@autlantic/payments 0.1.0

package/dist/client.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutlanticPayments = void 0;
+const chain_tron_1 = require("@autlantic/chain-tron");
+const payments_core_1 = require("@autlantic/payments-core");
+const from_env_1 = require("./from-env");
+const test_scenarios_1 = require("./test-scenarios");
+const webhook_1 = require("./webhook");
+class AutlanticPayments {
+    config;
+    constructor(config = {}) {
+        this.config = config;
+        (0, chain_tron_1.configureTronGrid)({
+            apiKey: config.tronGridApiKey,
+            maxRetries: config.tronGridMaxRetries,
+        });
+    }
+    /** Construct from environment variables (see `configFromEnv`). */
+    static fromEnv(env = process.env) {
+        return new AutlanticPayments((0, from_env_1.configFromEnv)(env));
+    }
+    /** Create a payment intent (store on your order / checkout row). */
+    createIntent(input) {
+        (0, payments_core_1.assertValidCreatePaymentIntentInput)(input);
+        return (0, payments_core_1.createPaymentIntent)(input);
+    }
+    /**
+     * Verify a user-submitted transaction hash against an intent.
+     */
+    async verifyByTxHash(intent, txHash) {
+        const trimmed = txHash.trim();
+        if (!trimmed) {
+            return {
+                ok: false,
+                code: "INVALID_TX_HASH",
+                message: "Transaction hash is required",
+                intent,
+            };
+        }
+        if (!(0, payments_core_1.isValidTronTxHash)(trimmed) && !this.config.sandbox) {
+            return {
+                ok: false,
+                code: "INVALID_TX_HASH",
+                message: "Transaction hash must be 64 hexadecimal characters",
+                intent,
+            };
+        }
+        if (this.config.sandbox) {
+            if (!(0, test_scenarios_1.isSandboxTxHash)(trimmed)) {
+                return {
+                    ok: false,
+                    code: "SANDBOX_ONLY",
+                    message: 'Sandbox mode: use a tx hash starting with "sandbox_"',
+                    intent,
+                };
+            }
+            return (0, test_scenarios_1.verifySandboxPayment)(intent, trimmed);
+        }
+        const transfer = await (0, chain_tron_1.fetchUsdtTransferByTxHash)(trimmed);
+        if (!transfer) {
+            return {
+                ok: false,
+                code: "PAYMENT_TX_NOT_FOUND",
+                message: "Could not find a USDT (TRC-20) transfer for this transaction hash",
+                intent,
+            };
+        }
+        return (0, payments_core_1.verifyTransferAgainstIntent)((0, payments_core_1.withIntentStatus)(intent, "confirming"), transfer);
+    }
+    /**
+     * Poll the chain for an incoming transfer matching the intent (exact or minimum amount).
+     */
+    async findMatchingPayment(intent) {
+        if (this.config.sandbox) {
+            const transfer = (0, test_scenarios_1.sandboxTransferForIntent)(intent, (0, test_scenarios_1.getSandboxScenario)("payment.confirmed").testTxHash, "payment.confirmed");
+            const verified = (0, payments_core_1.verifyTransferAgainstIntent)(intent, transfer);
+            if (!verified.ok)
+                return null;
+            return { intent: (0, payments_core_1.withIntentStatus)(intent, "confirmed"), transfer };
+        }
+        const transfer = await (0, chain_tron_1.findIncomingUsdtPayment)(intent, {
+            limit: this.config.incomingPollLimit,
+        });
+        if (!transfer)
+            return null;
+        const verified = (0, payments_core_1.verifyTransferAgainstIntent)(intent, transfer);
+        if (!verified.ok)
+            return null;
+        return {
+            intent: (0, payments_core_1.withIntentStatus)(intent, "confirmed"),
+            transfer,
+        };
+    }
+    /**
+     * Verify and return a confirmed event suitable for webhooks / internal handlers.
+     */
+    async confirmByTxHash(intent, txHash) {
+        const result = await this.verifyByTxHash(intent, txHash);
+        if (!result.ok)
+            return { ok: false, result };
+        const confirmedIntent = (0, payments_core_1.withIntentStatus)(result.intent, "confirmed");
+        return {
+            ok: true,
+            event: (0, payments_core_1.toConfirmedEvent)(confirmedIntent, result.transfer),
+            transfer: result.transfer,
+        };
+    }
+    /** Sign a webhook body (send as `x-autlantic-signature` header). */
+    signWebhook(event) {
+        const secret = this.config.webhookSecret;
+        if (!secret)
+            return null;
+        const body = (0, webhook_1.serializeConfirmedEvent)(event);
+        return { body, signature: (0, webhook_1.signWebhookPayload)(secret, body) };
+    }
+    /** Verify an inbound webhook from Autlantic (or your own signed events). */
+    verifyWebhook(rawBody, signatureHeader) {
+        const secret = this.config.webhookSecret;
+        if (!secret)
+            return false;
+        return (0, webhook_1.verifyWebhookSignature)(secret, rawBody, signatureHeader);
+    }
+    /** Verify signature and parse `payment.confirmed` payload. */
+    parseWebhook(rawBody, signatureHeader) {
+        const secret = this.config.webhookSecret;
+        if (!secret)
+            return null;
+        return (0, webhook_1.parseAndVerifyWebhook)(secret, rawBody, signatureHeader);
+    }
+    /**
+     * Stripe-style test harness: run a catalog scenario in sandbox (no TronGrid).
+     * Requires `sandbox: true` on the client.
+     */
+    emitTestEvent(input) {
+        this.assertSandboxMode("emitTestEvent");
+        return (0, test_scenarios_1.emitSandboxTestEvent)(input, this.config.webhookSecret);
+    }
+    /** List built-in sandbox scenarios (success + failure paths). */
+    listTestScenarios() {
+        return (0, test_scenarios_1.listSandboxScenarios)();
+    }
+    /**
+     * Trigger a scenario by id — same as `emitTestEvent` (CLI-friendly alias).
+     */
+    triggerTestEvent(input) {
+        return this.emitTestEvent(input);
+    }
+    assertSandboxMode(method) {
+        if (!this.config.sandbox) {
+            throw new Error(`${method} requires sandbox mode. Use new AutlanticPayments({ sandbox: true }) or AUTLANTIC_PAYMENTS_SANDBOX=true.`);
+        }
+    }
+}
+exports.AutlanticPayments = AutlanticPayments;

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+export type AutlanticPaymentsConfig = {
+    /** TronGrid API key (or set TRONGRID_API_KEY env). */
+    tronGridApiKey?: string;
+    /** Simulate confirmations without hitting the chain. */
+    sandbox?: boolean;
+    /** Secret for signing outbound webhooks to your app. */
+    webhookSecret?: string;
+    /** Max TRC-20 rows to scan when polling incoming payments (default 50). */
+    incomingPollLimit?: number;
+    /** TronGrid retries on 429/5xx (default 2). */
+    tronGridMaxRetries?: number;
+};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,uBAAuB,GAAG;IACpC,sDAAsD;IACtD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B,CAAC"}

package/dist/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/constants.d.ts

@@ -0,0 +1,5 @@
+/** Current SDK release (semver). */
+export declare const AUTLANTIC_PAYMENTS_SDK_VERSION = "0.1.0";
+/** HTTP header for outbound / inbound webhook signatures. */
+export declare const WEBHOOK_SIGNATURE_HEADER = "x-autlantic-signature";
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,eAAO,MAAM,8BAA8B,UAAU,CAAC;AAEtD,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,0BAA0B,CAAC"}

package/dist/constants.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WEBHOOK_SIGNATURE_HEADER = exports.AUTLANTIC_PAYMENTS_SDK_VERSION = void 0;
+/** Current SDK release (semver). */
+exports.AUTLANTIC_PAYMENTS_SDK_VERSION = "0.1.0";
+/** HTTP header for outbound / inbound webhook signatures. */
+exports.WEBHOOK_SIGNATURE_HEADER = "x-autlantic-signature";

package/dist/from-env.d.ts

@@ -0,0 +1,4 @@
+import type { AutlanticPaymentsConfig } from "./config";
+/** Build client config from `process.env` (or a custom env object). */
+export declare function configFromEnv(env?: Record<string, string | undefined>): AutlanticPaymentsConfig;
+//# sourceMappingURL=from-env.d.ts.map

package/dist/from-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"from-env.d.ts","sourceRoot":"","sources":["../src/from-env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAQxD,uEAAuE;AACvE,wBAAgB,aAAa,CAC3B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,uBAAuB,CAgBzB"}

package/dist/from-env.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configFromEnv = configFromEnv;
+function envFlag(value) {
+    if (!value)
+        return false;
+    const v = value.trim().toLowerCase();
+    return v === "1" || v === "true" || v === "yes";
+}
+/** Build client config from `process.env` (or a custom env object). */
+function configFromEnv(env = process.env) {
+    return {
+        tronGridApiKey: env.TRONGRID_API_KEY?.trim() || undefined,
+        sandbox: envFlag(env.AUTLANTIC_PAYMENTS_SANDBOX) || envFlag(env.AUTLANTIC_PAYMENTS_TEST_MODE),
+        webhookSecret: env.AUTLANTIC_PAYMENTS_WEBHOOK_SECRET?.trim() ||
+            env.AUTLANTIC_WEBHOOK_SECRET?.trim() ||
+            undefined,
+        incomingPollLimit: env.AUTLANTIC_PAYMENTS_POLL_LIMIT
+            ? Number(env.AUTLANTIC_PAYMENTS_POLL_LIMIT)
+            : undefined,
+        tronGridMaxRetries: env.AUTLANTIC_TRONGRID_MAX_RETRIES
+            ? Number(env.AUTLANTIC_TRONGRID_MAX_RETRIES)
+            : undefined,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { AutlanticPayments } from "./client";
+export type { AutlanticPaymentsConfig } from "./config";
+export { configFromEnv } from "./from-env";
+export { AUTLANTIC_PAYMENTS_SDK_VERSION, WEBHOOK_SIGNATURE_HEADER, } from "./constants";
+export { signWebhookPayload, verifyWebhookSignature, serializeConfirmedEvent, parseConfirmedWebhookEvent, parseAndVerifyWebhook, } from "./webhook";
+export { SANDBOX_TX_PREFIX, SANDBOX_SCENARIOS, emitSandboxTestEvent, getSandboxScenario, isSandboxTxHash, listSandboxScenarios, resolveSandboxScenario, sandboxTransferForIntent, verifySandboxPayment, type EmitTestEventInput, type EmitTestEventResult, type SandboxScenario, type SandboxScenarioId, } from "./test-scenarios";
+export * from "@autlantic/payments-core";
+export { configureTronGrid, fetchUsdtTransferByTxHash, findIncomingUsdtPayment, findExactUsdtIncomingPayment, findMatchingIncomingRow, USDT_TRC20_CONTRACT, type FindIncomingOptions, type Trc20IncomingRow, } from "@autlantic/chain-tron";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,EACL,8BAA8B,EAC9B,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,qBAAqB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAE1B,cAAc,0BAA0B,CAAC;AACzC,OAAO,EACL,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,EACvB,4BAA4B,EAC5B,uBAAuB,EACvB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,48 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USDT_TRC20_CONTRACT = exports.findMatchingIncomingRow = exports.findExactUsdtIncomingPayment = exports.findIncomingUsdtPayment = exports.fetchUsdtTransferByTxHash = exports.configureTronGrid = exports.verifySandboxPayment = exports.sandboxTransferForIntent = exports.resolveSandboxScenario = exports.listSandboxScenarios = exports.isSandboxTxHash = exports.getSandboxScenario = exports.emitSandboxTestEvent = exports.SANDBOX_SCENARIOS = exports.SANDBOX_TX_PREFIX = exports.parseAndVerifyWebhook = exports.parseConfirmedWebhookEvent = exports.serializeConfirmedEvent = exports.verifyWebhookSignature = exports.signWebhookPayload = exports.WEBHOOK_SIGNATURE_HEADER = exports.AUTLANTIC_PAYMENTS_SDK_VERSION = exports.configFromEnv = exports.AutlanticPayments = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "AutlanticPayments", { enumerable: true, get: function () { return client_1.AutlanticPayments; } });
+var from_env_1 = require("./from-env");
+Object.defineProperty(exports, "configFromEnv", { enumerable: true, get: function () { return from_env_1.configFromEnv; } });
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "AUTLANTIC_PAYMENTS_SDK_VERSION", { enumerable: true, get: function () { return constants_1.AUTLANTIC_PAYMENTS_SDK_VERSION; } });
+Object.defineProperty(exports, "WEBHOOK_SIGNATURE_HEADER", { enumerable: true, get: function () { return constants_1.WEBHOOK_SIGNATURE_HEADER; } });
+var webhook_1 = require("./webhook");
+Object.defineProperty(exports, "signWebhookPayload", { enumerable: true, get: function () { return webhook_1.signWebhookPayload; } });
+Object.defineProperty(exports, "verifyWebhookSignature", { enumerable: true, get: function () { return webhook_1.verifyWebhookSignature; } });
+Object.defineProperty(exports, "serializeConfirmedEvent", { enumerable: true, get: function () { return webhook_1.serializeConfirmedEvent; } });
+Object.defineProperty(exports, "parseConfirmedWebhookEvent", { enumerable: true, get: function () { return webhook_1.parseConfirmedWebhookEvent; } });
+Object.defineProperty(exports, "parseAndVerifyWebhook", { enumerable: true, get: function () { return webhook_1.parseAndVerifyWebhook; } });
+var test_scenarios_1 = require("./test-scenarios");
+Object.defineProperty(exports, "SANDBOX_TX_PREFIX", { enumerable: true, get: function () { return test_scenarios_1.SANDBOX_TX_PREFIX; } });
+Object.defineProperty(exports, "SANDBOX_SCENARIOS", { enumerable: true, get: function () { return test_scenarios_1.SANDBOX_SCENARIOS; } });
+Object.defineProperty(exports, "emitSandboxTestEvent", { enumerable: true, get: function () { return test_scenarios_1.emitSandboxTestEvent; } });
+Object.defineProperty(exports, "getSandboxScenario", { enumerable: true, get: function () { return test_scenarios_1.getSandboxScenario; } });
+Object.defineProperty(exports, "isSandboxTxHash", { enumerable: true, get: function () { return test_scenarios_1.isSandboxTxHash; } });
+Object.defineProperty(exports, "listSandboxScenarios", { enumerable: true, get: function () { return test_scenarios_1.listSandboxScenarios; } });
+Object.defineProperty(exports, "resolveSandboxScenario", { enumerable: true, get: function () { return test_scenarios_1.resolveSandboxScenario; } });
+Object.defineProperty(exports, "sandboxTransferForIntent", { enumerable: true, get: function () { return test_scenarios_1.sandboxTransferForIntent; } });
+Object.defineProperty(exports, "verifySandboxPayment", { enumerable: true, get: function () { return test_scenarios_1.verifySandboxPayment; } });
+__exportStar(require("@autlantic/payments-core"), exports);
+var chain_tron_1 = require("@autlantic/chain-tron");
+Object.defineProperty(exports, "configureTronGrid", { enumerable: true, get: function () { return chain_tron_1.configureTronGrid; } });
+Object.defineProperty(exports, "fetchUsdtTransferByTxHash", { enumerable: true, get: function () { return chain_tron_1.fetchUsdtTransferByTxHash; } });
+Object.defineProperty(exports, "findIncomingUsdtPayment", { enumerable: true, get: function () { return chain_tron_1.findIncomingUsdtPayment; } });
+Object.defineProperty(exports, "findExactUsdtIncomingPayment", { enumerable: true, get: function () { return chain_tron_1.findExactUsdtIncomingPayment; } });
+Object.defineProperty(exports, "findMatchingIncomingRow", { enumerable: true, get: function () { return chain_tron_1.findMatchingIncomingRow; } });
+Object.defineProperty(exports, "USDT_TRC20_CONTRACT", { enumerable: true, get: function () { return chain_tron_1.USDT_TRC20_CONTRACT; } });

package/dist/sandbox.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @deprecated Import from `./test-scenarios` — re-exported for compatibility.
+ */
+export { SANDBOX_TX_PREFIX, SANDBOX_SCENARIOS, emitSandboxTestEvent, getSandboxScenario, isSandboxTxHash, listSandboxScenarios, resolveSandboxScenario, sandboxTransferForIntent, verifySandboxPayment, type EmitTestEventInput, type EmitTestEventResult, type SandboxScenario, type SandboxScenarioId, } from "./test-scenarios";
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,wBAAwB,EACxB,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC"}

package/dist/sandbox.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifySandboxPayment = exports.sandboxTransferForIntent = exports.resolveSandboxScenario = exports.listSandboxScenarios = exports.isSandboxTxHash = exports.getSandboxScenario = exports.emitSandboxTestEvent = exports.SANDBOX_SCENARIOS = exports.SANDBOX_TX_PREFIX = void 0;
+/**
+ * @deprecated Import from `./test-scenarios` — re-exported for compatibility.
+ */
+var test_scenarios_1 = require("./test-scenarios");
+Object.defineProperty(exports, "SANDBOX_TX_PREFIX", { enumerable: true, get: function () { return test_scenarios_1.SANDBOX_TX_PREFIX; } });
+Object.defineProperty(exports, "SANDBOX_SCENARIOS", { enumerable: true, get: function () { return test_scenarios_1.SANDBOX_SCENARIOS; } });
+Object.defineProperty(exports, "emitSandboxTestEvent", { enumerable: true, get: function () { return test_scenarios_1.emitSandboxTestEvent; } });
+Object.defineProperty(exports, "getSandboxScenario", { enumerable: true, get: function () { return test_scenarios_1.getSandboxScenario; } });
+Object.defineProperty(exports, "isSandboxTxHash", { enumerable: true, get: function () { return test_scenarios_1.isSandboxTxHash; } });
+Object.defineProperty(exports, "listSandboxScenarios", { enumerable: true, get: function () { return test_scenarios_1.listSandboxScenarios; } });
+Object.defineProperty(exports, "resolveSandboxScenario", { enumerable: true, get: function () { return test_scenarios_1.resolveSandboxScenario; } });
+Object.defineProperty(exports, "sandboxTransferForIntent", { enumerable: true, get: function () { return test_scenarios_1.sandboxTransferForIntent; } });
+Object.defineProperty(exports, "verifySandboxPayment", { enumerable: true, get: function () { return test_scenarios_1.verifySandboxPayment; } });

package/dist/test-scenarios.d.ts

@@ -0,0 +1,48 @@
+import { type CreatePaymentIntentInput, type OnChainTransfer, type PaymentConfirmedEvent, type PaymentFailureCode, type PaymentIntent, type PaymentVerificationResult } from "@autlantic/payments-core";
+import { WEBHOOK_SIGNATURE_HEADER } from "./constants";
+export declare const SANDBOX_TX_PREFIX = "sandbox_";
+/** Stripe-style test scenario ids. */
+export type SandboxScenarioId = "payment.confirmed" | "payment.failed.short" | "payment.failed.expired" | "payment.failed.wrong_address" | "payment.failed.too_early" | "payment.failed.tx_not_found" | "payment.failed.invalid_hash";
+export type SandboxScenario = {
+    id: SandboxScenarioId;
+    /** Human label for docs / CLI */
+    label: string;
+    description: string;
+    /** Use this as `txHash` in sandbox `verifyByTxHash` */
+    testTxHash: string;
+    /** Webhook `event.type` when applicable */
+    eventType: string;
+    expectsSuccess: boolean;
+    expectedCode?: PaymentFailureCode;
+};
+/** Catalog of sandbox test cases (like Stripe test cards). */
+export declare const SANDBOX_SCENARIOS: SandboxScenario[];
+export declare function isSandboxTxHash(txHash: string): boolean;
+export declare function getSandboxScenario(id: SandboxScenarioId): SandboxScenario;
+export declare function listSandboxScenarios(): SandboxScenario[];
+export declare function resolveSandboxScenario(txHash: string): SandboxScenarioId | null;
+/** Unique per checkout (merchantRef) so sandbox test txs do not collide in @unique txHash columns. */
+export declare function sandboxStoredTxHash(intent: PaymentIntent, inputTxHash: string): string;
+export declare function sandboxTransferForIntent(intent: PaymentIntent, txHash: string, scenarioId?: SandboxScenarioId): OnChainTransfer;
+export declare function verifySandboxPayment(intent: PaymentIntent, txHash: string): PaymentVerificationResult;
+export type EmitTestEventInput = {
+    scenario: SandboxScenarioId;
+    merchantRef: string;
+    amountUsdt: number;
+    payToAddress: string;
+    expiresAt?: Date;
+    matchStrategy?: CreatePaymentIntentInput["matchStrategy"];
+};
+export type EmitTestEventResult = {
+    scenario: SandboxScenario;
+    intent: PaymentIntent;
+    verification: PaymentVerificationResult;
+    event?: PaymentConfirmedEvent;
+    webhook?: {
+        body: string;
+        signature: string;
+        headerName: typeof WEBHOOK_SIGNATURE_HEADER;
+    };
+};
+export declare function emitSandboxTestEvent(input: EmitTestEventInput, webhookSecret?: string): EmitTestEventResult;
+//# sourceMappingURL=test-scenarios.d.ts.map

package/dist/test-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-scenarios.d.ts","sourceRoot":"","sources":["../src/test-scenarios.ts"],"names":[],"mappings":"AACA,OAAO,EAOL,KAAK,wBAAwB,EAC7B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,yBAAyB,EAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGvD,eAAO,MAAM,iBAAiB,aAAa,CAAC;AAE5C,sCAAsC;AACtC,MAAM,MAAM,iBAAiB,GACzB,mBAAmB,GACnB,sBAAsB,GACtB,wBAAwB,GACxB,8BAA8B,GAC9B,0BAA0B,GAC1B,6BAA6B,GAC7B,6BAA6B,CAAC;AAElC,MAAM,MAAM,eAAe,GAAG;IAC5B,EAAE,EAAE,iBAAiB,CAAC;IACtB,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,kBAAkB,CAAC;CACnC,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,EAAE,eAAe,EA+D9C,CAAC;AA2BF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,iBAAiB,GAAG,eAAe,CAIzE;AAED,wBAAgB,oBAAoB,IAAI,eAAe,EAAE,CAExD;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAS/E;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAItF;AAID,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,EACd,UAAU,GAAE,iBAAuC,GAClD,eAAe,CA2CjB;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,yBAAyB,CAwC3B;AAED,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,IAAI,CAAC;IACjB,aAAa,CAAC,EAAE,wBAAwB,CAAC,eAAe,CAAC,CAAC;CAC3D,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,eAAe,CAAC;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB,YAAY,EAAE,yBAAyB,CAAC;IACxC,KAAK,CAAC,EAAE,qBAAqB,CAAC;IAC9B,OAAO,CAAC,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,OAAO,wBAAwB,CAAC;KAC7C,CAAC;CACH,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,kBAAkB,EACzB,aAAa,CAAC,EAAE,MAAM,GACrB,mBAAmB,CA6BrB"}

package/dist/test-scenarios.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SANDBOX_SCENARIOS = exports.SANDBOX_TX_PREFIX = void 0;
+exports.isSandboxTxHash = isSandboxTxHash;
+exports.getSandboxScenario = getSandboxScenario;
+exports.listSandboxScenarios = listSandboxScenarios;
+exports.resolveSandboxScenario = resolveSandboxScenario;
+exports.sandboxStoredTxHash = sandboxStoredTxHash;
+exports.sandboxTransferForIntent = sandboxTransferForIntent;
+exports.verifySandboxPayment = verifySandboxPayment;
+exports.emitSandboxTestEvent = emitSandboxTestEvent;
+const node_crypto_1 = require("node:crypto");
+const payments_core_1 = require("@autlantic/payments-core");
+const constants_1 = require("./constants");
+const webhook_1 = require("./webhook");
+exports.SANDBOX_TX_PREFIX = "sandbox_";
+/** Catalog of sandbox test cases (like Stripe test cards). */
+exports.SANDBOX_SCENARIOS = [
+    {
+        id: "payment.confirmed",
+        label: "Successful USDT payment",
+        description: "Payment meets amount and address; emits payment.confirmed.",
+        testTxHash: "sandbox_payment_confirmed",
+        eventType: "payment.confirmed",
+        expectsSuccess: true,
+    },
+    {
+        id: "payment.failed.short",
+        label: "Underpayment",
+        description: "On-chain amount below checkout requirement.",
+        testTxHash: "sandbox_payment_short",
+        eventType: "payment.failed",
+        expectsSuccess: false,
+        expectedCode: "PAYMENT_SHORT",
+    },
+    {
+        id: "payment.failed.expired",
+        label: "Expired checkout",
+        description: "Checkout session past expiresAt.",
+        testTxHash: "sandbox_payment_expired",
+        eventType: "payment.failed",
+        expectsSuccess: false,
+        expectedCode: "PAYMENT_EXPIRED",
+    },
+    {
+        id: "payment.failed.wrong_address",
+        label: "Wrong payout wallet",
+        description: "USDT sent to a different address than the intent.",
+        testTxHash: "sandbox_payment_wrong_address",
+        eventType: "payment.failed",
+        expectsSuccess: false,
+        expectedCode: "PAYMENT_WRONG_ADDRESS",
+    },
+    {
+        id: "payment.failed.too_early",
+        label: "Transaction too early",
+        description: "Transfer before checkout session (outside grace window).",
+        testTxHash: "sandbox_payment_too_early",
+        eventType: "payment.failed",
+        expectsSuccess: false,
+        expectedCode: "PAYMENT_TOO_EARLY",
+    },
+    {
+        id: "payment.failed.tx_not_found",
+        label: "Transaction not found",
+        description: "No USDT transfer for this hash (simulated).",
+        testTxHash: "sandbox_payment_not_found",
+        eventType: "payment.failed",
+        expectsSuccess: false,
+        expectedCode: "PAYMENT_TX_NOT_FOUND",
+    },
+    {
+        id: "payment.failed.invalid_hash",
+        label: "Invalid transaction hash",
+        description: "Malformed tx id (not 64 hex in production rules).",
+        testTxHash: "sandbox_payment_invalid_hash",
+        eventType: "payment.failed",
+        expectsSuccess: false,
+        expectedCode: "INVALID_TX_HASH",
+    },
+];
+const SCENARIO_BY_ID = new Map(exports.SANDBOX_SCENARIOS.map((s) => [s.id, s]));
+const TX_ALIASES = {
+    sandbox_payment_confirmed: "payment.confirmed",
+    sandbox_payment_short: "payment.failed.short",
+    sandbox_payment_expired: "payment.failed.expired",
+    sandbox_payment_wrong_address: "payment.failed.wrong_address",
+    sandbox_payment_too_early: "payment.failed.too_early",
+    sandbox_payment_not_found: "payment.failed.tx_not_found",
+    sandbox_payment_invalid_hash: "payment.failed.invalid_hash",
+    sandbox_confirm: "payment.confirmed",
+    sandbox_confirm_test: "payment.confirmed",
+    sandbox_success: "payment.confirmed",
+    sandbox_paid: "payment.confirmed",
+    sandbox_payer_submitted_tx: "payment.confirmed",
+    sandbox_underpay: "payment.failed.short",
+    sandbox_short: "payment.failed.short",
+    sandbox_expired: "payment.failed.expired",
+    sandbox_wrong_address: "payment.failed.wrong_address",
+    sandbox_too_early: "payment.failed.too_early",
+    sandbox_not_found: "payment.failed.tx_not_found",
+    sandbox_tx_not_found: "payment.failed.tx_not_found",
+    sandbox_invalid_hash: "payment.failed.invalid_hash",
+};
+function isSandboxTxHash(txHash) {
+    return txHash.trim().toLowerCase().startsWith(exports.SANDBOX_TX_PREFIX);
+}
+function getSandboxScenario(id) {
+    const scenario = SCENARIO_BY_ID.get(id);
+    if (!scenario)
+        throw new Error(`Unknown sandbox scenario: ${id}`);
+    return scenario;
+}
+function listSandboxScenarios() {
+    return [...exports.SANDBOX_SCENARIOS];
+}
+function resolveSandboxScenario(txHash) {
+    if (!isSandboxTxHash(txHash))
+        return null;
+    const key = txHash.trim().toLowerCase();
+    if (TX_ALIASES[key])
+        return TX_ALIASES[key];
+    for (const scenario of exports.SANDBOX_SCENARIOS) {
+        if (scenario.testTxHash === key)
+            return scenario.id;
+    }
+    /** Legacy: any other sandbox_* tx succeeds */
+    return "payment.confirmed";
+}
+/** Unique per checkout (merchantRef) so sandbox test txs do not collide in @unique txHash columns. */
+function sandboxStoredTxHash(intent, inputTxHash) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(`${inputTxHash.trim().toLowerCase()}|${intent.merchantRef}`)
+        .digest("hex");
+}
+const SANDBOX_ALT_PAYOUT = "TJXZEpXAzQD9s7YhfHwdCNJYwVf3fWmXnA";
+function sandboxTransferForIntent(intent, txHash, scenarioId = "payment.confirmed") {
+    const hash = sandboxStoredTxHash(intent, txHash);
+    const base = {
+        txHash: hash,
+        fromAddress: "TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH",
+        token: "USDT_TRC20",
+        network: "tron",
+        blockTimestamp: intent.createdAt.getTime() + 5_000,
+    };
+    switch (scenarioId) {
+        case "payment.failed.short":
+            return {
+                ...base,
+                toAddress: intent.payToAddress,
+                amountUsdt: Math.max(0.000001, intent.amount.valueUsdt - 1),
+                amountMicro: BigInt(Math.round(Math.max(0.000001, intent.amount.valueUsdt - 1) * 1_000_000)),
+            };
+        case "payment.failed.wrong_address":
+            return {
+                ...base,
+                toAddress: SANDBOX_ALT_PAYOUT,
+                amountUsdt: intent.amount.valueUsdt,
+                amountMicro: BigInt(Math.round(intent.amount.valueUsdt * 1_000_000)),
+            };
+        case "payment.failed.too_early":
+            return {
+                ...base,
+                toAddress: intent.payToAddress,
+                amountUsdt: intent.amount.valueUsdt,
+                amountMicro: BigInt(Math.round(intent.amount.valueUsdt * 1_000_000)),
+                blockTimestamp: intent.createdAt.getTime() - payments_core_1.ORDER_TIME_GRACE_MS - 60_000,
+            };
+        default:
+            return {
+                ...base,
+                toAddress: intent.payToAddress,
+                amountUsdt: intent.amount.valueUsdt,
+                amountMicro: BigInt(Math.round(intent.amount.valueUsdt * 1_000_000)),
+            };
+    }
+}
+function verifySandboxPayment(intent, txHash) {
+    if (!isSandboxTxHash(txHash)) {
+        return {
+            ok: false,
+            code: "SANDBOX_ONLY",
+            message: `Sandbox mode: use a tx hash starting with "${exports.SANDBOX_TX_PREFIX}"`,
+            intent,
+        };
+    }
+    const scenarioId = resolveSandboxScenario(txHash);
+    if (scenarioId === "payment.failed.invalid_hash") {
+        return {
+            ok: false,
+            code: "INVALID_TX_HASH",
+            message: (0, payments_core_1.failureMessageForCode)("INVALID_TX_HASH"),
+            intent,
+        };
+    }
+    if (scenarioId === "payment.failed.tx_not_found") {
+        return {
+            ok: false,
+            code: "PAYMENT_TX_NOT_FOUND",
+            message: (0, payments_core_1.failureMessageForCode)("PAYMENT_TX_NOT_FOUND"),
+            intent,
+        };
+    }
+    const intentForVerify = scenarioId === "payment.failed.expired"
+        ? { ...intent, expiresAt: new Date(0) }
+        : intent;
+    const transfer = sandboxTransferForIntent(intent, txHash, scenarioId);
+    return (0, payments_core_1.verifyTransferAgainstIntent)((0, payments_core_1.withIntentStatus)(intentForVerify, "confirming"), transfer);
+}
+function emitSandboxTestEvent(input, webhookSecret) {
+    const scenario = getSandboxScenario(input.scenario);
+    const intent = (0, payments_core_1.createPaymentIntent)({
+        merchantRef: input.merchantRef,
+        amountUsdt: input.amountUsdt,
+        payToAddress: input.payToAddress,
+        matchStrategy: input.matchStrategy ?? "minimum_amount",
+        expiresAt: input.expiresAt ?? new Date(Date.now() + 60 * 60 * 1000),
+    });
+    const verification = verifySandboxPayment(intent, scenario.testTxHash);
+    let event;
+    let webhook;
+    if (verification.ok) {
+        const confirmedIntent = (0, payments_core_1.withIntentStatus)(verification.intent, "confirmed");
+        event = (0, payments_core_1.toConfirmedEvent)(confirmedIntent, verification.transfer);
+        if (webhookSecret) {
+            const body = (0, webhook_1.serializeConfirmedEvent)(event);
+            webhook = {
+                body,
+                signature: (0, webhook_1.signWebhookPayload)(webhookSecret, body),
+                headerName: constants_1.WEBHOOK_SIGNATURE_HEADER,
+            };
+        }
+    }
+    return { scenario, intent, verification, event, webhook };
+}

package/dist/webhook.d.ts

@@ -0,0 +1,7 @@
+import type { PaymentConfirmedEvent } from "@autlantic/payments-core";
+export declare function signWebhookPayload(secret: string, body: string): string;
+export declare function verifyWebhookSignature(secret: string, rawBody: string, signatureHeader: string | null | undefined): boolean;
+export declare function serializeConfirmedEvent(event: PaymentConfirmedEvent): string;
+export declare function parseConfirmedWebhookEvent(rawBody: string): PaymentConfirmedEvent | null;
+export declare function parseAndVerifyWebhook(secret: string, rawBody: string, signatureHeader: string | null | undefined): PaymentConfirmedEvent | null;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../src/webhook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,MAAM,CAER;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACzC,OAAO,CAWT;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAE5E;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,GACd,qBAAqB,GAAG,IAAI,CAS9B;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACzC,qBAAqB,GAAG,IAAI,CAG9B"}