@txnod/sdk 1.0.2 → 1.2.0

package/AGENTS.md

@@ -1,7 +1,7 @@
 ---
 title: "@txnod/sdk — agent entry point"
 description: "How AI coding agents should consume @txnod/sdk documentation shipped inside the npm tarball."
-sdk_version: 1.0.2
+sdk_version: 1.2.0
 ---
 
 # @txnod/sdk — agent entry point

package/CHANGELOG.md

@@ -4,6 +4,30 @@ All notable changes to `@txnod/sdk` are documented here. Format: [Keep a Changel
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-06-24
+
+### Added
+
+- New coin/chain helpers exported from the package root: `COIN_TO_CHAIN` (a `Record<Coin, Chain>` map), `coinToChain(coin)` (the function form), and `COIN_DECIMALS` (base-unit decimal places per coin). Use these when an API that speaks `coin` (invoices) meets one that speaks `chain` (orphan payments), or when you need a coin's on-chain precision.
+- New amount converters `toBaseUnits(coin, humanString)` and `fromBaseUnits(coin, baseUnitsString)`. `toBaseUnits` turns a human decimal (`"1.5"`) into integer base units; `fromBaseUnits` is the inverse and trims trailing zeros. Both honour each coin's true precision — note that BEP-20 USDT/USDC use **18** decimals (not 6 like their ERC-20/TRC-20 siblings) and TON uses 9, so always round-trip `amount_units` through `fromBaseUnits` rather than assuming a width.
+- `verifyWebhookSignature` now accepts the raw body as `string | Buffer` (Node HTTP frameworks hand back a `Buffer` — no `.toString()` boilerplate needed) and a headers bag that is a structural superset of Node's `IncomingHttpHeaders`, so Express/Fastify `req.headers` work alongside the Web `Headers` object. The accepted header shape is exported as the new type `WebhookHeadersInput`.
+- New `client.environment` getter — resolves to `'production'`, `'non-production'`, or `'unknown'` after applying the constructor `environment` option and the `TXNOD_ENVIRONMENT` / `NODE_ENV` fallbacks. Read it at startup to fail fast on a misconfigured deploy.
+- `OrphanPaymentResponse` now carries a `coin` field.
+- The webhook event `data` payload now includes `external_id`, `metadata`, `amount_crypto`, and `amount_usd`.
+- The webhook event envelope now carries `resent_from_event_id` (`string | null`) — honest redelivery lineage, **not** a restore flag. It is `null` on first-time events and set to the original event's `event_id` for BOTH operator-triggered resends **and** reorg re-confirmations. Key webhook idempotency on the unique `event_id` — **never on `tx_hash`**. The reorg-restore signal specifically is an `invoice.paid` whose `data.reason === 'reorg'` (it repeats a previously-reverted `tx_hash`); on that event re-apply the credit you reversed on the prior `invoice.reverted` rather than dropping it as a `tx_hash` duplicate. An operator resend (`resent_from_event_id` set, `data.reason` not `'reorg'`) is a duplicate delivery of an already-processed event — dedupe it via your `event_id` ledger.
+- `createInvoice` accepts an optional `matching_mode` (`'exact' | 'at_least' | 'any'`) to override the project default per invoice. `exact` requires the deposit amount to equal the invoice amount; `at_least` accepts any amount ≥ the invoice amount (overpayment OK); `any` accepts any amount (donations / pay-what-you-want). Omit the field to inherit the project's configured default. When the address pool is saturated such that the invoice would share a deposit address, only `exact` is permitted — `at_least`/`any` reject with `TxnodOverlayMatchingModeError` (`overlay_matching_mode_required_exact`, HTTP 422). The same field now appears on every invoice response (`matching_mode`).
+- New sandbox invoice CRUD methods on `client.sandbox.*` — `createInvoice(body)`, `getInvoice(invoiceId)`, `listInvoices(query?)`, `cancelInvoice(invoiceId)` — mirroring the kind-locked production invoice surface against `/api/v1/sandbox/invoices`. The production `/api/v1/invoices` endpoints are production-kind-only and reject sandbox projects with `production_project_required`; sandbox projects must use these mirrors. Same request/response schemas and `(project_id, external_id)` idempotency contract; subject to the sandbox 10k active-invoice cap (`TxnodSandboxActiveInvoiceCapReachedError`).
+- New sandbox webhook delivery-log methods on `client.sandbox.*` — `listWebhookEvents(query?)` and `resendWebhookEvent(eventId)` — mirroring the kind-locked production `/api/v1/webhooks/events` surface against `/api/v1/sandbox/webhooks/events`. Same snake_case filters and response envelopes (`WebhookEventListResponse`, `WebhookEventResendResponse`); every listed row corresponds to an envelope delivered with `mode: 'sandbox'`.
+- New re-exported types from `@txnod/shared`: `ClockAdvance`, `CursorPaginatedInvoiceResponse`, `CursorPaginatedOrphanPaymentResponse`, `InvoiceCreateRequest`, `InvoiceResponse`, `InvoiceSearchQuery`, `OrphanAttributeRequest`, `OrphanPaymentListQuery`, `QuoteQuery`, `QuoteResponse`, `RatesQuery`, `RatesResponse`, `SimulateEvent`, `SimulateLatePayment`, `SimulateOverpaid`, `SimulatePartial`, `WalletsListResponse`, `WebhookEventListApiQuery`, `WebhookEventListResponse`, `WebhookEventResendResponse`.
+
+### Changed
+
+- `amount_usd` on invoice creation now enforces server-side bounds: minimum `0.01`, maximum `1_000_000_000`. Sub-cent values previously scaled to 0 base units and surfaced as an opaque HTTP 500; out-of-bounds values now reject at the validation edge with a typed message. (Pre-launch stance: shipped as a minor with no compatibility shim.)
+
+### Fixed
+
+- `verifyAddress` no longer throws `AddressVerificationError` for every EVM invoice (ETH / Polygon / BSC). The gateway serves canonical-lowercase EVM addresses while the verifier derives the EIP-55 checksummed form; the comparison was strict-equality and failed on casing alone. EVM hex addresses are case-insensitive by definition (EIP-55 is a display-layer checksum), so the comparison now lowercases both sides. TRON (base58check), TON (base64url), and bech32-chain comparisons remain exact.
+
 ## [1.0.2] - 2026-05-11
 
 ### Added

package/README.md

@@ -55,6 +55,29 @@ Operators enable coins per-project in the TxNod dashboard; a single `TxnodClient
 | `ton` | `ton` | TON native (Toncoin). |
 | `usdt_ton` | `ton` | Tether USD jetton on TON. |
 
+### Coin/chain helpers and amount conversion
+
+The package root exports a small set of pure helpers for working with coins, chains, and on-chain amounts:
+
+- `COIN_TO_CHAIN` — a `Record<Coin, Chain>` map; `coinToChain(coin)` is the function form. Use either when an API that speaks `coin` (invoices) meets one that speaks `chain` (orphan payments).
+- `COIN_DECIMALS` — a `Record<Coin, number>` of base-unit decimal places per coin.
+- `toBaseUnits(coin, humanString)` — converts a human decimal (`"1.5"`) into integer base units. Throws on malformed input, too many fractional digits for the coin, or a zero result.
+- `fromBaseUnits(coin, baseUnitsString)` — the inverse: formats integer base units (e.g. an invoice/webhook `amount_units` string) as a human decimal, trimming trailing zeros.
+
+```ts
+import { coinToChain, COIN_DECIMALS, toBaseUnits, fromBaseUnits } from '@txnod/sdk';
+
+coinToChain('usdt_trc20'); // 'tron'
+COIN_DECIMALS.usdt_bep20; // 18
+
+// BEP-20 trap: usdt_bep20 / usdc_bep20 / bnb use 18 decimals on-chain, unlike
+// the 6-decimal ERC-20 / TRC-20 / Polygon stablecoins (and TON, which is 9).
+// Always round-trip `amount_units` through fromBaseUnits rather than assuming 6.
+fromBaseUnits('usdt_bep20', '1500000000000000000'); // '1.5'
+fromBaseUnits('usdt_trc20', '1500000');             // '1.5'
+toBaseUnits('usdt_bep20', '1.5');                   // '1500000000000000000'
+```
+
 ## SDK-side address verification (`TXNOD_<chain>_XPUB`)
 
 When the matching env var is set, `createInvoice` automatically derives the expected deposit address from the operator's xpub at the invoice's `derivation_path` and rejects with `AddressVerificationError` on mismatch. This is the SDK's defense against a compromised gateway silently swapping the deposit address. Set per chain you accept; omit to skip verification on that chain.
@@ -168,6 +191,35 @@ export async function POST(request: Request): Promise<Response> {
 }
 ```
 
+### Per-invoice amount matching — `matching_mode`
+
+`createInvoice` accepts an optional `matching_mode` that controls how strictly a deposit's amount must match the invoice at attribution time:
+
+| Mode | Meaning | Use for |
+|---|---|---|
+| `exact` | The deposit amount must equal the invoice amount. | Standard fixed-price checkout. |
+| `at_least` | Any amount **≥** the invoice amount matches (overpayment is accepted). | Tips on top of a price, "pay at least X". |
+| `any` | **Any** amount matches. | Donations, pay-what-you-want, top-ups. |
+
+Omit the field to inherit the project's configured default (set in the dashboard). The chosen mode is echoed back on every invoice response as `matching_mode`.
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+declare const client: TxnodClient;
+
+// Donation: accept whatever the supporter sends.
+const donation = await client.createInvoice({
+  external_id: 'donation-2026-06',
+  coin: 'usdt_trc20',
+  amount_usd: 5, // suggested amount; `any` accepts more or less
+  matching_mode: 'any',
+});
+console.log(donation.matching_mode); // 'any'
+```
+
+> **Saturation caveat (`overlay_matching_mode_required_exact`, HTTP 422):** when the operator's address pool is fully allocated, a new invoice may have to share a deposit address with another invoice. In that case TxNod can only tell the two apart by amount, so only `exact` is permitted — `at_least` and `any` reject with `TxnodOverlayMatchingModeError`. Catch it and retry with `exact`, or surface "checkout temporarily unavailable" and notify the operator to grow the pool.
+
 ## Quickstart — verify a webhook
 
 A complete `app/api/txnod-webhook/route.ts` that validates the inbound HMAC and narrows the typed event:
@@ -205,6 +257,84 @@ export async function POST(request: Request): Promise<Response> {
 }
 ```
 
+`verifyWebhookSignature(headers, rawBody, secret)` is framework-agnostic on both arguments:
+
+- **`headers`** accepts either the Web `Headers` object (shown above) or any plain header bag whose values are `string | string[] | undefined` — a structural superset of Node's `IncomingHttpHeaders`, so Express/Fastify `req.headers` work unchanged. The accepted shape is exported as the type `WebhookHeadersInput`.
+- **`rawBody`** accepts `string | Buffer`. Node HTTP frameworks hand back the raw body as a `Buffer`, so you can pass it straight through with no `.toString()` boilerplate.
+
+```js
+import express from 'express';
+import { verifyWebhookSignature } from '@txnod/sdk';
+
+const app = express();
+// Capture the *raw* bytes — HMAC is computed over the exact payload, so this
+// must run before any JSON body parser rewrites the buffer.
+app.post('/api/txnod-webhook', express.raw({ type: '*/*' }), (req, res) => {
+  // req.headers is a WebhookHeadersInput (IncomingHttpHeaders); req.body is a
+  // Buffer — both accepted by verifyWebhookSignature with no conversion.
+  const event = verifyWebhookSignature(req.headers, req.body, process.env.TXNOD_WEBHOOK_SECRET);
+  if (event.event_type === 'invoice.paid') {
+    console.log('paid invoice', event.data.invoice_id);
+  }
+  res.json({ ok: true });
+});
+```
+
+### Webhook idempotency and reorg restores — read this
+
+Key your webhook idempotency on the envelope's unique `event_id` — **never on `tx_hash`**. A blockchain reorg can roll back a confirmed payment and then re-confirm it, and the SDK surfaces that cycle explicitly so you don't lose (or silently drop) the restore:
+
+1. The invoice confirms → `invoice.paid` with `event_id = A` (and `data.reason` absent). Fulfill the order.
+2. A reorg orphans the confirming block → `invoice.reverted`. Reverse the credit.
+3. The payment re-lands on the canonical chain → a **new** `invoice.paid` arrives with a **fresh** `event_id = C` and **`data.reason === 'reorg'`**. This is a **restore**: re-apply the credit.
+
+The restoring `invoice.paid` may carry the **same `tx_hash`** as the original. If you dedupe on `tx_hash`, you would drop the restore and the user would stay un-credited after you reversed them on step 2. So:
+
+- **Idempotency key = `event_id`** (unique per delivery). Never `tx_hash`.
+- **The reorg-restore signal = `data.reason === 'reorg'`** on an `invoice.paid`.
+- **`resent_from_event_id`** is honest redelivery lineage — `null` on first-time events, set to the original event's `event_id` for BOTH operator-triggered resends **and** reorg re-confirmations. It is *not* a restore flag; an operator resend (`resent_from_event_id` set, `data.reason` not `'reorg'`) is just a duplicate delivery, absorbed by your `event_id` dedupe.
+
+```ts
+import { verifyWebhookSignature } from '@txnod/sdk';
+
+export async function POST(request: Request): Promise<Response> {
+  const event = verifyWebhookSignature(
+    request.headers,
+    await request.text(),
+    process.env.TXNOD_WEBHOOK_SECRET!,
+  );
+
+  // Dedupe on event_id — the ONLY safe idempotency key. Never tx_hash.
+  // This also absorbs operator resends (a duplicate of an already-seen event).
+  if (await alreadyProcessed(event.event_id)) {
+    return Response.json({ ok: true });
+  }
+
+  if (event.event_type === 'invoice.reverted') {
+    await reverseCredit(event.data.invoice_id); // undo fulfillment
+  } else if (event.event_type === 'invoice.paid') {
+    if (event.data.reason === 'reorg') {
+      // Restore after a reorg revert. Same invoice (and possibly the same
+      // tx_hash) — re-apply the credit; do NOT drop it as a duplicate.
+      await restoreCredit(event.data.invoice_id);
+    } else {
+      await fulfillOrder(event.data.invoice_id); // first-time payment
+    }
+  }
+
+  await markProcessed(event.event_id);
+  return Response.json({ ok: true });
+}
+
+declare function alreadyProcessed(eventId: string): Promise<boolean>;
+declare function markProcessed(eventId: string): Promise<void>;
+declare function fulfillOrder(invoiceId: string): Promise<void>;
+declare function reverseCredit(invoiceId: string): Promise<void>;
+declare function restoreCredit(invoiceId: string): Promise<void>;
+```
+
+Correlate the revert/restore pair by `data.invoice_id`. An invoice that goes through the revert/re-confirm cycle legitimately emits `invoice.paid` more than once — `invoice.paid` is **not** a once-per-invoice event.
+
 ## Polygon PoS — create and verify (usdt_polygon)
 
 Polygon PoS invoices settle after 128 blocks — the Heimdall checkpoint depth at which the SDK marks an `invoice.paid` event terminal. The snippet below creates a USDT-Polygon invoice and, in the webhook route, matches the inbound `invoice.paid` event against the invoice id.
@@ -365,6 +495,25 @@ console.log(client.lastRequestId);
 
 `TXNOD_SDK_LOG_LEVEL` controls the SDK's internal pino logger (default `warn`). Set to `info`/`debug` for more verbose internals. The logger redacts `xpub` and `apiSecret` keys.
 
+### Resolved environment — `client.environment`
+
+`client.environment` reports the SDK's resolved deployment context as `'production'`, `'non-production'`, or `'unknown'`, after applying the constructor `environment` option and the `TXNOD_ENVIRONMENT` / `NODE_ENV` fallbacks. Read it at startup to fail fast on a misconfigured deploy, or to gate logging verbosity.
+
+```ts
+import { TxnodClient } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+});
+
+// Fail fast instead of silently signing production requests with a
+// non-production wiring.
+if (client.environment !== 'production') {
+  throw new Error(`TxNod: expected production, got ${client.environment}`);
+}
+```
+
 ## Idempotent invoice creation — `createOrGetInvoice`
 
 If your checkout flow may retry the same `external_id` (network glitch, queue at-least-once delivery), `createOrGetInvoice` collapses the "create-then-conflict-then-search" pattern into one call:

package/dist/_shared/index.d.ts

@@ -5,17 +5,27 @@
 
 export type InvoiceStatus = "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | "ambiguous";
 
-export type InvoiceCreateRequest = { external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; amount_usd?: number | undefined; amount_crypto?: string | undefined; callback_url?: string | undefined; metadata?: Record<string, unknown> | undefined; };
+export type InvoiceCreateRequest = { external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; amount_usd?: number | undefined; amount_crypto?: string | undefined; callback_url?: string | undefined; metadata?: Record<string, unknown> | undefined; matching_mode?: "any" | "exact" | "at_least" | undefined; };
 
-export type InvoiceResponse = { id: string; project_id: string; external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; address: string; amount_crypto: string; amount_crypto_units: string; amount_usd: number | null; rate_snapshot: { rate: string; source: "coingecko"; quoted_at: string; rate_is_stale: boolean; rate_age_seconds: number; } | null; payment_token: string | null; payment_uri: string; callback_url: string | null; metadata: Record<string, unknown> | null; matching_mode: "any" | "exact" | "at_least"; confirmation_threshold: number; status: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | "ambiguous"; expires_at: number; expires_at_iso: string; created_at: number; created_at_iso: string; derivation_path?: string | undefined; verification_standard?: "bip84" | "bip44" | "cip1852" | "bip44_ed25519" | undefined; transactions?: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string | null; tx_output_index: number | null; amount_units: string; block_height: number | null; confirmations: number; received_at: number; received_at_iso: string; orphaned_at: number | null; orphaned_at_iso: string | null; }[] | undefined; confirmations?: number | undefined; };
+export type InvoiceResponse = { id: string; project_id: string; external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; address: string; amount_crypto: string; amount_crypto_units: string; amount_usd: number | null; rate_snapshot: { rate: string; source: "coinpaprika" | "coingecko"; quoted_at: string; rate_is_stale: boolean; rate_age_seconds: number; } | null; payment_token: string | null; payment_uri: string; callback_url: string | null; metadata: Record<string, unknown> | null; matching_mode: "any" | "exact" | "at_least"; confirmation_threshold: number; status: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | "ambiguous"; expires_at: number; expires_at_iso: string; created_at: number; created_at_iso: string; derivation_path?: string | undefined; verification_standard?: "bip84" | "bip44" | "cip1852" | "bip44_ed25519" | undefined; transactions?: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string | null; tx_output_index: number | null; amount_units: string; block_height: number | null; confirmations: number; received_at: number; received_at_iso: string; orphaned_at: number | null; orphaned_at_iso: string | null; }[] | undefined; confirmations?: number | undefined; };
+
+export type InvoiceDetailResponse = { id: string; project_id: string; external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; address: string; amount_crypto: string; amount_crypto_units: string; amount_usd: number | null; rate_snapshot: { rate: string; source: "coinpaprika" | "coingecko"; quoted_at: string; rate_is_stale: boolean; rate_age_seconds: number; } | null; payment_token: string | null; payment_uri: string; callback_url: string | null; metadata: Record<string, unknown> | null; matching_mode: "any" | "exact" | "at_least"; confirmation_threshold: number; status: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | "ambiguous"; expires_at: number; expires_at_iso: string; created_at: number; created_at_iso: string; transactions: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string | null; tx_output_index: number | null; amount_units: string; block_height: number | null; confirmations: number; received_at: number; received_at_iso: string; orphaned_at: number | null; orphaned_at_iso: string | null; }[]; confirmations: number; derivation_path?: string | undefined; verification_standard?: "bip84" | "bip44" | "cip1852" | "bip44_ed25519" | undefined; };
 
 export type InvoiceSearchQuery = { external_id?: string | undefined; address?: string | undefined; tx_hash?: string | undefined; amount?: string | undefined; status?: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | "ambiguous" | undefined; date_from?: string | undefined; date_to?: string | undefined; cursor?: string | undefined; limit?: number | undefined; };
 
-export type CursorPaginatedInvoiceResponse = { items: { id: string; project_id: string; external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; address: string; amount_crypto: string; amount_crypto_units: string; amount_usd: number | null; rate_snapshot: { rate: string; source: "coingecko"; quoted_at: string; rate_is_stale: boolean; rate_age_seconds: number; } | null; payment_token: string | null; payment_uri: string; callback_url: string | null; metadata: Record<string, unknown> | null; matching_mode: "any" | "exact" | "at_least"; confirmation_threshold: number; status: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | "ambiguous"; expires_at: number; expires_at_iso: string; created_at: number; created_at_iso: string; derivation_path?: string | undefined; verification_standard?: "bip84" | "bip44" | "cip1852" | "bip44_ed25519" | undefined; transactions?: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string | null; tx_output_index: number | null; amount_units: string; block_height: number | null; confirmations: number; received_at: number; received_at_iso: string; orphaned_at: number | null; orphaned_at_iso: string | null; }[] | undefined; confirmations?: number | undefined; }[]; next_cursor?: string | undefined; };
+export type CursorPaginatedInvoiceResponse = { items: { id: string; project_id: string; external_id: string; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; address: string; amount_crypto: string; amount_crypto_units: string; amount_usd: number | null; rate_snapshot: { rate: string; source: "coinpaprika" | "coingecko"; quoted_at: string; rate_is_stale: boolean; rate_age_seconds: number; } | null; payment_token: string | null; payment_uri: string; callback_url: string | null; metadata: Record<string, unknown> | null; matching_mode: "any" | "exact" | "at_least"; confirmation_threshold: number; status: "pending" | "detected" | "paid" | "overpaid" | "partial" | "expired" | "expired_paid_late" | "reverted" | "cancelled" | "ambiguous"; expires_at: number; expires_at_iso: string; created_at: number; created_at_iso: string; derivation_path?: string | undefined; verification_standard?: "bip84" | "bip44" | "cip1852" | "bip44_ed25519" | undefined; transactions?: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string | null; tx_output_index: number | null; amount_units: string; block_height: number | null; confirmations: number; received_at: number; received_at_iso: string; orphaned_at: number | null; orphaned_at_iso: string | null; }[] | undefined; confirmations?: number | undefined; }[]; next_cursor?: string | undefined; };
+
+export type ClaimByTxRequest = { tx_hash: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; };
+
+export type ClaimByTxResponse = { request_id: string; status: "auto_attributed" | "pending_finality" | "pending_review" | "rejected"; resolved_facts: { sender_address?: string | undefined; recipient_address?: string | undefined; amount_units?: string | undefined; tx_timestamp_ms?: number | undefined; confirmations?: number | undefined; tx_output_index?: number | null | undefined; tx_lt?: string | null | undefined; ton_mc_block_depth?: number | null | undefined; token_contract?: string | undefined; }; terminal_status?: "paid" | "overpaid" | "partial" | undefined; rejection_reason?: "tx_not_found_or_incomplete" | "tx_already_attributed" | undefined; };
+
+export type ManualClaimFinalityThreshold = ManualClaimFinalityThreshold;
+
+export type ResolvedFacts = { sender_address: string; recipient_address: string; amount_units: string; tx_timestamp_ms: number; confirmations: number; tx_output_index: number | null; tx_lt: string | null; ton_mc_block_depth: number | null; token_contract?: string | undefined; };
 
 export type OrphanPaymentListQuery = { attributed?: boolean | undefined; chain?: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc" | undefined; tx_hash?: string | undefined; date_from?: string | undefined; date_to?: string | undefined; amount_units_gte?: string | undefined; amount_units_lte?: string | undefined; cursor?: string | undefined; limit?: number | undefined; };
 
-export type CursorPaginatedOrphanPaymentResponse = { items: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; tx_hash: string; to_address: string; tx_output_index: number; amount_units: string; block_height: number | null; received_at: number; received_at_iso: string; attributed: boolean; attributed_invoice_id: string | null; attributed_external_id: string | null; attributed_at: number | null; attributed_at_iso: string | null; }[]; next_cursor?: string | undefined; };
+export type CursorPaginatedOrphanPaymentResponse = { items: { id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton" | null; tx_hash: string; to_address: string; tx_output_index: number; amount_units: string; block_height: number | null; received_at: number; received_at_iso: string; attributed: boolean; attributed_invoice_id: string | null; attributed_external_id: string | null; attributed_at: number | null; attributed_at_iso: string | null; }[]; next_cursor?: string | undefined; };
 
 export type OrphanAttributeRequest = { external_id: string; user_id?: string | undefined; metadata?: Record<string, unknown> | undefined; to_address?: string | undefined; tx_output_index?: number | undefined; };
 
@@ -25,9 +35,9 @@ export type WebhookEventListResponse = { items: { id: string; event_type: "invoi
 
 export type WebhookEventResendResponse = { event_id: string; original_event_id: string; event_type: "invoice.detected" | "invoice.paid" | "invoice.overpaid" | "invoice.partial" | "invoice.expired" | "invoice.expired_paid_late" | "invoice.reverted" | "invoice.ambiguous"; project_id: string; invoice_id: string | null; target_url: string | null; created_at: number; created_at_iso: string; };
 
-export type WebhookEvent = { event_id: string; event_type: "invoice.detected"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.paid"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.overpaid"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.partial"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.expired"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.expired_paid_late"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.reverted"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; } | { event_id: string; event_type: "invoice.ambiguous"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; };
+export type WebhookEvent = { event_id: string; event_type: "invoice.detected"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; } | { event_id: string; event_type: "invoice.paid"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; } | { event_id: string; event_type: "invoice.overpaid"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; } | { event_id: string; event_type: "invoice.partial"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; } | { event_id: string; event_type: "invoice.expired"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; } | { event_id: string; event_type: "invoice.expired_paid_late"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; } | { event_id: string; event_type: "invoice.reverted"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; } | { event_id: string; event_type: "invoice.ambiguous"; created_at: number; created_at_iso: string; project_id: string; data: { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; }; attempt: number; mode: "production" | "testnet" | "sandbox"; resent_from_event_id: string | null; };
 
-export type WebhookEventData = { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; };
+export type WebhookEventData = { invoice_id: string; project_id: string; chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; coin: "btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton"; external_id: string; metadata: Record<string, unknown> | null; amount_crypto: string; amount_usd: string | null; tx_hash: string; to_address: string | null; amount_units: string; confirmations: number; block_height: number | null; payment_token: string | null; matched_payment_token: string | null; chain_specific: { ton?: { tx_lt: string; mc_block_seqno: number; block_ref: { workchain: number; shard: string; seqno: number; }; jetton_master?: string | undefined; } | undefined; } | null; reason?: "reorg" | "late_arrival" | undefined; };
 
 export type WebhookEventMode = "production" | "testnet" | "sandbox";
 
@@ -35,15 +45,15 @@ export type WebhookEventType = "invoice.detected" | "invoice.paid" | "invoice.ov
 
 export type RatesQuery = { coins?: string | undefined; };
 
-export type RatesResponse = { quoted_at: string; source: "coingecko"; rates: Partial<Record<"btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton", { rate: string; rate_is_stale: boolean; rate_age_seconds: number; }>>; indicative_notice: string; };
+export type RatesResponse = { quoted_at: string; source: "coinpaprika" | "coingecko"; rates: Partial<Record<"btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton", { rate: string; rate_is_stale: boolean; rate_age_seconds: number; }>>; indicative_notice: string; };
 
 export type QuoteQuery = { amount_usd: number; coins?: string | undefined; };
 
-export type QuoteResponse = { amount_usd: number; quoted_at: string; source: "coingecko"; quotes: Partial<Record<"btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton", { amount_crypto: string; amount_crypto_units: string; rate: string; rate_is_stale: boolean; rate_age_seconds: number; }>>; indicative_notice: string; };
+export type QuoteResponse = { amount_usd: number; quoted_at: string; source: "coinpaprika" | "coingecko"; quotes: Partial<Record<"btc" | "eth" | "usdt_erc20" | "usdc_erc20" | "trx" | "usdt_trc20" | "ada" | "pol" | "usdt_polygon" | "usdc_polygon" | "bnb" | "usdt_bep20" | "usdc_bep20" | "ton" | "usdt_ton", { amount_crypto: string; amount_crypto_units: string; rate: string; rate_is_stale: boolean; rate_age_seconds: number; }>>; indicative_notice: string; };
 
-export type ErrorCode = "validation_error" | "invalid_coin" | "invalid_xpub_format" | "invalid_webhook_url" | "auth_invalid" | "signature_invalid" | "signature_replayed" | "timestamp_out_of_window" | "key_suspended" | "project_suspended" | "permission_denied" | "key_revoked" | "invoice_not_found" | "project_not_found" | "wallet_not_found" | "external_id_conflict" | "xpub_not_verified" | "coin_not_enabled" | "amount_out_of_range" | "rate_limit_exceeded" | "pool_exhausted" | "webhook_capacity_exhausted" | "duplicate_provider_webhook_id" | "otp_expired" | "otp_used" | "invite_invalid" | "internal_error" | "invoice_not_cancellable" | "invalid_state_transition" | "orphan_not_found" | "orphan_already_attributed" | "event_not_found" | "wallet_not_bound" | "wallet_not_owned" | "wallet_has_active_bindings" | "wallet_kind_mismatch" | "subscription_expired" | "tron_no_activated_addresses_available" | "ton_operator_wallet_not_deployed" | "ton_invalid_wallet_version" | "ton_jetton_resolve_failed" | "ton_comment_parse_failed" | "tonconnect_payload_expired" | "tonconnect_payload_unknown" | "tonconnect_domain_mismatch" | "tonconnect_timestamp_skew" | "tonconnect_unknown_wallet_version" | "tonconnect_signature_invalid" | "tonconnect_network_mismatch" | "sandbox_project_required" | "production_project_required" | "sandbox_per_operator_cap_reached" | "sandbox_key_against_production_project" | "production_key_against_sandbox_project" | "sandbox_provisioning_failed" | "sandbox_invoice_transition_invalid" | "sandbox_invoice_not_found" | "sandbox_invoice_terminal" | "sandbox_rate_limit_exceeded" | "sandbox_reset_failed" | "sandbox_delete_failed" | "sandbox_active_invoice_cap_reached" | "overlay_matching_mode_required_exact" | "tx_not_found_or_incomplete" | "tx_already_attributed" | "manual_claim_rate_limit_exceeded" | "manual_claim_not_pending_review" | "manual_claim_invoice_not_open";
+export type ErrorCode = "tx_not_found_or_incomplete" | "tx_already_attributed" | "validation_error" | "invalid_coin" | "invalid_xpub_format" | "invalid_webhook_url" | "auth_invalid" | "signature_invalid" | "signature_replayed" | "timestamp_out_of_window" | "key_suspended" | "project_suspended" | "permission_denied" | "key_revoked" | "invoice_not_found" | "project_not_found" | "wallet_not_found" | "external_id_conflict" | "xpub_not_verified" | "coin_not_enabled" | "amount_out_of_range" | "rate_limit_exceeded" | "pool_exhausted" | "webhook_capacity_exhausted" | "duplicate_provider_webhook_id" | "otp_expired" | "otp_used" | "invite_invalid" | "internal_error" | "invoice_not_cancellable" | "invalid_state_transition" | "orphan_not_found" | "orphan_already_attributed" | "event_not_found" | "wallet_not_bound" | "wallet_not_owned" | "wallet_has_active_bindings" | "wallet_kind_mismatch" | "subscription_expired" | "tron_no_activated_addresses_available" | "ton_operator_wallet_not_deployed" | "ton_invalid_wallet_version" | "ton_jetton_resolve_failed" | "ton_comment_parse_failed" | "tonconnect_payload_expired" | "tonconnect_payload_unknown" | "tonconnect_domain_mismatch" | "tonconnect_timestamp_skew" | "tonconnect_unknown_wallet_version" | "tonconnect_signature_invalid" | "tonconnect_network_mismatch" | "sandbox_project_required" | "production_project_required" | "sandbox_per_operator_cap_reached" | "sandbox_key_against_production_project" | "production_key_against_sandbox_project" | "sandbox_provisioning_failed" | "sandbox_invoice_transition_invalid" | "sandbox_invoice_not_found" | "sandbox_invoice_terminal" | "sandbox_rate_limit_exceeded" | "sandbox_reset_failed" | "sandbox_delete_failed" | "sandbox_active_invoice_cap_reached" | "overlay_matching_mode_required_exact" | "manual_claim_rate_limit_exceeded" | "manual_claim_not_pending_review" | "manual_claim_invoice_not_open" | "event_not_resendable" | "rate_quote_unavailable";
 
-export type ProblemDetails = { type: "about:blank"; title: string; status: number; error_code: "validation_error" | "invalid_coin" | "invalid_xpub_format" | "invalid_webhook_url" | "auth_invalid" | "signature_invalid" | "signature_replayed" | "timestamp_out_of_window" | "key_suspended" | "project_suspended" | "permission_denied" | "key_revoked" | "invoice_not_found" | "project_not_found" | "wallet_not_found" | "external_id_conflict" | "xpub_not_verified" | "coin_not_enabled" | "amount_out_of_range" | "rate_limit_exceeded" | "pool_exhausted" | "webhook_capacity_exhausted" | "duplicate_provider_webhook_id" | "otp_expired" | "otp_used" | "invite_invalid" | "internal_error" | "invoice_not_cancellable" | "invalid_state_transition" | "orphan_not_found" | "orphan_already_attributed" | "event_not_found" | "wallet_not_bound" | "wallet_not_owned" | "wallet_has_active_bindings" | "wallet_kind_mismatch" | "subscription_expired" | "tron_no_activated_addresses_available" | "ton_operator_wallet_not_deployed" | "ton_invalid_wallet_version" | "ton_jetton_resolve_failed" | "ton_comment_parse_failed" | "tonconnect_payload_expired" | "tonconnect_payload_unknown" | "tonconnect_domain_mismatch" | "tonconnect_timestamp_skew" | "tonconnect_unknown_wallet_version" | "tonconnect_signature_invalid" | "tonconnect_network_mismatch" | "sandbox_project_required" | "production_project_required" | "sandbox_per_operator_cap_reached" | "sandbox_key_against_production_project" | "production_key_against_sandbox_project" | "sandbox_provisioning_failed" | "sandbox_invoice_transition_invalid" | "sandbox_invoice_not_found" | "sandbox_invoice_terminal" | "sandbox_rate_limit_exceeded" | "sandbox_reset_failed" | "sandbox_delete_failed" | "sandbox_active_invoice_cap_reached" | "overlay_matching_mode_required_exact" | "tx_not_found_or_incomplete" | "tx_already_attributed" | "manual_claim_rate_limit_exceeded" | "manual_claim_not_pending_review" | "manual_claim_invoice_not_open"; request_id: string; errors?: unknown[] | undefined; wallet_id?: string | undefined; current_status?: string | undefined; requested_event?: string | undefined; current_count?: number | undefined; reset_url?: string | undefined; failed_step?: string | null | undefined; wallet_kind?: "production" | "testnet" | "sandbox" | undefined; project_kind?: "production" | "testnet" | "sandbox" | undefined; attempted_mode?: "any" | "at_least" | undefined; };
+export type ProblemDetails = { type: "about:blank"; title: string; status: number; error_code: "tx_not_found_or_incomplete" | "tx_already_attributed" | "validation_error" | "invalid_coin" | "invalid_xpub_format" | "invalid_webhook_url" | "auth_invalid" | "signature_invalid" | "signature_replayed" | "timestamp_out_of_window" | "key_suspended" | "project_suspended" | "permission_denied" | "key_revoked" | "invoice_not_found" | "project_not_found" | "wallet_not_found" | "external_id_conflict" | "xpub_not_verified" | "coin_not_enabled" | "amount_out_of_range" | "rate_limit_exceeded" | "pool_exhausted" | "webhook_capacity_exhausted" | "duplicate_provider_webhook_id" | "otp_expired" | "otp_used" | "invite_invalid" | "internal_error" | "invoice_not_cancellable" | "invalid_state_transition" | "orphan_not_found" | "orphan_already_attributed" | "event_not_found" | "wallet_not_bound" | "wallet_not_owned" | "wallet_has_active_bindings" | "wallet_kind_mismatch" | "subscription_expired" | "tron_no_activated_addresses_available" | "ton_operator_wallet_not_deployed" | "ton_invalid_wallet_version" | "ton_jetton_resolve_failed" | "ton_comment_parse_failed" | "tonconnect_payload_expired" | "tonconnect_payload_unknown" | "tonconnect_domain_mismatch" | "tonconnect_timestamp_skew" | "tonconnect_unknown_wallet_version" | "tonconnect_signature_invalid" | "tonconnect_network_mismatch" | "sandbox_project_required" | "production_project_required" | "sandbox_per_operator_cap_reached" | "sandbox_key_against_production_project" | "production_key_against_sandbox_project" | "sandbox_provisioning_failed" | "sandbox_invoice_transition_invalid" | "sandbox_invoice_not_found" | "sandbox_invoice_terminal" | "sandbox_rate_limit_exceeded" | "sandbox_reset_failed" | "sandbox_delete_failed" | "sandbox_active_invoice_cap_reached" | "overlay_matching_mode_required_exact" | "manual_claim_rate_limit_exceeded" | "manual_claim_not_pending_review" | "manual_claim_invoice_not_open" | "event_not_resendable" | "rate_quote_unavailable"; request_id: string; errors?: unknown[] | undefined; wallet_id?: string | undefined; current_status?: string | undefined; requested_event?: string | undefined; current_count?: number | undefined; reset_url?: string | undefined; failed_step?: string | null | undefined; wallet_kind?: "production" | "testnet" | "sandbox" | undefined; project_kind?: "production" | "testnet" | "sandbox" | undefined; attempted_mode?: "any" | "at_least" | undefined; };
 
 export type Chain = "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc";
 
@@ -63,6 +73,6 @@ export type SimulatePartial = { fraction?: number | undefined; amountUnits?: str
 
 export type WalletsListResponse = { items: { chain: "btc" | "eth" | "ada" | "ton" | "tron" | "polygon" | "bsc"; xpub: string | null; derivation_path: string; stake_address: string | null; ed25519_pubkey_hex: string | null; }[]; };
 
-export declare const ERROR_CODES: readonly ["validation_error", "invalid_coin", "invalid_xpub_format", "invalid_webhook_url", "auth_invalid", "signature_invalid", "signature_replayed", "timestamp_out_of_window", "key_suspended", "project_suspended", "permission_denied", "key_revoked", "invoice_not_found", "project_not_found", "wallet_not_found", "external_id_conflict", "xpub_not_verified", "coin_not_enabled", "amount_out_of_range", "rate_limit_exceeded", "pool_exhausted", "webhook_capacity_exhausted", "duplicate_provider_webhook_id", "otp_expired", "otp_used", "invite_invalid", "internal_error", "invoice_not_cancellable", "invalid_state_transition", "orphan_not_found", "orphan_already_attributed", "event_not_found", "wallet_not_bound", "wallet_not_owned", "wallet_has_active_bindings", "wallet_kind_mismatch", "subscription_expired", "tron_no_activated_addresses_available", "ton_operator_wallet_not_deployed", "ton_invalid_wallet_version", "ton_jetton_resolve_failed", "ton_comment_parse_failed", "tonconnect_payload_expired", "tonconnect_payload_unknown", "tonconnect_domain_mismatch", "tonconnect_timestamp_skew", "tonconnect_unknown_wallet_version", "tonconnect_signature_invalid", "tonconnect_network_mismatch", "sandbox_project_required", "production_project_required", "sandbox_per_operator_cap_reached", "sandbox_key_against_production_project", "production_key_against_sandbox_project", "sandbox_provisioning_failed", "sandbox_invoice_transition_invalid", "sandbox_invoice_not_found", "sandbox_invoice_terminal", "sandbox_rate_limit_exceeded", "sandbox_reset_failed", "sandbox_delete_failed", "sandbox_active_invoice_cap_reached", "overlay_matching_mode_required_exact", "tx_not_found_or_incomplete", "tx_already_attributed", "manual_claim_rate_limit_exceeded", "manual_claim_not_pending_review", "manual_claim_invoice_not_open"];
+export declare const ERROR_CODES: readonly ["validation_error", "invalid_coin", "invalid_xpub_format", "invalid_webhook_url", "auth_invalid", "signature_invalid", "signature_replayed", "timestamp_out_of_window", "key_suspended", "project_suspended", "permission_denied", "key_revoked", "invoice_not_found", "project_not_found", "wallet_not_found", "external_id_conflict", "xpub_not_verified", "coin_not_enabled", "amount_out_of_range", "rate_limit_exceeded", "pool_exhausted", "webhook_capacity_exhausted", "duplicate_provider_webhook_id", "otp_expired", "otp_used", "invite_invalid", "internal_error", "invoice_not_cancellable", "invalid_state_transition", "orphan_not_found", "orphan_already_attributed", "event_not_found", "wallet_not_bound", "wallet_not_owned", "wallet_has_active_bindings", "wallet_kind_mismatch", "subscription_expired", "tron_no_activated_addresses_available", "ton_operator_wallet_not_deployed", "ton_invalid_wallet_version", "ton_jetton_resolve_failed", "ton_comment_parse_failed", "tonconnect_payload_expired", "tonconnect_payload_unknown", "tonconnect_domain_mismatch", "tonconnect_timestamp_skew", "tonconnect_unknown_wallet_version", "tonconnect_signature_invalid", "tonconnect_network_mismatch", "sandbox_project_required", "production_project_required", "sandbox_per_operator_cap_reached", "sandbox_key_against_production_project", "production_key_against_sandbox_project", "sandbox_provisioning_failed", "sandbox_invoice_transition_invalid", "sandbox_invoice_not_found", "sandbox_invoice_terminal", "sandbox_rate_limit_exceeded", "sandbox_reset_failed", "sandbox_delete_failed", "sandbox_active_invoice_cap_reached", "overlay_matching_mode_required_exact", "tx_not_found_or_incomplete", "tx_already_attributed", "manual_claim_rate_limit_exceeded", "manual_claim_not_pending_review", "manual_claim_invoice_not_open", "event_not_resendable", "rate_quote_unavailable"];
 
-export declare const ERROR_CODE_STATUS: { readonly validation_error: 400; readonly invalid_coin: 400; readonly invalid_xpub_format: 400; readonly invalid_webhook_url: 400; readonly auth_invalid: 401; readonly signature_invalid: 401; readonly signature_replayed: 401; readonly timestamp_out_of_window: 401; readonly key_suspended: 403; readonly project_suspended: 403; readonly permission_denied: 403; readonly key_revoked: 403; readonly invoice_not_found: 404; readonly project_not_found: 404; readonly wallet_not_found: 404; readonly external_id_conflict: 409; readonly xpub_not_verified: 409; readonly coin_not_enabled: 422; readonly amount_out_of_range: 422; readonly rate_limit_exceeded: 429; readonly pool_exhausted: 503; readonly webhook_capacity_exhausted: 503; readonly duplicate_provider_webhook_id: 409; readonly otp_expired: 400; readonly otp_used: 400; readonly invite_invalid: 400; readonly internal_error: 500; readonly invoice_not_cancellable: 409; readonly invalid_state_transition: 409; readonly orphan_not_found: 404; readonly orphan_already_attributed: 409; readonly event_not_found: 404; readonly wallet_not_bound: 422; readonly wallet_not_owned: 403; readonly wallet_has_active_bindings: 409; readonly wallet_kind_mismatch: 422; readonly subscription_expired: 402; readonly tron_no_activated_addresses_available: 422; readonly ton_operator_wallet_not_deployed: 422; readonly ton_invalid_wallet_version: 422; readonly ton_jetton_resolve_failed: 503; readonly ton_comment_parse_failed: 422; readonly tonconnect_payload_expired: 400; readonly tonconnect_payload_unknown: 400; readonly tonconnect_domain_mismatch: 400; readonly tonconnect_timestamp_skew: 400; readonly tonconnect_unknown_wallet_version: 400; readonly tonconnect_signature_invalid: 400; readonly tonconnect_network_mismatch: 400; readonly sandbox_project_required: 403; readonly production_project_required: 403; readonly sandbox_per_operator_cap_reached: 422; readonly sandbox_key_against_production_project: 400; readonly production_key_against_sandbox_project: 400; readonly sandbox_provisioning_failed: 500; readonly sandbox_invoice_transition_invalid: 422; readonly sandbox_invoice_not_found: 404; readonly sandbox_invoice_terminal: 422; readonly sandbox_rate_limit_exceeded: 429; readonly sandbox_reset_failed: 500; readonly sandbox_delete_failed: 500; readonly sandbox_active_invoice_cap_reached: 422; readonly overlay_matching_mode_required_exact: 422; readonly tx_not_found_or_incomplete: 200; readonly tx_already_attributed: 200; readonly manual_claim_rate_limit_exceeded: 429; readonly manual_claim_not_pending_review: 409; readonly manual_claim_invoice_not_open: 409; };
+export declare const ERROR_CODE_STATUS: { readonly validation_error: 400; readonly invalid_coin: 400; readonly invalid_xpub_format: 400; readonly invalid_webhook_url: 400; readonly auth_invalid: 401; readonly signature_invalid: 401; readonly signature_replayed: 401; readonly timestamp_out_of_window: 401; readonly key_suspended: 403; readonly project_suspended: 403; readonly permission_denied: 403; readonly key_revoked: 403; readonly invoice_not_found: 404; readonly project_not_found: 404; readonly wallet_not_found: 404; readonly external_id_conflict: 409; readonly xpub_not_verified: 409; readonly coin_not_enabled: 422; readonly amount_out_of_range: 422; readonly rate_limit_exceeded: 429; readonly pool_exhausted: 503; readonly webhook_capacity_exhausted: 503; readonly duplicate_provider_webhook_id: 409; readonly otp_expired: 400; readonly otp_used: 400; readonly invite_invalid: 400; readonly internal_error: 500; readonly invoice_not_cancellable: 409; readonly invalid_state_transition: 409; readonly orphan_not_found: 404; readonly orphan_already_attributed: 409; readonly event_not_found: 404; readonly wallet_not_bound: 422; readonly wallet_not_owned: 403; readonly wallet_has_active_bindings: 409; readonly wallet_kind_mismatch: 422; readonly subscription_expired: 402; readonly tron_no_activated_addresses_available: 422; readonly ton_operator_wallet_not_deployed: 422; readonly ton_invalid_wallet_version: 422; readonly ton_jetton_resolve_failed: 503; readonly ton_comment_parse_failed: 422; readonly tonconnect_payload_expired: 400; readonly tonconnect_payload_unknown: 400; readonly tonconnect_domain_mismatch: 400; readonly tonconnect_timestamp_skew: 400; readonly tonconnect_unknown_wallet_version: 400; readonly tonconnect_signature_invalid: 400; readonly tonconnect_network_mismatch: 400; readonly sandbox_project_required: 403; readonly production_project_required: 403; readonly sandbox_per_operator_cap_reached: 422; readonly sandbox_key_against_production_project: 400; readonly production_key_against_sandbox_project: 400; readonly sandbox_provisioning_failed: 500; readonly sandbox_invoice_transition_invalid: 422; readonly sandbox_invoice_not_found: 404; readonly sandbox_invoice_terminal: 422; readonly sandbox_rate_limit_exceeded: 429; readonly sandbox_reset_failed: 500; readonly sandbox_delete_failed: 500; readonly sandbox_active_invoice_cap_reached: 422; readonly overlay_matching_mode_required_exact: 422; readonly tx_not_found_or_incomplete: 200; readonly tx_already_attributed: 200; readonly manual_claim_rate_limit_exceeded: 429; readonly manual_claim_not_pending_review: 409; readonly manual_claim_invoice_not_open: 409; readonly event_not_resendable: 409; readonly rate_quote_unavailable: 503; };

package/dist/client-sandbox.d.ts

@@ -1,4 +1,4 @@
-import type { Chain, ClaimByTxResponse, ClockAdvance, SimulateEvent, SimulateLatePayment, SimulateOverpaid, SimulatePartial, WalletsListResponse } from './_shared/index.js';
+import type { Chain, ClaimByTxResponse, ClockAdvance, CursorPaginatedInvoiceResponse, InvoiceCreateRequest, InvoiceDetailResponse, InvoiceResponse, InvoiceSearchQuery, SimulateEvent, SimulateLatePayment, SimulateOverpaid, SimulatePartial, WalletsListResponse, WebhookEventListApiQuery, WebhookEventListResponse, WebhookEventResendResponse } 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
@@ -57,6 +57,152 @@ interface RequestFn {
 export declare class TxnodClientSandbox {
     #private;
     constructor(request: RequestFn);
+    /**
+     * `POST /api/v1/sandbox/invoices` — create an invoice on a sandbox project.
+     * The sandbox mirror of `client.createInvoice` (the production endpoint is
+     * kind-locked and rejects sandbox projects with
+     * `production_project_required`). Idempotent on `(project_id, external_id)`.
+     * Subject to the sandbox 10k active-invoice cap
+     * (`TxnodSandboxActiveInvoiceCapReachedError`).
+     *
+     * Unlike `client.createInvoice`, no xpub address-verification runs on the
+     * response — sandbox addresses derive from server-provisioned testnet xpubs
+     * and never carry real funds; use `client.sandbox.listWallets` if you want
+     * to verify derivation in a 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!, // sk_sandbox_...
+     *   environment: 'non-production',
+     * });
+     *
+     * const invoice = await client.sandbox.createInvoice({
+     *   amount_usd: 9.99,
+     *   coin: 'usdt_trc20',
+     *   external_id: 'order-42',
+     * });
+     * await client.sandbox.simulateDetect(invoice.id, { seed: 'order-42' });
+     * ```
+     */
+    createInvoice(body: InvoiceCreateRequest): Promise<InvoiceResponse>;
+    /**
+     * `GET /api/v1/sandbox/invoices/{invoiceId}` — fetch a sandbox invoice by
+     * ULID. The sandbox mirror of `client.getInvoice`; same
+     * `TxnodInvoiceNotFoundError` semantics on cross-project lookups.
+     *
+     * @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 invoice = await client.sandbox.getInvoice(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(invoice.status, invoice.confirmations);
+     * ```
+     */
+    getInvoice(id: string): Promise<InvoiceDetailResponse>;
+    /**
+     * `GET /api/v1/sandbox/invoices` — cursor-paginated search over the sandbox
+     * project's invoices. The sandbox mirror of `client.searchInvoices`; takes
+     * the same snake_case query filters.
+     *
+     * @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 page = await client.sandbox.listInvoices({ status: 'paid', limit: 20 });
+     * for (const invoice of page.items) console.log(invoice.id);
+     * ```
+     */
+    listInvoices(query?: InvoiceSearchQuery): Promise<CursorPaginatedInvoiceResponse>;
+    /**
+     * `POST /api/v1/sandbox/invoices/{invoiceId}/cancel` — cancel a sandbox
+     * invoice in `pending` or `detected` state. The sandbox mirror of
+     * `client.cancelInvoice`; throws `TxnodInvoiceNotCancellableError` on
+     * terminal-status invoices.
+     *
+     * @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 cancelled = await client.sandbox.cancelInvoice(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(cancelled.status); // 'cancelled'
+     * ```
+     */
+    cancelInvoice(id: string): Promise<InvoiceDetailResponse>;
+    /**
+     * `GET /api/v1/sandbox/webhooks/events` — cursor-paginated delivery log for
+     * the sandbox project's outbound webhook events. The sandbox mirror of
+     * `client.listWebhookEvents` (the production endpoint is kind-locked and
+     * rejects sandbox projects); takes the same snake_case query filters. Every
+     * row corresponds to an envelope with `mode: 'sandbox'`.
+     *
+     * @example
+     * ```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',
+     * });
+     *
+     * const page = await client.sandbox.listWebhookEvents({
+     *   invoice_id: '01HK8MAR2QEXAMPLE000000000',
+     *   limit: 50,
+     * });
+     * for (const event of page.items) console.log(event.id, event.event_type);
+     * ```
+     */
+    listWebhookEvents(query?: WebhookEventListApiQuery): Promise<WebhookEventListResponse>;
+    /**
+     * `POST /api/v1/sandbox/webhooks/events/{eventId}/resend` — re-enqueue a
+     * previously-delivered sandbox webhook event. The sandbox mirror of
+     * `client.resendWebhookEvent`; the resend mints a fresh `event_id` and the
+     * response carries `original_event_id` for lineage. In-flight or
+     * dead-lettered events throw `TxnodEventNotResendableError`.
+     *
+     * @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 resent = await client.sandbox.resendWebhookEvent(
+     *   '01HK8MAR2QEXAMPLE000000000',
+     * );
+     * console.log(resent.event_id, resent.original_event_id);
+     * ```
+     */
+    resendWebhookEvent(eventId: string): Promise<WebhookEventResendResponse>;
     /**
      * `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-detect` — synthesize
      * an `invoice.detected` event (status `pending` → `detected`) and write a

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

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