@txnod/sdk 1.0.1

package/dist/client.d.ts

@@ -0,0 +1,429 @@
+import type { InvoiceCreateRequest, InvoiceResponse, InvoiceSearchQuery, CursorPaginatedInvoiceResponse, OrphanPaymentListQuery, CursorPaginatedOrphanPaymentResponse, OrphanAttributeRequest, WebhookEventListApiQuery, WebhookEventListResponse, WebhookEventResendResponse, RatesQuery, RatesResponse, QuoteQuery, QuoteResponse } from './_shared/index.js';
+import { type SignedFetchRequestLogEntry, type SignedFetchRequestLogger } from './internals/fetch-with-retry.js';
+import { TxnodClientSandbox } from './client-sandbox.js';
+/**
+ * One log line per HTTP attempt — emitted to {@link TxnodClientOptions.requestLogger}
+ * if provided. Useful for correlating timeouts, 429 / 5xx retries, and slow
+ * downstream calls with `request_id` server-side.
+ */
+export type TxnodRequestLogEntry = SignedFetchRequestLogEntry;
+/**
+ * Per-attempt observer signature. Errors thrown from the logger are swallowed
+ * by the SDK so a buggy logger never fails a request.
+ */
+export type TxnodRequestLogger = SignedFetchRequestLogger;
+export interface TxnodClientOptions {
+    projectId: string;
+    apiSecret: string;
+    baseUrl?: string;
+    /**
+     * Per-attempt HTTP timeout in ms, applied to every retry separately.
+     * Defaults to 30,000 ms. Set to a higher value for slow chains or to a
+     * lower value for fast-fail user-facing flows.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Maximum acceptable response body size in bytes. Responses exceeding this
+     * are surfaced to the caller as `502 internal_error` so the SDK never
+     * buffers an unbounded payload from a hostile or misbehaving upstream.
+     * Defaults to 1 MiB — well above any legitimate TxNod response.
+     */
+    maxResponseBytes?: number;
+    /**
+     * Optional per-attempt logger. Receives one entry per HTTP call (success or
+     * failure, including each retry). Use it to correlate latency and
+     * `request_id` with your application logs.
+     */
+    requestLogger?: TxnodRequestLogger;
+    /**
+     * Explicit environment override. When set, takes precedence over
+     * TXNOD_ENVIRONMENT and NODE_ENV. Use this for staging replicas where
+     * NODE_ENV is conventionally 'production' but the secret is sandbox.
+     */
+    environment?: 'production' | 'non-production';
+    /**
+     * DELIBERATELY long, uncomfortable opt-in: bypass the SDK's
+     * sandbox-secret-in-production hard-fail. Setting this flag does NOT
+     * suppress the persistent console.error on every process start, and adds
+     * an X-Txnod-Client-Environment: production header to every API call.
+     *
+     * Renaming this option in any future SDK version requires a major-version
+     * bump and a deprecation cycle.
+     */
+    iAcknowledgeRoutingRealCustomerFundsToSandboxAddresses?: boolean;
+}
+/**
+ * Typed client for the TxNod integration API. Every method signs outbound
+ * requests with HMAC-SHA256 using `apiSecret`, retries on 429 and 5xx, and
+ * throws `TxnodError` on non-2xx responses.
+ *
+ * @example
+ * ```ts
+ * import { TxnodClient } from '@txnod/sdk';
+ *
+ * const client = new TxnodClient({
+ *   projectId: process.env.TXNOD_PROJECT_ID!,
+ *   apiSecret: process.env.TXNOD_API_SECRET!,
+ * });
+ *
+ * const invoice = await client.createInvoice({
+ *   amount_usd: 10.0,
+ *   coin: 'btc',
+ *   external_id: 'order-123',
+ *   callback_url: 'https://my-site.com/webhooks/txnod',
+ * });
+ * console.log(invoice.id, invoice.address);
+ * ```
+ */
+export declare class TxnodClient {
+    #private;
+    /**
+     * Server `X-Txnod-Request-Id` header from the most recently completed call,
+     * regardless of HTTP status. Reset to `undefined` at the start of every call,
+     * so a value here always corresponds to the call that just finished. Use it
+     * to correlate a successful response with TxNod-side logs (on failure paths
+     * the same id is also surfaced as `err.request_id` on the thrown
+     * `TxnodError`).
+     *
+     * Caveat: the field is per-instance, not per-call. Concurrent calls on a
+     * shared `TxnodClient` will overwrite each other; create a new client per
+     * request scope, or read the field synchronously after `await`-ing a single
+     * call.
+     */
+    lastRequestId: string | undefined;
+    constructor(options: TxnodClientOptions);
+    /**
+     * Lazy accessor for the `client.sandbox.*` namespace exposing 14 thin HTTP
+     * wrappers around `/api/v1/sandbox/...` endpoints. The namespace class is
+     * only constructed on first access — when an integrator never references
+     * `client.sandbox`, the bundler's tree-shaker drops the entire
+     * `TxnodClientSandbox` class graph from the produced bundle.
+     *
+     * Methods throw the typed sandbox-specific error classes (e.g.
+     * `TxnodSandboxInvoiceTransitionInvalidError`) on 4xx/5xx server responses
+     * per FR55. See `docs/05-sandbox.md` in the bundled tarball for the full
+     * surface and code examples.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient, TxnodSandboxInvoiceTransitionInvalidError } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     *   environment: 'non-production',
+     * });
+     *
+     * try {
+     *   const result = await client.sandbox.simulatePaid('01HK8MAR2QEXAMPLE000000000');
+     *   console.log(result.event_id, result.status);
+     * } catch (err) {
+     *   if (err instanceof TxnodSandboxInvoiceTransitionInvalidError) {
+     *     console.error('forbidden simulate transition', err.request_id);
+     *   } else {
+     *     throw err;
+     *   }
+     * }
+     * ```
+     */
+    get sandbox(): TxnodClientSandbox;
+    /**
+     * 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
+     * wallet rotation in long-lived processes (Lambda containers, daemon-style
+     * workers) where the constructor ran with stale env values. Idempotent —
+     * calling it when env is unchanged is a no-op.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient } from '@txnod/sdk';
+     *
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     * });
+     *
+     * // Operator rotated their xpub via the dashboard and your secrets manager
+     * // pushed the new TXNOD_BTC_XPUB into process.env. Pick it up without a restart:
+     * process.env.TXNOD_BTC_XPUB = 'zpub6r_NEW';
+     * client.refreshXpubConfig();
+     *
+     * // Subsequent createInvoice calls now verify the address against the new xpub.
+     * await client.createInvoice({
+     *   external_id: 'after-rotation',
+     *   coin: 'btc',
+     *   amount_usd: 10,
+     * });
+     * ```
+     */
+    refreshXpubConfig(): void;
+    /**
+     * Create a new invoice. Idempotent on `(project_id, external_id)`. When the
+     * matching `TXNOD_<chain>_XPUB` env var is set, the SDK automatically
+     * verifies the returned address derives from the configured xpub at the
+     * invoice's `derivation_path` and throws `AddressVerificationError` on
+     * mismatch — no flag needed.
+     *
+     * @example
+     * ```ts
+     * import { TxnodClient, TxnodError, AddressVerificationError } from '@txnod/sdk';
+     *
+     * // Set TXNOD_BTC_XPUB=zpub6r... in env to enable address verification.
+     * const client = new TxnodClient({
+     *   projectId: process.env.TXNOD_PROJECT_ID!,
+     *   apiSecret: process.env.TXNOD_API_SECRET!,
+     * });
+     *
+     * try {
+     *   const invoice = await client.createInvoice({
+     *     amount_usd: 10.0,
+     *     coin: 'btc',
+     *     external_id: 'order-123',
+     *     callback_url: 'https://my-site.com/webhooks/txnod',
+     *   });
+     *   console.log(invoice.id, invoice.address, invoice.payment_uri);
+     * } catch (err) {
+     *   if (err instanceof AddressVerificationError) {
+     *     console.error('address verify failed', err.expected_address, err.derived_address);
+     *   } else if (err instanceof TxnodError) {
+     *     console.error(err.error_code, err.status, err.request_id);
+     *   }
+     *   throw err;
+     * }
+     * ```
+     */
+    createInvoice(body: InvoiceCreateRequest): Promise<InvoiceResponse>;
+    /**
+     * Idempotent invoice creation. Tries `createInvoice`; on
+     * `TxnodExternalIdConflictError` fetches the pre-existing invoice via
+     * `searchInvoices({ external_id })` and returns it. Use this when your
+     * checkout flow may retry the same `external_id` (network glitches, idempotent
+     * upstream queues) and you want a single round-trip-then-fetch path.
+     *
+     * @example
+     * ```ts
+     * const invoice = await client.createOrGetInvoice({
+     *   external_id: 'order-42',
+     *   coin: 'usdt_trc20',
+     *   amount_usd: 9.99,
+     * });
+     * ```
+     */
+    createOrGetInvoice(body: InvoiceCreateRequest): Promise<InvoiceResponse>;
+    /**
+     * Fetch an invoice by ULID.
+     *
+     * @example
+     * ```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 invoice = await client.getInvoice('01HK8MAR2QEXAMPLE000000000');
+     *   console.log(invoice.status);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    getInvoice(id: string): Promise<InvoiceResponse>;
+    /**
+     * Search invoices with snake_case query filters.
+     *
+     * @example
+     * ```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 page = await client.searchInvoices({
+     *     status: 'paid',
+     *     limit: 20,
+     *   });
+     *   for (const invoice of page.items) console.log(invoice.id);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    searchInvoices(query: InvoiceSearchQuery): Promise<CursorPaginatedInvoiceResponse>;
+    /**
+     * Cancel a pending invoice.
+     *
+     * @example
+     * ```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 cancelled = await client.cancelInvoice('01HK8MAR2QEXAMPLE000000000');
+     *   console.log(cancelled.status);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    cancelInvoice(id: string): Promise<InvoiceResponse>;
+    /**
+     * List on-chain receipts that did not match any invoice address.
+     *
+     * @example
+     * ```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 page = await client.listOrphanPayments({ chain: 'btc', limit: 50 });
+     *   for (const orphan of page.items) console.log(orphan.tx_hash);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    listOrphanPayments(query: OrphanPaymentListQuery): Promise<CursorPaginatedOrphanPaymentResponse>;
+    /**
+     * Attribute an orphan payment to an external invoice id.
+     *
+     * @example
+     * ```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 invoice = await client.attributeOrphanPayment('0xabc123', {
+     *     external_id: 'order-123',
+     *   });
+     *   console.log(invoice.id);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    attributeOrphanPayment(txHash: string, body: OrphanAttributeRequest): Promise<InvoiceResponse>;
+    /**
+     * List outbound webhook events for the authenticated project.
+     *
+     * @example
+     * ```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 page = await client.listWebhookEvents({
+     *     status: 'delivered',
+     *     limit: 100,
+     *   });
+     *   for (const event of page.items) console.log(event.id, event.status);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    listWebhookEvents(query: WebhookEventListApiQuery): Promise<WebhookEventListResponse>;
+    /**
+     * Resend a previously dispatched webhook event.
+     *
+     * @example
+     * ```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 resent = await client.resendWebhookEvent(
+     *     '01HK8MAR2QEXAMPLE000000000',
+     *   );
+     *   console.log(resent.event_id);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    resendWebhookEvent(eventId: string): Promise<WebhookEventResendResponse>;
+    /**
+     * Returns an indicative rate for pre-invoice pricing. The binding rate is
+     * captured by `createInvoice` in `rate_snapshot`; any delta between this
+     * quote and the invoice is the partner's responsibility per FR33c.
+     *
+     * @example
+     * ```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 rates = await client.getRates({ coins: 'btc,eth' });
+     *   console.log(rates.rates.btc);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    getRates(query: RatesQuery): Promise<RatesResponse>;
+    /**
+     * Returns an indicative rate for pre-invoice pricing. The binding rate is
+     * captured by `createInvoice` in `rate_snapshot`; any delta between this
+     * quote and the invoice is the partner's responsibility per FR33c.
+     *
+     * @example
+     * ```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 quote = await client.quoteAmount({
+     *     amount_usd: 10.0,
+     *     coins: 'btc',
+     *   });
+     *   console.log(quote.quotes.btc);
+     * } catch (err) {
+     *   if (err instanceof TxnodError) console.error(err.error_code);
+     *   throw err;
+     * }
+     * ```
+     */
+    quoteAmount(query: QuoteQuery): Promise<QuoteResponse>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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