@agent-score/commerce 1.8.0 → 2.0.0

package/dist/discovery/index.d.ts

@@ -1,5 +1,10 @@
-import { R as RailKey, C as CompatibleClients } from '../agent_instructions-DiMSGkdm.js';
-export { f as compatibleClientsByRails } from '../agent_instructions-DiMSGkdm.js';
+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-BoFwnVsj.js';
+import '../rail_spec-XP0wKgJV.js';
+import '../core.js';
+import '../signer-3FAit11j.js';
+import '../x402_server-hgQzWQwB.js';
 
 /**
  * Build a sample x402 accepts entry for a CAIP-2 network. Looks up the USDC asset
@@ -146,7 +151,16 @@ interface PaymentMethodConfig {
     /** Vendor-specific extras merged into the purchase block (e.g., gift_note metadata). */
     extra?: Record<string, unknown>;
 }
-interface WellKnownMppInput {
+/**
+ * Build the standard `.well-known/mpp.json` discovery document. Lift the boilerplate
+ * (payment.methods, payment.identity_paths, payment.compliance) into a typed config so
+ * vendors get spec-compliance "for free"; merchant-specific fields (catalog, shipping)
+ * pass through.
+ *
+ * Wire it in your framework like:
+ *   app.get('/.well-known/mpp.json', (c) => c.json(buildWellKnownMpp({...})));
+ */
+declare function buildWellKnownMpp({ name, description, url, openapi, endpoints, catalog, purchase, shipping, extra, }: {
     /** Merchant display name. */
     name: string;
     /** Short description (1-2 sentences). */
@@ -168,17 +182,7 @@ interface WellKnownMppInput {
     shipping?: Record<string, unknown>;
     /** Vendor-specific extra fields merged at the top level. */
     extra?: Record<string, unknown>;
-}
-/**
- * Build the standard `.well-known/mpp.json` discovery document. Lift the boilerplate
- * (payment.methods, payment.identity_paths, payment.compliance) into a typed config so
- * vendors get spec-compliance "for free"; merchant-specific fields (catalog, shipping)
- * pass through.
- *
- * Wire it in your framework like:
- *   app.get('/.well-known/mpp.json', (c) => c.json(buildWellKnownMpp({...})));
- */
-declare function buildWellKnownMpp(input: WellKnownMppInput): Record<string, unknown>;
+}): Record<string, unknown>;
 
 /**
  * `buildWellKnownX402`: emits the x402scan v1 `/.well-known/x402` discovery shape.
@@ -214,7 +218,12 @@ interface WellKnownX402Document {
 }
 declare function buildWellKnownX402(input: BuildWellKnownX402Input): WellKnownX402Document;
 
-interface LlmsTxtIdentitySectionInput {
+/**
+ * Generate the standard "Choose your identity header" section for an AgentScore-gated
+ * merchant's llms.txt. Explains wallet-auth vs operator-token paths + the cross-merchant
+ * memory contract so agents know how to authenticate without reading the API docs.
+ */
+declare function llmsTxtIdentitySection({ agentscore, compliance, }?: {
     /** When true, include the AgentScore identity-paths explanation (wallet vs operator-token). */
     agentscore?: boolean;
     /** Compliance policy to mention (KYC, age, jurisdiction). */
@@ -224,14 +233,8 @@ interface LlmsTxtIdentitySectionInput {
         allowed_jurisdictions?: string[];
         require_sanctions_clear?: boolean;
     };
-}
-/**
- * Generate the standard "Choose your identity header" section for an AgentScore-gated
- * merchant's llms.txt. Explains wallet-auth vs operator-token paths + the cross-merchant
- * memory contract so agents know how to authenticate without reading the API docs.
- */
-declare function llmsTxtIdentitySection(input?: LlmsTxtIdentitySectionInput): string;
-interface LlmsTxtPaymentSectionInput {
+}): string;
+interface LlmsTxtPaymentSectionConfig {
     /** Symbolic rail names supported. */
     rails: ('tempo-mainnet' | 'tempo-testnet' | 'x402-base-mainnet' | 'x402-base-sepolia' | 'mpp-solana-mainnet' | 'mpp-solana-devnet' | 'stripe-spt' | string)[];
     /** Merchant URL — used in the example commands. */
@@ -255,8 +258,13 @@ interface LlmsTxtPaymentSectionInput {
  * Pass `verbose: true` for the rich variant — multi-step setup + multi-line command examples +
  * exact-amount warnings. Default is the compact one-bullet-per-rail form.
  */
-declare function llmsTxtPaymentSection(input: LlmsTxtPaymentSectionInput): string;
-interface BuildLlmsTxtInput {
+declare function llmsTxtPaymentSection(input: LlmsTxtPaymentSectionConfig): string;
+/**
+ * Assemble a complete llms.txt document. Vendor passes their merchant-specific sections
+ * (intro, catalog, endpoints, gift orders, shipping, etc.); the helper adds the AgentScore
+ * identity + payment boilerplate at the end. Returns the full markdown string.
+ */
+declare function buildLlmsTxt({ merchantName, tagline, sections, agentscoreIdentity, payment, }: {
     merchantName: string;
     /** Optional 1-line summary under the title. */
     tagline?: string;
@@ -266,16 +274,10 @@ interface BuildLlmsTxtInput {
         content: string;
     }[];
     /** Append the AgentScore identity section. */
-    agentscoreIdentity?: LlmsTxtIdentitySectionInput;
+    agentscoreIdentity?: Parameters<typeof llmsTxtIdentitySection>[0];
     /** Append the standard payment section. */
-    payment?: LlmsTxtPaymentSectionInput;
-}
-/**
- * Assemble a complete llms.txt document. Vendor passes their merchant-specific sections
- * (intro, catalog, endpoints, gift orders, shipping, etc.); the helper adds the AgentScore
- * identity + payment boilerplate at the end. Returns the full markdown string.
- */
-declare function buildLlmsTxt(input: BuildLlmsTxtInput): string;
+    payment?: Parameters<typeof llmsTxtPaymentSection>[0];
+}): string;
 
 /**
  * OpenAPI snippets for AgentScore-related concepts. Vendors plug these into their own
@@ -356,19 +358,23 @@ interface XPaymentInfoMppProtocol {
     mpp: {
         method: string;
         intent: string;
-        currency: string;
+        currency?: string;
+        [key: string]: unknown;
     };
 }
 type XPaymentInfoProtocol = XPaymentInfoX402Protocol | XPaymentInfoMppProtocol;
-interface XPaymentInfoInput {
+interface XPaymentInfoBlock {
+    authMode: 'payment';
     price: XPaymentInfoPrice;
     protocols: XPaymentInfoProtocol[];
+    description?: string;
 }
-declare function xPaymentInfoExtension(input: XPaymentInfoInput): {
-    'x-payment-info': {
-        price: XPaymentInfoPrice;
-        protocols: XPaymentInfoProtocol[];
-    };
+declare function xPaymentInfoExtension({ price, protocols, description, }: {
+    price: XPaymentInfoPrice;
+    protocols: XPaymentInfoProtocol[];
+    description?: string;
+}): {
+    'x-payment-info': XPaymentInfoBlock;
 };
 /**
  * `info.x-guidance` extension, per the x402scan discovery spec. Spread into your
@@ -390,14 +396,68 @@ declare function xPaymentInfoExtension(input: XPaymentInfoInput): {
 declare function xGuidanceExtension(text: string): {
     'x-guidance': string;
 };
-interface BuildAgentScoreOpenApiSnippetsInput {
-    /** Include security schemes in the snippet. Default true. */
-    security?: boolean;
-    /** Include denial schemas in the snippet. Default true. */
-    denials?: boolean;
-    /** Include the 402 PaymentRequired schema in the snippet. Default true. */
-    paymentRequired?: boolean;
-}
+/**
+ * `x-service-info` extension for the OpenAPI document's root. Discovery
+ * crawlers (x402scan, agent CLIs) read this to categorize the service and
+ * follow links to human-side docs. Spread into the OpenAPI doc's root
+ * alongside `paths`, `info`, etc.
+ *
+ * @example
+ * ```ts
+ * const spec = {
+ *   openapi: '3.1.0',
+ *   info: {...},
+ *   ...xServiceInfoExtension({
+ *     categories: ['commerce', 'wine'],
+ *     docs: { homepage: 'https://www.martinestate.com', llms: 'https://agents.martinestate.com/llms.txt' },
+ *   }),
+ *   paths: {...},
+ * };
+ * ```
+ */
+declare function xServiceInfoExtension(opts: {
+    categories: string[];
+    docs?: Record<string, string>;
+}): {
+    'x-service-info': {
+        categories: string[];
+        docs?: Record<string, string>;
+    };
+};
+/**
+ * Derive an `x-payment-info` extension from a configured `Checkout` instance.
+ *
+ * Walks `checkout.rails` and emits one entry in `protocols[]` per rail —
+ * Tempo MPP, x402 (Base), Solana MPP, Stripe SPT. Saves merchants from
+ * enumerating protocols by hand and keeps the OpenAPI doc in sync with the
+ * actual rails the Checkout serves.
+ *
+ * `price` is merchant-supplied (the rail registry doesn't carry per-merchant
+ * pricing; rates live on each Checkout's `computePricing` hook). Per-rail
+ * extras (client commands, asset names) can be merged via `protocolExtras`
+ * keyed by rail slug (`tempo`, `base`, `solana`, `stripe`).
+ */
+declare function xPaymentInfoFromCheckout(opts: {
+    checkout: {
+        rails: Record<string, {
+            network?: string;
+            recipient?: unknown;
+            currency?: unknown;
+            token?: unknown;
+            profileId?: unknown;
+        }>;
+    };
+    price: XPaymentInfoPrice;
+    description?: string;
+    protocolExtras?: Partial<{
+        tempo: Record<string, unknown>;
+        base: Record<string, unknown>;
+        solana: Record<string, unknown>;
+        stripe: Record<string, unknown>;
+    }>;
+}): {
+    'x-payment-info': XPaymentInfoBlock;
+};
 /**
  * Convenience: returns a `components` snippet ready to merge into an OpenAPI document.
  *
@@ -410,7 +470,14 @@ interface BuildAgentScoreOpenApiSnippetsInput {
  *
  * Or more idiomatically: `Object.assign(spec.components, agentscoreOpenApiSnippets())`.
  */
-declare function agentscoreOpenApiSnippets(opts?: BuildAgentScoreOpenApiSnippetsInput): {
+declare function agentscoreOpenApiSnippets({ security, denials, paymentRequired, }?: {
+    /** Include security schemes in the snippet. Default true. */
+    security?: boolean;
+    /** Include denial schemas in the snippet. Default true. */
+    denials?: boolean;
+    /** Include the 402 PaymentRequired schema in the snippet. Default true. */
+    paymentRequired?: boolean;
+}): {
     securitySchemes?: Record<string, unknown>;
     schemas?: Record<string, unknown>;
 };
@@ -522,6 +589,9 @@ interface SkillMdIdentityRequirements {
     /** Whether sanctions screening is enforced. */
     sanctionsClear?: boolean;
 }
+/** PHYSICAL-GOODS-ONLY. Shipping-policy block for skill.md. Digital goods and
+ *  API merchants skip this (the `shipping?:` field on BuildSkillMdInput is
+ *  optional). */
 interface SkillMdShippingPolicy {
     /** Allowed shipping countries (ISO 3166-1 alpha-2). */
     allowedCountries?: string[];
@@ -622,4 +692,336 @@ interface BuildSkillMdInput {
  */
 declare function buildSkillMd(input: BuildSkillMdInput): string;
 
-export { type BazaarDiscoveryConfig, type BuildAgentScoreOpenApiSnippetsInput, type BuildLlmsTxtInput, type BuildSkillMdInput, type BuildWellKnownX402Input, CompatibleClients, type DiscoveryProbeOptions, type DiscoveryProbeResponse, type LlmsTxtIdentitySectionInput, type LlmsTxtPaymentSectionInput, type NoindexNonDiscoveryOptions, type PaymentMethodConfig, RailKey, type RequestLike, type SkillMdEndpoint, type SkillMdIdentityRequirements, type SkillMdLink, type SkillMdShippingPolicy, type WellKnownMppInput, type WellKnownX402Document, type WellKnownX402Resource, type XPaymentInfoDynamicPrice, type XPaymentInfoFixedPrice, type XPaymentInfoInput, type XPaymentInfoMppProtocol, type XPaymentInfoPrice, type XPaymentInfoProtocol, type XPaymentInfoX402Protocol, agentscoreDenialSchemas, agentscoreOpenApiSnippets, agentscorePaymentRequiredSchema, agentscoreSecuritySchemes, applyNoindexHeader, buildDiscoveryProbeResponse, buildLlmsTxt, buildSkillMd, buildWellKnownMpp, buildWellKnownX402, createBazaarDiscovery, defaultDiscoveryPaths, isDiscoveryPath, isDiscoveryProbeRequest, llmsTxtIdentitySection, llmsTxtPaymentSection, noindexNonDiscoveryPaths, noindexNonDiscoveryPathsExpress, noindexNonDiscoveryPathsFastify, sampleX402AcceptForNetwork, siwxSecurityScheme, wrapNoindexResponse, xGuidanceExtension, xPaymentInfoExtension };
+/**
+ * Standard agent-facing prose for AgentScore-gated merchants.
+ *
+ * Every AgentScore merchant emits roughly the same skill.md onboarding steps,
+ * catalog purchase-mode notes, and endpoint descriptions. These helpers ship
+ * those canonical strings so merchants supply only the merchant-specific parts
+ * (name, URL, accepted rails) and get consistent agent-facing content back.
+ *
+ * Rationale: agents that hit one AgentScore merchant should see the same
+ * pattern hints at every other one. Custom prose per merchant adds noise
+ * without adding information; the SDK owns the cross-merchant boilerplate so
+ * it stays consistent.
+ */
+/**
+ * Whether a paid surface accepts redemption codes. Applies to any merchant
+ * that bills per-purchase or per-call — goods (catalog rows) and API
+ * (per-endpoint or per-tier billing) both use this enum.
+ */
+type PurchaseMode = 'redemption_only' | 'coupon_applicable' | 'paid_only';
+/**
+ * Canonical agent-facing notes for each `purchase_mode`. Surface this in
+ * /catalog rows (goods) or in `x-service-info` / `/llms.txt` (API) so agents
+ * know whether to expect a `redemption_code` field in the request body.
+ */
+declare const PURCHASE_MODE_NOTES: Readonly<Record<string, string>>;
+/**
+ * Canonical agent-facing note for a `purchase_mode`. Falls back to an empty
+ * string for unknown modes so responses don't leak `undefined` when the
+ * merchant introduces a non-standard mode.
+ */
+declare function purchaseModeNote(mode: string): string;
+/**
+ * Build the canonical skill.md `onboarding_steps` for an AgentScore merchant.
+ *
+ * Returns a list of imperative step strings the agent follows to bootstrap
+ * wallet + Passport, then either browse + buy (goods) or make the paid call
+ * (api). Generic across every AgentScore-gated merchant; only the
+ * merchantName + appUrl + rails list are substituted in.
+ *
+ * Rails accepted today: `"tempo"`, `"x402-base"`, `"solana-mpp"`, `"stripe-spt"`.
+ * Unknown rail names are passed through verbatim so future rails work without
+ * an SDK bump.
+ *
+ * Pass `vendorType: 'api'` for per-call API providers — the catalog step is
+ * dropped and the final step becomes "Make the paid call" instead of "Place
+ * the order".
+ */
+declare function buildAgentscoreOnboardingSteps(opts: {
+    merchantName: string;
+    appUrl: string;
+    acceptedRails: string[];
+    requiresKyc?: boolean;
+    vendorType?: 'goods' | 'api';
+}): string[];
+/**
+ * Canonical descriptions for the standard AgentScore **goods-merchant**
+ * endpoints (`/catalog`, `/catalog/{slug}`, `/purchase`, `/orders/{id}`).
+ *
+ * Use in `/` discovery JSON, OpenAPI summaries, or anywhere the merchant needs
+ * to describe what each endpoint does in agent-readable language. Descriptions
+ * are merchant-agnostic; they describe response semantics (402 on discovery,
+ * 400 on validation, 403 on identity, 200 on success), not the body schema
+ * (which varies per merchant; surface that in OpenAPI).
+ *
+ * Pass `kind: 'api'` for per-call API providers; the bundle drops catalog +
+ * orders routes and surfaces `POST /<endpoint>` + `GET /usage` instead.
+ *
+ * `includeOrderStatusRoute: true` (goods only) adds the lightweight
+ * `/orders/{id}/status` PII-free variant alongside `/orders/{id}`.
+ */
+declare function standardEndpointDescriptions(opts?: {
+    kind?: 'goods' | 'api';
+    includeOrderStatusRoute?: boolean;
+}): Record<string, string>;
+/**
+ * Build the canonical AgentScore commerce `/` root discovery body. Works for
+ * both goods merchants (catalog + purchase + orders) and API merchants (per-
+ * call paid endpoints) — `endpoints` and any merchant-specific fields are
+ * passed through `extra`.
+ *
+ * Common fields surfaced: `name`, `description`, `docs`, `endpoints`,
+ * `audience: 'agents'`, `supported_rails`. Pass `extra` for merchant-specific
+ * additions: `compliance` for goods merchants, `pricing` for API merchants,
+ * `website` for branded fronts.
+ *
+ * `docs` keys map to absolute URLs; pass whichever discovery surfaces this
+ * merchant ships (`llms`, `openapi`, `skill_md`, `mpp`, `agent_card`, `ucp`,
+ * `jwks`, `redemption`, ...).
+ */
+declare function buildMerchantIndexJson(opts: {
+    name: string;
+    description: string;
+    docs: Record<string, string>;
+    endpoints: Record<string, string>;
+    supportedRails: string[];
+    extra?: Record<string, unknown>;
+}): Record<string, unknown>;
+/**
+ * Standard `next_steps` block emitted in a 200 success body. Works for both
+ * goods-merchant order-success and API-merchant per-call-success — the
+ * `user_message` reinforces the cross-merchant Passport pattern (universal),
+ * with merchant-specific copy overridable via `userMessage`.
+ *
+ * `orderStatusUrl` is emitted as `order_status_url`. API merchants that don't
+ * have an order-detail endpoint can either pass a usage/dashboard URL or omit
+ * the field by passing an empty string (filtered out before emit).
+ *
+ * `fulfillmentEta` is goods-specific (shipping window) — omit for API or
+ * digital-goods merchants.
+ */
+declare function buildSuccessNextSteps(opts: {
+    orderStatusUrl?: string;
+    fulfillmentEta?: string;
+    userMessage?: string;
+}): Record<string, string>;
+
+/**
+ * Standard `/redemption.md` template for merchants offering redemption codes.
+ *
+ * Renders the canonical cold-start bootstrap + TL;DR + recovery table + body /
+ * code rules for any merchant that accepts single-use codes against a paid
+ * endpoint. The pattern is delivery-neutral: codes can be printed on a mailer,
+ * emailed, surfaced in-app, or issued as API trial credits.
+ *
+ * Goods merchants get the default body-shape (product_slug + shipping + email).
+ * API merchants or digital-credit issuers pass `bodyShape` to override the
+ * JSON example, and `extraRecoveryRows` to add merchant-specific error rows.
+ *
+ * Mirrors the prose every AgentScore merchant otherwise hand-writes so agents
+ * encounter the same shape of redemption flow at any merchant.
+ */
+/**
+ * Render the canonical `redemption.md` for an AgentScore merchant.
+ *
+ * `endpointPath` is the redemption endpoint relative to `appUrl`. Defaults to
+ * `"/purchase"` for goods merchants; API merchants typically pass
+ * `"/<endpoint>"` (the per-call paid route that accepts a `redemption_code`).
+ *
+ * `deliveryIntro` overrides the cold-start paragraph describing how the code
+ * was distributed. Default covers printed mailers, emails, and any other
+ * out-of-band delivery channel. API merchants distributing trial credits
+ * might override with vendor-specific language.
+ *
+ * `bodyShape` is the JSON example shown in the TL;DR. Defaults to the
+ * goods-merchant shape; API merchants pass their endpoint's body shape (which
+ * still includes `redemption_code`).
+ *
+ * `bodyRules` overrides the body-rules section. Default covers goods-shipping
+ * rules; API merchants typically pass either `""` (drop the section) or their
+ * own constraints.
+ *
+ * `extraRecoveryRows` is appended verbatim to the recovery table after the
+ * universal rows. Use it for merchant-specific error codes (e.g.
+ * `unsupported_jurisdiction`, per-tier code rules).
+ *
+ * `skuIntro` describes what the code unlocks at this merchant. Defaults to a
+ * generic placeholder.
+ *
+ * `peerMerchantPointer` is the optional "Don't have a code?" cross-link at the
+ * bottom. Omit to drop the section.
+ */
+declare function buildRedemptionSkillMd(opts: {
+    merchantName: string;
+    appUrl: string;
+    endpointPath?: string;
+    skuIntro?: string;
+    deliveryIntro?: string;
+    bodyShape?: string;
+    bodyRules?: string;
+    extraRecoveryRows?: string;
+    peerMerchantPointer?: string;
+}): string;
+
+/**
+ * Spec-rooted helpers for `/.well-known/{ucp,jwks.json}` discovery surfaces.
+ *
+ * What this module collapses for every UCP-publishing merchant:
+ *
+ * - Loading + caching the signing key via `loadUCPSigningKeyFromEnv`.
+ * - Composing the `payment_handlers` map from the merchant's `Checkout` rails
+ *   (TempoRailSpec → mppPaymentHandler; X402BaseRailSpec → x402PaymentHandler;
+ *   StripeRailSpec → stripeSptPaymentHandler).
+ * - Building the unsigned profile + signing it.
+ * - Cache-Control + CORS + X-Request-ID echo per UCP section 6.
+ * - RFC 7517 section 8.5 `application/jwk-set+json` media type on JWKS.
+ * - The 503 `ucp_misconfigured` fallback envelope when no handlers can be
+ *   derived (empty rails dict OR all rails have empty recipients).
+ *
+ * Each helper returns a framework-neutral `SignedDiscoveryResponse` that
+ * merchants wrap in their framework's Response builder (Hono `c.body`, Express
+ * `res.set/.status/.send`, Fastify `reply.headers/.code/.send`, Next.js
+ * `NextResponse`, Web Fetch `new Response`, etc.).
+ */
+
+/**
+ * Framework-neutral response shape for discovery endpoints.
+ *
+ * Wrap in your framework's response builder. `body` is already JSON-encoded
+ * bytes (as a string); do not re-serialize.
+ */
+interface SignedDiscoveryResponse {
+    body: string;
+    mediaType: string;
+    headers: Record<string, string>;
+    status: number;
+}
+/**
+ * Build the signed UCP profile response for `/.well-known/ucp`.
+ *
+ * Composes payment handlers from the Checkout's rails dict, builds the profile
+ * via `buildUCPProfile`, signs via `signUCPProfile`, and attaches the UCP
+ * section 6-prescribed Cache-Control + CORS + X-Request-ID headers.
+ *
+ * Returns a 503 `ucp_misconfigured` envelope (still with the section 6-compliant
+ * Cache-Control) when no payment handlers can be derived from rails.
+ *
+ * `services` is the spec-compliant services map (keyed by reverse-DNS service
+ * name). `wellKnownUcpUrl` is the canonical URL of this profile, surfaced as
+ * the value in `supported_versions`.
+ */
+declare function buildSignedUcpResponse(opts: {
+    checkout: Checkout;
+    name: string;
+    wellKnownUcpUrl: string;
+    services: Record<string, UCPServiceBinding[]>;
+    requestHeaders?: Headers | Record<string, string>;
+    signingKid?: string;
+    agentscoreGate?: AgentScoreGatePolicy;
+}): Promise<SignedDiscoveryResponse>;
+/**
+ * Build the JWKS response for `/.well-known/jwks.json`.
+ *
+ * RFC 7517 section 8.5 prescribes `application/jwk-set+json`. Five-minute
+ * Cache-Control balances verifier-side cache hit rate against rotation
+ * propagation latency.
+ */
+declare function buildSignedJwksResponse(opts?: {
+    requestHeaders?: Headers | Record<string, string>;
+    signingKid?: string;
+}): Promise<SignedDiscoveryResponse>;
+/**
+ * CORS preflight headers for `/.well-known/*` endpoints.
+ *
+ * Echoes `Access-Control-Request-Headers` verbatim when present rather than
+ * advertising `*` (which browsers reject with credentials in scope). Returns
+ * a 204 on the corresponding response via the merchant's framework.
+ */
+declare function wellKnownCorsPreflightHeaders(requestHeaders?: Headers | Record<string, string>): Record<string, string>;
+/**
+ * Build a 204 CORS preflight `Response` for `/.well-known/*` endpoints, wrapping
+ * {@link wellKnownCorsPreflightHeaders}. Universal across every UCP-publishing
+ * merchant; saves the 4-line `new Response(null, { status: 204, headers: ... })`
+ * wrapper every consumer otherwise hand-rolls.
+ */
+declare function wellKnownPreflightResponse(requestHeaders?: Headers | Record<string, string>): Response;
+/**
+ * Canonical UCP services map for a merchant publishing an A2A agent card.
+ *
+ * Returns `{"dev.ucp.shopping": [UCPServiceBinding(version: '2026-04-08',
+ * spec: <UCP shopping spec>, transport: 'a2a', endpoint: agentCardUrl)]}`;
+ * the binding every UCP-publishing merchant declares when their primary agent
+ * surface is the A2A v1.0 `/.well-known/agent-card.json` (versus a UCP MCP or
+ * REST endpoint).
+ *
+ * Merchants who additionally expose a UCP MCP or REST transport append further
+ * bindings to the same `dev.ucp.shopping` list.
+ */
+declare function defaultA2aServices(opts: {
+    agentCardUrl: string;
+}): Record<string, UCPServiceBinding[]>;
+/**
+ * Eager-load the UCP signing key at startup.
+ *
+ * A malformed `UCP_SIGNING_KEY_JWK_PRIVATE` env value otherwise surfaces on
+ * the first `/.well-known/ucp` hit after deploy, masquerading as a runtime
+ * 500. Calling this in the framework's startup hook fails the deploy fast.
+ *
+ * Wraps `loadUCPSigningKeyFromEnv`; throws (per that helper's contract) on a
+ * malformed JWK so the orchestrator marks the task unhealthy.
+ */
+declare function bootstrapUcpSigningKey(opts?: {
+    defaultKid?: string;
+}): Promise<void>;
+/** Hono / Web Fetch wrapper. Returns a `Response`. */
+declare function signedResponseHono(resp: SignedDiscoveryResponse): Response;
+/** Next.js wrapper. Returns a `Response` (interchangeable with NextResponse). */
+declare function signedResponseNextjs(resp: SignedDiscoveryResponse): Response;
+/** Web Fetch wrapper. Returns a standard `Response`. */
+declare function signedResponseWeb(resp: SignedDiscoveryResponse): Response;
+/** Express wrapper. Writes onto `res`; returns `void` to match Express convention. */
+declare function signedResponseExpress(res: {
+    status: (code: number) => unknown;
+    set: (headers: Record<string, string>) => unknown;
+    type: (mt: string) => unknown;
+    send: (body: string) => unknown;
+}, resp: SignedDiscoveryResponse): void;
+/** Fastify wrapper. Writes onto `reply` and returns it. */
+declare function signedResponseFastify(reply: {
+    code: (code: number) => unknown;
+    header: (k: string, v: string) => unknown;
+    type: (mt: string) => unknown;
+    send: (body: string) => unknown;
+}, resp: SignedDiscoveryResponse): unknown;
+
+/**
+ * Echo the request-id middleware sets on the context as an `X-Request-ID`
+ * response header. Agents correlate logs across 4xx retries by reading this.
+ *
+ * Hono variant — reads `c.get('requestId')` populated by `hono/request-id`.
+ * Express / Fastify / Next.js / Web Fetch variants will follow when consumers
+ * need them.
+ *
+ * Universal for AgentScore commerce merchants: every retry-loop pattern
+ * (probe-then-pay, 403-then-resume, settle-then-retry) benefits from the
+ * agent being able to grep server logs for the request id.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { requestId } from 'hono/request-id';
+ * import { echoRequestIdHeaderHono } from '@agent-score/commerce/discovery';
+ *
+ * const app = new Hono();
+ * app.use('*', requestId());
+ * app.use('*', echoRequestIdHeaderHono());
+ * ```
+ */
+declare function echoRequestIdHeaderHono(): (c: {
+    get: (key: 'requestId') => string | undefined;
+    header: (name: string, value: string) => void;
+}, next: () => Promise<void>) => Promise<void>;
+
+export { type BuildWellKnownX402Input, CompatibleClients, type DiscoveryProbeResponse, PURCHASE_MODE_NOTES, type PaymentMethodConfig, type PurchaseMode, RailKey, type RequestLike, type SignedDiscoveryResponse, type SkillMdEndpoint, type SkillMdIdentityRequirements, type SkillMdLink, type SkillMdShippingPolicy, type WellKnownX402Document, type WellKnownX402Resource, type XPaymentInfoBlock, type XPaymentInfoDynamicPrice, type XPaymentInfoFixedPrice, type XPaymentInfoMppProtocol, type XPaymentInfoPrice, type XPaymentInfoProtocol, type XPaymentInfoX402Protocol, agentscoreDenialSchemas, agentscoreOpenApiSnippets, agentscorePaymentRequiredSchema, agentscoreSecuritySchemes, applyNoindexHeader, bootstrapUcpSigningKey, buildAgentscoreOnboardingSteps, buildDiscoveryProbeResponse, buildLlmsTxt, buildMerchantIndexJson, buildRedemptionSkillMd, buildSignedJwksResponse, buildSignedUcpResponse, buildSkillMd, buildSuccessNextSteps, buildWellKnownMpp, buildWellKnownX402, createBazaarDiscovery, defaultA2aServices, defaultDiscoveryPaths, echoRequestIdHeaderHono, isDiscoveryPath, isDiscoveryProbeRequest, llmsTxtIdentitySection, llmsTxtPaymentSection, noindexNonDiscoveryPaths, noindexNonDiscoveryPathsExpress, noindexNonDiscoveryPathsFastify, purchaseModeNote, sampleX402AcceptForNetwork, signedResponseExpress, signedResponseFastify, signedResponseHono, signedResponseNextjs, signedResponseWeb, siwxSecurityScheme, standardEndpointDescriptions, wellKnownCorsPreflightHeaders, wellKnownPreflightResponse, wrapNoindexResponse, xGuidanceExtension, xPaymentInfoExtension, xPaymentInfoFromCheckout, xServiceInfoExtension };