sapixdb-js 0.3.0

package/README.md

@@ -0,0 +1,295 @@
+# SapixDB JavaScript / TypeScript SDK
+
+Official SDK for [SapixDB](https://sapixdb.com) — the agent-native living database.
+
+Zero dependencies. Works in Node.js 18+, Bun, Deno, and modern browsers.
+
+## Installation
+
+```bash
+npm install sapixdb
+# or
+bun add sapixdb
+```
+
+## Quick Start
+
+```typescript
+import { SapixClient } from "sapixdb";
+
+const db = new SapixClient({
+  url: "http://localhost:7475",
+  agent: "my-app",
+});
+
+// Write a record
+const record = await db.collection("products").write({
+  name: "T-Shirt",
+  price: 29.99,
+  stock: 100,
+});
+console.log(record.id);   // "nuc_abc123"
+console.log(record.hash); // "sha3:e7f2a1..."
+
+// Read latest records
+const products = await db.collection("products").latest();
+
+// Filter
+const shirts = await db.collection("products").find({ category: "apparel" });
+
+// Time travel — what did the DB look like yesterday?
+const yesterday = await db
+  .collection("orders")
+  .asOf("2026-05-11T00:00:00Z")
+  .latest();
+```
+
+## API Reference
+
+### `new SapixClient(config)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | — | SapixDB agent URL |
+| `agent` | `string` | — | Agent ID (matches `SAPIX_AGENT_ID`) |
+| `headers` | `Record<string,string>` | `{}` | Extra HTTP headers |
+| `timeout` | `number` | `10000` | Request timeout (ms) |
+
+---
+
+### `db.collection(name)`
+
+Returns a `CollectionClient` for the given collection name.
+
+#### `.write(data)` → `WriteResult`
+
+Append a new record. Nothing is ever overwritten.
+
+```typescript
+const result = await db.collection("orders").write({
+  customer_id: "cust_001",
+  total: 149.99,
+  status: "placed",
+});
+// result.id       — nucleotide ID
+// result.hash     — cryptographic fingerprint
+// result.timestamp — ISO 8601 timestamp
+```
+
+#### `.writeBatch(records[])` → `WriteResult[]`
+
+Write multiple records in parallel.
+
+```typescript
+await db.collection("products").writeBatch([
+  { name: "T-Shirt",  price: 29.99 },
+  { name: "Sneakers", price: 89.99 },
+]);
+```
+
+#### `.get(id)` → `NucleotideRecord`
+
+Fetch a single record by its nucleotide ID.
+
+```typescript
+const record = await db.collection("orders").get("nuc_abc123");
+console.log(record.data.status); // "placed"
+```
+
+#### `.latest(options?)` → `NucleotideRecord[]`
+
+Fetch the latest version of every record in the collection.
+
+#### `.history(options?)` → `NucleotideRecord[]`
+
+Fetch ALL versions — the full append-only history.
+
+#### `.find(filter, options?)` → `NucleotideRecord[]`
+
+Find records matching a filter (latest version only).
+
+```typescript
+const pending = await db.collection("orders").find({ status: "pending" });
+```
+
+#### `.findOne(filter)` → `NucleotideRecord | null`
+
+Find the first matching record, or `null`.
+
+#### `.asOf(timestamp)` → `CollectionQuery`
+
+Scope all subsequent reads to a specific point in time.
+
+```typescript
+// What did Alice's record look like 2 hours ago?
+const snapshot = await db
+  .collection("users")
+  .asOf("2026-05-12T08:00:00Z")
+  .find({ name: "Alice" });
+```
+
+---
+
+### `db.graph`
+
+#### `.relate(src, dst, type, weight?)` → `void`
+
+Create a typed directed edge between two records.
+
+```typescript
+await db.graph.relate(orderId, customerId, "placed_by");
+await db.graph.relate(productId, categoryId, "belongs_to");
+await db.graph.relate(managerId, reportId, "manages", 1.0);
+```
+
+#### `.addEdge(edge)` → `void`
+
+Full edge creation with all options.
+
+```typescript
+await db.graph.addEdge({
+  src: "nuc_abc123",
+  dst: "nuc_def456",
+  edge_type: "manages",
+  weight: 1.0,
+});
+```
+
+#### `.traverse(fromId, options?)` → `TraverseResult`
+
+Walk the graph from a starting node.
+
+```typescript
+const { nodes, edges } = await db.graph.traverse("nuc_abc123", {
+  depth: 3,
+  direction: "outbound", // "outbound" | "inbound" | "both"
+});
+```
+
+#### `.neighbors(id, direction?)` → `NucleotideRecord[]`
+
+Get direct neighbours of a node.
+
+---
+
+### `db.ingest(collection, data)` → `WriteResult`
+
+Write via the ingest endpoint — designed for AI agents, webhooks, and automated pipelines.
+
+```typescript
+await db.ingest("ai_decisions", {
+  model: "gpt-4o",
+  action: "approve_loan",
+  confidence: 0.94,
+  reasoning: "Credit score 780, DTI 28%",
+});
+```
+
+---
+
+### `db.health()` / `db.ping()`
+
+```typescript
+const { status, agent } = await db.health(); // throws on failure
+const alive = await db.ping();               // returns true/false, never throws
+```
+
+---
+
+## TypeScript Generics
+
+Pass your type as a generic to get full autocomplete and type checking:
+
+```typescript
+interface Product {
+  name: string;
+  price: number;
+  stock: number;
+  category?: string;
+}
+
+const products = db.collection<Product>("products");
+
+const result = await products.write({ name: "T-Shirt", price: 29.99, stock: 100 });
+const items = await products.latest();
+// items[0].data.price is typed as number ✓
+```
+
+---
+
+## Error Handling
+
+```typescript
+import { SapixError, SapixNetworkError, SapixNotFoundError } from "sapixdb";
+
+try {
+  const record = await db.collection("orders").get("nuc_missing");
+} catch (err) {
+  if (err instanceof SapixNotFoundError) {
+    console.log("Record does not exist");
+  } else if (err instanceof SapixNetworkError) {
+    console.log("Cannot reach SapixDB — is it running?");
+  } else if (err instanceof SapixError) {
+    console.log(`SapixDB error ${err.status}: ${err.message}`);
+  }
+}
+```
+
+---
+
+## Full Example: Online Store
+
+```typescript
+import { SapixClient } from "sapixdb";
+
+const db = new SapixClient({ url: "http://localhost:7475", agent: "store" });
+
+// ── 1. Add products ───────────────────────────────────────────────
+const shirt = await db.collection("products").write({
+  sku: "SHIRT-001", name: "Classic T-Shirt", price: 29.99, stock: 200,
+});
+const shoes = await db.collection("products").write({
+  sku: "SHOE-042", name: "Running Sneakers", price: 89.99, stock: 50,
+});
+
+// ── 2. Register a customer ────────────────────────────────────────
+const customer = await db.collection("customers").write({
+  name: "Alice Johnson", email: "alice@example.com", tier: "standard",
+});
+
+// ── 3. Place an order ─────────────────────────────────────────────
+const order = await db.collection("orders").write({
+  customer_id: customer.id,
+  items: [
+    { product_id: shirt.id, qty: 2, unit_price: 29.99 },
+    { product_id: shoes.id, qty: 1, unit_price: 89.99 },
+  ],
+  total: 149.97,
+  status: "placed",
+});
+
+// Link order → customer in the graph
+await db.graph.relate(order.id, customer.id, "placed_by");
+
+// ── 4. Ship the order (append, never overwrite) ───────────────────
+await db.collection("orders").write({
+  ...order,          // same logical entity
+  status: "shipped",
+  tracking: "UPS-1Z999AA10123456784",
+  shipped_at: new Date().toISOString(),
+});
+
+// ── 5. Audit: what was the order status 10 minutes ago? ───────────
+const tenMinutesAgo = new Date(Date.now() - 10 * 60_000).toISOString();
+const snapshot = await db
+  .collection("orders")
+  .asOf(tenMinutesAgo)
+  .find({ customer_id: customer.id });
+// → returns the "placed" version, before it was shipped
+
+// ── 6. Graph: find everything this customer is connected to ───────
+const { nodes } = await db.graph.traverse(customer.id, {
+  depth: 2, direction: "inbound",
+});
+// → returns the order records linked to this customer
+```

package/dist/client.d.ts

@@ -0,0 +1,115 @@
+import { CollectionClient } from "./collection.js";
+import { GraphClient } from "./graph.js";
+import type { StreamEvent, SubscribeOptions } from "./stream.js";
+import type { SapixClientConfig, HealthResponse, WriteResponse, SaqlQueryResult, SemanticQueryResult, ChainHeadResponse, CreateAgentResponse, AgentListResponse, CheckpointResponse } from "./types.js";
+export declare class SapixClient {
+    private readonly config;
+    /** Graph traversal and edge management. */
+    readonly graph: GraphClient;
+    constructor(config: SapixClientConfig);
+    /**
+     * Access a named agent as a collection.
+     * In SapixDB, every collection IS an agent — the agent-as-table paradigm.
+     * The named agent must exist (create it with createAgent or SAPIX_AGENTS env var).
+     *
+     * @example
+     * const products = db.collection("products-agt");
+     * await products.write({ name: "T-Shirt", price: 29.99 });
+     * const { records } = await products.latest(10);
+     */
+    collection<T = Record<string, unknown>>(name: string): CollectionClient<T>;
+    /**
+     * Alias for collection() — prefer this to match SapixDB terminology.
+     */
+    agent<T = Record<string, unknown>>(id: string): CollectionClient<T>;
+    /**
+     * Write a JSON record to the primary agent's strand.
+     * Use collection() / agent() to write to a named agent.
+     */
+    write(data: Record<string, unknown>): Promise<WriteResponse>;
+    /**
+     * Execute a structured SaQL query against the primary agent (POST /v1/query).
+     *
+     * @example
+     * await db.query({ type: "latest", limit: 10 });
+     * await db.query({ type: "hash", content_hash: "e7f2a1b3..." });
+     * await db.query({ type: "time_range", from_ts: 0, to_ts: 18446744073709551615 });
+     */
+    query(body: Record<string, unknown>): Promise<SaqlQueryResult>;
+    /**
+     * Send a natural-language query to POST /v1/query/semantic.
+     */
+    querySemantic(nl: string): Promise<SemanticQueryResult>;
+    /** Get the primary agent's current chain head and record count. */
+    head(): Promise<ChainHeadResponse>;
+    /** Check that the SapixDB agent is reachable and running. */
+    health(): Promise<HealthResponse>;
+    /**
+     * Ping the agent. Returns true if healthy, false if unreachable.
+     * Does not throw.
+     */
+    ping(): Promise<boolean>;
+    /**
+     * Create a new named agent with a genesis block (POST /v1/agents).
+     * seedHex must be 64 hex characters (32 bytes). zone defaults to "governed".
+     *
+     * @example
+     * await db.createAgent("orders-agt", "abcd...64hexchars", "governed");
+     */
+    createAgent(agentId: string, seedHex: string, zone?: string): Promise<CreateAgentResponse>;
+    /**
+     * List all agents running on this node (GET /v1/agents).
+     */
+    listAgents(): Promise<AgentListResponse>;
+    /**
+     * Ingest a record into a named agent's strand.
+     * Designed for AI agents, webhooks, and automated pipelines.
+     * If agentId is omitted or empty, writes to the primary agent.
+     *
+     * @example
+     * await db.ingest("ai-decisions-agt", {
+     *   model: "claude-opus-4-7",
+     *   action: "approve_loan",
+     *   confidence: 0.94,
+     * });
+     */
+    ingest(agentId: string, data: Record<string, unknown>): Promise<WriteResponse>;
+    /**
+     * Subscribe to realtime writes on a named agent via SSE.
+     * Returns an EventSource — call `.close()` to unsubscribe.
+     *
+     * @example
+     * const es = db.subscribeAgent("orders", (event) => {
+     *   console.log("new record:", event.record_id, event.payload);
+     * });
+     * // Later:
+     * es.close();
+     *
+     * // With backfill from an HLC timestamp:
+     * const es = db.subscribeAgent("orders", handler, { since: lastSeenHlc });
+     */
+    subscribeAgent(agentId: string, onEvent: (event: StreamEvent) => void, opts?: SubscribeOptions): EventSource;
+    /**
+     * Subscribe to realtime writes on all agents via SSE.
+     * Returns an EventSource — call `.close()` to unsubscribe.
+     *
+     * @example
+     * const es = db.subscribeGlobal((event) => {
+     *   console.log(event.agent_id, event.record_id);
+     * }, { agents: ["orders", "payments"] });
+     */
+    subscribeGlobal(onEvent: (event: StreamEvent) => void, opts?: SubscribeOptions & {
+        agents?: string[];
+    }): EventSource;
+    /**
+     * Seal and delete all agent WAL files so no plaintext remains on disk.
+     * Requires root key or a key with `admin:*` scope.
+     * Returns the number of agents checkpointed.
+     *
+     * @example
+     * const result = await db.checkpoint();
+     * console.log(`Sealed ${result.agents_checkpointed} agents`);
+     */
+    checkpoint(): Promise<CheckpointResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +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;AAEzC,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EACnB,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;;;;;;;;;OASG;IACH,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAI1E;;OAEG;IACH,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC,CAAC;IAInE;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAI5D;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;IAI9D;;OAEG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAIvD,mEAAmE;IACnE,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIlC,6DAA6D;IAC7D,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAIjC;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC;IAS9B;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,SAAa,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAQ9F;;OAEG;IACH,UAAU,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIxC;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAK9E;;;;;;;;;;;;;OAaG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,EACrC,IAAI,CAAC,EAAE,gBAAgB,GACtB,WAAW;IAId;;;;;;;;OAQG;IACH,eAAe,CACb,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,EACrC,IAAI,CAAC,EAAE,gBAAgB,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC9C,WAAW;IAId;;;;;;;;OAQG;IACH,UAAU,IAAI,OAAO,CAAC,kBAAkB,CAAC;CAG1C"}

package/dist/client.js

@@ -0,0 +1,156 @@
+import { request } from "./http.js";
+import { CollectionClient } from "./collection.js";
+import { GraphClient } from "./graph.js";
+import { subscribeAgent, subscribeGlobal } from "./stream.js";
+export class SapixClient {
+    constructor(config) {
+        this.config = {
+            timeout: 10000,
+            ...config,
+            url: config.url.replace(/\/$/, ""),
+        };
+        this.graph = new GraphClient(this.config);
+    }
+    /**
+     * Access a named agent as a collection.
+     * In SapixDB, every collection IS an agent — the agent-as-table paradigm.
+     * The named agent must exist (create it with createAgent or SAPIX_AGENTS env var).
+     *
+     * @example
+     * const products = db.collection("products-agt");
+     * await products.write({ name: "T-Shirt", price: 29.99 });
+     * const { records } = await products.latest(10);
+     */
+    collection(name) {
+        return new CollectionClient(this.config, name);
+    }
+    /**
+     * Alias for collection() — prefer this to match SapixDB terminology.
+     */
+    agent(id) {
+        return new CollectionClient(this.config, id);
+    }
+    /**
+     * Write a JSON record to the primary agent's strand.
+     * Use collection() / agent() to write to a named agent.
+     */
+    write(data) {
+        return request(this.config, "POST", "/v1/records/json", { data });
+    }
+    /**
+     * Execute a structured SaQL query against the primary agent (POST /v1/query).
+     *
+     * @example
+     * await db.query({ type: "latest", limit: 10 });
+     * await db.query({ type: "hash", content_hash: "e7f2a1b3..." });
+     * await db.query({ type: "time_range", from_ts: 0, to_ts: 18446744073709551615 });
+     */
+    query(body) {
+        return request(this.config, "POST", "/v1/query", body);
+    }
+    /**
+     * Send a natural-language query to POST /v1/query/semantic.
+     */
+    querySemantic(nl) {
+        return request(this.config, "POST", "/v1/query/semantic", { query: nl });
+    }
+    /** Get the primary agent's current chain head and record count. */
+    head() {
+        return request(this.config, "GET", "/v1/strand/head");
+    }
+    /** Check that the SapixDB agent is reachable and running. */
+    health() {
+        return request(this.config, "GET", "/v1/health");
+    }
+    /**
+     * Ping the agent. Returns true if healthy, false if unreachable.
+     * Does not throw.
+     */
+    async ping() {
+        try {
+            const res = await this.health();
+            return res.status === "ok";
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Create a new named agent with a genesis block (POST /v1/agents).
+     * seedHex must be 64 hex characters (32 bytes). zone defaults to "governed".
+     *
+     * @example
+     * await db.createAgent("orders-agt", "abcd...64hexchars", "governed");
+     */
+    createAgent(agentId, seedHex, zone = "governed") {
+        return request(this.config, "POST", "/v1/agents", {
+            agent_id: agentId,
+            seed_hex: seedHex,
+            zone,
+        });
+    }
+    /**
+     * List all agents running on this node (GET /v1/agents).
+     */
+    listAgents() {
+        return request(this.config, "GET", "/v1/agents");
+    }
+    /**
+     * Ingest a record into a named agent's strand.
+     * Designed for AI agents, webhooks, and automated pipelines.
+     * If agentId is omitted or empty, writes to the primary agent.
+     *
+     * @example
+     * await db.ingest("ai-decisions-agt", {
+     *   model: "claude-opus-4-7",
+     *   action: "approve_loan",
+     *   confidence: 0.94,
+     * });
+     */
+    ingest(agentId, data) {
+        const path = agentId ? `/v1/agents/${agentId}/records/json` : "/v1/records/json";
+        return request(this.config, "POST", path, { data });
+    }
+    /**
+     * Subscribe to realtime writes on a named agent via SSE.
+     * Returns an EventSource — call `.close()` to unsubscribe.
+     *
+     * @example
+     * const es = db.subscribeAgent("orders", (event) => {
+     *   console.log("new record:", event.record_id, event.payload);
+     * });
+     * // Later:
+     * es.close();
+     *
+     * // With backfill from an HLC timestamp:
+     * const es = db.subscribeAgent("orders", handler, { since: lastSeenHlc });
+     */
+    subscribeAgent(agentId, onEvent, opts) {
+        return subscribeAgent(this.config, agentId, onEvent, opts);
+    }
+    /**
+     * Subscribe to realtime writes on all agents via SSE.
+     * Returns an EventSource — call `.close()` to unsubscribe.
+     *
+     * @example
+     * const es = db.subscribeGlobal((event) => {
+     *   console.log(event.agent_id, event.record_id);
+     * }, { agents: ["orders", "payments"] });
+     */
+    subscribeGlobal(onEvent, opts) {
+        return subscribeGlobal(this.config, onEvent, opts);
+    }
+    /**
+     * Seal and delete all agent WAL files so no plaintext remains on disk.
+     * Requires root key or a key with `admin:*` scope.
+     * Returns the number of agents checkpointed.
+     *
+     * @example
+     * const result = await db.checkpoint();
+     * console.log(`Sealed ${result.agents_checkpointed} agents`);
+     */
+    checkpoint() {
+        return request(this.config, "POST", "/v1/control/checkpoint");
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/collection.d.ts

@@ -0,0 +1,59 @@
+import type { SapixClientConfig, WriteResponse, RecordView, SaqlQueryResult, ChainHeadResponse, AgentStatusResponse } from "./types.js";
+export interface DeletedRecord {
+    record_id: string;
+    content_hash: string;
+    deleted_at_ms: number;
+}
+export declare class CollectionClient<T = Record<string, unknown>> {
+    private readonly config;
+    private readonly name;
+    constructor(config: SapixClientConfig, name: string);
+    /**
+     * Append a JSON record to the agent's strand. Nothing is ever overwritten.
+     *
+     * @example
+     * const result = await products.write({ name: "T-Shirt", price: 29.99 });
+     * console.log(result.record_id, result.content_hash);
+     */
+    write(data: Partial<T> & Record<string, unknown>): Promise<WriteResponse>;
+    /**
+     * Append multiple records sequentially.
+     */
+    writeBatch(records: Array<Partial<T> & Record<string, unknown>>): Promise<WriteResponse[]>;
+    /**
+     * Fetch a record by content hash.
+     */
+    get(contentHash: string): Promise<RecordView>;
+    /**
+     * Return the most recent N records from the agent.
+     *
+     * @example
+     * const result = await products.latest(10);
+     * result.records.forEach(r => console.log(r.payload));
+     */
+    latest(limit?: number): Promise<SaqlQueryResult>;
+    /**
+     * Execute a structured SaQL query against the agent.
+     * body must have at least a "type" key.
+     *
+     * @example
+     * await products.query({ type: "time_range", from_ts: 0, to_ts: 18446744073709551615 });
+     * await products.query({ type: "hash", content_hash: "e7f2..." });
+     */
+    query(body: Record<string, unknown>): Promise<SaqlQueryResult>;
+    /** Return the agent's current chain head and record count. */
+    head(): Promise<ChainHeadResponse>;
+    /** Return the agent's status (record count + chain head). */
+    status(): Promise<AgentStatusResponse>;
+    /**
+     * Soft-delete a record by content hash. Writes a tombstone — the record is
+     * excluded from `latest()` and `find()` but remains in the strand for audit.
+     * Restore with `restore(contentHash)`.
+     */
+    deleteRecord(contentHash: string): Promise<void>;
+    /** List all soft-deleted (tombstoned) records for this agent. */
+    listDeleted(): Promise<DeletedRecord[]>;
+    /** Restore a previously soft-deleted record. */
+    restore(contentHash: string): Promise<void>;
+}
+//# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;CACvB;AAID,qBAAa,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAErD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBADJ,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,MAAM;IAG/B;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IASzE;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAKhG;;OAEG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAQ7C;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,SAAK,GAAG,OAAO,CAAC,eAAe,CAAC;IAI5C;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC;IAS9D,8DAA8D;IAC9D,IAAI,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAQlC,6DAA6D;IAC7D,MAAM,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAQtC;;;;OAIG;IACH,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQhD,iEAAiE;IACjE,WAAW,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IAQvC,gDAAgD;IAChD,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAO5C"}

package/dist/collection.js

@@ -0,0 +1,78 @@
+import { request } from "./http.js";
+// CollectionClient routes all operations to /v1/agents/{name}/...
+// In SapixDB, every collection IS an agent — the agent-as-table paradigm.
+export class CollectionClient {
+    constructor(config, name) {
+        this.config = config;
+        this.name = name;
+    }
+    /**
+     * Append a JSON record to the agent's strand. Nothing is ever overwritten.
+     *
+     * @example
+     * const result = await products.write({ name: "T-Shirt", price: 29.99 });
+     * console.log(result.record_id, result.content_hash);
+     */
+    write(data) {
+        return request(this.config, "POST", `/v1/agents/${this.name}/records/json`, { data });
+    }
+    /**
+     * Append multiple records sequentially.
+     */
+    async writeBatch(records) {
+        const results = await Promise.all(records.map((data) => this.write(data)));
+        return results;
+    }
+    /**
+     * Fetch a record by content hash.
+     */
+    get(contentHash) {
+        return request(this.config, "GET", `/v1/agents/${this.name}/records/${contentHash}`);
+    }
+    /**
+     * Return the most recent N records from the agent.
+     *
+     * @example
+     * const result = await products.latest(10);
+     * result.records.forEach(r => console.log(r.payload));
+     */
+    latest(limit = 20) {
+        return this.query({ type: "latest", limit });
+    }
+    /**
+     * Execute a structured SaQL query against the agent.
+     * body must have at least a "type" key.
+     *
+     * @example
+     * await products.query({ type: "time_range", from_ts: 0, to_ts: 18446744073709551615 });
+     * await products.query({ type: "hash", content_hash: "e7f2..." });
+     */
+    query(body) {
+        return request(this.config, "POST", `/v1/agents/${this.name}/query`, body);
+    }
+    /** Return the agent's current chain head and record count. */
+    head() {
+        return request(this.config, "GET", `/v1/agents/${this.name}/strand/head`);
+    }
+    /** Return the agent's status (record count + chain head). */
+    status() {
+        return request(this.config, "GET", `/v1/agents/${this.name}/status`);
+    }
+    /**
+     * Soft-delete a record by content hash. Writes a tombstone — the record is
+     * excluded from `latest()` and `find()` but remains in the strand for audit.
+     * Restore with `restore(contentHash)`.
+     */
+    deleteRecord(contentHash) {
+        return request(this.config, "DELETE", `/v1/agents/${this.name}/records/${contentHash}`);
+    }
+    /** List all soft-deleted (tombstoned) records for this agent. */
+    listDeleted() {
+        return request(this.config, "GET", `/v1/agents/${this.name}/records/deleted`);
+    }
+    /** Restore a previously soft-deleted record. */
+    restore(contentHash) {
+        return request(this.config, "POST", `/v1/agents/${this.name}/records/${contentHash}/restore`);
+    }
+}
+//# sourceMappingURL=collection.js.map

package/dist/collection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection.js","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBpC,kEAAkE;AAClE,0EAA0E;AAC1E,MAAM,OAAO,gBAAgB;IAC3B,YACmB,MAAyB,EACzB,IAAY;QADZ,WAAM,GAAN,MAAM,CAAmB;QACzB,SAAI,GAAJ,IAAI,CAAQ;IAC5B,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,IAA0C;QAC9C,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,MAAM,EACN,cAAc,IAAI,CAAC,IAAI,eAAe,EACtC,EAAE,IAAI,EAAE,CACT,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,OAAoD;QACnE,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC3E,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,WAAmB;QACrB,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,KAAK,EACL,cAAc,IAAI,CAAC,IAAI,YAAY,WAAW,EAAE,CACjD,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,GAAG,EAAE;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,IAA6B;QACjC,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,MAAM,EACN,cAAc,IAAI,CAAC,IAAI,QAAQ,EAC/B,IAAI,CACL,CAAC;IACJ,CAAC;IAED,8DAA8D;IAC9D,IAAI;QACF,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,KAAK,EACL,cAAc,IAAI,CAAC,IAAI,cAAc,CACtC,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,MAAM;QACJ,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,KAAK,EACL,cAAc,IAAI,CAAC,IAAI,SAAS,CACjC,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,WAAmB;QAC9B,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,QAAQ,EACR,cAAc,IAAI,CAAC,IAAI,YAAY,WAAW,EAAE,CACjD,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,WAAW;QACT,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,KAAK,EACL,cAAc,IAAI,CAAC,IAAI,kBAAkB,CAC1C,CAAC;IACJ,CAAC;IAED,gDAAgD;IAChD,OAAO,CAAC,WAAmB;QACzB,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,MAAM,EACN,cAAc,IAAI,CAAC,IAAI,YAAY,WAAW,UAAU,CACzD,CAAC;IACJ,CAAC;CACF"}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export declare class SapixError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+export declare class SapixNetworkError extends SapixError {
+    constructor(cause: unknown);
+}
+export declare class SapixNotFoundError extends SapixError {
+    constructor(id: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,UAAW,SAAQ,KAAK;aAGjB,MAAM,CAAC,EAAE,MAAM;aACf,IAAI,CAAC,EAAE,MAAM;gBAF7B,OAAO,EAAE,MAAM,EACC,MAAM,CAAC,EAAE,MAAM,YAAA,EACf,IAAI,CAAC,EAAE,MAAM,YAAA;CAKhC;AAED,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,KAAK,EAAE,OAAO;CAI3B;AAED,qBAAa,kBAAmB,SAAQ,UAAU;gBACpC,EAAE,EAAE,MAAM;CAIvB"}

package/dist/errors.js

@@ -0,0 +1,21 @@
+export class SapixError extends Error {
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "SapixError";
+    }
+}
+export class SapixNetworkError extends SapixError {
+    constructor(cause) {
+        super(`Network error: ${cause instanceof Error ? cause.message : String(cause)}`);
+        this.name = "SapixNetworkError";
+    }
+}
+export class SapixNotFoundError extends SapixError {
+    constructor(id) {
+        super(`Record not found: ${id}`, 404, "NOT_FOUND");
+        this.name = "SapixNotFoundError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,YACE,OAAe,EACC,MAAe,EACf,IAAa;QAE7B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAS;QACf,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAED,MAAM,OAAO,iBAAkB,SAAQ,UAAU;IAC/C,YAAY,KAAc;QACxB,KAAK,CAAC,kBAAkB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAChD,YAAY,EAAU;QACpB,KAAK,CAAC,qBAAqB,EAAE,EAAE,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}

package/dist/graph.d.ts

@@ -0,0 +1,26 @@
+import type { SapixClientConfig, GraphEdgeInput, GraphEdge, TraverseOptions, TraversalResult } from "./types.js";
+export declare class GraphClient {
+    private readonly config;
+    constructor(config: SapixClientConfig);
+    /** Create a directed edge between two agents or records. */
+    addEdge(edge: GraphEdgeInput): Promise<void>;
+    /** Convenience: create an edge with weight 1.0. */
+    relate(src: string, dst: string, edgeType: string, weight?: number): Promise<void>;
+    /** Delete a directed edge. */
+    removeEdge(src: string, edgeType: string, dst: string): Promise<void>;
+    /** Get all outbound edges from an agent. */
+    edges(agentId: string): Promise<GraphEdge[]>;
+    /** Get all inbound edges to an agent. */
+    inboundEdges(agentId: string): Promise<GraphEdge[]>;
+    /**
+     * Traverse the agent graph from a starting agent.
+     * Returns agents visited and the edges connecting them.
+     *
+     * @example
+     * const result = await db.graph.traverse("orders-agt", { depth: 2 });
+     */
+    traverse(agentId: string, options?: TraverseOptions): Promise<TraversalResult>;
+    /** Add a cross-agent record reference edge. */
+    addRecordRef(srcAgent: string, srcHash: string, edgeType: string, dstAgent: string, dstHash: string): Promise<void>;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,iBAAiB;IAEtD,4DAA4D;IAC5D,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5C,mDAAmD;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/E,8BAA8B;IAC9B,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQrE,4CAA4C;IAC5C,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQ5C,yCAAyC;IACzC,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQnD;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IASlF,+CAA+C;IAC/C,YAAY,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;CASjB"}

package/dist/graph.js

@@ -0,0 +1,52 @@
+import { request } from "./http.js";
+export class GraphClient {
+    constructor(config) {
+        this.config = config;
+    }
+    /** Create a directed edge between two agents or records. */
+    addEdge(edge) {
+        return request(this.config, "POST", "/v1/graph/edges", { ...edge, weight: edge.weight ?? 1.0 });
+    }
+    /** Convenience: create an edge with weight 1.0. */
+    relate(src, dst, edgeType, weight = 1.0) {
+        return this.addEdge({ src, dst, edge_type: edgeType, weight });
+    }
+    /** Delete a directed edge. */
+    removeEdge(src, edgeType, dst) {
+        return request(this.config, "DELETE", `/v1/graph/edges/${src}/${edgeType}/${dst}`);
+    }
+    /** Get all outbound edges from an agent. */
+    edges(agentId) {
+        return request(this.config, "GET", `/v1/graph/edges/${agentId}`);
+    }
+    /** Get all inbound edges to an agent. */
+    inboundEdges(agentId) {
+        return request(this.config, "GET", `/v1/graph/edges/${agentId}?direction=in`);
+    }
+    /**
+     * Traverse the agent graph from a starting agent.
+     * Returns agents visited and the edges connecting them.
+     *
+     * @example
+     * const result = await db.graph.traverse("orders-agt", { depth: 2 });
+     */
+    traverse(agentId, options = {}) {
+        const depth = options.depth ?? 1;
+        let path = `/v1/graph/traverse?agent_id=${encodeURIComponent(agentId)}&depth=${depth}`;
+        if (options.edge_type) {
+            path += `&edge_type=${encodeURIComponent(options.edge_type)}`;
+        }
+        return request(this.config, "GET", path);
+    }
+    /** Add a cross-agent record reference edge. */
+    addRecordRef(srcAgent, srcHash, edgeType, dstAgent, dstHash) {
+        return request(this.config, "POST", "/v1/graph/refs", {
+            src_agent: srcAgent,
+            src_content_hash: srcHash,
+            edge_type: edgeType,
+            dst_agent: dstAgent,
+            dst_content_hash: dstHash,
+        });
+    }
+}
+//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,MAAM,OAAO,WAAW;IACtB,YAA6B,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAE1D,4DAA4D;IAC5D,OAAO,CAAC,IAAoB;QAC1B,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,MAAM,EACN,iBAAiB,EACjB,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG,EAAE,CACxC,CAAC;IACJ,CAAC;IAED,mDAAmD;IACnD,MAAM,CAAC,GAAW,EAAE,GAAW,EAAE,QAAgB,EAAE,MAAM,GAAG,GAAG;QAC7D,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;IACjE,CAAC;IAED,8BAA8B;IAC9B,UAAU,CAAC,GAAW,EAAE,QAAgB,EAAE,GAAW;QACnD,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,QAAQ,EACR,mBAAmB,GAAG,IAAI,QAAQ,IAAI,GAAG,EAAE,CAC5C,CAAC;IACJ,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,OAAe;QACnB,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,KAAK,EACL,mBAAmB,OAAO,EAAE,CAC7B,CAAC;IACJ,CAAC;IAED,yCAAyC;IACzC,YAAY,CAAC,OAAe;QAC1B,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,KAAK,EACL,mBAAmB,OAAO,eAAe,CAC1C,CAAC;IACJ,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,OAAe,EAAE,UAA2B,EAAE;QACrD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;QACjC,IAAI,IAAI,GAAG,+BAA+B,kBAAkB,CAAC,OAAO,CAAC,UAAU,KAAK,EAAE,CAAC;QACvF,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,IAAI,IAAI,cAAc,kBAAkB,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAChE,CAAC;QACD,OAAO,OAAO,CAAkB,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED,+CAA+C;IAC/C,YAAY,CACV,QAAgB,EAChB,OAAe,EACf,QAAgB,EAChB,QAAgB,EAChB,OAAe;QAEf,OAAO,OAAO,CAAO,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE;YAC1D,SAAS,EAAE,QAAQ;YACnB,gBAAgB,EAAE,OAAO;YACzB,SAAS,EAAE,QAAQ;YACnB,SAAS,EAAE,QAAQ;YACnB,gBAAgB,EAAE,OAAO;SAC1B,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/http.d.ts

@@ -0,0 +1,3 @@
+import type { SapixClientConfig } from "./types.js";
+export declare function request<T>(config: SapixClientConfig, method: string, path: string, body?: unknown): Promise<T>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,OAAO,GACb,OAAO,CAAC,CAAC,CAAC,CA2CZ"}

package/dist/http.js

@@ -0,0 +1,48 @@
+import { SapixError, SapixNetworkError } from "./errors.js";
+export async function request(config, method, path, body) {
+    const url = `${config.url}${path}`;
+    const headers = {
+        "Content-Type": "application/json",
+        ...config.headers,
+    };
+    if (config.apiKey) {
+        headers["Authorization"] = `Bearer ${config.apiKey}`;
+    }
+    if (config.callerId) {
+        headers["X-Sapix-Caller"] = config.callerId;
+    }
+    let res;
+    try {
+        const opts = { method, headers };
+        if (body !== undefined)
+            opts.body = JSON.stringify(body);
+        if (config.timeout) {
+            const ac = new AbortController();
+            const timer = setTimeout(() => ac.abort(), config.timeout);
+            opts.signal = ac.signal;
+            res = await fetch(url, opts);
+            clearTimeout(timer);
+        }
+        else {
+            res = await fetch(url, opts);
+        }
+    }
+    catch (err) {
+        throw new SapixNetworkError(err);
+    }
+    if (!res.ok) {
+        let message = `HTTP ${res.status}`;
+        let code;
+        try {
+            const body = await res.json();
+            if (body.error)
+                message = body.error;
+            if (body.code)
+                code = body.code;
+        }
+        catch { /* ignore parse error */ }
+        throw new SapixError(message, res.status, code);
+    }
+    return res.json();
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAG5D,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,MAAyB,EACzB,MAAc,EACd,IAAY,EACZ,IAAc;IAEd,MAAM,GAAG,GAAG,GAAG,MAAM,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC;IACnC,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,kBAAkB;QAClC,GAAG,MAAM,CAAC,OAAO;KAClB,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;QAClB,OAAO,CAAC,eAAe,CAAC,GAAG,UAAU,MAAM,CAAC,MAAM,EAAE,CAAC;IACvD,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC;IAC9C,CAAC;IAED,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,IAAI,GAAgB,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;QAC9C,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAEzD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,EAAE,GAAG,IAAI,eAAe,EAAE,CAAC;YACjC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;YAC3D,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;YACxB,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAC7B,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,IAAI,OAAO,GAAG,QAAQ,GAAG,CAAC,MAAM,EAAE,CAAC;QACnC,IAAI,IAAwB,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAuC,CAAC;YACnE,IAAI,IAAI,CAAC,KAAK;gBAAE,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC;YACrC,IAAI,IAAI,CAAC,IAAI;gBAAE,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QAClC,CAAC;QAAC,MAAM,CAAC,CAAC,wBAAwB,CAAC,CAAC;QACpC,MAAM,IAAI,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,GAAG,CAAC,IAAI,EAAgB,CAAC;AAClC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { SapixClient } from "./client.js";
+export { CollectionClient } from "./collection.js";
+export type { DeletedRecord } from "./collection.js";
+export { GraphClient } from "./graph.js";
+export { SapixError, SapixNetworkError, SapixNotFoundError } from "./errors.js";
+export { subscribeAgent, subscribeGlobal } from "./stream.js";
+export type { SapixClientConfig, WriteResponse, CheckpointResponse, RecordView, ChainHeadResponse, AgentStatusResponse, CreateAgentResponse, AgentListResponse, GraphEdge, GraphEdgeInput, TraverseOptions, TraversalResult, TraversalEdge, HealthResponse, SaqlQueryResult, SemanticQueryResult, } from "./types.js";
+export type { StreamEvent, SubscribeOptions } from "./stream.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9D,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,UAAU,EACV,iBAAiB,EACjB,mBAAmB,EACnB,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,cAAc,EACd,eAAe,EACf,eAAe,EACf,aAAa,EACb,cAAc,EACd,eAAe,EACf,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { SapixClient } from "./client.js";
+export { CollectionClient } from "./collection.js";
+export { GraphClient } from "./graph.js";
+export { SapixError, SapixNetworkError, SapixNotFoundError } from "./errors.js";
+export { subscribeAgent, subscribeGlobal } from "./stream.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}

package/dist/stream.d.ts

@@ -0,0 +1,42 @@
+import type { SapixClientConfig } from "./types.js";
+/** A realtime write event pushed via SSE from SapixDB. */
+export interface StreamEvent {
+    agent_id: string;
+    event_type: string;
+    record_id: string;
+    content_hash: string;
+    timestamp_ms: number;
+    payload?: unknown;
+}
+/** Options for SSE subscriptions. */
+export interface SubscribeOptions {
+    /** HLC timestamp — server replays records written after this value before going live. */
+    since?: number;
+    /** Only emit events whose JSON payload contains this top-level field name. */
+    filter?: string;
+}
+/**
+ * Open an SSE stream for a single named agent.
+ * Returns an EventSource — call `.close()` to unsubscribe.
+ *
+ * @example
+ * const es = db.subscribeAgent("orders", (event) => {
+ *   console.log("new record:", event.record_id, event.payload);
+ * });
+ * // Later:
+ * es.close();
+ */
+export declare function subscribeAgent(config: SapixClientConfig, agentId: string, onEvent: (event: StreamEvent) => void, opts?: SubscribeOptions): EventSource;
+/**
+ * Open an SSE stream for all agents (optionally filtered).
+ * Returns an EventSource — call `.close()` to unsubscribe.
+ *
+ * @example
+ * const es = db.subscribeGlobal((event) => {
+ *   console.log(event.agent_id, event.record_id);
+ * }, { agents: ["orders", "payments"] });
+ */
+export declare function subscribeGlobal(config: SapixClientConfig, onEvent: (event: StreamEvent) => void, opts?: SubscribeOptions & {
+    agents?: string[];
+}): EventSource;
+//# sourceMappingURL=stream.d.ts.map

package/dist/stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.ts","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qCAAqC;AACrC,MAAM,WAAW,gBAAgB;IAC/B,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,EACrC,IAAI,CAAC,EAAE,gBAAgB,GACtB,WAAW,CAcb;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,EACrC,IAAI,CAAC,EAAE,gBAAgB,GAAG;IAAE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GAC9C,WAAW,CAeb"}

package/dist/stream.js

@@ -0,0 +1,59 @@
+/**
+ * Open an SSE stream for a single named agent.
+ * Returns an EventSource — call `.close()` to unsubscribe.
+ *
+ * @example
+ * const es = db.subscribeAgent("orders", (event) => {
+ *   console.log("new record:", event.record_id, event.payload);
+ * });
+ * // Later:
+ * es.close();
+ */
+export function subscribeAgent(config, agentId, onEvent, opts) {
+    const params = new URLSearchParams();
+    if (opts?.since != null)
+        params.set("since", String(opts.since));
+    if (opts?.filter)
+        params.set("filter", opts.filter);
+    const qs = params.size > 0 ? `?${params}` : "";
+    const es = new EventSource(`${config.url}/v1/agents/${agentId}/stream${qs}`);
+    es.addEventListener("record.written", (e) => {
+        try {
+            onEvent(JSON.parse(e.data));
+        }
+        catch {
+            // ignore malformed events
+        }
+    });
+    return es;
+}
+/**
+ * Open an SSE stream for all agents (optionally filtered).
+ * Returns an EventSource — call `.close()` to unsubscribe.
+ *
+ * @example
+ * const es = db.subscribeGlobal((event) => {
+ *   console.log(event.agent_id, event.record_id);
+ * }, { agents: ["orders", "payments"] });
+ */
+export function subscribeGlobal(config, onEvent, opts) {
+    const params = new URLSearchParams();
+    if (opts?.agents?.length)
+        params.set("agents", opts.agents.join(","));
+    if (opts?.since != null)
+        params.set("since", String(opts.since));
+    if (opts?.filter)
+        params.set("filter", opts.filter);
+    const qs = params.size > 0 ? `?${params}` : "";
+    const es = new EventSource(`${config.url}/v1/stream${qs}`);
+    es.addEventListener("record.written", (e) => {
+        try {
+            onEvent(JSON.parse(e.data));
+        }
+        catch {
+            // ignore malformed events
+        }
+    });
+    return es;
+}
+//# sourceMappingURL=stream.js.map

package/dist/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sourceRoot":"","sources":["../src/stream.ts"],"names":[],"mappings":"AAoBA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAyB,EACzB,OAAe,EACf,OAAqC,EACrC,IAAuB;IAEvB,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,IAAI,IAAI,EAAE,MAAM;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,MAAM,EAAE,GAAG,IAAI,WAAW,CAAC,GAAG,MAAM,CAAC,GAAG,cAAc,OAAO,UAAU,EAAE,EAAE,CAAC,CAAC;IAC7E,EAAE,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,CAAC,CAAQ,EAAE,EAAE;QACjD,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAE,CAAkB,CAAC,IAAI,CAAgB,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,0BAA0B;QAC5B,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAyB,EACzB,OAAqC,EACrC,IAA+C;IAE/C,MAAM,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;IACrC,IAAI,IAAI,EAAE,MAAM,EAAE,MAAM;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACtE,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACjE,IAAI,IAAI,EAAE,MAAM;QAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,MAAM,EAAE,GAAG,IAAI,WAAW,CAAC,GAAG,MAAM,CAAC,GAAG,aAAa,EAAE,EAAE,CAAC,CAAC;IAC3D,EAAE,CAAC,gBAAgB,CAAC,gBAAgB,EAAE,CAAC,CAAQ,EAAE,EAAE;QACjD,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAE,CAAkB,CAAC,IAAI,CAAgB,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,0BAA0B;QAC5B,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,124 @@
+export interface SapixClientConfig {
+    /** Base URL of the SapixDB agent, e.g. "http://localhost:7475" */
+    url: string;
+    /**
+     * API key for SapixDB bearer-token authentication (`SAPIX_API_KEY` on the server).
+     * When set, every request will include `Authorization: Bearer <apiKey>`.
+     * Takes precedence over a manually specified `Authorization` header in `headers`.
+     */
+    apiKey?: string;
+    /**
+     * Caller identity forwarded to Codios as `caller_identity`.
+     * Sent as `X-Sapix-Caller: <callerId>`. Use your Codios agent ID here
+     * so Codios can enforce per-caller policies.
+     */
+    callerId?: string;
+    /** Optional extra headers sent with every request */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds (default: 10000) */
+    timeout?: number;
+}
+/** Returned by every write operation. */
+export interface WriteResponse {
+    record_id: string;
+    content_hash: string;
+    chain_head: string;
+    /** null = Codios not configured (open mode); true = Codios authorized. */
+    codios_verified: boolean | null;
+    /** "open" or "enforced" */
+    codios_mode: string;
+    codios_contract_id?: string;
+}
+/** Returned by POST /v1/control/checkpoint. Requires root key or admin:* scope. */
+export interface CheckpointResponse {
+    status: string;
+    agents_checkpointed: number;
+}
+/** A single strand record returned by reads and queries. */
+export interface RecordView {
+    record_id: string;
+    content_hash: string;
+    parent_hash: string;
+    /** HLC timestamp packed as u64. */
+    timestamp_hlc: number;
+    timestamp_ms: number;
+    /** Base64-encoded raw payload bytes. */
+    payload_b64: string;
+    /** Decoded JSON payload (present on /json endpoints). */
+    payload?: unknown;
+    flags: number;
+    schema_version: number;
+}
+/** Response from GET /v1/strand/head and GET /v1/agents/:id/strand/head. */
+export interface ChainHeadResponse {
+    chain_head: string;
+    record_count: number;
+}
+/** Response from GET /v1/agents/:id/status. */
+export interface AgentStatusResponse {
+    agent_id: string;
+    record_count: number;
+    chain_head: string;
+}
+/** Response from POST /v1/agents. */
+export interface CreateAgentResponse {
+    agent_id: string;
+    public_key_hex: string;
+    genesis_record_id: string;
+    chain_head_hex: string;
+    zone: string;
+}
+/** Response from GET /v1/agents. */
+export interface AgentListResponse {
+    agents: string[];
+    total: number;
+}
+export interface GraphEdgeInput {
+    src: string;
+    dst: string;
+    edge_type: string;
+    weight?: number;
+}
+export interface GraphEdge {
+    src: string;
+    edge_type: string;
+    dst: string;
+    timestamp_hlc: number;
+    weight: number;
+}
+export interface TraversalEdge {
+    src: string;
+    dst: string;
+    edge_type: string;
+    weight: number;
+    across_peer: boolean;
+    peer_endpoint?: string;
+}
+export interface TraversalResult {
+    start_agent: string;
+    agents_visited: string[];
+    edges: TraversalEdge[];
+    depth_reached: number;
+}
+export interface TraverseOptions {
+    depth?: number;
+    edge_type?: string;
+}
+export interface HealthResponse {
+    status: string;
+    agent_id: string;
+    record_count: number;
+    chain_head: string;
+}
+/** Response from POST /v1/query and POST /v1/agents/:id/query. */
+export interface SaqlQueryResult {
+    records: RecordView[];
+    total: number;
+}
+/** Response from POST /v1/query/semantic. */
+export interface SemanticQueryResult {
+    source: string;
+    plan: Record<string, unknown>;
+    records: RecordView[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "sapixdb-js",
+  "version": "0.3.0",
+  "description": "Official JavaScript/TypeScript SDK for SapixDB — the agent-native living database",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "sapixdb",
+    "database",
+    "agent-native",
+    "ai-database",
+    "sdk",
+    "typescript"
+  ],
+  "author": "Sensart Technologies LLC",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sensart/sapixdb"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}