@agirails/sdk 2.0.2 → 2.0.3

package/src/ACTPClient.ts

@@ -3,8 +3,8 @@
  *
  * Provides the unified API for interacting with the ACTP protocol
  * through three different abstraction levels:
- * - `beginner`: High-level, opinionated API for simple use cases
- * - `intermediate`: Balanced API with more control
+ * - `basic`: High-level, opinionated API for simple use cases
+ * - `standard`: Balanced API with more control
  * - `advanced`: Direct protocol access for full control
  *
  * @module ACTPClient
@@ -17,18 +17,18 @@
  *   requesterAddress: '0x1234...',
  * });
  *
- * // Beginner API - simplest approach
- * const result = await client.beginner.pay({
+ * // Basic API - simplest approach
+ * const result = await client.basic.pay({
  *   to: '0xProvider...',
  *   amount: '100',
  * });
  *
- * // Intermediate API - more control
- * const txId = await client.intermediate.createTransaction({
+ * // Standard API - more control
+ * const txId = await client.standard.createTransaction({
  *   provider: '0xProvider...',
  *   amount: '100',
  * });
- * await client.intermediate.linkEscrow(txId);
+ * await client.standard.linkEscrow(txId);
  *
  * // Advanced API - direct protocol access
  * const tx = await client.advanced.getTransaction(txId);
@@ -43,8 +43,8 @@ import { MockRuntime } from './runtime/MockRuntime';
 import { MockStateManager } from './runtime/MockStateManager';
 import { BlockchainRuntime } from './runtime/BlockchainRuntime';
 import { IACTPRuntime, IMockRuntime } from './runtime/IACTPRuntime';
-import { BeginnerAdapter } from './adapters/BeginnerAdapter';
-import { IntermediateAdapter } from './adapters/IntermediateAdapter';
+import { BasicAdapter } from './adapters/BasicAdapter';
+import { StandardAdapter } from './adapters/StandardAdapter';
 import { EASHelper, EASConfig } from './protocol/EASHelper';
 import { getNetwork } from './config/networks';
 
@@ -324,13 +324,13 @@ export interface ACTPClientInfo {
  * This class provides a unified interface to the ACTP protocol through
  * three abstraction levels, catering to developers with different needs:
  *
- * **Beginner API** (`client.beginner`):
+ * **Basic API** (`client.basic`):
  * - Simplest possible interface
  * - Smart defaults (24h deadline, 2-day dispute window)
  * - User-friendly inputs (strings, no BigInt)
  * - Perfect for: Quick prototypes, simple integrations
  *
- * **Intermediate API** (`client.intermediate`):
+ * **Standard API** (`client.standard`):
  * - Explicit lifecycle methods
  * - More control over transaction flow
  * - Still with user-friendly input parsing
@@ -352,15 +352,15 @@ export interface ACTPClientInfo {
  *
  * // Three ways to create a transaction:
  *
- * // 1. Beginner: One call does everything
- * await client.beginner.pay({ to: '0xProvider', amount: '100' });
+ * // 1. Basic: One call does everything
+ * await client.basic.pay({ to: '0xProvider', amount: '100' });
  *
- * // 2. Intermediate: Explicit steps
- * const txId = await client.intermediate.createTransaction({
+ * // 2. Standard: Explicit steps
+ * const txId = await client.standard.createTransaction({
  *   provider: '0xProvider',
  *   amount: '100',
  * });
- * await client.intermediate.linkEscrow(txId);
+ * await client.standard.linkEscrow(txId);
  *
  * // 3. Advanced: Full control
  * const txId = await client.advanced.createTransaction({
@@ -374,7 +374,7 @@ export interface ACTPClientInfo {
  */
 export class ACTPClient {
   /**
-   * Beginner-level API.
+   * Basic-level API.
    *
    * Provides the simplest interface for creating and checking transactions.
    * Ideal for developers who want to "just make it work" without deep
@@ -382,7 +382,7 @@ export class ACTPClient {
    *
    * @example
    * ```typescript
-   * const result = await client.beginner.pay({
+   * const result = await client.basic.pay({
    *   to: '0xProvider...',
    *   amount: '100',
    * });
@@ -390,10 +390,10 @@ export class ACTPClient {
    * console.log('State:', result.state); // 'COMMITTED'
    * ```
    */
-  public readonly beginner: BeginnerAdapter;
+  public readonly basic: BasicAdapter;
 
   /**
-   * Intermediate-level API.
+   * Standard-level API.
    *
    * Provides explicit lifecycle methods for more control over
    * the transaction flow while still offering user-friendly inputs.
@@ -401,20 +401,20 @@ export class ACTPClient {
    * @example
    * ```typescript
    * // Create transaction (INITIATED state)
-   * const txId = await client.intermediate.createTransaction({
+   * const txId = await client.standard.createTransaction({
    *   provider: '0xProvider...',
    *   amount: '100',
    *   deadline: '+7d',
    * });
    *
    * // Link escrow (auto-transitions to COMMITTED)
-   * await client.intermediate.linkEscrow(txId);
+   * await client.standard.linkEscrow(txId);
    *
    * // Transition to DELIVERED
-   * await client.intermediate.transitionState(txId, 'DELIVERED');
+   * await client.standard.transitionState(txId, 'DELIVERED');
    * ```
    */
-  public readonly intermediate: IntermediateAdapter;
+  public readonly standard: StandardAdapter;
 
   /**
    * The underlying runtime implementation.
@@ -447,8 +447,8 @@ export class ACTPClient {
     this.runtime = runtime;
     this.info = info;
     this.easHelper = easHelper;
-    this.beginner = new BeginnerAdapter(runtime, requesterAddress, easHelper);
-    this.intermediate = new IntermediateAdapter(runtime, requesterAddress, easHelper);
+    this.basic = new BasicAdapter(runtime, requesterAddress, easHelper);
+    this.standard = new StandardAdapter(runtime, requesterAddress, easHelper);
   }
 
   // ==========================================================================

package/src/adapters/{BeginnerAdapter.ts → BasicAdapter.ts}

@@ -1,5 +1,5 @@
 /**
- * BeginnerAdapter - High-level, opinionated API for simple use cases
+ * BasicAdapter - High-level, opinionated API for simple use cases
  *
  * Provides the simplest possible interface for creating and checking transactions.
  * Designed for developers who want to "just make it work" without deep protocol knowledge.
@@ -10,7 +10,7 @@
  * - User-friendly input (strings, no BigInt)
  * - User-friendly output (formatted amounts, ISO dates)
  *
- * @module adapters/BeginnerAdapter
+ * @module adapters/BasicAdapter
  */
 
 import { BaseAdapter, ValidationError, DEFAULT_DISPUTE_WINDOW_SECONDS } from './BaseAdapter';
@@ -21,9 +21,9 @@ import { EASHelper } from '../protocol/EASHelper';
 /**
  * Parameters for creating a simple payment.
  *
- * This is the most beginner-friendly interface - minimal required fields.
+ * This is the most user-friendly interface - minimal required fields.
  */
-export interface BeginnerPayParams {
+export interface BasicPayParams {
   /** Recipient address (provider) */
   to: string;
 
@@ -42,7 +42,7 @@ export interface BeginnerPayParams {
  *
  * Provides user-friendly formatted data (not raw protocol types).
  */
-export interface BeginnerPayResult {
+export interface BasicPayResult {
   /** Transaction ID (bytes32 hex string) */
   txId: string;
 
@@ -63,7 +63,7 @@ export interface BeginnerPayResult {
 }
 
 /**
- * BeginnerAdapter - High-level API for simple payment flows.
+ * BasicAdapter - High-level API for simple payment flows.
  *
  * This adapter provides the simplest possible interface:
  * - `pay()` - Create and fund a transaction in one call
@@ -76,7 +76,7 @@ export interface BeginnerPayResult {
  * const client = await ACTPClient.create({ mode: 'mock' });
  *
  * // Simple payment (all defaults)
- * const result = await client.beginner.pay({
+ * const result = await client.basic.pay({
  *   to: '0xProvider123',
  *   amount: '100',
  * });
@@ -84,15 +84,15 @@ export interface BeginnerPayResult {
  * console.log('Amount:', result.amount); // "100.00 USDC"
  *
  * // Check status
- * const status = await client.beginner.checkStatus(result.txId);
+ * const status = await client.basic.checkStatus(result.txId);
  * if (status.canAccept) {
  *   console.log('Provider can accept this transaction');
  * }
  * ```
  */
-export class BeginnerAdapter extends BaseAdapter {
+export class BasicAdapter extends BaseAdapter {
   /**
-   * Creates a new BeginnerAdapter instance.
+   * Creates a new BasicAdapter instance.
    *
    * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
    * @param requesterAddress - The requester's Ethereum address
@@ -136,7 +136,7 @@ export class BeginnerAdapter extends BaseAdapter {
    * });
    * ```
    */
-  async pay(params: BeginnerPayParams): Promise<BeginnerPayResult> {
+  async pay(params: BasicPayParams): Promise<BasicPayResult> {
     // Validate and parse inputs
     const provider = this.validateAddress(params.to, 'to');
     const amount = this.parseAmount(params.amount);

package/src/adapters/{IntermediateAdapter.ts → StandardAdapter.ts}

@@ -1,7 +1,7 @@
 /**
- * IntermediateAdapter - Balanced API for developers with some protocol knowledge
+ * StandardAdapter - Balanced API for developers with some protocol knowledge
  *
- * Provides more control than BeginnerAdapter while still offering convenience:
+ * Provides more control than BasicAdapter while still offering convenience:
  * - Explicit transaction lifecycle methods
  * - Direct escrow operations
  * - State transition control
@@ -9,7 +9,7 @@
  * Use this adapter when you need fine-grained control but still want
  * user-friendly input parsing and validation.
  *
- * @module adapters/IntermediateAdapter
+ * @module adapters/StandardAdapter
  */
 
 import { BaseAdapter, ValidationError, DEFAULT_DISPUTE_WINDOW_SECONDS } from './BaseAdapter';
@@ -18,11 +18,11 @@ import { MockTransaction, TransactionState } from '../runtime/types/MockState';
 import { EASHelper } from '../protocol/EASHelper';
 
 /**
- * Parameters for creating a transaction (intermediate level).
+ * Parameters for creating a transaction (standard level).
  *
- * More explicit than BeginnerPayParams but still with smart defaults.
+ * More explicit than BasicPayParams but still with smart defaults.
  */
-export interface IntermediateTransactionParams {
+export interface StandardTransactionParams {
   /** Provider's Ethereum address */
   provider: string;
 
@@ -40,7 +40,7 @@ export interface IntermediateTransactionParams {
 }
 
 /**
- * IntermediateAdapter - Balanced API for transaction lifecycle control.
+ * StandardAdapter - Balanced API for transaction lifecycle control.
  *
  * Provides explicit methods for each stage of the ACTP lifecycle:
  * - `createTransaction()` - Create transaction without escrow
@@ -55,25 +55,25 @@ export interface IntermediateTransactionParams {
  * const client = await ACTPClient.create({ mode: 'mock' });
  *
  * // Create transaction (INITIATED state)
- * const txId = await client.intermediate.createTransaction({
+ * const txId = await client.standard.createTransaction({
  *   provider: '0xProvider123',
  *   amount: '100',
  *   deadline: '+7d',
  * });
  *
  * // Link escrow (auto-transitions to COMMITTED)
- * await client.intermediate.linkEscrow(txId, '100');
+ * await client.standard.linkEscrow(txId, '100');
  *
  * // Provider delivers
- * await client.intermediate.transitionState(txId, 'DELIVERED');
+ * await client.standard.transitionState(txId, 'DELIVERED');
  *
  * // Release funds after dispute window
- * await client.intermediate.releaseEscrow(escrowId);
+ * await client.standard.releaseEscrow(escrowId);
  * ```
  */
-export class IntermediateAdapter extends BaseAdapter {
+export class StandardAdapter extends BaseAdapter {
   /**
-   * Creates a new IntermediateAdapter instance.
+   * Creates a new StandardAdapter instance.
    *
    * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
    * @param requesterAddress - The requester's Ethereum address
@@ -90,7 +90,7 @@ export class IntermediateAdapter extends BaseAdapter {
   /**
    * Create a transaction (INITIATED state, no escrow yet).
    *
-   * Unlike `beginner.pay()`, this only creates the transaction
+   * Unlike `basic.pay()`, this only creates the transaction
    * without linking escrow. You must call `linkEscrow()` separately.
    *
    * @param params - Transaction parameters
@@ -106,7 +106,7 @@ export class IntermediateAdapter extends BaseAdapter {
    * });
    * ```
    */
-  async createTransaction(params: IntermediateTransactionParams): Promise<string> {
+  async createTransaction(params: StandardTransactionParams): Promise<string> {
     const provider = this.validateAddress(params.provider, 'provider');
     const amount = this.parseAmount(params.amount);
     const currentTime = this.runtime.time.now();

package/src/adapters/index.ts

@@ -3,8 +3,8 @@
  *
  * This module exports all adapter classes and types for the Three-Level API:
  * - BaseAdapter: Abstract base with shared utilities
- * - BeginnerAdapter: High-level, opinionated API
- * - IntermediateAdapter: Balanced control API
+ * - BasicAdapter: High-level, opinionated API
+ * - StandardAdapter: Balanced control API
  *
  * @module adapters
  */
@@ -18,8 +18,8 @@ export {
   MAX_DEADLINE_HOURS,
   MAX_DEADLINE_DAYS,
 } from './BaseAdapter';
-export { BeginnerAdapter, BeginnerPayParams, BeginnerPayResult } from './BeginnerAdapter';
-export { IntermediateAdapter, IntermediateTransactionParams } from './IntermediateAdapter';
+export { BasicAdapter, BasicPayParams, BasicPayResult } from './BasicAdapter';
+export { StandardAdapter, StandardTransactionParams } from './StandardAdapter';
 
 // Re-export runtime interface for convenience
 export { IACTPRuntime, CreateTransactionParams } from '../runtime/IACTPRuntime';

package/src/cli/commands/pay.ts

@@ -1,5 +1,5 @@
 /**
- * Pay Command - One-liner payment command (beginner API)
+ * Pay Command - One-liner payment command (basic API)
  *
  * The simplest way to create a payment transaction.
  * Creates transaction, links escrow, and returns immediately.
@@ -76,7 +76,7 @@ async function runPay(
     const disputeWindow = parseInt(options.disputeWindow, 10);
 
     // Create payment
-    const result = await client.beginner.pay({
+    const result = await client.basic.pay({
       to,
       amount,
       deadline,

package/src/cli/commands/tx.ts

@@ -2,7 +2,7 @@
  * Transaction Commands - tx subcommand group
  *
  * Commands for managing ACTP transactions:
- * - tx create: Create a new transaction (intermediate API)
+ * - tx create: Create a new transaction (standard API)
  * - tx status: Check transaction status
  * - tx list: List all transactions
  * - tx deliver: Mark transaction as delivered
@@ -66,7 +66,7 @@ function createTxCreateCommand(): Command {
         const disputeWindow = parseInt(options.disputeWindow, 10);
 
         // Create transaction
-        const txId = await client.intermediate.createTransaction({
+        const txId = await client.standard.createTransaction({
           provider,
           amount,
           deadline,
@@ -77,10 +77,10 @@ function createTxCreateCommand(): Command {
         // Optionally fund
         let escrowId: string | undefined;
         if (options.fund) {
-          escrowId = await client.intermediate.linkEscrow(txId);
+          escrowId = await client.standard.linkEscrow(txId);
         }
 
-        const tx = await client.intermediate.getTransaction(txId);
+        const tx = await client.standard.getTransaction(txId);
         if (!tx) throw new Error('Transaction not found after creation');
 
         output.result(
@@ -134,13 +134,13 @@ function createTxStatusCommand(): Command {
         }
 
         const client = await createClient();
-        const tx = await client.intermediate.getTransaction(txId);
+        const tx = await client.standard.getTransaction(txId);
 
         if (!tx) {
           throw new Error(`Transaction not found: ${txId}`);
         }
 
-        const status = await client.beginner.checkStatus(txId);
+        const status = await client.basic.checkStatus(txId);
 
         if (options.quiet) {
           output.raw(tx.state);
@@ -289,9 +289,9 @@ function createTxDeliverCommand(): Command {
         const client = await createClient();
 
         // Transition to DELIVERED
-        await client.intermediate.transitionState(txId, 'DELIVERED' as TransactionState);
+        await client.standard.transitionState(txId, 'DELIVERED' as TransactionState);
 
-        const tx = await client.intermediate.getTransaction(txId);
+        const tx = await client.standard.getTransaction(txId);
         if (!tx) throw new Error('Transaction not found');
 
         output.result(
@@ -345,15 +345,15 @@ function createTxSettleCommand(): Command {
         const client = await createClient();
 
         // Get transaction to find escrow
-        const tx = await client.intermediate.getTransaction(txId);
+        const tx = await client.standard.getTransaction(txId);
         if (!tx) throw new Error(`Transaction not found: ${txId}`);
         if (!tx.escrowId) throw new Error('Transaction has no linked escrow');
 
         // Release escrow
-        await client.intermediate.releaseEscrow(tx.escrowId);
+        await client.standard.releaseEscrow(tx.escrowId);
 
         // Get updated transaction
-        const updatedTx = await client.intermediate.getTransaction(txId);
+        const updatedTx = await client.standard.getTransaction(txId);
         if (!updatedTx) throw new Error('Transaction not found');
 
         output.result(
@@ -402,9 +402,9 @@ function createTxCancelCommand(): Command {
         const client = await createClient();
 
         // Transition to CANCELLED
-        await client.intermediate.transitionState(txId, 'CANCELLED' as TransactionState);
+        await client.standard.transitionState(txId, 'CANCELLED' as TransactionState);
 
-        const tx = await client.intermediate.getTransaction(txId);
+        const tx = await client.standard.getTransaction(txId);
         if (!tx) throw new Error('Transaction not found');
 
         output.result(

package/src/cli/commands/watch.ts

@@ -85,7 +85,7 @@ async function runWatch(
   }
 
   // Get initial state
-  const tx = await client.intermediate.getTransaction(txId);
+  const tx = await client.standard.getTransaction(txId);
   if (!tx) {
     throw new Error(`Transaction not found: ${txId}`);
   }
@@ -123,7 +123,7 @@ async function runWatch(
     }
 
     try {
-      const updatedTx = await client.intermediate.getTransaction(txId);
+      const updatedTx = await client.standard.getTransaction(txId);
       if (!updatedTx) {
         output.warning('Transaction no longer exists');
         process.exit(ExitCode.ERROR);

package/src/index.ts

@@ -20,7 +20,7 @@
  * await client.mintTokens(client.getAddress(), '10000000000');
  *
  * // Create a payment
- * const result = await client.beginner.pay({
+ * const result = await client.basic.pay({
  *   to: '0xProvider...',
  *   amount: '100',
  * });
@@ -54,15 +54,15 @@ export {
 } from './adapters/BaseAdapter';
 
 export {
-  BeginnerAdapter,
-  BeginnerPayParams,
-  BeginnerPayResult,
-} from './adapters/BeginnerAdapter';
+  BasicAdapter,
+  BasicPayParams,
+  BasicPayResult,
+} from './adapters/BasicAdapter';
 
 export {
-  IntermediateAdapter,
-  IntermediateTransactionParams,
-} from './adapters/IntermediateAdapter';
+  StandardAdapter,
+  StandardTransactionParams,
+} from './adapters/StandardAdapter';
 
 // =============================================================================
 // Runtime Layer - Protocol Implementation

package/src/protocol/ACTPKernel.ts

@@ -455,13 +455,13 @@ export class ACTPKernel {
    *
    * **REQUIRED: Use secure wrapper methods instead:**
    *
-   * 1. **BeginnerAdapter.completePayment()** (recommended for most users)
+   * 1. **BasicAdapter.completePayment()** (recommended for most users)
    *    - Automatically verifies attestation before release
    *    - Validates attestation belongs to this transaction
    *    - Checks attestation hasn't been used before
    *    - Handles all state transitions
    *
-   * 2. **IntermediateAdapter.releaseEscrow()** (for more control)
+   * 2. **StandardAdapter.releaseEscrow()** (for more control)
    *    - Explicitly requires attestation verification
    *    - Throws error if attestation invalid or missing
    *    - Allows custom verification logic
@@ -493,15 +493,15 @@ export class ACTPKernel {
    *
    * **For testnet/mainnet deployments:**
    * - MUST configure easConfig in ACTPClient
-   * - MUST use wrapper methods (Beginner/Intermediate adapters)
+   * - MUST use wrapper methods (Basic/Standard adapters)
    * - NEVER call this method directly unless attestation verified
    *
    * @param txId - Transaction ID to settle
    * @throws {ValidationError} If txId is invalid
    * @throws {TransactionRevertedError} If contract reverts
    *
-   * @see {@link BeginnerAdapter.completePayment} Recommended method with built-in verification
-   * @see {@link IntermediateAdapter.releaseEscrow} Explicit verification method
+   * @see {@link BasicAdapter.completePayment} Recommended method with built-in verification
+   * @see {@link StandardAdapter.releaseEscrow} Explicit verification method
    * @see {@link EASHelper.verifyDeliveryAttestation} Manual verification helper
    */
   async releaseEscrow(txId: string): Promise<void> {

package/src/runtime/BlockchainRuntime.ts

@@ -84,7 +84,7 @@ export interface BlockchainRuntimeConfig {
  * });
  *
  * // Now use with adapters
- * const adapter = new BeginnerAdapter(runtime, requesterAddress);
+ * const adapter = new BasicAdapter(runtime, requesterAddress);
  * await adapter.createJob({...});
  * ```
  */

package/src/runtime/IACTPRuntime.ts

@@ -49,7 +49,7 @@ export interface CreateTransactionParams {
  * });
  *
  * // Adapters work with either implementation
- * const adapter = new BeginnerAdapter(runtime, requesterAddress);
+ * const adapter = new BasicAdapter(runtime, requesterAddress);
  * ```
  */
 export interface IACTPRuntime {

package/src/utils/ErrorRecoveryGuide.ts

@@ -465,7 +465,7 @@ const DEFAULT_RECOVERY: ErrorRecoveryInfo = {
  * @example
  * ```typescript
  * try {
- *   await client.beginner.pay({ to: provider, amount: '100' });
+ *   await client.basic.pay({ to: provider, amount: '100' });
  * } catch (error) {
  *   const recovery = ErrorRecoveryGuide.analyze(error);
  *   console.log('Category:', recovery.category);
@@ -622,7 +622,7 @@ ${recovery.securityNotes.map((n) => `  ! ${n}`).join('\n')}`;
  * @example
  * ```typescript
  * const result = await withRecoveryGuidance(
- *   () => client.beginner.pay({ to: provider, amount: '100' }),
+ *   () => client.basic.pay({ to: provider, amount: '100' }),
  *   { logGuidance: true, autoRetry: true }
  * );
  * ```