@txnod/sdk 1.0.1

package/dist/client-sandbox.d.ts

@@ -0,0 +1,396 @@
+import type { ClockAdvance, SimulateEvent, SimulateLatePayment, SimulateOverpaid, SimulatePartial, WalletsListResponse } from './_shared/index.js';
+/**
+ * Result envelope returned by every `simulate*` method. `event_id` is the
+ * outbox `id` whose webhook payload your handler will receive (or `null` when
+ * the simulate-* call did not enqueue a webhook — e.g.
+ * `simulateDuplicateDelivery` re-emits an existing event).
+ */
+export interface SandboxSimulateResult {
+    event_id: string | null;
+    status: string;
+}
+/** Result envelope for `clock/advance`. */
+export interface SandboxClockAdvanceResult {
+    advanced: number;
+    remaining: number;
+}
+/** Result envelope for `reset` and `destroy`. */
+export interface SandboxLifecycleResult {
+    status: 'reset' | 'deleted';
+}
+interface RequestFn {
+    <T>(input: {
+        method: 'GET' | 'POST' | 'DELETE';
+        path: string;
+        query?: Record<string, string | number | undefined>;
+        body?: unknown;
+    }): Promise<T>;
+}
+/**
+ * Thin HTTP-wrapper class for the 14 sandbox-mode endpoints introduced by
+ * Story 37.2. Constructed lazily by `TxnodClient.sandbox` so unused sandbox
+ * code is dead-code-eliminated by the bundler. Methods sign requests with the
+ * underlying HMAC scheme, parse RFC 7807 errors into typed sandbox-* error
+ * classes, and return JSON-decoded result envelopes.
+ *
+ * **Do not instantiate this class directly.** Always go through
+ * `client.sandbox` so the client's HMAC + retry + telemetry pipeline is
+ * preserved.
+ *
+ * @example
+ * ```ts
+ * import { TxnodClient } from '@txnod/sdk';
+ *
+ * const client = new TxnodClient({
+ *   projectId: process.env.TXNOD_PROJECT_ID!,
+ *   apiSecret: process.env.TXNOD_API_SECRET!,
+ *   environment: 'non-production',
+ * });
+ *
+ * // Lazy access — TxnodClientSandbox is constructed on first use.
+ * const result = await client.sandbox.simulatePaid(
+ *   '01HK8MAR2QEXAMPLE000000000',
+ * );
+ * console.log(result.event_id, result.status);
+ * ```
+ */
+export declare class TxnodClientSandbox {
+    #private;
+    constructor(request: RequestFn);
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-detect` — synthesize
+     * an `invoice.detected` event (status `pending` → `detected`) and write a
+     * synthetic `invoice_transactions` row whose `confirmations=0` is the
+     * starting point for subsequent `clockAdvance` calls.
+     *
+     * Throws `TxnodSandboxInvoiceTransitionInvalidError` when the invoice is
+     * not in `pending` status, `TxnodSandboxInvoiceNotFoundError` when the
+     * invoice does not belong to the project, and `TxnodSandboxRateLimitExceededError`
+     * when the per-project rate cap is hit.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const result = await client.sandbox.simulateDetect(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     *   { seed: 'order-42' },
+     * );
+     * console.log(result.event_id, result.status);
+     * ```
+     */
+    simulateDetect(invoiceId: string, opts?: {
+        seed?: string;
+    }): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-paid` — finalise
+     * a `detected` invoice into `paid` and emit `invoice.paid`.
+     *
+     * Throws `TxnodSandboxInvoiceTransitionInvalidError` if the invoice is not
+     * in `detected` status.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * await client.sandbox.simulateDetect('01HK8MAR2QEXAMPLE000000000');
+     * const paid = await client.sandbox.simulatePaid(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(paid.status);
+     * ```
+     */
+    simulatePaid(invoiceId: string, opts?: {
+        seed?: string;
+    }): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-overpaid` — finalise
+     * a `detected` invoice into `overpaid` with an overpayment (>amount_crypto)
+     * and emit `invoice.overpaid`. Provide either `multiplier` (× the configured
+     * amount) or `extraUnits` (added on top of the configured amount).
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * await client.sandbox.simulateDetect('01HK8MAR2QEXAMPLE000000000');
+     * const r = await client.sandbox.simulateOverpaid(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     *   { multiplier: 1.5 },
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulateOverpaid(invoiceId: string, params: SimulateOverpaid): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-partial` — emit
+     * `invoice.partial` with a sub-amount receipt; invoice stays open. Provide
+     * either `fraction` (0 < fraction < 1) or `amountUnits` (a positive integer
+     * less than amount_crypto).
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const r = await client.sandbox.simulatePartial(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     *   { fraction: 0.5 },
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulatePartial(invoiceId: string, params: SimulatePartial): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-expire` — transition
+     * a non-paid invoice into `expired` and emit `invoice.expired`.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const r = await client.sandbox.simulateExpire(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulateExpire(invoiceId: string): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-late-payment` —
+     * transition an `expired` invoice to `expired_paid_late` and emit
+     * `invoice.expired_paid_late`. Optional `amountUnits` overrides the
+     * payment size; default mirrors the invoice's configured amount.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * await client.sandbox.simulateExpire('01HK8MAR2QEXAMPLE000000000');
+     * const r = await client.sandbox.simulateLatePayment(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulateLatePayment(invoiceId: string, params?: SimulateLatePayment): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-reorg` — flip a
+     * `paid`/`overpaid` invoice to `reverted` and emit `invoice.reverted`.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const r = await client.sandbox.simulateReorg(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulateReorg(invoiceId: string): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-reconfirm` — flip a
+     * `reverted` invoice back to `paid` and emit a re-confirmation
+     * `invoice.paid` (with a fresh `event_id` per spec).
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const r = await client.sandbox.simulateReconfirm(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulateReconfirm(invoiceId: string): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-duplicate-delivery` —
+     * re-emit the most recent webhook event for the invoice with the same
+     * `event_id`, exercising the integrator's idempotency layer.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const r = await client.sandbox.simulateDuplicateDelivery(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulateDuplicateDelivery(invoiceId: string): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-event` — emit any
+     * webhook event with caller-controlled fields. Use for negative testing
+     * (unexpected `event_type` for the current invoice status, custom
+     * `confirmations`, custom `block_height`, custom chain-specific payload).
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const r = await client.sandbox.simulateEvent(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     *   {
+     *     eventType: 'invoice.partial',
+     *     amountUnits: '1000',
+     *     confirmations: 1,
+     *     blockHeight: 100,
+     *     expectedCurrentStatus: 'detected',
+     *   },
+     * );
+     * console.log(r.status);
+     * ```
+     */
+    simulateEvent(invoiceId: string, eventInput: SimulateEvent): Promise<SandboxSimulateResult>;
+    /**
+     * `POST /api/v1/sandbox/{projectId}/clock/advance` — bump the
+     * `confirmations` counter on every `detected` invoice for the given chain
+     * and finalise any whose `confirmations >= confirmation_threshold`. Throws
+     * `TxnodSandboxRateLimitExceededError` (10/min/project per spec §6.1).
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const r = await client.sandbox.clockAdvance(
+     *   '01HK8MAR2QEXAMPLEPROJECT000',
+     *   { chain: 'btc', blocks: 6 },
+     * );
+     * console.log('finalized', r.advanced, 'remaining', r.remaining);
+     * ```
+     */
+    clockAdvance(projectId: string, params: ClockAdvance): Promise<SandboxClockAdvanceResult>;
+    /**
+     * `POST /api/v1/sandbox/{projectId}/reset` — soft-purge the data tail of
+     * a sandbox project (invoices, transactions, outbox events, address pool)
+     * while preserving the project shell + xpubs + bindings + sandbox PAT +
+     * api_keys. Throws `TxnodSandboxResetFailedError` on internal failure.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * await client.sandbox.reset('01HK8MAR2QEXAMPLEPROJECT000');
+     * console.log('sandbox project reset');
+     * ```
+     */
+    reset(projectId: string): Promise<SandboxLifecycleResult>;
+    /**
+     * `DELETE /api/v1/sandbox/{projectId}` — full-delete the sandbox project
+     * (per F-20: dashboard owns the create flow, SDK + MCP own destructive
+     * lifecycle). Throws `TxnodSandboxDeleteFailedError` on internal failure.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * await client.sandbox.destroy('01HK8MAR2QEXAMPLEPROJECT000');
+     * console.log('sandbox project deleted');
+     * ```
+     */
+    destroy(projectId: string): Promise<SandboxLifecycleResult>;
+    /**
+     * `GET /api/v1/sandbox/{projectId}/wallets` — list the per-chain xpubs +
+     * derivation paths the sandbox project routes against. Useful for
+     * integrators wiring the sandbox into a derivation-aware test harness.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * const wallets = await client.sandbox.listWallets(
+     *   '01HK8MAR2QEXAMPLEPROJECT000',
+     * );
+     * for (const w of wallets.items) console.log(w.chain, w.derivation_path);
+     * ```
+     */
+    listWallets(projectId: string): Promise<WalletsListResponse>;
+}
+export {};
+//# sourceMappingURL=client-sandbox.d.ts.map

package/dist/client-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-sandbox.d.ts","sourceRoot":"","sources":["../src/client-sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACpB,MAAM,eAAe,CAAC;AAEvB;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2CAA2C;AAC3C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,iDAAiD;AACjD,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;CAC7B;AAED,UAAU,SAAS;IACjB,CAAC,CAAC,EAAE,KAAK,EAAE;QACT,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,QAAQ,CAAC;QAClC,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;QACpD,IAAI,CAAC,EAAE,OAAO,CAAC;KAChB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,kBAAkB;;gBAGjB,OAAO,EAAE,SAAS;IAI9B;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACvB,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GACvB,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,eAAe,CACb,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAQjE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,mBAAmB,GAC3B,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAQhE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAQpE;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,yBAAyB,CACvB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACH,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,aAAa,GACxB,OAAO,CAAC,qBAAqB,CAAC;IAQjC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,yBAAyB,CAAC;IAQrC;;;;;;;;;;;;;;;;;;;OAmBG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAQzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAQ3D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAM7D"}