@0xdivyanshh/tab-sdk 0.1.0

package/dist/receipts.js

@@ -0,0 +1,309 @@
+import { REFUSAL_CODES, WEIGHT_REASONS } from '@0xdivyanshh/tab-protocol';
+import { TabInvalidError } from "./errors.js";
+import { parseAmount } from "./spend.js";
+/**
+ * Validated, not cast.
+ *
+ * A cast would type an unknown string as a valid refusal code, and the UI would
+ * then render a rule that does not exist — or worse, `isRetryable` would return
+ * false for it and an agent would stop retrying something it should retry. An
+ * unrecognised rule is dropped, which shows as a refusal with no rule rather
+ * than a refusal with a fictional one.
+ */
+function knownRule(value) {
+    return typeof value === 'string' && REFUSAL_CODES.includes(value);
+}
+/**
+ * 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 async function holds(client, tab) {
+    if (!tab)
+        throw new TabInvalidError('holds() needs a tab id');
+    const rows = await client.request('GET', `/v1/tabs/${tab}/holds`);
+    return rows.map((r) => ({
+        holdId: String(r['holdId']),
+        counterparty: String(r['counterparty']),
+        amount: parseAmount(r['amount'], 'hold.amount'),
+        at: String(r['at']),
+        expiresAt: String(r['expiresAt']),
+        status: r['status'] ?? 'pending',
+    }));
+}
+export async function receipts(client, tab) {
+    if (!tab)
+        throw new TabInvalidError('receipts() needs a tab id');
+    const rows = await client.request('GET', `/v1/tabs/${tab}/entries`);
+    return rows.map((r) => {
+        const leg = String(r['kind']);
+        return {
+            leg,
+            at: String(r['at']),
+            window: Number(r['window'] ?? 0),
+            ...(r['seq'] !== undefined && r['seq'] !== null ? { seq: Number(r['seq']) } : {}),
+            ...(r['requestHash'] ? { requestHash: String(r['requestHash']) } : {}),
+            ...(r['token'] ? { token: String(r['token']) } : {}),
+            ...(r['counterparty'] ? { counterparty: String(r['counterparty']) } : {}),
+            /*
+             * A refusal carries `requested`, not `amount` — it moved no money, and
+             * conflating the two would make the Refusals view show refused intent as
+             * though it were spend. Whichever is present is mapped to `amount` so a
+             * table can render one column, and `leg` tells a reader which it is.
+             */
+            ...(r['amount'] !== undefined && r['amount'] !== null
+                ? { amount: parseAmount(r['amount'], `${leg}.amount`) }
+                : r['requested'] !== undefined && r['requested'] !== null
+                    ? { amount: parseAmount(r['requested'], `${leg}.requested`) }
+                    : {}),
+            ...(typeof r['attested'] === 'boolean' ? { attested: r['attested'] } : {}),
+            ...(r['transactionId'] ? { transactionId: String(r['transactionId']) } : {}),
+            ...(r['holdId'] ? { holdId: String(r['holdId']) } : {}),
+            ...(knownRule(r['rule']) ? { rule: r['rule'] } : {}),
+        };
+    });
+}
+/** Is the gateway up, and which network and window is it on? */
+export async function health(client) {
+    const body = await client.request('GET', '/health');
+    const topics = body['topics'];
+    return {
+        ok: body['ok'] === true,
+        network: String(body['network'] ?? 'unknown'),
+        token: String(body['token'] ?? ''),
+        window: Number(body['window'] ?? 0),
+        demoMode: body['demoMode'] === true,
+        ...(topics?.['receipts'] && topics['ceilings'] && topics['settlements']
+            ? {
+                topics: {
+                    receipts: String(topics['receipts']),
+                    ceilings: String(topics['ceilings']),
+                    settlements: String(topics['settlements']),
+                },
+            }
+            : {}),
+    };
+}
+/**
+ * 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 async function counterparties(client, tab) {
+    if (!tab)
+        throw new TabInvalidError('counterparties() needs a tab id');
+    const rows = await client.request('GET', `/v1/tabs/${tab}/counterparties`);
+    return rows.map((r) => {
+        const raw = Array.isArray(r['reasons']) ? r['reasons'] : [];
+        const reasons = raw.filter(knownReason);
+        return {
+            counterparty: String(r['counterparty']),
+            bp: Number(r['bp'] ?? 0),
+            /*
+             * Never empty, even if every reason was unrecognised.
+             *
+             * A weight with no reason is unreadable in the console, so an unknown
+             * vocabulary degrades to `INDEPENDENT` ONLY when the weight is full —
+             * otherwise it stays empty and the view shows the number without a
+             * fabricated justification for it.
+             */
+            reasons: reasons.length > 0
+                ? reasons
+                : Number(r['bp'] ?? 0) === 10_000
+                    ? ['INDEPENDENT']
+                    : [],
+            blocking: r['blocking'] === true,
+            revenue: parseAmount(r['revenue'], 'counterparty.revenue'),
+            shareBp: Number(r['shareBp'] ?? 0),
+            window: Number(r['window'] ?? 0),
+            at: String(r['at']),
+            ...(r['token'] ? { token: String(r['token']) } : {}),
+            // Absent stays absent — see `CounterpartyWeight` for why defaulting any
+            // of these would fabricate the evidence the panel exists to show.
+            ...(r['firstSeen'] ? { firstSeen: String(r['firstSeen']) } : {}),
+            ...(r['funder'] ? { funder: String(r['funder']) } : {}),
+            ...(r['funderSeq'] !== undefined && r['funderSeq'] !== null
+                ? { funderSeq: Number(r['funderSeq']) }
+                : {}),
+            ...(r['tabFunder'] ? { tabFunder: String(r['tabFunder']) } : {}),
+        };
+    });
+}
+function knownReason(value) {
+    return typeof value === 'string' && WEIGHT_REASONS.includes(value);
+}
+const TIERS = ['A', 'B', 'C', 'Unrated'];
+const OUTCOMES = ['clean', 'missed', 'carried'];
+/** Validated, not cast — an unknown tier would render as a real one. */
+function tierOf(value) {
+    return typeof value === 'string' && TIERS.includes(value)
+        ? value
+        : 'Unrated';
+}
+function outcomeOf(value) {
+    return typeof value === 'string' && OUTCOMES.includes(value)
+        ? value
+        : 'carried';
+}
+function ceilingOf(r) {
+    const inputs = (r['inputs'] ?? {});
+    return {
+        ceiling: parseAmount(r['ceiling'], 'ceiling.ceiling'),
+        ...(r['computed'] !== undefined && r['computed'] !== null
+            ? { computed: parseAmount(r['computed'], 'ceiling.computed') }
+            : {}),
+        window: Number(r['window'] ?? 0),
+        binding: String(r['binding'] ?? 'unknown'),
+        cause: String(r['cause'] ?? 'unknown'),
+        at: String(r['at'] ?? ''),
+        model: String(r['model'] ?? ''),
+        hash: String(r['hash'] ?? ''),
+        ...(r['seq'] !== undefined && r['seq'] !== null ? { seq: Number(r['seq']) } : {}),
+        inputs: {
+            revenue: parseAmount(inputs['revenue'], 'ceiling.inputs.revenue'),
+            revenueAttested: parseAmount(inputs['revenueAttested'], 'ceiling.inputs.revenueAttested'),
+            revenueUnattested: parseAmount(inputs['revenueUnattested'], 'ceiling.inputs.revenueUnattested'),
+            tier: tierOf(inputs['tier']),
+            multBp: Number(inputs['multBp'] ?? 0),
+            rampBp: Number(inputs['rampBp'] ?? 0),
+            cap: parseAmount(inputs['cap'], 'ceiling.inputs.cap'),
+            floor: parseAmount(inputs['floor'], 'ceiling.inputs.floor'),
+            defaulted: inputs['defaulted'] === true,
+        },
+    };
+}
+/**
+ * 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 async function ceiling(client, tab) {
+    if (!tab)
+        throw new TabInvalidError('ceiling() needs a tab id');
+    const body = await client.request('GET', `/v1/tabs/${tab}/ceiling`);
+    const history = (Array.isArray(body['history']) ? body['history'] : []).map((row) => ceilingOf(row));
+    const published = body['published'] === true;
+    return {
+        tab: String(body['tab'] ?? tab),
+        published,
+        enforced: parseAmount(body['enforced'], 'ceiling.enforced'),
+        // `current` is the last history element rather than a separate parse of the
+        // top-level fields, so "the number in force" and "the last point on the
+        // chart" cannot disagree on screen.
+        ...(published && history.length > 0 ? { current: history[history.length - 1] } : {}),
+        history,
+        ...(body['note'] ? { note: String(body['note']) } : {}),
+    };
+}
+/**
+ * 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 async function settlements(client, tab) {
+    if (!tab)
+        throw new TabInvalidError('settlements() needs a tab id');
+    const rows = await client.request('GET', `/v1/tabs/${tab}/settlements`);
+    return rows.map((r) => ({
+        window: Number(r['window'] ?? 0),
+        at: String(r['at'] ?? ''),
+        ...(r['seq'] !== undefined && r['seq'] !== null ? { seq: Number(r['seq']) } : {}),
+        net: parseAmount(r['net'], 'settlement.net'),
+        ...(r['credits'] !== undefined && r['credits'] !== null
+            ? { credits: parseAmount(r['credits'], 'settlement.credits') }
+            : {}),
+        ...(r['debits'] !== undefined && r['debits'] !== null
+            ? { debits: parseAmount(r['debits'], 'settlement.debits') }
+            : {}),
+        ...(r['interest'] !== undefined && r['interest'] !== null
+            ? { interest: parseAmount(r['interest'], 'settlement.interest') }
+            : {}),
+        ...(r['outstanding'] !== undefined && r['outstanding'] !== null
+            ? { outstanding: parseAmount(r['outstanding'], 'settlement.outstanding') }
+            : {}),
+        ...(r['receiptCount'] !== undefined && r['receiptCount'] !== null
+            ? { receiptCount: Number(r['receiptCount']) }
+            : {}),
+        outcome: outcomeOf(r['outcome']),
+        rampFromBp: Number(r['rampFromBp'] ?? 0),
+        rampToBp: Number(r['rampToBp'] ?? 0),
+        ...(r['transactionId'] ? { transactionId: String(r['transactionId']) } : {}),
+        ...(r['token'] ? { token: String(r['token']) } : {}),
+    }));
+}
+/**
+ * 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 async function tabs(client) {
+    const body = await client.request('GET', '/v1/tabs');
+    const rows = Array.isArray(body['tabs']) ? body['tabs'] : [];
+    return {
+        window: Number(body['window'] ?? 0),
+        /*
+         * Defaults to FALSE when the field is absent, never true.
+         *
+         * An older gateway that does not send it has no registration flow either,
+         * so absence means unenforced. Defaulting the permissive way round would
+         * let a stale server silently license the "Registry" heading.
+         */
+        registrationEnforced: body['registrationEnforced'] === true,
+        rootsClaimed: Number(body['rootsClaimed'] ?? 0),
+        note: String(body['note'] ?? ''),
+        tabs: rows.map((raw) => {
+            const r = raw;
+            const summary = {
+                tab: String(r['tab']),
+                balance: parseAmount(r['balance'], 'tab.balance'),
+                outstanding: parseAmount(r['outstanding'], 'tab.outstanding'),
+                holds: parseAmount(r['holds'], 'tab.holds'),
+                available: parseAmount(r['available'], 'tab.available'),
+                ceiling: parseAmount(r['ceiling'], 'tab.ceiling'),
+                entries: Number(r['entries'] ?? 0),
+                // Absent stays absent. An unpublished tab has no tier, which is not the
+                // same as being Unrated.
+                ...(r['tier'] !== undefined && r['tier'] !== null ? { tier: tierOf(r['tier']) } : {}),
+                ...(r['publishedCeiling'] !== undefined && r['publishedCeiling'] !== null
+                    ? { publishedCeiling: parseAmount(r['publishedCeiling'], 'tab.publishedCeiling') }
+                    : {}),
+                ...(r['binding'] ? { binding: String(r['binding']) } : {}),
+                ...(r['cause'] ? { cause: String(r['cause']) } : {}),
+                ...(r['model'] ? { model: String(r['model']) } : {}),
+                ...(r['seq'] !== undefined && r['seq'] !== null ? { seq: Number(r['seq']) } : {}),
+                // Absent stays absent: no claim recorded is not the same as denied.
+                ...(r['registeredRoot'] ? { registeredRoot: String(r['registeredRoot']) } : {}),
+                ...(r['registeredAt'] ? { registeredAt: String(r['registeredAt']) } : {}),
+                ...(r['registrationSeq'] !== undefined && r['registrationSeq'] !== null
+                    ? { registrationSeq: Number(r['registrationSeq']) }
+                    : {}),
+                ...(r['uaid'] ? { uaid: String(r['uaid']) } : {}),
+            };
+            return summary;
+        }),
+    };
+}
+//# sourceMappingURL=receipts.js.map

package/dist/receipts.js.map

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

package/dist/spend.d.ts

@@ -0,0 +1,22 @@
+import { type MicroUsdc } from '@0xdivyanshh/tab-money';
+import type { TabClient } from './client.ts';
+import type { Quote, SpendRequest, SpendResult, TabState } from './types.ts';
+/** Parse a wire amount, with a message that names the field. */
+declare function amount(value: unknown, field: string): MicroUsdc;
+export declare function spend(client: TabClient, request: SpendRequest): Promise<SpendResult>;
+/**
+ * What could this tab afford right now, without reserving anything.
+ *
+ * Derived from `state()` rather than a dedicated endpoint, and deliberately so:
+ * a quote that took a hold would leave a hold that never commits, which is
+ * exactly the shape the reconciler exists to clean up. This reserves nothing
+ * and therefore guarantees nothing — between a quote and a spend, another call
+ * on the same tab can take the headroom.
+ */
+export declare function quote(client: TabClient, params: {
+    tab: string;
+    max: MicroUsdc;
+}): Promise<Quote>;
+export declare function state(client: TabClient, tab: string): Promise<TabState>;
+export { amount as parseAmount };
+//# sourceMappingURL=spend.d.ts.map

package/dist/spend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spend.d.ts","sourceRoot":"","sources":["../src/spend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAgB,MAAM,YAAY,CAAA;AAGzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AA4B5E,gEAAgE;AAChE,iBAAS,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,CA2CxD;AAED,wBAAsB,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAiF1F;AAED;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CACzB,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,SAAS,CAAA;CAAE,GACtC,OAAO,CAAC,KAAK,CAAC,CAgChB;AAED,wBAAsB,KAAK,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAc7E;AAED,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,CAAA"}

package/dist/spend.js

@@ -0,0 +1,185 @@
+import { toWire, usdc } from '@0xdivyanshh/tab-money';
+import { isRetryable, REFUSAL_GUIDANCE } from '@0xdivyanshh/tab-protocol';
+import { TabInvalidError, TabProtocolError } from "./errors.js";
+/**
+ * Spend, quote, and read state.
+ *
+ * The one design decision worth restating: **a refusal is a value.** `spend()`
+ * returns a discriminated result carrying the rule that fired, because refusal
+ * is the product demonstrating that underwriting works — not an error
+ * condition. Throwing would push every consumer into `try/catch` and make the
+ * Refusals view harder to build than the happy path.
+ */
+/**
+ * A key that makes a retry safe.
+ *
+ * The gateway treats it as the hold id, so the same key cannot spend twice. It
+ * is generated HERE rather than in the gateway because only the caller can
+ * decide that two calls are the same intent — and it is returned on every
+ * outcome, including failures, so a caller retrying an unknown outcome can
+ * reuse it.
+ *
+ * `crypto.randomUUID` is available in Node 19+ and every modern browser, which
+ * keeps this package browser-safe with no dependency.
+ */
+function newIdempotencyKey() {
+    return `h_${globalThis.crypto.randomUUID().replace(/-/g, '').slice(0, 16)}`;
+}
+/** Parse a wire amount, with a message that names the field. */
+function amount(value, field) {
+    if (typeof value !== 'string') {
+        throw new TabProtocolError(`Expected "${field}" to be a decimal string amount, got ${typeof value}`, 200, value);
+    }
+    /*
+     * STRICT — exactly six decimals and an ASCII minus, which is what `toWire`
+     * emits and nothing else.
+     *
+     * `usdc()` alone is not enough here, and a test caught that: it is tolerant
+     * by design, accepting a U+2212 minus and padding a 4-decimal value. That
+     * tolerance is right for human input and wrong for a wire parser, because it
+     * makes silent data loss undetectable — the gateway once served `format()`
+     * output where a wire value belonged, `1.234567` went out as `"1.2345"`, and
+     * `usdc()` would have happily parsed it as `1234500`. Sixty-seven
+     * micro-USDC per value, no error, and a dashboard that cannot match
+     * HashScan.
+     *
+     * So the shape is checked before parsing, and a display string is rejected
+     * with a message that names the actual cause.
+     */
+    if (!/^-?\d+\.\d{6}$/.test(value)) {
+        throw new TabProtocolError(`"${field}" = ${JSON.stringify(value)} is not a wire amount. ` +
+            'Exactly six decimals and an ASCII minus are required (`toWire`). Four decimals or a ' +
+            'U+2212 minus means the server serialised a DISPLAY string instead of a wire value, ' +
+            'which is lossy — do not "fix" this by loosening the check.', 200, value);
+    }
+    try {
+        return usdc(value);
+    }
+    catch (error) {
+        throw new TabProtocolError(`"${field}" = ${JSON.stringify(value)} has the right shape but did not parse`, 200, error);
+    }
+}
+export async function spend(client, request) {
+    if (!request.tab)
+        throw new TabInvalidError('spend() needs a tab id');
+    if (!request.url)
+        throw new TabInvalidError('spend() needs a seller url');
+    if (request.max !== undefined && request.max <= 0n) {
+        // A zero or negative max is a programming error, not a refusal: there is no
+        // spend to underwrite, so the rail has nothing to decide.
+        throw new TabInvalidError(`spend() needs a positive max, got ${request.max}`);
+    }
+    const idempotencyKey = request.idempotencyKey ?? newIdempotencyKey();
+    const body = await client.request('POST', '/v1/spend', {
+        tab: request.tab,
+        url: request.url,
+        // Absent means "accept the seller's quote"; the gateway reads it from the
+        // 402. Sending an explicit null would instead be a value the gateway must
+        // interpret, so the key is simply left off.
+        ...(request.max !== undefined ? { max: toWire(request.max) } : {}),
+        idempotencyKey,
+        ...(request.init ? { init: request.init } : {}),
+    });
+    if (body.refused) {
+        const rule = body.refused.rule;
+        return {
+            outcome: 'refused',
+            rule,
+            reason: body.refused.reason,
+            /*
+             * Guidance comes from `@0xdivyanshh/tab-protocol`, not from the server's message.
+             *
+             * The rule code is the contract; the prose is not. Taking guidance from
+             * the wire would let a server version change what an agent does next
+             * without any consumer noticing.
+             */
+            guidance: REFUSAL_GUIDANCE[rule] ?? 'Surface this to the operator.',
+            retryable: isRetryable(rule),
+            ...(body.refused.evidence ? { evidence: body.refused.evidence } : {}),
+        };
+    }
+    if (body.paid) {
+        return {
+            outcome: 'paid',
+            amount: amount(body.paid.amount, 'paid.amount'),
+            seller: body.paid.seller,
+            holdId: body.paid.holdId,
+            receiptSeq: body.paid.receiptSeq,
+            body: body.body ?? null,
+            elapsedMs: body.paid.elapsedMs,
+        };
+    }
+    if (body.failed) {
+        return { outcome: 'failed', reason: body.failed.reason, holdId: body.failed.holdId };
+    }
+    /*
+     * Infrastructure failure reported through the top-level `error` field.
+     *
+     * Returned as `failed` rather than thrown, carrying the idempotency key —
+     * the caller needs that key to retry safely, and an exception would discard
+     * the one piece of information that makes the retry safe.
+     */
+    if (body.error) {
+        return { outcome: 'failed', reason: body.error, holdId: idempotencyKey };
+    }
+    throw new TabProtocolError('The gateway returned neither paid, refused, nor failed', 200, body);
+}
+/**
+ * What could this tab afford right now, without reserving anything.
+ *
+ * Derived from `state()` rather than a dedicated endpoint, and deliberately so:
+ * a quote that took a hold would leave a hold that never commits, which is
+ * exactly the shape the reconciler exists to clean up. This reserves nothing
+ * and therefore guarantees nothing — between a quote and a spend, another call
+ * on the same tab can take the headroom.
+ */
+export async function quote(client, params) {
+    const s = await state(client, params.tab);
+    if (params.max > s.perCallCap) {
+        return {
+            tab: s.tab,
+            affordable: false,
+            available: s.available,
+            ceiling: s.ceiling,
+            perCallCap: s.perCallCap,
+            wouldRefuse: 'PER_CALL_CAP',
+            reason: `${toWire(params.max)} exceeds the per-call cap of ${toWire(s.perCallCap)}`,
+        };
+    }
+    if (params.max > s.available) {
+        return {
+            tab: s.tab,
+            affordable: false,
+            available: s.available,
+            ceiling: s.ceiling,
+            perCallCap: s.perCallCap,
+            wouldRefuse: 'CEILING_EXCEEDED',
+            reason: `${toWire(params.max)} exceeds the available ${toWire(s.available)} under a ceiling of ${toWire(s.ceiling)}`,
+        };
+    }
+    return {
+        tab: s.tab,
+        affordable: true,
+        available: s.available,
+        ceiling: s.ceiling,
+        perCallCap: s.perCallCap,
+    };
+}
+export async function state(client, tab) {
+    if (!tab)
+        throw new TabInvalidError('state() needs a tab id');
+    const body = await client.request('GET', `/v1/tabs/${tab}`);
+    return {
+        tab: String(body['tab'] ?? tab),
+        balance: amount(body['balance'], 'balance'),
+        outstanding: amount(body['outstanding'], 'outstanding'),
+        holds: amount(body['holds'], 'holds'),
+        available: amount(body['available'], 'available'),
+        ceiling: amount(body['ceiling'], 'ceiling'),
+        perCallCap: amount(body['perCallCap'], 'perCallCap'),
+        window: Number(body['window'] ?? 0),
+        entries: Number(body['entries'] ?? 0),
+    };
+}
+export { amount as parseAmount };
+//# sourceMappingURL=spend.js.map

package/dist/spend.js.map

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