@txnod/sdk 1.0.1

package/dist/client-sandbox.js

@@ -0,0 +1,448 @@
+/**
+ * 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 class TxnodClientSandbox {
+    #request;
+    constructor(request) {
+        this.#request = request;
+    }
+    /**
+     * `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, opts) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-detect`,
+            body: opts?.seed !== undefined ? { seed: opts.seed } : {},
+        });
+    }
+    /**
+     * `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, opts) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-paid`,
+            body: opts?.seed !== undefined ? { seed: opts.seed } : {},
+        });
+    }
+    /**
+     * `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, params) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-overpaid`,
+            body: params,
+        });
+    }
+    /**
+     * `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, params) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-partial`,
+            body: params,
+        });
+    }
+    /**
+     * `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) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-expire`,
+            body: {},
+        });
+    }
+    /**
+     * `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, params) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-late-payment`,
+            body: params ?? {},
+        });
+    }
+    /**
+     * `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) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-reorg`,
+            body: {},
+        });
+    }
+    /**
+     * `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) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-reconfirm`,
+            body: {},
+        });
+    }
+    /**
+     * `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) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-duplicate-delivery`,
+            body: {},
+        });
+    }
+    /**
+     * `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, eventInput) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/invoices/${invoiceId}/simulate-event`,
+            body: eventInput,
+        });
+    }
+    /**
+     * `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, params) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/${projectId}/clock/advance`,
+            body: params,
+        });
+    }
+    /**
+     * `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) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/sandbox/${projectId}/reset`,
+            body: {},
+        });
+    }
+    /**
+     * `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) {
+        return this.#request({
+            method: 'DELETE',
+            path: `/api/v1/sandbox/${projectId}`,
+            body: {},
+        });
+    }
+    /**
+     * `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) {
+        return this.#request({
+            method: 'GET',
+            path: `/api/v1/sandbox/${projectId}/wallets`,
+        });
+    }
+}
+//# sourceMappingURL=client-sandbox.js.map

package/dist/client-sandbox.js.map

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