@agent-score/commerce 1.0.0

package/dist/discovery/index.d.mts

@@ -0,0 +1,382 @@
+/**
+ * Build a sample x402 accepts entry for a CAIP-2 network. Looks up the USDC asset
+ * for the network from the `USDC` registry and uses a placeholder payTo. Used by
+ * the discovery probe to advertise x402 support without exposing real deposit
+ * addresses.
+ *
+ * Returns null when the network isn't in the registry — vendors with custom
+ * networks should construct accepts entries by hand and pass them via
+ * `x402Sample.accepts` directly.
+ */
+declare function sampleX402AcceptForNetwork(caip2: string, amountAtomic?: string): Record<string, unknown> | null;
+interface DiscoveryProbeOptions {
+    /** Realm — typically the host of your merchant URL (e.g., "agents.merchant.example"). */
+    realm: string;
+    /** Symbolic rail name to advertise in the sample challenge (e.g., 'tempo-mainnet'). */
+    sampleRail: string;
+    /** Sample amount in USD for the probe (e.g., 1.00). Crawlers use this as an example. */
+    sampleAmountUsd: number;
+    /** A recipient address to use in the sample directive (your real or zero address is fine). */
+    sampleRecipient: string;
+    /** MPP intent. Defaults to 'charge'. */
+    intent?: string;
+    /** TTL for the probe challenge in seconds. Defaults to 300 (5 minutes). */
+    ttlSeconds?: number;
+    /** Optional URL to include in the body for further docs (e.g., your llms.txt). */
+    docsUrl?: string;
+    /** Optional human-readable message in the body. */
+    message?: string;
+    /** Optional sample x402 accepts entries. When provided, the probe response also
+     *  carries the standard x402 `payment-required` header (base64 PaymentRequired) AND
+     *  an `accepts` array in the body — so x402 crawlers (e.g. Coinbase awal's
+     *  `x402 details`/`x402 pay`) can discover the endpoint's x402 support without
+     *  needing to send a fully-formed business request. Each entry is run through
+     *  `aliasAmountFields` so v1-only parsers can read `maxAmountRequired` too.
+     *
+     *  Pass `networks` (shorthand) for the common case — the helper looks up USDC
+     *  per network from the registry and uses placeholder payTo addresses. Or pass
+     *  `accepts` directly for full control over the sample shape. */
+    x402Sample?: {
+        /** Spec version to declare. Defaults to 2. */
+        version?: 1 | 2;
+        /** Shorthand: array of CAIP-2 network strings. Each is mapped to a sample
+         *  USDC accepts entry via `sampleX402AcceptForNetwork`. Networks not in the
+         *  USDC registry are silently skipped. Use `accepts` for custom shapes. */
+        networks?: string[];
+        /** Sample accepts entries. Used when `networks` shorthand isn't enough.
+         *  Supplied entries are NOT merged with `networks`-derived entries — pick
+         *  one or the other. */
+        accepts?: unknown[];
+        /** Sample atomic amount used by the `networks` shorthand. Defaults to
+         *  `'1000000'` ($1.00 USDC at 6 decimals). Ignored when `accepts` is set. */
+        amountAtomic?: string;
+        /** Resource URL the probe is responding for. Used in the PAYMENT-REQUIRED header. */
+        resourceUrl?: string;
+    };
+}
+interface DiscoveryProbeResponse {
+    status: 402;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Build a 402 response advertising a sample Payment challenge. MPP crawlers
+ * (mppscan, link-cli mpp decode) probe with empty bodies; merchants need to answer
+ * with a properly-formatted Payment directive so the realm can be indexed.
+ *
+ * Returns a framework-agnostic response shape. Wrap in your framework's response:
+ *
+ *   const probe = buildDiscoveryProbeResponse({...});
+ *   return new Response(probe.body, { status: probe.status, headers: probe.headers });
+ */
+declare function buildDiscoveryProbeResponse(opts: DiscoveryProbeOptions): DiscoveryProbeResponse;
+interface RequestLike {
+    method: string;
+    headers: {
+        get(name: string): string | null;
+    };
+    clone(): {
+        text(): Promise<string>;
+    };
+}
+/**
+ * Returns true when the request is an empty-body POST without a payment credential —
+ * the canonical MPP discovery probe pattern. Vendors compose this with
+ * buildDiscoveryProbeResponse to short-circuit crawler requests before any business
+ * logic runs.
+ */
+declare function isDiscoveryProbeRequest(req: RequestLike): Promise<boolean>;
+
+/**
+ * Bazaar discovery extension wrapper. Vendors pass their merchant config and we wrap
+ * `declareDiscoveryExtension` from `@x402/extensions/bazaar`. The returned value is
+ * registered on the x402 server (e.g., via `createX402Server({bazaar: true})` or
+ * `server.registerExtension(...)`).
+ *
+ * `@x402/extensions` is an optional peer dependency.
+ */
+interface BazaarDiscoveryConfig {
+    bodyType?: 'json' | 'form';
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+declare function createBazaarDiscovery(config: BazaarDiscoveryConfig): Promise<unknown>;
+
+interface PaymentMethodConfig {
+    /** MPP payment methods accepted, e.g., ['tempo', 'x402', 'stripe']. */
+    methods: string[];
+    /** x402-specific config (when 'x402' is in methods). */
+    x402?: {
+        networks: string[];
+        scheme?: string;
+        asset?: string;
+        facilitator?: string;
+        client_tooling?: string;
+    };
+    /** Identity headers accepted (e.g., ['X-Operator-Token', 'X-Wallet-Address']). */
+    identity?: string[];
+    /** Per-identity-path metadata for agents. */
+    identity_paths?: {
+        wallet?: {
+            header: string;
+            applies_to_rails: string[];
+            note?: string;
+        };
+        operator_token?: {
+            header: string;
+            applies_to_rails: string[];
+            note?: string;
+        };
+    };
+    /** Compliance policy summary for agents to know what they need before purchasing. */
+    compliance?: {
+        require_kyc?: boolean;
+        min_age?: number;
+        allowed_jurisdictions?: string[];
+        require_sanctions_clear?: boolean;
+    };
+    /** Required fields in the request body. */
+    required_fields?: string[];
+    /** Optional fields in the request body. */
+    optional_fields?: string[];
+    /** Vendor-specific extras merged into the purchase block (e.g., gift_note metadata). */
+    extra?: Record<string, unknown>;
+}
+interface WellKnownMppInput {
+    /** Merchant display name. */
+    name: string;
+    /** Short description (1-2 sentences). */
+    description?: string;
+    /** Canonical merchant URL. */
+    url: string;
+    /** OpenAPI doc URL (typically `${url}/openapi.json`). */
+    openapi?: string;
+    /** Endpoints map: path → {method, url}. */
+    endpoints: Record<string, {
+        method: string;
+        url: string;
+    }>;
+    /** Catalog metadata (categories, etc). Optional. */
+    catalog?: Record<string, unknown>;
+    /** Purchase flow details (payment methods, identity, compliance). */
+    purchase: PaymentMethodConfig;
+    /** Shipping policy (countries, restrictions). */
+    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>;
+
+interface LlmsTxtIdentitySectionInput {
+    /** When true, include the AgentScore identity-paths explanation (wallet vs operator-token). */
+    agentscore?: boolean;
+    /** Compliance policy to mention (KYC, age, jurisdiction). */
+    compliance?: {
+        require_kyc?: boolean;
+        min_age?: number;
+        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 {
+    /** Symbolic rail names supported. */
+    rails: ('tempo-mainnet' | 'tempo-testnet' | 'x402-base-mainnet' | 'x402-base-sepolia' | 'x402-solana-mainnet' | 'x402-solana-devnet' | 'stripe-spt' | string)[];
+    /** Merchant URL — used in the example commands. */
+    appUrl: string;
+    /**
+     * When true, emit the verbose multi-step variant: setup commands per rail, full per-rail
+     * payment-command examples, and warnings about footguns. Default false (one-line bullet per rail).
+     * Use this when llms.txt is the primary integration doc the agent reads.
+     */
+    verbose?: boolean;
+    /** When verbose, the Tempo network name to mention in the prerequisites. Default 'tempo-mainnet'. */
+    tempoNetworkName?: string;
+    /** When verbose, the Tempo chain id to mention in the prerequisites. Default 4217. */
+    tempoChainId?: number;
+}
+/**
+ * Generate the standard "## Payment" section for a merchant's llms.txt. Documents the
+ * supported rails with concrete CLI examples (tempo request, agentscore-pay, link-cli)
+ * per the configured rail set.
+ *
+ * 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 {
+    merchantName: string;
+    /** Optional 1-line summary under the title. */
+    tagline?: string;
+    /** Custom merchant-written sections (intro, endpoints, terms, etc.). */
+    sections: {
+        heading: string;
+        content: string;
+    }[];
+    /** Append the AgentScore identity section. */
+    agentscoreIdentity?: LlmsTxtIdentitySectionInput;
+    /** 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;
+
+/**
+ * OpenAPI snippets for AgentScore-related concepts. Vendors plug these into their own
+ * OpenAPI 3.1 document (typically /openapi.json) so MPPScan and similar agent registries
+ * can validate the merchant's auth + denial schemas correctly.
+ *
+ * Each helper returns a piece of an OpenAPI document — vendors compose them into their
+ * full spec.
+ */
+/**
+ * Standard AgentScore identity security schemes. Plug into `components.securitySchemes`.
+ */
+declare function agentscoreSecuritySchemes(): Record<string, unknown>;
+/**
+ * Standard AgentScore denial response schemas. Plug into `components.schemas` so OpenAPI
+ * validators understand the 403 body shape across denial codes.
+ */
+declare function agentscoreDenialSchemas(): Record<string, unknown>;
+/**
+ * Standard 402 PaymentRequired body schema (for AgentScore-extended 402 responses).
+ * Includes the rails, identity metadata, agent_instructions, pricing, and x402-compliance
+ * fields a typical merchant emits via build402Body.
+ */
+declare function agentscorePaymentRequiredSchema(): Record<string, unknown>;
+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;
+}
+/**
+ * Convenience: returns a `components` snippet ready to merge into an OpenAPI document.
+ *
+ *   const spec = {
+ *     openapi: '3.1.0',
+ *     info: { title: 'My Merchant API', version: '1.0' },
+ *     paths: {...},
+ *     components: { ...agentscoreOpenApiSnippets(), schemas: { ...mySchemas, ...agentscoreOpenApiSnippets().schemas } },
+ *   };
+ *
+ * Or more idiomatically: `Object.assign(spec.components, agentscoreOpenApiSnippets())`.
+ */
+declare function agentscoreOpenApiSnippets(opts?: BuildAgentScoreOpenApiSnippetsInput): {
+    securitySchemes?: Record<string, unknown>;
+    schemas?: Record<string, unknown>;
+};
+
+/**
+ * Default discovery paths emitted by `@agent-score/commerce` builders. These are
+ * the public-by-design endpoints agents and crawlers fetch to learn the
+ * merchant's shape: OpenAPI, llms.txt, MPP well-known, A2A agent card, UCP profile.
+ * They should NOT carry `X-Robots-Tag: noindex` since the whole point is for
+ * agents (and search/discovery crawlers) to find them.
+ *
+ * Everything else on an agent-only API should noindex by default — there's no
+ * human-shaped HTML to surface to general search engines, and accidental
+ * indexing leaks transactional endpoints into noisy SERPs.
+ */
+declare const defaultDiscoveryPaths: ReadonlySet<string>;
+/**
+ * Pure predicate for "is this path a known discovery surface?". Compose this
+ * into your own framework's middleware when you don't want the bundled Hono
+ * wrapper. Custom paths are the union with the defaults — pass `replace: true`
+ * to skip the defaults.
+ */
+declare function isDiscoveryPath(path: string, options?: {
+    customPaths?: Iterable<string>;
+    replace?: boolean;
+}): boolean;
+interface NoindexNonDiscoveryOptions {
+    /** Additional discovery paths beyond the defaults (e.g. `/sitemap.xml`,
+     *  `/.well-known/foo`). Merged with the defaults unless `replacePaths: true`. */
+    customPaths?: Iterable<string>;
+    /** When true, ignore the bundled defaults and only treat `customPaths` as
+     *  discovery surfaces. Use when the merchant deliberately chooses a different
+     *  set (e.g. omits `/openapi.json` from a closed API). */
+    replacePaths?: boolean;
+    /** Override the X-Robots-Tag value applied to non-discovery paths. Defaults to
+     *  the standard "noindex, nofollow, noarchive, nosnippet" tuple — change only
+     *  if you have a very specific crawl-shape requirement. */
+    robotsTag?: string;
+}
+/**
+ * Hono middleware. Mount globally near the top of your middleware stack:
+ *
+ *   app.use('*', noindexNonDiscoveryPaths());
+ *   app.use('*', noindexNonDiscoveryPaths({ customPaths: ['/sitemap.xml'] }));
+ *
+ * Per-framework variants (`noindexNonDiscoveryPathsExpress`,
+ * `noindexNonDiscoveryPathsFastify`, `noindexNonDiscoveryPathsWeb`) ship below.
+ * For Next.js Route Handlers, use `applyNoindexHeader(response, path, opts)`
+ * inline since route handlers don't have a global mount point.
+ */
+declare function noindexNonDiscoveryPaths(options?: NoindexNonDiscoveryOptions): (c: {
+    req: {
+        path: string;
+    };
+    header: (k: string, v: string) => void;
+}, next: () => Promise<void>) => Promise<void>;
+/** Express middleware. Sets the header before `next()` so route handlers can
+ *  override per-response if they need to. */
+declare function noindexNonDiscoveryPathsExpress(options?: NoindexNonDiscoveryOptions): (req: {
+    path: string;
+}, res: {
+    setHeader: (name: string, value: string) => void;
+}, next: () => void) => void;
+/** Fastify plugin (use as `app.register(noindexNonDiscoveryPathsFastify, opts)`).
+ *  Registers an `onRequest` hook so the header lands on every response. */
+interface FastifyReqLike {
+    url?: string;
+    routerPath?: string;
+}
+interface FastifyReplyLike {
+    header: (name: string, value: string) => void;
+}
+interface FastifyAppLike {
+    addHook(event: 'onRequest', handler: (req: FastifyReqLike, reply: FastifyReplyLike, done: () => void) => void): void;
+}
+declare function noindexNonDiscoveryPathsFastify(app: FastifyAppLike, options: NoindexNonDiscoveryOptions | undefined, done: () => void): void;
+/** Web Fetch / Cloudflare Workers / Deno / Bun helper. Returns a wrapped
+ *  Response that carries `X-Robots-Tag` on non-discovery paths. Pair with the
+ *  request's URL pathname:
+ *
+ *    return wrapNoindexResponse(new URL(req.url).pathname, response);
+ */
+declare function wrapNoindexResponse(path: string, response: Response, options?: NoindexNonDiscoveryOptions): Response;
+/** Next.js Route Handler helper. Call inline before returning the Response:
+ *
+ *    export async function POST(req: Request) {
+ *      const path = new URL(req.url).pathname;
+ *      const res = Response.json({...});
+ *      return applyNoindexHeader(res, path);
+ *    }
+ *
+ *  Same wrapper shape as the Web Fetch helper — exported separately for clarity
+ *  in Next.js docs/examples. */
+declare const applyNoindexHeader: typeof wrapNoindexResponse;
+
+export { type BazaarDiscoveryConfig, type BuildAgentScoreOpenApiSnippetsInput, type BuildLlmsTxtInput, type DiscoveryProbeOptions, type DiscoveryProbeResponse, type LlmsTxtIdentitySectionInput, type LlmsTxtPaymentSectionInput, type NoindexNonDiscoveryOptions, type PaymentMethodConfig, type RequestLike, type WellKnownMppInput, agentscoreDenialSchemas, agentscoreOpenApiSnippets, agentscorePaymentRequiredSchema, agentscoreSecuritySchemes, applyNoindexHeader, buildDiscoveryProbeResponse, buildLlmsTxt, buildWellKnownMpp, createBazaarDiscovery, defaultDiscoveryPaths, isDiscoveryPath, isDiscoveryProbeRequest, llmsTxtIdentitySection, llmsTxtPaymentSection, noindexNonDiscoveryPaths, noindexNonDiscoveryPathsExpress, noindexNonDiscoveryPathsFastify, sampleX402AcceptForNetwork, wrapNoindexResponse };