@x402/extensions 0.0.1 → 2.0.0

package/dist/esm/bazaar/index.d.mts

@@ -0,0 +1,547 @@
+import { QueryParamMethods, BodyMethods, 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;
+
+/**
+ * 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: Omit<DeclareDiscoveryExtensionConfig, "method">): 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;
+    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 of the discovered resource */
+    url: string;
+    /** The protocol type of the resource */
+    type: string;
+    /** Additional metadata about the resource */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Response from listing discovery resources.
+ */
+interface DiscoveryResourcesResponse {
+    /** The list of discovered resources */
+    resources: DiscoveryResource[];
+    /** Total count of resources matching the query */
+    total?: number;
+    /** The limit used for this query */
+    limit?: number;
+    /** The offset used for this query */
+    offset?: 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, type BazaarClientExtension, type BodyDiscoveryExtension, type BodyDiscoveryInfo, type DiscoveryExtension, type DiscoveryInfo, type DiscoveryResource, type DiscoveryResourcesResponse, type ListDiscoveryResourcesParams, type QueryDiscoveryExtension, type QueryDiscoveryInfo, type ValidationResult, type WithExtensions as W, bazaarResourceServerExtension, declareDiscoveryExtension, extractDiscoveryInfo, extractDiscoveryInfoFromExtension, extractDiscoveryInfoV1, extractResourceMetadataV1, isDiscoverableV1, validateAndExtract, validateDiscoveryExtension, withBazaar };

package/dist/esm/bazaar/index.mjs

@@ -0,0 +1,27 @@
+import {
+  BAZAAR,
+  bazaarResourceServerExtension,
+  declareDiscoveryExtension,
+  extractDiscoveryInfo,
+  extractDiscoveryInfoFromExtension,
+  extractDiscoveryInfoV1,
+  extractResourceMetadataV1,
+  isDiscoverableV1,
+  validateAndExtract,
+  validateDiscoveryExtension,
+  withBazaar
+} from "../chunk-STXY3Q5R.mjs";
+export {
+  BAZAAR,
+  bazaarResourceServerExtension,
+  declareDiscoveryExtension,
+  extractDiscoveryInfo,
+  extractDiscoveryInfoFromExtension,
+  extractDiscoveryInfoV1,
+  extractResourceMetadataV1,
+  isDiscoverableV1,
+  validateAndExtract,
+  validateDiscoveryExtension,
+  withBazaar
+};
+//# sourceMappingURL=index.mjs.map

package/dist/esm/bazaar/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/esm/chunk-MKFJ5AA3.mjs

@@ -0,0 +1 @@
+//# sourceMappingURL=chunk-MKFJ5AA3.mjs.map

package/dist/esm/chunk-MKFJ5AA3.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}