@txnod/sdk 1.0.1

package/docs/05-errors.md

@@ -0,0 +1,199 @@
+---
+title: "Error handling"
+description: "Every typed TxnodError subclass, what raises it, and how to branch on it."
+sdk_version: 1.0.0
+---
+
+# Error handling
+
+Every `TxnodClient` method throws a subclass of `TxnodError` on any non-2xx response. `verifyWebhookSignature` throws a `TxnodError` subclass on signature failure. All subclasses are named exports of `@txnod/sdk`.
+
+## Base shape
+
+```ts
+class TxnodError extends Error {
+  readonly kind: string;         // machine-friendly class discriminant, e.g. 'rate_limit_exceeded'
+  readonly error_code: ErrorCode; // the server's error_code from the RFC 7807 envelope
+  readonly status: number;        // HTTP status
+  readonly request_id: string;    // correlate with txnod server logs via this id
+  readonly raw: ProblemDetails;   // full RFC 7807 envelope, may carry `errors`/`meta`
+}
+```
+
+- Always log `err.request_id` — it's the only reliable way to correlate with server-side logs when asking for support.
+- `err.raw.errors` is populated on `TxnodValidationError` with Zod-shaped per-field issues.
+
+## Canonical branching pattern
+
+```ts
+import {
+  TxnodClient,
+  TxnodError,
+  TxnodPoolExhaustedError,
+  TxnodRateLimitError,
+  TxnodValidationError,
+  TxnodAuthInvalidError,
+} from '@txnod/sdk';
+
+try {
+  await client.createInvoice({ /* ... */ });
+} catch (err) {
+  if (err instanceof TxnodRateLimitError || err instanceof TxnodPoolExhaustedError) {
+    await sleep(err.retry_after_seconds * 1000);
+    // retry once
+    return;
+  }
+  if (err instanceof TxnodValidationError) {
+    console.warn('per-field validation:', err.raw.errors);
+    throw err; // not retryable — fix inputs
+  }
+  if (err instanceof TxnodAuthInvalidError) {
+    throw new Error('check TXNOD_PROJECT_ID / TXNOD_API_SECRET');
+  }
+  if (err instanceof TxnodError) {
+    console.error(err.error_code, err.request_id, err.status);
+  }
+  throw err;
+}
+```
+
+**Always order the `instanceof` checks most-specific → base.** `TxnodRateLimitError extends TxnodError`, so a bare `instanceof TxnodError` check first would swallow everything.
+
+## Error class catalogue
+
+Grouped by what the operator should do. Full `error_code` → class lookup is in [`reference/errors.md`](./reference/errors.md).
+
+### Fatal — fix inputs / configuration
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodValidationError` | `validation_error` | Request body failed server Zod validation — inspect `err.raw.errors` |
+| `TxnodInvalidCoinError` | `invalid_coin` | `coin` not in supported coins enum |
+| `TxnodInvalidXpubFormatError` | `invalid_xpub_format` | xpub structurally invalid for chain |
+| `TxnodInvalidWebhookUrlError` | `invalid_webhook_url` | `callback_url` is not a valid https URL |
+| `TxnodCoinNotEnabledError` | `coin_not_enabled` | Coin supported but not enabled for this project — use `getRates()` to see enabled coins |
+| `TxnodAmountOutOfRangeError` | `amount_out_of_range` | Amount below/above project-configured range |
+| `TxnodXpubNotVerifiedError` | `xpub_not_verified` | xpub added to the project but ownership challenge not yet completed |
+| `TxnodWalletNotBoundError` | `wallet_not_bound` | No verified wallet of matching kind bound for the chain on this project — operator must bind one before invoice creation succeeds |
+| `TxnodWalletKindMismatchError` | `wallet_kind_mismatch` | Cross-kind binding rejected at the dashboard — production projects only accept production wallets, testnet projects only testnet wallets |
+| `TxnodTronNoActivatedAddressesError` | `tron_no_activated_addresses_available` | TRON-only — operator's address pool has zero activated rows; `.walletId` carries the operator wallet id for deep-link UX. Operator-action-required, do not auto-retry |
+| `TxnodInvoiceNotCancellableError` | `invoice_not_cancellable` | Cannot cancel an invoice past its cancellable state |
+| `TxnodInvalidStateTransitionError` | `invalid_state_transition` | Requested op would produce an illegal invoice transition |
+
+### Fatal — auth / identity
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodAuthInvalidError` | `auth_invalid` | Headers missing/malformed, or project id unknown |
+| `TxnodSignatureInvalidError` | `signature_invalid` | Computed HMAC mismatch on outbound API call |
+| `TxnodSignatureReplayedError` | `signature_replayed` | Same `(timestamp, signature)` seen before — body cache hit. Fix the partner's signing pipeline (do not regenerate timestamps for retries) |
+| `TxnodTimestampOutOfWindowError` | `timestamp_out_of_window` | `X-Timestamp` outside ±300 s — fix NTP on caller |
+| `TxnodKeySuspendedError` | `key_suspended` | Key owner suspended by operator |
+| `TxnodKeyRevokedError` | `key_revoked` | Key has been rotated/revoked — stop using |
+| `TxnodProjectSuspendedError` | `project_suspended` | Target project suspended by operator |
+| `TxnodSubscriptionExpiredError` | `subscription_expired` | HTTP 402 — operator's subscription is not `active`; writes are blocked, reads still work. Operator must renew via dashboard `/billing` before writes resume |
+| `TxnodPermissionDeniedError` | `permission_denied` | Key lacks the capability for this route |
+
+### Fatal — not found
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodInvoiceNotFoundError` | `invoice_not_found` | Invoice id does not belong to this project |
+| `TxnodProjectNotFoundError` | `project_not_found` | Project id unknown or not accessible |
+| `TxnodWalletNotFoundError` | `wallet_not_found` | No wallet bound for `(chain, project)` |
+| `TxnodOrphanNotFoundError` | `orphan_not_found` | Orphan payment with that tx hash doesn't exist |
+| `TxnodEventNotFoundError` | `event_not_found` | Webhook event id unknown |
+
+### Idempotent — treat as success
+
+| Class | `error_code` | What to do |
+|---|---|---|
+| `TxnodExternalIdConflictError` | `external_id_conflict` | Invoice with that `external_id` already exists; fetch via `searchInvoices({ external_id })` |
+| `TxnodOrphanAlreadyAttributedError` | `orphan_already_attributed` | Orphan already bound to an invoice; treat as success |
+
+### Transient — retry
+
+| Class | `error_code` | Notes |
+|---|---|---|
+| `TxnodRateLimitError` | `rate_limit_exceeded` | `.retry_after_seconds` holds the `Retry-After` value. The SDK already retries once internally; this is what you see after retries are exhausted |
+| `TxnodPoolExhaustedError` | `pool_exhausted` | Pool hit hard cap (`poolSizePerChain[chain]`). `.retry_after_seconds` holds the server-computed `Retry-After` (soonest `locked_until` or project cooldown). Wait it out, or raise the cap if it fires under steady load |
+| `TxnodWebhookCapacityExhaustedError` | `webhook_capacity_exhausted` | Webhook fleet for this chain has no spare slots. `.retry_after_seconds` is always `0` because a partner retry alone won't free capacity — treat as transient outage and queue the invoice for a later retry |
+| `TxnodServerError` | `internal_error` | 5xx classified as uncategorized — retryable with backoff |
+
+### TON-chain runtime
+
+Server-side TON failures that surface to partner code on `createInvoice` (or downstream during settlement). `ton_jetton_resolve_failed` is transient (provider hiccup); the others are operator-action-required.
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodTonOperatorWalletNotDeployedError` | `ton_operator_wallet_not_deployed` | TON operator wallet has not been deployed on-chain yet — operator must broadcast the wallet's `StateInit` (typical first send) before invoices can resolve. HTTP 422 |
+| `TxnodTonInvalidWalletVersionError` | `ton_invalid_wallet_version` | Configured wallet version does not match the deployed one. Operator must reconcile `TXNOD_TON_WALLET_VERSION` with the actual deployed version (`v3R2` / `v4R2` / `v5`). HTTP 422 |
+| `TxnodTonJettonResolveFailedError` | `ton_jetton_resolve_failed` | Toncenter v3 or TONAPI failed to resolve the jetton master/wallet pair (provider hiccup, typically transient). HTTP 503 — retry with backoff |
+| `TxnodTonCommentParseFailedError` | `ton_comment_parse_failed` | Inbound TON tx carried a malformed `payment_token` comment that did not parse as the expected 8-hex memo. Indicates a mis-formed wallet send; operator review required. HTTP 422 |
+
+### TonConnect operator-onboarding
+
+Raised by the operator's TonConnect signing flow during xpub onboarding — never on partner-facing methods. Exported so the dashboard's typed-error catch can branch correctly.
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodTonConnectPayloadExpiredError` | `tonconnect_payload_expired` | The challenge payload was signed past its TTL — operator must restart the connect flow |
+| `TxnodTonConnectPayloadUnknownError` | `tonconnect_payload_unknown` | Challenge payload not in the server's recent-issued set — replay or stale browser tab |
+| `TxnodTonConnectDomainMismatchError` | `tonconnect_domain_mismatch` | `proof.domain.value` does not match `TXNOD_TONCONNECT_DOMAIN` — manifest is being served from the wrong origin |
+| `TxnodTonConnectTimestampSkewError` | `tonconnect_timestamp_skew` | Wallet timestamp outside the configured window — clock-skew on the wallet side |
+| `TxnodTonConnectUnknownWalletVersionError` | `tonconnect_unknown_wallet_version` | Wallet returned a `walletStateInit` whose version the server does not recognise |
+| `TxnodTonConnectSignatureInvalidError` | `tonconnect_signature_invalid` | Ed25519 signature verification failed |
+| `TxnodTonConnectNetworkMismatchError` | `tonconnect_network_mismatch` | Wallet network (`-239` mainnet / `-3` testnet) does not match the server-configured TON network |
+
+### Sandbox lifecycle + simulation
+
+Raised by the sandbox surface (`/api/v1/sandbox/*` REST + the 14 `client.sandbox.*` SDK methods + `sandbox:simulate` MCP scope). See [`05-sandbox.md`](./05-sandbox.md) for the full lifecycle.
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodSandboxProjectRequiredError` | `sandbox_project_required` | Sandbox endpoint hit against a `kind: 'production'` project — sandbox tooling is structurally unreachable from production projects (and vice versa). HTTP 403 |
+| `TxnodSandboxPerOperatorCapReachedError` | `sandbox_per_operator_cap_reached` | Operator already owns the maximum number of sandbox projects (per-operator cap). Delete an existing sandbox via `client.sandbox.destroy(id)` before creating another. HTTP 422 |
+| `TxnodSandboxKeyAgainstProductionProjectError` | `sandbox_key_against_production_project` | A sandbox API secret (prefix `sk_sandbox_`) was used to authenticate against a production project. Mismatch between key kind and project kind. HTTP 400 |
+| `TxnodProductionKeyAgainstSandboxProjectError` | `production_key_against_sandbox_project` | A production API secret was used against a sandbox project. Same kind-mismatch as the previous, opposite direction. HTTP 400 |
+| `TxnodSandboxProvisioningFailedError` | `sandbox_provisioning_failed` | Server failed to provision the sandbox project shell during `POST /sandbox`. Internal failure; retry. HTTP 500 |
+| `TxnodSandboxInvoiceTransitionInvalidError` | `sandbox_invoice_transition_invalid` | A `simulate*` call was issued against an invoice in a state that does not allow the requested transition. `.message` carries the current and attempted transition. HTTP 422 |
+| `TxnodSandboxInvoiceNotFoundError` | `sandbox_invoice_not_found` | Sandbox `simulate*` call referenced an invoice that does not belong to the targeted sandbox project. Collapsed across "wrong project" / "soft-deleted" / "non-existent" (oracle-safe). HTTP 404 |
+| `TxnodSandboxInvoiceTerminalError` | `sandbox_invoice_terminal` | `simulateDuplicateDelivery` requires a prior terminal webhook on the invoice — this one has none yet. HTTP 422 |
+| `TxnodSandboxRateLimitExceededError` | `sandbox_rate_limit_exceeded` | Sandbox per-project rate cap hit (e.g. `clockAdvance` ≤ 10/min). HTTP 429 — back off |
+| `TxnodSandboxResetFailedError` | `sandbox_reset_failed` | `client.sandbox.reset(projectId)` failed mid-purge. Internal failure; retry. HTTP 500 |
+| `TxnodSandboxDeleteFailedError` | `sandbox_delete_failed` | `client.sandbox.destroy(projectId)` failed mid-delete. Internal failure; retry. HTTP 500 |
+| `TxnodSandboxActiveInvoiceCapReachedError` | `sandbox_active_invoice_cap_reached` | Sandbox project has too many concurrently-open invoices — finalise or expire some via `simulateExpire` / `simulatePaid` before creating more. HTTP 422 |
+
+### SDK-local synthesised (init-time guards)
+
+Thrown by `TxnodClient` constructor and `parseXpubConfig` before any HTTP call leaves the process. They synthesise a `ProblemDetails` envelope so they share the `instanceof TxnodError` invariant — but they have no server-side `error_code`. Catch them around `new TxnodClient(...)` and the verify helpers.
+
+| Class | `kind` | Meaning |
+|---|---|---|
+| `TxnodSandboxKeyInProductionError` | `sandbox_key_in_production` | A `sk_sandbox_` secret was passed into a `TxnodClient` constructed with `environment: 'production'` (or with `environment` omitted while `NODE_ENV === 'production'`). Carries `.signal` (`'env-mismatch'` / `'explicit-production'`), `.secretPrefix`, `.detectedEnvironment`. **Fail-closed at construction** |
+| `TxnodEnvironmentUnknownError` | `environment_unknown` | A `sk_sandbox_` secret was used without an explicit `environment` AND `NODE_ENV` is unset/unknown — refuses to guess. Set `environment: 'non-production'` or `'production'` explicitly |
+| `TxnodSandboxXpubInProductionError` | `sandbox_xpub_in_production` | A testnet xpub (e.g. `tpub`/`vpub` for BTC) was loaded for a chain whose env-detected mode is production. Carries `.chain`, `.xpubPrefix`, `.detectedEnvironment`. **Fail-closed at config parse** |
+
+### Dashboard-only (exported but not reachable from `TxnodClient`)
+
+The partner HMAC surface never raises these — they appear only on internal Server Actions inside the operator dashboard. They are exported so the `error_code` ↔ class map stays exhaustive. Do not branch on them in partner code.
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodWalletNotOwnedError` | `wallet_not_owned` | Operator targeted a wallet they do not own — never crosses the partner API |
+| `TxnodWalletHasActiveBindingsError` | `wallet_has_active_bindings` | Operator tried to archive a wallet still bound to one or more projects |
+
+### Webhook-local (thrown by `verifyWebhookSignature` only)
+
+| Class | Kind | Meaning |
+|---|---|---|
+| `TxnodSignatureFormatError` | `signature_format` | `X-Txnod-Signature` absent or not `t=<int>,v1=<hex>` |
+| `TxnodHmacError` | `hmac` | Computed HMAC does not match |
+| `TxnodTimestampError` | `timestamp` | `|now - t| > 300` — `.skew_seconds` is the signed delta |
+| `TxnodWebhookPayloadParseError` | `webhook_payload_parse` | HMAC passed but body is not valid JSON. Indicates a misbehaving server release; treat as 401-class (do not parse, do not act). `.cause` carries the underlying `SyntaxError` |
+
+## Related
+
+- [`reference/errors.md`](./reference/errors.md) — `error_code` ↔ class lookup
+- [`01-authentication.md`](./01-authentication.md) — why the auth-family errors happen
+- [`04-webhooks.md`](./04-webhooks.md) — when the webhook-local trio fires

package/docs/05-sandbox.md

@@ -0,0 +1,159 @@
+---
+title: "Sandbox"
+description: "client.sandbox.* surface, environment-detection guards, layered defenses against routing real customer funds to sandbox addresses."
+sdk_version: 1.0.0
+---
+
+# Sandbox
+
+The `@txnod/sdk` ships a sandbox surface (`client.sandbox.*` and 14 matching MCP tools) for deterministic integration testing. **Sandbox secrets and sandbox projects exist in the same Postgres database as production — there is no separate environment.** Discrimination happens via:
+
+1. The `sk_sandbox_` API-secret prefix.
+2. A `projects.kind` column whose value is `'sandbox'` or `'production'`.
+3. The webhook envelope's `mode: 'sandbox' | 'production'` discriminator.
+4. The SDK constructor's environment-detection guards (this document).
+
+## 30-second overview
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!, // sk_sandbox_...
+  environment: 'non-production', // explicit override; trusts NODE_ENV otherwise
+});
+
+// 1. Create an invoice as usual
+const invoice = await client.createInvoice({
+  amount_usd: 9.99,
+  coin: 'usdt_trc20',
+  external_id: 'order-42',
+});
+
+// 2. Drive the state machine deterministically
+await client.sandbox.simulateDetect(invoice.id, { seed: 'order-42' });
+await client.sandbox.simulatePaid(invoice.id);
+
+// 3. Your webhook handler receives invoice.detected then invoice.paid with mode='sandbox'
+
+// 4. Reset between test runs
+await client.sandbox.reset(process.env.TXNOD_PROJECT_ID!);
+```
+
+## Environment detection (`getSdkEnv`)
+
+The SDK never trusts a single signal. `getSdkEnv()` resolves environment in this order:
+
+1. The constructor's `environment` option (`'production' | 'non-production'`).
+2. `process.env.TXNOD_ENVIRONMENT === 'production'` → `'production'`.
+3. `process.env.TXNOD_ENVIRONMENT === 'non-production'` → `'non-production'`.
+4. `process.env.NODE_ENV === 'production'` → `'production'`.
+5. `process.env.NODE_ENV === 'development' | 'test'` → `'non-production'`.
+6. Otherwise → `'unknown'`.
+
+`getSdkEnv()` is the only environment-signal reader in the SDK — there is no second source of truth.
+
+## Layered defenses
+
+| Layer | What it catches | When it fires |
+|---|---|---|
+| 1. SDK constructor | Sandbox secret in production-detected env | Hard-fail at boot via `TxnodSandboxKeyInProductionError` |
+| 2. SDK constructor | Sandbox secret with no env signal | Hard-fail at boot via `TxnodEnvironmentUnknownError` |
+| 3. SDK xpub-prefix guard | Testnet xpub (`tpub`/`vpub`/`upub`) in production | Hard-fail at boot via `TxnodSandboxXpubInProductionError` |
+| 4. Server cross-mode guard | Sandbox secret targeting production project (or vice-versa) | API returns `sandbox_key_against_production_project` / `production_key_against_sandbox_project` |
+| 5. Webhook envelope `mode` | Drift between intent and outcome | Integrator asserts `event.mode === 'sandbox'` in non-prod tests |
+
+## Per-chain testnet-prefix truth table
+
+| Chain | Mainnet xpub prefixes | Testnet xpub prefixes the SDK guard catches | Network safety also enforced at |
+|---|---|---|---|
+| BTC | `xpub` (BIP44), `ypub` (BIP49), `zpub` (BIP84) | `tpub`, `upub`, `vpub` | Address checksum + bech32 hrp (`bc1` / `tb1`) |
+| ETH | `xpub` | `tpub` | Per-chain id (mainnet=1, testnet has no per-address discriminator) |
+| Polygon | `xpub` | `tpub` | Per-chain id (mainnet=137, amoy=80002) |
+| BSC | `xpub` | `tpub` | Per-chain id (mainnet=56, testnet=97) |
+| TRON | `xpub` | `tpub` | Address byte prefix (`T` mainnet, `2` testnet via base58check leading byte) |
+| Cardano | `acct_xvk1...` (CIP-5 hrp; same for mainnet + testnet) | (no SDK-side discriminator) | Address-level NetworkId byte (server-side) |
+| TON | `TXNOD_TON_PUBKEY` is a 32-byte ed25519 pubkey, never an extended key | (no xpub concept; guard is a no-op) | `TXNOD_TON_WORKCHAIN` + bounceable address discriminator |
+
+**EVM family carve-out:** since `xpub`-prefixed extended keys are valid for both mainnet and testnet on EVM chains (network differentiation lives in the per-address checksum and the chain id), the SDK guard ONLY catches `tpub`/`vpub`/`upub`. An `xpub` configured for an EVM testnet falls through to layer 4 (server cross-mode) and layer 5 (envelope `mode`).
+
+**Cardano carve-out:** CIP-5's hrp does not distinguish testnet at the account-pubkey level — the safety lives in the address-level NetworkId byte. The xpub-prefix guard is a no-op for ADA.
+
+## Constructor options
+
+| Option | Type | Purpose |
+|---|---|---|
+| `environment` | `'production' \| 'non-production'` | Explicit override; precedence above env vars. Use for staging replicas where `NODE_ENV='production'` but the secret is sandbox. |
+| `iAcknowledgeRoutingRealCustomerFundsToSandboxAddresses` | `boolean` | Bypass the sandbox-secret-in-production hard-fail. Setting `true` does NOT suppress a non-suppressible `console.error` on every constructor invocation, and adds an `X-Txnod-Client-Environment: production` header to every API call (server-side telemetry surfaces these in the admin dashboard). |
+
+The override option is deliberately verbose — it must remain awkward to type. Renaming it in any future SDK version requires a major-version bump and a deprecation cycle.
+
+## `client.sandbox.*` surface
+
+All 14 methods sign with the same HMAC scheme as the rest of the SDK and throw the typed sandbox-* error classes per the SDK's typed-error contract.
+
+| Method | HTTP | Returns | Throws |
+|---|---|---|---|
+| `simulateDetect(invoiceId, opts?)` | `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-detect` | `{ event_id, status: 'detected' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `pending`), `TxnodSandboxInvoiceNotFoundError` |
+| `simulatePaid(invoiceId, opts?)` | `POST .../simulate-paid` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `detected`) |
+| `simulateOverpaid(invoiceId, params)` | `POST .../simulate-overpaid` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` |
+| `simulatePartial(invoiceId, params)` | `POST .../simulate-partial` | `{ event_id, status: 'detected' }` | `TxnodSandboxInvoiceTransitionInvalidError` |
+| `simulateExpire(invoiceId)` | `POST .../simulate-expire` | `{ event_id, status: 'expired' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice already terminal) |
+| `simulateLatePayment(invoiceId, opts?)` | `POST .../simulate-late-payment` | `{ event_id, status: 'expired_paid_late' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `expired`) |
+| `simulateReorg(invoiceId)` | `POST .../simulate-reorg` | `{ event_id, status: 'reverted' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `paid`/`overpaid`/`partial`) |
+| `simulateReconfirm(invoiceId)` | `POST .../simulate-reconfirm` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `reverted`) |
+| `simulateDuplicateDelivery(invoiceId)` | `POST .../simulate-duplicate-delivery` | `{ event_id }` | `TxnodSandboxInvoiceTerminalError` (no terminal event yet) |
+| `simulateEvent(invoiceId, eventInput)` | `POST .../simulate-event` | `{ event_id, status }` | `TxnodSandboxInvoiceTransitionInvalidError` (current status != `expectedCurrentStatus`) |
+| `clockAdvance(projectId, params)` | `POST /api/v1/sandbox/{projectId}/clock/advance` | `{ advanced, remaining }` | `TxnodSandboxRateLimitExceededError` (>10/min/project) |
+| `reset(projectId)` | `POST /api/v1/sandbox/{projectId}/reset` | `{ status: 'reset' }` | `TxnodSandboxResetFailedError` |
+| `destroy(projectId)` | `DELETE /api/v1/sandbox/{projectId}` | `{ status: 'deleted' }` | `TxnodSandboxDeleteFailedError` |
+| `listWallets(projectId)` | `GET /api/v1/sandbox/{projectId}/wallets` | `WalletsListResponse` | (read-only; no transition errors) |
+
+The `client.sandbox` getter is lazy — bundlers tree-shake the entire namespace when it is never referenced from your application code.
+
+## Recommended CI assertion
+
+Add this once at the top of your test setup so a misconfiguration breaks CI loudly:
+
+```ts
+// tests/setup.ts
+function assertSafeMode(): void {
+  const env = process.env.NODE_ENV ?? 'unknown';
+  const secret = process.env.TXNOD_API_SECRET ?? '';
+  const isSandbox = secret.startsWith('sk_sandbox_');
+  if (env === 'production' && isSandbox) {
+    throw new Error(
+      '[ci] Sandbox API secret cannot run with NODE_ENV=production',
+    );
+  }
+  if (env !== 'production' && !isSandbox) {
+    throw new Error(
+      '[ci] Production API secret cannot run outside production',
+    );
+  }
+}
+assertSafeMode();
+```
+
+And on every webhook event your test handler asserts the `mode` matches the runtime:
+
+```ts
+import { verifyWebhookSignature } from '@txnod/sdk';
+
+export async function POST(request: Request): Promise<Response> {
+  const rawBody = await request.text();
+  const event = verifyWebhookSignature(
+    request.headers,
+    rawBody,
+    process.env.TXNOD_WEBHOOK_SECRET!,
+  );
+  if (process.env.NODE_ENV === 'production' && event.mode === 'sandbox') {
+    throw new Error('refusing to process sandbox event in production');
+  }
+  // ...
+  return Response.json({ ok: true });
+}
+```
+
+See [`./examples/sandbox-vitest-suite.md`](./examples/sandbox-vitest-suite.md) for an end-to-end Vitest harness covering all seven webhook event types.

package/docs/06-idempotency.md

@@ -0,0 +1,132 @@
+---
+title: "Idempotency, reorgs, and reverts"
+description: "Four idempotency layers you must respect: external_id on create, event_id on webhooks, tx-level uniqueness, reorg re-confirmation."
+sdk_version: 1.0.0
+---
+
+# Idempotency, reorgs, and reverts
+
+TxNod is designed around four idempotency layers. Integrating correctly means respecting each one.
+
+## 1. Invoice creation — `(project_id, external_id)`
+
+`createInvoice` is idempotent on the pair `(project_id, external_id)`. A second attempt with the same `external_id` raises `TxnodExternalIdConflictError` — **treat it as success** and fetch the existing invoice:
+
+```ts
+import { TxnodClient, TxnodExternalIdConflictError } from '@txnod/sdk';
+
+import type { Coin } from '@txnod/sdk';
+
+async function createOrLoadInvoice(args: {
+  external_id: string;
+  coin: Coin;
+  amount_usd: number;
+  callback_url: string;
+}) {
+  try {
+    return await client.createInvoice(args);
+  } catch (err) {
+    if (err instanceof TxnodExternalIdConflictError) {
+      const page = await client.searchInvoices({ external_id: args.external_id, limit: 1 });
+      return page.items[0]!;
+    }
+    throw err;
+  }
+}
+```
+
+**Your `external_id` must be stable for the thing you are charging for.** Use the order / invoice id from your own system — not a random UUID regenerated on retry.
+
+## 2. Webhook events — `event_id`
+
+Every webhook event carries a stable `event_id` (ULID). Retries of the **same** event use the **same** `event_id`. You MUST de-duplicate on it.
+
+```sql
+-- Minimal partner-side schema
+CREATE TABLE txnod_webhook_events_processed (
+  event_id      TEXT PRIMARY KEY,
+  event_type    TEXT NOT NULL,
+  invoice_id    TEXT,
+  processed_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+```ts
+import { verifyWebhookSignature } from '@txnod/sdk';
+
+export async function POST(request: Request): Promise<Response> {
+  const rawBody = await request.text();
+  const event = verifyWebhookSignature(request.headers, rawBody, secret);
+
+  const inserted = await db.insertIgnore('txnod_webhook_events_processed', {
+    event_id: event.event_id,
+    event_type: event.event_type,
+    invoice_id: event.data.invoice_id, // typed as `string` on every event_type
+  });
+  if (!inserted) {
+    // We have already processed this event. Ack and move on.
+    return Response.json({ ok: true });
+  }
+
+  // First time we see this event_id — safe to take side effects.
+  await applyBusinessEffect(event);
+  return Response.json({ ok: true });
+}
+```
+
+Do **not** key idempotency on `(invoice_id, event_type)` — resends and reorg re-confirmations both preserve `event_id` but can produce legitimate repeats of `(invoice_id, event_type)`.
+
+## 3. On-chain credit — `(tx_hash, to_address, tx_output_index)`
+
+The TxNod server uses `UNIQUE (tx_hash, to_address, tx_output_index)` to ensure a single UTXO (or EVM log / Tron trigger / Cardano output) credits an invoice exactly once, even across provider retries and watcher restarts. You do not need to reimplement this — it is transparent to you — but understanding it explains why a multi-output transaction can surface multiple `invoice.detected` events (one per matching output).
+
+## 4. Reorg re-confirmation — `(invoice_id, terminal_status)`
+
+When a chain reorg evicts a transaction that had already confirmed, the invoice moves from `paid`/`overpaid` → `reverted` and emits `invoice.reverted` **once**. If the same transaction later re-confirms on the new canonical chain, the invoice transitions back to `paid`/`overpaid` and emits a fresh `invoice.paid`/`invoice.overpaid` with a stable `event_id` derived from `(invoice_id, terminal_status)`.
+
+Rules:
+
+- **`paid` is not terminal.** Do not release digital goods or disburse funds on `invoice.paid` alone. Wait for `confirmations` ≥ your finalization threshold (configurable per project), or impose your own time-based wait.
+- **If you act on `paid` and later receive `invoice.reverted`**, you must roll the action back. Plan the reversal path from day one.
+- **Re-confirmations are idempotent.** If you already fulfilled on the first `paid`, don't fulfill again on the second.
+
+### Minimal finite-state pattern
+
+```ts
+type OrderState = 'awaiting_payment' | 'paid' | 'fulfilled' | 'reverted';
+
+async function handleEvent(event: WebhookEvent) {
+  const order = await loadOrderByInvoiceId(event.data.invoice_id);
+
+  switch (event.event_type) {
+    case 'invoice.paid':
+    case 'invoice.overpaid':
+      if (order.state === 'awaiting_payment') {
+        await setOrderState(order.id, 'paid');
+        await fulfilIfReady(order); // only when confirmations >= threshold
+      } else if (order.state === 'reverted') {
+        // Re-confirmation after an earlier revert.
+        await setOrderState(order.id, 'paid');
+      }
+      return;
+
+    case 'invoice.reverted':
+      if (order.state === 'fulfilled') {
+        await reverseFulfilment(order); // your compensation logic
+      }
+      await setOrderState(order.id, 'reverted');
+      return;
+
+    case 'invoice.expired':
+    case 'invoice.expired_paid_late':
+      // Terminal — see your own policy for late payments.
+      return;
+  }
+}
+```
+
+## Related
+
+- [`02-invoices.md`](./02-invoices.md#lifecycle) — full status table
+- [`04-webhooks.md`](./04-webhooks.md) — event envelope and retry semantics
+- [`05-errors.md`](./05-errors.md) — `TxnodExternalIdConflictError` and `TxnodOrphanAlreadyAttributedError`

package/docs/examples/express-webhook-receiver.md

@@ -0,0 +1,97 @@
+---
+title: "Express webhook receiver"
+description: "Express webhook endpoint using express.raw so verifyWebhookSignature sees the exact request bytes."
+sdk_version: 1.0.0
+---
+
+# Express webhook receiver
+
+Express's default `express.json()` parses and re-serializes the body — this breaks HMAC verification. For the webhook route you must mount `express.raw({ type: 'application/json' })`.
+
+## Full example
+
+```ts
+import express, { type Request, type Response } from 'express';
+import {
+  TxnodHmacError,
+  TxnodSignatureFormatError,
+  TxnodTimestampError,
+  verifyWebhookSignature,
+} from '@txnod/sdk';
+
+const app = express();
+
+// Webhook route — raw body. Register BEFORE any generic JSON middleware.
+app.post(
+  '/api/txnod-webhook',
+  express.raw({ type: 'application/json' }),
+  async (req: Request, res: Response) => {
+    // req.body is a Buffer here because of express.raw.
+    const rawBody = (req.body as Buffer).toString('utf8');
+
+    try {
+      const event = verifyWebhookSignature(
+        req.headers as Record<string, string | string[]>,
+        rawBody,
+        process.env.TXNOD_WEBHOOK_SECRET!,
+      );
+
+      // Idempotency: insert-if-not-exists keyed on event.event_id
+      // (see ../06-idempotency.md for the schema).
+
+      switch (event.event_type) {
+        case 'invoice.paid':
+        case 'invoice.overpaid':
+          // fulfil
+          break;
+        case 'invoice.reverted':
+          // reverse fulfilment if already applied
+          break;
+        case 'invoice.expired':
+        case 'invoice.expired_paid_late':
+        case 'invoice.detected':
+        case 'invoice.partial':
+          break;
+      }
+
+      res.status(200).json({ ok: true });
+    } catch (err) {
+      if (err instanceof TxnodSignatureFormatError) {
+        res.status(401).send('bad header');
+        return;
+      }
+      if (err instanceof TxnodHmacError) {
+        res.status(401).send('bad sig');
+        return;
+      }
+      if (err instanceof TxnodTimestampError) {
+        console.warn('clock skew seconds:', err.skew_seconds);
+        res.status(401).send('stale');
+        return;
+      }
+      throw err;
+    }
+  },
+);
+
+// All other routes can use the JSON parser freely.
+app.use(express.json());
+
+// ...
+
+app.listen(3000);
+```
+
+## Things that break silently
+
+1. **Mounting `express.json()` before the webhook route.** The webhook handler then sees `req.body` as a parsed object, not a `Buffer`, and `.toString()` reconstructs JSON that does not byte-match what TxNod signed. Fix: register `express.raw` on the webhook route specifically, before any global `express.json()`.
+
+2. **Reverse proxies that rewrite bodies.** If a proxy normalizes whitespace, re-indents JSON, or adds/removes a trailing newline, the HMAC will not match. Disable body rewriting for the webhook path.
+
+3. **Array-valued headers.** Node on Express exposes `req.headers` where some entries may be `string[]`. `verifyWebhookSignature` handles both shapes, but case-insensitive lookup assumes lowercase names — do not pass a framework-specific wrapper that renames headers.
+
+## Related
+
+- [`../04-webhooks.md`](../04-webhooks.md) — signature scheme
+- [`../06-idempotency.md`](../06-idempotency.md) — `event_id` de-duplication
+- [`nextjs-route-handler.md`](./nextjs-route-handler.md) — equivalent for Next.js 16 App Router