@agent-score/commerce 2.0.1 → 2.1.0

package/dist/default_rails-BxBzcCA1.d.ts

@@ -0,0 +1,188 @@
+import { a as RecipientLike, T as TempoRailSpec, X as X402BaseRailSpec, S as SolanaMppRailSpec, b as StripeRailSpec } from './rail_spec-D6qzh3J0.js';
+
+/** Detects whether a request is a "settle leg" (carries a payment credential)
+ *  vs a "discovery leg" (no payment credential, expects a 402).
+ *
+ *  Used by the gate-conditional mount pattern documented in CLAUDE.md: mount
+ *  `agentscoreGate` on a route only when payment is being attempted, so the
+ *  discovery leg flows through unauthenticated and gets a 402 with all rails.
+ *
+ *  Three credential channels are checked:
+ *   - `Payment-Signature` — MPP credentials (Tempo, Solana, Stripe SPT)
+ *   - `X-Payment` — x402 v1 EIP-3009 credentials
+ *   - `Authorization: Payment <jwt>` — x402 v2 / paymentauth.org credentials
+ */
+type WebHeaders = {
+    get(name: string): string | null;
+};
+type RecordHeaders = Record<string, string | string[] | undefined>;
+type HeadersLike = WebHeaders | RecordHeaders | Headers;
+declare function readHeader(headers: HeadersLike, name: string): string | null;
+declare function asHeaders(input: Request | HeadersLike): HeadersLike;
+/** True when the request carries any of the payment-credential headers we
+ *  recognize. Accepts a Web Fetch `Headers`, a Web Fetch `Request` (uses
+ *  `request.headers`), or a plain header record (Express/Fastify-shaped).
+ *
+ *  Use this to gate the `agentscoreGate` middleware so anonymous discovery
+ *  legs flow through and get a 402 with all rails. See CLAUDE.md
+ *  "Anonymous discovery" pattern.
+ */
+declare function hasPaymentHeader(input: Request | HeadersLike): boolean;
+/** True when the request carries an x402 payment credential (`X-Payment` or
+ *  `Payment-Signature`). Use to dispatch to the x402 settle path. */
+declare function hasX402Header(input: Request | HeadersLike): boolean;
+/** True when the request carries an mppx payment credential
+ *  (`Authorization: Payment <jwt>`). Use to dispatch to the MPP settle path. */
+declare function hasMppxHeader(input: Request | HeadersLike): boolean;
+
+/**
+ * USD ↔ atomic-unit conversion for token amounts.
+ *
+ * `usdToAtomic(usd, { decimals: 6 })` returns the bigint atomic value of a USD
+ * amount for a token with `decimals` places of precision (USDC is 6). String
+ * parsing + bigint arithmetic so the result is exact; ROUND_HALF_UP at the
+ * rounding boundary matches the cross-language Python sibling.
+ *
+ * Rejects negative, NaN, infinite, and unparseable inputs. Fixed-notation only;
+ * scientific notation (e.g. `"1e6"`) is not parsed (mirrors the locked cross-
+ * language fixture corpus, which uses fixed notation exclusively).
+ */
+/**
+ * Convert a USD amount to atomic units for a token with `decimals` places.
+ *
+ * @param usd USD amount. Strings (`"1.23"`) and `number`s (`1.23`) are accepted.
+ *   `number` is converted via `String(usd)` before parsing, so JS float precision
+ *   limits apply when the float can't represent the value exactly.
+ * @param opts.decimals Number of decimal places in the atomic unit (6 for USDC,
+ *   18 for ETH, etc.). Must be a non-negative integer.
+ *
+ * @returns Integer atomic units as a `bigint`. `"1.23"` with `decimals: 6`
+ *   returns `1_230_000n`.
+ *
+ * @throws RangeError when `usd` is negative, NaN, infinite, or `decimals` is
+ *   not a non-negative integer.
+ * @throws SyntaxError when `usd` cannot be parsed as a fixed-notation decimal.
+ */
+declare function usdToAtomic(usd: string | number, opts: {
+    decimals: number;
+}): bigint;
+/**
+ * Format an integer cent amount as a fixed-2-decimal USD string.
+ *
+ * `formatUsdCents(500)` returns `"5.00"`. Negative values are formatted with a
+ * leading minus. Use everywhere a merchant emits `(cents / 100).toFixed(2)`;
+ * consistent formatting across catalog rows, order responses, and 402 bodies
+ * prevents agent-side string-comparison flakiness.
+ *
+ * `decimals` controls the dollar-precision of the output and defaults to `2`
+ * (canonical USD cents). Raise it for sub-cent unit pricing — e.g.
+ * `formatUsdCents(0.05, 4)` returns `"0.0005"` for a half-of-one-millicent
+ * amount. The `cents` input is allowed to be fractional so per-token /
+ * per-byte pricing models can compute `priceCents = unitPriceCents × n`
+ * without rounding before reaching the formatter.
+ */
+declare function formatUsdCents(cents: number, decimals?: number): string;
+
+/**
+ * Solana MPP fee-payer signer loader.
+ *
+ * Buyers paying via Solana MPP USDC don't typically carry SOL for transaction
+ * fees, so merchants commonly co-sign the buyer's `solana/charge` tx as the
+ * fee payer (~5000 lamports per tx; negligible vs the USDC value moved).
+ *
+ * `loadSolanaFeePayer({ privateKey })` accepts a Solana keypair in any of the
+ * three forms agents commonly export it as:
+ *
+ *   - **base58** (Phantom export format) — 64-byte secret+public, or 32-byte
+ *     secret-only
+ *   - **hex** — 128-char string (64 bytes hex: 32-byte secret + 32-byte public)
+ *
+ * Returns a `KeyPairSigner` from `@solana/kit` ready to pass as the `signer`
+ * field on a `SolanaMppRailSpec`. Returns `undefined` when `privateKey` is
+ * empty / absent (so consumers can use `process.env.X` directly without
+ * null-checks).
+ *
+ * Requires the `@solana/kit` peer dependency.
+ */
+declare function loadSolanaFeePayer(opts: {
+    privateKey: string | undefined;
+}): Promise<unknown | undefined>;
+
+/** Builder for the `compose(...intents)` array passed to mppx in a merchant's
+ *  custom `composeMppx` hook. Replaces the hand-rolled `composeRails`
+ *  assembly that recurs verbatim across every multi-rail merchant (sayer,
+ *  martin, sandbox).
+ *
+ *  The intent shape is mppx-protocol-shaped; this helper just spares callers
+ *  from re-typing the same atomic-conversion + per-rail object literal.
+ */
+interface BuildMppxComposeRailsOptions {
+    /** USD price string (e.g. `'1.50'`). Tempo + Stripe consume it verbatim;
+     *  Solana converts to atomic units (`bigint`) per its scheme. */
+    amountUsd: string;
+    /** Tempo recipient address. When omitted, the `tempo/charge` intent is
+     *  not emitted (e.g., merchant with no Tempo rail configured). */
+    tempoRecipient?: string;
+    /** Tempo USDC contract address. Defaults to USDC.tempo.mainnet.address. */
+    tempoTokenAddress?: string;
+    /** Solana recipient address. When omitted, the `solana/charge` intent is
+     *  not emitted (e.g., per-order Stripe-multichain merchant that didn't
+     *  mint a Solana deposit address). */
+    solanaRecipient?: string;
+    /** Solana USDC mint. Defaults to USDC.solana.mainnet.mint. */
+    solanaTokenMint?: string;
+    /** Solana CAIP-2 network. Defaults to mainnet-beta. */
+    solanaNetwork?: string;
+    /** Include the `stripe/charge` intent (Stripe SPT rail). Default `true`. */
+    includeStripe?: boolean;
+}
+/** Build the `compose(...intents)` argument array. Order matches mppx's
+ *  preferred ordering: tempo first (cheapest), then solana, then stripe.
+ *
+ *  Throws when Solana is requested but `amountUsd` can't convert to atomic
+ *  (e.g., empty string, NaN); merchants should catch and return `{status: 402}`
+ *  to drop the rail rather than crash the request.
+ */
+declare function buildMppxComposeRails(opts: BuildMppxComposeRailsOptions): unknown[];
+
+/** Boilerplate-reducer for the `rails` config passed to `Checkout` /
+ *  `computeFirstCheckout`. Merchants supplying a chain set always rebuild the
+ *  same constants (`recipient: ''` sentinel, network/chainId/token defaults);
+ *  this helper folds those defaults in so the merchant config only specifies
+ *  the merchant-specific overrides.
+ *
+ *  Per-order recipient minting (Stripe-multichain) is wired via the Checkout's
+ *  `mintRecipients` hook, so the `recipient: ''` sentinel here is the expected
+ *  shape — `mintRecipients` overrides it at request time.
+ */
+
+interface BuildDefaultCheckoutRailsOptions {
+    /** Tempo MPP rail. Pass `{}` to accept all defaults; pass overrides
+     *  (`network`, `chainId`, `token`, ...) to customize. Omit to skip. */
+    tempo?: {
+        recipient?: RecipientLike;
+    } & Partial<Omit<TempoRailSpec, 'recipient'>>;
+    /** x402 EVM (Base) rail. Same opt-in semantics. */
+    x402Base?: {
+        recipient?: RecipientLike;
+    } & Partial<Omit<X402BaseRailSpec, 'recipient'>>;
+    /** Solana MPP rail. Same opt-in semantics. */
+    solanaMpp?: {
+        recipient?: RecipientLike;
+    } & Partial<Omit<SolanaMppRailSpec, 'recipient'>>;
+    /** Stripe SPT rail. No recipient (Stripe owns the deposit address). */
+    stripe?: Partial<StripeRailSpec>;
+}
+type DefaultRails = {
+    tempo?: TempoRailSpec;
+    x402_base?: X402BaseRailSpec;
+    solana_mpp?: SolanaMppRailSpec;
+    stripe?: StripeRailSpec;
+};
+/** Build the canonical four-rail `rails` dict. Keys match the convention used
+ *  across consumer codebases (`tempo`, `x402_base`, `solana_mpp`, `stripe`).
+ *  Empty-string recipients are placeholders — Checkout's `mintRecipients` hook
+ *  must populate real values at request time. */
+declare function buildDefaultCheckoutRails(opts: BuildDefaultCheckoutRailsOptions): DefaultRails;
+
+export { type BuildDefaultCheckoutRailsOptions as B, type HeadersLike as H, type BuildMppxComposeRailsOptions as a, asHeaders as b, buildDefaultCheckoutRails as c, buildMppxComposeRails as d, hasPaymentHeader as e, formatUsdCents as f, hasX402Header as g, hasMppxHeader as h, loadSolanaFeePayer as l, readHeader as r, usdToAtomic as u };

package/dist/discovery/index.d.mts

@@ -1,10 +1,10 @@
-import { R as RailKey, C as CompatibleClients } from '../pricing-CxzwyiO6.mjs';
-export { g as compatibleClientsByRails } from '../pricing-CxzwyiO6.mjs';
-import { C as Checkout, r as UCPServiceBinding, b as AgentScoreGatePolicy } from '../checkout-BN5i1Fi7.mjs';
-import '../rail_spec-XP0wKgJV.mjs';
+import { R as RailKey, C as CompatibleClients } from '../pricing-4n5Ota0D.mjs';
+export { g as compatibleClientsByRails } from '../pricing-4n5Ota0D.mjs';
+import { C as Checkout, q as UCPServiceBinding, a as AgentScoreGatePolicy } from '../checkout-Bd_4aQ6c.mjs';
+import '../rail_spec-D6qzh3J0.mjs';
 import '../core.mjs';
 import '../signer-3FAit11j.mjs';
-import '../x402_server-hgQzWQwB.mjs';
+import '../x402_server-Ciz2mls2.mjs';
 
 /**
  * Build a sample x402 accepts entry for a CAIP-2 network. Looks up the USDC asset

package/dist/discovery/index.d.ts

@@ -1,10 +1,10 @@
-import { R as RailKey, C as CompatibleClients } from '../pricing-CQ9DIFaw.js';
-export { g as compatibleClientsByRails } from '../pricing-CQ9DIFaw.js';
-import { C as Checkout, r as UCPServiceBinding, b as AgentScoreGatePolicy } from '../checkout-B1JuEcbx.js';
-import '../rail_spec-XP0wKgJV.js';
+import { R as RailKey, C as CompatibleClients } from '../pricing-DHfH3ogG.js';
+export { g as compatibleClientsByRails } from '../pricing-DHfH3ogG.js';
+import { C as Checkout, q as UCPServiceBinding, a as AgentScoreGatePolicy } from '../checkout-BH-I_Ns8.js';
+import '../rail_spec-D6qzh3J0.js';
 import '../core.js';
 import '../signer-3FAit11j.js';
-import '../x402_server-hgQzWQwB.js';
+import '../x402_server-Ciz2mls2.js';
 
 /**
  * Build a sample x402 accepts entry for a CAIP-2 network. Looks up the USDC asset

package/dist/discovery/index.js

@@ -1224,6 +1224,19 @@ ${bodyRulesSection}
 ${peerSection}`;
 }
 
+// src/payment/network_kind.ts
+function readNetwork(input) {
+  if (typeof input === "string") return input;
+  if (input && typeof input === "object") {
+    const network = input.network;
+    return typeof network === "string" ? network : "";
+  }
+  return "";
+}
+function isSolanaNetwork(input) {
+  return readNetwork(input).startsWith("solana:");
+}
+
 // src/identity/ucp.ts
 function ucpSigningKeyFromJWKImpl(jwk) {
   if (!jwk || typeof jwk !== "object") {
@@ -1390,7 +1403,7 @@ function isTempoSessionRailSpec(s) {
 }
 function mppRailToNetworkEntry(spec) {
   if (isTempoSessionRailSpec(spec)) return tempoSessionToNetworkEntry(spec);
-  if ("rpcUrl" in spec || "tokenProgram" in spec || (spec.network?.startsWith("solana:") ?? false)) {
+  if ("rpcUrl" in spec || "tokenProgram" in spec || isSolanaNetwork(spec)) {
     return solanaMppToNetworkEntry(spec);
   }
   if (isTempoRailSpec(spec)) return tempoToNetworkEntry(spec);