@agent-score/commerce 1.8.1 → 2.0.1

package/dist/checkout-B1JuEcbx.d.ts

@@ -0,0 +1,939 @@
+import { T as TempoRailSpec, S as SolanaMppRailSpec, a as TempoSessionRailSpec, b as StripeRailSpec, X as X402BaseRailSpec } from './rail_spec-XP0wKgJV.js';
+import { P as PricingBlock, R as RailKey } from './pricing-CQ9DIFaw.js';
+import { CreateSessionOnMissing, AgentScoreCoreOptions, DenialReason } from './core.js';
+import { X as X402Server } from './x402_server-hgQzWQwB.js';
+
+/**
+ * UCP (Universal Commerce Protocol) profile builder.
+ *
+ * Compose the JSON payload published at `/.well-known/ucp` per the UCP spec.
+ * Output shape matches the spec example: top-level `{ ucp: {...}, signing_keys: [...] }`
+ * envelope, with `services` / `capabilities` / `payment_handlers` as MAPs keyed by
+ * reverse-DNS service / capability / handler name.
+ *
+ * AgentScore identity claims layer over UCP via the `sh.agentscore.identity` capability
+ * (vendor-namespaced; UCP doesn't define KYC/sanctions/age/jurisdiction natively). The
+ * capability extends `dev.ucp.shopping.checkout` AND `dev.ucp.shopping.cart` (multi-parent,
+ * the standard pattern UCP allows for capabilities that compose multiple parents).
+ *
+ * The unsigned profile body returned here is what merchants publish; pass it through
+ * `signUCPProfile` to attach the `agentscore-profile+jws` signature for trust-mode
+ * verifiers (vendor extension; UCP itself doesn't mandate profile-body signing).
+ *
+ * Spec reference: https://ucp.dev/
+ */
+/**
+ * UCP per-element shape note: each binding interface (`UCPServiceBinding`,
+ * `UCPCapabilityBinding`, `UCPPaymentHandlerBinding`) carries the canonical UCP fields
+ * plus arbitrary vendor extras flat on the same object via `[k: string]: unknown`. The
+ * python sibling models these as dataclasses with an explicit `extras: dict` field. Both
+ * designs offer equivalent guarantees through different mechanisms.
+ */
+
+/**
+ * Construct a UCPSigningKey from a public JWK dict (e.g. the `publicJWK` returned by
+ * `generateUCPSigningKey()`). Validates required fields and rejects symmetric keys that
+ * can't publicly verify a JWS in trust-mode UCP. Mirrors python's
+ * `UCPSigningKey.from_jwk(public_jwk)` classmethod via the `UCPSigningKey.fromJWK`
+ * static-method-style namespace export below.
+ */
+declare function ucpSigningKeyFromJWKImpl(jwk: Record<string, unknown>): UCPSigningKey;
+interface UCPSigningKey {
+    /** JWK kid (key id). */
+    kid: string;
+    /** JWK kty (key type) — `EC`, `RSA`, or `OKP`. */
+    kty: string;
+    /** JWK alg (signing algorithm) — `ES256`, `RS256`, or `EdDSA`. */
+    alg?: string;
+    /** JWK use, typically `sig`. */
+    use?: string;
+    /** JWK crv (curve) for EC / OKP keys. */
+    crv?: string;
+    /** JWK x / y / n / e / etc. The full key material; passed through verbatim. */
+    [k: string]: unknown;
+}
+/** Static-method-style namespace on the `UCPSigningKey` interface — mirrors python's
+ *  `UCPSigningKey.from_jwk(jwk)` classmethod. Use as `UCPSigningKey.fromJWK(jwk)`. */
+declare const UCPSigningKey: {
+    fromJWK: typeof ucpSigningKeyFromJWKImpl;
+};
+/** Transport binding — keyed under a service name (e.g., `dev.ucp.shopping`). */
+interface UCPServiceBinding {
+    /** Spec version, YYYY-MM-DD per UCP convention. REQUIRED. */
+    version: string;
+    /** URL to human-readable specification. REQUIRED. */
+    spec: string;
+    /** Transport — `rest` / `mcp` / `a2a` / `embedded`. REQUIRED. */
+    transport: 'rest' | 'mcp' | 'a2a' | 'embedded';
+    /** Endpoint URL — required for rest/mcp; A2A points at the agent-card.json URL. */
+    endpoint?: string;
+    /** URL to JSON Schema — required for rest/mcp/embedded per spec. */
+    schema?: string;
+    /** Optional id for entity-instance disambiguation. */
+    id?: string;
+    /** Entity-specific config. */
+    config?: Record<string, unknown>;
+    /** Vendor-specific extras. */
+    [k: string]: unknown;
+}
+/** Capability binding — keyed under a capability name (e.g., `dev.ucp.shopping.checkout`). */
+interface UCPCapabilityBinding {
+    /** Capability version, YYYY-MM-DD. REQUIRED. */
+    version: string;
+    /** URL to human-readable specification. REQUIRED. */
+    spec: string;
+    /** URL to JSON Schema. REQUIRED. */
+    schema: string;
+    /** Optional id for entity-instance disambiguation. */
+    id?: string;
+    /** Entity-specific config (feature flags, callback URLs, etc). */
+    config?: Record<string, unknown>;
+    /** Parent capability(ies) extended — single string or array for multi-parent. */
+    extends?: string | string[];
+    /** Optional version requirements per UCP §6.5. */
+    requires?: {
+        protocol?: {
+            min: string;
+            max?: string;
+        };
+        capabilities?: Record<string, {
+            min: string;
+            max?: string;
+        }>;
+    };
+    /** Vendor-specific extras allowed per UCP convention (e.g., the AgentScore identity
+     *  capability adds a vendor-namespaced policy declaration here). */
+    [k: string]: unknown;
+}
+/** Payment handler binding — keyed under a handler reverse-DNS name (e.g., `com.google.pay`). */
+interface UCPPaymentHandlerBinding {
+    /** Handler instance id (short, human-readable, e.g., `gpay`, `tempo`, `x402`). REQUIRED. */
+    id: string;
+    /** Handler spec version, YYYY-MM-DD. REQUIRED. */
+    version: string;
+    /** URL to handler spec. REQUIRED. */
+    spec: string;
+    /** URL to handler config schema. REQUIRED. */
+    schema: string;
+    /** Available instruments — type + per-type constraints (cards, wallets, etc.). */
+    available_instruments?: Array<{
+        type: string;
+        constraints?: Record<string, unknown>;
+        [k: string]: unknown;
+    }>;
+    /** Handler config — gateway IDs, merchant IDs, public keys, etc. */
+    config?: Record<string, unknown>;
+    /** Vendor-specific extras. */
+    [k: string]: unknown;
+}
+/** UCP body — nested under the `ucp` key of the published profile. */
+interface UCPProfileBody {
+    /** UCP spec version (YYYY-MM-DD). */
+    version: string;
+    /** Display name for the merchant / agent surface. */
+    name?: string;
+    /** Services — keyed by service name (e.g., `dev.ucp.shopping`). Each value is an
+     *  array of transport bindings (one merchant typically advertises multiple transports
+     *  under one service name). */
+    services: Record<string, UCPServiceBinding[]>;
+    /** Capabilities — keyed by capability name (e.g., `dev.ucp.shopping.checkout`). */
+    capabilities: Record<string, UCPCapabilityBinding[]>;
+    /** Payment handlers — keyed by handler reverse-DNS name (e.g., `com.google.pay`). */
+    payment_handlers: Record<string, UCPPaymentHandlerBinding[]>;
+    /** Optional `supported_versions` map linking historical version-specific profile URLs.
+     *  Pattern: `{ "2026-01-23": "https://merchant/.well-known/ucp/2026-01-23", ... }`. */
+    supported_versions?: Record<string, string>;
+    /** Vendor-specific extras inside the `ucp` envelope. */
+    [k: string]: unknown;
+}
+/** Full UCP profile body as published at `/.well-known/ucp`. Top-level shape:
+ *  `{ ucp: {...}, signing_keys: [...], signature?: "..." }`. */
+interface UCPProfile {
+    /** UCP body. ALL UCP-spec fields nest here per spec. */
+    ucp: UCPProfileBody;
+    /** JWKS — public keys at the OUTER level per UCP spec. Verifiers fetch this profile,
+     *  match the kid from a JWS / RFC 9421 signature header against this list, and validate. */
+    signing_keys: UCPSigningKey[];
+    /** Set when JWS-signed via `signUCPProfile` — JWS Compact Serialization with detached
+     *  payload (header..signature; payload is the canonicalized body minus this field). */
+    signature?: string;
+    /** Top-level vendor-specific extras (outside the `ucp` envelope). */
+    [k: string]: unknown;
+}
+interface BuildUCPProfileInput {
+    /** UCP spec version. Default `'2026-04-08'` (the latest published UCP spec date). MUST match a published UCP spec version, not a free-form date. */
+    version?: string;
+    /** Display name for the merchant / agent surface. */
+    name?: string;
+    /** Services map, keyed by service name. UCP-shopping merchants typically advertise
+     *  bindings under `'dev.ucp.shopping'`. */
+    services?: Record<string, UCPServiceBinding[]>;
+    /** Capabilities map, keyed by capability name. The `sh.agentscore.identity` capability
+     *  is auto-added when `agentscore_gate` is provided. */
+    capabilities?: Record<string, UCPCapabilityBinding[]>;
+    /** Payment handlers map, keyed by handler reverse-DNS name. */
+    payment_handlers?: Record<string, UCPPaymentHandlerBinding[]>;
+    /** JWKS — public keys the merchant signs with. REQUIRED by spec. */
+    signing_keys: UCPSigningKey[];
+    /** Merchant gate policy declaration. When provided, the SDK auto-injects an
+     *  `sh.agentscore.identity` capability binding into `capabilities`, with the
+     *  policy as the binding's `config`. Static merchant declaration only — no
+     *  per-operator data ever ends up on the public profile. Per-operator identity
+     *  attestation lives on the AP2 risk-signal endpoint, not here. */
+    agentscore_gate?: AgentScoreGatePolicy;
+    /** Optional override for the AgentScore capability schema URL. Field is snake_cased
+     *  for cross-language parity with the Python sibling. */
+    agentscore_schema_url?: string;
+    /** Optional override for the AgentScore capability spec URL. */
+    agentscore_spec_url?: string;
+    /** `supported_versions` map at the profile root for backwards-compat across
+     *  spec dates. Pattern: `{ "<date>": "<base>/.well-known/ucp/<date>" }`. */
+    supported_versions?: Record<string, string>;
+    /** Vendor-specific extras at the OUTER level (alongside `ucp` + `signing_keys`). */
+    extras?: Record<string, unknown>;
+    /** Vendor-specific extras INSIDE the `ucp` envelope (alongside `version`, `services`, etc.). */
+    ucp_extras?: Record<string, unknown>;
+}
+/** Merchant gate policy declared on the UCP profile via `sh.agentscore.identity` capability config.
+ *  All fields optional; merchant declares which AgentScore checks the gate enforces. Snake-case
+ *  field names match the AgentScore API's `/v1/assess` policy contract verbatim — no conversion
+ *  layer between this declaration and what the gate actually enforces at runtime. */
+interface AgentScoreGatePolicy {
+    /** Gate denies if the operator/account behind the agent is not Stripe-Identity-verified. */
+    require_kyc?: boolean;
+    /** Gate denies if the operator/account is flagged by OpenSanctions screening. */
+    require_sanctions_clear?: boolean;
+    /** Gate denies if the verified age (from KYC) is below this threshold. Common values: 18, 21. */
+    min_age?: number;
+    /** ISO-3166-1 alpha-2 country codes the gate accepts. Empty/absent allows any. Mutually exclusive
+     *  with `blocked_jurisdictions` (set one or the other, not both). */
+    allowed_jurisdictions?: string[];
+    /** ISO-3166-1 alpha-2 country codes the gate denies. Empty/absent denies none. Mutually exclusive
+     *  with `allowed_jurisdictions`. */
+    blocked_jurisdictions?: string[];
+}
+/**
+ * Compose a UCP profile body for `/.well-known/ucp` publication. Returns the spec-
+ * compliant shape: `{ ucp: { version, services, capabilities, payment_handlers, ... },
+ * signing_keys: [...] }`. Pass through `signUCPProfile` to attach a JWS signature for
+ * trust-mode verifiers.
+ *
+ * Auto-injects `sh.agentscore.identity` as a vendor capability extending both
+ * `dev.ucp.shopping.checkout` and `dev.ucp.shopping.cart` when `agentscore_gate`
+ * is provided. The capability's `config` carries the merchant's static gate
+ * policy declaration (require_kyc / require_sanctions_clear / min_age /
+ * allowed_jurisdictions / blocked_jurisdictions). NO per-operator data is ever
+ * placed on the public profile — per-operator identity attestation flows through
+ * the AP2 risk-signal endpoint, not here.
+ *
+ * Example:
+ * ```ts
+ * import { buildUCPProfile } from '@agent-score/commerce';
+ *
+ * const profile = buildUCPProfile({
+ *   name: 'Example Merchant',
+ *   services: {
+ *     'dev.ucp.shopping': [
+ *       { version: '2026-04-08', spec: 'https://ucp.dev/2026-04-08/specification/overview',
+ *         transport: 'mcp', endpoint: 'https://merchant.example/api/ucp/mcp',
+ *         schema: 'https://ucp.dev/services/shopping/mcp.openrpc.json' },
+ *     ],
+ *   },
+ *   payment_handlers: {
+ *     ...mppPaymentHandler({ networks: [{ network: 'tempo-mainnet', chain_id: 4217, recipient: TEMPO_ADDR }] }),
+ *   },
+ *   signing_keys: [signingKey],
+ *   agentscore_gate: { require_kyc: true, min_age: 21, allowed_jurisdictions: ['US'] },
+ * });
+ * ```
+ */
+declare function buildUCPProfile(input: BuildUCPProfileInput): UCPProfile;
+declare const AGENTSCORE_UCP_CAPABILITY = "sh.agentscore.identity";
+type MppRailSpec = TempoRailSpec | SolanaMppRailSpec | TempoSessionRailSpec;
+/**
+ * Build the `sh.agentscore.payment.mpp` payment handler block for a UCP profile.
+ *
+ * Pass any mix of `TempoRailSpec`, `SolanaMppRailSpec`, and `TempoSessionRailSpec`.
+ *
+ * @example
+ * ```ts
+ * buildUCPProfile({
+ *   ...,
+ *   payment_handlers: {
+ *     ...mppPaymentHandler({
+ *       networks: [
+ *         { recipient: '0xtempo' },        // TempoRailSpec
+ *         { recipient: 'solanaaddr', network: 'solana:5eykt4...' },  // SolanaMppRailSpec
+ *       ],
+ *     }),
+ *   },
+ * });
+ * ```
+ */
+declare function mppPaymentHandler({ networks, }: {
+    networks: MppRailSpec[];
+}): Record<string, UCPPaymentHandlerBinding[]>;
+/**
+ * Build the `sh.agentscore.payment.x402` payment handler block for a UCP profile.
+ *
+ * @example
+ * ```ts
+ * buildUCPProfile({
+ *   ...,
+ *   payment_handlers: {
+ *     ...x402PaymentHandler({ networks: [{ recipient: '0xabc...' }] }),
+ *   },
+ * });
+ * ```
+ */
+declare function x402PaymentHandler({ networks, }: {
+    networks: X402BaseRailSpec[];
+}): Record<string, UCPPaymentHandlerBinding[]>;
+/**
+ * Build the `sh.agentscore.payment.stripe_spt` payment handler block for a UCP profile.
+ *
+ * @example
+ * ```ts
+ * buildUCPProfile({
+ *   ...,
+ *   payment_handlers: {
+ *     ...stripeSptPaymentHandler({ spec: { profileId: 'profile_5xKvNqM9BaH' } }),
+ *   },
+ * });
+ * ```
+ */
+declare function stripeSptPaymentHandler({ spec, }: {
+    spec: StripeRailSpec;
+}): Record<string, UCPPaymentHandlerBinding[]>;
+
+/**
+ * High-level Checkout orchestrator — composes 402-emit + verify+settle.
+ *
+ * The Checkout primitive collapses the agent-commerce dance (emit 402 →
+ * verify+settle on retry → respond) into a single `await checkout.handle(request)`
+ * call. It services every merchant shape:
+ *
+ * - **Goods sellers** wire inventory hooks (`onSettled` persists the order;
+ *   `mintRecipients` mints per-order Stripe-multichain addresses).
+ * - **API sellers** wire per-call billing (`computePricing` returns a fixed
+ *   amount; `onSettled` returns the inline API response body).
+ * - **Self-custody-only merchants** configure chain rails (Tempo / Base / Solana)
+ *   via `X402BaseRailSpec` / `TempoRailSpec` / `SolanaMppRailSpec`.
+ * - **Custodial-only merchants** configure `StripeRailSpec` and skip the chain
+ *   rails — Stripe SPT settles via the same `composeMppx` hook.
+ * - **Multi-rail merchants** configure all of the above; the agent picks the rail.
+ *
+ * Three flexibility axes — every combination is supported:
+ *
+ * - **x402 only / MPP only / both** — Checkout works with `x402Server` alone,
+ *   `composeMppx` alone, or both. Whichever payment header arrives is dispatched
+ *   to the configured handler; the other path is simply absent.
+ * - **Self-custody / Stripe / mixed** — rails dict is the single source of truth.
+ *   Listing `StripeRailSpec` makes Stripe SPT an acceptable rail; omitting it
+ *   makes the merchant chain-only. Mixing freely is the default.
+ * - **Gated / ungated identity** — `CheckoutRequest.assess` is optional. Merchants
+ *   who run AgentScoreGate upstream pass its result through; merchants running
+ *   anonymous leave it `null`.
+ *
+ * Domain-neutral by design: every per-request value is keyed by `referenceId`
+ * (a UUID minted on first contact). Goods merchants persist this as their order
+ * id; API merchants treat it as a per-call request id.
+ */
+
+type CheckoutRailSpec = TempoRailSpec | X402BaseRailSpec | SolanaMppRailSpec | StripeRailSpec | TempoSessionRailSpec;
+/**
+ * Framework-neutral HTTP request input to `Checkout.handle`.
+ *
+ * Merchants build this from their framework's request object once; the
+ * Checkout layer then runs the same flow regardless of Hono / Express / Next /
+ * Fastify / raw Web Fetch.
+ */
+interface CheckoutRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+    /** Parsed JSON body. For non-JSON endpoints, pass `{}` and stash the raw bytes elsewhere. */
+    body: Record<string, unknown>;
+    /** Optional assess block from the gate (operator/wallet identity, signer verdicts).
+     *
+     *  When present, hooks can branch on identity (e.g. KYC-only pricing). When absent,
+     *  the merchant is either running pre-gate (anonymous discovery) or chose to skip
+     *  the gate for this endpoint. */
+    assess?: Record<string, unknown> | null;
+    /** Optional escape hatch for the framework's native request object. Pass when
+     *  your `composeMppx` hook needs to call `mppx.compose(...)(rawRequest)` — mppx's
+     *  compose binds to the raw HTTP request, so the orchestrator forwards this
+     *  through unchanged. */
+    raw?: unknown;
+}
+/** Output of `Checkout.computePricing` — per-request pricing. */
+interface PricingResult {
+    /** Total to charge in USD (or the upper bound, for `mode: 'upto'` rails). */
+    amountUsd: number;
+    currency?: string;
+    /** Optional pre-built `PricingBlock`. When omitted, Checkout builds a minimal
+     *  block from `amountUsd` so the 402 body always carries pricing metadata. */
+    block?: PricingBlock;
+    /** Optional product block surfaced in the 402 body's `product` field. Goods
+     *  merchants populate `{id, name, slug, list_price_usd, ...}`; API sellers leave
+     *  this absent since per-call billing has no product concept. */
+    product?: Record<string, string>;
+    /** Optional merchant-specific fields merged into the 402 body alongside the
+     *  standard `accepted_methods` / `agent_instructions` / `pricing` blocks.
+     *  Useful for `redemption_code_applied`, coupon hints, or any other field the
+     *  merchant wants the agent to see in the challenge body. */
+    bodyExtras?: Record<string, unknown>;
+}
+/**
+ * Build a {@link PricingResult} from cents-denominated inputs.
+ *
+ * Saves the `{ amountUsd: ..., block: buildPricingBlock({...}) }` dance every
+ * US-commerce merchant repeats. When `subtotalCents` is set:
+ *
+ * - `subtotalCents` is the list price (pre-discount). `discountCents` is the
+ *   deduction applied (redemption code / coupon / promo).
+ * - `amountUsd` is derived from `(subtotal + tax + shipping - discount) / 100`
+ *   (floored at 0) unless explicitly provided.
+ * - A {@link PricingBlock} is built via {@link buildPricingBlock} and attached
+ *   to the result's `block` field. `discount` is surfaced as a dollar-string
+ *   when `discountCents` is supplied.
+ *
+ * When `subtotalCents` is omitted, the function passes through to the raw
+ * `PricingResult` shape; `amountUsd` is then required.
+ *
+ * Use this in `computePricing` hooks instead of hand-rolling:
+ *
+ * @example
+ * computePricing: async (ctx) => pricingResult({
+ *   subtotalCents: 25000,
+ *   taxCents: 2000,
+ *   taxRate: 0.08,
+ *   taxState: 'CA',
+ * }),
+ *
+ * @example
+ * // Redemption-code applied (free order, agent sees the savings line):
+ * computePricing: async (ctx) => pricingResult({
+ *   subtotalCents: 7500,
+ *   discountCents: 7500,
+ * }),
+ */
+declare function pricingResult(opts: {
+    subtotalCents?: number;
+    taxCents?: number;
+    shippingCents?: number;
+    discountCents?: number;
+    taxRate?: number;
+    taxState?: string;
+    currency?: string;
+    amountUsd?: number;
+    product?: Record<string, string>;
+    bodyExtras?: Record<string, unknown>;
+}): PricingResult;
+/**
+ * Per-route discovery-probe config. When passed to {@link Checkout}, any
+ * empty-body POST without a payment credential short-circuits with a sample
+ * 402 advertising the merchant's payment shape — the canonical pattern x402
+ * crawlers (`awal x402 details`, `x402-proxy`, `x402scan`) rely on.
+ *
+ * Mirrors python's `DiscoveryProbeConfig` dataclass.
+ */
+interface DiscoveryProbeConfig {
+    realm: string;
+    sampleRail: 'tempo' | 'base' | 'solana' | 'stripe';
+    sampleAmountUsd: number;
+    sampleRecipient: string;
+    intent?: 'charge' | 'authorize' | 'session.open';
+    ttlSeconds?: number;
+    docsUrl?: string;
+    message?: string;
+    x402Sample?: {
+        version?: 1 | 2;
+        networks?: string[];
+        accepts?: unknown[];
+        amountAtomic?: string;
+        resourceUrl?: string;
+    };
+}
+/** In-flight state passed to every hook in the Checkout flow. */
+interface CheckoutContext {
+    request: CheckoutRequest;
+    /** UUID minted on first contact. Goods merchants persist as order id; API
+     *  merchants treat as request id. */
+    referenceId: string;
+    /** Set after `computePricing` runs. */
+    pricing: PricingResult | null;
+    /** rail-key → recipient address, after `mintRecipients` runs (if provided).
+     *  Static rails inherit recipients from the RailSpec. */
+    recipients: Record<string, string>;
+    /** Merchant-supplied per-request state, populated by `preValidate`. Other
+     *  hooks read from here (e.g. `ctx.state.product` after preValidate
+     *  resolved it). Stays empty when no `preValidate` is configured. */
+    state: Record<string, unknown>;
+    /** Capture the signer wallet under the operator credential the gate resolved
+     *  for this request. Set by Checkout's internal gate after a successful allow
+     *  when an operator_token is present; `undefined` for wallet-authenticated
+     *  requests (no operator_token to associate) or anonymous discovery legs.
+     *  Fire-and-forget — invoke from `onSettled` with the recovered signer. */
+    captureWallet?: (opts: {
+        walletAddress: string;
+        network: 'evm' | 'solana';
+        idempotencyKey?: string;
+    }) => Promise<void>;
+}
+/**
+ * Derive a coarse identity status (`'verified' | 'unverified' | 'anonymous'`)
+ * from the assess block on a CheckoutContext. Goods merchants persist this on
+ * the order row so audit logs distinguish gated buyers from anonymous ones.
+ */
+declare function getIdentityStatus(ctx: CheckoutContext): 'verified' | 'unverified' | 'anonymous';
+/**
+ * Raised from a `preValidate` hook to short-circuit Checkout with a canonical
+ * 4xx envelope.
+ *
+ * Checkout catches this and emits the canonical `{ error, next_steps }` envelope
+ * via `buildValidationError` so merchants don't construct response bodies
+ * themselves in the pre-validate path.
+ */
+declare class CheckoutValidationError extends Error {
+    readonly code: string;
+    readonly action: string;
+    readonly status: number;
+    readonly extra: Record<string, unknown> | undefined;
+    constructor(opts: {
+        code: string;
+        message: string;
+        action?: string;
+        status?: number;
+        extra?: Record<string, unknown>;
+    });
+}
+/**
+ * Hook that runs once per request before pricing/settle. Returns a state dict
+ * that Checkout merges into `ctx.state` so downstream hooks (`computePricing`,
+ * `onSettled`) can read merchant-resolved values like the product row,
+ * redemption code, post-discount cents, etc.
+ *
+ * Throw {@link CheckoutValidationError} to short-circuit with a 4xx envelope.
+ */
+type PreValidateFn = (ctx: CheckoutContext) => Record<string, unknown> | Promise<Record<string, unknown>>;
+/** Denial returned by a `CheckoutGateConfig.runGate` function. */
+interface GateDenial {
+    status: number;
+    body: Record<string, unknown>;
+    headers?: Record<string, string>;
+}
+/**
+ * Function the merchant supplies (or builds via a Checkout-gate helper) to run
+ * the per-request AgentScore gate. Returns `null` on accept, a `GateDenial`
+ * on deny.
+ */
+type RunGateFn = (ctx: CheckoutContext) => Promise<GateDenial | null>;
+/**
+ * Wires the AgentScore gate into Checkout.
+ *
+ * The SDK constructs an `AgentScoreCore` from the policy fields (KYC, age,
+ * sanctions, jurisdiction allowlist) and evaluates it after `preValidate`
+ * populates state. Supports the full `createSessionOnMissing` hook surface so
+ * merchants can pre-create pending orders before the verification session is
+ * minted (set `onBeforeSession` to upsert state keyed by `ctx.referenceId` or
+ * `ctx.state.*`, returning extras that the SDK folds into `reason.extra`).
+ *
+ * Three customization layers, in order of precedence:
+ *
+ * 1. ``runGate`` — full escape hatch. Replaces the SDK's gate flow entirely.
+ *    Merchants implement assess + denial body construction themselves. Useful
+ *    only for non-standard auth (e.g. shared signing keys, non-AgentScore IdP).
+ * 2. ``perRequestPolicy`` — reads `ctx.state` (populated by preValidate) and
+ *    returns a partial policy override applied per request (e.g. product-level
+ *    KYC requirement). When omitted, the static fields below apply uniformly.
+ * 3. ``onDenied`` — invoked AFTER the SDK builds the canonical DenialReason.
+ *    Return a `GateDenial` to override the response body shape, or null to
+ *    fall back to the canonical body from `denialReasonToBody`.
+ *
+ * Static policy fields mirror `AgentScoreCoreOptions` — see that interface
+ * for field semantics.
+ */
+interface CheckoutGateConfig {
+    /** AgentScore API key. Required when `runGate` is omitted. */
+    apiKey?: string;
+    /** Override the default `https://api.agentscore.sh` base URL. */
+    baseUrl?: string;
+    /** Prepended to the default User-Agent on API calls. */
+    userAgent?: string;
+    /** Require KYC verification. */
+    requireKyc?: boolean;
+    /** Require operator clear of sanctions. */
+    requireSanctionsClear?: boolean;
+    /** Minimum operator age bracket (18 or 21). */
+    minAge?: number;
+    /** Blocked jurisdiction list. */
+    blockedJurisdictions?: string[];
+    /** Allowed jurisdiction allowlist; only these pass. */
+    allowedJurisdictions?: string[];
+    /** Fail-open posture for AgentScore-side infra failures. Default false. */
+    failOpen?: boolean;
+    /** How long to cache results in seconds. Default 300. */
+    cacheSeconds?: number;
+    /** Optional chain filter for scoring. */
+    chain?: string;
+    /** Session-mint config for missing-identity bootstrap. Hooks receive the
+     *  CheckoutContext so `getSessionOptions` and `onBeforeSession` can read
+     *  state populated by `preValidate`. */
+    createSessionOnMissing?: CreateSessionOnMissing<CheckoutContext>;
+    /** Surfaced in `agent_memory` hints and audit logs. */
+    merchantName?: string;
+    /** Free-form context label (e.g. `"purchase"`, `"orders"`). */
+    context?: string;
+    /** Per-request policy override. Returns the partial fields to merge over
+     *  the static config above. Return `null` to skip the gate. */
+    perRequestPolicy?: (ctx: CheckoutContext) => Partial<AgentScoreCoreOptions> | null | Promise<Partial<AgentScoreCoreOptions> | null>;
+    /** Customize the denial response body. Called after the SDK resolves a
+     *  DenialReason. Return a `GateDenial` to override the canonical body, or
+     *  null to use `denialReasonToBody`. */
+    onDenied?: (ctx: CheckoutContext, reason: DenialReason) => GateDenial | null | Promise<GateDenial | null>;
+    /** Full escape hatch — replaces the SDK gate flow. */
+    runGate?: RunGateFn;
+}
+/** Surface passed to `Checkout.onSettled` after a payment lands. */
+interface SettleOutcome {
+    /** Protocol family that handled the settle. */
+    rail: 'x402' | 'mpp';
+    /** The `PAYMENT-RESPONSE` header to echo (x402 success path). `null` for MPP. */
+    paymentResponseHeader: string | null;
+    /** The `Payment-Receipt` header to echo (MPP success path, paymentauth.org §5).
+     *  `null` for x402 and for the MPP zero-settle carve-out (no receipt minted). */
+    paymentReceiptHeader: string | null;
+    /** The underlying settle result for merchants that need to inspect tx hash / etc. */
+    raw: unknown;
+    /** On-chain transaction hash where applicable; `null` for the zero-settle carve-out
+     *  (no on-chain settle) and for Stripe SPT. */
+    txHash?: string | null;
+    /** Verified signer address (EVM lowercased; Solana base58 verbatim). */
+    signerAddress?: string | null;
+    /** Network family of the signer; `'evm'` or `'solana'`. */
+    signerNetwork?: string | null;
+    /** The merchant's `rails`-dict key that handled this settle (e.g. `'tempo'`,
+     *  `'x402_base'`). Use to label rails in audit logs and persisted orders. */
+    railKey?: string;
+}
+/** Result a `composeMppx` hook returns when handling an MPP credential.
+ *
+ *  `status: 200` means mppx validated the `Authorization: Payment` credential
+ *  and the settlement landed; Checkout runs `onSettled` and returns success.
+ *
+ *  `status: 402` means mppx emitted a 402 (no credential / invalid credential).
+ *  Checkout layers its rich body on top of mppx's WWW-Authenticate header and
+ *  optional x402 PAYMENT-REQUIRED, returning the composed 402.
+ */
+interface MppxComposeOutcome {
+    status: 200 | 402;
+    /** For `status: 402`: the WWW-Authenticate (+ any other) headers mppx's compose
+     *  emitted. Checkout merges these into the final 402 response. */
+    headers?: Record<string, string>;
+    /** For `status: 200`: optional PAYMENT-RESPONSE header echoed to the agent. */
+    paymentResponseHeader?: string | null;
+    /** For `status: 200`: serialized `Payment-Receipt` header (base64url-encoded
+     *  receipt struct per mppx's `Receipt.serialize`). Echoed to the agent so
+     *  spec-strict MPP clients (tempo CLI, etc.) can lift tx_hash + source from
+     *  headers without parsing the JSON body. */
+    paymentReceiptHeader?: string | null;
+    /** The underlying mppx compose result for `onSettled` introspection. */
+    raw?: unknown;
+    /** On-chain tx hash from the mppx Receipt (when status=200 and on-chain). */
+    txHash?: string | null;
+    /** Verified signer recovered from the credential (when status=200). */
+    signerAddress?: string | null;
+    /** Network family of the signer; `'evm'` or `'solana'`. */
+    signerNetwork?: string | null;
+    /** The merchant's `rails`-dict key that handled this settle. Defaults to
+     *  `"tempo"` when unset by the hook. */
+    railKey?: string;
+}
+/** Framework-neutral output of `Checkout.handle`. */
+interface CheckoutResult {
+    status: number;
+    body: Record<string, unknown>;
+    headers: Record<string, string>;
+    referenceId: string;
+    settled: boolean;
+    /** `null` on settlement success; otherwise the failure phase
+     *  (`'verify_failed'`, `'settle_failed'`, ...) for diagnostics. */
+    settlePhase?: string | null;
+}
+type PricingFn = (ctx: CheckoutContext) => PricingResult | Promise<PricingResult>;
+type RecipientsFn = (ctx: CheckoutContext) => Record<string, string> | Promise<Record<string, string>>;
+type ReferenceIdFn = (ctx: CheckoutContext) => string | Promise<string>;
+type OnSettledFn = (ctx: CheckoutContext, outcome: SettleOutcome) => Record<string, unknown> | null | Promise<Record<string, unknown> | null>;
+type ComposeMppxFn = (ctx: CheckoutContext) => MppxComposeOutcome | Promise<MppxComposeOutcome>;
+type IsCachedAddressFn = (address: string) => boolean | Promise<boolean>;
+/**
+ * Build the canonical `composeMppx` hook for pympp/mppx-backed MPP rails.
+ *
+ * Lazily resolves the server via the supplied `serverGetter` (typically the
+ * output of `lazyMppxServer`). Forwards the request's `Authorization: Payment`
+ * header and the current pricing amount to `mpp.charge`. Maps the three pympp
+ * outcomes to `MppxComposeOutcome`:
+ *
+ * - `Challenge` (no/invalid credential) → `status: 402` with the
+ *   `www-authenticate` header pympp issued.
+ * - `(Credential, Receipt)` tuple → `status: 200` with the tx hash lifted from
+ *   `receipt.reference` / `receipt.transaction` and the signer lifted from the
+ *   credential's `did:pkh:...` source.
+ * - Any unexpected exception → `status: 402` (no headers; Checkout falls back
+ *   to its standard 402 emit).
+ */
+declare function makeMppxComposeHook(opts: {
+    serverGetter: () => Promise<unknown>;
+}): ComposeMppxFn;
+/**
+ * Framework-neutral 4xx envelope (`{ error, next_steps, agent_instructions }`).
+ *
+ * Returns the body dict; merchants wrap in their framework's JSON response.
+ * The per-framework `validationResponse*` helpers do this for you.
+ */
+declare function validationEnvelope(opts: {
+    code: string;
+    message: string;
+    action?: string;
+    extra?: Record<string, unknown>;
+}): Record<string, unknown>;
+interface ValidationResponseInput {
+    code: string;
+    message: string;
+    action?: string;
+    status?: number;
+    extra?: Record<string, unknown>;
+}
+/** Hono one-liner; returns a `Response` via `c.json`-equivalent semantics. */
+declare function validationResponseHono(input: ValidationResponseInput): Response;
+/**
+ * Express helper; writes the response on the supplied `res`. Returns `void`
+ * to match Express convention.
+ */
+declare function validationResponseExpress(res: {
+    status: (code: number) => unknown;
+    json: (body: unknown) => unknown;
+}, input: ValidationResponseInput): void;
+/** Fastify helper; writes on the supplied `reply` and returns it for chaining. */
+declare function validationResponseFastify(reply: {
+    code: (code: number) => unknown;
+    send: (body: unknown) => unknown;
+}, input: ValidationResponseInput): unknown;
+/** Next.js helper; returns a `Response` (interchangeable with NextResponse.json). */
+declare function validationResponseNextjs(input: ValidationResponseInput): Response;
+/** Web Fetch helper; returns a standard `Response`. */
+declare function validationResponseWeb(input: ValidationResponseInput): Response;
+declare module './checkout' {
+}
+/**
+ * High-level agent-commerce orchestrator.
+ *
+ * @example
+ * ```ts
+ * const checkout = new Checkout({
+ *   rails: { tempo: ..., x402_base: ..., stripe: ... },
+ *   url: APP_URL,
+ *   computePricing: (ctx) => ({ amountUsd: cartTotal(ctx.request.body) }),
+ *   mintRecipients: (ctx) => stripeMultichainAddressesFor(ctx),
+ *   onSettled: (ctx, outcome) => persistOrder(ctx.referenceId, ctx.request.body, outcome),
+ *   composeMppx: (ctx) => mppxCompose(mppx, ctx.request),
+ *   x402Server: x402,
+ * });
+ * const result = await checkout.handle(buildCheckoutRequest(request));
+ * return new Response(JSON.stringify(result.body), { status: result.status, headers: result.headers });
+ * ```
+ */
+declare class Checkout {
+    readonly rails: Record<string, CheckoutRailSpec>;
+    readonly url: string;
+    readonly merchantName: string | undefined;
+    readonly computePricing: PricingFn;
+    readonly preValidate: PreValidateFn | undefined;
+    x402Server: X402Server | undefined;
+    composeMppx: ComposeMppxFn | undefined;
+    readonly mintRecipients: RecipientsFn | undefined;
+    readonly mintReferenceId: ReferenceIdFn | undefined;
+    readonly onSettled: OnSettledFn | undefined;
+    readonly isCachedAddress: IsCachedAddressFn | undefined;
+    readonly zeroSettleCarveOut: boolean;
+    readonly gate: CheckoutGateConfig | undefined;
+    readonly discoveryExtensions: Record<string, unknown> | undefined;
+    readonly discoveryProbe: DiscoveryProbeConfig | undefined;
+    private _x402ServerGetter;
+    constructor(opts: {
+        rails: Record<string, CheckoutRailSpec>;
+        url: string;
+        computePricing: PricingFn;
+        /** Per-request validation hook. Runs before pricing/gate/settle. Throw
+         *  `CheckoutValidationError` to short-circuit with a 4xx envelope. Returns
+         *  a state dict merged into `ctx.state` for downstream hooks. */
+        preValidate?: PreValidateFn;
+        /** Built via `createX402Server`. Pair it with an `X402BaseRailSpec` in
+         *  `rails['x402_base']`; the CAIP-2 network is read from `rail.network`.
+         *  When omitted, Checkout auto-derives via `lazyX402Server` from the flat
+         *  `cdpApiKeyId` / `cdpApiKeySecret` kwargs. */
+        x402Server?: X402Server;
+        /** Required when the merchant accepts `Authorization: Payment` credentials.
+         *  When omitted and `mppxSecretKey` is supplied, Checkout auto-derives via
+         *  `lazyMppxServer` + the canonical compose hook (see `makeMppxComposeHook`). */
+        composeMppx?: ComposeMppxFn;
+        /** Flat-config: when `x402Server` is omitted and any X402BaseRailSpec is in
+         *  `rails`, Checkout lazy-builds the x402 server. Pair `cdpApiKeyId` +
+         *  `cdpApiKeySecret` to use Coinbase's facilitator; omit both for the
+         *  public HTTP facilitator. */
+        cdpApiKeyId?: string;
+        cdpApiKeySecret?: string;
+        /** Flat-config: when `composeMppx` is omitted and an MPP rail is in `rails`,
+         *  Checkout lazy-builds the mppx server. */
+        mppxSecretKey?: string;
+        /** Per-order deposit address minting (e.g. Stripe-multichain). */
+        mintRecipients?: RecipientsFn;
+        /** Default is `randomUUID()`. */
+        mintReferenceId?: ReferenceIdFn;
+        /** Runs after a settle lands; can return an inline response body for API sellers. */
+        onSettled?: OnSettledFn;
+        /** Pass when the merchant mints per-order addresses so `verifyX402Request` can
+         *  confirm the `payTo` was minted by this merchant. Defaults to permissive. */
+        isCachedAddress?: IsCachedAddressFn;
+        /** Engage the EIP-3009 value=0 + pympp `proof` carve-out when pricing
+         *  resolves to $0. Goods merchants offering free redemption codes set this
+         *  to `true` so the credential parses without an on-chain settle. */
+        zeroSettleCarveOut?: boolean;
+        /** Per-request gate config. When set, the gate runs after `preValidate`
+         *  populates `ctx.state` and before pricing/settle. Denials short-circuit
+         *  with the gate's body verbatim. */
+        gate?: CheckoutGateConfig;
+        /** Per-endpoint x402 `extensions` block emitted on the 402 body. Merge
+         *  outputs of `createBazaarDiscovery({...})` (or other extension declarers)
+         *  here — Checkout forwards verbatim into the 402 response body's
+         *  `extensions` field so Bazaar crawlers and other spec-compliant clients
+         *  read the route's declared input/output schema. */
+        discoveryExtensions?: Record<string, unknown>;
+        /** Optional discovery-probe config: auto-route empty-body POSTs without a
+         *  payment header to a sample 402 advertising the merchant's shape for
+         *  crawlers (`awal x402 details`, x402-proxy, x402scan, ...). */
+        discoveryProbe?: DiscoveryProbeConfig;
+    });
+    /** Canonical `RailKey` list derived from the configured rails dict. Each
+     *  `*RailSpec` type maps to one `RailKey` (Tempo and TempoSession both fold
+     *  to `"tempo_mpp"`). Dedupes so listing is per protocol, not per recipient.
+     *  Use in `.well-known/mpp.json`, skill.md / llms.txt discovery responses. */
+    get acceptedRails(): RailKey[];
+    /** Protocol-shaped method-name list (`"tempo/charge"`, `"x402/exact (base)"`).
+     *  Suitable for the `methods: [...]` array of `.well-known/mpp.json`. */
+    get acceptedMethodNames(): string[];
+    /** Resolve the x402 server, awaiting the lazy getter on first use. */
+    private getX402Server;
+    private x402ServerAvailable;
+    /** Return the rails-dict key for the X402BaseRailSpec entry. Defaults to
+     *  `"x402_base"` when no match found. */
+    private x402RailKey;
+    /** Return the rails-dict key for the primary MPP rail. */
+    private mppRailKey;
+    /** CAIP-2 read from `rails['x402_base'].network` (or its default).
+     *  Defined only when an `X402BaseRailSpec` is present in rails AND a server
+     *  is configured (explicit or auto-derived); otherwise `null`. */
+    get x402BaseNetwork(): string | null;
+    handle(request: CheckoutRequest): Promise<CheckoutResult>;
+    private validationErrorResult;
+    private runGate;
+    private handleZeroSettle;
+    private mintRefId;
+    private resolveRecipientsForCtx;
+    private asyncIsCachedAddress;
+    private handleX402;
+    private handleMppx;
+    private emit402;
+    private buildSuccess;
+}
+interface Checkout {
+    handleHono(c: {
+        req: {
+            method: string;
+            url: string;
+            raw?: Request;
+            header: (name?: string) => string | Record<string, string> | undefined;
+            json: () => Promise<unknown>;
+        };
+        json: (body: unknown, status?: number, headers?: Record<string, string>) => Response;
+        body: (body: string, status?: number, headers?: Record<string, string>) => Response;
+    }, body?: Record<string, unknown>): Promise<Response>;
+    handleExpress(req: {
+        method: string;
+        originalUrl?: string;
+        url?: string;
+        headers: Record<string, string | string[] | undefined>;
+        body?: unknown;
+    }, res: {
+        status: (code: number) => unknown;
+        setHeader: (name: string, value: string) => unknown;
+        json: (body: unknown) => unknown;
+    }, body?: Record<string, unknown>): Promise<void>;
+    handleFastify(request: {
+        method: string;
+        url: string;
+        headers: Record<string, string | string[] | undefined>;
+        body?: unknown;
+    }, reply: {
+        code: (code: number) => unknown;
+        header: (name: string, value: string) => unknown;
+        send: (body: unknown) => unknown;
+    }, body?: Record<string, unknown>): Promise<unknown>;
+    handleNextjs(request: Request, body?: Record<string, unknown>): Promise<Response>;
+    handleWeb(request: Request, body?: Record<string, unknown>): Promise<Response>;
+    mountUcpRoutesHono(app: {
+        get: (path: string, handler: (c: {
+            req: {
+                raw: Request;
+            };
+        }) => Promise<Response> | Response) => unknown;
+        options: (path: string, handler: (c: {
+            req: {
+                raw: Request;
+            };
+        }) => Promise<Response> | Response) => unknown;
+    }, opts: MountUcpRoutesOptions): void;
+    mountUcpRoutesExpress(app: {
+        get: (path: string, handler: (req: {
+            headers: Record<string, string | string[] | undefined>;
+        }, res: ExpressLikeRes) => Promise<void> | void) => unknown;
+        options: (path: string, handler: (req: {
+            headers: Record<string, string | string[] | undefined>;
+        }, res: ExpressLikeRes) => Promise<void> | void) => unknown;
+    }, opts: MountUcpRoutesOptions): void;
+    mountUcpRoutesFastify(app: {
+        get: (path: string, handler: (request: {
+            headers: Record<string, string | string[] | undefined>;
+        }, reply: FastifyLikeReply) => Promise<unknown> | unknown) => unknown;
+        options: (path: string, handler: (request: {
+            headers: Record<string, string | string[] | undefined>;
+        }, reply: FastifyLikeReply) => Promise<unknown> | unknown) => unknown;
+    }, opts: MountUcpRoutesOptions): void;
+}
+interface ExpressLikeRes {
+    status: (code: number) => unknown;
+    set: (headers: Record<string, string>) => unknown;
+    type: (mt: string) => unknown;
+    send: (body: string) => unknown;
+}
+interface FastifyLikeReply {
+    code: (code: number) => unknown;
+    header: (k: string, v: string) => unknown;
+    type: (mt: string) => unknown;
+    send: (body: string) => unknown;
+}
+/** Options for the `mountUcpRoutes<Framework>` helpers — one shape used by all
+ *  three adapters. Saves merchants from copy-pasting the same 3-route block
+ *  (GET ucp + GET jwks + OPTIONS preflights) every time. */
+interface MountUcpRoutesOptions {
+    name: string;
+    wellKnownUcpUrl: string;
+    services: Record<string, unknown[]>;
+    signingKid?: string;
+    agentscoreGate?: unknown;
+    ucpPath?: string;
+    jwksPath?: string;
+}
+
+export { AGENTSCORE_UCP_CAPABILITY as A, validationResponseFastify as B, Checkout as C, type DiscoveryProbeConfig as D, validationResponseHono as E, validationResponseNextjs as F, type GateDenial as G, validationResponseWeb as H, type IsCachedAddressFn as I, x402PaymentHandler as J, type MountUcpRoutesOptions as M, type OnSettledFn as O, type PreValidateFn as P, type RecipientsFn as R, type SettleOutcome as S, UCPSigningKey as U, type UCPProfile as a, type AgentScoreGatePolicy as b, type CheckoutContext as c, type CheckoutGateConfig as d, type CheckoutRailSpec as e, type CheckoutRequest as f, type CheckoutResult as g, CheckoutValidationError as h, type ComposeMppxFn as i, type MppxComposeOutcome as j, type PricingFn as k, type PricingResult as l, type ReferenceIdFn as m, type RunGateFn as n, type UCPCapabilityBinding as o, type UCPPaymentHandlerBinding as p, type UCPProfileBody as q, type UCPServiceBinding as r, buildUCPProfile as s, getIdentityStatus as t, makeMppxComposeHook as u, mppPaymentHandler as v, pricingResult as w, stripeSptPaymentHandler as x, validationEnvelope as y, validationResponseExpress as z };