@x402/extensions 2.2.0 → 2.3.0

package/dist/cjs/index-DvDlinmy.d.ts

@@ -0,0 +1,575 @@
+import { BodyMethods, QueryParamMethods, HTTPFacilitatorClient } from '@x402/core/http';
+import { ResourceServerExtension, PaymentPayload, PaymentRequirements, PaymentRequirementsV1 } from '@x402/core/types';
+
+/**
+ * Shared type utilities for x402 extensions
+ */
+/**
+ * Type utility to merge extensions properly when chaining.
+ * If T already has extensions, merge them; otherwise add new extensions.
+ *
+ * @example
+ * ```ts
+ * // Chaining multiple extensions preserves all types:
+ * const client = withBazaar(withOtherExtension(new HTTPFacilitatorClient()));
+ * // Type: HTTPFacilitatorClient & { extensions: OtherExtension & BazaarExtension }
+ * ```
+ */
+type WithExtensions<T, E> = T extends {
+    extensions: infer Existing;
+} ? Omit<T, "extensions"> & {
+    extensions: Existing & E;
+} : T & {
+    extensions: E;
+};
+
+/**
+ * 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;
+        queryParams?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    };
+    output?: {
+        type?: string;
+        format?: string;
+        example?: unknown;
+    };
+}
+/**
+ * Discovery info for body methods (POST, PUT, PATCH)
+ */
+interface BodyDiscoveryInfo {
+    input: {
+        type: "http";
+        method: BodyMethods;
+        bodyType: "json" | "form-data" | "text";
+        body: Record<string, unknown>;
+        queryParams?: Record<string, unknown>;
+        headers?: Record<string, string>;
+    };
+    output?: {
+        type?: string;
+        format?: string;
+        example?: unknown;
+    };
+}
+/**
+ * Combined discovery info type
+ */
+type DiscoveryInfo = QueryDiscoveryInfo | BodyDiscoveryInfo;
+/**
+ * Discovery extension for query parameter methods (GET, HEAD, DELETE)
+ */
+interface QueryDiscoveryExtension {
+    info: QueryDiscoveryInfo;
+    schema: {
+        $schema: "https://json-schema.org/draft/2020-12/schema";
+        type: "object";
+        properties: {
+            input: {
+                type: "object";
+                properties: {
+                    type: {
+                        type: "string";
+                        const: "http";
+                    };
+                    method: {
+                        type: "string";
+                        enum: QueryParamMethods[];
+                    };
+                    queryParams?: {
+                        type: "object";
+                        properties?: Record<string, unknown>;
+                        required?: string[];
+                        additionalProperties?: boolean;
+                    };
+                    headers?: {
+                        type: "object";
+                        additionalProperties: {
+                            type: "string";
+                        };
+                    };
+                };
+                required: ("type" | "method")[];
+                additionalProperties?: boolean;
+            };
+            output?: {
+                type: "object";
+                properties?: Record<string, unknown>;
+                required?: readonly string[];
+                additionalProperties?: boolean;
+            };
+        };
+        required: ["input"];
+    };
+}
+/**
+ * Discovery extension for body methods (POST, PUT, PATCH)
+ */
+interface BodyDiscoveryExtension {
+    info: BodyDiscoveryInfo;
+    schema: {
+        $schema: "https://json-schema.org/draft/2020-12/schema";
+        type: "object";
+        properties: {
+            input: {
+                type: "object";
+                properties: {
+                    type: {
+                        type: "string";
+                        const: "http";
+                    };
+                    method: {
+                        type: "string";
+                        enum: BodyMethods[];
+                    };
+                    bodyType: {
+                        type: "string";
+                        enum: ["json", "form-data", "text"];
+                    };
+                    body: Record<string, unknown>;
+                    queryParams?: {
+                        type: "object";
+                        properties?: Record<string, unknown>;
+                        required?: string[];
+                        additionalProperties?: boolean;
+                    };
+                    headers?: {
+                        type: "object";
+                        additionalProperties: {
+                            type: "string";
+                        };
+                    };
+                };
+                required: ("type" | "method" | "bodyType" | "body")[];
+                additionalProperties?: boolean;
+            };
+            output?: {
+                type: "object";
+                properties?: Record<string, unknown>;
+                required?: readonly string[];
+                additionalProperties?: boolean;
+            };
+        };
+        required: ["input"];
+    };
+}
+/**
+ * Combined discovery extension type
+ */
+type DiscoveryExtension = QueryDiscoveryExtension | BodyDiscoveryExtension;
+interface DeclareQueryDiscoveryExtensionConfig {
+    method?: QueryParamMethods;
+    input?: Record<string, unknown>;
+    inputSchema?: Record<string, unknown>;
+    output?: {
+        example?: unknown;
+        schema?: Record<string, unknown>;
+    };
+}
+interface DeclareBodyDiscoveryExtensionConfig {
+    method?: BodyMethods;
+    input?: Record<string, unknown>;
+    inputSchema?: Record<string, unknown>;
+    bodyType: "json" | "form-data" | "text";
+    output?: {
+        example?: unknown;
+        schema?: Record<string, unknown>;
+    };
+}
+type DeclareDiscoveryExtensionConfig = DeclareQueryDiscoveryExtensionConfig | DeclareBodyDiscoveryExtensionConfig;
+/**
+ * Distributive Omit - properly distributes Omit over union types.
+ *
+ * Standard `Omit<A | B, K>` collapses to common properties only,
+ * losing discriminant properties like `bodyType`.
+ *
+ * This type uses conditional type distribution to preserve the union:
+ * `DistributiveOmit<A | B, K>` = `Omit<A, K> | Omit<B, K>`
+ */
+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.
+ */
+type DeclareDiscoveryExtensionInput = DistributiveOmit<DeclareDiscoveryExtensionConfig, "method">;
+
+/**
+ * Resource Service functions for creating Bazaar discovery extensions
+ *
+ * These functions help servers declare the shape of their endpoints
+ * for facilitator discovery and cataloging in the Bazaar.
+ */
+
+/**
+ * Create a discovery extension for any HTTP method
+ *
+ * This function helps servers declare how their endpoint should be called,
+ * including the expected input parameters/body and output format.
+ *
+ * @param config - Configuration object for the discovery extension
+ * @returns A discovery extension object with both info and schema
+ *
+ * @example
+ * ```typescript
+ * // For a GET endpoint with no input
+ * const getExtension = declareDiscoveryExtension({
+ *   method: "GET",
+ *   output: {
+ *     example: { message: "Success", timestamp: "2024-01-01T00:00:00Z" }
+ *   }
+ * });
+ *
+ * // For a GET endpoint with query params
+ * const getWithParams = declareDiscoveryExtension({
+ *   method: "GET",
+ *   input: { query: "example" },
+ *   inputSchema: {
+ *     properties: {
+ *       query: { type: "string" }
+ *     },
+ *     required: ["query"]
+ *   }
+ * });
+ *
+ * // For a POST endpoint with JSON body
+ * const postExtension = declareDiscoveryExtension({
+ *   method: "POST",
+ *   input: { name: "John", age: 30 },
+ *   inputSchema: {
+ *     properties: {
+ *       name: { type: "string" },
+ *       age: { type: "number" }
+ *     },
+ *     required: ["name"]
+ *   },
+ *   bodyType: "json",
+ *   output: {
+ *     example: { success: true, id: "123" }
+ *   }
+ * });
+ * ```
+ */
+declare function declareDiscoveryExtension(config: DeclareDiscoveryExtensionInput): Record<string, DiscoveryExtension>;
+
+declare const bazaarResourceServerExtension: ResourceServerExtension;
+
+/**
+ * Facilitator functions for validating and extracting Bazaar discovery extensions
+ *
+ * These functions help facilitators validate extension data against schemas
+ * and extract the discovery information for cataloging in the Bazaar.
+ *
+ * Supports both v2 (extensions in PaymentRequired) and v1 (outputSchema in PaymentRequirements).
+ */
+
+/**
+ * Validation result for discovery extensions
+ */
+interface ValidationResult {
+    valid: boolean;
+    errors?: string[];
+}
+/**
+ * Validates a discovery extension's info against its schema
+ *
+ * @param extension - The discovery extension containing info and schema
+ * @returns Validation result indicating if the info matches the schema
+ *
+ * @example
+ * ```typescript
+ * const extension = declareDiscoveryExtension(...);
+ * const result = validateDiscoveryExtension(extension);
+ *
+ * if (result.valid) {
+ *   console.log("Extension is valid");
+ * } else {
+ *   console.error("Validation errors:", result.errors);
+ * }
+ * ```
+ */
+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;
+}
+/**
+ * Extracts discovery information from payment payload and requirements.
+ * Combines resource URL, HTTP method, version, and discovery info into a single object.
+ *
+ * @param paymentPayload - The payment payload containing extensions and resource info
+ * @param paymentRequirements - The payment requirements to validate against
+ * @param validate - Whether to validate the discovery info against the schema (default: true)
+ * @returns Discovered resource info with URL, method, version and discovery data, or null if not found
+ */
+declare function extractDiscoveryInfo(paymentPayload: PaymentPayload, paymentRequirements: PaymentRequirements | PaymentRequirementsV1, validate?: boolean): DiscoveredResource | null;
+/**
+ * Extracts discovery info from a v2 extension directly
+ *
+ * This is a lower-level function for when you already have the extension object.
+ * For general use, prefer the main extractDiscoveryInfo function.
+ *
+ * @param extension - The discovery extension to extract info from
+ * @param validate - Whether to validate before extracting (default: true)
+ * @returns The discovery info if valid
+ * @throws Error if validation fails and validate is true
+ */
+declare function extractDiscoveryInfoFromExtension(extension: DiscoveryExtension, validate?: boolean): DiscoveryInfo;
+/**
+ * Validates and extracts discovery info in one step
+ *
+ * This is a convenience function that combines validation and extraction,
+ * returning both the validation result and the info if valid.
+ *
+ * @param extension - The discovery extension to validate and extract
+ * @returns Object containing validation result and info (if valid)
+ *
+ * @example
+ * ```typescript
+ * const extension = declareDiscoveryExtension(...);
+ * const { valid, info, errors } = validateAndExtract(extension);
+ *
+ * if (valid && info) {
+ *   // Store info in Bazaar catalog
+ * } else {
+ *   console.error("Validation errors:", errors);
+ * }
+ * ```
+ */
+declare function validateAndExtract(extension: DiscoveryExtension): {
+    valid: boolean;
+    info?: DiscoveryInfo;
+    errors?: string[];
+};
+
+/**
+ * V1 Facilitator functions for extracting Bazaar discovery information
+ *
+ * In v1, discovery information is stored in the `outputSchema` field
+ * of PaymentRequirements, which has a different structure than v2.
+ *
+ * This module transforms v1 data into v2 DiscoveryInfo format.
+ */
+
+/**
+ * Extracts discovery info from v1 PaymentRequirements and transforms to v2 format
+ *
+ * In v1, the discovery information is stored in the `outputSchema` field,
+ * which contains both input (endpoint shape) and output (response schema) information.
+ *
+ * This function makes smart assumptions to normalize v1 data into v2 DiscoveryInfo format:
+ * - For GET/HEAD/DELETE: Looks for queryParams, query, or params fields
+ * - For POST/PUT/PATCH: Looks for bodyFields, body, or data fields and normalizes bodyType
+ * - Extracts optional headers if present
+ *
+ * @param paymentRequirements - V1 payment requirements
+ * @returns Discovery info in v2 format if present and valid, or null if not discoverable
+ *
+ * @example
+ * ```typescript
+ * const requirements: PaymentRequirementsV1 = {
+ *   scheme: "exact",
+ *   network: "eip155:8453",
+ *   maxAmountRequired: "100000",
+ *   resource: "https://api.example.com/data",
+ *   description: "Get data",
+ *   mimeType: "application/json",
+ *   outputSchema: {
+ *     input: {
+ *       type: "http",
+ *       method: "GET",
+ *       discoverable: true,
+ *       queryParams: { query: "string" }
+ *     },
+ *     output: { type: "object" }
+ *   },
+ *   payTo: "0x...",
+ *   maxTimeoutSeconds: 300,
+ *   asset: "0x...",
+ *   extra: {}
+ * };
+ *
+ * const info = extractDiscoveryInfoV1(requirements);
+ * if (info) {
+ *   console.log("Endpoint method:", info.input.method);
+ * }
+ * ```
+ */
+declare function extractDiscoveryInfoV1(paymentRequirements: PaymentRequirementsV1): DiscoveryInfo | null;
+/**
+ * Checks if v1 PaymentRequirements contains discoverable information
+ *
+ * @param paymentRequirements - V1 payment requirements
+ * @returns True if the requirements contain valid discovery info
+ *
+ * @example
+ * ```typescript
+ * if (isDiscoverableV1(requirements)) {
+ *   const info = extractDiscoveryInfoV1(requirements);
+ *   // Catalog info in Bazaar
+ * }
+ * ```
+ */
+declare function isDiscoverableV1(paymentRequirements: PaymentRequirementsV1): boolean;
+/**
+ * Extracts resource metadata from v1 PaymentRequirements
+ *
+ * In v1, resource information is embedded directly in the payment requirements
+ * rather than in a separate resource object.
+ *
+ * @param paymentRequirements - V1 payment requirements
+ * @returns Resource metadata
+ *
+ * @example
+ * ```typescript
+ * const metadata = extractResourceMetadataV1(requirements);
+ * console.log("Resource URL:", metadata.url);
+ * console.log("Description:", metadata.description);
+ * ```
+ */
+declare function extractResourceMetadataV1(paymentRequirements: PaymentRequirementsV1): {
+    url: string;
+    description: string;
+    mimeType: string;
+};
+
+/**
+ * Client extensions for querying Bazaar discovery resources
+ */
+
+/**
+ * Parameters for listing discovery resources.
+ * All parameters are optional and used for filtering/pagination.
+ */
+interface ListDiscoveryResourcesParams {
+    /**
+     * Filter by protocol type (e.g., "http", "mcp").
+     * Currently, the only supported protocol type is "http".
+     */
+    type?: string;
+    /**
+     * The number of discovered x402 resources to return per page.
+     */
+    limit?: number;
+    /**
+     * The offset of the first discovered x402 resource to return.
+     */
+    offset?: number;
+}
+/**
+ * A discovered x402 resource from the bazaar.
+ */
+interface DiscoveryResource {
+    /** The URL or identifier of the discovered resource */
+    resource: string;
+    /** The protocol type of the resource (e.g., "http") */
+    type: string;
+    /** The x402 protocol version supported by this resource */
+    x402Version: number;
+    /** Array of accepted payment methods for this resource */
+    accepts: PaymentRequirements[];
+    /** ISO 8601 timestamp of when the resource was last updated */
+    lastUpdated: string;
+    /** Additional metadata about the resource */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from listing discovery resources.
+ */
+interface DiscoveryResourcesResponse {
+    /** The x402 protocol version of this response */
+    x402Version: number;
+    /** The list of discovered resources */
+    items: DiscoveryResource[];
+    /** Pagination information for the response */
+    pagination: {
+        /** Maximum number of results returned */
+        limit: number;
+        /** Number of results skipped */
+        offset: number;
+        /** Total count of resources matching the query */
+        total: number;
+    };
+}
+/**
+ * Bazaar client extension interface providing discovery query functionality.
+ */
+interface BazaarClientExtension {
+    discovery: {
+        /**
+         * List x402 discovery resources from the bazaar.
+         *
+         * @param params - Optional filtering and pagination parameters
+         * @returns A promise resolving to the discovery resources response
+         */
+        listResources(params?: ListDiscoveryResourcesParams): Promise<DiscoveryResourcesResponse>;
+    };
+}
+/**
+ * Extends a facilitator client with Bazaar discovery query functionality.
+ * Preserves and merges with any existing extensions from prior chaining.
+ *
+ * @param client - The facilitator client to extend
+ * @returns The client extended with bazaar discovery capabilities
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const client = withBazaar(new HTTPFacilitatorClient());
+ * const resources = await client.extensions.discovery.listResources({ type: "http" });
+ *
+ * // Chaining with other extensions
+ * const client = withBazaar(withOtherExtension(new HTTPFacilitatorClient()));
+ * await client.extensions.other.someMethod();
+ * await client.extensions.discovery.listResources();
+ * ```
+ */
+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 };

package/dist/cjs/index.d.ts

@@ -1,3 +1,6 @@
-export { BAZAAR, BazaarClientExtension, BodyDiscoveryExtension, BodyDiscoveryInfo, DiscoveryExtension, DiscoveryInfo, DiscoveryResource, DiscoveryResourcesResponse, ListDiscoveryResourcesParams, QueryDiscoveryExtension, QueryDiscoveryInfo, ValidationResult, W as WithExtensions, bazaarResourceServerExtension, declareDiscoveryExtension, extractDiscoveryInfo, extractDiscoveryInfoFromExtension, extractDiscoveryInfoV1, extractResourceMetadataV1, isDiscoverableV1, validateAndExtract, validateDiscoveryExtension, withBazaar } from './bazaar/index.js';
+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 { 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, 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 '@x402/core/http';
 import '@x402/core/types';
+import 'zod';