@0xdivyanshh/tab-sdk 0.1.0

package/README.md

@@ -0,0 +1,54 @@
+# @0xdivyanshh/tab-sdk
+
+**Tier 3 · PUBLISHED to npm · thin HTTP client · browser-safe**
+
+The TypeScript client every other surface is built on: `agentkit-plugin`, `mcp`, `cli`,
+`dashboard`, and both demo agents.
+
+## Thin on purpose
+
+`boundaries.json` forbids `@hiero-ledger/sdk`, `ioredis` and `drizzle-orm` here. This package
+speaks HTTP to the gateway and nothing else.
+
+That constraint carries the product claim. The agent holds no key and signs nothing — so the
+library it installs should not even be *able* to sign. If the SDK bundled the Hedera SDK, the
+claim would rest on us not having used it. This way it rests on a check anyone can run.
+
+Browser-safe matters too: `apps/web` imports this, and a browser bundle must not be able to
+reach a signing path or a database driver.
+
+## Surface
+
+`spend` · `quote` · `balance` · `ceiling` · `receipts` · `register`
+
+The same five verbs appear in the Agent Kit plugin and the MCP server. Define them once here.
+
+## Contents
+
+| File | Holds |
+|---|---|
+| `src/client.ts` | constructor, auth, retry, timeouts |
+| `src/spend.ts` | the spend call, including the refusal shape |
+| `src/quote.ts` | pre-flight quote without reserving |
+| `src/state.ts` | balance, ceiling, available, pending holds, window countdown |
+| `src/receipts.ts` | receipt history and the SSE stream the dashboard consumes |
+| `src/errors.ts` | typed errors — refusal, unavailable, invalid |
+| `src/types.ts` | re-exported from `@0xdivyanshh/tab-protocol`. One definition, not two |
+
+## Invariants
+
+- **A refusal is a value, not an exception.** `spend()` returns a discriminated result carrying
+  the rule that fired. Throwing on refusal pushes every consumer into `try/catch` and makes the
+  Refusals view harder to build — and refusal is the demo, so it deserves a first-class type.
+  Throw only for transport and protocol failures.
+- **Amounts cross the wire as decimal strings**, parsed to `MicroUsdc` on the way in. `bigint`
+  does not survive `JSON.stringify`.
+- **Types are re-exported from `@0xdivyanshh/tab-protocol`, never redefined.** A second copy will drift.
+- **Retries are safe.** `spend` carries an idempotency key so a network retry cannot double-spend.
+- **No key material in the constructor.** If the SDK ever accepts a private key, the whole claim
+  is gone.
+
+## Publishing
+
+Versioned with changesets. Once an agent depends on this, breaking changes cost someone a
+redeploy — so treat exports as a contract from the first release.

package/dist/client.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The HTTP client.
+ *
+ * Thin on purpose. `boundaries.json` forbids `@hiero-ledger/sdk`, `ioredis` and
+ * `drizzle-orm` here, and that constraint carries the product claim: the agent
+ * holds no key and signs nothing, so the library it installs should not even be
+ * ABLE to sign. If this bundled the Hedera SDK the claim would rest on us not
+ * having used it; this way it rests on a check anyone can run.
+ *
+ * Browser-safe for the same reason — `apps/web` imports this, and a browser
+ * bundle must not be able to reach a signing path or a database driver.
+ */
+export interface TabClientConfig {
+    /** The gateway's base URL. */
+    baseUrl: string;
+    /**
+     * Bearer token, if the deployment requires one.
+     *
+     * NOT a private key, and there is deliberately no way to pass one. If this
+     * constructor ever accepts key material the whole claim is gone.
+     */
+    token?: string;
+    /** Per-request timeout. Default 120s — a spend waits on x402 settlement. */
+    timeoutMs?: number;
+    /** Retries for transport failures only. Default 2. */
+    maxRetries?: number;
+    /** Injectable for tests and for runtimes with a non-global fetch. */
+    fetch?: typeof globalThis.fetch;
+}
+export declare class TabClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly doFetch;
+    constructor(config: TabClientConfig);
+    /**
+     * One request, with retries for transport failures only.
+     *
+     * A 4xx or 5xx is NOT retried. The gateway answered — retrying an answer we
+     * did not like is how a refused spend becomes six refused spends, and how a
+     * 500 mid-settlement becomes a double payment. Only a thrown fetch (DNS,
+     * connection reset, timeout) is retried, and only because in that case the
+     * caller has no answer at all.
+     */
+    request<T>(method: 'GET' | 'POST', path: string, body?: unknown): Promise<T>;
+}
+//# 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":"AAEA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CAChC;AAeD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAQ;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;gBAErC,MAAM,EAAE,eAAe;IA4BnC;;;;;;;;OAQG;IACG,OAAO,CAAC,CAAC,EAAE,MAAM,EAAE,KAAK,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;CA+FnF"}

package/dist/client.js

@@ -0,0 +1,140 @@
+import { TabProtocolError, TabUnavailableError } from "./errors.js";
+const DEFAULTS = {
+    /*
+     * 120 seconds, which looks absurd for an HTTP client and is not.
+     *
+     * A spend waits on an x402 HTS settlement, measured at 25-39s end to end,
+     * plus a hold write awaiting consensus. A 30s default would time out on
+     * perfectly healthy spends and the caller would retry — against a gateway
+     * that had already taken the hold.
+     */
+    timeoutMs: 120_000,
+    maxRetries: 2,
+};
+export class TabClient {
+    baseUrl;
+    token;
+    timeoutMs;
+    maxRetries;
+    doFetch;
+    constructor(config) {
+        // Trailing slash removed once, here, so every path can be written `/v1/...`
+        // without a caller having to know whether it will be doubled.
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        if (config.token)
+            this.token = config.token;
+        this.timeoutMs = config.timeoutMs ?? DEFAULTS.timeoutMs;
+        this.maxRetries = config.maxRetries ?? DEFAULTS.maxRetries;
+        /*
+         * BOUND to globalThis, and that bind is load-bearing in a browser.
+         *
+         * `fetch` is a method on Window, and the spec requires it to be called with
+         * a Window receiver. Stored bare and invoked as `this.doFetch(...)`, the
+         * receiver becomes this client instance and the browser throws
+         *
+         *   TypeError: Failed to execute 'fetch' on 'Window': Illegal invocation
+         *
+         * before a single byte leaves the machine. Node's fetch has no such
+         * requirement, so every test here and every server-side caller passed while
+         * the console failed on EVERY request — and failed as a transport error,
+         * which reads exactly like an unreachable gateway. It cost hours of
+         * chasing CORS and cold starts that were never involved.
+         *
+         * An INJECTED fetch is used as given: it is the caller's function and
+         * binding it to globalThis would be us rewriting their receiver.
+         */
+        this.doFetch = config.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * One request, with retries for transport failures only.
+     *
+     * A 4xx or 5xx is NOT retried. The gateway answered — retrying an answer we
+     * did not like is how a refused spend becomes six refused spends, and how a
+     * 500 mid-settlement becomes a double payment. Only a thrown fetch (DNS,
+     * connection reset, timeout) is retried, and only because in that case the
+     * caller has no answer at all.
+     */
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        let lastError;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            try {
+                const response = await this.doFetch(url, {
+                    method,
+                    headers: {
+                        'content-type': 'application/json',
+                        ...(this.token ? { authorization: `Bearer ${this.token}` } : {}),
+                    },
+                    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                    signal: controller.signal,
+                });
+                const text = await response.text();
+                let parsed;
+                try {
+                    parsed = text.length > 0 ? JSON.parse(text) : null;
+                }
+                catch {
+                    throw new TabProtocolError(`The gateway returned ${response.status} with a body that is not JSON`, response.status, text.slice(0, 512));
+                }
+                /*
+                 * A REFUSAL comes back 200 with `{ refused: ... }`, so it lands here as
+                 * a normal response and the caller gets a value. A non-2xx really is a
+                 * protocol failure — the gateway could not answer the question.
+                 */
+                if (!response.ok) {
+                    throw new TabProtocolError(`The gateway returned ${response.status}`, response.status, parsed);
+                }
+                return parsed;
+            }
+            catch (error) {
+                if (error instanceof TabProtocolError)
+                    throw error;
+                lastError = error;
+                // Backoff only between attempts, never after the last one.
+                if (attempt < this.maxRetries) {
+                    await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
+                }
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        }
+        /*
+         * The outcome is UNKNOWN, and saying so is the whole point of this message.
+         *
+         * The first draft said "nothing was spent", which is false and dangerously
+         * reassuring: a timeout can mean the gateway took the hold, paid the seller,
+         * and the RESPONSE was lost. A client that tells a caller it is safe to
+         * retry blindly is how one spend becomes two.
+         *
+         * The idempotency key is what makes a retry safe, so the caller is told to
+         * reuse it rather than told not to worry.
+         */
+        /*
+         * The CAUSE is named in the message, not only attached as `cause`.
+         *
+         * "Could not reach the gateway" is true of a CORS rejection, a DNS
+         * failure, a refused connection and a timeout alike — and those have
+         * completely different fixes. The distinguishing detail was being carried
+         * on a property nothing displays, so a console showing this error sent us
+         * hunting the wrong problem more than once.
+         *
+         * An AbortError here is always OUR timeout firing, so it is named as one:
+         * "aborted" reads like a cancelled request and hides the fact that a
+         * deadline was exceeded.
+         */
+        const because = lastError instanceof Error
+            ? lastError.name === 'AbortError' || lastError.name === 'TimeoutError'
+                ? `timed out after ${this.timeoutMs}ms`
+                : `${lastError.name}: ${lastError.message}`
+            : String(lastError);
+        throw new TabUnavailableError(`Could not reach the Tab gateway at ${url} after ${this.maxRetries + 1} attempt(s) ` +
+            `(${because}). ` +
+            'The outcome is UNKNOWN — a transport failure cannot distinguish "never arrived" from ' +
+            '"succeeded and the response was lost". Retry with the SAME idempotencyKey: the gateway ' +
+            'treats it as the hold id, so a repeat cannot double-spend. Do not retry with a new key.', lastError);
+    }
+}
+//# 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/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed errors — and the one thing that is deliberately NOT an error.
+ *
+ * **A refusal is a value, not an exception.** `spend()` returns a discriminated
+ * result carrying the rule that fired. Throwing on refusal would push every
+ * consumer into `try/catch`, and refusal is the product demonstrating that
+ * underwriting works — it deserves a first-class type, not a control-flow
+ * escape.
+ *
+ * These throw only for transport and protocol failures: the gateway was
+ * unreachable, or it answered something this client cannot interpret.
+ */
+/** The gateway could not be reached, or did not answer in time. */
+export declare class TabUnavailableError extends Error {
+    readonly kind: "unavailable";
+    readonly reason: unknown;
+    constructor(message: string, reason?: unknown);
+}
+/**
+ * The gateway answered, but not with something this client understands.
+ *
+ * Carries the status and the raw body. A caller debugging a version mismatch
+ * needs to see what actually came back — "invalid response" with the evidence
+ * discarded is the least useful error a client can raise.
+ */
+export declare class TabProtocolError extends Error {
+    readonly kind: "protocol";
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/** A caller mistake — a malformed amount, a missing tab id. */
+export declare class TabInvalidError extends Error {
+    readonly kind: "invalid";
+    constructor(message: string);
+}
+export type TabError = TabUnavailableError | TabProtocolError | TabInvalidError;
+export declare function isTabError(error: unknown): error is TabError;
+//# 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;;;;;;;;;;;GAWG;AAEH,mEAAmE;AACnE,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAG,aAAa,CAAS;IAStC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;gBACZ,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO;CAK9C;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAS;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;gBACV,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO;CAM3D;AAED,+DAA+D;AAC/D,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,IAAI,EAAG,SAAS,CAAS;gBACtB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,MAAM,QAAQ,GAAG,mBAAmB,GAAG,gBAAgB,GAAG,eAAe,CAAA;AAE/E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAM5D"}

package/dist/errors.js

@@ -0,0 +1,62 @@
+/**
+ * Typed errors — and the one thing that is deliberately NOT an error.
+ *
+ * **A refusal is a value, not an exception.** `spend()` returns a discriminated
+ * result carrying the rule that fired. Throwing on refusal would push every
+ * consumer into `try/catch`, and refusal is the product demonstrating that
+ * underwriting works — it deserves a first-class type, not a control-flow
+ * escape.
+ *
+ * These throw only for transport and protocol failures: the gateway was
+ * unreachable, or it answered something this client cannot interpret.
+ */
+/** The gateway could not be reached, or did not answer in time. */
+export class TabUnavailableError extends Error {
+    kind = 'unavailable';
+    /*
+     * Fields declared and assigned, not TS parameter properties.
+     *
+     * `erasableSyntaxOnly` is on across the repo so Node can run the TypeScript
+     * directly with `--experimental-strip-types`, and parameter properties are
+     * not erasable — they generate assignments. The constraint is repo-wide; see
+     * HANDOFF.
+     */
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.name = 'TabUnavailableError';
+        this.reason = reason;
+    }
+}
+/**
+ * The gateway answered, but not with something this client understands.
+ *
+ * Carries the status and the raw body. A caller debugging a version mismatch
+ * needs to see what actually came back — "invalid response" with the evidence
+ * discarded is the least useful error a client can raise.
+ */
+export class TabProtocolError extends Error {
+    kind = 'protocol';
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = 'TabProtocolError';
+        this.status = status;
+        this.body = body;
+    }
+}
+/** A caller mistake — a malformed amount, a missing tab id. */
+export class TabInvalidError extends Error {
+    kind = 'invalid';
+    constructor(message) {
+        super(message);
+        this.name = 'TabInvalidError';
+    }
+}
+export function isTabError(error) {
+    return (error instanceof TabUnavailableError ||
+        error instanceof TabProtocolError ||
+        error instanceof TabInvalidError);
+}
+//# 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;;;;;;;;;;;GAWG;AAEH,mEAAmE;AACnE,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,GAAG,aAAsB,CAAA;IACtC;;;;;;;OAOG;IACM,MAAM,CAAS;IACxB,YAAY,OAAe,EAAE,MAAgB;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAChC,IAAI,GAAG,UAAmB,CAAA;IAC1B,MAAM,CAAQ;IACd,IAAI,CAAS;IACtB,YAAY,OAAe,EAAE,MAAc,EAAE,IAAa;QACxD,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAA;QAC9B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,IAAI,GAAG,SAAkB,CAAA;IAClC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAA;QACd,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;IAC/B,CAAC;CACF;AAID,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,CACL,KAAK,YAAY,mBAAmB;QACpC,KAAK,YAAY,gBAAgB;QACjC,KAAK,YAAY,eAAe,CACjC,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @0xdivyanshh/tab-sdk — the client every other surface is built on.
+ *
+ * Tier 3. Published, thin, browser-safe. `boundaries.json` forbids
+ * `@hiero-ledger/sdk`, `ioredis` and `drizzle-orm` here, and that constraint
+ * carries the product claim: the agent holds no key and signs nothing, so the
+ * library it installs should not even be ABLE to sign.
+ *
+ * ```ts
+ * const tab = createTab({ baseUrl: 'http://localhost:8080' })
+ * const result = await tab.spend({ tab: '0.0.x', url: seller, max: usdc('0.040000') })
+ * if (result.outcome === 'refused') console.log(result.rule, result.guidance)
+ * ```
+ *
+ * **A refusal is a value, not an exception.** That is the one thing to know
+ * before using this.
+ */
+import type { MicroUsdc } from '@0xdivyanshh/tab-money';
+import { type TabClientConfig } from './client.ts';
+import { health } from './receipts.ts';
+import type { CeilingView, CounterpartyWeight, Hold, Quote, ReceiptRow, SettlementView, SpendRequest, SpendResult, TabList, TabState } from './types.ts';
+export interface Tab {
+    spend(request: SpendRequest): Promise<SpendResult>;
+    quote(params: {
+        tab: string;
+        max: MicroUsdc;
+    }): Promise<Quote>;
+    state(tab: string): Promise<TabState>;
+    holds(tab: string): Promise<Hold[]>;
+    receipts(tab: string): Promise<ReceiptRow[]>;
+    counterparties(tab: string): Promise<CounterpartyWeight[]>;
+    /** The ceiling in force, its arithmetic, and the series behind it. */
+    ceiling(tab: string): Promise<CeilingView>;
+    /** Settled windows, ascending by window. */
+    settlements(tab: string): Promise<SettlementView[]>;
+    /** The tabs this gateway knows about. NOT a registry — see `TabList`. */
+    tabs(): Promise<TabList>;
+    health(): Promise<Awaited<ReturnType<typeof health>>>;
+}
+/**
+ * The ten verbs, bound to one client.
+ *
+ * Object-with-methods rather than loose functions because the same surface
+ * appears in the Agent Kit plugin, the MCP server and the CLI — defining it
+ * once, here, is what stops those three drifting apart.
+ *
+ * Two of the ten (`spend`, `quote`) act. The other eight only read, and every
+ * one of them reads what was PUBLISHED rather than recomputing it: this package
+ * cannot import `@0xdivyanshh/tab-scoring` or `@0xdivyanshh/tab-graph`, so it is structurally incapable
+ * of offering a second opinion about a ceiling or a weight. That is the point.
+ */
+export declare function createTab(config: TabClientConfig): Tab;
+export type { WeightReason } from '@0xdivyanshh/tab-protocol';
+export { TabClient, type TabClientConfig } from './client.ts';
+export { isTabError, type TabError, TabInvalidError, TabProtocolError, TabUnavailableError, } from './errors.ts';
+export { ceiling, counterparties, health, holds, receipts, settlements, tabs } from './receipts.ts';
+export { parseAmount, quote, spend, state } from './spend.ts';
+export type { CeilingInputsView, CeilingView, CounterpartyWeight, Hold, PublishedCeilingView, Quote, ReceiptLeg, ReceiptRow, RefusalCode, SettlementView, SpendFailed, SpendPaid, SpendRefused, SpendRequest, SpendResult, TabList, TabState, TabSummary, } from './types.ts';
+export { BLOCKING_REASONS, isBlocking, isRetryable, REFUSAL_CODES, REFUSAL_GUIDANCE, WEIGHT_REASON_DETAIL, WEIGHT_REASONS, } from './types.ts';
+//# 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;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAC3C,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAA2B,MAAM,EAAsC,MAAM,eAAe,CAAA;AAEnG,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,IAAI,EACJ,KAAK,EACL,UAAU,EACV,cAAc,EACd,YAAY,EACZ,WAAW,EACX,OAAO,EACP,QAAQ,EACT,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,GAAG;IAClB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAClD,KAAK,CAAC,MAAM,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,SAAS,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAC9D,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;IACrC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAAA;IACnC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAAA;IAC5C,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAA;IAC1D,sEAAsE;IACtE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;IAC1C,4CAA4C;IAC5C,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAA;IACnD,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB,MAAM,IAAI,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,OAAO,MAAM,CAAC,CAAC,CAAC,CAAA;CACtD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,eAAe,GAAG,GAAG,CActD;AAID,YAAY,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EACL,UAAU,EACV,KAAK,QAAQ,EACb,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACnG,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAC7D,YAAY,EACV,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,IAAI,EACJ,oBAAoB,EACpB,KAAK,EACL,UAAU,EACV,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACX,SAAS,EACT,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,OAAO,EACP,QAAQ,EACR,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * @0xdivyanshh/tab-sdk — the client every other surface is built on.
+ *
+ * Tier 3. Published, thin, browser-safe. `boundaries.json` forbids
+ * `@hiero-ledger/sdk`, `ioredis` and `drizzle-orm` here, and that constraint
+ * carries the product claim: the agent holds no key and signs nothing, so the
+ * library it installs should not even be ABLE to sign.
+ *
+ * ```ts
+ * const tab = createTab({ baseUrl: 'http://localhost:8080' })
+ * const result = await tab.spend({ tab: '0.0.x', url: seller, max: usdc('0.040000') })
+ * if (result.outcome === 'refused') console.log(result.rule, result.guidance)
+ * ```
+ *
+ * **A refusal is a value, not an exception.** That is the one thing to know
+ * before using this.
+ */
+import { TabClient } from "./client.js";
+import { ceiling, counterparties, health, holds, receipts, settlements, tabs } from "./receipts.js";
+import { quote, spend, state } from "./spend.js";
+/**
+ * The ten verbs, bound to one client.
+ *
+ * Object-with-methods rather than loose functions because the same surface
+ * appears in the Agent Kit plugin, the MCP server and the CLI — defining it
+ * once, here, is what stops those three drifting apart.
+ *
+ * Two of the ten (`spend`, `quote`) act. The other eight only read, and every
+ * one of them reads what was PUBLISHED rather than recomputing it: this package
+ * cannot import `@0xdivyanshh/tab-scoring` or `@0xdivyanshh/tab-graph`, so it is structurally incapable
+ * of offering a second opinion about a ceiling or a weight. That is the point.
+ */
+export function createTab(config) {
+    const client = new TabClient(config);
+    return {
+        spend: (request) => spend(client, request),
+        quote: (params) => quote(client, params),
+        state: (tab) => state(client, tab),
+        holds: (tab) => holds(client, tab),
+        receipts: (tab) => receipts(client, tab),
+        counterparties: (tab) => counterparties(client, tab),
+        ceiling: (tab) => ceiling(client, tab),
+        settlements: (tab) => settlements(client, tab),
+        tabs: () => tabs(client),
+        health: () => health(client),
+    };
+}
+export { TabClient } from "./client.js";
+export { isTabError, TabInvalidError, TabProtocolError, TabUnavailableError, } from "./errors.js";
+export { ceiling, counterparties, health, holds, receipts, settlements, tabs } from "./receipts.js";
+export { parseAmount, quote, spend, state } from "./spend.js";
+export { BLOCKING_REASONS, isBlocking, isRetryable, REFUSAL_CODES, REFUSAL_GUIDANCE, WEIGHT_REASON_DETAIL, WEIGHT_REASONS, } from "./types.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;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,SAAS,EAAwB,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACnG,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AA8BhD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,SAAS,CAAC,MAAuB;IAC/C,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,MAAM,CAAC,CAAA;IACpC,OAAO;QACL,KAAK,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC;QAC1C,KAAK,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC;QACxC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC;QAClC,KAAK,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,CAAC;QAClC,QAAQ,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;QACxC,cAAc,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC;QACpD,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;QACtC,WAAW,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,MAAM,EAAE,GAAG,CAAC;QAC9C,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC;QACxB,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;KAC7B,CAAA;AACH,CAAC;AAKD,OAAO,EAAE,SAAS,EAAwB,MAAM,aAAa,CAAA;AAC7D,OAAO,EACL,UAAU,EAEV,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AACpB,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,eAAe,CAAA;AACnG,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAqB7D,OAAO,EACL,gBAAgB,EAChB,UAAU,EACV,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,GACf,MAAM,YAAY,CAAA"}

package/dist/receipts.d.ts

@@ -0,0 +1,81 @@
+import type { TabClient } from './client.ts';
+import type { CeilingView, CounterpartyWeight, Hold, ReceiptRow, SettlementView, TabList } from './types.ts';
+/**
+ * Receipt history and pending holds.
+ *
+ * Both read the gateway's projection rather than HCS directly, because this
+ * package must stay browser-safe and a browser has no business walking a topic.
+ * A consumer that wants to verify rather than display should run
+ * `pnpm verify-tab`, which replays the topic itself and trusts nothing we say.
+ */
+export declare function holds(client: TabClient, tab: string): Promise<Hold[]>;
+export declare function receipts(client: TabClient, tab: string): Promise<ReceiptRow[]>;
+/** Is the gateway up, and which network and window is it on? */
+export declare function health(client: TabClient): Promise<{
+    ok: boolean;
+    network: string;
+    token: string;
+    window: number;
+    demoMode: boolean;
+    /**
+     * The HCS topics this gateway is actually reading.
+     *
+     * Served so a reader can go and check for themselves, and taken from the
+     * gateway rather than from the consumer's own config so the two cannot
+     * disagree — a "view on HashScan" link that points somewhere other than the
+     * data it sits beside is worse than no link.
+     *
+     * Absent from an older gateway that did not serve them, in which case a
+     * caller should show no link rather than guess at one.
+     */
+    topics?: {
+        receipts: string;
+        ceilings: string;
+        settlements: string;
+    };
+}>;
+/**
+ * Published independence weights for a tab's counterparties.
+ *
+ * Reason codes are VALIDATED against `WEIGHT_REASONS`, not cast — an unknown
+ * reason from a newer server is dropped rather than typed as a real one, for
+ * the same reason an unknown refusal code is: the console would otherwise
+ * render a rule that does not exist, and `isBlocking` would answer confidently
+ * about it.
+ */
+export declare function counterparties(client: TabClient, tab: string): Promise<CounterpartyWeight[]>;
+/**
+ * The ceiling in force, its arithmetic, and the series behind it.
+ *
+ * Read from what the ENGINE published, never recomputed — the SDK is
+ * browser-safe and cannot import `@0xdivyanshh/tab-scoring`, and that is the right
+ * constraint. A client that recomputed the ceiling would hand a viewer a second
+ * answer to compare against the topic, and two answers is worse than one even
+ * when they agree.
+ *
+ * `published: false` is not an error. It means the engine has not run for this
+ * tab yet and the starter ceiling is in force — `enforced` says what that is.
+ */
+export declare function ceiling(client: TabClient, tab: string): Promise<CeilingView>;
+/**
+ * Settled windows, ascending by window.
+ *
+ * Ordered by WINDOW rather than by arrival: a repaired or late settlement lands
+ * on the topic after the windows that follow it, and a table sorted by
+ * timestamp would put window 41 above window 39 with no explanation.
+ *
+ * The gross legs come through as absent when the topic did not carry them. A
+ * caller must render that as "not published", never as zero.
+ */
+export declare function settlements(client: TabClient, tab: string): Promise<SettlementView[]>;
+/**
+ * The tabs this gateway knows about.
+ *
+ * Named `tabs`, not `registry`, and the response carries
+ * `registrationEnforced: false` so a caller cannot mistake it for one. Nothing
+ * writes a `register` message yet — one Starter Tab per funding root is
+ * unenforced and the README labels it OPEN — so a tab appears here the first
+ * time it spends or earns, and there is no registration time to report.
+ */
+export declare function tabs(client: TabClient): Promise<TabList>;
+//# sourceMappingURL=receipts.d.ts.map

package/dist/receipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receipts.d.ts","sourceRoot":"","sources":["../src/receipts.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAG5C,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,IAAI,EAEJ,UAAU,EACV,cAAc,EACd,OAAO,EAER,MAAM,YAAY,CAAA;AAenB;;;;;;;GAOG;AAEH,wBAAsB,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,CAW3E;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CA+BpF;AAED,gEAAgE;AAChE,wBAAsB,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IACvD,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,OAAO,CAAA;IACjB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CACrE,CAAC,CAmBD;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,SAAS,EACjB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,kBAAkB,EAAE,CAAC,CA0C/B;AAqDD;;;;;;;;;;;GAWG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAkBlF;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CA6B3F;AAED;;;;;;;;GAQG;AACH,wBAAsB,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,CA8C9D"}