@antonlytics/sdk

Installation

npm install @antonlytics/sdk
# or
yarn add @antonlytics/sdk
# or
pnpm add @antonlytics/sdk

Quick Start

import { Antonlytics, Triplet, EntityRef } from "@antonlytics/sdk";

const anto = new Antonlytics({
  apiKey: process.env.ANTONLYTICS_API_KEY!, // anto_live_...
});

// Ingest a relationship
await anto.ingest.track({
  projectId: "proj_abc",
  triplets: new Triplet(
    new EntityRef("Customer", "cust_1", { name: "Alice", country: "USA" }),
    "PURCHASED",
    new EntityRef("Product", "prod_5", { title: "Laptop Pro", price: 999 }),
    { quantity: 2 }
  ),
});

// Query the graph
const { rows } = await anto.query
  .build("proj_abc")
  .select("Customer", "c1")
    .properties("name", "email", "country")
    .eq("country", "USA")
    .gte("age", 18)
  .done()
  .orderBy("age", "desc")
  .limit(50)
  .run();

Configuration

const anto = new Antonlytics({
  apiKey:    "anto_live_...",     // required
  baseUrl:   "https://api.antonlytics.com", // optional
  timeout:   30_000,             // ms, default 30s
  retries:   2,                  // auto-retry on 5xx/network
  debug:     false,              // log requests to console
  fetch:     customFetch,        // custom fetch (Node 16, Deno, test mocks)
  rateLimit: { maxRequests: 100, windowMs: 60_000 }, // client-side throttle
});

API keys must start with anto_live_. The constructor validates this immediately and throws INVALID_API_KEY on startup rather than failing mid-request.

Ingestion

All data enters as subject–predicate–object triplets. Batches ≤100 process synchronously; batches >100 queue asynchronously.

track() — recommended

const result = await anto.ingest.track(
  {
    projectId: "proj_abc",
    triplets: [
      new Triplet(
        new EntityRef("Customer", "c1", { name: "Alice" }),
        "PURCHASED",
        new EntityRef("Product", "p1", { title: "Laptop", price: 999 }),
        { quantity: 1, date: "2026-04-15" }
      ),
    ],
  },
  { interval: 1000, timeout: 60000, onStatus: e => console.log(e.status) }
);

batch() — large datasets

await anto.ingest.batch({
  projectId: "proj_abc",
  triplets: thousandsOfTriplets,
  chunkSize: 200,
  onChunk: (i, total) => console.log(`Chunk ${i}/${total}`),
});

Query Builder

const result = await anto.query
  .build("proj_abc")
  .select("Customer", "c1")          // alias, entity type
    .properties("name", "email", "country")
    .eq("country", "USA")            // filter: country == USA
    .gte("age", 21)                  // filter: age >= 21
    .relatesTo("PURCHASED", "p1")    // join via relationship
  .done()
  .select("Product", "p1")
    .properties("title", "price")
    .lte("price", 500)
  .done()
  .orderBy("age", "desc")
  .limit(100)
  .name("US adults buying affordable products")
  .run();

// result.rows     → array of matched rows
// result.total    → total count
// result.execution_ms → query time

Filter operators

Error Handling

import { isAntoError, AntoError } from "@antonlytics/sdk";

try {
  await anto.ingest.track({ ... });
} catch (err) {
  if (isAntoError(err)) {
    console.log(err.code);    // "PLAN_LIMIT_REACHED", "UNAUTHORIZED", ...
    console.log(err.status);  // 402, 401, 0 (network), ...
    console.log(err.message); // human-readable

    if (err.code === "PLAN_LIMIT_REACHED") {
      // redirect to /billing
    }
  }
}

CLI Reference

# Set your API key
export ANTO_API_KEY=anto_live_xxx

anto projects                         # List all projects
anto stats      <project-id>          # Graph statistics
anto ontology   <project-id>          # Print schema
anto ingest     <project-id> file.json # Ingest triplets
anto query      <project-id> file.json # Execute query
anto dashboard  <project-id>          # Dashboard summary
anto poll       <event-id>            # Poll async event

# Options
ANTO_BASE_URL=http://localhost:8000   # Self-hosted backend
ANTO_DEBUG=1                          # Log HTTP calls