@agirails/sdk 2.2.0 → 2.2.2

package/src/adapters/IAdapter.ts

@@ -0,0 +1,292 @@
+/**
+ * IAdapter - Common interface for all payment adapters.
+ *
+ * This interface defines the contract that all payment adapters must implement,
+ * enabling the AdapterRouter to select and use any adapter interchangeably.
+ *
+ * CRITICAL ACTP COMPLIANCE:
+ * - pay() creates transaction + locks escrow -> state = COMMITTED
+ * - Caller must transition to IN_PROGRESS before work
+ * - Caller must transition to DELIVERED with proof after work
+ * - Caller must call release() to settle (NO auto-settle)
+ *
+ * @module adapters/IAdapter
+ */
+
+import {
+  AdapterMetadata,
+  UnifiedPayParams,
+  UnifiedPayResult,
+} from '../types/adapter';
+
+// ============================================================================
+// TransactionStatus - Adapter-agnostic status
+// ============================================================================
+
+/**
+ * Valid transaction states across all adapters.
+ */
+export type AdapterTransactionState =
+  | 'INITIATED'
+  | 'COMMITTED'
+  | 'IN_PROGRESS'
+  | 'DELIVERED'
+  | 'SETTLED'
+  | 'DISPUTED'
+  | 'CANCELLED';
+
+/**
+ * Transaction status returned by getStatus().
+ *
+ * Provides a consistent view of transaction state across different
+ * adapter implementations with action hints for what can be done next.
+ */
+export interface TransactionStatus {
+  /** Current transaction state */
+  state: AdapterTransactionState;
+
+  /** Can provider start work? (COMMITTED -> IN_PROGRESS) */
+  canStartWork: boolean;
+
+  /** Can provider mark as delivered? (IN_PROGRESS -> DELIVERED) */
+  canDeliver: boolean;
+
+  /** Can escrow be released? (DELIVERED + dispute window expired) */
+  canRelease: boolean;
+
+  /** Can requester dispute? (DELIVERED, within dispute window) */
+  canDispute: boolean;
+
+  /** Transaction amount (formatted string) */
+  amount: string;
+
+  /** Deadline as ISO 8601 string (optional) */
+  deadline?: string;
+
+  /** Dispute window end as ISO 8601 string (optional) */
+  disputeWindowEnds?: string;
+
+  /** Provider address */
+  provider: string;
+
+  /** Requester address */
+  requester: string;
+}
+
+// ============================================================================
+// IAdapter Interface
+// ============================================================================
+
+/**
+ * Common interface for all payment adapters.
+ *
+ * Implementations include:
+ * - BasicAdapter: High-level, opinionated API
+ * - StandardAdapter: Balanced control API
+ * - X402Adapter: HTTP 402 Payment Required protocol (Phase 1 Step 2)
+ * - ERC8004Adapter: Identity-based payments (Phase 1 Step 3)
+ *
+ * @example
+ * ```typescript
+ * class CustomAdapter implements IAdapter {
+ *   readonly metadata: AdapterMetadata = {
+ *     id: 'custom',
+ *     name: 'Custom Adapter',
+ *     usesEscrow: true,
+ *     supportsDisputes: true,
+ *     requiresIdentity: false,
+ *     settlementMode: 'explicit',
+ *     priority: 50,
+ *   };
+ *
+ *   async pay(params: UnifiedPayParams): Promise<UnifiedPayResult> {
+ *     // Implementation...
+ *   }
+ *
+ *   canHandle(params: UnifiedPayParams): boolean {
+ *     return true; // Can handle all params
+ *   }
+ *
+ *   validate(params: UnifiedPayParams): void {
+ *     // Throw if invalid
+ *   }
+ * }
+ * ```
+ */
+export interface IAdapter {
+  /**
+   * Adapter metadata describing capabilities.
+   *
+   * Used by AdapterRouter for selection and by developers
+   * to understand adapter behavior.
+   */
+  readonly metadata: AdapterMetadata;
+
+  /**
+   * Execute payment through this adapter.
+   *
+   * IMPORTANT: Returns with state=COMMITTED, NOT settled.
+   * Caller must follow ACTP lifecycle:
+   * 1. pay() -> COMMITTED
+   * 2. startWork() -> IN_PROGRESS
+   * 3. deliver() -> DELIVERED
+   * 4. release() -> SETTLED (explicit!)
+   *
+   * @param params - Unified payment parameters
+   * @returns Promise resolving to payment result
+   * @throws {ValidationError} If params are invalid
+   *
+   * @example
+   * ```typescript
+   * const result = await adapter.pay({
+   *   to: '0xProvider...',
+   *   amount: '100',
+   *   deadline: '+24h',
+   * });
+   * console.log(result.state); // 'COMMITTED'
+   * console.log(result.releaseRequired); // true
+   * ```
+   */
+  pay(params: UnifiedPayParams): Promise<UnifiedPayResult>;
+
+  /**
+   * Check if this adapter can handle the given parameters.
+   *
+   * Used by AdapterRouter to filter adapters that are capable
+   * of processing a specific payment request.
+   *
+   * @param params - Payment parameters to check
+   * @returns True if adapter can handle these params
+   *
+   * @example
+   * ```typescript
+   * if (adapter.canHandle({ to: 'https://api.example.com', amount: '10' })) {
+   *   // This adapter supports HTTP endpoints
+   * }
+   * ```
+   */
+  canHandle(params: UnifiedPayParams): boolean;
+
+  /**
+   * Validate parameters before execution.
+   *
+   * Called by AdapterRouter before routing to ensure
+   * parameters are valid for this specific adapter.
+   *
+   * @param params - Parameters to validate
+   * @throws {ValidationError} If params are invalid
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   adapter.validate(params);
+   * } catch (error) {
+   *   console.error('Invalid params:', error.message);
+   * }
+   * ```
+   */
+  validate(params: UnifiedPayParams): void;
+
+  /**
+   * Get transaction status by ID.
+   *
+   * Returns current state plus action hints indicating
+   * what operations are available.
+   *
+   * @param txId - Transaction ID
+   * @returns Promise resolving to transaction status
+   * @throws {Error} If transaction not found
+   *
+   * @example
+   * ```typescript
+   * const status = await adapter.getStatus(txId);
+   * if (status.canRelease) {
+   *   await adapter.release(escrowId);
+   * }
+   * ```
+   */
+  getStatus(txId: string): Promise<TransactionStatus>;
+
+  /**
+   * Transition to IN_PROGRESS state (provider starts work).
+   *
+   * Must be called by provider after accepting the transaction.
+   * ACTP requires this explicit transition.
+   *
+   * @param txId - Transaction ID
+   * @throws {Error} If transaction not found or wrong state
+   *
+   * @example
+   * ```typescript
+   * // Provider acknowledges and starts work
+   * await adapter.startWork(txId);
+   * ```
+   */
+  startWork(txId: string): Promise<void>;
+
+  /**
+   * Transition to DELIVERED state (provider completes work).
+   *
+   * @param txId - Transaction ID
+   * @param proof - Delivery proof (ABI-encoded dispute window)
+   * @throws {Error} If transaction not found or wrong state
+   *
+   * @example
+   * ```typescript
+   * // Provider marks work as delivered with 2-hour dispute window
+   * const proof = ethers.AbiCoder.defaultAbiCoder().encode(['uint256'], [7200]);
+   * await adapter.deliver(txId, proof);
+   * ```
+   */
+  deliver(txId: string, proof: string): Promise<void>;
+
+  /**
+   * Release escrow funds (EXPLICIT settlement).
+   *
+   * MUST be called after dispute window expires or requester approves.
+   * This is the ONLY way to settle - NO auto-settle.
+   *
+   * @param escrowId - Escrow ID (usually same as txId)
+   * @param attestationUID - Optional attestation UID for verification
+   * @throws {Error} If escrow not found or dispute window active
+   *
+   * @example
+   * ```typescript
+   * // After dispute window expires
+   * await adapter.release(result.escrowId);
+   * // Transaction is now SETTLED
+   * ```
+   */
+  release(escrowId: string, attestationUID?: string): Promise<void>;
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+/**
+ * Type guard to check if an object implements IAdapter.
+ *
+ * @param obj - Object to check
+ * @returns True if object implements IAdapter
+ */
+export function isAdapter(obj: unknown): obj is IAdapter {
+  if (!obj || typeof obj !== 'object') {
+    return false;
+  }
+
+  const adapter = obj as Partial<IAdapter>;
+
+  return (
+    typeof adapter.metadata === 'object' &&
+    adapter.metadata !== null &&
+    typeof adapter.metadata.id === 'string' &&
+    typeof adapter.pay === 'function' &&
+    typeof adapter.canHandle === 'function' &&
+    typeof adapter.validate === 'function' &&
+    typeof adapter.getStatus === 'function' &&
+    typeof adapter.startWork === 'function' &&
+    typeof adapter.deliver === 'function' &&
+    typeof adapter.release === 'function'
+  );
+}

package/src/adapters/StandardAdapter.ts

@@ -16,6 +16,12 @@ import { BaseAdapter, ValidationError } from './BaseAdapter';
 import { IACTPRuntime } from '../runtime/IACTPRuntime';
 import { MockTransaction, TransactionState } from '../runtime/types/MockState';
 import { EASHelper } from '../protocol/EASHelper';
+import { IAdapter, TransactionStatus } from './IAdapter';
+import {
+  AdapterMetadata,
+  UnifiedPayParams,
+  UnifiedPayResult,
+} from '../types/adapter';
 
 /**
  * Parameters for creating a transaction (standard level).
@@ -37,6 +43,9 @@ export interface StandardTransactionParams {
 
   /** Optional: Service description */
   serviceDescription?: string;
+
+  /** Optional: ERC-8004 agent ID (for reputation reporting) */
+  agentId?: string;
 }
 
 /**
@@ -71,7 +80,20 @@ export interface StandardTransactionParams {
  * await client.standard.releaseEscrow(escrowId);
  * ```
  */
-export class StandardAdapter extends BaseAdapter {
+export class StandardAdapter extends BaseAdapter implements IAdapter {
+  /**
+   * Adapter metadata for router selection.
+   */
+  public readonly metadata: AdapterMetadata = {
+    id: 'standard',
+    name: 'Standard Adapter',
+    usesEscrow: true,
+    supportsDisputes: true,
+    requiresIdentity: false,
+    settlementMode: 'timed', // Auto-release after dispute window
+    priority: 60, // Higher priority than basic (preferred when escrow required)
+  };
+
   /**
    * Creates a new StandardAdapter instance.
    *
@@ -143,6 +165,7 @@ export class StandardAdapter extends BaseAdapter {
       deadline,
       disputeWindow,
       serviceDescription: params.serviceDescription,
+      agentId: params.agentId, // ERC-8004 agent ID for reputation reporting
     });
   }
 
@@ -333,4 +356,200 @@ export class StandardAdapter extends BaseAdapter {
   async getTransaction(txId: string): Promise<MockTransaction | null> {
     return this.runtime.getTransaction(txId);
   }
+
+  // ==========================================================================
+  // IAdapter Implementation
+  // ==========================================================================
+
+  /**
+   * Unified pay method for IAdapter interface.
+   *
+   * Creates transaction AND links escrow in one call.
+   *
+   * @param params - Unified payment parameters
+   * @returns Promise resolving to unified payment result
+   */
+  async pay(params: UnifiedPayParams): Promise<UnifiedPayResult> {
+    // Validate using IAdapter validate()
+    this.validate(params);
+
+    // Map to StandardTransactionParams
+    const standardParams: StandardTransactionParams = {
+      provider: params.to,
+      amount: params.amount,
+      deadline: params.deadline,
+      disputeWindow: params.disputeWindow,
+      serviceDescription: params.description,
+      agentId: params.erc8004AgentId, // Pass ERC-8004 agent ID
+    };
+
+    // Create transaction
+    const txId = await this.createTransaction(standardParams);
+
+    // Link escrow (auto-transitions to COMMITTED)
+    await this.linkEscrow(txId);
+
+    // Fetch transaction for response
+    const tx = await this.runtime.getTransaction(txId);
+    if (!tx) {
+      throw new Error(`Transaction ${txId} not found after creation`);
+    }
+
+    const provider = this.validateAddress(params.to, 'to');
+    const deadline = tx.deadline;
+
+    return {
+      txId,
+      escrowId: txId,
+      adapter: this.metadata.id,
+      state: 'COMMITTED',
+      success: true,
+      amount: this.formatAmount(tx.amount),
+      releaseRequired: true, // ACTP requires explicit release()
+      provider,
+      requester: this.requesterAddress,
+      deadline: new Date(deadline * 1000).toISOString(),
+      erc8004AgentId: params.erc8004AgentId, // Return agent ID
+    };
+  }
+
+  /**
+   * Check if this adapter can handle the given parameters.
+   *
+   * StandardAdapter can handle any Ethereum address recipient.
+   *
+   * @param params - Payment parameters to check
+   * @returns True if params have a valid Ethereum address
+   */
+  canHandle(params: UnifiedPayParams): boolean {
+    // StandardAdapter handles Ethereum addresses only
+    if (typeof params.to !== 'string') {
+      return false;
+    }
+
+    // Check if it's an Ethereum address (0x-prefixed hex)
+    return /^0x[a-fA-F0-9]{40}$/.test(params.to);
+  }
+
+  /**
+   * Validate parameters before execution.
+   *
+   * @param params - Parameters to validate
+   * @throws {ValidationError} If params are invalid
+   */
+  validate(params: UnifiedPayParams): void {
+    // Validate address
+    this.validateAddress(params.to, 'to');
+
+    // Validate amount (will throw if invalid)
+    this.parseAmount(params.amount);
+
+    // Validate deadline if provided
+    if (params.deadline !== undefined) {
+      this.parseDeadline(params.deadline);
+    }
+
+    // Validate dispute window if provided
+    if (params.disputeWindow !== undefined) {
+      this.validateDisputeWindow(params.disputeWindow);
+    }
+  }
+
+  /**
+   * Get transaction status by ID.
+   *
+   * Returns TransactionStatus with action hints.
+   *
+   * @param txId - Transaction ID
+   * @returns Promise resolving to transaction status
+   */
+  async getStatus(txId: string): Promise<TransactionStatus> {
+    const tx = await this.runtime.getTransaction(txId);
+
+    if (!tx) {
+      throw new Error(`Transaction ${txId} not found`);
+    }
+
+    const now = this.runtime.time.now();
+    const disputeWindowEnds = tx.completedAt
+      ? tx.completedAt + tx.disputeWindow
+      : undefined;
+
+    return {
+      state: tx.state as TransactionStatus['state'],
+      canStartWork: tx.state === 'COMMITTED',
+      canDeliver: tx.state === 'IN_PROGRESS',
+      canRelease:
+        tx.state === 'DELIVERED' &&
+        disputeWindowEnds !== undefined &&
+        now >= disputeWindowEnds,
+      canDispute:
+        tx.state === 'DELIVERED' &&
+        disputeWindowEnds !== undefined &&
+        now < disputeWindowEnds,
+      amount: this.formatAmount(tx.amount),
+      deadline: new Date(tx.deadline * 1000).toISOString(),
+      disputeWindowEnds: disputeWindowEnds
+        ? new Date(disputeWindowEnds * 1000).toISOString()
+        : undefined,
+      provider: tx.provider,
+      requester: tx.requester,
+    };
+  }
+
+  /**
+   * Transition to IN_PROGRESS state (provider starts work).
+   *
+   * @param txId - Transaction ID
+   */
+  async startWork(txId: string): Promise<void> {
+    await this.runtime.transitionState(txId, 'IN_PROGRESS');
+  }
+
+  /**
+   * Transition to DELIVERED state (provider completes work).
+   *
+   * When no proof is provided, fetches the transaction's actual disputeWindow
+   * and encodes it as proof. This ensures consistency with the dispute window
+   * specified at transaction creation time.
+   *
+   * @param txId - Transaction ID
+   * @param proof - Optional delivery proof (ABI-encoded dispute window).
+   *                If not provided, uses transaction's disputeWindow.
+   */
+  async deliver(txId: string, proof?: string): Promise<void> {
+    let deliveryProof = proof;
+
+    if (!deliveryProof) {
+      // Fetch transaction to get its actual disputeWindow
+      const tx = await this.runtime.getTransaction(txId);
+      if (!tx) {
+        throw new Error(`Transaction ${txId} not found`);
+      }
+      // Use transaction's disputeWindow, not a default
+      deliveryProof = this.encodeDisputeWindowProof(tx.disputeWindow);
+    }
+
+    await this.runtime.transitionState(txId, 'DELIVERED', deliveryProof);
+  }
+
+  /**
+   * Release escrow funds (EXPLICIT settlement).
+   *
+   * Wrapper around releaseEscrow() for IAdapter interface.
+   *
+   * @param escrowId - Escrow ID (usually same as txId)
+   * @param attestationUID - Optional attestation UID for verification
+   */
+  async release(escrowId: string, attestationUID?: string): Promise<void> {
+    // Find txId from escrowId (they're usually the same)
+    const legacyMatch = escrowId.match(/^escrow-(.+)-\d+$/);
+    const txId = legacyMatch ? legacyMatch[1] : escrowId;
+
+    if (attestationUID) {
+      await this.releaseEscrow(escrowId, { txId, attestationUID });
+    } else {
+      await this.releaseEscrow(escrowId);
+    }
+  }
 }