@agent-score/commerce 1.1.0 → 1.3.0

package/dist/discovery/index.d.mts

@@ -1,3 +1,6 @@
+import { R as RailKey, C as CompatibleClients } from '../agent_instructions-DiMSGkdm.mjs';
+export { f as compatibleClientsByRails } from '../agent_instructions-DiMSGkdm.mjs';
+
 /**
  * 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
@@ -177,6 +180,40 @@ interface WellKnownMppInput {
  */
 declare function buildWellKnownMpp(input: WellKnownMppInput): Record<string, unknown>;
 
+/**
+ * `buildWellKnownX402`: emits the x402scan v1 `/.well-known/x402` discovery shape.
+ *
+ * x402scan accepts three discovery strategies (OpenAPI > `/.well-known/x402` > endpoint
+ * probe). Most AgentScore merchants already publish a richer `/.well-known/mpp.json`,
+ * but x402scan's strict parser only reads the v1 shape, so we emit both. The two
+ * coexist on different paths.
+ *
+ * Spec (verbatim, x402scan):
+ *
+ *   {
+ *     "version": 1,
+ *     "resources": ["POST /api/route", ...]
+ *   }
+ *
+ * Resource entries are `"METHOD /path"` strings, not objects. Runtime 402 behavior
+ * is authoritative over this static metadata.
+ */
+interface WellKnownX402Resource {
+    /** HTTP method, uppercase: `'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'`. */
+    method: string;
+    /** Path, leading slash: `'/purchase'`. */
+    path: string;
+}
+interface BuildWellKnownX402Input {
+    /** Invocable, payment-required routes. Each entry becomes `"METHOD /path"`. */
+    resources: WellKnownX402Resource[];
+}
+interface WellKnownX402Document {
+    version: 1;
+    resources: string[];
+}
+declare function buildWellKnownX402(input: BuildWellKnownX402Input): WellKnownX402Document;
+
 interface LlmsTxtIdentitySectionInput {
     /** When true, include the AgentScore identity-paths explanation (wallet vs operator-token). */
     agentscore?: boolean;
@@ -196,7 +233,7 @@ interface LlmsTxtIdentitySectionInput {
 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)[];
+    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. */
     appUrl: string;
     /**
@@ -250,8 +287,20 @@ declare function buildLlmsTxt(input: BuildLlmsTxtInput): string;
  */
 /**
  * Standard AgentScore identity security schemes. Plug into `components.securitySchemes`.
+ *
+ * Includes `siwx` (Sign-In With X) per the x402scan discovery spec so identity-gated
+ * operations can declare `security: [{ siwx: [] }]` and stay classified as identity-only,
+ * not paid.
  */
 declare function agentscoreSecuritySchemes(): Record<string, unknown>;
+/**
+ * Sign-In With X security scheme entry, per the x402scan discovery spec.
+ *
+ * Reference it on identity-gated (but free) operations as
+ * `security: [{ siwx: [] }]`. Do NOT also attach `x-payment-info` to those routes,
+ * x402scan will misclassify them as paid.
+ */
+declare function siwxSecurityScheme(): Record<string, unknown>;
 /**
  * Standard AgentScore denial response schemas. Plug into `components.schemas` so OpenAPI
  * validators understand the 403 body shape across denial codes.
@@ -263,6 +312,84 @@ declare function agentscoreDenialSchemas(): Record<string, unknown>;
  * fields a typical merchant emits via build402Body.
  */
 declare function agentscorePaymentRequiredSchema(): Record<string, unknown>;
+/**
+ * Per-operation `x-payment-info` extension, per the x402scan discovery spec.
+ *
+ * Every payment-required OpenAPI operation should carry this block alongside a
+ * 402 response. Tells discovery crawlers (x402scan, agent CLIs) the static price
+ * and which protocols the route accepts. Runtime 402 behavior is authoritative
+ * over this static metadata; the static side is for indexability.
+ *
+ * @example fixed price across x402 + MPP Tempo
+ * ```ts
+ * Object.assign(operation, {
+ *   ...xPaymentInfoExtension({
+ *     price: { mode: 'fixed', currency: 'USD', amount: '0.10' },
+ *     protocols: [
+ *       { x402: {} },
+ *       { mpp: { method: 'tempo/charge', intent: 'pay', currency: 'USD' } },
+ *     ],
+ *   }),
+ *   responses: {
+ *     '200': {...},
+ *     '402': { description: 'Payment Required' },
+ *   },
+ * });
+ * ```
+ */
+interface XPaymentInfoFixedPrice {
+    mode: 'fixed';
+    currency: string;
+    amount: string;
+}
+interface XPaymentInfoDynamicPrice {
+    mode: 'dynamic';
+    currency: string;
+    min: string;
+    max: string;
+}
+type XPaymentInfoPrice = XPaymentInfoFixedPrice | XPaymentInfoDynamicPrice;
+interface XPaymentInfoX402Protocol {
+    x402: Record<string, unknown>;
+}
+interface XPaymentInfoMppProtocol {
+    mpp: {
+        method: string;
+        intent: string;
+        currency: string;
+    };
+}
+type XPaymentInfoProtocol = XPaymentInfoX402Protocol | XPaymentInfoMppProtocol;
+interface XPaymentInfoInput {
+    price: XPaymentInfoPrice;
+    protocols: XPaymentInfoProtocol[];
+}
+declare function xPaymentInfoExtension(input: XPaymentInfoInput): {
+    'x-payment-info': {
+        price: XPaymentInfoPrice;
+        protocols: XPaymentInfoProtocol[];
+    };
+};
+/**
+ * `info.x-guidance` extension, per the x402scan discovery spec. Spread into your
+ * OpenAPI document's `info` block to give agents a high-level prose description
+ * of how to use the API. Discovery crawlers surface this on the listing page.
+ *
+ * @example
+ * ```ts
+ * const spec = {
+ *   openapi: '3.1.0',
+ *   info: {
+ *     title: 'My Merchant API',
+ *     version: '1.0',
+ *     ...xGuidanceExtension('Wine merchant. POST /purchase with a verified operator token...'),
+ *   },
+ * };
+ * ```
+ */
+declare function xGuidanceExtension(text: string): {
+    'x-guidance': string;
+};
 interface BuildAgentScoreOpenApiSnippetsInput {
     /** Include security schemes in the snippet. Default true. */
     security?: boolean;
@@ -379,4 +506,120 @@ declare function wrapNoindexResponse(path: string, response: Response, options?:
  *  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 };
+interface SkillMdEndpoint {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    authRequired: boolean;
+    description: string;
+}
+interface SkillMdIdentityRequirements {
+    /** Whether KYC is required for gated routes. */
+    kycRequired?: boolean;
+    /** Minimum age (e.g. 21 for alcohol). */
+    minAge?: number;
+    /** Allowed-jurisdictions list (ISO 3166-1 alpha-2 country codes). */
+    allowedJurisdictions?: string[];
+    /** Whether sanctions screening is enforced. */
+    sanctionsClear?: boolean;
+}
+interface SkillMdShippingPolicy {
+    /** Allowed shipping countries (ISO 3166-1 alpha-2). */
+    allowedCountries?: string[];
+    /** Blocked US states (2-letter codes). */
+    blockedStates?: string[];
+}
+interface SkillMdLink {
+    label: string;
+    url: string;
+}
+interface BuildSkillMdInput {
+    /** Skill manifest identifier — kebab-case per agentskills.io spec: 1-64 chars, lowercase
+     *  alphanumeric + hyphens, no leading/trailing/consecutive hyphens. Validated at build
+     *  time; invalid names throw. e.g. 'example-merchant-commerce'. */
+    name: string;
+    /** Skill description — agentskills.io spec: 1-1024 chars, non-empty. Should describe both
+     *  what the skill does AND when to use it; imperative phrasing recommended ("Use when…").
+     *  Validated at build time; over-length throws. */
+    description: string;
+    /** Merchant homepage (or domain root). Emitted as `metadata.homepage` per spec
+     *  (top-level non-spec fields go under metadata). */
+    homepage: string;
+    /** Skill schema version — increment when the skill body materially changes. Emitted as
+     *  a quoted string under `metadata.version` per agentskills.io spec (metadata values
+     *  must be strings). Accepts string or number; numbers are converted. Default "1". */
+    version?: string | number;
+    /** Optional license name or path to a bundled license file. Emitted as top-level
+     *  frontmatter `license:` per spec. */
+    license?: string;
+    /** Optional environment-requirements note (max 500 chars). e.g. "Requires Node 20+".
+     *  Emitted as top-level frontmatter `compatibility:` per spec. */
+    compatibility?: string;
+    /** Optional space-separated string of pre-approved tools (experimental per spec). */
+    allowedTools?: string;
+    /** Additional caller-defined metadata entries — flat key/value strings nested under
+     *  `metadata:`. Spec requires string values. */
+    metadata?: Record<string, string | number>;
+    /** Human display name (e.g. "Example Merchant"). */
+    merchantName: string;
+    /** Optional one-line tagline appearing under the title. */
+    tagline?: string;
+    /** Optional short prose intro describing what the merchant offers. Renders below the title. */
+    intro?: string;
+    /** Files / well-known URLs surfaced under the "Important Files" table. The skill.md URL
+     *  itself is added automatically — list other discovery surfaces (llms.txt, mpp.json,
+     *  openapi.json, agent-card.json). */
+    files?: SkillMdLink[];
+    /** Rails the merchant accepts. Drives the Payment + Compatible Clients sections. Order
+     *  is preserved in render. Default to the rails actually declared on the merchant's
+     *  `respond402` config — keep these in sync. */
+    acceptedRails: RailKey[];
+    /** Override the per-rail compatible-clients matrix. When omitted, derives from
+     *  `acceptedRails` via the SDK's smoke-verified default. Override keys not in
+     *  `acceptedRails` are dropped (the rail isn't accepted, so the row isn't rendered). */
+    compatibleClients?: CompatibleClients;
+    /** Identity requirements as agent-observable outcomes (kyc / age / jurisdiction /
+     *  sanctions). Internal posture (`failOpen`, mount strategy, KYC vendor) is intentionally
+     *  not part of this shape — agents act on outcomes, not implementation. */
+    identity?: SkillMdIdentityRequirements;
+    /** URL to the identity-bootstrap skill. Linked from the Identity Prerequisite section
+     *  so an agent without a Passport can follow the bootstrap before attempting purchase. */
+    identityBootstrapUrl?: string;
+    /** Shipping policy, for physical-goods merchants. Omit for digital merchants. */
+    shipping?: SkillMdShippingPolicy;
+    /** Agent-facing endpoints — path, method, whether auth is required, brief purpose. */
+    endpoints: SkillMdEndpoint[];
+    /** When this skill should fire (skill loader uses for trigger matching). */
+    triggers: string[];
+    /** Optional numbered onboarding steps. Each entry renders as a numbered list item;
+     *  may include shell snippets in markdown code fences. */
+    onboardingSteps?: string[];
+    /** Support / homepage / docs links rendered in the "Support" section. */
+    supportLinks?: SkillMdLink[];
+    /** When true (default), append a footer noting clients can refresh skill.md to pick
+     *  up new endpoints. Set to false to suppress. */
+    refreshFooter?: boolean;
+}
+/**
+ * Render an agentskills.io-compatible `skill.md` for an agent-commerce merchant.
+ *
+ * Output is YAML frontmatter (`name` / `description` / optional `license` /
+ * `compatibility` / `allowed-tools` / `metadata`) followed by markdown sections
+ * describing payment rails, identity requirements, endpoints, triggers, and support
+ * links — strictly the agent-facing contract, with no internal posture (no `failOpen`,
+ * no mount-strategy names, no KYC vendor, no defense parameters).
+ *
+ * Spec compliance:
+ *   - `name` validated against the agentskills.io regex (lowercase alphanumeric + hyphens,
+ *     no leading/trailing/consecutive hyphens, ≤64 chars).
+ *   - `description` length capped at 1024.
+ *   - `metadata` values always emitted as quoted strings.
+ *   - `description` (and other user scalars) double-quoted to defuse the colon /
+ *     newline / quote pitfall the spec explicitly warns about.
+ *
+ * The compatible-clients-per-rail table sources from the same SDK constant
+ * (`compatibleClientsByRails`) that drives the live 402 body's `compatible_clients`
+ * field, so updating a smoke-verified client in one place propagates to every surface.
+ */
+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 };

package/dist/discovery/index.d.ts

@@ -1,3 +1,6 @@
+import { R as RailKey, C as CompatibleClients } from '../agent_instructions-DiMSGkdm.js';
+export { f as compatibleClientsByRails } from '../agent_instructions-DiMSGkdm.js';
+
 /**
  * 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
@@ -177,6 +180,40 @@ interface WellKnownMppInput {
  */
 declare function buildWellKnownMpp(input: WellKnownMppInput): Record<string, unknown>;
 
+/**
+ * `buildWellKnownX402`: emits the x402scan v1 `/.well-known/x402` discovery shape.
+ *
+ * x402scan accepts three discovery strategies (OpenAPI > `/.well-known/x402` > endpoint
+ * probe). Most AgentScore merchants already publish a richer `/.well-known/mpp.json`,
+ * but x402scan's strict parser only reads the v1 shape, so we emit both. The two
+ * coexist on different paths.
+ *
+ * Spec (verbatim, x402scan):
+ *
+ *   {
+ *     "version": 1,
+ *     "resources": ["POST /api/route", ...]
+ *   }
+ *
+ * Resource entries are `"METHOD /path"` strings, not objects. Runtime 402 behavior
+ * is authoritative over this static metadata.
+ */
+interface WellKnownX402Resource {
+    /** HTTP method, uppercase: `'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'`. */
+    method: string;
+    /** Path, leading slash: `'/purchase'`. */
+    path: string;
+}
+interface BuildWellKnownX402Input {
+    /** Invocable, payment-required routes. Each entry becomes `"METHOD /path"`. */
+    resources: WellKnownX402Resource[];
+}
+interface WellKnownX402Document {
+    version: 1;
+    resources: string[];
+}
+declare function buildWellKnownX402(input: BuildWellKnownX402Input): WellKnownX402Document;
+
 interface LlmsTxtIdentitySectionInput {
     /** When true, include the AgentScore identity-paths explanation (wallet vs operator-token). */
     agentscore?: boolean;
@@ -196,7 +233,7 @@ interface LlmsTxtIdentitySectionInput {
 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)[];
+    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. */
     appUrl: string;
     /**
@@ -250,8 +287,20 @@ declare function buildLlmsTxt(input: BuildLlmsTxtInput): string;
  */
 /**
  * Standard AgentScore identity security schemes. Plug into `components.securitySchemes`.
+ *
+ * Includes `siwx` (Sign-In With X) per the x402scan discovery spec so identity-gated
+ * operations can declare `security: [{ siwx: [] }]` and stay classified as identity-only,
+ * not paid.
  */
 declare function agentscoreSecuritySchemes(): Record<string, unknown>;
+/**
+ * Sign-In With X security scheme entry, per the x402scan discovery spec.
+ *
+ * Reference it on identity-gated (but free) operations as
+ * `security: [{ siwx: [] }]`. Do NOT also attach `x-payment-info` to those routes,
+ * x402scan will misclassify them as paid.
+ */
+declare function siwxSecurityScheme(): Record<string, unknown>;
 /**
  * Standard AgentScore denial response schemas. Plug into `components.schemas` so OpenAPI
  * validators understand the 403 body shape across denial codes.
@@ -263,6 +312,84 @@ declare function agentscoreDenialSchemas(): Record<string, unknown>;
  * fields a typical merchant emits via build402Body.
  */
 declare function agentscorePaymentRequiredSchema(): Record<string, unknown>;
+/**
+ * Per-operation `x-payment-info` extension, per the x402scan discovery spec.
+ *
+ * Every payment-required OpenAPI operation should carry this block alongside a
+ * 402 response. Tells discovery crawlers (x402scan, agent CLIs) the static price
+ * and which protocols the route accepts. Runtime 402 behavior is authoritative
+ * over this static metadata; the static side is for indexability.
+ *
+ * @example fixed price across x402 + MPP Tempo
+ * ```ts
+ * Object.assign(operation, {
+ *   ...xPaymentInfoExtension({
+ *     price: { mode: 'fixed', currency: 'USD', amount: '0.10' },
+ *     protocols: [
+ *       { x402: {} },
+ *       { mpp: { method: 'tempo/charge', intent: 'pay', currency: 'USD' } },
+ *     ],
+ *   }),
+ *   responses: {
+ *     '200': {...},
+ *     '402': { description: 'Payment Required' },
+ *   },
+ * });
+ * ```
+ */
+interface XPaymentInfoFixedPrice {
+    mode: 'fixed';
+    currency: string;
+    amount: string;
+}
+interface XPaymentInfoDynamicPrice {
+    mode: 'dynamic';
+    currency: string;
+    min: string;
+    max: string;
+}
+type XPaymentInfoPrice = XPaymentInfoFixedPrice | XPaymentInfoDynamicPrice;
+interface XPaymentInfoX402Protocol {
+    x402: Record<string, unknown>;
+}
+interface XPaymentInfoMppProtocol {
+    mpp: {
+        method: string;
+        intent: string;
+        currency: string;
+    };
+}
+type XPaymentInfoProtocol = XPaymentInfoX402Protocol | XPaymentInfoMppProtocol;
+interface XPaymentInfoInput {
+    price: XPaymentInfoPrice;
+    protocols: XPaymentInfoProtocol[];
+}
+declare function xPaymentInfoExtension(input: XPaymentInfoInput): {
+    'x-payment-info': {
+        price: XPaymentInfoPrice;
+        protocols: XPaymentInfoProtocol[];
+    };
+};
+/**
+ * `info.x-guidance` extension, per the x402scan discovery spec. Spread into your
+ * OpenAPI document's `info` block to give agents a high-level prose description
+ * of how to use the API. Discovery crawlers surface this on the listing page.
+ *
+ * @example
+ * ```ts
+ * const spec = {
+ *   openapi: '3.1.0',
+ *   info: {
+ *     title: 'My Merchant API',
+ *     version: '1.0',
+ *     ...xGuidanceExtension('Wine merchant. POST /purchase with a verified operator token...'),
+ *   },
+ * };
+ * ```
+ */
+declare function xGuidanceExtension(text: string): {
+    'x-guidance': string;
+};
 interface BuildAgentScoreOpenApiSnippetsInput {
     /** Include security schemes in the snippet. Default true. */
     security?: boolean;
@@ -379,4 +506,120 @@ declare function wrapNoindexResponse(path: string, response: Response, options?:
  *  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 };
+interface SkillMdEndpoint {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    authRequired: boolean;
+    description: string;
+}
+interface SkillMdIdentityRequirements {
+    /** Whether KYC is required for gated routes. */
+    kycRequired?: boolean;
+    /** Minimum age (e.g. 21 for alcohol). */
+    minAge?: number;
+    /** Allowed-jurisdictions list (ISO 3166-1 alpha-2 country codes). */
+    allowedJurisdictions?: string[];
+    /** Whether sanctions screening is enforced. */
+    sanctionsClear?: boolean;
+}
+interface SkillMdShippingPolicy {
+    /** Allowed shipping countries (ISO 3166-1 alpha-2). */
+    allowedCountries?: string[];
+    /** Blocked US states (2-letter codes). */
+    blockedStates?: string[];
+}
+interface SkillMdLink {
+    label: string;
+    url: string;
+}
+interface BuildSkillMdInput {
+    /** Skill manifest identifier — kebab-case per agentskills.io spec: 1-64 chars, lowercase
+     *  alphanumeric + hyphens, no leading/trailing/consecutive hyphens. Validated at build
+     *  time; invalid names throw. e.g. 'example-merchant-commerce'. */
+    name: string;
+    /** Skill description — agentskills.io spec: 1-1024 chars, non-empty. Should describe both
+     *  what the skill does AND when to use it; imperative phrasing recommended ("Use when…").
+     *  Validated at build time; over-length throws. */
+    description: string;
+    /** Merchant homepage (or domain root). Emitted as `metadata.homepage` per spec
+     *  (top-level non-spec fields go under metadata). */
+    homepage: string;
+    /** Skill schema version — increment when the skill body materially changes. Emitted as
+     *  a quoted string under `metadata.version` per agentskills.io spec (metadata values
+     *  must be strings). Accepts string or number; numbers are converted. Default "1". */
+    version?: string | number;
+    /** Optional license name or path to a bundled license file. Emitted as top-level
+     *  frontmatter `license:` per spec. */
+    license?: string;
+    /** Optional environment-requirements note (max 500 chars). e.g. "Requires Node 20+".
+     *  Emitted as top-level frontmatter `compatibility:` per spec. */
+    compatibility?: string;
+    /** Optional space-separated string of pre-approved tools (experimental per spec). */
+    allowedTools?: string;
+    /** Additional caller-defined metadata entries — flat key/value strings nested under
+     *  `metadata:`. Spec requires string values. */
+    metadata?: Record<string, string | number>;
+    /** Human display name (e.g. "Example Merchant"). */
+    merchantName: string;
+    /** Optional one-line tagline appearing under the title. */
+    tagline?: string;
+    /** Optional short prose intro describing what the merchant offers. Renders below the title. */
+    intro?: string;
+    /** Files / well-known URLs surfaced under the "Important Files" table. The skill.md URL
+     *  itself is added automatically — list other discovery surfaces (llms.txt, mpp.json,
+     *  openapi.json, agent-card.json). */
+    files?: SkillMdLink[];
+    /** Rails the merchant accepts. Drives the Payment + Compatible Clients sections. Order
+     *  is preserved in render. Default to the rails actually declared on the merchant's
+     *  `respond402` config — keep these in sync. */
+    acceptedRails: RailKey[];
+    /** Override the per-rail compatible-clients matrix. When omitted, derives from
+     *  `acceptedRails` via the SDK's smoke-verified default. Override keys not in
+     *  `acceptedRails` are dropped (the rail isn't accepted, so the row isn't rendered). */
+    compatibleClients?: CompatibleClients;
+    /** Identity requirements as agent-observable outcomes (kyc / age / jurisdiction /
+     *  sanctions). Internal posture (`failOpen`, mount strategy, KYC vendor) is intentionally
+     *  not part of this shape — agents act on outcomes, not implementation. */
+    identity?: SkillMdIdentityRequirements;
+    /** URL to the identity-bootstrap skill. Linked from the Identity Prerequisite section
+     *  so an agent without a Passport can follow the bootstrap before attempting purchase. */
+    identityBootstrapUrl?: string;
+    /** Shipping policy, for physical-goods merchants. Omit for digital merchants. */
+    shipping?: SkillMdShippingPolicy;
+    /** Agent-facing endpoints — path, method, whether auth is required, brief purpose. */
+    endpoints: SkillMdEndpoint[];
+    /** When this skill should fire (skill loader uses for trigger matching). */
+    triggers: string[];
+    /** Optional numbered onboarding steps. Each entry renders as a numbered list item;
+     *  may include shell snippets in markdown code fences. */
+    onboardingSteps?: string[];
+    /** Support / homepage / docs links rendered in the "Support" section. */
+    supportLinks?: SkillMdLink[];
+    /** When true (default), append a footer noting clients can refresh skill.md to pick
+     *  up new endpoints. Set to false to suppress. */
+    refreshFooter?: boolean;
+}
+/**
+ * Render an agentskills.io-compatible `skill.md` for an agent-commerce merchant.
+ *
+ * Output is YAML frontmatter (`name` / `description` / optional `license` /
+ * `compatibility` / `allowed-tools` / `metadata`) followed by markdown sections
+ * describing payment rails, identity requirements, endpoints, triggers, and support
+ * links — strictly the agent-facing contract, with no internal posture (no `failOpen`,
+ * no mount-strategy names, no KYC vendor, no defense parameters).
+ *
+ * Spec compliance:
+ *   - `name` validated against the agentskills.io regex (lowercase alphanumeric + hyphens,
+ *     no leading/trailing/consecutive hyphens, ≤64 chars).
+ *   - `description` length capped at 1024.
+ *   - `metadata` values always emitted as quoted strings.
+ *   - `description` (and other user scalars) double-quoted to defuse the colon /
+ *     newline / quote pitfall the spec explicitly warns about.
+ *
+ * The compatible-clients-per-rail table sources from the same SDK constant
+ * (`compatibleClientsByRails`) that drives the live 402 body's `compatible_clients`
+ * field, so updating a smoke-verified client in one place propagates to every surface.
+ */
+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 };