sapixdb 0.1.0 → 0.3.0

package/README.md

@@ -1,295 +0,0 @@
-# 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/graph.d.ts

@@ -1,28 +0,0 @@
-import type { SapixClientConfig, GraphEdgeInput, GraphEdge, TraverseOptions, TraverseResult, NucleotideRecord } from "./types.js";
-export declare class GraphClient {
-    private readonly config;
-    constructor(config: SapixClientConfig);
-    /** Create a directed edge between two records. */
-    addEdge(edge: GraphEdgeInput): Promise<void>;
-    /** Remove an edge between two records. */
-    removeEdge(src: string, dst: string, edge_type: string): Promise<void>;
-    /**
-     * Traverse the graph from a starting node.
-     * Returns all reachable nodes and the edges connecting them.
-     */
-    traverse(fromId: string, options?: TraverseOptions): Promise<TraverseResult>;
-    /** Get all direct neighbours of a node. */
-    neighbors(id: string, direction?: "outbound" | "inbound" | "both"): Promise<NucleotideRecord[]>;
-    /** Get all outbound edges from a node. */
-    edges(id: string): Promise<GraphEdge[]>;
-    /**
-     * Connect two records with a typed relationship.
-     * Convenience wrapper around addEdge.
-     *
-     * @example
-     * await db.graph.relate(orderId, customerId, "placed_by");
-     * await db.graph.relate(productId, categoryId, "belongs_to");
-     */
-    relate(src: string, dst: string, type: string, weight?: number): Promise<void>;
-}
-//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -1 +0,0 @@
-{"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,cAAc,EACd,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,iBAAiB;IAEtD,kDAAkD;IAC5C,OAAO,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IASlD,0CAA0C;IACpC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS5E;;;OAGG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,cAAc,CAAC;IAS1B,2CAA2C;IACrC,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,GAAE,UAAU,GAAG,SAAS,GAAG,MAAmB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAKjH,0CAA0C;IACpC,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAK7C;;;;;;;OAOG;IACG,MAAM,CACV,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,SAAM,GACX,OAAO,CAAC,IAAI,CAAC;CAGjB"}

package/dist/graph.js

@@ -1,44 +0,0 @@
-import { request } from "./http.js";
-export class GraphClient {
-    constructor(config) {
-        this.config = config;
-    }
-    /** Create a directed edge between two records. */
-    async addEdge(edge) {
-        await request(this.config, "POST", `/v1/${this.config.agent}/graph/edge`, { ...edge, weight: edge.weight ?? 1.0 });
-    }
-    /** Remove an edge between two records. */
-    async removeEdge(src, dst, edge_type) {
-        await request(this.config, "DELETE", `/v1/${this.config.agent}/graph/edge`, { src, dst, edge_type });
-    }
-    /**
-     * Traverse the graph from a starting node.
-     * Returns all reachable nodes and the edges connecting them.
-     */
-    async traverse(fromId, options = {}) {
-        const { depth = 1, direction = "outbound" } = options;
-        return request(this.config, "GET", `/v1/${this.config.agent}/graph/traverse/${fromId}?depth=${depth}&direction=${direction}`);
-    }
-    /** Get all direct neighbours of a node. */
-    async neighbors(id, direction = "outbound") {
-        const result = await this.traverse(id, { depth: 1, direction });
-        return result.nodes;
-    }
-    /** Get all outbound edges from a node. */
-    async edges(id) {
-        const result = await this.traverse(id, { depth: 1 });
-        return result.edges;
-    }
-    /**
-     * Connect two records with a typed relationship.
-     * Convenience wrapper around addEdge.
-     *
-     * @example
-     * await db.graph.relate(orderId, customerId, "placed_by");
-     * await db.graph.relate(productId, categoryId, "belongs_to");
-     */
-    async relate(src, dst, type, weight = 1.0) {
-        return this.addEdge({ src, dst, edge_type: type, weight });
-    }
-}
-//# sourceMappingURL=graph.js.map

package/dist/graph.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"graph.js","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,MAAM,OAAO,WAAW;IACtB,YAA6B,MAAyB;QAAzB,WAAM,GAAN,MAAM,CAAmB;IAAG,CAAC;IAE1D,kDAAkD;IAClD,KAAK,CAAC,OAAO,CAAC,IAAoB;QAChC,MAAM,OAAO,CACX,IAAI,CAAC,MAAM,EACX,MAAM,EACN,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,aAAa,EACrC,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,GAAG,EAAE,CACxC,CAAC;IACJ,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,UAAU,CAAC,GAAW,EAAE,GAAW,EAAE,SAAiB;QAC1D,MAAM,OAAO,CACX,IAAI,CAAC,MAAM,EACX,QAAQ,EACR,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,aAAa,EACrC,EAAE,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,CACxB,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,QAAQ,CACZ,MAAc,EACd,UAA2B,EAAE;QAE7B,MAAM,EAAE,KAAK,GAAG,CAAC,EAAE,SAAS,GAAG,UAAU,EAAE,GAAG,OAAO,CAAC;QACtD,OAAO,OAAO,CACZ,IAAI,CAAC,MAAM,EACX,KAAK,EACL,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,mBAAmB,MAAM,UAAU,KAAK,cAAc,SAAS,EAAE,CAC1F,CAAC;IACJ,CAAC;IAED,2CAA2C;IAC3C,KAAK,CAAC,SAAS,CAAC,EAAU,EAAE,YAA6C,UAAU;QACjF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC;QAChE,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED,0CAA0C;IAC1C,KAAK,CAAC,KAAK,CAAC,EAAU;QACpB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;QACrD,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,CACV,GAAW,EACX,GAAW,EACX,IAAY,EACZ,MAAM,GAAG,GAAG;QAEZ,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/http.d.ts

@@ -1,3 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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,CAqCZ"}

package/dist/http.js

@@ -1,42 +0,0 @@
-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,
-    };
-    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

@@ -1 +0,0 @@
-{"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;IAEF,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"}