sapixdb 0.1.0 → 0.3.0

package/dist/collection.d.ts

@@ -1,41 +1,134 @@
-import type { SapixClientConfig, WriteResult, NucleotideRecord, QueryOptions } from "./types.js";
-export declare class CollectionQuery<T = Record<string, unknown>> {
-    private readonly config;
+import type { AgentStatusResponse, ChainHeadResponse, DeletedRecord, QueryResult, RecordView, SaqlQuery, StrandRecordsResponse, WriteResponse } from "./types.js";
+type Requester = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+/**
+ * A read-only view of a collection scoped to a specific point in time.
+ * Returned by `CollectionClient.asOf(timestampHlc)`.
+ *
+ * @example
+ * const snapshot = db.collection("orders").asOf(record.timestamp_hlc);
+ * const results  = await snapshot.latest({ limit: 10 });
+ */
+export declare class CollectionSnapshot {
     private readonly name;
-    private readonly asOfTimestamp?;
-    constructor(config: SapixClientConfig, name: string, asOfTimestamp?: string | undefined);
-    /** Fetch all versions matching filter (full history). */
-    all(options?: Omit<QueryOptions, "latest">): Promise<NucleotideRecord<T>[]>;
-    /** Fetch only the latest version of each matching record. */
-    latest(options?: Omit<QueryOptions, "latest">): Promise<NucleotideRecord<T>[]>;
-    /** Find records matching a filter, latest version only. */
-    find(filter: Record<string, unknown>, options?: Omit<QueryOptions, "filter" | "latest">): Promise<NucleotideRecord<T>[]>;
-    /** Find one record matching a filter, or null. */
-    findOne(filter: Record<string, unknown>): Promise<NucleotideRecord<T> | null>;
-    private _query;
+    private readonly timestampHlc;
+    private readonly req;
+    constructor(name: string, timestampHlc: number, req: Requester);
+    /** Records written at or before this snapshot timestamp, newest-first. */
+    latest(opts?: {
+        limit?: number;
+    }): Promise<QueryResult>;
+    /**
+     * Equality-filter scan bounded by the snapshot timestamp.
+     * `filter` is a `{field: value}` object — first key is used.
+     */
+    find(filter: Record<string, unknown>, opts?: {
+        limit?: number;
+    }): Promise<QueryResult>;
+    findOne(filter: Record<string, unknown>): Promise<RecordView | null>;
 }
-export declare class CollectionClient<T = Record<string, unknown>> {
-    private readonly config;
-    private readonly name;
-    constructor(config: SapixClientConfig, name: string);
-    /**
-     * Return a query scoped to a specific point in time.
-     * @param timestamp ISO 8601 string, e.g. "2026-05-12T10:00:00Z"
-     */
-    asOf(timestamp: string): CollectionQuery<T>;
-    /** Write a new record. Every write is a new nucleotide — nothing is overwritten. */
-    write(data: Partial<T> & Record<string, unknown>): Promise<WriteResult>;
-    /** Write multiple records in one call. */
-    writeBatch(records: Array<Partial<T> & Record<string, unknown>>): Promise<WriteResult[]>;
-    /** Fetch a single record by its nucleotide ID. */
-    get(id: string): Promise<NucleotideRecord<T>>;
-    /** Query the latest version of all records in this collection. */
-    latest(options?: Omit<QueryOptions, "latest">): Promise<NucleotideRecord<T>[]>;
-    /** Query ALL versions (full history) in this collection. */
-    history(options?: Omit<QueryOptions, "latest">): Promise<NucleotideRecord<T>[]>;
-    /** Find records matching a filter (latest version only). */
-    find(filter: Record<string, unknown>, options?: Omit<QueryOptions, "filter" | "latest">): Promise<NucleotideRecord<T>[]>;
-    /** Find one record or return null. */
-    findOne(filter: Record<string, unknown>): Promise<NucleotideRecord<T> | null>;
+/**
+ * Client for a named SapixDB agent (collection).
+ * All operations route to `/v1/agents/{name}/...`.
+ *
+ * Obtain via `SapixClient.collection(name)` or `SapixClient.agent(name)`.
+ *
+ * @example
+ * const orders = db.collection("orders");
+ *
+ * // Write
+ * const record = await orders.write({ total: 99.99, status: "pending" });
+ *
+ * // Read
+ * const latest  = await orders.latest({ limit: 20 });
+ * const pending = await orders.find({ status: "pending" });
+ * const one     = await orders.findOne({ status: "pending" });
+ * const byHash  = await orders.get(record.content_hash);
+ *
+ * // History (chronological)
+ * const history = await orders.history({ limit: 100, offset: 0 });
+ *
+ * // Time travel
+ * const snapshot = await orders.asOf(record.timestamp_hlc).latest();
+ *
+ * // Direct SaQL
+ * const result = await orders.query({ type: "latest", limit: 5 });
+ *
+ * // Realtime — handled on SapixClient
+ * client.subscribeAgent("orders", (event) => console.log(event));
+ */
+export declare class CollectionClient {
+    readonly name: string;
+    private readonly req;
+    constructor(name: string, req: Requester);
+    /**
+     * Append a JSON record to the agent's strand.
+     * `data` can be any JSON-serialisable object.
+     */
+    write(data: Record<string, unknown>): Promise<WriteResponse>;
+    /** Alias for `write` — matches Python/Go SDK naming. */
+    writeJson(data: Record<string, unknown>): Promise<WriteResponse>;
+    /**
+     * Fetch a single record by its BLAKE3 content hash.
+     * Use `record.content_hash` from a previous write or query.
+     */
+    get(contentHash: string): Promise<RecordView>;
+    /**
+     * Return the most recent records, newest-first.
+     *
+     * Pass `filter: { field: value }` to run an equality scan (uses a field
+     * index when one is available for that field, otherwise a full strand scan).
+     */
+    latest(opts?: {
+        limit?: number;
+        filter?: Record<string, unknown>;
+    }): Promise<QueryResult>;
+    /**
+     * Return records in chronological order (oldest-first) with pagination.
+     * Uses `GET /v1/agents/{name}/strand/records`.
+     */
+    history(opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StrandRecordsResponse>;
+    /**
+     * Equality-filter scan across the full strand.
+     * `filter` is a `{field: value}` object — first key is used.
+     *
+     * Uses a field index when one exists for that field; otherwise falls back
+     * to a full strand scan on the server.
+     */
+    find(filter: Record<string, unknown>, opts?: {
+        limit?: number;
+    }): Promise<QueryResult>;
+    /** Return the first matching record, or `null` if none. */
+    findOne(filter: Record<string, unknown>): Promise<RecordView | null>;
+    /** Execute any SaQL query directly against this agent. */
+    query(q: SaqlQuery): Promise<QueryResult>;
+    /** Current chain head hash and record count. */
+    head(): Promise<ChainHeadResponse>;
+    /** Agent status: record count, chain head, zone, schema version, caged state. */
+    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)`.
+     */
+    softDelete(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>;
+    /**
+     * Scope reads to a point in time identified by an HLC timestamp.
+     * Returns a `CollectionSnapshot` — call `.latest()` or `.find()` on it.
+     *
+     * @param timestampHlc — `NucleotideRecord.timestamp_hlc` from any prior record
+     *
+     * @example
+     * const snapshot = orders.asOf(record.timestamp_hlc);
+     * const state    = await snapshot.latest({ limit: 50 });
+     */
+    asOf(timestampHlc: number): CollectionSnapshot;
 }
+export {};
 //# sourceMappingURL=collection.d.ts.map

package/dist/collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,eAAe,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAEpD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;gBAFd,MAAM,EAAE,iBAAiB,EACzB,IAAI,EAAE,MAAM,EACZ,aAAa,CAAC,EAAE,MAAM,YAAA;IAGzC,yDAAyD;IACnD,GAAG,CAAC,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAIrF,6DAA6D;IACvD,MAAM,CAAC,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAIxF,2DAA2D;IACrD,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,QAAQ,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAIlI,kDAAkD;IAC5C,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;YAKrE,MAAM;CAerB;AAED,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;;;OAGG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAAC,CAAC,CAAC;IAI3C,oFAAoF;IAC9E,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC;IAS7E,0CAA0C;IACpC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAK9F,kDAAkD;IAC5C,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAenD,kEAAkE;IAC5D,MAAM,CAAC,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAIxF,4DAA4D;IACtD,OAAO,CAAC,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAIzF,4DAA4D;IACtD,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAE,IAAI,CAAC,YAAY,EAAE,QAAQ,GAAG,QAAQ,CAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAIlI,sCAAsC;IAChC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CAGpF"}
+{"version":3,"file":"collection.d.ts","sourceRoot":"","sources":["../src/collection.ts"],"names":[],"mappings":"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"}

package/dist/collection.js

@@ -1,87 +1,207 @@
-import { request } from "./http.js";
-import { SapixNotFoundError } from "./errors.js";
-export class CollectionQuery {
-    constructor(config, name, asOfTimestamp) {
-        this.config = config;
+// ── CollectionSnapshot ────────────────────────────────────────────────────────
+/**
+ * A read-only view of a collection scoped to a specific point in time.
+ * Returned by `CollectionClient.asOf(timestampHlc)`.
+ *
+ * @example
+ * const snapshot = db.collection("orders").asOf(record.timestamp_hlc);
+ * const results  = await snapshot.latest({ limit: 10 });
+ */
+export class CollectionSnapshot {
+    name;
+    timestampHlc;
+    req;
+    constructor(name, timestampHlc, req) {
         this.name = name;
-        this.asOfTimestamp = asOfTimestamp;
+        this.timestampHlc = timestampHlc;
+        this.req = req;
     }
-    /** Fetch all versions matching filter (full history). */
-    async all(options = {}) {
-        return this._query({ ...options, latest: false });
+    /** Records written at or before this snapshot timestamp, newest-first. */
+    latest(opts = {}) {
+        return this.req("POST", `/v1/agents/${this.name}/query`, {
+            type: "as_of",
+            timestamp_hlc: this.timestampHlc,
+            limit: opts.limit ?? 20,
+        });
     }
-    /** Fetch only the latest version of each matching record. */
-    async latest(options = {}) {
-        return this._query({ ...options, latest: true });
-    }
-    /** Find records matching a filter, latest version only. */
-    async find(filter, options = {}) {
-        return this._query({ filter, latest: true, ...options });
+    /**
+     * Equality-filter scan bounded by the snapshot timestamp.
+     * `filter` is a `{field: value}` object — first key is used.
+     */
+    find(filter, opts = {}) {
+        const [field, value] = Object.entries(filter)[0] ?? [];
+        const whereFilter = field
+            ? { field, op: "eq", value }
+            : undefined;
+        return this.req("POST", `/v1/agents/${this.name}/query`, {
+            type: "scan",
+            limit: opts.limit ?? 20,
+            ...(whereFilter ? { filter: whereFilter } : {}),
+        });
     }
-    /** Find one record matching a filter, or null. */
     async findOne(filter) {
-        const results = await this.find(filter, { limit: 1 });
-        return results[0] ?? null;
-    }
-    async _query(options) {
-        const body = {
-            collection: this.name,
-            ...options,
-        };
-        if (this.asOfTimestamp)
-            body.as_of = this.asOfTimestamp;
-        const res = await request(this.config, "POST", `/v1/${this.config.agent}/strand/query`, body);
-        return res.results;
+        const result = await this.find(filter, { limit: 1 });
+        return result.records[0] ?? null;
     }
 }
+// ── CollectionClient ──────────────────────────────────────────────────────────
+/**
+ * Client for a named SapixDB agent (collection).
+ * All operations route to `/v1/agents/{name}/...`.
+ *
+ * Obtain via `SapixClient.collection(name)` or `SapixClient.agent(name)`.
+ *
+ * @example
+ * const orders = db.collection("orders");
+ *
+ * // Write
+ * const record = await orders.write({ total: 99.99, status: "pending" });
+ *
+ * // Read
+ * const latest  = await orders.latest({ limit: 20 });
+ * const pending = await orders.find({ status: "pending" });
+ * const one     = await orders.findOne({ status: "pending" });
+ * const byHash  = await orders.get(record.content_hash);
+ *
+ * // History (chronological)
+ * const history = await orders.history({ limit: 100, offset: 0 });
+ *
+ * // Time travel
+ * const snapshot = await orders.asOf(record.timestamp_hlc).latest();
+ *
+ * // Direct SaQL
+ * const result = await orders.query({ type: "latest", limit: 5 });
+ *
+ * // Realtime — handled on SapixClient
+ * client.subscribeAgent("orders", (event) => console.log(event));
+ */
 export class CollectionClient {
-    constructor(config, name) {
-        this.config = config;
+    name;
+    req;
+    constructor(name, req) {
         this.name = name;
+        this.req = req;
     }
+    // ── Writes ──────────────────────────────────────────────────────────────────
     /**
-     * Return a query scoped to a specific point in time.
-     * @param timestamp ISO 8601 string, e.g. "2026-05-12T10:00:00Z"
+     * Append a JSON record to the agent's strand.
+     * `data` can be any JSON-serialisable object.
      */
-    asOf(timestamp) {
-        return new CollectionQuery(this.config, this.name, timestamp);
-    }
-    /** Write a new record. Every write is a new nucleotide — nothing is overwritten. */
-    async write(data) {
-        return request(this.config, "POST", `/v1/${this.config.agent}/strand/write`, { collection: this.name, data });
-    }
-    /** Write multiple records in one call. */
-    async writeBatch(records) {
-        const results = await Promise.all(records.map((data) => this.write(data)));
-        return results;
-    }
-    /** Fetch a single record by its nucleotide ID. */
-    async get(id) {
-        try {
-            return await request(this.config, "GET", `/v1/${this.config.agent}/strand/${id}`);
-        }
-        catch (err) {
-            if (err instanceof Error && "status" in err && err.status === 404) {
-                throw new SapixNotFoundError(id);
+    write(data) {
+        return this.req("POST", `/v1/agents/${this.name}/records/json`, { data });
+    }
+    /** Alias for `write` — matches Python/Go SDK naming. */
+    writeJson(data) {
+        return this.write(data);
+    }
+    // ── Reads ───────────────────────────────────────────────────────────────────
+    /**
+     * Fetch a single record by its BLAKE3 content hash.
+     * Use `record.content_hash` from a previous write or query.
+     */
+    get(contentHash) {
+        return this.req("GET", `/v1/agents/${this.name}/records/${contentHash}`);
+    }
+    /**
+     * Return the most recent records, newest-first.
+     *
+     * Pass `filter: { field: value }` to run an equality scan (uses a field
+     * index when one is available for that field, otherwise a full strand scan).
+     */
+    latest(opts = {}) {
+        if (opts.filter) {
+            const [field, value] = Object.entries(opts.filter)[0] ?? [];
+            if (field !== undefined) {
+                return this.req("POST", `/v1/agents/${this.name}/query`, {
+                    type: "scan",
+                    limit: opts.limit ?? 20,
+                    filter: { field, op: "eq", value },
+                });
             }
-            throw err;
         }
+        return this.req("POST", `/v1/agents/${this.name}/query`, {
+            type: "latest",
+            limit: opts.limit ?? 20,
+        });
     }
-    /** Query the latest version of all records in this collection. */
-    async latest(options = {}) {
-        return new CollectionQuery(this.config, this.name).latest(options);
-    }
-    /** Query ALL versions (full history) in this collection. */
-    async history(options = {}) {
-        return new CollectionQuery(this.config, this.name).all(options);
+    /**
+     * Return records in chronological order (oldest-first) with pagination.
+     * Uses `GET /v1/agents/{name}/strand/records`.
+     */
+    history(opts = {}) {
+        const params = new URLSearchParams();
+        if (opts.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts.offset !== undefined)
+            params.set("offset", String(opts.offset));
+        const qs = params.size > 0 ? `?${params}` : "";
+        return this.req("GET", `/v1/agents/${this.name}/strand/records${qs}`);
     }
-    /** Find records matching a filter (latest version only). */
-    async find(filter, options = {}) {
-        return new CollectionQuery(this.config, this.name).find(filter, options);
+    /**
+     * Equality-filter scan across the full strand.
+     * `filter` is a `{field: value}` object — first key is used.
+     *
+     * Uses a field index when one exists for that field; otherwise falls back
+     * to a full strand scan on the server.
+     */
+    find(filter, opts = {}) {
+        const [field, value] = Object.entries(filter)[0] ?? [];
+        const whereFilter = field
+            ? { field, op: "eq", value }
+            : undefined;
+        return this.req("POST", `/v1/agents/${this.name}/query`, {
+            type: "scan",
+            limit: opts.limit ?? 20,
+            ...(whereFilter ? { filter: whereFilter } : {}),
+        });
     }
-    /** Find one record or return null. */
+    /** Return the first matching record, or `null` if none. */
     async findOne(filter) {
-        return new CollectionQuery(this.config, this.name).findOne(filter);
+        const result = await this.find(filter, { limit: 1 });
+        return result.records[0] ?? null;
+    }
+    /** Execute any SaQL query directly against this agent. */
+    query(q) {
+        return this.req("POST", `/v1/agents/${this.name}/query`, q);
+    }
+    /** Current chain head hash and record count. */
+    head() {
+        return this.req("GET", `/v1/agents/${this.name}/strand/head`);
+    }
+    /** Agent status: record count, chain head, zone, schema version, caged state. */
+    status() {
+        return this.req("GET", `/v1/agents/${this.name}/status`);
+    }
+    // ── Soft delete ─────────────────────────────────────────────────────────────
+    /**
+     * 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)`.
+     */
+    softDelete(contentHash) {
+        return this.req("DELETE", `/v1/agents/${this.name}/records/${contentHash}`);
+    }
+    /** List all soft-deleted (tombstoned) records for this agent. */
+    listDeleted() {
+        return this.req("GET", `/v1/agents/${this.name}/records/deleted`);
+    }
+    /** Restore a previously soft-deleted record. */
+    restore(contentHash) {
+        return this.req("POST", `/v1/agents/${this.name}/records/${contentHash}/restore`);
+    }
+    // ── Time travel ─────────────────────────────────────────────────────────────
+    /**
+     * Scope reads to a point in time identified by an HLC timestamp.
+     * Returns a `CollectionSnapshot` — call `.latest()` or `.find()` on it.
+     *
+     * @param timestampHlc — `NucleotideRecord.timestamp_hlc` from any prior record
+     *
+     * @example
+     * const snapshot = orders.asOf(record.timestamp_hlc);
+     * const state    = await snapshot.latest({ limit: 50 });
+     */
+    asOf(timestampHlc) {
+        return new CollectionSnapshot(this.name, timestampHlc, this.req);
     }
 }
 //# sourceMappingURL=collection.js.map

package/dist/collection.js.map

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

package/dist/errors.d.ts

@@ -1,12 +1,30 @@
 export declare class SapixError extends Error {
     readonly status?: number | undefined;
-    readonly code?: string | undefined;
-    constructor(message: string, status?: number | undefined, code?: string | undefined);
+    readonly body?: string | undefined;
+    constructor(message: string, status?: number | undefined, body?: string | undefined);
+    static fromResponse(resp: Response): Promise<SapixError>;
 }
-export declare class SapixNetworkError extends SapixError {
-    constructor(cause: unknown);
-}
-export declare class SapixNotFoundError extends SapixError {
-    constructor(id: string);
+/**
+ * Thrown when an API key exceeds its configured requests-per-second limit (HTTP 429).
+ *
+ * @example
+ * import { SapixRateLimitError } from "@sapixdb/client";
+ *
+ * try {
+ *   await orders.write(data);
+ * } catch (err) {
+ *   if (err instanceof SapixRateLimitError) {
+ *     const delay = err.rpsLimit ? 1000 / err.rpsLimit : 1000;
+ *     await new Promise(r => setTimeout(r, delay));
+ *     await orders.write(data);  // retry once
+ *   } else throw err;
+ * }
+ */
+export declare class SapixRateLimitError extends SapixError {
+    /** The key's configured limit in requests/second, parsed from the server message. */
+    readonly rpsLimit?: number | undefined;
+    constructor(message: string, 
+    /** The key's configured limit in requests/second, parsed from the server message. */
+    rpsLimit?: number | undefined);
 }
 //# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -1 +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"}
+{"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;WAMlB,YAAY,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC;CA0B/D;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,mBAAoB,SAAQ,UAAU;IAG/C,qFAAqF;aACrE,QAAQ,CAAC,EAAE,MAAM;gBAFjC,OAAO,EAAE,MAAM;IACf,qFAAqF;IACrE,QAAQ,CAAC,EAAE,MAAM,YAAA;CAKpC"}

package/dist/errors.js

@@ -1,21 +1,60 @@
 export class SapixError extends Error {
-    constructor(message, status, code) {
+    status;
+    body;
+    constructor(message, status, body) {
         super(message);
         this.status = status;
-        this.code = code;
+        this.body = body;
         this.name = "SapixError";
     }
-}
-export class SapixNetworkError extends SapixError {
-    constructor(cause) {
-        super(`Network error: ${cause instanceof Error ? cause.message : String(cause)}`);
-        this.name = "SapixNetworkError";
+    static async fromResponse(resp) {
+        let body;
+        try {
+            body = await resp.text();
+        }
+        catch {
+            body = "<unreadable>";
+        }
+        if (resp.status === 429) {
+            let message = "rate limit exceeded";
+            let rpsLimit;
+            try {
+                const data = JSON.parse(body);
+                message = data.message ?? data.error ?? message;
+                const m = message.match(/rate limit of (\d+) req\/s/);
+                if (m)
+                    rpsLimit = Number(m[1]);
+            }
+            catch { /* body was not JSON */ }
+            return new SapixRateLimitError(message, rpsLimit);
+        }
+        return new SapixError(`sapix-agent returned ${resp.status} ${resp.statusText}: ${body}`, resp.status, body);
     }
 }
-export class SapixNotFoundError extends SapixError {
-    constructor(id) {
-        super(`Record not found: ${id}`, 404, "NOT_FOUND");
-        this.name = "SapixNotFoundError";
+/**
+ * Thrown when an API key exceeds its configured requests-per-second limit (HTTP 429).
+ *
+ * @example
+ * import { SapixRateLimitError } from "@sapixdb/client";
+ *
+ * try {
+ *   await orders.write(data);
+ * } catch (err) {
+ *   if (err instanceof SapixRateLimitError) {
+ *     const delay = err.rpsLimit ? 1000 / err.rpsLimit : 1000;
+ *     await new Promise(r => setTimeout(r, delay));
+ *     await orders.write(data);  // retry once
+ *   } else throw err;
+ * }
+ */
+export class SapixRateLimitError extends SapixError {
+    rpsLimit;
+    constructor(message, 
+    /** The key's configured limit in requests/second, parsed from the server message. */
+    rpsLimit) {
+        super(message, 429);
+        this.rpsLimit = rpsLimit;
+        this.name = "SapixRateLimitError";
     }
 }
 //# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -1 +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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,UAAW,SAAQ,KAAK;IAGjB;IACA;IAHlB,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;IAED,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,IAAc;QACtC,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,GAAG,cAAc,CAAC;QACxB,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACxB,IAAI,OAAO,GAAG,qBAAqB,CAAC;YACpC,IAAI,QAA4B,CAAC;YACjC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAyC,CAAC;gBACtE,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC;gBAChD,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,4BAA4B,CAAC,CAAC;gBACtD,IAAI,CAAC;oBAAE,QAAQ,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC,CAAC,uBAAuB,CAAC,CAAC;YACnC,OAAO,IAAI,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACpD,CAAC;QAED,OAAO,IAAI,UAAU,CACnB,wBAAwB,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,UAAU,KAAK,IAAI,EAAE,EACjE,IAAI,CAAC,MAAM,EACX,IAAI,CACL,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,mBAAoB,SAAQ,UAAU;IAI/B;IAHlB,YACE,OAAe;IACf,qFAAqF;IACrE,QAAiB;QAEjC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;QAFJ,aAAQ,GAAR,QAAQ,CAAS;QAGjC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF"}