@txnod/sdk 1.0.1 → 1.0.2

package/dist/verify/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/verify/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,OAAO,wBAAyB,SAAQ,UAAU;IACpC,IAAI,GAAG,sBAA+B,CAAC;IAChD,KAAK,CAAQ;IACb,eAAe,CAAS;IACxB,gBAAgB,CAAS;IACzB,eAAe,CAAS;IAEjC,YAAY,KAKX;QACC,KAAK,CACH,gBAAgB,CACd,cAAc,EACd,GAAG,EACH,0CAA0C,KAAK,CAAC,KAAK,gBAAgB,KAAK,CAAC,gBAAgB,eAAe,KAAK,CAAC,eAAe,gBAAgB,KAAK,CAAC,eAAe,IAAI,CACzK,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;QAC7C,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,CAAC;QAC/C,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;IAC/C,CAAC;CACF"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/verify/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAC;AAGrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,OAAO,wBAAyB,SAAQ,UAAU;IACpC,IAAI,GAAG,sBAA+B,CAAC;IAChD,KAAK,CAAQ;IACb,eAAe,CAAS;IACxB,gBAAgB,CAAS;IACzB,eAAe,CAAS;IAEjC,YAAY,KAKX;QACC,KAAK,CACH,gBAAgB,CACd,cAAc,EACd,GAAG,EACH,0CAA0C,KAAK,CAAC,KAAK,gBAAgB,KAAK,CAAC,gBAAgB,eAAe,KAAK,CAAC,eAAe,gBAAgB,KAAK,CAAC,eAAe,IAAI,CACzK,CACF,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;QACzB,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;QAC7C,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,CAAC;QAC/C,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,eAAe,CAAC;IAC/C,CAAC;CACF"}

package/dist/verify/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Multi-chain address-verification dispatcher consumed by TxnodClient.createInvoice.
  * Routes the invoice's coin → chain → per-chain verifier with multi-xpub
- * iteration (newest-first per AD-10) and selective error rethrow.
+ * iteration (newest-first) and selective error rethrow.
  */
 import type { Chain, InvoiceResponse, WalletEdgeKind } from '../_shared/index.js';
 import type { TonXpubConfig } from './config.js';

package/dist/verify/index.js

@@ -1,7 +1,7 @@
 /**
  * Multi-chain address-verification dispatcher consumed by TxnodClient.createInvoice.
  * Routes the invoice's coin → chain → per-chain verifier with multi-xpub
- * iteration (newest-first per AD-10) and selective error rethrow.
+ * iteration (newest-first) and selective error rethrow.
  */
 import { logger } from '../internals/logger.js';
 import { AddressVerificationError } from './errors.js';
@@ -12,7 +12,7 @@ import { verifyCardano } from './chains/cardano.js';
 import { verifyPolygon } from './chains/polygon.js';
 import { verifyBsc } from './chains/bsc.js';
 import { verifyTonAddress } from './chains/ton.js';
-// Mirrors packages/shared/src/schemas/coin.ts COIN_TO_CHAIN — drift is coupled with the shared table.
+// Coin → chain lookup. Kept in lockstep with the shared coin schema.
 const COIN_TO_CHAIN_LITERAL = {
     btc: 'btc',
     eth: 'eth',

package/dist/verify/index.js.map

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

package/docs/02-invoices.md

@@ -1,7 +1,7 @@
 ---
 title: "Invoices"
-description: "Create, fetch, search, and cancel invoices; the nine-state invoice lifecycle."
-sdk_version: 1.0.0
+description: "Create, fetch, search, and cancel invoices; the ten-state invoice lifecycle."
+sdk_version: 1.0.2
 ---
 
 # Invoices
@@ -21,6 +21,7 @@ An invoice moves through a state machine. Statuses are the `InvoiceStatus` union
 | `expired_paid_late` | Payment arrived after `expires_at` | yes |
 | `reverted` | Previously `paid`/`overpaid` but dropped by a chain reorg | yes |
 | `cancelled` | Explicitly cancelled via `cancelInvoice` | yes |
+| `ambiguous` | A deposit could not be attributed to a single open invoice (multiple candidates matched). Held until operator resolves via dashboard one-click flip | no (operator-resolved) |
 
 **`paid` is not the end of the story.** A deeper reorg can still invalidate on-chain receipts. Only trust `paid` / `overpaid` for fulfilment once `confirmations` ≥ your project's finalization threshold, and always have a path to roll back on an `invoice.reverted` webhook — see [`06-idempotency.md`](./06-idempotency.md).
 
@@ -209,6 +210,49 @@ A receipt that lands on a derivation address not currently bound to any open inv
 - [`listOrphanPayments`](./reference/client.md#listorphanpayments) — list and filter
 - [`attributeOrphanPayment`](./reference/client.md#attributeorphanpayment) — post-hoc bind an orphan to an `external_id`; the returned invoice reflects the attribution
 
+## Manual tx-hash claim
+
+For the "I paid but the invoice is still open" recovery flow, the merchant's backend can forward an end-customer-submitted tx hash to `client.claimInvoiceByTx`. The server resolves the tx via the chain provider, verifies sender / recipient / amount / timestamp, and returns one of four outcomes:
+
+- `auto_attributed` — facts matched; the invoice has been credited and transitioned to the corresponding terminal status (`terminal_status` field on the response carries which).
+- `pending_review` — no automatic match; the claim is queued for operator review in the dashboard.
+- `pending_finality` — the tx is not yet finalised against the per-chain finality threshold; the server will re-check asynchronously.
+- `rejected` — `response.rejection_reason` is one of `tx_not_found_or_incomplete` (chain provider couldn't resolve the tx, or facts mismatch) or `tx_already_attributed` (the tx was previously credited).
+
+```ts
+import { TxnodClient, TxnodError } from '@txnod/sdk';
+
+const client = new TxnodClient({
+  projectId: process.env.TXNOD_PROJECT_ID!,
+  apiSecret: process.env.TXNOD_API_SECRET!,
+});
+
+try {
+  const result = await client.claimInvoiceByTx({
+    invoiceId: '01HK8MAR2QEXAMPLE000000000',
+    txHash: '0xabc...def',
+    chain: 'eth',
+  });
+  if (result.status === 'auto_attributed') {
+    console.log('attributed; terminal_status:', result.terminal_status);
+  } else if (result.status === 'rejected') {
+    console.log('rejected:', result.rejection_reason);
+  } else {
+    console.log('queued; status:', result.status);
+  }
+} catch (err) {
+  if (err instanceof TxnodError && err.error_code === 'manual_claim_rate_limit_exceeded') {
+    // 429; per-user hourly throttle (10/hour/user). Back off and retry later.
+    return;
+  }
+  throw err;
+}
+```
+
+Rejection paths come back in the response body — they do **not** throw. Throw-style consumers can opt in by inspecting `result.rejection_reason` and constructing `TxnodTxNotFoundError` / `TxnodTxAlreadyAttributedError` themselves; see [`reference/errors.md`](./reference/errors.md#manual-tx-hash-claim-flow).
+
+The per-user throttle of 10 claims / hour / user surfaces as `error_code: 'manual_claim_rate_limit_exceeded'` (HTTP 429 with `Retry-After`); branch on `err.error_code` against the base `TxnodError`.
+
 ## Related
 
 - [`04-webhooks.md`](./04-webhooks.md) — status changes you will observe from the outside

package/docs/04-webhooks.md

@@ -1,7 +1,7 @@
 ---
 title: "Webhooks"
 description: "Event types, verifyWebhookSignature, ±300-second window, event_id idempotency, retries, resend."
-sdk_version: 1.0.0
+sdk_version: 1.0.2
 ---
 
 # Webhooks
@@ -21,6 +21,7 @@ The `WebhookEvent` type is a discriminated union on `event_type`:
 | `invoice.expired` | `expires_at` passed before `paid` | yes |
 | `invoice.expired_paid_late` | Payment arrived after `expires_at` | yes |
 | `invoice.reverted` | Previously `paid`/`overpaid` dropped by reorg | yes |
+| `invoice.ambiguous` | Deposit could not be attributed to a single open invoice — multiple candidates matched (overlay-collision). Operator must resolve via one-click flip in the dashboard | no (operator-resolved) |
 
 Every event shares this envelope:
 

package/docs/05-errors.md

@@ -1,7 +1,7 @@
 ---
 title: "Error handling"
 description: "Every typed TxnodError subclass, what raises it, and how to branch on it."
-sdk_version: 1.0.0
+sdk_version: 1.0.2
 ---
 
 # Error handling
@@ -111,12 +111,32 @@ Grouped by what the operator should do. Full `error_code` → class lookup is in
 | `TxnodExternalIdConflictError` | `external_id_conflict` | Invoice with that `external_id` already exists; fetch via `searchInvoices({ external_id })` |
 | `TxnodOrphanAlreadyAttributedError` | `orphan_already_attributed` | Orphan already bound to an invoice; treat as success |
 
+### Overlay matching (pool routing)
+
+The overlay allocator picks per-invoice addresses with a soft-reuse policy. Under saturation it falls back to a stricter mode that requires exact-amount matching — partner code must catch the resulting validation error if the project's matching mode is `at_least` or `any`.
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodOverlayMatchingModeError` | `overlay_matching_mode_required_exact` | Pool saturation forced the allocator into `required_exact` matching, but the project's `matching_mode` is `at_least` or `any`. Switch the project to `required_exact` (recommended) or wait for the pool to drain. HTTP 422 |
+
+### Manual tx-hash claim flow
+
+`client.claimInvoiceByTx` has an unusual error model: the two most common rejections (`tx_not_found_or_incomplete` and `tx_already_attributed`) are returned in the **response body** as `{ status: 'rejected', rejection_reason }` on HTTP 200 — they do **not** throw. The two error classes below are provided as helpers for consumers who prefer to convert those response shapes into throws themselves; they are **not** raised by the SDK's own `parseProblemDetails` path.
+
+| Class | `error_code` | Meaning |
+|---|---|---|
+| `TxnodTxNotFoundError` | `tx_not_found_or_incomplete` | Chain provider could not resolve the submitted tx hash, or resolved facts do not match the invoice (recipient / amount / state). Surfaced as `response.rejection_reason` on HTTP 200 |
+| `TxnodTxAlreadyAttributedError` | `tx_already_attributed` | The submitted tx was previously credited to an invoice. Surfaced as `response.rejection_reason` on HTTP 200 |
+
+See [`02-invoices.md`](./02-invoices.md#manual-tx-hash-claim) for the full lifecycle.
+
 ### Transient — retry
 
 | Class | `error_code` | Notes |
 |---|---|---|
 | `TxnodRateLimitError` | `rate_limit_exceeded` | `.retry_after_seconds` holds the `Retry-After` value. The SDK already retries once internally; this is what you see after retries are exhausted |
-| `TxnodPoolExhaustedError` | `pool_exhausted` | Pool hit hard cap (`poolSizePerChain[chain]`). `.retry_after_seconds` holds the server-computed `Retry-After` (soonest `locked_until` or project cooldown). Wait it out, or raise the cap if it fires under steady load |
+| `TxnodError` (generic) | `manual_claim_rate_limit_exceeded` | HTTP 429 with `Retry-After`. Per-user hourly throttle on `client.claimInvoiceByTx` (10 claims / hour / user). Falls through to the base `TxnodError` — branch on `err.error_code` to distinguish from the standard API rate limit |
+| `TxnodPoolExhaustedError` | `pool_exhausted` | Pool hit hard cap (`poolSizePerChain[chain]`). `.retry_after_seconds` holds the server-computed `Retry-After` (soonest `locked_until` or per-chain cooldown via `cooldownSecondsPerChain[chain]`). Wait it out, or raise the cap if it fires under steady load |
 | `TxnodWebhookCapacityExhaustedError` | `webhook_capacity_exhausted` | Webhook fleet for this chain has no spare slots. `.retry_after_seconds` is always `0` because a partner retry alone won't free capacity — treat as transient outage and queue the invoice for a later retry |
 | `TxnodServerError` | `internal_error` | 5xx classified as uncategorized — retryable with backoff |
 
@@ -129,7 +149,7 @@ Server-side TON failures that surface to partner code on `createInvoice` (or dow
 | `TxnodTonOperatorWalletNotDeployedError` | `ton_operator_wallet_not_deployed` | TON operator wallet has not been deployed on-chain yet — operator must broadcast the wallet's `StateInit` (typical first send) before invoices can resolve. HTTP 422 |
 | `TxnodTonInvalidWalletVersionError` | `ton_invalid_wallet_version` | Configured wallet version does not match the deployed one. Operator must reconcile `TXNOD_TON_WALLET_VERSION` with the actual deployed version (`v3R2` / `v4R2` / `v5`). HTTP 422 |
 | `TxnodTonJettonResolveFailedError` | `ton_jetton_resolve_failed` | Toncenter v3 or TONAPI failed to resolve the jetton master/wallet pair (provider hiccup, typically transient). HTTP 503 — retry with backoff |
-| `TxnodTonCommentParseFailedError` | `ton_comment_parse_failed` | Inbound TON tx carried a malformed `payment_token` comment that did not parse as the expected 8-hex memo. Indicates a mis-formed wallet send; operator review required. HTTP 422 |
+| `TxnodTonCommentParseFailedError` | `ton_comment_parse_failed` | Inbound TON tx carried a malformed `payment_token` comment that did not parse as the expected memo shape (8 or 16 lowercase hex). Indicates a mis-formed wallet send; operator review required. HTTP 422 |
 
 ### TonConnect operator-onboarding
 
@@ -147,7 +167,7 @@ Raised by the operator's TonConnect signing flow during xpub onboarding — neve
 
 ### Sandbox lifecycle + simulation
 
-Raised by the sandbox surface (`/api/v1/sandbox/*` REST + the 14 `client.sandbox.*` SDK methods + `sandbox:simulate` MCP scope). See [`05-sandbox.md`](./05-sandbox.md) for the full lifecycle.
+Raised by the sandbox surface (`/api/v1/sandbox/*` REST + the `client.sandbox.*` SDK methods + `sandbox:simulate` MCP scope). See [`05-sandbox.md`](./05-sandbox.md) for the full lifecycle.
 
 | Class | `error_code` | Meaning |
 |---|---|---|

package/docs/05-sandbox.md

@@ -1,12 +1,12 @@
 ---
 title: "Sandbox"
 description: "client.sandbox.* surface, environment-detection guards, layered defenses against routing real customer funds to sandbox addresses."
-sdk_version: 1.0.0
+sdk_version: 1.0.2
 ---
 
 # Sandbox
 
-The `@txnod/sdk` ships a sandbox surface (`client.sandbox.*` and 14 matching MCP tools) for deterministic integration testing. **Sandbox secrets and sandbox projects exist in the same Postgres database as production — there is no separate environment.** Discrimination happens via:
+The `@txnod/sdk` ships a sandbox surface (`client.sandbox.*` with matching MCP tools on the server) for deterministic integration testing. **Sandbox secrets and sandbox projects exist in the same Postgres database as production — there is no separate environment.** Discrimination happens via:
 
 1. The `sk_sandbox_` API-secret prefix.
 2. A `projects.kind` column whose value is `'sandbox'` or `'production'`.
@@ -91,7 +91,7 @@ The override option is deliberately verbose — it must remain awkward to type.
 
 ## `client.sandbox.*` surface
 
-All 14 methods sign with the same HMAC scheme as the rest of the SDK and throw the typed sandbox-* error classes per the SDK's typed-error contract.
+All sandbox methods sign with the same HMAC scheme as the rest of the SDK and throw the typed sandbox-* error classes per the SDK's typed-error contract.
 
 | Method | HTTP | Returns | Throws |
 |---|---|---|---|
@@ -105,6 +105,7 @@ All 14 methods sign with the same HMAC scheme as the rest of the SDK and throw t
 | `simulateReconfirm(invoiceId)` | `POST .../simulate-reconfirm` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `reverted`) |
 | `simulateDuplicateDelivery(invoiceId)` | `POST .../simulate-duplicate-delivery` | `{ event_id }` | `TxnodSandboxInvoiceTerminalError` (no terminal event yet) |
 | `simulateEvent(invoiceId, eventInput)` | `POST .../simulate-event` | `{ event_id, status }` | `TxnodSandboxInvoiceTransitionInvalidError` (current status != `expectedCurrentStatus`) |
+| `simulateClaimByTx(invoiceId, args)` | `POST .../claim-by-tx` | `ClaimByTxResponse` | Generic `TxnodError` with `error_code: 'manual_claim_rate_limit_exceeded'` (per-user 10/hour throttle); rejection paths return in the response body, not thrown |
 | `clockAdvance(projectId, params)` | `POST /api/v1/sandbox/{projectId}/clock/advance` | `{ advanced, remaining }` | `TxnodSandboxRateLimitExceededError` (>10/min/project) |
 | `reset(projectId)` | `POST /api/v1/sandbox/{projectId}/reset` | `{ status: 'reset' }` | `TxnodSandboxResetFailedError` |
 | `destroy(projectId)` | `DELETE /api/v1/sandbox/{projectId}` | `{ status: 'deleted' }` | `TxnodSandboxDeleteFailedError` |

package/docs/reference/client.md

@@ -1,7 +1,7 @@
 ---
 title: "TxnodClient reference"
 description: "Every method of TxnodClient and the verifyWebhookSignature helper: signature, behaviour, and a minimal example."
-sdk_version: 1.0.0
+sdk_version: 1.0.2
 ---
 
 # `TxnodClient` reference
@@ -242,6 +242,36 @@ attributeOrphanPayment(
 
 ---
 
+## `claimInvoiceByTx`
+
+Submit a manual tx-hash claim for an open invoice — the "I paid but it's not showing up" recovery path. The server resolves the tx via the chain provider, verifies sender / recipient / amount / timestamp, and either auto-attributes, queues for operator review, defers pending finality, or rejects.
+
+**Signature**
+
+```ts
+claimInvoiceByTx(args: {
+  invoiceId: string;
+  txHash: string;
+  chain: Chain;
+}): Promise<ClaimByTxResponse>
+```
+
+**Response (`ClaimByTxResponse`)**
+
+| Field | Type | Notes |
+|---|---|---|
+| `request_id` | ULID | Request correlation id |
+| `status` | `'auto_attributed' \| 'pending_review' \| 'pending_finality' \| 'rejected'` | Outcome discriminator |
+| `terminal_status` | `'paid' \| 'overpaid' \| 'partial' \| 'expired_paid_late' \| null` | Present when `status === 'auto_attributed'` |
+| `resolved_facts` | `ResolvedFacts \| null` | Sender / recipient / amount / confirmations / timestamp as resolved from the chain provider |
+| `rejection_reason` | `'tx_not_found_or_incomplete' \| 'tx_already_attributed' \| null` | Present when `status === 'rejected'` |
+
+**Throws**: generic `TxnodError` with `error_code: 'manual_claim_rate_limit_exceeded'` (HTTP 429, per-user 10/hour throttle). The `tx_not_found_or_incomplete` and `tx_already_attributed` rejection paths are returned in the response body, not thrown.
+
+See [`../02-invoices.md#manual-tx-hash-claim`](../02-invoices.md#manual-tx-hash-claim) for the full lifecycle and a worked example.
+
+---
+
 ## `listWebhookEvents`
 
 Paginated audit list of outbound webhook events for the calling project.
@@ -291,7 +321,7 @@ resendWebhookEvent(eventId: string): Promise<WebhookEventResendResponse>
 
 ## Sandbox surface (`client.sandbox.*`)
 
-Lazy accessor (`client.sandbox` is constructed on first use; bundlers tree-shake the entire namespace when never referenced) onto the 14 sandbox-mode endpoints introduced by Story 37.2. Use it from a sandbox-API-secret-authenticated client (`apiSecret: 'sk_sandbox_...'` + `environment: 'non-production'`) — production secrets cannot reach these routes (the server returns `production_key_against_sandbox_project`). See [`../05-sandbox.md`](../05-sandbox.md) for the lifecycle picture and per-method worked examples.
+Lazy accessor (`client.sandbox` is constructed on first use; bundlers tree-shake the entire namespace when never referenced) onto the sandbox-mode endpoints. Use it from a sandbox-API-secret-authenticated client (`apiSecret: 'sk_sandbox_...'` + `environment: 'non-production'`) — production secrets cannot reach these routes (the server returns `production_key_against_sandbox_project`). See [`../05-sandbox.md`](../05-sandbox.md) for the lifecycle picture and per-method worked examples.
 
 ```ts
 const client = new TxnodClient({

package/docs/reference/errors.md

@@ -1,7 +1,7 @@
 ---
 title: "Error class catalogue"
 description: "Complete error_code → class lookup and the narrative groups."
-sdk_version: 1.0.0
+sdk_version: 1.0.2
 ---
 
 # Error class catalogue
@@ -56,6 +56,7 @@ The 55-row lookup below covers every server-emitted code in `ERROR_CODES` (58 en
 |---|---|---|---|
 | `external_id_conflict` | `TxnodExternalIdConflictError` | 409 | **Idempotent** — fetch existing |
 | `orphan_already_attributed` | `TxnodOrphanAlreadyAttributedError` | 409 | **Idempotent** — treat as success |
+| `overlay_matching_mode_required_exact` | `TxnodOverlayMatchingModeError` | 422 | Pool saturation forced the allocator into `required_exact`; project's `matching_mode` must be flipped or the pool must drain |
 | `wallet_not_bound` | `TxnodWalletNotBoundError` | 422 | Operator must bind a verified wallet of matching kind for the requested chain before invoice creation succeeds |
 | `wallet_not_owned` | `TxnodWalletNotOwnedError` | 403 | **Dashboard-only** — never reaches partner API |
 | `wallet_has_active_bindings` | `TxnodWalletHasActiveBindingsError` | 409 | **Dashboard-only** — never reaches partner API |
@@ -71,6 +72,15 @@ The 55-row lookup below covers every server-emitted code in `ERROR_CODES` (58 en
 | `ton_jetton_resolve_failed` | `TxnodTonJettonResolveFailedError` | 503 | Toncenter/TONAPI hiccup resolving the jetton master/wallet pair — retry with backoff |
 | `ton_comment_parse_failed` | `TxnodTonCommentParseFailedError` | 422 | Inbound TON tx carried a malformed `payment_token` comment |
 
+### Manual tx-hash claim flow
+
+Returned in the **response body** as `{ status: 'rejected', rejection_reason }` on HTTP 200 — these two codes are not raised by `parseProblemDetails`. The classes below exist as helpers for partners who prefer to throw on the rejection paths themselves.
+
+| `error_code` | Class | HTTP status | Notes |
+|---|---|---|---|
+| `tx_not_found_or_incomplete` | `TxnodTxNotFoundError` | 200 (body) | Chain provider could not resolve the tx, or facts (recipient / amount / state) do not match the invoice |
+| `tx_already_attributed` | `TxnodTxAlreadyAttributedError` | 200 (body) | The submitted tx was previously credited to an invoice |
+
 ### TonConnect (operator-onboarding)
 
 These never reach partner methods — they fire on the operator's TonConnect signing flow during xpub onboarding. Exported so the dashboard's typed-error catch can branch correctly.
@@ -87,7 +97,7 @@ These never reach partner methods — they fire on the operator's TonConnect sig
 
 ### Sandbox (lifecycle + simulation)
 
-Surfaced by `/api/v1/sandbox/*` REST endpoints, the 14 `client.sandbox.*` SDK methods, and the `sandbox:simulate`-scoped MCP tools.
+Surfaced by `/api/v1/sandbox/*` REST endpoints, the `client.sandbox.*` SDK methods, and the `sandbox:simulate`-scoped MCP tools.
 
 | `error_code` | Class | HTTP status | Notes |
 |---|---|---|---|
@@ -109,6 +119,7 @@ Surfaced by `/api/v1/sandbox/*` REST endpoints, the 14 `client.sandbox.*` SDK me
 | `error_code` | Class | HTTP status | Notes |
 |---|---|---|---|
 | `rate_limit_exceeded` | `TxnodRateLimitError` | 429 | `.retry_after_seconds` |
+| `manual_claim_rate_limit_exceeded` | `TxnodError` (generic) | 429 | Per-user hourly throttle on `client.claimInvoiceByTx` (10/hour/user); falls through to base `TxnodError` — branch on `err.error_code` |
 | `pool_exhausted` | `TxnodPoolExhaustedError` | 503 | `.retry_after_seconds` — hard-cap hit, wait for cooldown |
 | `webhook_capacity_exhausted` | `TxnodWebhookCapacityExhaustedError` | 503 | `.retry_after_seconds` always `0` — partner retry alone won't free capacity, treat as transient outage |
 | `internal_error` | `TxnodServerError` | 5xx | Log `request_id`, retryable |

package/docs/reference/types.md

@@ -1,7 +1,7 @@
 ---
 title: "Type reference"
 description: "Authoritative type shapes for requests, responses, and shared primitives."
-sdk_version: 1.0.0
+sdk_version: 1.0.2
 ---
 
 # Type reference
@@ -200,7 +200,8 @@ type WebhookEventType =
   | 'invoice.partial'
   | 'invoice.expired'
   | 'invoice.expired_paid_late'
-  | 'invoice.reverted';
+  | 'invoice.reverted'
+  | 'invoice.ambiguous';
 
 type WebhookEventData = {
   invoice_id: string;
@@ -212,7 +213,7 @@ type WebhookEventData = {
   amount_units: string;                    // integer string in smallest unit
   confirmations: number;
   block_height: number | null;
-  payment_token: string | null;            // TON only — 8-hex memo token
+  payment_token: string | null;            // TON only — lowercase hex memo token (8 or 16 chars)
   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; } } | null;
   reason?: 'reorg' | 'late_arrival';        // present on reverted/expired_paid_late
@@ -372,7 +373,7 @@ type CursorPaginatedOrphanPaymentResponse = {
 };
 ```
 
-> **TRON activation events never appear here.** Story 31.3 server-side filter excludes inbound activation transactions (operator-funded TRX/USDT sends that activate a fresh address) from orphan classification — partners do not need to dedupe them client-side.
+> **TRON activation events never appear here.** A server-side filter excludes inbound activation transactions (operator-funded TRX/USDT sends that activate a fresh address) from orphan classification — partners do not need to dedupe them client-side.
 
 ## `ProblemDetails`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@txnod/sdk",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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",