@agirails/sdk 2.0.1-beta → 2.0.2

package/src/errors/index.ts

@@ -12,7 +12,8 @@ export class ACTPError extends Error {
   ) {
     super(message);
     this.name = 'ACTPError';
-    Object.setPrototypeOf(this, ACTPError.prototype);
+    // Ensure `instanceof` works for subclasses (TS + Error inheritance quirk)
+    Object.setPrototypeOf(this, new.target.prototype);
   }
 }
 
@@ -127,4 +128,300 @@ export class InvalidAmountError extends ValidationError {
   }
 }
 
+/**
+ * Storage Errors (AIP-7)
+ */
+export class StorageError extends ACTPError {
+  constructor(operation: string, message: string, details?: any) {
+    super(
+      `Storage operation failed (${operation}): ${message}`,
+      'STORAGE_ERROR',
+      undefined,
+      { operation, ...details }
+    );
+    this.name = 'StorageError';
+  }
+}
+
+export class InvalidCIDError extends ValidationError {
+  constructor(cid: string, reason?: string) {
+    super('cid', `Invalid IPFS CID: ${cid}${reason ? ` (${reason})` : ''}`);
+    this.name = 'InvalidCIDError';
+  }
+}
+
+export class UploadTimeoutError extends StorageError {
+  constructor(timeoutMs: number) {
+    super('upload', `Upload timed out after ${timeoutMs}ms`, { timeoutMs });
+    this.name = 'UploadTimeoutError';
+  }
+}
+
+export class DownloadTimeoutError extends StorageError {
+  constructor(cid: string, timeoutMs: number) {
+    super('download', `Download of ${cid} timed out after ${timeoutMs}ms`, { cid, timeoutMs });
+    this.name = 'DownloadTimeoutError';
+  }
+}
+
+export class FileSizeLimitExceededError extends StorageError {
+  constructor(size: number, maxSize: number) {
+    super(
+      'upload',
+      `File size ${size} bytes exceeds maximum ${maxSize} bytes`,
+      { size, maxSize }
+    );
+    this.name = 'FileSizeLimitExceededError';
+  }
+}
+
+export class StorageAuthenticationError extends StorageError {
+  constructor(provider: string) {
+    super('authentication', `Authentication failed for ${provider}`, { provider });
+    this.name = 'StorageAuthenticationError';
+  }
+}
+
+export class StorageRateLimitError extends StorageError {
+  constructor(retryAfter?: number) {
+    super(
+      'rate-limit',
+      `Rate limit exceeded${retryAfter ? `, retry after ${retryAfter}s` : ''}`,
+      { retryAfter }
+    );
+    this.name = 'StorageRateLimitError';
+  }
+}
+
+export class ContentNotFoundError extends StorageError {
+  constructor(cid: string) {
+    super('download', `Content not found for CID: ${cid}`, { cid });
+    this.name = 'ContentNotFoundError';
+  }
+}
+
+export class ArweaveUploadError extends StorageError {
+  constructor(message: string, details?: any) {
+    super('upload', `Arweave upload failed: ${message}`, details);
+    this.name = 'ArweaveUploadError';
+  }
+}
+
+export class ArweaveDownloadError extends StorageError {
+  constructor(txId: string, message: string) {
+    super('download', `Failed to download from Arweave (${txId}): ${message}`, { txId });
+    this.name = 'ArweaveDownloadError';
+  }
+}
+
+export class InsufficientBalanceError extends StorageError {
+  constructor(required: string, available: string, currency: string) {
+    super(
+      'funding',
+      `Insufficient Irys balance: need ${required} ${currency}, have ${available} ${currency}`,
+      { required, available, currency }
+    );
+    this.name = 'InsufficientBalanceError';
+  }
+}
+
+export class ArweaveTimeoutError extends StorageError {
+  constructor(operation: string, timeoutMs: number) {
+    super('timeout', `Arweave ${operation} timed out after ${timeoutMs}ms`, { operation, timeoutMs });
+    this.name = 'ArweaveTimeoutError';
+  }
+}
+
+export class InvalidArweaveTxIdError extends ValidationError {
+  constructor(txId: string, reason?: string) {
+    super('txId', `Invalid Arweave transaction ID: ${txId}${reason ? ` (${reason})` : ''}`);
+    this.name = 'InvalidArweaveTxIdError';
+  }
+}
+
+export class SwapExecutionError extends StorageError {
+  constructor(message: string, details?: any) {
+    super('swap', `Swap execution failed: ${message}`, details);
+    this.name = 'SwapExecutionError';
+  }
+}
+
+/**
+ * Registry Query Cap Exceeded Error (L-4)
+ *
+ * Thrown when AgentRegistry.queryAgentsByService() cannot complete because
+ * the registry contains more than MAX_QUERY_AGENTS (1000) agents.
+ *
+ * ## Resolution
+ *
+ * When this error is thrown, you must migrate to an off-chain indexer:
+ *
+ * 1. **The Graph**: Deploy a subgraph indexing AgentRegistered events
+ *    - https://thegraph.com/docs/en/developing/creating-a-subgraph/
+ *
+ * 2. **Goldsky**: Mirror-based indexing (faster deployment)
+ *    - https://docs.goldsky.com/
+ *
+ * 3. **Alchemy Subgraphs**: Managed Graph service
+ *    - https://docs.alchemy.com/docs/subgraphs-overview
+ *
+ * ## Events to Index
+ *
+ * - `AgentRegistered(address indexed agent, string did, string endpoint, uint256 timestamp)`
+ * - `ServiceTypeUpdated(address indexed agent, bytes32 serviceTypeHash, bool added, uint256 timestamp)`
+ * - `ActiveStatusUpdated(address indexed agent, bool isActive, uint256 timestamp)`
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const agents = await registry.queryAgentsByService({ ... });
+ * } catch (error) {
+ *   if (error instanceof QueryCapExceededError) {
+ *     // Switch to off-chain indexer
+ *     const agents = await myIndexer.queryAgents({ ... });
+ *   }
+ * }
+ * ```
+ */
+export class QueryCapExceededError extends ACTPError {
+  constructor(registrySize: number, maxQueryAgents: number = 1000) {
+    super(
+      `Registry size (${registrySize}) exceeds query cap (${maxQueryAgents}). ` +
+        `On-chain queries are disabled to prevent DoS. Use an off-chain indexer instead.`,
+      'QUERY_CAP_EXCEEDED',
+      undefined,
+      {
+        registrySize,
+        maxQueryAgents,
+        solution: 'Migrate to off-chain indexer (The Graph, Goldsky, or Alchemy Subgraphs)'
+      }
+    );
+    this.name = 'QueryCapExceededError';
+  }
+}
+
+/**
+ * Agent/Job Errors (Basic & Standard API)
+ */
+
+/**
+ * No provider found for the requested service
+ *
+ * Thrown when request() cannot find any provider offering the service.
+ */
+export class NoProviderFoundError extends ACTPError {
+  constructor(service: string, details?: any) {
+    super(
+      `No provider found for service "${service}". ` +
+        `Ensure at least one agent is providing this service.`,
+      'NO_PROVIDER_FOUND',
+      undefined,
+      { service, ...details }
+    );
+    this.name = 'NoProviderFoundError';
+  }
+}
+
+/**
+ * Request timeout error
+ *
+ * Thrown when provider doesn't respond within the timeout period.
+ */
+export class TimeoutError extends ACTPError {
+  constructor(timeoutMs: number, operation?: string) {
+    super(
+      `Operation timed out after ${timeoutMs}ms${operation ? ` (${operation})` : ''}`,
+      'TIMEOUT',
+      undefined,
+      { timeoutMs, operation }
+    );
+    this.name = 'TimeoutError';
+  }
+}
+
+/**
+ * Provider rejected the job
+ *
+ * Thrown when provider explicitly rejects a job (e.g., budget too low).
+ */
+export class ProviderRejectedError extends ACTPError {
+  constructor(provider: string, reason?: string, details?: any) {
+    super(
+      `Provider ${provider} rejected the job${reason ? `: ${reason}` : ''}`,
+      'PROVIDER_REJECTED',
+      undefined,
+      { provider, reason, ...details }
+    );
+    this.name = 'ProviderRejectedError';
+  }
+}
+
+/**
+ * Provider failed to deliver result
+ *
+ * Thrown when provider transitions to DELIVERED but doesn't provide valid result.
+ */
+export class DeliveryFailedError extends ACTPError {
+  constructor(txId: string, reason?: string) {
+    super(
+      `Delivery failed for transaction ${txId}${reason ? `: ${reason}` : ''}`,
+      'DELIVERY_FAILED',
+      undefined,
+      { txId, reason }
+    );
+    this.name = 'DeliveryFailedError';
+  }
+}
+
+/**
+ * Dispute raised on transaction
+ *
+ * Thrown when requester raises a dispute on a delivered result.
+ */
+export class DisputeRaisedError extends ACTPError {
+  constructor(txId: string, reason?: string) {
+    super(
+      `Dispute raised for transaction ${txId}${reason ? `: ${reason}` : ''}`,
+      'DISPUTE_RAISED',
+      undefined,
+      { txId, reason }
+    );
+    this.name = 'DisputeRaisedError';
+  }
+}
+
+/**
+ * Service configuration error
+ *
+ * Thrown when Agent.provide() is called with invalid service configuration.
+ */
+export class ServiceConfigError extends ACTPError {
+  constructor(field: string, message: string, details?: any) {
+    super(
+      `Service configuration error (${field}): ${message}`,
+      'SERVICE_CONFIG_ERROR',
+      undefined,
+      { field, ...details }
+    );
+    this.name = 'ServiceConfigError';
+  }
+}
+
+/**
+ * Agent lifecycle error
+ *
+ * Thrown when invalid agent lifecycle operations are attempted
+ * (e.g., calling start() on already running agent).
+ */
+export class AgentLifecycleError extends ACTPError {
+  constructor(currentState: string, attemptedAction: string) {
+    super(
+      `Cannot ${attemptedAction} agent in ${currentState} state`,
+      'AGENT_LIFECYCLE_ERROR',
+      undefined,
+      { currentState, attemptedAction }
+    );
+    this.name = 'AgentLifecycleError';
+  }
+}
 

package/src/index.ts

@@ -1,95 +1,226 @@
 /**
- * ACTP SDK - Protocol SDK for Agent Commerce
+ * AGIRAILS SDK - Agent Commerce Transaction Protocol
+ *
+ * This is the main entry point for the AGIRAILS SDK.
+ * The recommended way to use this SDK is through the ACTPClient class.
+ *
  * @packageDocumentation
+ *
+ * @example
+ * ```typescript
+ * import { ACTPClient } from '@agirails/sdk';
+ *
+ * // Create client in mock mode
+ * const client = await ACTPClient.create({
+ *   mode: 'mock',
+ *   requesterAddress: '0x1234...',
+ * });
+ *
+ * // Mint some tokens for testing
+ * await client.mintTokens(client.getAddress(), '10000000000');
+ *
+ * // Create a payment
+ * const result = await client.beginner.pay({
+ *   to: '0xProvider...',
+ *   amount: '100',
+ * });
+ *
+ * console.log('Transaction ID:', result.txId);
+ * ```
  */
 
-// Main client
-export { ACTPClient, ACTPClientConfig } from './ACTPClient';
+// =============================================================================
+// Primary API - ACTPClient
+// =============================================================================
+
+export {
+  ACTPClient,
+  ACTPClientConfig,
+  ACTPClientMode,
+  ACTPClientInfo,
+} from './ACTPClient';
+
+// =============================================================================
+// Adapter Layer - Three-Level API
+// =============================================================================
+
+export {
+  BaseAdapter,
+  DEFAULT_DISPUTE_WINDOW_SECONDS,
+  DEFAULT_DEADLINE_SECONDS,
+  MIN_AMOUNT_WEI,
+  MAX_DEADLINE_HOURS,
+  MAX_DEADLINE_DAYS,
+} from './adapters/BaseAdapter';
+
+export {
+  BeginnerAdapter,
+  BeginnerPayParams,
+  BeginnerPayResult,
+} from './adapters/BeginnerAdapter';
+
+export {
+  IntermediateAdapter,
+  IntermediateTransactionParams,
+} from './adapters/IntermediateAdapter';
+
+// =============================================================================
+// Runtime Layer - Protocol Implementation
+// =============================================================================
+
+// Runtime interfaces
+export {
+  IACTPRuntime,
+  IMockRuntime,
+  CreateTransactionParams,
+} from './runtime/IACTPRuntime';
+
+// MockRuntime (for local development)
+export {
+  MockRuntime,
+  InsufficientBalanceError,
+  EscrowNotFoundError,
+  DeadlinePassedError,
+  ContractPausedError,
+  DisputeWindowActiveError,
+} from './runtime/MockRuntime';
+
+// MockStateManager (for custom state management)
+export {
+  MockStateManager,
+  MockStateCorruptedError,
+  MockStateVersionError,
+  MockStateLockError,
+} from './runtime/MockStateManager';
+
+// BlockchainRuntime (for testnet/mainnet)
+export {
+  BlockchainRuntime,
+  BlockchainRuntimeConfig,
+} from './runtime/BlockchainRuntime';
+
+// =============================================================================
+// Type Exports
+// =============================================================================
+
+export {
+  MockState,
+  MockTransaction,
+  MockEscrow,
+  MockAccount,
+  MockBlockchain,
+  MockEvent,
+  TransactionState,
+  TransactionStateValue,
+  MOCK_STATE_DEFAULTS,
+} from './runtime/types/MockState';
+
+// =============================================================================
+// Protocol Layer (from sdk-js merge)
+// =============================================================================
 
 // Protocol modules
 export { ACTPKernel } from './protocol/ACTPKernel';
 export { EscrowVault } from './protocol/EscrowVault';
 export { EventMonitor } from './protocol/EventMonitor';
-export { ProofGenerator } from './protocol/ProofGenerator';
 export { MessageSigner } from './protocol/MessageSigner';
+export { ProofGenerator, URLValidationConfig } from './protocol/ProofGenerator';
 export { EASHelper, EASConfig } from './protocol/EASHelper';
-export { QuoteBuilder, QuoteParams, QuoteMessage } from './protocol/QuoteBuilder';
+export { AgentRegistry } from './protocol/AgentRegistry';
+export { DIDManager } from './protocol/DIDManager';
+export { DIDResolver } from './protocol/DIDResolver';
 
-// Types
-export {
+// Builders
+export { QuoteBuilder } from './builders/QuoteBuilder';
+export { DeliveryProofBuilder } from './builders/DeliveryProofBuilder';
+
+// Config
+export { getNetwork } from './config/networks';
+export type { NetworkConfig } from './config/networks';
+
+// Protocol types
+export type {
   State,
-  StateMachine,
   Transaction,
-  CreateTransactionParams,
+  CreateTransactionParams as ProtocolCreateParams,
   DisputeResolution,
   EconomicParams,
-  Escrow,
-  ACTPMessage,
-  QuoteRequest,
-  QuoteResponse,
-  DeliveryProof,
-  DeliveryProofMessage,
-  EASAttestationData
 } from './types';
 
-// EIP-712 types
+// Utils
+export { NonceManager, InMemoryNonceManager } from './utils/NonceManager';
+export { IReceivedNonceTracker, InMemoryReceivedNonceTracker } from './utils/ReceivedNonceTracker';
+// Note: IPFSClient is not exported from main index to avoid ESM compatibility issues
+// Import directly from '@agirails/sdk/utils/IPFSClient' if needed
+export type { IPFSClient, IPFSClientConfig } from './utils/IPFSClient';
+export { generateSecureNonce, isValidNonce, generateSecureNonces } from './utils/SecureNonce';
+export { Semaphore, RateLimiter } from './utils/Semaphore';
 export {
-  EIP712Domain,
-  AIP4DeliveryProofTypes,
-  AIP4DeliveryProofData,
-  DeliveryProofTypes,
-  DeliveryProofData,
-  deliveryProofDataFromProof
-} from './types/eip712';
+  IUsedAttestationTracker,
+  InMemoryUsedAttestationTracker,
+  FileBasedUsedAttestationTracker,
+  createUsedAttestationTracker,
+} from './utils/UsedAttestationTracker';
 
-// Builders
+// Helper utilities
 export {
-  DeliveryProofBuilder,
-  DeliveryProofParams,
-  AGIRAILS_DELIVERY_SCHEMA_UID
-} from './builders';
+  USDC,
+  Deadline,
+  Address,
+  Bytes32,
+  State as StateHelpers,
+  DisputeWindow,
+  parseUSDC,
+  formatUSDC,
+  shortenAddress,
+  ServiceHash,
+  hashServiceMetadata,
+} from './utils/Helpers';
+export type { ServiceMetadata } from './utils/Helpers';
 
-// Utilities
-export {
-  canonicalJsonStringify,
-  computeCanonicalHash,
-  computeResultHash
-} from './utils/canonicalJson';
+// =============================================================================
+// Basic API - Simple provide/request interface
+// =============================================================================
 
-export {
-  IPFSClient,
-  IPFSHTTPClientImpl,
-  IPFSClientConfig,
-  createIPFSClient,
-  IPFS_CONFIGS
-} from './utils/IPFSClient';
+export { provide, request, serviceDirectory } from './level0';
+export type {
+  Provider,
+  ProviderStatus,
+  ProviderStats,
+  ProviderBalance,
+} from './level0';
 
-export {
-  NonceManager,
-  InMemoryNonceManager,
-  DIDScopedNonceManager,
-  createNonceManager
-} from './utils/NonceManager';
+// =============================================================================
+// Standard API - Agent-based interface
+// =============================================================================
+
+export { Agent, calculatePrice, DEFAULT_PRICING_STRATEGY } from './level1';
+export type {
+  AgentConfig,
+  AgentStatus,
+  AgentStats,
+  AgentBalance,
+  ServiceConfig,
+  Job,
+  JobHandler,
+  JobContext,
+  ProvideOptions,
+  RequestOptions,
+  RequestResult,
+  RequestStatus,
+  WalletOption,
+  NetworkOption,
+  PricingStrategy,
+  ServiceCost,
+  BelowPriceBehavior,
+  BelowCostBehavior,
+  PriceCalculation,
+} from './level1';
+
+// =============================================================================
+// Enhanced Error Exports
+// =============================================================================
 
-// V4 Security: Nonce Replay Protection
-export {
-  IReceivedNonceTracker,
-  InMemoryReceivedNonceTracker,
-  SetBasedReceivedNonceTracker,
-  createReceivedNonceTracker,
-  NonceValidationResult
-} from './utils/ReceivedNonceTracker';
-
-// Validation utilities
-export {
-  validateAddress,
-  validateAmount,
-  validateDeadline,
-  validateDisputeWindow,
-  validateTxId
-} from './utils/validation';
-
-// Errors
 export {
   ACTPError,
   InsufficientFundsError,
@@ -101,8 +232,13 @@ export {
   NetworkError,
   ValidationError,
   InvalidAddressError,
-  InvalidAmountError
+  InvalidAmountError,
+  // Basic/Standard API errors
+  NoProviderFoundError,
+  TimeoutError,
+  ProviderRejectedError,
+  DeliveryFailedError,
+  DisputeRaisedError,
+  ServiceConfigError,
+  AgentLifecycleError,
 } from './errors';
-
-// Configuration
-export { NetworkConfig, NETWORKS, getNetwork, isValidNetwork } from './config/networks';