@txnod/sdk 1.0.1 → 1.1.0

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({
@@ -308,6 +338,12 @@ const r = await client.sandbox.simulatePaid('01HK8MAR2QEXAMPLE000000000');
 
 | Method | HTTP | Returns | Throws |
 |---|---|---|---|
+| `createInvoice(body)` | `POST /api/v1/sandbox/invoices` | `InvoiceResponse` | `TxnodSandboxActiveInvoiceCapReachedError` (10k active cap), `TxnodCoinNotEnabledError`, `TxnodRateQuoteUnavailableError` |
+| `getInvoice(invoiceId)` | `GET /api/v1/sandbox/invoices/{invoiceId}` | `InvoiceDetailResponse` | `TxnodInvoiceNotFoundError` |
+| `listInvoices(query?)` | `GET /api/v1/sandbox/invoices` | `CursorPaginatedInvoiceResponse` | `TxnodValidationError` |
+| `cancelInvoice(invoiceId)` | `POST /api/v1/sandbox/invoices/{invoiceId}/cancel` | `InvoiceDetailResponse` | `TxnodInvoiceNotFoundError`, `TxnodInvoiceNotCancellableError` |
+| `listWebhookEvents(query?)` | `GET /api/v1/sandbox/webhooks/events` | `WebhookEventListResponse` | `TxnodValidationError` |
+| `resendWebhookEvent(eventId)` | `POST /api/v1/sandbox/webhooks/events/{eventId}/resend` | `WebhookEventResendResponse` | `TxnodEventNotFoundError`, `TxnodEventNotResendableError` (in-flight or dead-lettered) |
 | `simulateDetect(invoiceId, opts?)` | `POST /api/v1/sandbox/invoices/{invoiceId}/simulate-detect` | `{ event_id, status: 'detected' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `pending`), `TxnodSandboxInvoiceNotFoundError` |
 | `simulatePaid(invoiceId, opts?)` | `POST .../simulate-paid` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` (invoice not in `detected`) |
 | `simulateOverpaid(invoiceId, params)` | `POST .../simulate-overpaid` | `{ event_id, status: 'paid' }` | `TxnodSandboxInvoiceTransitionInvalidError` |
@@ -318,6 +354,7 @@ const r = await client.sandbox.simulatePaid('01HK8MAR2QEXAMPLE000000000');
 | `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/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.1.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",
@@ -20,6 +20,17 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "scripts": {
+    "build": "pnpm --filter @txnod/shared build && tsc --build && node scripts/bundle-shared-types.mjs",
+    "typecheck": "tsc --build",
+    "lint": "eslint src",
+    "test": "vitest run --config vitest.unit.config.ts",
+    "test:contract": "pnpm run build && vitest run --config vitest.contract.config.ts",
+    "check:bundle-size": "bash ../../scripts/ci/sdk-bundle-size.sh",
+    "check:dep-allowlist": "bash ../../scripts/ci/sdk-dep-allowlist.sh",
+    "check:pack-whitelist": "bash ../../scripts/ci/sdk-pack-whitelist.sh",
+    "check:dts-self-contained": "bash ../../scripts/ci/sdk-dts-self-contained.sh"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -38,16 +49,5 @@
   "devDependencies": {
     "@testcontainers/postgresql": "11.14.0",
     "@ton/ton": "16.2.4"
-  },
-  "scripts": {
-    "build": "pnpm --filter @txnod/shared build && tsc --build && node scripts/bundle-shared-types.mjs",
-    "typecheck": "tsc --build",
-    "lint": "eslint src",
-    "test": "vitest run --config vitest.unit.config.ts",
-    "test:contract": "pnpm run build && vitest run --config vitest.contract.config.ts",
-    "check:bundle-size": "bash ../../scripts/ci/sdk-bundle-size.sh",
-    "check:dep-allowlist": "bash ../../scripts/ci/sdk-dep-allowlist.sh",
-    "check:pack-whitelist": "bash ../../scripts/ci/sdk-pack-whitelist.sh",
-    "check:dts-self-contained": "bash ../../scripts/ci/sdk-dts-self-contained.sh"
   }
-}
+}