@txnod/sdk 1.0.1

package/dist/client.js

@@ -0,0 +1,588 @@
+import { signedFetch, } from './internals/fetch-with-retry.js';
+import { parseProblemDetails } from './internals/parse-problem-details.js';
+import { parseXpubConfig, parseTonConfig } from './verify/config.js';
+import { verifyAddress } from './verify/index.js';
+import { assertNoTestnetXpubsInProduction } from './verify/xpub-safety.js';
+import { TxnodEnvironmentUnknownError, TxnodExternalIdConflictError, TxnodSandboxKeyInProductionError, } from './errors.js';
+import { getSdkEnv } from './env.js';
+import { TxnodClientSandbox } from './client-sandbox.js';
+const DEFAULT_BASE_URL = 'https://txnod.com';
+function stripTrailingSlash(url) {
+    return url.endsWith('/') ? url.slice(0, -1) : url;
+}
+function toQueryParams(q) {
+    const out = {};
+    for (const [k, v] of Object.entries(q)) {
+        if (v === undefined)
+            continue;
+        out[k] = typeof v === 'boolean' ? String(v) : v;
+    }
+    return out;
+}
+const SANDBOX_API_SECRET_PREFIX = 'sk_sandbox_';
+/**
+ * Implements spec §7.2 behavior matrix. Called from `TxnodClient.constructor`
+ * BEFORE any field assignment so a misconfiguration fails boot loudly.
+ *
+ * Per-constructor-invocation diagnostics: every call to `new TxnodClient(...)`
+ * with a sandbox secret emits exactly one `console.warn` (non-production env)
+ * or one `console.error` (production-detected with override) — module-level
+ * dedup is deliberately avoided so multiple clients in the same process all
+ * surface their config moment.
+ */
+function assertEnvironmentSafety(apiSecret, projectId, options) {
+    const isSandboxSecret = apiSecret.startsWith(SANDBOX_API_SECRET_PREFIX);
+    if (!isSandboxSecret) {
+        return { prodOverrideActive: false };
+    }
+    const env = getSdkEnv(options.environment);
+    if (env === 'production') {
+        if (options.iAcknowledgeRoutingRealCustomerFundsToSandboxAddresses === true) {
+            // Non-suppressible diagnostic per spec §7.2. The byte-exact string is
+            // load-bearing — partner runbooks may grep for it.
+            console.error(`[txnod-sdk] CRITICAL: Sandbox API secret active in production-detected environment for project_id=${projectId}. Real on-chain payments will NOT be observed. iAcknowledgeRoutingRealCustomerFundsToSandboxAddresses=true is set; X-Txnod-Client-Environment: production will be sent on every request.`);
+            return { prodOverrideActive: true };
+        }
+        const signal = options.environment !== undefined
+            ? 'environment_option'
+            : process.env['TXNOD_ENVIRONMENT'] === 'production'
+                ? 'TXNOD_ENVIRONMENT'
+                : 'NODE_ENV';
+        throw new TxnodSandboxKeyInProductionError(signal);
+    }
+    if (env === 'unknown') {
+        throw new TxnodEnvironmentUnknownError();
+    }
+    // env === 'non-production' — emit one warn per construction.
+    console.warn('[txnod-sdk] Sandbox API secret detected. Real on-chain payments will not be observed.');
+    return { prodOverrideActive: false };
+}
+const REQUEST_ID_HEADER = 'X-Txnod-Request-Id';
+/**
+ * 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 class TxnodClient {
+    #projectId;
+    #apiSecret;
+    #baseUrl;
+    #requestTimeoutMs;
+    #maxResponseBytes;
+    #requestLogger;
+    #prodOverrideActive;
+    #environmentOption;
+    #xpubConfig;
+    #tonConfig;
+    #sandboxNamespace;
+    #requestBound;
+    /**
+     * 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;
+    constructor(options) {
+        const safety = assertEnvironmentSafety(options.apiSecret, options.projectId, options);
+        this.#projectId = options.projectId;
+        this.#apiSecret = options.apiSecret;
+        this.#baseUrl = stripTrailingSlash(options.baseUrl ?? DEFAULT_BASE_URL);
+        this.#requestTimeoutMs = options.requestTimeoutMs;
+        this.#maxResponseBytes = options.maxResponseBytes;
+        this.#requestLogger = options.requestLogger;
+        this.#prodOverrideActive = safety.prodOverrideActive;
+        this.#environmentOption = options.environment;
+        this.#xpubConfig = parseXpubConfig();
+        this.#tonConfig = parseTonConfig();
+        assertNoTestnetXpubsInProduction(this.#xpubConfig, getSdkEnv(this.#environmentOption));
+    }
+    /**
+     * 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() {
+        if (this.#sandboxNamespace === undefined) {
+            if (this.#requestBound === undefined) {
+                this.#requestBound = (input) => this.#request(input);
+            }
+            this.#sandboxNamespace = new TxnodClientSandbox(this.#requestBound);
+        }
+        return this.#sandboxNamespace;
+    }
+    /**
+     * 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() {
+        this.#xpubConfig = parseXpubConfig();
+        this.#tonConfig = parseTonConfig();
+        assertNoTestnetXpubsInProduction(this.#xpubConfig, getSdkEnv(this.#environmentOption));
+    }
+    async #request(input) {
+        const fetchInput = {
+            baseUrl: this.#baseUrl,
+            projectId: this.#projectId,
+            apiSecret: this.#apiSecret,
+            method: input.method,
+            path: input.path,
+        };
+        if (input.query !== undefined)
+            fetchInput.query = input.query;
+        if (input.body !== undefined)
+            fetchInput.body = input.body;
+        if (this.#requestTimeoutMs !== undefined)
+            fetchInput.requestTimeoutMs = this.#requestTimeoutMs;
+        if (this.#maxResponseBytes !== undefined)
+            fetchInput.maxResponseBytes = this.#maxResponseBytes;
+        if (this.#requestLogger !== undefined)
+            fetchInput.requestLogger = this.#requestLogger;
+        if (this.#prodOverrideActive) {
+            fetchInput.extraHeaders = { 'X-Txnod-Client-Environment': 'production' };
+        }
+        this.lastRequestId = undefined;
+        const response = await signedFetch(fetchInput);
+        const headerRequestId = response.headers.get(REQUEST_ID_HEADER);
+        this.lastRequestId =
+            headerRequestId !== null && headerRequestId.length > 0
+                ? headerRequestId
+                : undefined;
+        if (response.status >= 200 && response.status < 300) {
+            return (await response.json());
+        }
+        throw await parseProblemDetails(response);
+    }
+    /**
+     * 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;
+     * }
+     * ```
+     */
+    async createInvoice(body) {
+        const invoice = await this.#request({
+            method: 'POST',
+            path: '/api/v1/invoices',
+            body,
+        });
+        const verifyInput = {
+            invoice,
+            config: this.#xpubConfig,
+        };
+        if (this.#tonConfig !== undefined)
+            verifyInput.tonConfig = this.#tonConfig;
+        verifyAddress(verifyInput);
+        return invoice;
+    }
+    /**
+     * 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,
+     * });
+     * ```
+     */
+    async createOrGetInvoice(body) {
+        try {
+            return await this.createInvoice(body);
+        }
+        catch (err) {
+            if (!(err instanceof TxnodExternalIdConflictError))
+                throw err;
+            const page = await this.searchInvoices({
+                external_id: body.external_id,
+                limit: 1,
+            });
+            const existing = page.items[0];
+            if (existing === undefined) {
+                // Conflict raised but the row is not findable via search — surface the
+                // original error rather than silently masking it.
+                throw err;
+            }
+            return existing;
+        }
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'GET',
+            path: `/api/v1/invoices/${id}`,
+        });
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'GET',
+            path: '/api/v1/invoices',
+            query: toQueryParams(query),
+        });
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/invoices/${id}/cancel`,
+        });
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'GET',
+            path: '/api/v1/orphan-payments',
+            query: toQueryParams(query),
+        });
+    }
+    /**
+     * 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, body) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/orphan-payments/${txHash}/attribute`,
+            body,
+        });
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'GET',
+            path: '/api/v1/webhooks/events',
+            query: toQueryParams(query),
+        });
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'POST',
+            path: `/api/v1/webhooks/events/${eventId}/resend`,
+        });
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'GET',
+            path: '/api/v1/rates',
+            query: toQueryParams(query),
+        });
+    }
+    /**
+     * 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) {
+        return this.#request({
+            method: 'GET',
+            path: '/api/v1/quote',
+            query: toQueryParams(query),
+        });
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/env.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Single, concentrated reader for environment-detection signals consumed by
+ * `TxnodClient`'s sandbox-safety guards. Resolution order (per spec §7.2 + F-2):
+ *
+ * 1. `explicit` argument — the constructor's `environment` option wins
+ *    everything when set. Use it for staging replicas where `NODE_ENV` is
+ *    conventionally `'production'` but the secret is sandbox.
+ * 2. `process.env.TXNOD_ENVIRONMENT === 'production'` → `'production'`.
+ * 3. `process.env.TXNOD_ENVIRONMENT === 'non-production'` → `'non-production'`.
+ * 4. `process.env.NODE_ENV === 'production'` → `'production'`.
+ * 5. `process.env.NODE_ENV === 'development' | 'test'` → `'non-production'`.
+ * 6. Otherwise → `'unknown'`.
+ *
+ * **String comparisons are case-sensitive** to match Node.js convention
+ * (`NODE_ENV=Production` is treated as unrecognised by Express, Next.js, and
+ * Node's own runtime checks). A misconfigured `'Production'` therefore
+ * resolves to `'unknown'` and — paired with a sandbox secret — surfaces as
+ * `TxnodEnvironmentUnknownError` at construction, prompting the operator to
+ * fix the casing.
+ *
+ * The optional `env` parameter exists for testability — production callers
+ * always omit it. Mirrors the same shape as `parseXpubConfig`.
+ *
+ * **This is the only `process.env` reader in `packages/sdk/src/` for environment
+ * signals.** Do not introduce a second; it would split the resolution rules
+ * across files and bypass the sandbox-safety matrix in `TxnodClient`.
+ */
+export declare function getSdkEnv(explicit?: 'production' | 'non-production', env?: NodeJS.ProcessEnv): 'production' | 'non-production' | 'unknown';
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CACvB,QAAQ,CAAC,EAAE,YAAY,GAAG,gBAAgB,EAC1C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,YAAY,GAAG,gBAAgB,GAAG,SAAS,CAW7C"}

package/dist/env.js

@@ -0,0 +1,44 @@
+/**
+ * Single, concentrated reader for environment-detection signals consumed by
+ * `TxnodClient`'s sandbox-safety guards. Resolution order (per spec §7.2 + F-2):
+ *
+ * 1. `explicit` argument — the constructor's `environment` option wins
+ *    everything when set. Use it for staging replicas where `NODE_ENV` is
+ *    conventionally `'production'` but the secret is sandbox.
+ * 2. `process.env.TXNOD_ENVIRONMENT === 'production'` → `'production'`.
+ * 3. `process.env.TXNOD_ENVIRONMENT === 'non-production'` → `'non-production'`.
+ * 4. `process.env.NODE_ENV === 'production'` → `'production'`.
+ * 5. `process.env.NODE_ENV === 'development' | 'test'` → `'non-production'`.
+ * 6. Otherwise → `'unknown'`.
+ *
+ * **String comparisons are case-sensitive** to match Node.js convention
+ * (`NODE_ENV=Production` is treated as unrecognised by Express, Next.js, and
+ * Node's own runtime checks). A misconfigured `'Production'` therefore
+ * resolves to `'unknown'` and — paired with a sandbox secret — surfaces as
+ * `TxnodEnvironmentUnknownError` at construction, prompting the operator to
+ * fix the casing.
+ *
+ * The optional `env` parameter exists for testability — production callers
+ * always omit it. Mirrors the same shape as `parseXpubConfig`.
+ *
+ * **This is the only `process.env` reader in `packages/sdk/src/` for environment
+ * signals.** Do not introduce a second; it would split the resolution rules
+ * across files and bypass the sandbox-safety matrix in `TxnodClient`.
+ */
+export function getSdkEnv(explicit, env = process.env) {
+    if (explicit === 'production' || explicit === 'non-production') {
+        return explicit;
+    }
+    const txnodEnv = env['TXNOD_ENVIRONMENT'];
+    if (txnodEnv === 'production')
+        return 'production';
+    if (txnodEnv === 'non-production')
+        return 'non-production';
+    const nodeEnv = env['NODE_ENV'];
+    if (nodeEnv === 'production')
+        return 'production';
+    if (nodeEnv === 'development' || nodeEnv === 'test')
+        return 'non-production';
+    return 'unknown';
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,SAAS,CACvB,QAA0C,EAC1C,MAAyB,OAAO,CAAC,GAAG;IAEpC,IAAI,QAAQ,KAAK,YAAY,IAAI,QAAQ,KAAK,gBAAgB,EAAE,CAAC;QAC/D,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,MAAM,QAAQ,GAAG,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC1C,IAAI,QAAQ,KAAK,YAAY;QAAE,OAAO,YAAY,CAAC;IACnD,IAAI,QAAQ,KAAK,gBAAgB;QAAE,OAAO,gBAAgB,CAAC;IAC3D,MAAM,OAAO,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC;IAChC,IAAI,OAAO,KAAK,YAAY;QAAE,OAAO,YAAY,CAAC;IAClD,IAAI,OAAO,KAAK,aAAa,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,gBAAgB,CAAC;IAC7E,OAAO,SAAS,CAAC;AACnB,CAAC"}