@agirails/sdk 2.2.0 → 2.2.1

package/dist/adapters/AdapterRegistry.d.ts

@@ -0,0 +1,140 @@
+/**
+ * AdapterRegistry - Central registry for payment adapters.
+ *
+ * Manages the collection of available adapters and provides
+ * methods for registration, lookup, and priority-based retrieval.
+ *
+ * @module adapters/AdapterRegistry
+ */
+import { IAdapter } from './IAdapter';
+/**
+ * AdapterRegistry - Central registry for managing available adapters.
+ *
+ * The registry maintains a collection of adapters indexed by their ID.
+ * It provides methods for:
+ * - Registration and unregistration
+ * - Lookup by ID
+ * - Priority-sorted retrieval
+ *
+ * @example
+ * ```typescript
+ * const registry = new AdapterRegistry();
+ *
+ * // Register adapters
+ * registry.register(basicAdapter);
+ * registry.register(standardAdapter);
+ *
+ * // Lookup by ID
+ * const adapter = registry.get('basic');
+ *
+ * // Get all adapters sorted by priority
+ * const adapters = registry.getByPriority();
+ * ```
+ */
+export declare class AdapterRegistry {
+    /**
+     * Internal map of adapters by ID.
+     */
+    private adapters;
+    /**
+     * Register an adapter.
+     *
+     * If an adapter with the same ID already exists, it will be replaced.
+     *
+     * @param adapter - Adapter to register
+     *
+     * @example
+     * ```typescript
+     * registry.register(new BasicAdapter(runtime, requesterAddress));
+     * ```
+     */
+    register(adapter: IAdapter): void;
+    /**
+     * Unregister an adapter by ID.
+     *
+     * @param id - Adapter ID to remove
+     * @returns True if adapter was found and removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const removed = registry.unregister('custom-adapter');
+     * ```
+     */
+    unregister(id: string): boolean;
+    /**
+     * Get an adapter by ID.
+     *
+     * @param id - Adapter ID to look up
+     * @returns The adapter or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const adapter = registry.get('standard');
+     * if (adapter) {
+     *   await adapter.pay(params);
+     * }
+     * ```
+     */
+    get(id: string): IAdapter | undefined;
+    /**
+     * Get all registered adapters.
+     *
+     * Returns adapters in insertion order.
+     *
+     * @returns Array of all registered adapters
+     *
+     * @example
+     * ```typescript
+     * const all = registry.getAll();
+     * console.log(`${all.length} adapters registered`);
+     * ```
+     */
+    getAll(): IAdapter[];
+    /**
+     * Check if an adapter is registered.
+     *
+     * @param id - Adapter ID to check
+     * @returns True if adapter is registered
+     *
+     * @example
+     * ```typescript
+     * if (registry.has('x402')) {
+     *   console.log('x402 adapter available');
+     * }
+     * ```
+     */
+    has(id: string): boolean;
+    /**
+     * Get adapters sorted by priority (highest first).
+     *
+     * Higher priority adapters are tried first during selection.
+     *
+     * @returns Array of adapters sorted by priority descending
+     *
+     * @example
+     * ```typescript
+     * const byPriority = registry.getByPriority();
+     * // byPriority[0] has highest priority
+     * ```
+     */
+    getByPriority(): IAdapter[];
+    /**
+     * Get the number of registered adapters.
+     *
+     * @returns Number of adapters
+     */
+    get size(): number;
+    /**
+     * Get all adapter IDs.
+     *
+     * @returns Array of adapter IDs
+     */
+    getIds(): string[];
+    /**
+     * Clear all registered adapters.
+     *
+     * Primarily useful for testing.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=AdapterRegistry.d.ts.map

package/dist/adapters/AdapterRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdapterRegistry.d.ts","sourceRoot":"","sources":["../../src/adapters/AdapterRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,qBAAa,eAAe;IAC1B;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAoC;IAEpD;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,IAAI;IAOjC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAI/B;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAIrC;;;;;;;;;;;;OAYG;IACH,MAAM,IAAI,QAAQ,EAAE;IAIpB;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;;;;;;;;;;;OAYG;IACH,aAAa,IAAI,QAAQ,EAAE;IAM3B;;;;OAIG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,MAAM,IAAI,MAAM,EAAE;IAIlB;;;;OAIG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/adapters/AdapterRegistry.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * AdapterRegistry - Central registry for payment adapters.
+ *
+ * Manages the collection of available adapters and provides
+ * methods for registration, lookup, and priority-based retrieval.
+ *
+ * @module adapters/AdapterRegistry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterRegistry = void 0;
+/**
+ * AdapterRegistry - Central registry for managing available adapters.
+ *
+ * The registry maintains a collection of adapters indexed by their ID.
+ * It provides methods for:
+ * - Registration and unregistration
+ * - Lookup by ID
+ * - Priority-sorted retrieval
+ *
+ * @example
+ * ```typescript
+ * const registry = new AdapterRegistry();
+ *
+ * // Register adapters
+ * registry.register(basicAdapter);
+ * registry.register(standardAdapter);
+ *
+ * // Lookup by ID
+ * const adapter = registry.get('basic');
+ *
+ * // Get all adapters sorted by priority
+ * const adapters = registry.getByPriority();
+ * ```
+ */
+class AdapterRegistry {
+    constructor() {
+        /**
+         * Internal map of adapters by ID.
+         */
+        this.adapters = new Map();
+    }
+    /**
+     * Register an adapter.
+     *
+     * If an adapter with the same ID already exists, it will be replaced.
+     *
+     * @param adapter - Adapter to register
+     *
+     * @example
+     * ```typescript
+     * registry.register(new BasicAdapter(runtime, requesterAddress));
+     * ```
+     */
+    register(adapter) {
+        if (!adapter.metadata?.id) {
+            throw new Error('Cannot register adapter without metadata.id');
+        }
+        this.adapters.set(adapter.metadata.id, adapter);
+    }
+    /**
+     * Unregister an adapter by ID.
+     *
+     * @param id - Adapter ID to remove
+     * @returns True if adapter was found and removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const removed = registry.unregister('custom-adapter');
+     * ```
+     */
+    unregister(id) {
+        return this.adapters.delete(id);
+    }
+    /**
+     * Get an adapter by ID.
+     *
+     * @param id - Adapter ID to look up
+     * @returns The adapter or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const adapter = registry.get('standard');
+     * if (adapter) {
+     *   await adapter.pay(params);
+     * }
+     * ```
+     */
+    get(id) {
+        return this.adapters.get(id);
+    }
+    /**
+     * Get all registered adapters.
+     *
+     * Returns adapters in insertion order.
+     *
+     * @returns Array of all registered adapters
+     *
+     * @example
+     * ```typescript
+     * const all = registry.getAll();
+     * console.log(`${all.length} adapters registered`);
+     * ```
+     */
+    getAll() {
+        return Array.from(this.adapters.values());
+    }
+    /**
+     * Check if an adapter is registered.
+     *
+     * @param id - Adapter ID to check
+     * @returns True if adapter is registered
+     *
+     * @example
+     * ```typescript
+     * if (registry.has('x402')) {
+     *   console.log('x402 adapter available');
+     * }
+     * ```
+     */
+    has(id) {
+        return this.adapters.has(id);
+    }
+    /**
+     * Get adapters sorted by priority (highest first).
+     *
+     * Higher priority adapters are tried first during selection.
+     *
+     * @returns Array of adapters sorted by priority descending
+     *
+     * @example
+     * ```typescript
+     * const byPriority = registry.getByPriority();
+     * // byPriority[0] has highest priority
+     * ```
+     */
+    getByPriority() {
+        return this.getAll().sort((a, b) => b.metadata.priority - a.metadata.priority);
+    }
+    /**
+     * Get the number of registered adapters.
+     *
+     * @returns Number of adapters
+     */
+    get size() {
+        return this.adapters.size;
+    }
+    /**
+     * Get all adapter IDs.
+     *
+     * @returns Array of adapter IDs
+     */
+    getIds() {
+        return Array.from(this.adapters.keys());
+    }
+    /**
+     * Clear all registered adapters.
+     *
+     * Primarily useful for testing.
+     */
+    clear() {
+        this.adapters.clear();
+    }
+}
+exports.AdapterRegistry = AdapterRegistry;
+//# sourceMappingURL=AdapterRegistry.js.map

package/dist/adapters/AdapterRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdapterRegistry.js","sourceRoot":"","sources":["../../src/adapters/AdapterRegistry.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;;AAIH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAa,eAAe;IAA5B;QACE;;WAEG;QACK,aAAQ,GAA0B,IAAI,GAAG,EAAE,CAAC;IAqItD,CAAC;IAnIC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,OAAiB;QACxB,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;QACjE,CAAC;QACD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC;IAED;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAU;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAClC,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,EAAU;QACZ,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CACvB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,QAAQ,CACpD,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AAzID,0CAyIC"}

package/dist/adapters/AdapterRouter.d.ts

@@ -0,0 +1,165 @@
+/**
+ * AdapterRouter - Intelligent adapter selection with guard-rails.
+ *
+ * The router selects the best adapter for each payment based on:
+ * - Explicit adapter preference
+ * - Required capabilities (escrow, disputes, identity)
+ * - Recipient type (address vs HTTP endpoint)
+ * - Adapter priority
+ *
+ * SECURITY: All parameters are validated before selection.
+ * SECURITY: All adapters must enforce explicit release (no auto-settle).
+ *
+ * @module adapters/AdapterRouter
+ */
+import { AdapterRegistry } from './AdapterRegistry';
+import { IAdapter } from './IAdapter';
+import { UnifiedPayParams } from '../types/adapter';
+import { ERC8004Bridge } from '../erc8004/ERC8004Bridge';
+/**
+ * Result of adapter selection with potential ERC-8004 resolution.
+ */
+export interface AdapterSelectionResult {
+    /** Selected adapter */
+    adapter: IAdapter;
+    /** Resolved payment parameters (with wallet instead of agentId) */
+    resolvedParams: UnifiedPayParams;
+    /** Whether an ERC-8004 agent ID was resolved */
+    wasAgentIdResolved: boolean;
+}
+/**
+ * AdapterRouter - Intelligent adapter selection with guard-rails.
+ *
+ * Selection logic (in order):
+ * 1. Validate params (throws if invalid)
+ * 2. Explicit adapter requested -> use it
+ * 3. Escrow/dispute required -> StandardAdapter
+ * 4. HTTP endpoint + no escrow -> X402Adapter (when available)
+ * 5. ERC-8004 identity -> ERC8004Adapter (when available)
+ * 6. Default -> First adapter that can handle (by priority)
+ *
+ * @example
+ * ```typescript
+ * const registry = new AdapterRegistry();
+ * registry.register(basicAdapter);
+ * registry.register(standardAdapter);
+ *
+ * const router = new AdapterRouter(registry);
+ *
+ * // Auto-select best adapter
+ * const adapter = router.select({ to: '0x...', amount: '100' });
+ *
+ * // Explicit adapter request
+ * const adapter = router.select({
+ *   to: '0x...',
+ *   amount: '100',
+ *   metadata: { preferredAdapter: 'standard' }
+ * });
+ * ```
+ */
+export declare class AdapterRouter {
+    private registry;
+    private erc8004Bridge?;
+    /**
+     * Creates a new AdapterRouter instance.
+     *
+     * @param registry - AdapterRegistry containing available adapters
+     * @param erc8004Bridge - Optional ERC-8004 bridge for agent ID resolution
+     */
+    constructor(registry: AdapterRegistry, erc8004Bridge?: ERC8004Bridge);
+    /**
+     * Set the ERC-8004 bridge for agent ID resolution.
+     *
+     * @param bridge - ERC8004Bridge instance
+     */
+    setERC8004Bridge(bridge: ERC8004Bridge): void;
+    /**
+     * Select the best adapter for the given payment parameters.
+     *
+     * @param params - Unified payment parameters
+     * @returns The selected adapter
+     * @throws {ValidationError} If params are invalid
+     * @throws {Error} If no suitable adapter found
+     *
+     * @example
+     * ```typescript
+     * const adapter = router.select({
+     *   to: '0xProvider...',
+     *   amount: '100',
+     * });
+     * const result = await adapter.pay(params);
+     * ```
+     */
+    select(params: UnifiedPayParams): IAdapter;
+    /**
+     * Validate payment parameters with Zod schema.
+     *
+     * GUARD-RAIL: Performs strict validation before any adapter selection.
+     *
+     * @param params - Parameters to validate
+     * @throws {ValidationError} If params are invalid
+     */
+    private validateParams;
+    /**
+     * Check if a string is an HTTP/HTTPS endpoint.
+     *
+     * @param to - Recipient string to check
+     * @returns True if it's an HTTP endpoint
+     */
+    private isHttpEndpoint;
+    /**
+     * Get all adapters that can handle the given params.
+     *
+     * Useful for debugging or letting users choose from multiple options.
+     *
+     * @param params - Payment parameters
+     * @returns Array of adapters that can handle params
+     */
+    getCompatibleAdapters(params: UnifiedPayParams): IAdapter[];
+    /**
+     * Check if any adapter can handle the given params.
+     *
+     * @param params - Payment parameters
+     * @returns True if at least one adapter can handle
+     */
+    canHandle(params: UnifiedPayParams): boolean;
+    /**
+     * Select adapter AND resolve ERC-8004 agent IDs.
+     *
+     * This is the recommended method for payment flows. It:
+     * 1. Checks if `to` is an ERC-8004 agent ID (numeric string)
+     * 2. If so, resolves it to a wallet address via ERC8004Bridge
+     * 3. Stores the original agentId in erc8004AgentId field
+     * 4. Selects the appropriate adapter
+     *
+     * @param params - Unified payment parameters
+     * @returns Selection result with resolved params
+     * @throws {ValidationError} If params invalid or agent not found
+     *
+     * @example
+     * ```typescript
+     * const { adapter, resolvedParams } = await router.selectAndResolve({
+     *   to: '12345',  // ERC-8004 agent ID
+     *   amount: '100',
+     * });
+     *
+     * // resolvedParams.to is now the wallet address
+     * // resolvedParams.erc8004AgentId is '12345'
+     * const result = await adapter.pay(resolvedParams);
+     * ```
+     */
+    selectAndResolve(params: UnifiedPayParams): Promise<AdapterSelectionResult>;
+    /**
+     * Check if a string looks like an ERC-8004 agent ID.
+     *
+     * Agent IDs are numeric strings (uint256) that are:
+     * - NOT Ethereum addresses (0x-prefixed)
+     * - NOT URLs (http/https)
+     * - Valid as BigInt in range [0, 2^256)
+     *
+     * @param to - Recipient string to check
+     * @returns True if it looks like an agent ID
+     */
+    isERC8004AgentId(to: string): boolean;
+}
+//# sourceMappingURL=AdapterRouter.d.ts.map

package/dist/adapters/AdapterRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdapterRouter.d.ts","sourceRoot":"","sources":["../../src/adapters/AdapterRouter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EACL,gBAAgB,EAGjB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,uBAAuB;IACvB,OAAO,EAAE,QAAQ,CAAC;IAElB,mEAAmE;IACnE,cAAc,EAAE,gBAAgB,CAAC;IAEjC,gDAAgD;IAChD,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,aAAa;IAUtB,OAAO,CAAC,QAAQ;IATlB,OAAO,CAAC,aAAa,CAAC,CAAgB;IAEtC;;;;;OAKG;gBAEO,QAAQ,EAAE,eAAe,EACjC,aAAa,CAAC,EAAE,aAAa;IAK/B;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAI7C;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ;IA4F1C;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IA6CtB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAStB;;;;;;;OAOG;IACH,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,QAAQ,EAAE;IAW3D;;;;;OAKG;IACH,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO;IAa5C;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAgDjF;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAuBtC"}