sapixdb 0.1.0 → 0.2.0

package/dist/admin.d.ts

@@ -0,0 +1,78 @@
+import type { ApiKeyPatch, ApiKeyUsage, ApiKeyView, CreateApiKeyRequest, CreateApiKeyResponse, ListApiKeysResponse } from "./types.js";
+type Requester = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+/**
+ * Programmatic API key management.
+ * Requires a root key or a key with ``admin:api-keys`` scope.
+ *
+ * Obtain via ``SapixClient.admin``.
+ *
+ * @example
+ * const db = new SapixClient({ baseUrl: "http://localhost:7475",
+ *                               apiKey: process.env.SAPIX_ROOT_KEY });
+ *
+ * // Create a scoped key for an orders service
+ * const result = await db.admin.createKey({
+ *   label: "orders-service-prod",
+ *   scopes: ["write:agents/orders/records", "read:agents/orders/query"],
+ *   rate_limit_rps: 500,
+ * });
+ * console.log(result.key);   // save immediately — shown once
+ *
+ * // List all keys
+ * const { keys } = await db.admin.listKeys();
+ *
+ * // Update expiry
+ * await db.admin.updateKey(result.key_id, { expires_at_ms: Date.now() + 90 * 86_400_000 });
+ *
+ * // Remove rate limit
+ * await db.admin.updateKey(result.key_id, { rate_limit_rps: null });
+ *
+ * // Check usage
+ * const usage = await db.admin.keyUsage(result.key_id);
+ * console.log(usage.request_count_since_restart);
+ *
+ * // Revoke
+ * await db.admin.revokeKey(result.key_id);
+ */
+export declare class AdminClient {
+    private readonly req;
+    constructor(req: Requester);
+    /** Return all API keys. Secrets are never included. */
+    listKeys(): Promise<ListApiKeysResponse>;
+    /**
+     * Create a new scoped API key.
+     *
+     * ``result.key`` contains the full secret and is returned **exactly once**.
+     *
+     * **Scope examples**
+     * ```
+     * ["admin:*"]                                      // full operator access
+     * ["admin:api-keys"]                               // can manage keys only
+     * ["write:agents/orders/records",
+     *  "read:agents/orders/query"]                     // scoped to one agent
+     * ["write:*", "read:*"]                            // all reads + writes
+     * ```
+     */
+    createKey(req: CreateApiKeyRequest): Promise<CreateApiKeyResponse>;
+    /** Fetch a single key by ID. Throws ``SapixError`` with status 404 if missing. */
+    getKey(keyId: string): Promise<ApiKeyView>;
+    /**
+     * Partially update a key. Only provided fields are changed.
+     *
+     * Set a nullable field to ``null`` to remove it:
+     * ```ts
+     * // Make key permanent (remove expiry)
+     * await db.admin.updateKey(id, { expires_at_ms: null });
+     *
+     * // Remove rate limit
+     * await db.admin.updateKey(id, { rate_limit_rps: null });
+     * ```
+     */
+    updateKey(keyId: string, patch: ApiKeyPatch): Promise<ApiKeyView>;
+    /** Revoke a key permanently. Immediately blocks all requests from it. */
+    revokeKey(keyId: string): Promise<void>;
+    /** Request count and last-used timestamp since the last agent restart. */
+    keyUsage(keyId: string): Promise<ApiKeyUsage>;
+}
+export {};
+//# sourceMappingURL=admin.d.ts.map

package/dist/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,KAAK,SAAS,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,GAAG;gBAAH,GAAG,EAAE,SAAS;IAE3C,uDAAuD;IACvD,QAAQ,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAIxC;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAIlE,kFAAkF;IAClF,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI1C;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAIjE,yEAAyE;IACzE,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvC,0EAA0E;IAC1E,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;CAG9C"}

package/dist/admin.js

@@ -0,0 +1,89 @@
+/**
+ * Programmatic API key management.
+ * Requires a root key or a key with ``admin:api-keys`` scope.
+ *
+ * Obtain via ``SapixClient.admin``.
+ *
+ * @example
+ * const db = new SapixClient({ baseUrl: "http://localhost:7475",
+ *                               apiKey: process.env.SAPIX_ROOT_KEY });
+ *
+ * // Create a scoped key for an orders service
+ * const result = await db.admin.createKey({
+ *   label: "orders-service-prod",
+ *   scopes: ["write:agents/orders/records", "read:agents/orders/query"],
+ *   rate_limit_rps: 500,
+ * });
+ * console.log(result.key);   // save immediately — shown once
+ *
+ * // List all keys
+ * const { keys } = await db.admin.listKeys();
+ *
+ * // Update expiry
+ * await db.admin.updateKey(result.key_id, { expires_at_ms: Date.now() + 90 * 86_400_000 });
+ *
+ * // Remove rate limit
+ * await db.admin.updateKey(result.key_id, { rate_limit_rps: null });
+ *
+ * // Check usage
+ * const usage = await db.admin.keyUsage(result.key_id);
+ * console.log(usage.request_count_since_restart);
+ *
+ * // Revoke
+ * await db.admin.revokeKey(result.key_id);
+ */
+export class AdminClient {
+    req;
+    constructor(req) {
+        this.req = req;
+    }
+    /** Return all API keys. Secrets are never included. */
+    listKeys() {
+        return this.req("GET", "/v1/admin/api-keys");
+    }
+    /**
+     * Create a new scoped API key.
+     *
+     * ``result.key`` contains the full secret and is returned **exactly once**.
+     *
+     * **Scope examples**
+     * ```
+     * ["admin:*"]                                      // full operator access
+     * ["admin:api-keys"]                               // can manage keys only
+     * ["write:agents/orders/records",
+     *  "read:agents/orders/query"]                     // scoped to one agent
+     * ["write:*", "read:*"]                            // all reads + writes
+     * ```
+     */
+    createKey(req) {
+        return this.req("POST", "/v1/admin/api-keys", req);
+    }
+    /** Fetch a single key by ID. Throws ``SapixError`` with status 404 if missing. */
+    getKey(keyId) {
+        return this.req("GET", `/v1/admin/api-keys/${keyId}`);
+    }
+    /**
+     * Partially update a key. Only provided fields are changed.
+     *
+     * Set a nullable field to ``null`` to remove it:
+     * ```ts
+     * // Make key permanent (remove expiry)
+     * await db.admin.updateKey(id, { expires_at_ms: null });
+     *
+     * // Remove rate limit
+     * await db.admin.updateKey(id, { rate_limit_rps: null });
+     * ```
+     */
+    updateKey(keyId, patch) {
+        return this.req("PATCH", `/v1/admin/api-keys/${keyId}`, patch);
+    }
+    /** Revoke a key permanently. Immediately blocks all requests from it. */
+    revokeKey(keyId) {
+        return this.req("DELETE", `/v1/admin/api-keys/${keyId}`);
+    }
+    /** Request count and last-used timestamp since the last agent restart. */
+    keyUsage(keyId) {
+        return this.req("GET", `/v1/admin/api-keys/${keyId}/usage`);
+    }
+}
+//# sourceMappingURL=admin.js.map

package/dist/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../src/admin.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,GAAc;QAAd,QAAG,GAAH,GAAG,CAAW;IAAG,CAAC;IAE/C,uDAAuD;IACvD,QAAQ;QACN,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,GAAwB;QAChC,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED,kFAAkF;IAClF,MAAM,CAAC,KAAa;QAClB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,sBAAsB,KAAK,EAAE,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,KAAa,EAAE,KAAkB;QACzC,OAAO,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,sBAAsB,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;IACjE,CAAC;IAED,yEAAyE;IACzE,SAAS,CAAC,KAAa;QACrB,OAAO,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,sBAAsB,KAAK,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,0EAA0E;IAC1E,QAAQ,CAAC,KAAa;QACpB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,sBAAsB,KAAK,QAAQ,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/dist/client.d.ts

@@ -1,43 +1,99 @@
+import { AdminClient } from "./admin.js";
 import { CollectionClient } from "./collection.js";
-import { GraphClient } from "./graph.js";
-import type { SapixClientConfig, HealthResponse, WriteResult } from "./types.js";
+import type { StreamEvent, SubscribeOptions } from "./stream.js";
+import type { AddEdgeRequest, AddRecordRefRequest, ChainHeadResponse, EdgeView, GenesisRequest, GenesisResponse, HealthResponse, QueryResult, RecordRefView, RecordView, SapixClientOptions, SaqlQuery, WriteResponse } from "./types.js";
 export declare class SapixClient {
-    private readonly config;
-    /** Graph traversal and edge management. */
-    readonly graph: GraphClient;
-    constructor(config: SapixClientConfig);
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly _fetch;
+    private readonly authHeaders;
+    constructor(options: SapixClientOptions);
+    private request;
+    private toB64;
+    fromB64(b64: string): Uint8Array;
     /**
-     * Access a collection. All reads and writes go through this.
+     * API key management — create, list, update, revoke, and inspect usage.
+     * Requires a root key or a key with ``admin:api-keys`` scope.
      *
      * @example
-     * const products = db.collection("products");
-     * await products.write({ name: "T-Shirt", price: 29.99 });
-     * const all = await products.latest();
+     * const result = await db.admin.createKey({
+     *   label: "orders-service-prod",
+     *   scopes: ["write:agents/orders/records", "read:agents/orders/query"],
+     *   rate_limit_rps: 500,
+     * });
+     * console.log(result.key);  // save immediately — shown once
+     */
+    get admin(): AdminClient;
+    /**
+     * Return a `CollectionClient` for a named SapixDB agent.
+     *
+     * Every named agent is an independent strand — a logical "table" scoped to
+     * its own keypair and access policy. Operations route to `/v1/agents/{name}/...`.
      *
-     * // With TypeScript generics for full type safety:
-     * const products = db.collection<Product>("products");
+     * @example
+     * const orders = db.collection("orders");
+     * const record = await orders.write({ total: 99.99 });
+     * const latest = await orders.latest({ limit: 20 });
+     * const one    = await orders.findOne({ status: "pending" });
+     * const byHash = await orders.get(record.content_hash);
+     * const hist   = await orders.history({ limit: 100 });
+     * const snap   = await orders.asOf(record.timestamp_hlc).latest();
+     */
+    collection(name: string): CollectionClient;
+    /**
+     * Alias for `collection(name)` — preferred when thinking in SapixDB terms
+     * where each "table" is an agent.
      */
-    collection<T = Record<string, unknown>>(name: string): CollectionClient<T>;
+    agent(name: string): CollectionClient;
+    health(): Promise<HealthResponse>;
+    genesis(req?: GenesisRequest): Promise<GenesisResponse>;
     /**
-     * Ingest a record via the agent ingest endpoint.
-     * Designed for AI agents, webhooks, and automated pipelines.
-     * Supports optional dual-write to Supabase if configured on the server.
+     * Append a raw byte payload to the agent's strand.
+     * Encode your domain object before calling (e.g. with msgpackr or JSON.stringify).
+     */
+    write(payload: Uint8Array | string, flags?: number): Promise<WriteResponse>;
+    /**
+     * Convenience: JSON-encode `obj` and write it.
+     * Use `client.fromB64(record.payload_b64)` → `JSON.parse(...)` to decode on read.
+     */
+    writeJson(obj: unknown, flags?: number): Promise<WriteResponse>;
+    readByHash(contentHash: string): Promise<RecordView>;
+    chainHead(): Promise<ChainHeadResponse>;
+    query(q: SaqlQuery): Promise<QueryResult>;
+    queryLatest(limit?: number): Promise<QueryResult>;
+    queryTimeRange(fromTs: number, toTs: number): Promise<QueryResult>;
+    queryByHash(contentHash: string): Promise<QueryResult>;
+    queryChainHead(): Promise<QueryResult>;
+    addEdge(req: AddEdgeRequest): Promise<void>;
+    getEdges(agentId: string, opts?: {
+        direction?: "in" | "out";
+        edge_type?: string;
+    }): Promise<EdgeView[]>;
+    deleteEdge(src: string, edgeType: string, dst: string): Promise<void>;
+    addRecordRef(req: AddRecordRefRequest): Promise<void>;
+    getRecordRefs(agentId: string, contentHash: string): Promise<RecordRefView[]>;
+    /**
+     * Subscribe to realtime writes on a named agent via SSE.
+     * Returns an `EventSource` — call `.close()` to unsubscribe.
      *
      * @example
-     * await db.ingest("ai_decisions", {
-     *   model: "gpt-4o",
-     *   action: "approve_loan",
-     *   confidence: 0.94,
-     *   reasoning: "Credit score 780, DTI 28%",
+     * const es = client.subscribeAgent("orders", (ev) => {
+     *   console.log(ev.record_id, ev.payload);
      * });
+     * es.close();
      */
-    ingest(collection: string, data: Record<string, unknown>): Promise<WriteResult>;
-    /** Check that the SapixDB agent is reachable and running. */
-    health(): Promise<HealthResponse>;
+    subscribeAgent(agentId: string, onEvent: (event: StreamEvent) => void, opts?: SubscribeOptions): EventSource;
     /**
-     * Ping the agent. Returns true if healthy, false if unreachable.
-     * Does not throw.
+     * Subscribe to realtime writes on all agents via SSE.
+     * Returns an `EventSource` — call `.close()` to unsubscribe.
+     *
+     * @example
+     * const es = client.subscribeGlobal((ev) => {
+     *   console.log(ev.agent_id, ev.record_id);
+     * }, { agents: ["orders", "payments"] });
      */
-    ping(): Promise<boolean>;
+    subscribeGlobal(onEvent: (event: StreamEvent) => void, opts?: SubscribeOptions & {
+        agents?: string[];
+    }): EventSource;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAE3C,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;gBAEhB,MAAM,EAAE,iBAAiB;IASrC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAI1E;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IASrF,6DAA6D;IACvD,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAIvC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;CAQ/B"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/client.js

@@ -1,61 +1,210 @@
-import { request } from "./http.js";
+import { SapixError } from "./errors.js";
+import { AdminClient } from "./admin.js";
 import { CollectionClient } from "./collection.js";
-import { GraphClient } from "./graph.js";
+import { openAgentStream, openGlobalStream } from "./stream.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
 export class SapixClient {
-    constructor(config) {
-        this.config = {
-            timeout: 10000,
-            ...config,
-            url: config.url.replace(/\/$/, ""),
-        };
-        this.graph = new GraphClient(this.config);
+    baseUrl;
+    timeoutMs;
+    _fetch;
+    authHeaders;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this._fetch = options.fetch ?? globalThis.fetch.bind(globalThis);
+        this.authHeaders = {};
+        if (options.apiKey) {
+            this.authHeaders["Authorization"] = `Bearer ${options.apiKey}`;
+        }
+        if (options.callerId) {
+            this.authHeaders["X-Sapix-Caller"] = options.callerId;
+        }
+    }
+    // ── Internal helpers ──────────────────────────────────────────────────────
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let resp;
+        try {
+            const baseHeaders = { ...this.authHeaders };
+            if (body !== undefined)
+                baseHeaders["content-type"] = "application/json";
+            const init = {
+                method,
+                headers: baseHeaders,
+                signal: controller.signal,
+            };
+            if (body !== undefined)
+                init.body = JSON.stringify(body);
+            resp = await this._fetch(`${this.baseUrl}${path}`, init);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!resp.ok) {
+            throw await SapixError.fromResponse(resp);
+        }
+        if (resp.status === 204 || resp.headers.get("content-length") === "0") {
+            return undefined;
+        }
+        return resp.json();
+    }
+    toB64(payload) {
+        if (typeof payload === "string") {
+            return btoa(payload);
+        }
+        let binary = "";
+        for (let i = 0; i < payload.length; i++) {
+            binary += String.fromCharCode(payload[i]);
+        }
+        return btoa(binary);
+    }
+    fromB64(b64) {
+        const binary = atob(b64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return bytes;
     }
+    // ── Admin ─────────────────────────────────────────────────────────────────
     /**
-     * Access a collection. All reads and writes go through this.
+     * API key management — create, list, update, revoke, and inspect usage.
+     * Requires a root key or a key with ``admin:api-keys`` scope.
      *
      * @example
-     * const products = db.collection("products");
-     * await products.write({ name: "T-Shirt", price: 29.99 });
-     * const all = await products.latest();
+     * const result = await db.admin.createKey({
+     *   label: "orders-service-prod",
+     *   scopes: ["write:agents/orders/records", "read:agents/orders/query"],
+     *   rate_limit_rps: 500,
+     * });
+     * console.log(result.key);  // save immediately — shown once
+     */
+    get admin() {
+        return new AdminClient(this.request.bind(this));
+    }
+    // ── Named agents (collections) ────────────────────────────────────────────
+    /**
+     * Return a `CollectionClient` for a named SapixDB agent.
+     *
+     * Every named agent is an independent strand — a logical "table" scoped to
+     * its own keypair and access policy. Operations route to `/v1/agents/{name}/...`.
      *
-     * // With TypeScript generics for full type safety:
-     * const products = db.collection<Product>("products");
+     * @example
+     * const orders = db.collection("orders");
+     * const record = await orders.write({ total: 99.99 });
+     * const latest = await orders.latest({ limit: 20 });
+     * const one    = await orders.findOne({ status: "pending" });
+     * const byHash = await orders.get(record.content_hash);
+     * const hist   = await orders.history({ limit: 100 });
+     * const snap   = await orders.asOf(record.timestamp_hlc).latest();
      */
     collection(name) {
-        return new CollectionClient(this.config, name);
+        return new CollectionClient(name, this.request.bind(this));
+    }
+    /**
+     * Alias for `collection(name)` — preferred when thinking in SapixDB terms
+     * where each "table" is an agent.
+     */
+    agent(name) {
+        return this.collection(name);
+    }
+    // ── Health ────────────────────────────────────────────────────────────────
+    health() {
+        return this.request("GET", "/v1/health");
+    }
+    // ── Genesis ───────────────────────────────────────────────────────────────
+    genesis(req = {}) {
+        return this.request("POST", "/v1/genesis", { zone: req.zone ?? "governed" });
     }
+    // ── Records ───────────────────────────────────────────────────────────────
     /**
-     * Ingest a record via the agent ingest endpoint.
-     * Designed for AI agents, webhooks, and automated pipelines.
-     * Supports optional dual-write to Supabase if configured on the server.
+     * Append a raw byte payload to the agent's strand.
+     * Encode your domain object before calling (e.g. with msgpackr or JSON.stringify).
+     */
+    write(payload, flags = 0) {
+        return this.request("POST", "/v1/records", {
+            payload_b64: this.toB64(payload),
+            flags,
+        });
+    }
+    /**
+     * Convenience: JSON-encode `obj` and write it.
+     * Use `client.fromB64(record.payload_b64)` → `JSON.parse(...)` to decode on read.
+     */
+    writeJson(obj, flags = 0) {
+        return this.write(new TextEncoder().encode(JSON.stringify(obj)), flags);
+    }
+    readByHash(contentHash) {
+        return this.request("GET", `/v1/records/${contentHash}`);
+    }
+    chainHead() {
+        return this.request("GET", "/v1/strand/head");
+    }
+    // ── SaQL ─────────────────────────────────────────────────────────────────
+    query(q) {
+        return this.request("POST", "/v1/query", q);
+    }
+    queryLatest(limit = 10) {
+        return this.query({ type: "latest", limit });
+    }
+    queryTimeRange(fromTs, toTs) {
+        return this.query({ type: "time_range", from_ts: fromTs, to_ts: toTs });
+    }
+    queryByHash(contentHash) {
+        return this.query({ type: "hash", content_hash: contentHash });
+    }
+    queryChainHead() {
+        return this.query({ type: "chain_head" });
+    }
+    // ── Graph — edges ─────────────────────────────────────────────────────────
+    addEdge(req) {
+        return this.request("POST", "/v1/graph/edges", req);
+    }
+    getEdges(agentId, opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.direction)
+            params.set("direction", opts.direction);
+        if (opts.edge_type)
+            params.set("edge_type", opts.edge_type);
+        const qs = params.size > 0 ? `?${params}` : "";
+        return this.request("GET", `/v1/graph/edges/${agentId}${qs}`);
+    }
+    deleteEdge(src, edgeType, dst) {
+        return this.request("DELETE", `/v1/graph/edges/${src}/${edgeType}/${dst}`);
+    }
+    // ── Graph — record refs ───────────────────────────────────────────────────
+    addRecordRef(req) {
+        return this.request("POST", "/v1/graph/refs", req);
+    }
+    getRecordRefs(agentId, contentHash) {
+        return this.request("GET", `/v1/graph/refs/${agentId}/${contentHash}`);
+    }
+    // ── Realtime SSE ──────────────────────────────────────────────────────────
+    /**
+     * Subscribe to realtime writes on a named agent via SSE.
+     * Returns an `EventSource` — call `.close()` to unsubscribe.
      *
      * @example
-     * await db.ingest("ai_decisions", {
-     *   model: "gpt-4o",
-     *   action: "approve_loan",
-     *   confidence: 0.94,
-     *   reasoning: "Credit score 780, DTI 28%",
+     * const es = client.subscribeAgent("orders", (ev) => {
+     *   console.log(ev.record_id, ev.payload);
      * });
+     * es.close();
      */
-    async ingest(collection, data) {
-        return request(this.config, "POST", `/v1/${this.config.agent}/ingest`, { collection, data });
-    }
-    /** Check that the SapixDB agent is reachable and running. */
-    async health() {
-        return request(this.config, "GET", "/v1/health");
+    subscribeAgent(agentId, onEvent, opts) {
+        return openAgentStream(this.baseUrl, agentId, onEvent, opts);
     }
     /**
-     * Ping the agent. Returns true if healthy, false if unreachable.
-     * Does not throw.
+     * Subscribe to realtime writes on all agents via SSE.
+     * Returns an `EventSource` — call `.close()` to unsubscribe.
+     *
+     * @example
+     * const es = client.subscribeGlobal((ev) => {
+     *   console.log(ev.agent_id, ev.record_id);
+     * }, { agents: ["orders", "payments"] });
      */
-    async ping() {
-        try {
-            const res = await this.health();
-            return res.status === "ok";
-        }
-        catch {
-            return false;
-        }
+    subscribeGlobal(onEvent, opts) {
+        return openGlobalStream(this.baseUrl, onEvent, opts);
     }
 }
 //# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAOzC,MAAM,OAAO,WAAW;IAMtB,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG;YACZ,OAAO,EAAE,KAAM;YACf,GAAG,MAAM;YACT,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;SACnC,CAAC;QACF,IAAI,CAAC,KAAK,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CAA8B,IAAY;QAClD,OAAO,IAAI,gBAAgB,CAAI,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACpD,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,MAAM,CAAC,UAAkB,EAAE,IAA6B;QAC5D,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,MAAM,EACN,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,SAAS,EACjC,EAAE,UAAU,EAAE,IAAI,EAAE,CACrB,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,KAAK,CAAC,MAAM;QACV,OAAO,OAAO,CAAiB,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC;IACnE,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI;QACR,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,OAAO,GAAG,CAAC,MAAM,KAAK,IAAI,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAkBhE,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAElC,MAAM,OAAO,WAAW;IACL,OAAO,CAAS;IAChB,SAAS,CAAS;IAClB,MAAM,CAA0B;IAChC,WAAW,CAAyB;IAErD,YAAY,OAA2B;QACrC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC;QACzD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QACjE,IAAI,CAAC,WAAW,GAAG,EAAE,CAAC;QACtB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,IAAI,CAAC,WAAW,CAAC,eAAe,CAAC,GAAG,UAAU,OAAO,CAAC,MAAM,EAAE,CAAC;QACjE,CAAC;QACD,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YACrB,IAAI,CAAC,WAAW,CAAC,gBAAgB,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC;QACxD,CAAC;IACH,CAAC;IAED,6EAA6E;IAErE,KAAK,CAAC,OAAO,CACnB,MAAc,EACd,IAAY,EACZ,IAAc;QAEd,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAEnE,IAAI,IAAc,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,WAAW,GAA2B,EAAE,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;YACpE,IAAI,IAAI,KAAK,SAAS;gBAAE,WAAW,CAAC,cAAc,CAAC,GAAG,kBAAkB,CAAC;YACzE,MAAM,IAAI,GAAgB;gBACxB,MAAM;gBACN,OAAO,EAAE,WAAW;gBACpB,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC;YACF,IAAI,IAAI,KAAK,SAAS;gBAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YACzD,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;QAC3D,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACb,MAAM,MAAM,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;QAC5C,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,GAAG,EAAE,CAAC;YACtE,OAAO,SAAc,CAAC;QACxB,CAAC;QAED,OAAO,IAAI,CAAC,IAAI,EAAgB,CAAC;IACnC,CAAC;IAEO,KAAK,CAAC,OAA4B;QACxC,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;YAChC,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,CAAE,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;IACtB,CAAC;IAED,OAAO,CAAC,GAAW;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC;QACzB,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;QAClC,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6EAA6E;IAE7E;;;;;;;;;;;OAWG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,6EAA6E;IAE7E;;;;;;;;;;;;;;OAcG;IACH,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAY;QAChB,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAED,6EAA6E;IAE7E,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IAC3C,CAAC;IAED,6EAA6E;IAE7E,OAAO,CAAC,MAAsB,EAAE;QAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,UAAU,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,6EAA6E;IAE7E;;;OAGG;IACH,KAAK,CAAC,OAA4B,EAAE,KAAK,GAAG,CAAC;QAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE;YACzC,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YAChC,KAAK;SACN,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,SAAS,CAAC,GAAY,EAAE,KAAK,GAAG,CAAC;QAC/B,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC1E,CAAC;IAED,UAAU,CAAC,WAAmB;QAC5B,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,eAAe,WAAW,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,iBAAiB,CAAC,CAAC;IAChD,CAAC;IAED,4EAA4E;IAE5E,KAAK,CAAC,CAAY;QAChB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAC9C,CAAC;IAED,WAAW,CAAC,KAAK,GAAG,EAAE;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,cAAc,CAAC,MAAc,EAAE,IAAY;QACzC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,WAAW,CAAC,WAAmB;QAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,cAAc;QACZ,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,6EAA6E;IAE7E,OAAO,CAAC,GAAmB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAAC;IACtD,CAAC;IAED,QAAQ,CACN,OAAe,EACf,OAAyD,EAAE;QAE3D,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5D,IAAI,IAAI,CAAC,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5D,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,mBAAmB,OAAO,GAAG,EAAE,EAAE,CAAC,CAAC;IAChE,CAAC;IAED,UAAU,CAAC,GAAW,EAAE,QAAgB,EAAE,GAAW;QACnD,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,QAAQ,IAAI,GAAG,EAAE,CAAC,CAAC;IAC7E,CAAC;IAED,6EAA6E;IAE7E,YAAY,CAAC,GAAwB;QACnC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED,aAAa,CAAC,OAAe,EAAE,WAAmB;QAChD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,kBAAkB,OAAO,IAAI,WAAW,EAAE,CAAC,CAAC;IACzE,CAAC;IAED,6EAA6E;IAE7E;;;;;;;;;OASG;IACH,cAAc,CACZ,OAAe,EACf,OAAqC,EACrC,IAAuB;QAEvB,OAAO,eAAe,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IAC/D,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CACb,OAAqC,EACrC,IAA+C;QAE/C,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACvD,CAAC;CACF"}