@agent-score/commerce 2.0.1 → 2.1.0

package/dist/{pricing-CxzwyiO6.d.mts → pricing-4n5Ota0D.d.mts}

@@ -1,4 +1,4 @@
-import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-XP0wKgJV.mjs';
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-D6qzh3J0.mjs';
 
 interface HowToPayRailEntry {
     setup?: string[];
@@ -34,7 +34,7 @@ interface HowToPayRails {
  *
  * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
  */
-declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPlaceholder, maxSpend, }: {
+declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPlaceholder, maxSpend, decimals, }: {
     /** The merchant's full URL (e.g., 'https://agents.merchant.example/api/buy'). */
     url: string;
     /** JSON string of the body the agent should retry with — typically the original request body. */
@@ -45,8 +45,13 @@ declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPla
     rails: HowToPayRails;
     /** Placeholder text for the operator token in commands. Defaults to '<your_opc_token>'. */
     opTokenPlaceholder?: string;
-    /** Override max-spend value used in commands. Default: ceil(totalUsd) + 1. */
+    /** Override max-spend value used in commands. Default: `ceil(totalUsd) + 1`
+     *  (for prices ≥ $1) or `totalUsd.toFixed(decimals)` (for sub-dollar prices,
+     *  so the command flags reflect the real amount instead of `1.00`). */
     maxSpend?: string | number;
+    /** Fractional digits when formatting the auto-derived `maxSpend` for
+     *  sub-dollar / sub-cent prices. Default `2`. */
+    decimals?: number;
 }): HowToPayBlock;
 
 /** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
@@ -172,7 +177,7 @@ interface PricingBlock {
  * omit entirely if you don't want shipping in the response shape at all. Total floors at 0
  * when discount exceeds subtotal + tax + shipping.
  */
-declare function buildPricingBlock({ subtotalCents, taxCents, shippingCents, discountCents, totalCents, taxRate, taxState, currency, }: {
+declare function buildPricingBlock({ subtotalCents, taxCents, shippingCents, discountCents, totalCents, taxRate, taxState, currency, decimals, }: {
     subtotalCents: number;
     taxCents?: number;
     shippingCents?: number;
@@ -181,6 +186,11 @@ declare function buildPricingBlock({ subtotalCents, taxCents, shippingCents, dis
     taxRate?: number;
     taxState?: string;
     currency?: string;
+    /** Dollar-precision for every emitted money field (default `2`). Raise for
+     *  sub-cent unit pricing so `subtotal` / `total` show the real amount
+     *  instead of rounding to two decimals. Subtotal/tax/total inputs become
+     *  fractional cents under this mode. */
+    decimals?: number;
 }): PricingBlock;
 
 export { type AgentInstructions as A, type CompatibleClients as C, type HowToPayBlock as H, type PricingBlock as P, type RailKey as R, type HowToPayRailEntry as a, type HowToPayRails as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, buildPricingBlock as f, compatibleClientsByRails as g };

package/dist/{pricing-CQ9DIFaw.d.ts → pricing-DHfH3ogG.d.ts}

@@ -1,4 +1,4 @@
-import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-XP0wKgJV.js';
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-D6qzh3J0.js';
 
 interface HowToPayRailEntry {
     setup?: string[];
@@ -34,7 +34,7 @@ interface HowToPayRails {
  *
  * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
  */
-declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPlaceholder, maxSpend, }: {
+declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPlaceholder, maxSpend, decimals, }: {
     /** The merchant's full URL (e.g., 'https://agents.merchant.example/api/buy'). */
     url: string;
     /** JSON string of the body the agent should retry with — typically the original request body. */
@@ -45,8 +45,13 @@ declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPla
     rails: HowToPayRails;
     /** Placeholder text for the operator token in commands. Defaults to '<your_opc_token>'. */
     opTokenPlaceholder?: string;
-    /** Override max-spend value used in commands. Default: ceil(totalUsd) + 1. */
+    /** Override max-spend value used in commands. Default: `ceil(totalUsd) + 1`
+     *  (for prices ≥ $1) or `totalUsd.toFixed(decimals)` (for sub-dollar prices,
+     *  so the command flags reflect the real amount instead of `1.00`). */
     maxSpend?: string | number;
+    /** Fractional digits when formatting the auto-derived `maxSpend` for
+     *  sub-dollar / sub-cent prices. Default `2`. */
+    decimals?: number;
 }): HowToPayBlock;
 
 /** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
@@ -172,7 +177,7 @@ interface PricingBlock {
  * omit entirely if you don't want shipping in the response shape at all. Total floors at 0
  * when discount exceeds subtotal + tax + shipping.
  */
-declare function buildPricingBlock({ subtotalCents, taxCents, shippingCents, discountCents, totalCents, taxRate, taxState, currency, }: {
+declare function buildPricingBlock({ subtotalCents, taxCents, shippingCents, discountCents, totalCents, taxRate, taxState, currency, decimals, }: {
     subtotalCents: number;
     taxCents?: number;
     shippingCents?: number;
@@ -181,6 +186,11 @@ declare function buildPricingBlock({ subtotalCents, taxCents, shippingCents, dis
     taxRate?: number;
     taxState?: string;
     currency?: string;
+    /** Dollar-precision for every emitted money field (default `2`). Raise for
+     *  sub-cent unit pricing so `subtotal` / `total` show the real amount
+     *  instead of rounding to two decimals. Subtotal/tax/total inputs become
+     *  fractional cents under this mode. */
+    decimals?: number;
 }): PricingBlock;
 
 export { type AgentInstructions as A, type CompatibleClients as C, type HowToPayBlock as H, type PricingBlock as P, type RailKey as R, type HowToPayRailEntry as a, type HowToPayRails as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, buildPricingBlock as f, compatibleClientsByRails as g };

package/dist/{rail_spec-XP0wKgJV.d.mts → rail_spec-D6qzh3J0.d.mts}

@@ -129,4 +129,4 @@ declare const RAIL_SPEC_DEFAULTS: {
     };
 };
 
-export { RAIL_SPEC_DEFAULTS as R, type SolanaMppRailSpec as S, type TempoRailSpec as T, type X402BaseRailSpec as X, type TempoSessionRailSpec as a, type StripeRailSpec as b, type RecipientLike as c, resolveRecipient as r };
+export { RAIL_SPEC_DEFAULTS as R, type SolanaMppRailSpec as S, type TempoRailSpec as T, type X402BaseRailSpec as X, type RecipientLike as a, type StripeRailSpec as b, type TempoSessionRailSpec as c, resolveRecipient as r };

package/dist/{rail_spec-XP0wKgJV.d.ts → rail_spec-D6qzh3J0.d.ts}

@@ -129,4 +129,4 @@ declare const RAIL_SPEC_DEFAULTS: {
     };
 };
 
-export { RAIL_SPEC_DEFAULTS as R, type SolanaMppRailSpec as S, type TempoRailSpec as T, type X402BaseRailSpec as X, type TempoSessionRailSpec as a, type StripeRailSpec as b, type RecipientLike as c, resolveRecipient as r };
+export { RAIL_SPEC_DEFAULTS as R, type SolanaMppRailSpec as S, type TempoRailSpec as T, type X402BaseRailSpec as X, type RecipientLike as a, type StripeRailSpec as b, type TempoSessionRailSpec as c, resolveRecipient as r };

package/dist/stripe-multichain/index.d.mts

@@ -52,6 +52,106 @@ declare function createMultichainPaymentIntent({ stripe, amount, currency, netwo
     idempotencyKey?: string;
 }): Promise<MultichainPaymentIntentResult>;
 
+/**
+ * Stripe PaymentIntent + deposit-address cache.
+ *
+ * Stripe-multichain merchants need three lookups during a request lifecycle:
+ *
+ *   1. **Is this on-chain `pay_to` address one we minted?** — when an MPP credential
+ *      arrives with a `recipient`, verify it matches a recently-minted Stripe deposit
+ *      address. Validates the credential's deposit address against the addresses the
+ *      merchant has actually minted.
+ *
+ *   2. **Which PaymentIntent owns this deposit address?** — when settling, the
+ *      `simulate_crypto_deposit` test_helpers call needs the PaymentIntent id for the
+ *      deposit address that was paid to.
+ *
+ *   3. **Which sibling deposit addresses belong to the same PaymentIntent?** — when
+ *      enriching a 402 with x402 entries, the merchant needs the Base + Solana addresses
+ *      Stripe minted alongside the original Tempo address (one PI carries up to three).
+ *
+ * All three are TTL-bounded (default 300s — long enough for an agent to retry, short
+ * enough to bound memory). Backed by Redis when `redisUrl` is set, falls back to
+ * in-process Map otherwise. Single-instance servers can use the in-memory cache;
+ * multi-instance deployments need a shared cache (Redis) so a deposit lands on
+ * whichever instance settles it.
+ */
+interface PiCache {
+    /** Mark an on-chain address as one this merchant minted. Idempotent + TTL-bounded. */
+    cacheAddress(address: string): Promise<void>;
+    /** Return true when the address was minted by this merchant within TTL. */
+    hasAddress(address: string): Promise<boolean>;
+    /** Associate an on-chain deposit address with the Stripe PaymentIntent that minted it. */
+    cachePaymentIntent(depositAddress: string, paymentIntentId: string): void;
+    /** Get the Stripe PaymentIntent id for a previously-minted deposit address, or undefined. */
+    getPaymentIntentId(depositAddress: string): string | undefined;
+    /** Associate a PaymentIntent id with the full set of sibling deposit addresses (one per network). */
+    cacheNetworkAddresses(paymentIntentId: string, addresses: Record<string, string>): void;
+    /** Look up the deposit address Stripe minted on a specific network for a given PaymentIntent. */
+    getNetworkDepositAddress(paymentIntentId: string, network: string): string | undefined;
+    /** Stop the background TTL-eviction loop. Call from server shutdown handlers. */
+    stop(): void;
+}
+declare function createPiCache({ redisUrl, ttlSeconds, keyPrefix, }?: {
+    /** Redis connection URL (e.g. `rediss://…cache.amazonaws.com:6379`). When omitted,
+     *  the cache falls back to in-process Maps with the same API. */
+    redisUrl?: string;
+    /** TTL for cached entries in seconds. Default 300. */
+    ttlSeconds?: number;
+    /** Prefix for Redis keys. Default `'payto:'`. */
+    keyPrefix?: string;
+}): PiCache;
+
+/**
+ * Per-order Stripe-multichain `pay_to` resolver.
+ *
+ * Stripe-multichain merchants need ONE function for their `mintRecipients`
+ * (or per-request payTo) hook that does the right thing on both legs:
+ *
+ *   - **Discovery leg** (no payment header): mint a fresh PaymentIntent so
+ *     the 402 advertises a stable per-order deposit address.
+ *   - **Settle leg** (MPP credential attached): reuse the buyer's
+ *     signed-against payTo from the credential (after verifying it's in the
+ *     local cache) — otherwise the verify leg would compare against a
+ *     freshly-rotated address and reject the credential.
+ *
+ * Stripe SPT and card methods don't carry an on-chain recipient, so the
+ * settle leg still mints a fresh PaymentIntent for them.
+ *
+ * Mirrors the hand-rolled `createPayToAddress` block consumers wrote in
+ * `lib/payment.ts`. Lifts the structural branching; merchants keep
+ * env-driven config (network list, default network, metadata) at the call site.
+ */
+
+interface CreatePayToAddressFromStripePIOptions {
+    /** Inbound HTTP request — header is read for an Authorization Payment credential. */
+    request: Request;
+    /** Order amount in cents. */
+    amountCents: number;
+    /** Configured Stripe client (peer dep). */
+    stripe: StripeClientLike;
+    /** Cache backing the merchant's minted addresses + PI lookups. */
+    piCache: PiCache;
+    /** Networks to advertise to Stripe `deposit_options`. Default ['tempo', 'base', 'solana']. */
+    networks?: string[];
+    /** Optional Stripe metadata. */
+    metadata?: Record<string, string>;
+    /** Pending-order id; used as the Stripe idempotency key seed so retries
+     *  of the same order don't mint duplicate PaymentIntents. */
+    orderId?: string;
+    /** Preferred network for the returned address when minting fresh. Default
+     *  picks `tempo`, falls back to `base`. */
+    preferredNetwork?: string;
+}
+/** Returns the on-chain `pay_to` address the agent should be told to pay
+ *  (in the 402 challenge or the bound MPP credential).
+ *
+ *  On the settle leg, when the inbound `Authorization: Payment` credential
+ *  binds a `tempo` or `solana` recipient, the helper returns THAT address
+ *  (after verifying it's still in `piCache`). Otherwise it mints a fresh
+ *  `createMultichainPaymentIntent` and caches the addresses + PI mapping. */
+declare function createPayToAddressFromStripePI(opts: CreatePayToAddressFromStripePIOptions): Promise<string>;
+
 /**
  * Stripe's documented magic test_helpers transaction hash that resolves the
  * PaymentIntent to `succeeded` within 15 seconds. Same value across all networks —
@@ -157,54 +257,57 @@ declare function createMppxStripe({ profileId, secretKey, paymentMethodTypes, }:
     paymentMethodTypes?: string[];
 }): Promise<unknown>;
 
-/**
- * Stripe PaymentIntent + deposit-address cache.
- *
- * Stripe-multichain merchants need three lookups during a request lifecycle:
+/** Settle-outcome → simulator dispatch. Replaces the 3-branch rail/railKey
+ *  switch + thin `simulateDepositIfTestnet(addr, network)` wrapper that
+ *  consumer codebases (sayer, martin, sandbox) hand-rolled in their own
+ *  `lib/payment.ts` files.
  *
- *   1. **Is this on-chain `pay_to` address one we minted?** — when an MPP credential
- *      arrives with a `recipient`, verify it matches a recently-minted Stripe deposit
- *      address. Validates the credential's deposit address against the addresses the
- *      merchant has actually minted.
- *
- *   2. **Which PaymentIntent owns this deposit address?** — when settling, the
- *      `simulate_crypto_deposit` test_helpers call needs the PaymentIntent id for the
- *      deposit address that was paid to.
- *
- *   3. **Which sibling deposit addresses belong to the same PaymentIntent?** — when
- *      enriching a 402 with x402 entries, the merchant needs the Base + Solana addresses
- *      Stripe minted alongside the original Tempo address (one PI carries up to three).
- *
- * All three are TTL-bounded (default 300s — long enough for an agent to retry, short
- * enough to bound memory). Backed by Redis when `redisUrl` is set, falls back to
- * in-process Map otherwise. Single-instance servers can use the in-memory cache;
- * multi-instance deployments need a shared cache (Redis) so a deposit lands on
- * whichever instance settles it.
+ *  Folding the dispatch into the SDK removes the consumer-wrap anti-pattern
+ *  (`feedback_no_consumer_sdk_rewrapping`): merchants call this directly from
+ *  `onSettled`, no per-merchant payment.ts wrapper needed.
  */
-interface PiCache {
-    /** Mark an on-chain address as one this merchant minted. Idempotent + TTL-bounded. */
-    cacheAddress(address: string): Promise<void>;
-    /** Return true when the address was minted by this merchant within TTL. */
-    hasAddress(address: string): Promise<boolean>;
-    /** Associate an on-chain deposit address with the Stripe PaymentIntent that minted it. */
-    cachePaymentIntent(depositAddress: string, paymentIntentId: string): void;
-    /** Get the Stripe PaymentIntent id for a previously-minted deposit address, or undefined. */
-    getPaymentIntentId(depositAddress: string): string | undefined;
-    /** Associate a PaymentIntent id with the full set of sibling deposit addresses (one per network). */
-    cacheNetworkAddresses(paymentIntentId: string, addresses: Record<string, string>): void;
-    /** Look up the deposit address Stripe minted on a specific network for a given PaymentIntent. */
-    getNetworkDepositAddress(paymentIntentId: string, network: string): string | undefined;
-    /** Stop the background TTL-eviction loop. Call from server shutdown handlers. */
-    stop(): void;
+type SimulateNetwork = 'tempo' | 'base' | 'solana';
+/** Map a settle outcome (from `Checkout.onSettled` or
+ *  `computeFirstCheckout.onSettled`) to the `network` arg consumed by
+ *  `simulateDepositIfTestMode`. Returns null for:
+ *   - Stripe SPT (no on-chain deposit)
+ *   - rails we don't recognize
+ *
+ *  Accepts both Checkout-shaped outcomes (`rail` + `railKey`) and
+ *  computeFirstCheckout-shaped outcomes (`rail` + `mppMethod`). The settle
+ *  outcomes diverged historically; this helper canonicalizes them. */
+declare function networkForOutcome(outcome: {
+    rail?: string;
+    railKey?: string;
+    mppMethod?: string;
+}): SimulateNetwork | null;
+interface SimulateDepositForOutcomeOptions {
+    /** The settle outcome handed to `onSettled`. Reads `rail` / `railKey` /
+     *  `mppMethod` to pick the network arg. */
+    outcome: {
+        rail?: string;
+        railKey?: string;
+        mppMethod?: string;
+    };
+    /** On-chain deposit address that was paid to. For Stripe-multichain
+     *  merchants this is the per-order minted address; for static-recipient
+     *  merchants it's the merchant treasury. */
+    depositAddress: string;
+    /** PI-id resolver. Typically `piCache.getPaymentIntentId` from
+     *  `createPiCache(...)`. */
+    getPaymentIntentId: (depositAddress: string) => string | undefined;
+    /** Stripe secret key. The wrapper checks `sk_test_` and no-ops on live. */
+    stripeSecretKey: string;
+    /** Stripe API version (defaults to the deposit-mode preview). */
+    stripeVersion?: string;
+    /** Optional simulated buyer wallet. */
+    buyerWallet?: string;
 }
-declare function createPiCache({ redisUrl, ttlSeconds, keyPrefix, }?: {
-    /** Redis connection URL (e.g. `rediss://…cache.amazonaws.com:6379`). When omitted,
-     *  the cache falls back to in-process Maps with the same API. */
-    redisUrl?: string;
-    /** TTL for cached entries in seconds. Default 300. */
-    ttlSeconds?: number;
-    /** Prefix for Redis keys. Default `'payto:'`. */
-    keyPrefix?: string;
-}): PiCache;
+/** Dispatch `simulateDepositIfTestMode` based on the outcome's rail. Calls
+ *  through to the SDK simulator; no-op for Stripe SPT or unknown rails.
+ *
+ *  Use this in `onSettled` to replace the hand-rolled rail switch +
+ *  `simulateDepositIfTestnet` wrapper pattern. */
+declare function simulateDepositForOutcome(opts: SimulateDepositForOutcomeOptions): Promise<void>;
 
-export { type MultichainPaymentIntentResult, type PiCache, STRIPE_TEST_TX_HASH_FAILED, STRIPE_TEST_TX_HASH_SUCCESS, type StripeClientLike, type StripePaymentIntent, createMppxStripe, createMultichainPaymentIntent, createPiCache, simulateCryptoDeposit, simulateDepositIfTestMode };
+export { type CreatePayToAddressFromStripePIOptions, type MultichainPaymentIntentResult, type PiCache, STRIPE_TEST_TX_HASH_FAILED, STRIPE_TEST_TX_HASH_SUCCESS, type SimulateDepositForOutcomeOptions, type SimulateNetwork, type StripeClientLike, type StripePaymentIntent, createMppxStripe, createMultichainPaymentIntent, createPayToAddressFromStripePI, createPiCache, networkForOutcome, simulateCryptoDeposit, simulateDepositForOutcome, simulateDepositIfTestMode };

package/dist/stripe-multichain/index.d.ts

@@ -52,6 +52,106 @@ declare function createMultichainPaymentIntent({ stripe, amount, currency, netwo
     idempotencyKey?: string;
 }): Promise<MultichainPaymentIntentResult>;
 
+/**
+ * Stripe PaymentIntent + deposit-address cache.
+ *
+ * Stripe-multichain merchants need three lookups during a request lifecycle:
+ *
+ *   1. **Is this on-chain `pay_to` address one we minted?** — when an MPP credential
+ *      arrives with a `recipient`, verify it matches a recently-minted Stripe deposit
+ *      address. Validates the credential's deposit address against the addresses the
+ *      merchant has actually minted.
+ *
+ *   2. **Which PaymentIntent owns this deposit address?** — when settling, the
+ *      `simulate_crypto_deposit` test_helpers call needs the PaymentIntent id for the
+ *      deposit address that was paid to.
+ *
+ *   3. **Which sibling deposit addresses belong to the same PaymentIntent?** — when
+ *      enriching a 402 with x402 entries, the merchant needs the Base + Solana addresses
+ *      Stripe minted alongside the original Tempo address (one PI carries up to three).
+ *
+ * All three are TTL-bounded (default 300s — long enough for an agent to retry, short
+ * enough to bound memory). Backed by Redis when `redisUrl` is set, falls back to
+ * in-process Map otherwise. Single-instance servers can use the in-memory cache;
+ * multi-instance deployments need a shared cache (Redis) so a deposit lands on
+ * whichever instance settles it.
+ */
+interface PiCache {
+    /** Mark an on-chain address as one this merchant minted. Idempotent + TTL-bounded. */
+    cacheAddress(address: string): Promise<void>;
+    /** Return true when the address was minted by this merchant within TTL. */
+    hasAddress(address: string): Promise<boolean>;
+    /** Associate an on-chain deposit address with the Stripe PaymentIntent that minted it. */
+    cachePaymentIntent(depositAddress: string, paymentIntentId: string): void;
+    /** Get the Stripe PaymentIntent id for a previously-minted deposit address, or undefined. */
+    getPaymentIntentId(depositAddress: string): string | undefined;
+    /** Associate a PaymentIntent id with the full set of sibling deposit addresses (one per network). */
+    cacheNetworkAddresses(paymentIntentId: string, addresses: Record<string, string>): void;
+    /** Look up the deposit address Stripe minted on a specific network for a given PaymentIntent. */
+    getNetworkDepositAddress(paymentIntentId: string, network: string): string | undefined;
+    /** Stop the background TTL-eviction loop. Call from server shutdown handlers. */
+    stop(): void;
+}
+declare function createPiCache({ redisUrl, ttlSeconds, keyPrefix, }?: {
+    /** Redis connection URL (e.g. `rediss://…cache.amazonaws.com:6379`). When omitted,
+     *  the cache falls back to in-process Maps with the same API. */
+    redisUrl?: string;
+    /** TTL for cached entries in seconds. Default 300. */
+    ttlSeconds?: number;
+    /** Prefix for Redis keys. Default `'payto:'`. */
+    keyPrefix?: string;
+}): PiCache;
+
+/**
+ * Per-order Stripe-multichain `pay_to` resolver.
+ *
+ * Stripe-multichain merchants need ONE function for their `mintRecipients`
+ * (or per-request payTo) hook that does the right thing on both legs:
+ *
+ *   - **Discovery leg** (no payment header): mint a fresh PaymentIntent so
+ *     the 402 advertises a stable per-order deposit address.
+ *   - **Settle leg** (MPP credential attached): reuse the buyer's
+ *     signed-against payTo from the credential (after verifying it's in the
+ *     local cache) — otherwise the verify leg would compare against a
+ *     freshly-rotated address and reject the credential.
+ *
+ * Stripe SPT and card methods don't carry an on-chain recipient, so the
+ * settle leg still mints a fresh PaymentIntent for them.
+ *
+ * Mirrors the hand-rolled `createPayToAddress` block consumers wrote in
+ * `lib/payment.ts`. Lifts the structural branching; merchants keep
+ * env-driven config (network list, default network, metadata) at the call site.
+ */
+
+interface CreatePayToAddressFromStripePIOptions {
+    /** Inbound HTTP request — header is read for an Authorization Payment credential. */
+    request: Request;
+    /** Order amount in cents. */
+    amountCents: number;
+    /** Configured Stripe client (peer dep). */
+    stripe: StripeClientLike;
+    /** Cache backing the merchant's minted addresses + PI lookups. */
+    piCache: PiCache;
+    /** Networks to advertise to Stripe `deposit_options`. Default ['tempo', 'base', 'solana']. */
+    networks?: string[];
+    /** Optional Stripe metadata. */
+    metadata?: Record<string, string>;
+    /** Pending-order id; used as the Stripe idempotency key seed so retries
+     *  of the same order don't mint duplicate PaymentIntents. */
+    orderId?: string;
+    /** Preferred network for the returned address when minting fresh. Default
+     *  picks `tempo`, falls back to `base`. */
+    preferredNetwork?: string;
+}
+/** Returns the on-chain `pay_to` address the agent should be told to pay
+ *  (in the 402 challenge or the bound MPP credential).
+ *
+ *  On the settle leg, when the inbound `Authorization: Payment` credential
+ *  binds a `tempo` or `solana` recipient, the helper returns THAT address
+ *  (after verifying it's still in `piCache`). Otherwise it mints a fresh
+ *  `createMultichainPaymentIntent` and caches the addresses + PI mapping. */
+declare function createPayToAddressFromStripePI(opts: CreatePayToAddressFromStripePIOptions): Promise<string>;
+
 /**
  * Stripe's documented magic test_helpers transaction hash that resolves the
  * PaymentIntent to `succeeded` within 15 seconds. Same value across all networks —
@@ -157,54 +257,57 @@ declare function createMppxStripe({ profileId, secretKey, paymentMethodTypes, }:
     paymentMethodTypes?: string[];
 }): Promise<unknown>;
 
-/**
- * Stripe PaymentIntent + deposit-address cache.
- *
- * Stripe-multichain merchants need three lookups during a request lifecycle:
+/** Settle-outcome → simulator dispatch. Replaces the 3-branch rail/railKey
+ *  switch + thin `simulateDepositIfTestnet(addr, network)` wrapper that
+ *  consumer codebases (sayer, martin, sandbox) hand-rolled in their own
+ *  `lib/payment.ts` files.
  *
- *   1. **Is this on-chain `pay_to` address one we minted?** — when an MPP credential
- *      arrives with a `recipient`, verify it matches a recently-minted Stripe deposit
- *      address. Validates the credential's deposit address against the addresses the
- *      merchant has actually minted.
- *
- *   2. **Which PaymentIntent owns this deposit address?** — when settling, the
- *      `simulate_crypto_deposit` test_helpers call needs the PaymentIntent id for the
- *      deposit address that was paid to.
- *
- *   3. **Which sibling deposit addresses belong to the same PaymentIntent?** — when
- *      enriching a 402 with x402 entries, the merchant needs the Base + Solana addresses
- *      Stripe minted alongside the original Tempo address (one PI carries up to three).
- *
- * All three are TTL-bounded (default 300s — long enough for an agent to retry, short
- * enough to bound memory). Backed by Redis when `redisUrl` is set, falls back to
- * in-process Map otherwise. Single-instance servers can use the in-memory cache;
- * multi-instance deployments need a shared cache (Redis) so a deposit lands on
- * whichever instance settles it.
+ *  Folding the dispatch into the SDK removes the consumer-wrap anti-pattern
+ *  (`feedback_no_consumer_sdk_rewrapping`): merchants call this directly from
+ *  `onSettled`, no per-merchant payment.ts wrapper needed.
  */
-interface PiCache {
-    /** Mark an on-chain address as one this merchant minted. Idempotent + TTL-bounded. */
-    cacheAddress(address: string): Promise<void>;
-    /** Return true when the address was minted by this merchant within TTL. */
-    hasAddress(address: string): Promise<boolean>;
-    /** Associate an on-chain deposit address with the Stripe PaymentIntent that minted it. */
-    cachePaymentIntent(depositAddress: string, paymentIntentId: string): void;
-    /** Get the Stripe PaymentIntent id for a previously-minted deposit address, or undefined. */
-    getPaymentIntentId(depositAddress: string): string | undefined;
-    /** Associate a PaymentIntent id with the full set of sibling deposit addresses (one per network). */
-    cacheNetworkAddresses(paymentIntentId: string, addresses: Record<string, string>): void;
-    /** Look up the deposit address Stripe minted on a specific network for a given PaymentIntent. */
-    getNetworkDepositAddress(paymentIntentId: string, network: string): string | undefined;
-    /** Stop the background TTL-eviction loop. Call from server shutdown handlers. */
-    stop(): void;
+type SimulateNetwork = 'tempo' | 'base' | 'solana';
+/** Map a settle outcome (from `Checkout.onSettled` or
+ *  `computeFirstCheckout.onSettled`) to the `network` arg consumed by
+ *  `simulateDepositIfTestMode`. Returns null for:
+ *   - Stripe SPT (no on-chain deposit)
+ *   - rails we don't recognize
+ *
+ *  Accepts both Checkout-shaped outcomes (`rail` + `railKey`) and
+ *  computeFirstCheckout-shaped outcomes (`rail` + `mppMethod`). The settle
+ *  outcomes diverged historically; this helper canonicalizes them. */
+declare function networkForOutcome(outcome: {
+    rail?: string;
+    railKey?: string;
+    mppMethod?: string;
+}): SimulateNetwork | null;
+interface SimulateDepositForOutcomeOptions {
+    /** The settle outcome handed to `onSettled`. Reads `rail` / `railKey` /
+     *  `mppMethod` to pick the network arg. */
+    outcome: {
+        rail?: string;
+        railKey?: string;
+        mppMethod?: string;
+    };
+    /** On-chain deposit address that was paid to. For Stripe-multichain
+     *  merchants this is the per-order minted address; for static-recipient
+     *  merchants it's the merchant treasury. */
+    depositAddress: string;
+    /** PI-id resolver. Typically `piCache.getPaymentIntentId` from
+     *  `createPiCache(...)`. */
+    getPaymentIntentId: (depositAddress: string) => string | undefined;
+    /** Stripe secret key. The wrapper checks `sk_test_` and no-ops on live. */
+    stripeSecretKey: string;
+    /** Stripe API version (defaults to the deposit-mode preview). */
+    stripeVersion?: string;
+    /** Optional simulated buyer wallet. */
+    buyerWallet?: string;
 }
-declare function createPiCache({ redisUrl, ttlSeconds, keyPrefix, }?: {
-    /** Redis connection URL (e.g. `rediss://…cache.amazonaws.com:6379`). When omitted,
-     *  the cache falls back to in-process Maps with the same API. */
-    redisUrl?: string;
-    /** TTL for cached entries in seconds. Default 300. */
-    ttlSeconds?: number;
-    /** Prefix for Redis keys. Default `'payto:'`. */
-    keyPrefix?: string;
-}): PiCache;
+/** Dispatch `simulateDepositIfTestMode` based on the outcome's rail. Calls
+ *  through to the SDK simulator; no-op for Stripe SPT or unknown rails.
+ *
+ *  Use this in `onSettled` to replace the hand-rolled rail switch +
+ *  `simulateDepositIfTestnet` wrapper pattern. */
+declare function simulateDepositForOutcome(opts: SimulateDepositForOutcomeOptions): Promise<void>;
 
-export { type MultichainPaymentIntentResult, type PiCache, STRIPE_TEST_TX_HASH_FAILED, STRIPE_TEST_TX_HASH_SUCCESS, type StripeClientLike, type StripePaymentIntent, createMppxStripe, createMultichainPaymentIntent, createPiCache, simulateCryptoDeposit, simulateDepositIfTestMode };
+export { type CreatePayToAddressFromStripePIOptions, type MultichainPaymentIntentResult, type PiCache, STRIPE_TEST_TX_HASH_FAILED, STRIPE_TEST_TX_HASH_SUCCESS, type SimulateDepositForOutcomeOptions, type SimulateNetwork, type StripeClientLike, type StripePaymentIntent, createMppxStripe, createMultichainPaymentIntent, createPayToAddressFromStripePI, createPiCache, networkForOutcome, simulateCryptoDeposit, simulateDepositForOutcome, simulateDepositIfTestMode };