@x402/extensions 2.3.1 → 2.4.0

package/dist/cjs/{index-DvDlinmy.d.ts → index-G8RNfr6X.d.ts}

@@ -1,5 +1,5 @@
+import { FacilitatorExtension, ResourceServerExtension, PaymentPayload, PaymentRequirements, PaymentRequirementsV1 } from '@x402/core/types';
 import { BodyMethods, QueryParamMethods, HTTPFacilitatorClient } from '@x402/core/http';
-import { ResourceServerExtension, PaymentPayload, PaymentRequirements, PaymentRequirementsV1 } from '@x402/core/types';
 
 /**
  * Shared type utilities for x402 extensions
@@ -24,20 +24,17 @@ type WithExtensions<T, E> = T extends {
 };
 
 /**
- * Type definitions for the Bazaar Discovery Extension
+ * HTTP-specific type definitions for the Bazaar Discovery Extension
  */
 
-/**
- * Extension identifier constant for the Bazaar discovery extension
- */
-declare const BAZAAR = "bazaar";
 /**
  * Discovery info for query parameter methods (GET, HEAD, DELETE)
  */
 interface QueryDiscoveryInfo {
     input: {
         type: "http";
-        method: QueryParamMethods;
+        /** Absent at declaration time; set by bazaarResourceServerExtension.enrichDeclaration */
+        method?: QueryParamMethods;
         queryParams?: Record<string, unknown>;
         headers?: Record<string, string>;
     };
@@ -53,7 +50,8 @@ interface QueryDiscoveryInfo {
 interface BodyDiscoveryInfo {
     input: {
         type: "http";
-        method: BodyMethods;
+        /** Absent at declaration time; set by bazaarResourceServerExtension.enrichDeclaration */
+        method?: BodyMethods;
         bodyType: "json" | "form-data" | "text";
         body: Record<string, unknown>;
         queryParams?: Record<string, unknown>;
@@ -65,10 +63,6 @@ interface BodyDiscoveryInfo {
         example?: unknown;
     };
 }
-/**
- * Combined discovery info type
- */
-type DiscoveryInfo = QueryDiscoveryInfo | BodyDiscoveryInfo;
 /**
  * Discovery extension for query parameter methods (GET, HEAD, DELETE)
  */
@@ -166,10 +160,6 @@ interface BodyDiscoveryExtension {
         required: ["input"];
     };
 }
-/**
- * Combined discovery extension type
- */
-type DiscoveryExtension = QueryDiscoveryExtension | BodyDiscoveryExtension;
 interface DeclareQueryDiscoveryExtensionConfig {
     method?: QueryParamMethods;
     input?: Record<string, unknown>;
@@ -189,7 +179,124 @@ interface DeclareBodyDiscoveryExtensionConfig {
         schema?: Record<string, unknown>;
     };
 }
-type DeclareDiscoveryExtensionConfig = DeclareQueryDiscoveryExtensionConfig | DeclareBodyDiscoveryExtensionConfig;
+interface DiscoveredHTTPResource {
+    resourceUrl: string;
+    description?: string;
+    mimeType?: string;
+    /** Present after server extension enrichment; may be absent for pre-enrichment data */
+    method?: string;
+    x402Version: number;
+    discoveryInfo: DiscoveryInfo;
+}
+declare const isQueryExtensionConfig: (config: DeclareQueryDiscoveryExtensionConfig | DeclareBodyDiscoveryExtensionConfig) => config is DeclareQueryDiscoveryExtensionConfig;
+declare const isBodyExtensionConfig: (config: DeclareQueryDiscoveryExtensionConfig | DeclareBodyDiscoveryExtensionConfig) => config is DeclareBodyDiscoveryExtensionConfig;
+
+/**
+ * MCP-specific type definitions for the Bazaar Discovery Extension
+ */
+
+/**
+ * Discovery info for MCP tools
+ */
+interface McpDiscoveryInfo {
+    input: {
+        type: "mcp";
+        toolName: string;
+        description?: string;
+        transport?: "streamable-http" | "sse";
+        inputSchema: Record<string, unknown>;
+        example?: Record<string, unknown>;
+    };
+    output?: {
+        type?: string;
+        format?: string;
+        example?: unknown;
+    };
+}
+/**
+ * Discovery extension for MCP tools
+ */
+interface McpDiscoveryExtension {
+    info: McpDiscoveryInfo;
+    schema: {
+        $schema: "https://json-schema.org/draft/2020-12/schema";
+        type: "object";
+        properties: {
+            input: {
+                type: "object";
+                properties: {
+                    type: {
+                        type: "string";
+                        const: "mcp";
+                    };
+                    toolName: {
+                        type: "string";
+                    };
+                    description?: {
+                        type: "string";
+                    };
+                    transport?: {
+                        type: "string";
+                        enum: ["streamable-http", "sse"];
+                    };
+                    inputSchema: Record<string, unknown>;
+                    example?: Record<string, unknown>;
+                };
+                required: ("type" | "toolName" | "inputSchema")[];
+                additionalProperties?: boolean;
+            };
+            output?: {
+                type: "object";
+                properties?: Record<string, unknown>;
+                required?: readonly string[];
+                additionalProperties?: boolean;
+            };
+        };
+        required: ["input"];
+    };
+}
+interface DeclareMcpDiscoveryExtensionConfig {
+    toolName: string;
+    description?: string;
+    transport?: "streamable-http" | "sse";
+    inputSchema: Record<string, unknown>;
+    example?: Record<string, unknown>;
+    output?: {
+        example?: unknown;
+        schema?: Record<string, unknown>;
+    };
+}
+interface DiscoveredMCPResource {
+    resourceUrl: string;
+    description?: string;
+    mimeType?: string;
+    toolName: string;
+    x402Version: number;
+    discoveryInfo: DiscoveryInfo;
+}
+declare const isMcpExtensionConfig: (config: DeclareMcpDiscoveryExtensionConfig | Record<string, unknown>) => config is DeclareMcpDiscoveryExtensionConfig;
+
+/**
+ * Shared type definitions for the Bazaar Discovery Extension
+ *
+ * Protocol-specific types live in their own directories (http/, mcp/).
+ * This file defines the shared unions, constants, and utility types,
+ * and re-exports all protocol-specific types for backwards compatibility.
+ */
+
+/**
+ * Extension identifier for the Bazaar discovery extension.
+ */
+declare const BAZAAR: FacilitatorExtension;
+/**
+ * Combined discovery info type
+ */
+type DiscoveryInfo = QueryDiscoveryInfo | BodyDiscoveryInfo | McpDiscoveryInfo;
+/**
+ * Combined discovery extension type
+ */
+type DiscoveryExtension = QueryDiscoveryExtension | BodyDiscoveryExtension | McpDiscoveryExtension;
+type DeclareDiscoveryExtensionConfig = DeclareQueryDiscoveryExtensionConfig | DeclareBodyDiscoveryExtensionConfig | DeclareMcpDiscoveryExtensionConfig;
 /**
  * Distributive Omit - properly distributes Omit over union types.
  *
@@ -202,19 +309,20 @@ type DeclareDiscoveryExtensionConfig = DeclareQueryDiscoveryExtensionConfig | De
 type DistributiveOmit<T, K extends keyof T> = T extends T ? Omit<T, K> : never;
 /**
  * Config type for declareDiscoveryExtension function.
- * Uses DistributiveOmit to preserve bodyType discriminant in the union.
+ * Uses DistributiveOmit to preserve bodyType discriminant in the union for HTTP configs.
+ * MCP config has no `method` field so it's included directly.
  */
-type DeclareDiscoveryExtensionInput = DistributiveOmit<DeclareDiscoveryExtensionConfig, "method">;
+type DeclareDiscoveryExtensionInput = DistributiveOmit<DeclareQueryDiscoveryExtensionConfig, "method"> | DistributiveOmit<DeclareBodyDiscoveryExtensionConfig, "method"> | DeclareMcpDiscoveryExtensionConfig;
 
 /**
- * Resource Service functions for creating Bazaar discovery extensions
+ * Resource Service entry point for creating Bazaar discovery extensions
  *
- * These functions help servers declare the shape of their endpoints
- * for facilitator discovery and cataloging in the Bazaar.
+ * This module provides the unified `declareDiscoveryExtension` function that
+ * routes to protocol-specific builders in http/ and mcp/.
  */
 
 /**
- * Create a discovery extension for any HTTP method
+ * Create a discovery extension for any HTTP method or MCP tool
  *
  * This function helps servers declare how their endpoint should be called,
  * including the expected input parameters/body and output format.
@@ -260,6 +368,22 @@ type DeclareDiscoveryExtensionInput = DistributiveOmit<DeclareDiscoveryExtension
  *     example: { success: true, id: "123" }
  *   }
  * });
+ *
+ * // For an MCP tool
+ * const mcpExtension = declareDiscoveryExtension({
+ *   toolName: "financial_analysis",
+ *   description: "Analyze financial data for a given ticker",
+ *   inputSchema: {
+ *     type: "object",
+ *     properties: {
+ *       ticker: { type: "string" },
+ *     },
+ *     required: ["ticker"],
+ *   },
+ *   output: {
+ *     example: { pe_ratio: 28.5, recommendation: "hold" }
+ *   }
+ * });
  * ```
  */
 declare function declareDiscoveryExtension(config: DeclareDiscoveryExtensionInput): Record<string, DiscoveryExtension>;
@@ -301,44 +425,8 @@ interface ValidationResult {
  * ```
  */
 declare function validateDiscoveryExtension(extension: DiscoveryExtension): ValidationResult;
-/**
- * Extracts the discovery info from payment payload and requirements
- *
- * This function handles both v2 (extensions) and v1 (outputSchema) formats.
- *
- * For v2: Discovery info is in PaymentPayload.extensions (client copied it from PaymentRequired)
- * For v1: Discovery info is in PaymentRequirements.outputSchema
- *
- * V1 data is automatically transformed to v2 DiscoveryInfo format, making smart
- * assumptions about field names (queryParams/query/params for GET, bodyFields/body/data for POST, etc.)
- *
- * @param paymentPayload - The payment payload containing extensions (v2) and version info
- * @param paymentRequirements - The payment requirements (contains outputSchema for v1)
- * @param validate - Whether to validate v2 extensions before extracting (default: true)
- * @returns The discovery info in v2 format if present, or null if not discoverable
- *
- * @example
- * ```typescript
- * // V2 - extensions are in PaymentPayload
- * const info = extractDiscoveryInfo(paymentPayload, paymentRequirements);
- *
- * // V1 - discovery info is in PaymentRequirements.outputSchema
- * const info = extractDiscoveryInfo(paymentPayloadV1, paymentRequirementsV1);
- *
- * if (info) {
- *   // Both v1 and v2 return the same DiscoveryInfo structure
- *   console.log("Method:", info.input.method);
- * }
- * ```
- */
-interface DiscoveredResource {
-    resourceUrl: string;
-    description?: string;
-    mimeType?: string;
-    method: string;
-    x402Version: number;
-    discoveryInfo: DiscoveryInfo;
-}
+
+type DiscoveredResource = DiscoveredHTTPResource | DiscoveredMCPResource;
 /**
  * Extracts discovery information from payment payload and requirements.
  * Combines resource URL, HTTP method, version, and discovery info into a single object.
@@ -490,7 +578,6 @@ declare function extractResourceMetadataV1(paymentRequirements: PaymentRequireme
 interface ListDiscoveryResourcesParams {
     /**
      * Filter by protocol type (e.g., "http", "mcp").
-     * Currently, the only supported protocol type is "http".
      */
     type?: string;
     /**
@@ -572,4 +659,4 @@ interface BazaarClientExtension {
  */
 declare function withBazaar<T extends HTTPFacilitatorClient>(client: T): WithExtensions<T, BazaarClientExtension>;
 
-export { BAZAAR as B, type DiscoveredResource as D, type ListDiscoveryResourcesParams as L, type QueryDiscoveryExtension as Q, type ValidationResult as V, type WithExtensions as W, type BazaarClientExtension as a, type BodyDiscoveryExtension as b, type BodyDiscoveryInfo as c, type DiscoveryExtension as d, type DiscoveryInfo as e, type DiscoveryResource as f, type DiscoveryResourcesResponse as g, type QueryDiscoveryInfo as h, bazaarResourceServerExtension as i, declareDiscoveryExtension as j, extractDiscoveryInfo as k, extractDiscoveryInfoFromExtension as l, extractDiscoveryInfoV1 as m, extractResourceMetadataV1 as n, isDiscoverableV1 as o, validateDiscoveryExtension as p, validateAndExtract as v, withBazaar as w };
+export { validateAndExtract as A, BAZAAR as B, validateDiscoveryExtension as C, type DeclareBodyDiscoveryExtensionConfig as D, withBazaar as E, type ListDiscoveryResourcesParams as L, type McpDiscoveryExtension as M, type QueryDiscoveryExtension as Q, type ValidationResult as V, type WithExtensions as W, type BazaarClientExtension as a, type BodyDiscoveryExtension as b, type BodyDiscoveryInfo as c, type DeclareDiscoveryExtensionConfig as d, type DeclareDiscoveryExtensionInput as e, type DeclareMcpDiscoveryExtensionConfig as f, type DeclareQueryDiscoveryExtensionConfig as g, type DiscoveredHTTPResource as h, type DiscoveredMCPResource as i, type DiscoveredResource as j, type DiscoveryExtension as k, type DiscoveryInfo as l, type DiscoveryResource as m, type DiscoveryResourcesResponse as n, type McpDiscoveryInfo as o, type QueryDiscoveryInfo as p, bazaarResourceServerExtension as q, declareDiscoveryExtension as r, extractDiscoveryInfo as s, extractDiscoveryInfoFromExtension as t, extractDiscoveryInfoV1 as u, extractResourceMetadataV1 as v, isBodyExtensionConfig as w, isDiscoverableV1 as x, isMcpExtensionConfig as y, isQueryExtensionConfig as z };

package/dist/cjs/index.d.ts

@@ -1,6 +1,134 @@
-export { B as BAZAAR, a as BazaarClientExtension, b as BodyDiscoveryExtension, c as BodyDiscoveryInfo, D as DiscoveredResource, d as DiscoveryExtension, e as DiscoveryInfo, f as DiscoveryResource, g as DiscoveryResourcesResponse, L as ListDiscoveryResourcesParams, Q as QueryDiscoveryExtension, h as QueryDiscoveryInfo, V as ValidationResult, W as WithExtensions, i as bazaarResourceServerExtension, j as declareDiscoveryExtension, k as extractDiscoveryInfo, l as extractDiscoveryInfoFromExtension, m as extractDiscoveryInfoV1, n as extractResourceMetadataV1, o as isDiscoverableV1, v as validateAndExtract, p as validateDiscoveryExtension, w as withBazaar } from './index-DvDlinmy.js';
+export { B as BAZAAR, a as BazaarClientExtension, b as BodyDiscoveryExtension, c as BodyDiscoveryInfo, D as DeclareBodyDiscoveryExtensionConfig, d as DeclareDiscoveryExtensionConfig, e as DeclareDiscoveryExtensionInput, f as DeclareMcpDiscoveryExtensionConfig, g as DeclareQueryDiscoveryExtensionConfig, h as DiscoveredHTTPResource, i as DiscoveredMCPResource, j as DiscoveredResource, k as DiscoveryExtension, l as DiscoveryInfo, m as DiscoveryResource, n as DiscoveryResourcesResponse, L as ListDiscoveryResourcesParams, M as McpDiscoveryExtension, o as McpDiscoveryInfo, Q as QueryDiscoveryExtension, p as QueryDiscoveryInfo, V as ValidationResult, W as WithExtensions, q as bazaarResourceServerExtension, r as declareDiscoveryExtension, s as extractDiscoveryInfo, t as extractDiscoveryInfoFromExtension, u as extractDiscoveryInfoV1, v as extractResourceMetadataV1, w as isBodyExtensionConfig, x as isDiscoverableV1, y as isMcpExtensionConfig, z as isQueryExtensionConfig, A as validateAndExtract, C as validateDiscoveryExtension, E as withBazaar } from './index-G8RNfr6X.js';
 export { CompleteSIWxInfo, CreateSIWxHookOptions, DeclareSIWxOptions, EVMMessageVerifier, EVMSigner, InMemorySIWxStorage, SIGN_IN_WITH_X, SIWxExtension, SIWxExtensionInfo, SIWxExtensionSchema, SIWxHookEvent, SIWxPayload, SIWxPayloadSchema, SIWxSigner, SIWxStorage, SIWxValidationOptions, SIWxValidationResult, SIWxVerifyOptions, SIWxVerifyResult, SOLANA_DEVNET, SOLANA_MAINNET, SOLANA_TESTNET, SignatureScheme, SignatureType, SolanaSigner, SupportedChain, buildSIWxSchema, createSIWxClientHook, createSIWxMessage, createSIWxPayload, createSIWxRequestHook, createSIWxSettleHook, declareSIWxExtension, decodeBase58, encodeBase58, encodeSIWxHeader, extractEVMChainId, extractSolanaChainReference, formatSIWEMessage, formatSIWSMessage, getEVMAddress, getSolanaAddress, isEVMSigner, isSolanaSigner, parseSIWxHeader, signEVMMessage, signSolanaMessage, siwxResourceServerExtension, validateSIWxMessage, verifyEVMSignature, verifySIWxSignature, verifySolanaSignature, wrapFetchWithSIWx } from './sign-in-with-x/index.js';
 export { PAYMENT_IDENTIFIER, PAYMENT_ID_MAX_LENGTH, PAYMENT_ID_MIN_LENGTH, PAYMENT_ID_PATTERN, PaymentIdentifierExtension, PaymentIdentifierInfo, PaymentIdentifierSchema, PaymentIdentifierValidationResult, appendPaymentIdentifierToExtensions, declarePaymentIdentifierExtension, extractAndValidatePaymentIdentifier, extractPaymentIdentifier, generatePaymentId, hasPaymentIdentifier, isPaymentIdentifierExtension, isPaymentIdentifierRequired, isValidPaymentId, paymentIdentifierResourceServerExtension, paymentIdentifierSchema, validatePaymentIdentifier, validatePaymentIdentifierRequirement } from './payment-identifier/index.js';
+import { FacilitatorExtension, PaymentPayload } from '@x402/core/types';
 import '@x402/core/http';
-import '@x402/core/types';
 import 'zod';
+
+/**
+ * Type definitions for the EIP-2612 Gas Sponsoring Extension
+ *
+ * This extension enables gasless approval of the Permit2 contract for tokens
+ * that implement EIP-2612. The client signs an off-chain permit, and the
+ * facilitator submits it on-chain via `x402Permit2Proxy.settleWithPermit`.
+ */
+
+/**
+ * Extension identifier for the EIP-2612 gas sponsoring extension.
+ */
+declare const EIP2612_GAS_SPONSORING: FacilitatorExtension;
+/**
+ * EIP-2612 gas sponsoring info populated by the client.
+ *
+ * Contains the EIP-2612 permit signature and parameters that the facilitator
+ * needs to call `x402Permit2Proxy.settleWithPermit`.
+ */
+interface Eip2612GasSponsoringInfo {
+    /** Index signature for compatibility with Record<string, unknown> */
+    [key: string]: unknown;
+    /** The address of the sender (token owner). */
+    from: string;
+    /** The address of the ERC-20 token contract. */
+    asset: string;
+    /** The address of the spender (Canonical Permit2). */
+    spender: string;
+    /** The amount to approve (uint256 as decimal string). Typically MaxUint256. */
+    amount: string;
+    /** The current EIP-2612 nonce of the sender (decimal string). */
+    nonce: string;
+    /** The timestamp at which the permit signature expires (decimal string). */
+    deadline: string;
+    /** The 65-byte concatenated EIP-2612 permit signature (r, s, v) as a hex string. */
+    signature: string;
+    /** Schema version identifier. */
+    version: string;
+}
+/**
+ * Server-side EIP-2612 gas sponsoring info included in PaymentRequired.
+ * Contains a description and version; the client populates the rest.
+ */
+interface Eip2612GasSponsoringServerInfo {
+    /** Index signature for compatibility with Record<string, unknown> */
+    [key: string]: unknown;
+    /** Human-readable description of the extension. */
+    description: string;
+    /** Schema version identifier. */
+    version: string;
+}
+/**
+ * The full extension object as it appears in PaymentRequired.extensions
+ * and PaymentPayload.extensions.
+ */
+interface Eip2612GasSponsoringExtension {
+    /** Extension info - server-provided or client-enriched. */
+    info: Eip2612GasSponsoringServerInfo | Eip2612GasSponsoringInfo;
+    /** JSON Schema describing the expected structure of info. */
+    schema: Record<string, unknown>;
+}
+
+/**
+ * Resource Service functions for declaring the EIP-2612 Gas Sponsoring extension.
+ *
+ * These functions help servers declare support for EIP-2612 gasless Permit2 approvals
+ * in the PaymentRequired response extensions.
+ */
+
+/**
+ * Declares the EIP-2612 gas sponsoring extension for inclusion in
+ * PaymentRequired.extensions.
+ *
+ * The server advertises that it (or its facilitator) supports EIP-2612
+ * gasless Permit2 approval. The client will populate the info with the
+ * actual permit signature data.
+ *
+ * @returns An object keyed by the extension identifier containing the extension declaration
+ *
+ * @example
+ * ```typescript
+ * import { declareEip2612GasSponsoringExtension } from '@x402/extensions';
+ *
+ * const routes = [
+ *   {
+ *     path: "/api/data",
+ *     price: "$0.01",
+ *     extensions: {
+ *       ...declareEip2612GasSponsoringExtension(),
+ *     },
+ *   },
+ * ];
+ * ```
+ */
+declare function declareEip2612GasSponsoringExtension(): Record<string, Eip2612GasSponsoringExtension>;
+
+/**
+ * Facilitator functions for extracting and validating EIP-2612 Gas Sponsoring extension data.
+ *
+ * These functions help facilitators extract the EIP-2612 permit data from payment
+ * payloads and validate it before calling settleWithPermit.
+ */
+
+/**
+ * Extracts the EIP-2612 gas sponsoring info from a payment payload's extensions.
+ *
+ * Returns the info if the extension is present and contains the required client-populated
+ * fields (from, asset, spender, amount, nonce, deadline, signature, version).
+ *
+ * @param paymentPayload - The payment payload to extract from
+ * @returns The EIP-2612 gas sponsoring info, or null if not present
+ */
+declare function extractEip2612GasSponsoringInfo(paymentPayload: PaymentPayload): Eip2612GasSponsoringInfo | null;
+/**
+ * Validates that the EIP-2612 gas sponsoring info has valid format.
+ *
+ * Performs basic validation on the info fields:
+ * - Addresses are valid hex (0x + 40 hex chars)
+ * - Amount, nonce, deadline are numeric strings
+ * - Signature is a hex string
+ * - Version is a numeric version string
+ *
+ * @param info - The EIP-2612 gas sponsoring info to validate
+ * @returns True if the info is valid, false otherwise
+ */
+declare function validateEip2612GasSponsoringInfo(info: Eip2612GasSponsoringInfo): boolean;
+
+export { EIP2612_GAS_SPONSORING, type Eip2612GasSponsoringExtension, type Eip2612GasSponsoringInfo, type Eip2612GasSponsoringServerInfo, declareEip2612GasSponsoringExtension, extractEip2612GasSponsoringInfo, validateEip2612GasSponsoringInfo };