@autlantic/payments 0.1.0

package/API.md

@@ -0,0 +1,92 @@
+# API reference — @autlantic/payments v0.1
+
+## `AutlanticPayments`
+
+### Constructor
+
+```ts
+new AutlanticPayments({
+  tronGridApiKey?: string;
+  sandbox?: boolean;
+  webhookSecret?: string;
+  incomingPollLimit?: number;  // default 50, max 200
+  tronGridMaxRetries?: number; // default 2
+});
+```
+
+### `static fromEnv(env?)`
+
+Reads:
+
+| Env | Config |
+|-----|--------|
+| `TRONGRID_API_KEY` | `tronGridApiKey` |
+| `AUTLANTIC_PAYMENTS_SANDBOX` or `AUTLANTIC_PAYMENTS_TEST_MODE` | `sandbox` |
+| `AUTLANTIC_PAYMENTS_WEBHOOK_SECRET` | `webhookSecret` |
+| `AUTLANTIC_PAYMENTS_POLL_LIMIT` | `incomingPollLimit` |
+| `AUTLANTIC_TRONGRID_MAX_RETRIES` | `tronGridMaxRetries` |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `createIntent(input)` | `PaymentIntent` | Validates input, creates intent |
+| `verifyByTxHash(intent, txHash)` | `PaymentVerificationResult` | On-chain or sandbox verify |
+| `findMatchingPayment(intent)` | `MatchedPayment \| null` | Poll recent incoming USDT |
+| `confirmByTxHash(intent, txHash)` | `{ ok, event?, transfer? }` | Verify + `payment.confirmed` event |
+| `signWebhook(event)` | `{ body, signature } \| null` | HMAC-SHA256 outbound webhook |
+| `verifyWebhook(body, header)` | `boolean` | Check `x-autlantic-signature` |
+| `parseWebhook(body, header)` | `PaymentConfirmedEvent \| null` | Verify + parse JSON |
+| `emitTestEvent(input)` | `EmitTestEventResult` | Sandbox: run catalog scenario + optional webhook |
+| `triggerTestEvent(input)` | same as `emitTestEvent` | CLI alias |
+| `listTestScenarios()` | `SandboxScenario[]` | All built-in test cases |
+
+### Sandbox scenario ids
+
+`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`
+
+See [TESTING.md](./TESTING.md).
+
+## Core types (`@autlantic/payments-core`)
+
+- `PaymentIntent`, `CreatePaymentIntentInput`
+- `PaymentMatchStrategy`: `"minimum_amount"` \| `"exact_amount"`
+- `PaymentFailureCode` — see `PAYMENT_FAILURE_CODES`, `failureMessageForCode()`
+- `verifyTransferAgainstIntent(intent, transfer)` — pure, no I/O
+- `defaultCheckoutExpiresAt(hours?)`, `defaultMatchStrategy()`
+- `isValidTronTxHash`, `validatePayToAddress`
+- `isVerificationSuccess` / `isVerificationFailure`
+
+## Chain (`@autlantic/chain-tron`)
+
+- `fetchUsdtTransferByTxHash(txHash)`
+- `findIncomingUsdtPayment(intent, { limit? })`
+- `findMatchingIncomingRow(rows, intent)` — pure filter
+- `configureTronGrid({ apiKey, fetchImpl, maxRetries, retryDelayMs })`
+
+## Webhook event
+
+```json
+{
+  "type": "payment.confirmed",
+  "intentId": "pi_…",
+  "merchantRef": "order_123",
+  "txHash": "…",
+  "amountUsdt": 20,
+  "payToAddress": "T…",
+  "blockTimestamp": 1700000000000,
+  "observedAt": "2026-05-22T12:00:00.000Z"
+}
+```
+
+Header: `x-autlantic-signature` (hex HMAC-SHA256 of raw body).
+
+## CLI
+
+```bash
+pnpm build:sdk
+pnpm --filter @autlantic/payments exec autlantic-payments sandbox \
+  --merchant-ref demo --amount 20 \
+  --to TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH \
+  --tx sandbox_cli_test
+```

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+## 0.1.0 — 2026-05-22 (complete + distribution)
+
+### Distribution
+
+- npm publish ready (`publishConfig`, MIT, dist-only exports) — see [PUBLISHING.md](../PUBLISHING.md)
+- Hosted HTTP API: `apps/payments-api` (`/v1/intents`, `/v1/payments/verify`, API key auth)
+
+## 0.1.0 — 2026-05-22 (complete)
+
+### Added (final)
+
+- `AutlanticPayments.fromEnv()` / `configFromEnv()`
+- `parseWebhook`, `parseConfirmedWebhookEvent`, `parseAndVerifyWebhook`
+- CLI: `autlantic-payments` (`verify` / `sandbox`)
+- `API.md`, `SECURITY.md`, `AUTLANTIC_PAYMENTS_SDK_VERSION`
+- TronGrid retry on 429/5xx; configurable poll limit
+- `PAYMENT_FAILURE_CODES`, `defaultCheckoutExpiresAt`, `defaultMatchStrategy`
+
+## 0.1.0 — 2026-05-22
+
+### Added
+
+- `@autlantic/payments-core` — intents, USDT amounts, verify rules, type guards, tx/address validation
+- `@autlantic/chain-tron` — TronGrid client, TRC-20 fetch by tx hash, incoming payment match, mockable fetch
+- `@autlantic/payments` — `AutlanticPayments` client, sandbox mode, webhook sign/verify
+- Match strategies: `exact_amount`, `minimum_amount`
+- `validateCreatePaymentIntentInput`, `isValidTronTxHash`, `PaymentError`
+- Standalone test suite (`pnpm test:sdk`) — 35+ tests, no network
+- Examples: `example`, `example:merchant`
+- Optional live TronGrid test (`TRONGRID_INTEGRATION=1`)
+- Umbrella doc: [packages/SDK.md](../SDK.md)
+
+### Notes
+
+- v0.1 is monorepo-private; npm publish planned separately.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Autlantic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @autlantic/payments
+
+Autlantic Payments SDK — verify **USDT (TRC-20)** on **TRON** for merchant checkouts.
+
+Standalone library: use in any Node app. Optional integration with the Autlantic product is a separate step.
+
+## Packages
+
+| Package | Role |
+|---------|------|
+| [`@autlantic/payments-core`](../payments-core) | Types, intents, pure verify (no I/O) |
+| [`@autlantic/chain-tron`](../chain-tron) | TronGrid + TRC-20 USDT |
+| `@autlantic/payments` | `AutlanticPayments` client, sandbox, webhooks |
+
+## Install
+
+```bash
+npm install @autlantic/payments
+# monorepo: pnpm add @autlantic/payments@workspace:*
+```
+
+Publish / scope setup: [PUBLISHING.md](../PUBLISHING.md)
+
+## Hosted API (no Node SDK required)
+
+Deploy or run [apps/payments-api](../../apps/payments-api/README.md):
+
+```bash
+pnpm dev:payments-api
+```
+
+Use `X-Autlantic-Api-Key` + REST (`/v1/intents`, `/v1/payments/verify`, …).
+
+## Quickstart
+
+```ts
+import { AutlanticPayments } from "@autlantic/payments";
+
+const payments = new AutlanticPayments({
+  tronGridApiKey: process.env.TRONGRID_API_KEY,
+});
+
+const intent = payments.createIntent({
+  merchantRef: order.id,
+  amountUsdt: 20,
+  payToAddress: creator.payoutAddressTron,
+  matchStrategy: "minimum_amount",
+  expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+});
+
+const result = await payments.verifyByTxHash(intent, txHashFromUser);
+if (result.ok) {
+  await markOrderPaid(order.id, result.transfer.txHash);
+}
+
+const match = await payments.findMatchingPayment(intent);
+```
+
+## Sandbox & test events (Stripe-style)
+
+Full guide: **[TESTING.md](./TESTING.md)**
+
+```ts
+const payments = new AutlanticPayments({ sandbox: true, webhookSecret: "whsec_test" });
+
+// Test tx hashes (like Stripe test cards)
+await payments.verifyByTxHash(intent, "sandbox_payment_confirmed");
+await payments.verifyByTxHash(intent, "sandbox_payment_short"); // → PAYMENT_SHORT
+
+// Trigger events (like stripe trigger)
+const out = payments.emitTestEvent({
+  scenario: "payment.confirmed",
+  merchantRef: "order_1",
+  amountUsdt: 20,
+  payToAddress: "TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH",
+});
+// out.event, out.webhook for your handler
+```
+
+Run the demo:
+
+```bash
+pnpm example:sdk
+```
+
+## Match strategies
+
+| Strategy | Use case |
+|----------|----------|
+| `minimum_amount` | Plan price (e.g. 20 USDT); overpay OK |
+| `exact_amount` | Micro-unit exact match (legacy) |
+
+## Webhooks
+
+```ts
+const payments = new AutlanticPayments({ webhookSecret: process.env.WEBHOOK_SECRET });
+const out = await payments.confirmByTxHash(intent, txHash);
+if (out.ok) {
+  const signed = payments.signWebhook(out.event);
+  // POST signed.body, header: x-autlantic-signature
+}
+```
+
+Inbound: `verifyWebhookSignature(secret, rawBody, header)`.
+
+## API surface
+
+| Method | Description |
+|--------|-------------|
+| `createIntent(input)` | Build `PaymentIntent` for checkout |
+| `verifyByTxHash(intent, hash)` | Verify pasted Tron tx |
+| `findMatchingPayment(intent)` | Poll recent incoming USDT |
+| `confirmByTxHash(intent, hash)` | Verify + `payment.confirmed` event |
+| `signWebhook(event)` | HMAC-SHA256 body + signature |
+
+Re-exported from core/chain: `createPaymentIntent`, `verifyTransferAgainstIntent`, `fetchUsdtTransferByTxHash`, type guards, etc.
+
+## Tests
+
+```bash
+pnpm test:sdk          # all packages (no network)
+pnpm example:sdk       # sandbox demo script
+```
+
+Per package: `pnpm --filter @autlantic/payments-core test`
+
+### Optional live TronGrid test
+
+```bash
+TRONGRID_INTEGRATION=1 \
+TRONGRID_API_KEY=your_key \
+TRON_TEST_TX_HASH=64_char_hex \
+TRON_TEST_PAY_TO=T… \
+TRON_TEST_AMOUNT_USDT=20 \
+pnpm --filter @autlantic/payments test:live
+```
+
+## Environment
+
+| Variable | Used by |
+|----------|---------|
+| `TRONGRID_API_KEY` | Live verify / poll |
+| `webhookSecret` (config) | Outbound webhook signing |
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).
+
+## v0.1 status
+
+**SDK complete** for standalone use.
+
+- Full API: [API.md](./API.md)
+- Umbrella: [packages/SDK.md](../SDK.md)
+- Security: [SECURITY.md](../SECURITY.md)
+
+```bash
+pnpm check:sdk   # build + test + example
+```
+
+```ts
+import { AutlanticPayments } from "@autlantic/payments";
+const payments = AutlanticPayments.fromEnv();
+```
+
+## Roadmap (v0.2+)
+
+- npm publish
+- Multi-chain adapters on same core types
+- Per-order deposit addresses

package/TESTING.md

@@ -0,0 +1,140 @@
+# Testing & sandbox — Stripe-style guide
+
+Use **sandbox mode** as your test environment. No real USDT, no TronGrid key required.
+
+## Enable sandbox (test account)
+
+```bash
+export AUTLANTIC_PAYMENTS_SANDBOX=true
+export AUTLANTIC_PAYMENTS_WEBHOOK_SECRET=whsec_test_123   # optional, for webhook tests
+```
+
+```ts
+import { AutlanticPayments } from "@autlantic/payments";
+
+const payments = AutlanticPayments.fromEnv(); // reads env above
+// or
+const payments = new AutlanticPayments({ sandbox: true, webhookSecret: "whsec_test_123" });
+```
+
+**Never enable sandbox in production.**
+
+---
+
+## Test transaction hashes (like Stripe test cards)
+
+Pass these as `txHash` in `verifyByTxHash` while `sandbox: true`:
+
+| Test tx hash | Scenario | Expected result |
+|--------------|----------|-----------------|
+| `sandbox_payment_confirmed` | Successful payment | `ok: true` → `payment.confirmed` |
+| `sandbox_payment_short` | Underpayment | `PAYMENT_SHORT` |
+| `sandbox_payment_expired` | Expired checkout | `PAYMENT_EXPIRED` |
+| `sandbox_payment_wrong_address` | Wrong wallet | `PAYMENT_WRONG_ADDRESS` |
+| `sandbox_payment_too_early` | Tx before session | `PAYMENT_TOO_EARLY` |
+| `sandbox_payment_not_found` | Tx not on chain | `PAYMENT_TX_NOT_FOUND` |
+| `sandbox_payment_invalid_hash` | Bad hash format | `INVALID_TX_HASH` |
+
+**Legacy aliases** still work: `sandbox_confirm_test`, `sandbox_success`, `sandbox_short`, etc.
+
+Any other `sandbox_*` hash defaults to **success** (backward compatible).
+
+---
+
+## Trigger test events (like `stripe trigger`)
+
+Programmatic — no tx hash needed:
+
+```ts
+const payments = new AutlanticPayments({ sandbox: true, webhookSecret: "whsec_test" });
+
+// Success + signed webhook payload
+const success = payments.emitTestEvent({
+  scenario: "payment.confirmed",
+  merchantRef: "order_1001",
+  amountUsdt: 49,
+  payToAddress: "TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH",
+});
+
+console.log(success.event);
+console.log(success.webhook?.body, success.webhook?.signature);
+
+// Failure path
+const failed = payments.emitTestEvent({
+  scenario: "payment.failed.short",
+  merchantRef: "order_1002",
+  amountUsdt: 20,
+  payToAddress: "TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH",
+});
+
+if (!failed.verification.ok) {
+  console.log(failed.verification.code); // PAYMENT_SHORT
+}
+```
+
+List all scenarios:
+
+```ts
+payments.listTestScenarios().forEach((s) => {
+  console.log(s.id, s.testTxHash, s.description);
+});
+```
+
+---
+
+## CLI
+
+```bash
+pnpm build:sdk
+
+# List scenarios
+pnpm --filter @autlantic/payments exec autlantic-payments scenarios
+
+# Trigger success event (JSON output)
+pnpm --filter @autlantic/payments exec autlantic-payments trigger payment.confirmed \
+  --merchant-ref order_1 --amount 20 \
+  --to TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH
+
+# Trigger failure
+pnpm --filter @autlantic/payments exec autlantic-payments trigger payment.failed.short \
+  --merchant-ref order_2 --amount 20 \
+  --to TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH
+
+# Classic verify with test tx
+pnpm --filter @autlantic/payments exec autlantic-payments sandbox \
+  --merchant-ref order_3 --amount 20 \
+  --to TLyqzVGLV1srkB7dToTAEqgDSfPtXRJZYH \
+  --tx sandbox_payment_confirmed
+```
+
+---
+
+## Webhook handler test flow
+
+1. `emitTestEvent({ scenario: "payment.confirmed", ... })`
+2. POST `webhook.body` to your endpoint with header `x-autlantic-signature: webhook.signature`
+3. In your app: `payments.parseWebhook(rawBody, signature)`
+
+---
+
+## Live mode (optional)
+
+Use real Tron tx hashes (64 hex) + `TRONGRID_API_KEY` with **sandbox off**.
+
+```bash
+TRONGRID_INTEGRATION=1 TRON_TEST_TX_HASH=<64hex> pnpm --filter @autlantic/payments test:live
+```
+
+---
+
+## Scenario reference
+
+| Scenario id | Event type |
+|-------------|------------|
+| `payment.confirmed` | `payment.confirmed` |
+| `payment.failed.short` | `payment.failed` |
+| `payment.failed.expired` | `payment.failed` |
+| `payment.failed.wrong_address` | `payment.failed` |
+| `payment.failed.too_early` | `payment.failed` |
+| `payment.failed.tx_not_found` | `payment.failed` |
+| `payment.failed.invalid_hash` | `payment.failed` |

package/bin/autlantic-payments.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * Autlantic Payments CLI (run `pnpm build:sdk` first).
+ */
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const {
+  AutlanticPayments,
+  configFromEnv,
+  isVerificationSuccess,
+  listSandboxScenarios,
+} = require("../dist/index.js");
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2).replace(/-/g, "_");
+      out[key] = argv[i + 1];
+      i++;
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function usage() {
+  console.log(`Autlantic Payments CLI
+
+Commands:
+  scenarios              List sandbox test scenarios (Stripe-style)
+  trigger <scenario-id>  Emit a test event (requires sandbox)
+  sandbox                Verify using a sandbox test tx hash
+  verify                 Verify a live Tron tx (TRONGRID_API_KEY)
+
+Trigger / sandbox options:
+  --merchant-ref <id>
+  --amount <usdt>
+  --to <tron base58 address>
+  --tx <hash>            (sandbox / verify only)
+
+Examples:
+  autlantic-payments trigger payment.confirmed --merchant-ref o1 --amount 20 --to TLyqz...
+  autlantic-payments sandbox --merchant-ref o1 --amount 20 --to TLyqz... --tx sandbox_payment_confirmed
+`);
+}
+
+function sandboxPayments() {
+  const base = configFromEnv(process.env);
+  return new AutlanticPayments({ ...base, sandbox: true });
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const cmd = args._[0];
+  if (!cmd || cmd === "help" || cmd === "--help") {
+    usage();
+    process.exit(cmd ? 0 : 1);
+  }
+
+  if (cmd === "scenarios") {
+    console.log(JSON.stringify(listSandboxScenarios(), null, 2));
+    return;
+  }
+
+  if (cmd === "trigger") {
+    const scenarioId = args._[1];
+    const merchantRef = args.merchant_ref;
+    const amount = Number(args.amount);
+    const payTo = args.to;
+    if (!scenarioId || !merchantRef || !Number.isFinite(amount) || !payTo) {
+      usage();
+      process.exit(1);
+    }
+    const payments = sandboxPayments();
+    const out = payments.triggerTestEvent({
+      scenario: scenarioId,
+      merchantRef,
+      amountUsdt: amount,
+      payToAddress: payTo,
+    });
+    console.log(
+      JSON.stringify(
+        {
+          scenario: out.scenario.id,
+          ok: out.verification.ok,
+          code: out.verification.ok ? undefined : out.verification.code,
+          message: out.verification.ok ? undefined : out.verification.message,
+          event: out.event,
+          webhook: out.webhook,
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(out.verification.ok ? 0 : 2);
+  }
+
+  const merchantRef = args.merchant_ref;
+  const amount = Number(args.amount);
+  const payTo = args.to;
+  const txHash = args.tx;
+
+  if (!merchantRef || !Number.isFinite(amount) || !payTo || !txHash) {
+    usage();
+    process.exit(1);
+  }
+
+  const base = configFromEnv(process.env);
+  const payments = new AutlanticPayments({
+    ...base,
+    sandbox: cmd === "sandbox" ? true : base.sandbox,
+  });
+
+  const intent = payments.createIntent({
+    merchantRef,
+    amountUsdt: amount,
+    payToAddress: payTo,
+    matchStrategy: "minimum_amount",
+    expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+  });
+
+  const result = await payments.verifyByTxHash(intent, txHash);
+  if (!isVerificationSuccess(result)) {
+    console.error(
+      JSON.stringify(
+        { ok: false, code: result.code, message: result.message },
+        null,
+        2,
+      ),
+    );
+    process.exit(2);
+  }
+
+  console.log(
+    JSON.stringify(
+      {
+        ok: true,
+        txHash: result.transfer.txHash,
+        amountUsdt: result.transfer.amountUsdt,
+        merchantRef: intent.merchantRef,
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,53 @@
+import { type CreatePaymentIntentInput, type MatchedPayment, type OnChainTransfer, type PaymentConfirmedEvent, type PaymentIntent, type PaymentVerificationResult } from "@autlantic/payments-core";
+import type { AutlanticPaymentsConfig } from "./config";
+import { type EmitTestEventInput, type EmitTestEventResult, type SandboxScenario, type SandboxScenarioId } from "./test-scenarios";
+export declare class AutlanticPayments {
+    private readonly config;
+    constructor(config?: AutlanticPaymentsConfig);
+    /** Construct from environment variables (see `configFromEnv`). */
+    static fromEnv(env?: Record<string, string | undefined>): AutlanticPayments;
+    /** Create a payment intent (store on your order / checkout row). */
+    createIntent(input: CreatePaymentIntentInput): PaymentIntent;
+    /**
+     * Verify a user-submitted transaction hash against an intent.
+     */
+    verifyByTxHash(intent: PaymentIntent, txHash: string): Promise<PaymentVerificationResult>;
+    /**
+     * Poll the chain for an incoming transfer matching the intent (exact or minimum amount).
+     */
+    findMatchingPayment(intent: PaymentIntent): Promise<MatchedPayment | null>;
+    /**
+     * Verify and return a confirmed event suitable for webhooks / internal handlers.
+     */
+    confirmByTxHash(intent: PaymentIntent, txHash: string): Promise<{
+        ok: true;
+        event: PaymentConfirmedEvent;
+        transfer: OnChainTransfer;
+    } | {
+        ok: false;
+        result: PaymentVerificationResult;
+    }>;
+    /** Sign a webhook body (send as `x-autlantic-signature` header). */
+    signWebhook(event: PaymentConfirmedEvent): {
+        body: string;
+        signature: string;
+    } | null;
+    /** Verify an inbound webhook from Autlantic (or your own signed events). */
+    verifyWebhook(rawBody: string, signatureHeader: string | null | undefined): boolean;
+    /** Verify signature and parse `payment.confirmed` payload. */
+    parseWebhook(rawBody: string, signatureHeader: string | null | undefined): PaymentConfirmedEvent | null;
+    /**
+     * Stripe-style test harness: run a catalog scenario in sandbox (no TronGrid).
+     * Requires `sandbox: true` on the client.
+     */
+    emitTestEvent(input: EmitTestEventInput): EmitTestEventResult;
+    /** List built-in sandbox scenarios (success + failure paths). */
+    listTestScenarios(): SandboxScenario[];
+    /**
+     * Trigger a scenario by id — same as `emitTestEvent` (CLI-friendly alias).
+     */
+    triggerTestEvent(input: EmitTestEventInput): EmitTestEventResult;
+    private assertSandboxMode;
+}
+export type { EmitTestEventInput, EmitTestEventResult, SandboxScenario, SandboxScenarioId };
+//# 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":"AAKA,OAAO,EAOL,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,yBAAyB,EAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAC;AAExD,OAAO,EAOL,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACvB,MAAM,kBAAkB,CAAC;AAQ1B,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;gBAErC,MAAM,GAAE,uBAA4B;IAQhD,kEAAkE;IAClE,MAAM,CAAC,OAAO,CAAC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,iBAAiB;IAIxF,oEAAoE;IACpE,YAAY,CAAC,KAAK,EAAE,wBAAwB,GAAG,aAAa;IAK5D;;OAEG;IACG,cAAc,CAClB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,yBAAyB,CAAC;IAgDrC;;OAEG;IACG,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA0BhF;;OAEG;IACG,eAAe,CACnB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,MAAM,GACb,OAAO,CACN;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,KAAK,EAAE,qBAAqB,CAAC;QAAC,QAAQ,EAAE,eAAe,CAAA;KAAE,GACrE;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,MAAM,EAAE,yBAAyB,CAAA;KAAE,CACnD;IAWD,oEAAoE;IACpE,WAAW,CAAC,KAAK,EAAE,qBAAqB,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAOrF,4EAA4E;IAC5E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAMnF,8DAA8D;IAC9D,YAAY,CACV,OAAO,EAAE,MAAM,EACf,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACzC,qBAAqB,GAAG,IAAI;IAM/B;;;OAGG;IACH,aAAa,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB;IAK7D,iEAAiE;IACjE,iBAAiB,IAAI,eAAe,EAAE;IAItC;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,kBAAkB,GAAG,mBAAmB;IAIhE,OAAO,CAAC,iBAAiB;CAO1B;AAED,YAAY,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,eAAe,EAAE,iBAAiB,EAAE,CAAC"}