@agent-score/commerce 1.8.1 → 2.0.0

package/dist/{agent_instructions-DiMSGkdm.d.mts → pricing-CQ9DIFaw.d.ts}

@@ -1,3 +1,5 @@
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-XP0wKgJV.js';
+
 interface HowToPayRailEntry {
     setup?: string[];
     prerequisite?: string;
@@ -19,7 +21,20 @@ interface HowToPayBlock {
     solana_mpp?: HowToPayRailEntry;
     stripe?: HowToPayStripeEntry;
 }
-interface BuildHowToPayInput {
+interface HowToPayRails {
+    tempo?: TempoRailSpec;
+    x402_base?: X402BaseRailSpec;
+    solana_mpp?: SolanaMppRailSpec;
+    stripe?: StripeRailSpec;
+}
+/**
+ * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
+ * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
+ * they support; the helper produces the right command for each.
+ *
+ * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
+ */
+declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPlaceholder, maxSpend, }: {
     /** 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. */
@@ -27,69 +42,18 @@ interface BuildHowToPayInput {
     /** Total amount in USD (string or number). Used to compute max-spend defaults and stripe context. */
     totalUsd: string | number;
     /** Per-rail config — each is optional. Pass only the rails you support. */
-    rails: {
-        tempo?: {
-            recipient: string;
-            networkName?: string;
-            chainId?: number;
-            recommend?: 'tempo' | 'agentscore-pay' | 'both';
-        };
-        x402_base?: {
-            recipient: string;
-            network?: string;
-        };
-        solana_mpp?: {
-            recipient: string;
-            network?: string;
-        };
-        stripe?: {
-            profileId?: string | null;
-            productName?: string;
-        };
-    };
+    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. */
     maxSpend?: string | number;
-}
-/**
- * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
- * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
- * they support; the helper produces the right command for each.
- *
- * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
- */
-declare function buildHowToPay(input: BuildHowToPayInput): HowToPayBlock;
+}): HowToPayBlock;
 
 /** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
  *  that have been smoke-verified by the merchant against the protocol shape they emit.
  *  Strings are display labels, not install commands — agents already get install commands
  *  via `how_to_pay.<rail>.setup`. Use these as a "what's known to work" hint. */
 type CompatibleClients = Record<string, string[]>;
-interface BuildAgentInstructionsInput {
-    /** Per-rail commands. Build with `buildHowToPay`. */
-    howToPay: HowToPayBlock;
-    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
-    recommendedTools?: string[];
-    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
-    walletCompatibility?: string;
-    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
-    timeoutSeconds?: number;
-    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
-    warnings?: string[];
-    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
-     *  to keep the SDK's protocol warnings AND add merchant-specific notes (e.g., a per-order
-     *  rail-availability message). Ignored when `warnings` is set explicitly. */
-    extraWarnings?: string[];
-    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
-    recommended?: string;
-    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
-     *  this from their own smoke matrix — defaults to none (avoids vouching for clients the
-     *  merchant has not tested). When omitted, the field is not emitted. */
-    compatibleClients?: CompatibleClients;
-    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
-    extra?: Record<string, unknown>;
-}
 interface AgentInstructions {
     how_to_pay: HowToPayBlock;
     recommended_tools: string[];
@@ -128,6 +92,95 @@ declare function compatibleClientsByRails(rails: readonly RailKey[]): Compatible
  * Stripe-only merchants get neither rail-specific warning. Vendors override
  * `warnings`/`recommendedTools` for full control.
  */
-declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
+declare function buildAgentInstructions({ howToPay, recommendedTools, walletCompatibility, timeoutSeconds, warnings, extraWarnings, recommended, compatibleClients, extra, }: {
+    /** Per-rail commands. Build with `buildHowToPay`. */
+    howToPay: HowToPayBlock;
+    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
+    recommendedTools?: string[];
+    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
+    walletCompatibility?: string;
+    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
+    timeoutSeconds?: number;
+    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
+    warnings?: string[];
+    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
+     *  to keep the SDK's protocol warnings AND add merchant-specific notes. Ignored when
+     *  `warnings` is set explicitly. */
+    extraWarnings?: string[];
+    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
+    recommended?: string;
+    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
+     *  this from their own smoke matrix — defaults to none. When omitted, the field is not emitted. */
+    compatibleClients?: CompatibleClients;
+    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
+    extra?: Record<string, unknown>;
+}): AgentInstructions;
+
+/**
+ * Pricing block builder + canonical type.
+ *
+ * Composes the cents-denominated price components into the dollar-string shape that
+ * 402 challenge bodies advertise. Standardizes the pricing block so every merchant
+ * — current and future commerce-platform plugins (Commerce7, WooCommerce, Shopify) —
+ * surfaces the same shape to agents.
+ *
+ * Shipping is included by default because most physical-goods merchants carry it; pass
+ * `shippingCents: 0` (or omit) for digital goods / services. Tax is optional for
+ * merchants outside taxable jurisdictions.
+ */
+interface PricingBlock {
+    /** List-price subtotal as a dollar-string (e.g. `"250.00"`), pre-tax, pre-shipping, pre-discount. */
+    subtotal: string;
+    /** Tax amount as a dollar-string. Always present even if `"0.00"`. */
+    tax: string;
+    /** Shipping cost as a dollar-string. Always present even if `"0.00"`. */
+    shipping?: string;
+    /** Discount deducted from subtotal (redemption code, coupon, promo) as a dollar-string. Omit when no discount applied; agents reading the 402 see `subtotal`/`discount`/`total` and can render the savings line. */
+    discount?: string;
+    /** Final total = subtotal + tax + shipping - discount, dollar-string. Floored at 0. */
+    total: string;
+    /** Tax rate as a decimal fraction (e.g. `0.0775` for 7.75%). Optional — omit for tax-free merchants. */
+    tax_rate?: number;
+    /** ISO-3166-2 state code or jurisdiction name used for tax calc. Optional. */
+    tax_state?: string;
+    /** ISO-4217 currency code. Default `"USD"`. */
+    currency?: string;
+}
+/**
+ * Compose a `PricingBlock` from cents-denominated inputs. Handles the cents → dollar-string
+ * conversion (always 2 decimals) and computes the total when not explicitly provided.
+ * `subtotalCents` is the list price, pre-discount; `discountCents` is the deduction applied
+ * (redemption code, coupon).
+ *
+ * Example:
+ * ```ts
+ * const pricing = buildPricingBlock({
+ *   subtotalCents: 25000,
+ *   taxCents: 1875,
+ *   shippingCents: 999,
+ *   taxRate: 0.075,
+ *   taxState: 'CA',
+ * });
+ * // → { subtotal: '250.00', tax: '18.75', shipping: '9.99', total: '278.74', tax_rate: 0.075, tax_state: 'CA' }
+ *
+ * // Redemption-code applied:
+ * buildPricingBlock({ subtotalCents: 7500, discountCents: 7500 });
+ * // → { subtotal: '75.00', discount: '75.00', tax: '0.00', total: '0.00' }
+ * ```
+ *
+ * Pass `shippingCents: 0` for digital goods if you want the field present (it's then `"0.00"`);
+ * 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, }: {
+    subtotalCents: number;
+    taxCents?: number;
+    shippingCents?: number;
+    discountCents?: number;
+    totalCents?: number;
+    taxRate?: number;
+    taxState?: string;
+    currency?: string;
+}): PricingBlock;
 
-export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, compatibleClientsByRails as f };
+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/{agent_instructions-DiMSGkdm.d.ts → pricing-CxzwyiO6.d.mts}

@@ -1,3 +1,5 @@
+import { T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-XP0wKgJV.mjs';
+
 interface HowToPayRailEntry {
     setup?: string[];
     prerequisite?: string;
@@ -19,7 +21,20 @@ interface HowToPayBlock {
     solana_mpp?: HowToPayRailEntry;
     stripe?: HowToPayStripeEntry;
 }
-interface BuildHowToPayInput {
+interface HowToPayRails {
+    tempo?: TempoRailSpec;
+    x402_base?: X402BaseRailSpec;
+    solana_mpp?: SolanaMppRailSpec;
+    stripe?: StripeRailSpec;
+}
+/**
+ * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
+ * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
+ * they support; the helper produces the right command for each.
+ *
+ * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
+ */
+declare function buildHowToPay({ url, retryBodyJson, totalUsd, rails, opTokenPlaceholder, maxSpend, }: {
     /** 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. */
@@ -27,69 +42,18 @@ interface BuildHowToPayInput {
     /** Total amount in USD (string or number). Used to compute max-spend defaults and stripe context. */
     totalUsd: string | number;
     /** Per-rail config — each is optional. Pass only the rails you support. */
-    rails: {
-        tempo?: {
-            recipient: string;
-            networkName?: string;
-            chainId?: number;
-            recommend?: 'tempo' | 'agentscore-pay' | 'both';
-        };
-        x402_base?: {
-            recipient: string;
-            network?: string;
-        };
-        solana_mpp?: {
-            recipient: string;
-            network?: string;
-        };
-        stripe?: {
-            profileId?: string | null;
-            productName?: string;
-        };
-    };
+    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. */
     maxSpend?: string | number;
-}
-/**
- * Build the agent_instructions.how_to_pay block. Generates per-rail setup/command/what_it_does
- * boilerplate so agents see concrete commands per rail in the 402 body. Vendors pass the rails
- * they support; the helper produces the right command for each.
- *
- * Tool recommendations (tempo CLI vs agentscore-pay vs link-cli) are configurable per rail.
- */
-declare function buildHowToPay(input: BuildHowToPayInput): HowToPayBlock;
+}): HowToPayBlock;
 
 /** Map of rail key (e.g. 'x402_base', 'tempo_mpp', 'stripe') → list of client identifiers
  *  that have been smoke-verified by the merchant against the protocol shape they emit.
  *  Strings are display labels, not install commands — agents already get install commands
  *  via `how_to_pay.<rail>.setup`. Use these as a "what's known to work" hint. */
 type CompatibleClients = Record<string, string[]>;
-interface BuildAgentInstructionsInput {
-    /** Per-rail commands. Build with `buildHowToPay`. */
-    howToPay: HowToPayBlock;
-    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
-    recommendedTools?: string[];
-    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
-    walletCompatibility?: string;
-    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
-    timeoutSeconds?: number;
-    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
-    warnings?: string[];
-    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
-     *  to keep the SDK's protocol warnings AND add merchant-specific notes (e.g., a per-order
-     *  rail-availability message). Ignored when `warnings` is set explicitly. */
-    extraWarnings?: string[];
-    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
-    recommended?: string;
-    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
-     *  this from their own smoke matrix — defaults to none (avoids vouching for clients the
-     *  merchant has not tested). When omitted, the field is not emitted. */
-    compatibleClients?: CompatibleClients;
-    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
-    extra?: Record<string, unknown>;
-}
 interface AgentInstructions {
     how_to_pay: HowToPayBlock;
     recommended_tools: string[];
@@ -128,6 +92,95 @@ declare function compatibleClientsByRails(rails: readonly RailKey[]): Compatible
  * Stripe-only merchants get neither rail-specific warning. Vendors override
  * `warnings`/`recommendedTools` for full control.
  */
-declare function buildAgentInstructions(input: BuildAgentInstructionsInput): AgentInstructions;
+declare function buildAgentInstructions({ howToPay, recommendedTools, walletCompatibility, timeoutSeconds, warnings, extraWarnings, recommended, compatibleClients, extra, }: {
+    /** Per-rail commands. Build with `buildHowToPay`. */
+    howToPay: HowToPayBlock;
+    /** Tool recommendations as human-readable strings. Defaults to a sensible set covering tempo + agentscore-pay. */
+    recommendedTools?: string[];
+    /** Wallet-stack compatibility note for the agent. Default: rail-neutral, no specific wallet stack required. */
+    walletCompatibility?: string;
+    /** How long the merchant will wait for payment after the 402. Default 300 (5 minutes). */
+    timeoutSeconds?: number;
+    /** Warnings about common footguns. Defaults include tempo wallet transfer + raw on-chain x402 deposits. */
+    warnings?: string[];
+    /** Additional warnings appended to the default protocol-footgun set. Use this when you want
+     *  to keep the SDK's protocol warnings AND add merchant-specific notes. Ignored when
+     *  `warnings` is set explicitly. */
+    extraWarnings?: string[];
+    /** Recommended rail (e.g., 'tempo', 'x402_base'). Surfaced for agents to default to. */
+    recommended?: string;
+    /** Per-rail list of client names the merchant has verified work end-to-end. Vendors set
+     *  this from their own smoke matrix — defaults to none. When omitted, the field is not emitted. */
+    compatibleClients?: CompatibleClients;
+    /** Arbitrary additional fields the vendor wants merged into the agent_instructions object. */
+    extra?: Record<string, unknown>;
+}): AgentInstructions;
+
+/**
+ * Pricing block builder + canonical type.
+ *
+ * Composes the cents-denominated price components into the dollar-string shape that
+ * 402 challenge bodies advertise. Standardizes the pricing block so every merchant
+ * — current and future commerce-platform plugins (Commerce7, WooCommerce, Shopify) —
+ * surfaces the same shape to agents.
+ *
+ * Shipping is included by default because most physical-goods merchants carry it; pass
+ * `shippingCents: 0` (or omit) for digital goods / services. Tax is optional for
+ * merchants outside taxable jurisdictions.
+ */
+interface PricingBlock {
+    /** List-price subtotal as a dollar-string (e.g. `"250.00"`), pre-tax, pre-shipping, pre-discount. */
+    subtotal: string;
+    /** Tax amount as a dollar-string. Always present even if `"0.00"`. */
+    tax: string;
+    /** Shipping cost as a dollar-string. Always present even if `"0.00"`. */
+    shipping?: string;
+    /** Discount deducted from subtotal (redemption code, coupon, promo) as a dollar-string. Omit when no discount applied; agents reading the 402 see `subtotal`/`discount`/`total` and can render the savings line. */
+    discount?: string;
+    /** Final total = subtotal + tax + shipping - discount, dollar-string. Floored at 0. */
+    total: string;
+    /** Tax rate as a decimal fraction (e.g. `0.0775` for 7.75%). Optional — omit for tax-free merchants. */
+    tax_rate?: number;
+    /** ISO-3166-2 state code or jurisdiction name used for tax calc. Optional. */
+    tax_state?: string;
+    /** ISO-4217 currency code. Default `"USD"`. */
+    currency?: string;
+}
+/**
+ * Compose a `PricingBlock` from cents-denominated inputs. Handles the cents → dollar-string
+ * conversion (always 2 decimals) and computes the total when not explicitly provided.
+ * `subtotalCents` is the list price, pre-discount; `discountCents` is the deduction applied
+ * (redemption code, coupon).
+ *
+ * Example:
+ * ```ts
+ * const pricing = buildPricingBlock({
+ *   subtotalCents: 25000,
+ *   taxCents: 1875,
+ *   shippingCents: 999,
+ *   taxRate: 0.075,
+ *   taxState: 'CA',
+ * });
+ * // → { subtotal: '250.00', tax: '18.75', shipping: '9.99', total: '278.74', tax_rate: 0.075, tax_state: 'CA' }
+ *
+ * // Redemption-code applied:
+ * buildPricingBlock({ subtotalCents: 7500, discountCents: 7500 });
+ * // → { subtotal: '75.00', discount: '75.00', tax: '0.00', total: '0.00' }
+ * ```
+ *
+ * Pass `shippingCents: 0` for digital goods if you want the field present (it's then `"0.00"`);
+ * 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, }: {
+    subtotalCents: number;
+    taxCents?: number;
+    shippingCents?: number;
+    discountCents?: number;
+    totalCents?: number;
+    taxRate?: number;
+    taxState?: string;
+    currency?: string;
+}): PricingBlock;
 
-export { type AgentInstructions as A, type BuildAgentInstructionsInput as B, type CompatibleClients as C, type HowToPayBlock as H, type RailKey as R, type BuildHowToPayInput as a, type HowToPayRailEntry as b, type HowToPayStripeEntry as c, buildAgentInstructions as d, buildHowToPay as e, compatibleClientsByRails as f };
+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

@@ -0,0 +1,132 @@
+/**
+ * Canonical `*RailSpec` types — one shape per rail, consumed by every helper.
+ *
+ * A merchant accepting Tempo + Base + Solana + Stripe declares one `*RailSpec`
+ * per rail and passes it to every helper (`buildAcceptedMethods`,
+ * `buildHowToPay`, `mppPaymentHandler`, `createMppxServer`, ...). One canonical
+ * shape per rail means the recipient address, network identifier, and token
+ * defaults are declared once and reused everywhere.
+ *
+ * `RecipientLike` is polymorphic over `string | (() => string | Promise<string>)`
+ * so per-order recipients (Stripe-multichain mints fresh deposit addresses per
+ * PaymentIntent) flow through identically to static-treasury recipients. The
+ * factory is called once per helper invocation; callers cache externally.
+ */
+type RecipientLike = string | (() => string | Promise<string>);
+/**
+ * Resolve a `RecipientLike` to a concrete address string. Accepts a string
+ * (returned verbatim), a sync callable (called once), or an async callable
+ * (awaited once). Helpers call this on every invocation; callers that want
+ * once-per-session resolution should cache externally.
+ */
+declare function resolveRecipient(r: RecipientLike): Promise<string>;
+/** Canonical config for the Tempo MPP rail. */
+interface TempoRailSpec {
+    recipient: RecipientLike;
+    network?: string;
+    chainId?: number;
+    token?: string;
+    symbol?: string;
+    decimals?: number;
+    testnet?: boolean;
+    recommend?: 'tempo' | 'agentscore-pay' | 'both';
+}
+/** Canonical config for the x402 EVM (Base) rail. */
+interface X402BaseRailSpec {
+    recipient: RecipientLike;
+    /** CAIP-2 canonical, e.g. `eip155:8453`. */
+    network?: string;
+    chainId?: number;
+    token?: string;
+    symbol?: string;
+    decimals?: number;
+    mode?: 'exact' | 'upto';
+}
+/**
+ * Canonical config for the Solana MPP rail.
+ *
+ * `signer` is an optional fee-payer signer for server-side fee sponsorship —
+ * typed as `unknown` to avoid hard-importing `@solana/kit` types here. Pass any
+ * `TransactionPartialSigner`.
+ */
+interface SolanaMppRailSpec {
+    recipient: RecipientLike;
+    network?: string;
+    token?: string;
+    symbol?: string;
+    decimals?: number;
+    rpcUrl?: string;
+    signer?: unknown;
+    tokenProgram?: string;
+}
+/**
+ * Canonical config for the Stripe SPT rail.
+ *
+ * `recipient` is intentionally absent — Stripe rails use `profileId` as the
+ * merchant-side network identifier the agent's SPT is scoped to; the
+ * transaction recipient is the merchant's Stripe account, not an on-chain
+ * address.
+ */
+interface StripeRailSpec {
+    profileId?: string | null;
+    rails?: ('card' | 'link' | 'shared_payment_token')[];
+    paymentMethodTypes?: string[];
+    productName?: string;
+    secretKey?: string;
+}
+/**
+ * Canonical config for the Tempo session MPP rail (pay-as-you-go channels).
+ *
+ * `escrowContract` is the merchant-deployed on-chain escrow that holds channel
+ * deposits + pays out cumulative vouchers on settlement. `store` is a
+ * `ChannelStore` instance — typed as `unknown` to avoid hard-importing `mppx`'s
+ * store interface here.
+ */
+interface TempoSessionRailSpec {
+    recipient: RecipientLike;
+    escrowContract: string;
+    store: unknown;
+    currency?: string;
+    testnet?: boolean;
+    chains?: unknown;
+}
+/**
+ * Default field values for each `*RailSpec`. Mirrors python-commerce's
+ * `*RailSpec` dataclass defaults — callers can spread these into their spec
+ * literal when they want defaults without typing them out. Sourced from the
+ * USDC registry so they stay in sync with on-chain reality.
+ */
+declare const RAIL_SPEC_DEFAULTS: {
+    readonly tempo: {
+        readonly network: "tempo-mainnet";
+        readonly chainId: 4217;
+        readonly token: "0x20C000000000000000000000b9537d11c60E8b50";
+        readonly symbol: "USDC.e";
+        readonly decimals: 6;
+        readonly testnet: false;
+        readonly recommend: "both";
+    };
+    readonly x402Base: {
+        readonly network: "eip155:8453";
+        readonly chainId: 8453;
+        readonly token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+        readonly symbol: "USDC";
+        readonly decimals: 6;
+        readonly mode: "exact";
+    };
+    readonly solanaMpp: {
+        readonly network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+        readonly token: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+        readonly symbol: "USDC";
+        readonly decimals: 6;
+    };
+    readonly stripe: {
+        readonly rails: ("card" | "link" | "shared_payment_token")[];
+    };
+    readonly tempoSession: {
+        readonly currency: "0x20C000000000000000000000b9537d11c60E8b50";
+        readonly testnet: false;
+    };
+};
+
+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 };

package/dist/rail_spec-XP0wKgJV.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Canonical `*RailSpec` types — one shape per rail, consumed by every helper.
+ *
+ * A merchant accepting Tempo + Base + Solana + Stripe declares one `*RailSpec`
+ * per rail and passes it to every helper (`buildAcceptedMethods`,
+ * `buildHowToPay`, `mppPaymentHandler`, `createMppxServer`, ...). One canonical
+ * shape per rail means the recipient address, network identifier, and token
+ * defaults are declared once and reused everywhere.
+ *
+ * `RecipientLike` is polymorphic over `string | (() => string | Promise<string>)`
+ * so per-order recipients (Stripe-multichain mints fresh deposit addresses per
+ * PaymentIntent) flow through identically to static-treasury recipients. The
+ * factory is called once per helper invocation; callers cache externally.
+ */
+type RecipientLike = string | (() => string | Promise<string>);
+/**
+ * Resolve a `RecipientLike` to a concrete address string. Accepts a string
+ * (returned verbatim), a sync callable (called once), or an async callable
+ * (awaited once). Helpers call this on every invocation; callers that want
+ * once-per-session resolution should cache externally.
+ */
+declare function resolveRecipient(r: RecipientLike): Promise<string>;
+/** Canonical config for the Tempo MPP rail. */
+interface TempoRailSpec {
+    recipient: RecipientLike;
+    network?: string;
+    chainId?: number;
+    token?: string;
+    symbol?: string;
+    decimals?: number;
+    testnet?: boolean;
+    recommend?: 'tempo' | 'agentscore-pay' | 'both';
+}
+/** Canonical config for the x402 EVM (Base) rail. */
+interface X402BaseRailSpec {
+    recipient: RecipientLike;
+    /** CAIP-2 canonical, e.g. `eip155:8453`. */
+    network?: string;
+    chainId?: number;
+    token?: string;
+    symbol?: string;
+    decimals?: number;
+    mode?: 'exact' | 'upto';
+}
+/**
+ * Canonical config for the Solana MPP rail.
+ *
+ * `signer` is an optional fee-payer signer for server-side fee sponsorship —
+ * typed as `unknown` to avoid hard-importing `@solana/kit` types here. Pass any
+ * `TransactionPartialSigner`.
+ */
+interface SolanaMppRailSpec {
+    recipient: RecipientLike;
+    network?: string;
+    token?: string;
+    symbol?: string;
+    decimals?: number;
+    rpcUrl?: string;
+    signer?: unknown;
+    tokenProgram?: string;
+}
+/**
+ * Canonical config for the Stripe SPT rail.
+ *
+ * `recipient` is intentionally absent — Stripe rails use `profileId` as the
+ * merchant-side network identifier the agent's SPT is scoped to; the
+ * transaction recipient is the merchant's Stripe account, not an on-chain
+ * address.
+ */
+interface StripeRailSpec {
+    profileId?: string | null;
+    rails?: ('card' | 'link' | 'shared_payment_token')[];
+    paymentMethodTypes?: string[];
+    productName?: string;
+    secretKey?: string;
+}
+/**
+ * Canonical config for the Tempo session MPP rail (pay-as-you-go channels).
+ *
+ * `escrowContract` is the merchant-deployed on-chain escrow that holds channel
+ * deposits + pays out cumulative vouchers on settlement. `store` is a
+ * `ChannelStore` instance — typed as `unknown` to avoid hard-importing `mppx`'s
+ * store interface here.
+ */
+interface TempoSessionRailSpec {
+    recipient: RecipientLike;
+    escrowContract: string;
+    store: unknown;
+    currency?: string;
+    testnet?: boolean;
+    chains?: unknown;
+}
+/**
+ * Default field values for each `*RailSpec`. Mirrors python-commerce's
+ * `*RailSpec` dataclass defaults — callers can spread these into their spec
+ * literal when they want defaults without typing them out. Sourced from the
+ * USDC registry so they stay in sync with on-chain reality.
+ */
+declare const RAIL_SPEC_DEFAULTS: {
+    readonly tempo: {
+        readonly network: "tempo-mainnet";
+        readonly chainId: 4217;
+        readonly token: "0x20C000000000000000000000b9537d11c60E8b50";
+        readonly symbol: "USDC.e";
+        readonly decimals: 6;
+        readonly testnet: false;
+        readonly recommend: "both";
+    };
+    readonly x402Base: {
+        readonly network: "eip155:8453";
+        readonly chainId: 8453;
+        readonly token: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+        readonly symbol: "USDC";
+        readonly decimals: 6;
+        readonly mode: "exact";
+    };
+    readonly solanaMpp: {
+        readonly network: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+        readonly token: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+        readonly symbol: "USDC";
+        readonly decimals: 6;
+    };
+    readonly stripe: {
+        readonly rails: ("card" | "link" | "shared_payment_token")[];
+    };
+    readonly tempoSession: {
+        readonly currency: "0x20C000000000000000000000b9537d11c60E8b50";
+        readonly testnet: false;
+    };
+};
+
+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 };