moltspay 0.8.14 → 0.9.0

package/dist/registry-OsEO2dOu.d.mts

@@ -0,0 +1,233 @@
+/**
+ * Facilitator Interface
+ *
+ * A facilitator is a service that handles x402 payment verification and settlement.
+ * This abstraction allows MoltsPay to support multiple facilitators.
+ *
+ * @see https://www.x402.org/ecosystem?category=facilitators
+ */
+/**
+ * x402 Payment Payload (from client)
+ */
+interface X402PaymentPayload {
+    x402Version: number;
+    scheme?: string;
+    network?: string;
+    accepted?: {
+        scheme: string;
+        network: string;
+        asset: string;
+        amount: string;
+        payTo: string;
+        maxTimeoutSeconds: number;
+        extra?: Record<string, unknown>;
+    };
+    payload: unknown;
+}
+/**
+ * x402 Payment Requirements (server specifies what it accepts)
+ */
+interface X402PaymentRequirements {
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+/**
+ * Result of payment verification
+ */
+interface VerifyResult {
+    valid: boolean;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Result of payment settlement
+ */
+interface SettleResult {
+    success: boolean;
+    transaction?: string;
+    error?: string;
+    status?: string;
+}
+/**
+ * Facilitator health check result
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/**
+ * Facilitator fee information (for selection strategies)
+ */
+interface FacilitatorFee {
+    perTx: number;
+    currency: string;
+    freeQuota?: number;
+}
+/**
+ * Facilitator configuration
+ */
+interface FacilitatorConfig {
+    /** Facilitator endpoint URL */
+    endpoint?: string;
+    /** API key (if required) */
+    apiKey?: string;
+    /** API secret (if required) */
+    apiSecret?: string;
+    /** Additional config specific to facilitator */
+    [key: string]: unknown;
+}
+/**
+ * Facilitator Interface
+ *
+ * All facilitators must implement this interface.
+ */
+interface Facilitator {
+    /** Unique identifier for this facilitator */
+    readonly name: string;
+    /** Human-readable display name */
+    readonly displayName: string;
+    /** Supported networks (e.g., ["eip155:8453", "eip155:84532"]) */
+    readonly supportedNetworks: string[];
+    /**
+     * Check if facilitator is available and responsive
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Verify a payment signature without executing it
+     *
+     * @param paymentPayload - The x402 payment payload from client
+     * @param requirements - The payment requirements from server
+     */
+    verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    /**
+     * Settle a payment on-chain
+     *
+     * @param paymentPayload - The x402 payment payload from client
+     * @param requirements - The payment requirements from server
+     */
+    settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /**
+     * Get current fee information (optional, for selection strategies)
+     */
+    getFee?(): Promise<FacilitatorFee>;
+    /**
+     * Check if this facilitator supports a given network
+     */
+    supportsNetwork(network: string): boolean;
+}
+/**
+ * Base class with common functionality
+ */
+declare abstract class BaseFacilitator implements Facilitator {
+    abstract readonly name: string;
+    abstract readonly displayName: string;
+    abstract readonly supportedNetworks: string[];
+    abstract healthCheck(): Promise<HealthCheckResult>;
+    abstract verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    abstract settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    supportsNetwork(network: string): boolean;
+}
+
+/**
+ * Facilitator Registry
+ *
+ * Central registry for all available facilitators.
+ * Supports selection strategies for failover, load balancing, etc.
+ */
+
+/**
+ * Selection strategy for choosing facilitators
+ */
+type SelectionStrategy = 'failover' | 'cheapest' | 'fastest' | 'random' | 'roundrobin';
+/**
+ * Facilitator selection configuration
+ */
+interface FacilitatorSelection {
+    /** Primary facilitator to use */
+    primary: string;
+    /** Fallback facilitators (in order of preference) */
+    fallback?: string[];
+    /** Selection strategy */
+    strategy?: SelectionStrategy;
+    /** Per-facilitator config overrides */
+    config?: Record<string, FacilitatorConfig>;
+}
+/**
+ * Factory function type for creating facilitators
+ */
+type FacilitatorFactory = (config?: FacilitatorConfig) => Facilitator;
+/**
+ * Facilitator Registry
+ *
+ * Manages available facilitators and provides selection logic.
+ */
+declare class FacilitatorRegistry {
+    private factories;
+    private instances;
+    private selection;
+    private roundRobinIndex;
+    constructor(selection?: FacilitatorSelection);
+    /**
+     * Register a new facilitator factory
+     */
+    registerFactory(name: string, factory: FacilitatorFactory): void;
+    /**
+     * Get or create a facilitator instance
+     */
+    get(name: string, config?: FacilitatorConfig): Facilitator;
+    /**
+     * Get all configured facilitator names
+     */
+    getConfiguredNames(): string[];
+    /**
+     * Get list of facilitators based on selection strategy
+     */
+    private getOrderedFacilitators;
+    private shuffle;
+    private sortByCheapest;
+    private sortByFastest;
+    /**
+     * Verify payment using configured facilitators
+     */
+    verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult & {
+        facilitator: string;
+    }>;
+    /**
+     * Settle payment using configured facilitators
+     */
+    settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult & {
+        facilitator: string;
+    }>;
+    /**
+     * Check health of all configured facilitators
+     */
+    healthCheckAll(): Promise<Record<string, HealthCheckResult>>;
+    /**
+     * Check if an error is transient (network/server issue) vs permanent (bad request)
+     */
+    private isTransientError;
+    /**
+     * Update selection configuration
+     */
+    setSelection(selection: FacilitatorSelection): void;
+    /**
+     * Get current selection configuration
+     */
+    getSelection(): FacilitatorSelection;
+}
+/**
+ * Get the default facilitator registry
+ */
+declare function getDefaultRegistry(): FacilitatorRegistry;
+/**
+ * Create a new registry with custom selection
+ */
+declare function createRegistry(selection?: FacilitatorSelection): FacilitatorRegistry;
+
+export { BaseFacilitator as B, type Facilitator as F, type HealthCheckResult as H, type SelectionStrategy as S, type VerifyResult as V, type X402PaymentPayload as X, type FacilitatorConfig as a, type FacilitatorFee as b, FacilitatorRegistry as c, type FacilitatorSelection as d, type SettleResult as e, type X402PaymentRequirements as f, createRegistry as g, getDefaultRegistry as h };

package/dist/registry-OsEO2dOu.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Facilitator Interface
+ *
+ * A facilitator is a service that handles x402 payment verification and settlement.
+ * This abstraction allows MoltsPay to support multiple facilitators.
+ *
+ * @see https://www.x402.org/ecosystem?category=facilitators
+ */
+/**
+ * x402 Payment Payload (from client)
+ */
+interface X402PaymentPayload {
+    x402Version: number;
+    scheme?: string;
+    network?: string;
+    accepted?: {
+        scheme: string;
+        network: string;
+        asset: string;
+        amount: string;
+        payTo: string;
+        maxTimeoutSeconds: number;
+        extra?: Record<string, unknown>;
+    };
+    payload: unknown;
+}
+/**
+ * x402 Payment Requirements (server specifies what it accepts)
+ */
+interface X402PaymentRequirements {
+    scheme: string;
+    network: string;
+    asset: string;
+    amount: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra?: Record<string, unknown>;
+}
+/**
+ * Result of payment verification
+ */
+interface VerifyResult {
+    valid: boolean;
+    error?: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Result of payment settlement
+ */
+interface SettleResult {
+    success: boolean;
+    transaction?: string;
+    error?: string;
+    status?: string;
+}
+/**
+ * Facilitator health check result
+ */
+interface HealthCheckResult {
+    healthy: boolean;
+    latencyMs?: number;
+    error?: string;
+}
+/**
+ * Facilitator fee information (for selection strategies)
+ */
+interface FacilitatorFee {
+    perTx: number;
+    currency: string;
+    freeQuota?: number;
+}
+/**
+ * Facilitator configuration
+ */
+interface FacilitatorConfig {
+    /** Facilitator endpoint URL */
+    endpoint?: string;
+    /** API key (if required) */
+    apiKey?: string;
+    /** API secret (if required) */
+    apiSecret?: string;
+    /** Additional config specific to facilitator */
+    [key: string]: unknown;
+}
+/**
+ * Facilitator Interface
+ *
+ * All facilitators must implement this interface.
+ */
+interface Facilitator {
+    /** Unique identifier for this facilitator */
+    readonly name: string;
+    /** Human-readable display name */
+    readonly displayName: string;
+    /** Supported networks (e.g., ["eip155:8453", "eip155:84532"]) */
+    readonly supportedNetworks: string[];
+    /**
+     * Check if facilitator is available and responsive
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Verify a payment signature without executing it
+     *
+     * @param paymentPayload - The x402 payment payload from client
+     * @param requirements - The payment requirements from server
+     */
+    verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    /**
+     * Settle a payment on-chain
+     *
+     * @param paymentPayload - The x402 payment payload from client
+     * @param requirements - The payment requirements from server
+     */
+    settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    /**
+     * Get current fee information (optional, for selection strategies)
+     */
+    getFee?(): Promise<FacilitatorFee>;
+    /**
+     * Check if this facilitator supports a given network
+     */
+    supportsNetwork(network: string): boolean;
+}
+/**
+ * Base class with common functionality
+ */
+declare abstract class BaseFacilitator implements Facilitator {
+    abstract readonly name: string;
+    abstract readonly displayName: string;
+    abstract readonly supportedNetworks: string[];
+    abstract healthCheck(): Promise<HealthCheckResult>;
+    abstract verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult>;
+    abstract settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult>;
+    supportsNetwork(network: string): boolean;
+}
+
+/**
+ * Facilitator Registry
+ *
+ * Central registry for all available facilitators.
+ * Supports selection strategies for failover, load balancing, etc.
+ */
+
+/**
+ * Selection strategy for choosing facilitators
+ */
+type SelectionStrategy = 'failover' | 'cheapest' | 'fastest' | 'random' | 'roundrobin';
+/**
+ * Facilitator selection configuration
+ */
+interface FacilitatorSelection {
+    /** Primary facilitator to use */
+    primary: string;
+    /** Fallback facilitators (in order of preference) */
+    fallback?: string[];
+    /** Selection strategy */
+    strategy?: SelectionStrategy;
+    /** Per-facilitator config overrides */
+    config?: Record<string, FacilitatorConfig>;
+}
+/**
+ * Factory function type for creating facilitators
+ */
+type FacilitatorFactory = (config?: FacilitatorConfig) => Facilitator;
+/**
+ * Facilitator Registry
+ *
+ * Manages available facilitators and provides selection logic.
+ */
+declare class FacilitatorRegistry {
+    private factories;
+    private instances;
+    private selection;
+    private roundRobinIndex;
+    constructor(selection?: FacilitatorSelection);
+    /**
+     * Register a new facilitator factory
+     */
+    registerFactory(name: string, factory: FacilitatorFactory): void;
+    /**
+     * Get or create a facilitator instance
+     */
+    get(name: string, config?: FacilitatorConfig): Facilitator;
+    /**
+     * Get all configured facilitator names
+     */
+    getConfiguredNames(): string[];
+    /**
+     * Get list of facilitators based on selection strategy
+     */
+    private getOrderedFacilitators;
+    private shuffle;
+    private sortByCheapest;
+    private sortByFastest;
+    /**
+     * Verify payment using configured facilitators
+     */
+    verify(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<VerifyResult & {
+        facilitator: string;
+    }>;
+    /**
+     * Settle payment using configured facilitators
+     */
+    settle(paymentPayload: X402PaymentPayload, requirements: X402PaymentRequirements): Promise<SettleResult & {
+        facilitator: string;
+    }>;
+    /**
+     * Check health of all configured facilitators
+     */
+    healthCheckAll(): Promise<Record<string, HealthCheckResult>>;
+    /**
+     * Check if an error is transient (network/server issue) vs permanent (bad request)
+     */
+    private isTransientError;
+    /**
+     * Update selection configuration
+     */
+    setSelection(selection: FacilitatorSelection): void;
+    /**
+     * Get current selection configuration
+     */
+    getSelection(): FacilitatorSelection;
+}
+/**
+ * Get the default facilitator registry
+ */
+declare function getDefaultRegistry(): FacilitatorRegistry;
+/**
+ * Create a new registry with custom selection
+ */
+declare function createRegistry(selection?: FacilitatorSelection): FacilitatorRegistry;
+
+export { BaseFacilitator as B, type Facilitator as F, type HealthCheckResult as H, type SelectionStrategy as S, type VerifyResult as V, type X402PaymentPayload as X, type FacilitatorConfig as a, type FacilitatorFee as b, FacilitatorRegistry as c, type FacilitatorSelection as d, type SettleResult as e, type X402PaymentRequirements as f, createRegistry as g, getDefaultRegistry as h };

package/dist/server/index.d.mts

@@ -1,3 +1,5 @@
+import { d as FacilitatorSelection } from '../registry-OsEO2dOu.mjs';
+
 /**
  * MoltsPay Server Types
  */
@@ -78,8 +80,7 @@ interface MoltsPayServerOptions {
 /**
  * MoltsPay Server - Payment infrastructure for AI Agents
  *
- * Supports both testnet (x402.org) and mainnet (CDP) facilitators.
- * Server does NOT need private key - facilitator handles on-chain settlement.
+ * Now uses pluggable Facilitator abstraction for payment verification/settlement.
  *
  * Environment variables (from ~/.moltspay/.env or process.env):
  *   USE_MAINNET=true          - Use Base mainnet (requires CDP keys)
@@ -92,14 +93,21 @@ interface MoltsPayServerOptions {
  *   server.listen(3000);
  */
 
+/**
+ * Extended server options with facilitator config
+ */
+interface MoltsPayServerOptionsExtended extends MoltsPayServerOptions {
+    /** Facilitator selection configuration */
+    facilitators?: FacilitatorSelection;
+}
 declare class MoltsPayServer {
     private manifest;
     private skills;
     private options;
-    private cdpConfig;
-    private facilitatorUrl;
+    private registry;
     private networkId;
-    constructor(servicesPath: string, options?: MoltsPayServerOptions);
+    private useMainnet;
+    constructor(servicesPath: string, options?: MoltsPayServerOptionsExtended);
     /**
      * Register a skill handler for a service
      */
@@ -116,6 +124,10 @@ declare class MoltsPayServer {
      * GET /services - List available services
      */
     private handleGetServices;
+    /**
+     * GET /health - Health check endpoint
+     */
+    private handleHealthCheck;
     /**
      * POST /execute - Execute service with x402 payment
      */
@@ -129,19 +141,11 @@ declare class MoltsPayServer {
      */
     private validatePayment;
     /**
-     * Build complete payment requirements for facilitator
+     * Build payment requirements for facilitator
      */
     private buildPaymentRequirements;
-    /**
-     * Verify payment with facilitator (testnet or CDP)
-     */
-    private verifyWithFacilitator;
-    /**
-     * Settle payment with facilitator (execute on-chain transfer)
-     */
-    private settleWithFacilitator;
     private readBody;
     private sendJson;
 }
 
-export { type Charge, type ChargeStatus, type InputField, MoltsPayServer, type MoltsPayServerOptions, type OutputField, type PaymentRequest, type ProviderConfig, type RegisteredSkill, type ServiceConfig, type ServicesManifest, type SkillFunction, type VerifyRequest };
+export { type Charge, type ChargeStatus, type InputField, MoltsPayServer, type MoltsPayServerOptions, type MoltsPayServerOptionsExtended, type OutputField, type PaymentRequest, type ProviderConfig, type RegisteredSkill, type ServiceConfig, type ServicesManifest, type SkillFunction, type VerifyRequest };

package/dist/server/index.d.ts

@@ -1,3 +1,5 @@
+import { d as FacilitatorSelection } from '../registry-OsEO2dOu.js';
+
 /**
  * MoltsPay Server Types
  */
@@ -78,8 +80,7 @@ interface MoltsPayServerOptions {
 /**
  * MoltsPay Server - Payment infrastructure for AI Agents
  *
- * Supports both testnet (x402.org) and mainnet (CDP) facilitators.
- * Server does NOT need private key - facilitator handles on-chain settlement.
+ * Now uses pluggable Facilitator abstraction for payment verification/settlement.
  *
  * Environment variables (from ~/.moltspay/.env or process.env):
  *   USE_MAINNET=true          - Use Base mainnet (requires CDP keys)
@@ -92,14 +93,21 @@ interface MoltsPayServerOptions {
  *   server.listen(3000);
  */
 
+/**
+ * Extended server options with facilitator config
+ */
+interface MoltsPayServerOptionsExtended extends MoltsPayServerOptions {
+    /** Facilitator selection configuration */
+    facilitators?: FacilitatorSelection;
+}
 declare class MoltsPayServer {
     private manifest;
     private skills;
     private options;
-    private cdpConfig;
-    private facilitatorUrl;
+    private registry;
     private networkId;
-    constructor(servicesPath: string, options?: MoltsPayServerOptions);
+    private useMainnet;
+    constructor(servicesPath: string, options?: MoltsPayServerOptionsExtended);
     /**
      * Register a skill handler for a service
      */
@@ -116,6 +124,10 @@ declare class MoltsPayServer {
      * GET /services - List available services
      */
     private handleGetServices;
+    /**
+     * GET /health - Health check endpoint
+     */
+    private handleHealthCheck;
     /**
      * POST /execute - Execute service with x402 payment
      */
@@ -129,19 +141,11 @@ declare class MoltsPayServer {
      */
     private validatePayment;
     /**
-     * Build complete payment requirements for facilitator
+     * Build payment requirements for facilitator
      */
     private buildPaymentRequirements;
-    /**
-     * Verify payment with facilitator (testnet or CDP)
-     */
-    private verifyWithFacilitator;
-    /**
-     * Settle payment with facilitator (execute on-chain transfer)
-     */
-    private settleWithFacilitator;
     private readBody;
     private sendJson;
 }
 
-export { type Charge, type ChargeStatus, type InputField, MoltsPayServer, type MoltsPayServerOptions, type OutputField, type PaymentRequest, type ProviderConfig, type RegisteredSkill, type ServiceConfig, type ServicesManifest, type SkillFunction, type VerifyRequest };
+export { type Charge, type ChargeStatus, type InputField, MoltsPayServer, type MoltsPayServerOptions, type MoltsPayServerOptionsExtended, type OutputField, type PaymentRequest, type ProviderConfig, type RegisteredSkill, type ServiceConfig, type ServicesManifest, type SkillFunction, type VerifyRequest };