@txnod/sdk 1.0.1

package/docs/reference/types.md

@@ -0,0 +1,400 @@
+---
+title: "Type reference"
+description: "Authoritative type shapes for requests, responses, and shared primitives."
+sdk_version: 1.0.0
+---
+
+# Type reference
+
+The `@txnod/sdk` package re-exports six type names directly for partner use in `import type` annotations:
+
+- `Coin`
+- `Chain`
+- `Network`
+- `InvoiceStatus`
+- `WebhookEvent`
+- `WebhookEventType`
+
+All other request/response types are derived at build time from the server's Zod schemas, fully expanded to plain TypeScript, and shipped inside this tarball as `./dist/_shared/index.d.ts`. Partners install **only** `@txnod/sdk` — no `@txnod/*` package, no `zod`, no other peer dependency. **Authoritative source is `./dist/index.d.ts` inside this package.** When this markdown disagrees with `.d.ts`, trust `.d.ts`.
+
+This file is a guided index — each section points at the TS source in the monorepo for context when needed, and summarizes the shape for quick agent consumption.
+
+## `Coin`
+
+```ts
+type Coin =
+  | 'btc'
+  | 'eth'
+  | 'usdt_erc20'
+  | 'usdc_erc20'
+  | 'trx'
+  | 'usdt_trc20'
+  | 'ada'
+  | 'pol'
+  | 'usdt_polygon'
+  | 'usdc_polygon'
+  | 'bnb'
+  | 'usdt_bep20'
+  | 'usdc_bep20'
+  | 'ton'
+  | 'usdt_ton';
+```
+
+Source: `packages/shared/src/schemas/coin.ts`.
+
+Chain mapping:
+
+| Coin | Chain |
+|---|---|
+| `btc` | `btc` |
+| `eth`, `usdt_erc20`, `usdc_erc20` | `eth` |
+| `trx`, `usdt_trc20` | `tron` |
+| `ada` | `ada` |
+| `pol`, `usdt_polygon`, `usdc_polygon` | `polygon` |
+| `bnb`, `usdt_bep20`, `usdc_bep20` | `bsc` |
+| `ton`, `usdt_ton` | `ton` |
+
+## `Chain`
+
+```ts
+type Chain = 'btc' | 'eth' | 'ada' | 'ton' | 'tron' | 'polygon' | 'bsc';
+```
+
+`Coin` resolves to a `Chain` per the table above.
+
+## `InvoiceStatus`
+
+```ts
+type InvoiceStatus =
+  | 'pending'
+  | 'detected'
+  | 'paid'
+  | 'overpaid'
+  | 'partial'
+  | 'expired'
+  | 'expired_paid_late'
+  | 'reverted'
+  | 'cancelled';
+```
+
+See [`../02-invoices.md`](../02-invoices.md#lifecycle) for semantics.
+
+## `InvoiceCreateRequest`
+
+Required fields: `external_id`, `coin`, and exactly one of `amount_usd` / `amount_crypto`.
+
+```ts
+type InvoiceCreateRequest = {
+  external_id: string;                    // 1..128 chars
+  coin: Coin;
+  amount_usd?: number;                    // positive finite; XOR with amount_crypto
+  amount_crypto?: string;                 // decimal /^\d+(\.\d+)?$/; XOR with amount_usd
+  callback_url?: string;                  // https URL
+  metadata?: Record<string, unknown>;
+};
+```
+
+## `InvoiceResponse`
+
+```ts
+type InvoiceResponse = {
+  id: string;                              // ULID, txnod primary key
+  project_id: string;                      // ULID
+  external_id: string;
+  coin: Coin;
+  address: string;                         // deposit address
+  amount_crypto: string;                   // decimal string in display units
+  amount_crypto_units: string;             // integer string in smallest unit
+  amount_usd: number | null;               // null if request used amount_crypto
+  rate_snapshot: {
+    rate: string;                          // decimal USD per 1 coin
+    source: 'coingecko';
+    quoted_at: string;                     // ISO-8601 UTC
+    rate_is_stale: boolean;
+    rate_age_seconds: number;              // int ≥ 0
+  } | null;                                // null if amount_crypto was supplied
+  payment_uri: string;                          // BIP-21 / EIP-681 / Cardano
+  callback_url: string | null;
+  metadata: Record<string, unknown> | null;
+  matching_mode: 'exact' | 'at_least' | 'any';
+  confirmation_threshold: number;
+  status: InvoiceStatus;
+  expires_at: number;                      // unix seconds
+  expires_at_iso: string;                  // ISO-8601 UTC
+  created_at: number;
+  created_at_iso: string;
+  transactions?: InvoiceTransactionResponse[]; // present when expanded
+  confirmations?: number;                  // present on detail
+};
+```
+
+## `InvoiceTransactionResponse`
+
+```ts
+type InvoiceTransactionResponse = {
+  id: string;                              // ULID
+  chain: Chain;                            // 'btc' | 'eth' | 'tron' | 'ada' | 'polygon' | 'bsc' | 'ton'
+  tx_hash: string;
+  to_address: string;
+  tx_output_index: number;                 // int ≥ 0
+  amount_units: string;                    // integer string in smallest unit
+  block_height: number | null;
+  confirmations: number;
+  received_at: number;
+  received_at_iso: string;
+  orphaned_at: number | null;
+  orphaned_at_iso: string | null;
+};
+```
+
+## `InvoiceSearchQuery`
+
+```ts
+type InvoiceSearchQuery = {
+  external_id?: string;
+  address?: string;
+  tx_hash?: string;
+  amount?: string;
+  status?: InvoiceStatus;
+  date_from?: string;                      // ISO-8601
+  date_to?: string;                        // ISO-8601
+  cursor?: string;                         // ULID
+  limit?: number;                          // 1..200, default 50
+};
+```
+
+## `WalletEdgeKind`
+
+```ts
+type WalletEdgeKind = 'production' | 'testnet';
+```
+
+Source: `packages/shared/src/db/tables/kinds.ts`. Replaces the prior `Network` re-export. Sandbox is excluded by design — sandbox addresses are simulated, not derived from real chain provider URLs.
+
+## `ProjectKind`
+
+```ts
+type ProjectKind = 'production' | 'testnet' | 'sandbox';
+```
+
+The full discriminator on every project (and every wallet, binding, invoice). The webhook envelope `mode` field is typed `ProjectKind`.
+
+## `CursorPaginatedInvoiceResponse`
+
+```ts
+type CursorPaginatedInvoiceResponse = {
+  items: InvoiceResponse[];
+  next_cursor?: string;                    // omitted on the last page; pass to the next call to continue
+};
+```
+
+## `WebhookEvent`
+
+Discriminated union on `event_type` — `event.data` is fully typed after a narrowing switch on `event.event_type`. **No casts are needed** to read `event.data.invoice_id` once you have narrowed.
+
+```ts
+type WebhookEventType =
+  | 'invoice.detected'
+  | 'invoice.paid'
+  | 'invoice.overpaid'
+  | 'invoice.partial'
+  | 'invoice.expired'
+  | 'invoice.expired_paid_late'
+  | 'invoice.reverted';
+
+type WebhookEventData = {
+  invoice_id: string;
+  project_id: string;
+  chain: Chain;
+  coin: Coin;
+  tx_hash: string;
+  to_address: string | null;
+  amount_units: string;                    // integer string in smallest unit
+  confirmations: number;
+  block_height: number | null;
+  payment_token: string | null;            // TON only — 8-hex memo token
+  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
+};
+
+type WebhookEvent = {
+  event_id: string;                        // ULID, stable across retries
+  event_type: WebhookEventType;             // discriminant
+  created_at: number;                      // unix seconds
+  created_at_iso: string;                  // ISO-8601 UTC
+  project_id: string;                      // ULID
+  data: WebhookEventData;                  // fully typed under each event_type branch
+  attempt: number;                         // 1-based
+  mode: 'production' | 'testnet' | 'sandbox'; // envelope discriminator across project kinds
+};
+```
+
+The `mode` field lets a single handler accept production, testnet, and sandbox traffic and assert which surface generated each delivery — the production secret signs production envelopes; the testnet secret signs `mode: 'testnet'` envelopes; the sandbox secret signs `mode: 'sandbox'` envelopes. Asserting `event.mode === expectedMode` after `verifyWebhookSignature` returns is the recommended fail-closed CI gate (see [`../05-sandbox.md`](../05-sandbox.md#recommended-ci-assertion)). The `mode` field is carried on the **delivered envelope** that arrives at your callback URL — not on the forensic-listing rows returned by `listWebhookEvents` (which omit the parsed payload entirely; they expose delivery state only).
+
+Example narrowing:
+
+```ts
+if (event.event_type === 'invoice.paid') {
+  // event.data.invoice_id is string here, no cast needed
+  console.log('paid', event.data.invoice_id, 'with', event.data.amount_units, 'units');
+}
+```
+
+The variants share the same `WebhookEventData` shape today; the discriminated-union type is preserved so future variant-specific fields (e.g. orphan-only fields) can land without breaking partner code.
+
+## `WebhookEventListApiQuery` / `WebhookEventListResponse`
+
+```ts
+type WebhookEventListApiQuery = {
+  status?: 'delivered' | 'retrying' | 'dlq' | 'skipped';
+  event_type?: WebhookEventType;
+  since?: string;                          // ISO-8601
+  invoice_id?: string;                     // ULID
+  cursor?: string;
+  limit?: number;                          // 1..200, default 50
+};
+
+type WebhookEventListResponse = {
+  items: {
+    id: string;
+    event_type: WebhookEventType;
+    status: 'delivered' | 'retrying' | 'dlq' | 'skipped';
+    created_at: string;                    // ISO-8601
+    target_url: string | null;
+    attempt_count: number;
+    last_response_status: number | null;
+    invoice_id: string | null;
+    dlq_at: string | null;
+    delivered_at: string | null;
+    skip_reason: 'not_subscribed' | 'no_target_url' | null;
+  }[];
+  next_cursor?: string;                    // omitted on the last page; pass to the next call to continue
+};
+```
+
+## `WebhookEventResendResponse`
+
+```ts
+type WebhookEventResendResponse = {
+  event_id: string;                        // new id
+  original_event_id: string;
+  event_type: WebhookEventType;
+  project_id: string;
+  invoice_id: string | null;
+  target_url: string | null;
+  created_at: number;
+  created_at_iso: string;
+};
+```
+
+## `RatesQuery` / `RatesResponse`
+
+```ts
+type RatesQuery = { coins?: string };      // CSV, optional
+
+type RatesResponse = {
+  quoted_at: string;                       // ISO-8601
+  source: 'coingecko';
+  rates: Partial<Record<Coin, {
+    rate: string;                          // decimal USD per 1 coin
+    rate_is_stale: boolean;
+    rate_age_seconds: number;              // int ≥ 0
+  }>>;
+  indicative_notice: string;
+};
+```
+
+## `QuoteQuery` / `QuoteResponse`
+
+```ts
+type QuoteQuery = {
+  amount_usd: number;                      // positive finite
+  coins?: string;                          // CSV, optional
+};
+
+type QuoteResponse = {
+  amount_usd: number;
+  quoted_at: string;
+  source: 'coingecko';
+  quotes: Partial<Record<Coin, {
+    amount_crypto: string;                 // decimal
+    amount_crypto_units: string;           // integer smallest unit
+    rate: string;                          // decimal USD per 1 coin
+    rate_is_stale: boolean;
+    rate_age_seconds: number;
+  }>>;
+  indicative_notice: string;
+};
+```
+
+## `OrphanPaymentListQuery`, `OrphanAttributeRequest`, `CursorPaginatedOrphanPaymentResponse`
+
+```ts
+type OrphanPaymentListQuery = {
+  attributed?: boolean;
+  chain?: 'btc' | 'eth' | 'tron' | 'ada' | 'polygon' | 'bsc' | 'ton';
+  tx_hash?: string;
+  date_from?: string;
+  date_to?: string;
+  amount_units_gte?: string;
+  amount_units_lte?: string;
+  cursor?: string;
+  limit?: number;                          // 1..200, default 50
+};
+
+type OrphanAttributeRequest = {
+  external_id: string;                     // 1..128
+  user_id?: string;                        // 1..256
+  metadata?: Record<string, unknown>;
+  to_address?: string;
+  tx_output_index?: number;                // int ≥ 0
+};
+
+type CursorPaginatedOrphanPaymentResponse = {
+  items: {
+    id: string;
+    chain: Chain;
+    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;                    // omitted on the last page
+};
+```
+
+> **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.
+
+## `ProblemDetails`
+
+Raw RFC 7807 envelope surfaced via `TxnodError.raw`:
+
+```ts
+type ProblemDetails = {
+  type: string;
+  title: string;
+  status: number;
+  detail?: string;
+  instance?: string;
+  error_code: ErrorCode;
+  request_id: string;
+  errors?: unknown;                        // per-field Zod issues on validation_error
+  meta?: Record<string, unknown>;
+};
+```
+
+See [`errors.md`](./errors.md) for the `error_code` enum.
+
+## Related
+
+- [`client.md`](./client.md) — which method uses which type
+- [`../02-invoices.md`](../02-invoices.md), [`../03-rates-and-quotes.md`](../03-rates-and-quotes.md), [`../04-webhooks.md`](../04-webhooks.md) — usage context

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@txnod/sdk",
+  "version": "1.0.1",
+  "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",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs",
+    "AGENTS.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@noble/curves": "2.2.0",
+    "@noble/ed25519": "3.1.0",
+    "@noble/hashes": "2.2.0",
+    "@scure/base": "2.2.0",
+    "@scure/bip32": "2.2.0",
+    "pino": "10.3.1"
+  },
+  "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"
+  }
+}