@txnod/sdk 1.1.0 → 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.1.0
+sdk_version: 1.2.0
 ---
 
 # @txnod/sdk — agent entry point

package/CHANGELOG.md

@@ -4,10 +4,18 @@ All notable changes to `@txnod/sdk` are documented here. Format: [Keep a Changel
 
 ## [Unreleased]
 
-## [1.1.0] - 2026-06-11
+## [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`.

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,7 +5,7 @@
 
 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: "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; };
 
@@ -25,7 +25,7 @@ export type ResolvedFacts = { sender_address: string; recipient_address: string;
 
 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; };
 
@@ -35,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";
 

package/dist/client.d.ts

@@ -127,6 +127,30 @@ export declare class TxnodClient {
      * ```
      */
     get sandbox(): TxnodClientSandbox;
+    /**
+     * The resolved SDK environment — `'production'`, `'non-production'`, or
+     * `'unknown'` — after applying the constructor `environment` option and the
+     * `TXNOD_ENVIRONMENT` / `NODE_ENV` fallbacks. Read it at startup to assert
+     * your wiring (e.g. fail fast if a production deploy resolved to
+     * `'non-production'`/`'unknown'`, or to gate logging/verbosity).
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     * });
+     *
+     * // Fail fast on a misconfigured deploy instead of silently signing
+     * // production requests with a non-production wiring.
+     * if (client.environment !== 'production') {
+     *   throw new Error(`TxNod: expected production, got ${client.environment}`);
+     * }
+     * ```
+     */
+    get environment(): 'production' | 'non-production' | 'unknown';
     /**
      * Re-read `TXNOD_<chain>_XPUB` env vars (and TON-specific siblings — the
      * `TXNOD_TON_PUBKEY` family) into the client's xpub config. Useful after a
@@ -164,6 +188,14 @@ export declare class TxnodClient {
      * invoice's `derivation_path` and throws `AddressVerificationError` on
      * mismatch — no flag needed.
      *
+     * Pass the optional `matching_mode` (`'exact' | 'at_least' | 'any'`) to
+     * override the project's default amount-matching policy for this invoice.
+     * When omitted the invoice inherits the project default. Note: `'any'` /
+     * `'at_least'` are rejected (HTTP 422 `overlay_matching_mode_required_exact`)
+     * when the address pool is saturated and the invoice would land as an
+     * amount-overlay sibling on a shared pool address — amount disambiguation
+     * there requires `'exact'`.
+     *
      * @example
      * ```ts
      * import { TxnodClient, TxnodError, AddressVerificationError } from '@txnod/sdk';

package/dist/client.d.ts.map

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

package/dist/client.js

@@ -165,6 +165,32 @@ export class TxnodClient {
         }
         return this.#sandboxNamespace;
     }
+    /**
+     * The resolved SDK environment — `'production'`, `'non-production'`, or
+     * `'unknown'` — after applying the constructor `environment` option and the
+     * `TXNOD_ENVIRONMENT` / `NODE_ENV` fallbacks. Read it at startup to assert
+     * your wiring (e.g. fail fast if a production deploy resolved to
+     * `'non-production'`/`'unknown'`, or to gate logging/verbosity).
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     * });
+     *
+     * // Fail fast on a misconfigured deploy instead of silently signing
+     * // production requests with a non-production wiring.
+     * if (client.environment !== 'production') {
+     *   throw new Error(`TxNod: expected production, got ${client.environment}`);
+     * }
+     * ```
+     */
+    get environment() {
+        return getSdkEnv(this.#environmentOption);
+    }
     /**
      * Re-read `TXNOD_<chain>_XPUB` env vars (and TON-specific siblings — the
      * `TXNOD_TON_PUBKEY` family) into the client's xpub config. Useful after a
@@ -239,6 +265,14 @@ export class TxnodClient {
      * invoice's `derivation_path` and throws `AddressVerificationError` on
      * mismatch — no flag needed.
      *
+     * Pass the optional `matching_mode` (`'exact' | 'at_least' | 'any'`) to
+     * override the project's default amount-matching policy for this invoice.
+     * When omitted the invoice inherits the project default. Note: `'any'` /
+     * `'at_least'` are rejected (HTTP 422 `overlay_matching_mode_required_exact`)
+     * when the address pool is saturated and the invoice would land as an
+     * amount-overlay sibling on a shared pool address — amount disambiguation
+     * there requires `'exact'`.
+     *
      * @example
      * ```ts
      * import { TxnodClient, TxnodError, AddressVerificationError } from '@txnod/sdk';

package/dist/client.js.map

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

package/dist/coins.d.ts

@@ -0,0 +1,29 @@
+import type { Chain, Coin } from './_shared/index.js';
+/**
+ * Maps a {@link Coin} (e.g. `usdt_trc20`) to the {@link Chain} it settles on
+ * (e.g. `tron`). Useful when an API that speaks `Coin` (invoices) meets one
+ * that speaks `Chain` (orphan payments).
+ */
+export declare const COIN_TO_CHAIN: Record<Coin, Chain>;
+/** Returns the {@link Chain} a {@link Coin} settles on. */
+export declare function coinToChain(coin: Coin): Chain;
+/**
+ * Base-unit decimal places per {@link Coin}. NOTE the traps: BEP-20 USDT/USDC
+ * are **18** decimals (not 6 like their ERC-20/TRC-20 siblings), and TON is 9.
+ * Always format `amount_units` (base units, from invoices and webhooks)
+ * through {@link fromBaseUnits} rather than assuming a width.
+ */
+export declare const COIN_DECIMALS: Record<Coin, number>;
+/**
+ * Converts a human decimal amount (e.g. `"1.5"`) into integer base units
+ * (e.g. `"1500000"` for a 6-decimal coin). Throws on malformed input, too many
+ * fractional digits for the coin, or a zero result.
+ */
+export declare function toBaseUnits(coin: Coin, humanString: string): string;
+/**
+ * Formats integer base units (e.g. an invoice/webhook `amount_units` string)
+ * as a human decimal string (e.g. `"1500000"` → `"1.5"` for a 6-decimal
+ * coin), trimming trailing zeros. The inverse of {@link toBaseUnits}.
+ */
+export declare function fromBaseUnits(coin: Coin, baseUnitsString: string): string;
+//# sourceMappingURL=coins.d.ts.map

package/dist/coins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coins.d.ts","sourceRoot":"","sources":["../src/coins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAQjD;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,KAAK,CAgB7C,CAAC;AAEF,2DAA2D;AAC3D,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,KAAK,CAE7C;AAED;;;;;GAKG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAgB9C,CAAC;AAIF;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CA2BnE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,GAAG,MAAM,CAczE"}

package/dist/coins.js

@@ -0,0 +1,107 @@
+// Vendored copies of the shared coin metadata. The published SDK has ZERO
+// runtime dependency on `@txnod/shared` (it imports only *types*), so these
+// maps are duplicated here as plain data — kept honest by the drift guard in
+// `coins.test.ts`, which compares them against the shared source. The
+// `Record<Coin, …>` shape makes the type-checker reject any missing coin.
+/**
+ * Maps a {@link Coin} (e.g. `usdt_trc20`) to the {@link Chain} it settles on
+ * (e.g. `tron`). Useful when an API that speaks `Coin` (invoices) meets one
+ * that speaks `Chain` (orphan payments).
+ */
+export const COIN_TO_CHAIN = {
+    btc: 'btc',
+    eth: 'eth',
+    usdt_erc20: 'eth',
+    usdc_erc20: 'eth',
+    trx: 'tron',
+    usdt_trc20: 'tron',
+    ada: 'ada',
+    pol: 'polygon',
+    usdt_polygon: 'polygon',
+    usdc_polygon: 'polygon',
+    bnb: 'bsc',
+    usdt_bep20: 'bsc',
+    usdc_bep20: 'bsc',
+    ton: 'ton',
+    usdt_ton: 'ton',
+};
+/** Returns the {@link Chain} a {@link Coin} settles on. */
+export function coinToChain(coin) {
+    return COIN_TO_CHAIN[coin];
+}
+/**
+ * Base-unit decimal places per {@link Coin}. NOTE the traps: BEP-20 USDT/USDC
+ * are **18** decimals (not 6 like their ERC-20/TRC-20 siblings), and TON is 9.
+ * Always format `amount_units` (base units, from invoices and webhooks)
+ * through {@link fromBaseUnits} rather than assuming a width.
+ */
+export const COIN_DECIMALS = {
+    btc: 8,
+    eth: 18,
+    usdt_erc20: 6,
+    usdc_erc20: 6,
+    trx: 6,
+    usdt_trc20: 6,
+    ada: 6,
+    pol: 18,
+    usdt_polygon: 6,
+    usdc_polygon: 6,
+    bnb: 18,
+    usdt_bep20: 18,
+    usdc_bep20: 18,
+    ton: 9,
+    usdt_ton: 6,
+};
+const VALID_AMOUNT_REGEX = /^(0|[1-9][0-9]*)(\.[0-9]+)?$/;
+/**
+ * Converts a human decimal amount (e.g. `"1.5"`) into integer base units
+ * (e.g. `"1500000"` for a 6-decimal coin). Throws on malformed input, too many
+ * fractional digits for the coin, or a zero result.
+ */
+export function toBaseUnits(coin, humanString) {
+    if (typeof humanString !== 'string') {
+        throw new Error('amount must be a string');
+    }
+    if (humanString !== humanString.trim()) {
+        throw new Error('amount must not have leading or trailing whitespace');
+    }
+    if (humanString === '') {
+        throw new Error('amount must not be empty');
+    }
+    if (!VALID_AMOUNT_REGEX.test(humanString)) {
+        throw new Error(`invalid amount format: ${humanString}`);
+    }
+    const decimals = COIN_DECIMALS[coin];
+    const [whole, frac = ''] = humanString.split('.');
+    if (frac.length > decimals) {
+        throw new Error(`amount has more than ${decimals} fractional digits for ${coin}: ${humanString}`);
+    }
+    const fracPadded = frac.padEnd(decimals, '0');
+    const combined = `${whole}${fracPadded}`;
+    const asBig = BigInt(combined);
+    if (asBig === 0n) {
+        throw new Error('amount must be greater than zero');
+    }
+    return asBig.toString();
+}
+/**
+ * Formats integer base units (e.g. an invoice/webhook `amount_units` string)
+ * as a human decimal string (e.g. `"1500000"` → `"1.5"` for a 6-decimal
+ * coin), trimming trailing zeros. The inverse of {@link toBaseUnits}.
+ */
+export function fromBaseUnits(coin, baseUnitsString) {
+    if (!/^[0-9]+$/.test(baseUnitsString)) {
+        throw new Error(`invalid base-units string: ${baseUnitsString}`);
+    }
+    const decimals = COIN_DECIMALS[coin];
+    const value = BigInt(baseUnitsString);
+    const divisor = 10n ** BigInt(decimals);
+    const whole = value / divisor;
+    const frac = value % divisor;
+    if (frac === 0n) {
+        return whole.toString();
+    }
+    const fracStr = frac.toString().padStart(decimals, '0').replace(/0+$/, '');
+    return `${whole.toString()}.${fracStr}`;
+}
+//# sourceMappingURL=coins.js.map

package/dist/coins.js.map

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

package/dist/index.d.ts

@@ -19,12 +19,13 @@ export declare const PACKAGE_NAME: "@txnod/sdk";
  * console.log(`@txnod/sdk v${SDK_VERSION}`);
  * ```
  */
-export declare const SDK_VERSION: "1.1.0";
+export declare const SDK_VERSION: "1.2.0";
 export { TxnodClient, type TxnodClientOptions, type TxnodRequestLogEntry, type TxnodRequestLogger, } from './client.js';
 export { getSdkEnv } from './env.js';
 export { TxnodClientSandbox, type SandboxClockAdvanceResult, type SandboxLifecycleResult, type SandboxSimulateResult, } from './client-sandbox.js';
 export { TxnodAmountOutOfRangeError, TxnodAuthInvalidError, TxnodCoinNotEnabledError, TxnodEnvironmentUnknownError, TxnodError, TxnodEventNotFoundError, TxnodEventNotResendableError, TxnodExternalIdConflictError, TxnodHmacError, TxnodInvalidCoinError, TxnodInvalidStateTransitionError, TxnodInvalidWebhookUrlError, TxnodInvalidXpubFormatError, TxnodInvoiceNotCancellableError, TxnodInvoiceNotFoundError, TxnodKeyRevokedError, TxnodKeySuspendedError, TxnodOrphanAlreadyAttributedError, TxnodOrphanNotFoundError, TxnodOverlayMatchingModeError, TxnodPermissionDeniedError, TxnodPoolExhaustedError, TxnodProductionKeyAgainstSandboxProjectError, TxnodProjectNotFoundError, TxnodProjectSuspendedError, TxnodRateLimitError, TxnodRateQuoteUnavailableError, TxnodSandboxActiveInvoiceCapReachedError, TxnodSandboxDeleteFailedError, TxnodSandboxInvoiceNotFoundError, TxnodSandboxInvoiceTerminalError, TxnodSandboxInvoiceTransitionInvalidError, TxnodSandboxKeyAgainstProductionProjectError, TxnodSandboxKeyInProductionError, TxnodSandboxPerOperatorCapReachedError, TxnodSandboxProjectRequiredError, TxnodProductionProjectRequiredError, TxnodSandboxProvisioningFailedError, TxnodSandboxRateLimitExceededError, TxnodSandboxResetFailedError, TxnodSandboxXpubInProductionError, TxnodServerError, TxnodSignatureFormatError, TxnodSignatureInvalidError, TxnodSignatureReplayedError, TxnodSubscriptionExpiredError, TxnodTimestampError, TxnodTimestampOutOfWindowError, TxnodTonCommentParseFailedError, TxnodTonConnectDomainMismatchError, TxnodTonConnectNetworkMismatchError, TxnodTonConnectPayloadExpiredError, TxnodTonConnectPayloadUnknownError, TxnodTonConnectSignatureInvalidError, TxnodTonConnectTimestampSkewError, TxnodTonConnectUnknownWalletVersionError, TxnodTonInvalidWalletVersionError, TxnodTonJettonResolveFailedError, TxnodTonOperatorWalletNotDeployedError, TxnodTronNoActivatedAddressesError, TxnodValidationError, TxnodWalletHasActiveBindingsError, TxnodWalletKindMismatchError, TxnodWalletNotBoundError, TxnodWalletNotFoundError, TxnodWalletNotOwnedError, TxnodTxNotFoundError, TxnodTxAlreadyAttributedError, TxnodWebhookCapacityExhaustedError, TxnodWebhookPayloadParseError, TxnodXpubNotVerifiedError, } from './errors.js';
-export { verifyWebhookSignature } from './verify-webhook-signature.js';
+export { verifyWebhookSignature, type WebhookHeadersInput, } from './verify-webhook-signature.js';
+export { COIN_TO_CHAIN, coinToChain, COIN_DECIMALS, toBaseUnits, fromBaseUnits, } from './coins.js';
 export { verifyAddress } from './verify/index.js';
 export type { VerifyAddressInput, VerificationResult } from './verify/index.js';
 export { verifyTonAddress } from './verify/chains/ton.js';

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -19,12 +19,13 @@ export const PACKAGE_NAME = '@txnod/sdk';
  * console.log(`@txnod/sdk v${SDK_VERSION}`);
  * ```
  */
-export const SDK_VERSION = '1.1.0';
+export const SDK_VERSION = '1.2.0';
 export { TxnodClient, } from './client.js';
 export { getSdkEnv } from './env.js';
 export { TxnodClientSandbox, } from './client-sandbox.js';
 export { TxnodAmountOutOfRangeError, TxnodAuthInvalidError, TxnodCoinNotEnabledError, TxnodEnvironmentUnknownError, TxnodError, TxnodEventNotFoundError, TxnodEventNotResendableError, TxnodExternalIdConflictError, TxnodHmacError, TxnodInvalidCoinError, TxnodInvalidStateTransitionError, TxnodInvalidWebhookUrlError, TxnodInvalidXpubFormatError, TxnodInvoiceNotCancellableError, TxnodInvoiceNotFoundError, TxnodKeyRevokedError, TxnodKeySuspendedError, TxnodOrphanAlreadyAttributedError, TxnodOrphanNotFoundError, TxnodOverlayMatchingModeError, TxnodPermissionDeniedError, TxnodPoolExhaustedError, TxnodProductionKeyAgainstSandboxProjectError, TxnodProjectNotFoundError, TxnodProjectSuspendedError, TxnodRateLimitError, TxnodRateQuoteUnavailableError, TxnodSandboxActiveInvoiceCapReachedError, TxnodSandboxDeleteFailedError, TxnodSandboxInvoiceNotFoundError, TxnodSandboxInvoiceTerminalError, TxnodSandboxInvoiceTransitionInvalidError, TxnodSandboxKeyAgainstProductionProjectError, TxnodSandboxKeyInProductionError, TxnodSandboxPerOperatorCapReachedError, TxnodSandboxProjectRequiredError, TxnodProductionProjectRequiredError, TxnodSandboxProvisioningFailedError, TxnodSandboxRateLimitExceededError, TxnodSandboxResetFailedError, TxnodSandboxXpubInProductionError, TxnodServerError, TxnodSignatureFormatError, TxnodSignatureInvalidError, TxnodSignatureReplayedError, TxnodSubscriptionExpiredError, TxnodTimestampError, TxnodTimestampOutOfWindowError, TxnodTonCommentParseFailedError, TxnodTonConnectDomainMismatchError, TxnodTonConnectNetworkMismatchError, TxnodTonConnectPayloadExpiredError, TxnodTonConnectPayloadUnknownError, TxnodTonConnectSignatureInvalidError, TxnodTonConnectTimestampSkewError, TxnodTonConnectUnknownWalletVersionError, TxnodTonInvalidWalletVersionError, TxnodTonJettonResolveFailedError, TxnodTonOperatorWalletNotDeployedError, TxnodTronNoActivatedAddressesError, TxnodValidationError, TxnodWalletHasActiveBindingsError, TxnodWalletKindMismatchError, TxnodWalletNotBoundError, TxnodWalletNotFoundError, TxnodWalletNotOwnedError, TxnodTxNotFoundError, TxnodTxAlreadyAttributedError, TxnodWebhookCapacityExhaustedError, TxnodWebhookPayloadParseError, TxnodXpubNotVerifiedError, } from './errors.js';
-export { verifyWebhookSignature } from './verify-webhook-signature.js';
+export { verifyWebhookSignature, } from './verify-webhook-signature.js';
+export { COIN_TO_CHAIN, coinToChain, COIN_DECIMALS, toBaseUnits, fromBaseUnits, } from './coins.js';
 export { verifyAddress } from './verify/index.js';
 export { verifyTonAddress } from './verify/chains/ton.js';
 export { parseXpubConfig, parseTonConfig } from './verify/config.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,YAAqB,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAgB,CAAC;AAE5C,OAAO,EACL,WAAW,GAIZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,kBAAkB,GAInB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,EAC5B,UAAU,EACV,uBAAuB,EACvB,4BAA4B,EAC5B,4BAA4B,EAC5B,cAAc,EACd,qBAAqB,EACrB,gCAAgC,EAChC,2BAA2B,EAC3B,2BAA2B,EAC3B,+BAA+B,EAC/B,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,iCAAiC,EACjC,wBAAwB,EACxB,6BAA6B,EAC7B,0BAA0B,EAC1B,uBAAuB,EACvB,4CAA4C,EAC5C,yBAAyB,EACzB,0BAA0B,EAC1B,mBAAmB,EACnB,8BAA8B,EAC9B,wCAAwC,EACxC,6BAA6B,EAC7B,gCAAgC,EAChC,gCAAgC,EAChC,yCAAyC,EACzC,4CAA4C,EAC5C,gCAAgC,EAChC,sCAAsC,EACtC,gCAAgC,EAChC,mCAAmC,EACnC,mCAAmC,EACnC,kCAAkC,EAClC,4BAA4B,EAC5B,iCAAiC,EACjC,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,EAC3B,6BAA6B,EAC7B,mBAAmB,EACnB,8BAA8B,EAC9B,+BAA+B,EAC/B,kCAAkC,EAClC,mCAAmC,EACnC,kCAAkC,EAClC,kCAAkC,EAClC,oCAAoC,EACpC,iCAAiC,EACjC,wCAAwC,EACxC,iCAAiC,EACjC,gCAAgC,EAChC,sCAAsC,EACtC,kCAAkC,EAClC,oBAAoB,EACpB,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,6BAA6B,EAC7B,kCAAkC,EAClC,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,cAAc,EAAsB,MAAM,oBAAoB,CAAC;AACzF,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,YAAqB,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,OAAgB,CAAC;AAE5C,OAAO,EACL,WAAW,GAIZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EACL,kBAAkB,GAInB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,0BAA0B,EAC1B,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,EAC5B,UAAU,EACV,uBAAuB,EACvB,4BAA4B,EAC5B,4BAA4B,EAC5B,cAAc,EACd,qBAAqB,EACrB,gCAAgC,EAChC,2BAA2B,EAC3B,2BAA2B,EAC3B,+BAA+B,EAC/B,yBAAyB,EACzB,oBAAoB,EACpB,sBAAsB,EACtB,iCAAiC,EACjC,wBAAwB,EACxB,6BAA6B,EAC7B,0BAA0B,EAC1B,uBAAuB,EACvB,4CAA4C,EAC5C,yBAAyB,EACzB,0BAA0B,EAC1B,mBAAmB,EACnB,8BAA8B,EAC9B,wCAAwC,EACxC,6BAA6B,EAC7B,gCAAgC,EAChC,gCAAgC,EAChC,yCAAyC,EACzC,4CAA4C,EAC5C,gCAAgC,EAChC,sCAAsC,EACtC,gCAAgC,EAChC,mCAAmC,EACnC,mCAAmC,EACnC,kCAAkC,EAClC,4BAA4B,EAC5B,iCAAiC,EACjC,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,EAC1B,2BAA2B,EAC3B,6BAA6B,EAC7B,mBAAmB,EACnB,8BAA8B,EAC9B,+BAA+B,EAC/B,kCAAkC,EAClC,mCAAmC,EACnC,kCAAkC,EAClC,kCAAkC,EAClC,oCAAoC,EACpC,iCAAiC,EACjC,wCAAwC,EACxC,iCAAiC,EACjC,gCAAgC,EAChC,sCAAsC,EACtC,kCAAkC,EAClC,oBAAoB,EACpB,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,wBAAwB,EACxB,wBAAwB,EACxB,oBAAoB,EACpB,6BAA6B,EAC7B,kCAAkC,EAClC,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,GAEvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,aAAa,EACb,WAAW,EACX,aAAa,EACb,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,eAAe,EAAE,cAAc,EAAsB,MAAM,oBAAoB,CAAC;AACzF,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/verify-webhook-signature.d.ts

@@ -1,4 +1,11 @@
 import type { WebhookEvent } from './_shared/index.js';
+/**
+ * Header bag accepted by {@link verifyWebhookSignature}. The
+ * `string | string[] | undefined` value shape makes this a structural
+ * superset of Node's `IncomingHttpHeaders` (Express/Fastify `req.headers`),
+ * so the verifier is drop-in there as well as with the Web `Headers` object.
+ */
+export type WebhookHeadersInput = Headers | Record<string, string | string[] | undefined>;
 /**
  * Verifies an inbound webhook signature and returns a typed event. Parses
  * the `X-Txnod-Signature: t=<unix>,v1=<hex>` header, recomputes HMAC-SHA256
@@ -26,5 +33,5 @@ import type { WebhookEvent } from './_shared/index.js';
  * }
  * ```
  */
-export declare function verifyWebhookSignature(headers: Headers | Record<string, string> | Record<string, string[]>, rawBody: string, secret: string): WebhookEvent;
+export declare function verifyWebhookSignature(headers: WebhookHeadersInput, rawBody: string | Buffer, secret: string): WebhookEvent;
 //# sourceMappingURL=verify-webhook-signature.d.ts.map

package/dist/verify-webhook-signature.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verify-webhook-signature.d.ts","sourceRoot":"","sources":["../src/verify-webhook-signature.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AA8BlD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,EACpE,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,GACb,YAAY,CAqCd"}
+{"version":3,"file":"verify-webhook-signature.d.ts","sourceRoot":"","sources":["../src/verify-webhook-signature.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAalD;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;AAsBlD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,MAAM,GAAG,MAAM,EACxB,MAAM,EAAE,MAAM,GACb,YAAY,CAwCd"}

package/dist/verify-webhook-signature.js

@@ -11,6 +11,9 @@ function getHeader(headers, name) {
     for (const [key, value] of Object.entries(headers)) {
         if (key.toLowerCase() !== name)
             continue;
+        if (value === undefined) {
+            return undefined;
+        }
         if (Array.isArray(value)) {
             return value[0];
         }
@@ -46,6 +49,9 @@ function getHeader(headers, name) {
  * ```
  */
 export function verifyWebhookSignature(headers, rawBody, secret) {
+    // Node HTTP frameworks hand back the body as a Buffer; decode to the exact
+    // UTF-8 bytes the gateway signed so `.toString()` boilerplate is unnecessary.
+    const body = typeof rawBody === 'string' ? rawBody : rawBody.toString('utf8');
     const raw = getHeader(headers, SIGNATURE_HEADER);
     if (raw === undefined) {
         throw new TxnodSignatureFormatError();
@@ -66,7 +72,7 @@ export function verifyWebhookSignature(headers, rawBody, secret) {
         throw new TxnodTimestampError(skewSeconds);
     }
     const expected = createHmac('sha256', secret)
-        .update(`${timestamp}.${rawBody}`)
+        .update(`${timestamp}.${body}`)
         .digest();
     // `provided` is structurally `DIGEST_BYTES` long: HEADER_PATTERN + the
     // `providedHex.length === DIGEST_BYTES * 2` check above guarantee 64 hex
@@ -75,7 +81,7 @@ export function verifyWebhookSignature(headers, rawBody, secret) {
         throw new TxnodHmacError();
     }
     try {
-        return JSON.parse(rawBody);
+        return JSON.parse(body);
     }
     catch (cause) {
         throw new TxnodWebhookPayloadParseError(cause);

package/dist/verify-webhook-signature.js.map

@@ -1 +1 @@
-{"version":3,"file":"verify-webhook-signature.js","sourceRoot":"","sources":["../src/verify-webhook-signature.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE1D,OAAO,EACL,cAAc,EACd,yBAAyB,EACzB,mBAAmB,EACnB,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AAErB,MAAM,wBAAwB,GAAG,GAAG,CAAC;AACrC,MAAM,YAAY,GAAG,EAAE,CAAC;AACxB,MAAM,gBAAgB,GAAG,mBAAmB,CAAC;AAC7C,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAErD,SAAS,SAAS,CAChB,OAAoE,EACpE,IAAY;IAEZ,IAAI,OAAO,YAAY,OAAO,EAAE,CAAC;QAC/B,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;IACxC,CAAC;IACD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,IAAI;YAAE,SAAS;QACzC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAoE,EACpE,OAAe,EACf,MAAc;IAEd,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IACjD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IACD,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC/B,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;IAC9B,IAAI,WAAW,CAAC,MAAM,KAAK,YAAY,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,yBAAyB,EAAE,CAAC;IACxC,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;IAC7C,MAAM,WAAW,GAAG,MAAM,GAAG,SAAS,CAAC;IACvC,IAAI,IAAI,CAAC,GAAG,CAAC,WAAW,CAAC,GAAG,wBAAwB,EAAE,CAAC;QACrD,MAAM,IAAI,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC7C,CAAC;IAED,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,EAAE,MAAM,CAAC;SAC1C,MAAM,CAAC,GAAG,SAAS,IAAI,OAAO,EAAE,CAAC;SACjC,MAAM,EAAE,CAAC;IACZ,uEAAuE;IACvE,yEAAyE;IACzE,uEAAuE;IACvE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;QAChE,MAAM,IAAI,cAAc,EAAE,CAAC;IAC7B,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAiB,CAAC;IAC7C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,6BAA6B,CAAC,KAAK,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}
+{"version":3,"file":"verify-webhook-signature.js","sourceRoot":"","sources":["../src/verify-webhook-signature.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@txnod/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "TypeScript SDK for the txnod non-custodial crypto payment gateway — sign requests, verify webhook signatures, and verify invoice deposit-address derivation across BTC, ETH, TRON, Cardano, Polygon PoS, BNB Smart Chain, and TON. Pure Node >= 20; runs in any server-side framework (Express, Fastify, Hono, Next.js, Nuxt, SvelteKit, etc.).",
   "license": "MIT",
   "type": "module",