@agirails/sdk 2.0.1-beta → 2.0.3

package/dist/adapters/BasicAdapter.d.ts

@@ -0,0 +1,152 @@
+/**
+ * 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.
+ *
+ * Key Features:
+ * - Smart defaults (24h deadline, 2-day dispute window)
+ * - Inferred requester (from constructor)
+ * - User-friendly input (strings, no BigInt)
+ * - User-friendly output (formatted amounts, ISO dates)
+ *
+ * @module adapters/BasicAdapter
+ */
+import { BaseAdapter } from './BaseAdapter';
+import { IACTPRuntime } from '../runtime/IACTPRuntime';
+import { EASHelper } from '../protocol/EASHelper';
+/**
+ * Parameters for creating a simple payment.
+ *
+ * This is the most user-friendly interface - minimal required fields.
+ */
+export interface BasicPayParams {
+    /** Recipient address (provider) */
+    to: string;
+    /** Amount in user-friendly format ("100", "100.50", "100 USDC", "$100") */
+    amount: string | number;
+    /** Optional: Deadline as relative time ("+24h") or Unix timestamp. Defaults to +24h */
+    deadline?: string | number;
+    /** Optional: Dispute window in seconds. Defaults to 172800 (2 days) */
+    disputeWindow?: number;
+}
+/**
+ * Result of creating a payment.
+ *
+ * Provides user-friendly formatted data (not raw protocol types).
+ */
+export interface BasicPayResult {
+    /** Transaction ID (bytes32 hex string) */
+    txId: string;
+    /** Provider address */
+    provider: string;
+    /** Requester address (caller) */
+    requester: string;
+    /** Amount in USDC (human-readable, e.g., "100.00 USDC") */
+    amount: string;
+    /** Deadline as ISO 8601 timestamp */
+    deadline: string;
+    /** Transaction state */
+    state: string;
+}
+/**
+ * BasicAdapter - High-level API for simple payment flows.
+ *
+ * This adapter provides the simplest possible interface:
+ * - `pay()` - Create and fund a transaction in one call
+ * - `checkStatus()` - Get transaction status with action hints
+ *
+ * All complexity is hidden behind smart defaults.
+ *
+ * @example
+ * ```typescript
+ * const client = await ACTPClient.create({ mode: 'mock' });
+ *
+ * // Simple payment (all defaults)
+ * const result = await client.basic.pay({
+ *   to: '0xProvider123',
+ *   amount: '100',
+ * });
+ * console.log('Transaction ID:', result.txId);
+ * console.log('Amount:', result.amount); // "100.00 USDC"
+ *
+ * // Check status
+ * const status = await client.basic.checkStatus(result.txId);
+ * if (status.canAccept) {
+ *   console.log('Provider can accept this transaction');
+ * }
+ * ```
+ */
+export declare class BasicAdapter extends BaseAdapter {
+    private runtime;
+    private easHelper?;
+    /**
+     * Creates a new BasicAdapter instance.
+     *
+     * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
+     * @param requesterAddress - The requester's Ethereum address
+     * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+     */
+    constructor(runtime: IACTPRuntime, requesterAddress: string, easHelper?: EASHelper | undefined);
+    /**
+     * Create a payment transaction with smart defaults.
+     *
+     * This is the simplest way to create a transaction - just specify
+     * recipient and amount. All other parameters use sensible defaults.
+     *
+     * Smart defaults:
+     * - Requester: Inferred from constructor
+     * - Deadline: 24 hours from now
+     * - Dispute window: 2 days (172800 seconds)
+     *
+     * Validations performed:
+     * - Address format (0x-prefixed hex)
+     * - Amount format (positive number)
+     * - Deadline in future
+     * - Cannot pay yourself
+     *
+     * @param params - Payment parameters
+     * @returns User-friendly payment result
+     * @throws {ValidationError} If inputs are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.pay({
+     *   to: '0xProvider123',
+     *   amount: '100.50',
+     *   deadline: '+7d', // Optional: 7 days from now
+     * });
+     * ```
+     */
+    pay(params: BasicPayParams): Promise<BasicPayResult>;
+    /**
+     * Check payment status by transaction ID.
+     *
+     * Returns current state plus action hints (what can be done next).
+     *
+     * Action hints:
+     * - `canAccept`: Provider can accept (INITIATED state, before deadline)
+     * - `canComplete`: Provider can mark as delivered (COMMITTED state)
+     * - `canDispute`: Requester can dispute (DELIVERED state, within dispute window)
+     *
+     * @param txId - Transaction ID to check
+     * @returns Status with action hints
+     * @throws {Error} If transaction not found
+     *
+     * @example
+     * ```typescript
+     * const status = await adapter.checkStatus(txId);
+     * console.log('State:', status.state); // "COMMITTED"
+     * if (status.canComplete) {
+     *   // Provider can deliver now
+     * }
+     * ```
+     */
+    checkStatus(txId: string): Promise<{
+        state: string;
+        canAccept: boolean;
+        canComplete: boolean;
+        canDispute: boolean;
+    }>;
+}
+//# sourceMappingURL=BasicAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BasicAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/BasicAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAmD,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IAEX,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE3B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IAEjB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IAEf,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IAEjB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,YAAa,SAAQ,WAAW;IASzC,OAAO,CAAC,OAAO;IAEf,OAAO,CAAC,SAAS,CAAC;IAVpB;;;;;;OAMG;gBAEO,OAAO,EAAE,YAAY,EAC7B,gBAAgB,EAAE,MAAM,EAChB,SAAS,CAAC,uBAAW;IAK/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,GAAG,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAiD1D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,OAAO,CAAC;QACnB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CAgBH"}

package/dist/adapters/BasicAdapter.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * 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.
+ *
+ * Key Features:
+ * - Smart defaults (24h deadline, 2-day dispute window)
+ * - Inferred requester (from constructor)
+ * - User-friendly input (strings, no BigInt)
+ * - User-friendly output (formatted amounts, ISO dates)
+ *
+ * @module adapters/BasicAdapter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BasicAdapter = void 0;
+const BaseAdapter_1 = require("./BaseAdapter");
+/**
+ * BasicAdapter - High-level API for simple payment flows.
+ *
+ * This adapter provides the simplest possible interface:
+ * - `pay()` - Create and fund a transaction in one call
+ * - `checkStatus()` - Get transaction status with action hints
+ *
+ * All complexity is hidden behind smart defaults.
+ *
+ * @example
+ * ```typescript
+ * const client = await ACTPClient.create({ mode: 'mock' });
+ *
+ * // Simple payment (all defaults)
+ * const result = await client.basic.pay({
+ *   to: '0xProvider123',
+ *   amount: '100',
+ * });
+ * console.log('Transaction ID:', result.txId);
+ * console.log('Amount:', result.amount); // "100.00 USDC"
+ *
+ * // Check status
+ * const status = await client.basic.checkStatus(result.txId);
+ * if (status.canAccept) {
+ *   console.log('Provider can accept this transaction');
+ * }
+ * ```
+ */
+class BasicAdapter extends BaseAdapter_1.BaseAdapter {
+    /**
+     * Creates a new BasicAdapter instance.
+     *
+     * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
+     * @param requesterAddress - The requester's Ethereum address
+     * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+     */
+    constructor(runtime, requesterAddress, easHelper) {
+        super(requesterAddress);
+        this.runtime = runtime;
+        this.easHelper = easHelper;
+    }
+    /**
+     * Create a payment transaction with smart defaults.
+     *
+     * This is the simplest way to create a transaction - just specify
+     * recipient and amount. All other parameters use sensible defaults.
+     *
+     * Smart defaults:
+     * - Requester: Inferred from constructor
+     * - Deadline: 24 hours from now
+     * - Dispute window: 2 days (172800 seconds)
+     *
+     * Validations performed:
+     * - Address format (0x-prefixed hex)
+     * - Amount format (positive number)
+     * - Deadline in future
+     * - Cannot pay yourself
+     *
+     * @param params - Payment parameters
+     * @returns User-friendly payment result
+     * @throws {ValidationError} If inputs are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.pay({
+     *   to: '0xProvider123',
+     *   amount: '100.50',
+     *   deadline: '+7d', // Optional: 7 days from now
+     * });
+     * ```
+     */
+    async pay(params) {
+        // Validate and parse inputs
+        const provider = this.validateAddress(params.to, 'to');
+        const amount = this.parseAmount(params.amount);
+        const currentTime = this.runtime.time.now();
+        const deadline = this.parseDeadline(params.deadline, currentTime);
+        // SECURITY FIX (L-1): Validate dispute window bounds
+        const disputeWindow = this.validateDisputeWindow(params.disputeWindow);
+        const requester = this.requesterAddress;
+        // Additional validations
+        if (requester.toLowerCase() === provider.toLowerCase()) {
+            throw new BaseAdapter_1.ValidationError('Cannot pay yourself (requester equals provider)');
+        }
+        if (deadline <= currentTime) {
+            throw new BaseAdapter_1.ValidationError('Deadline must be in the future');
+        }
+        // Create transaction
+        const txId = await this.runtime.createTransaction({
+            provider,
+            requester,
+            amount: amount.toString(),
+            deadline,
+            disputeWindow,
+        });
+        // Link escrow (auto-transitions to COMMITTED)
+        await this.runtime.linkEscrow(txId, amount.toString());
+        // Fetch transaction details for user-friendly response
+        const tx = await this.runtime.getTransaction(txId);
+        if (!tx) {
+            throw new Error(`Transaction ${txId} not found after creation`);
+        }
+        return {
+            txId,
+            provider,
+            requester,
+            amount: this.formatAmount(amount),
+            deadline: new Date(deadline * 1000).toISOString(),
+            state: tx.state,
+        };
+    }
+    /**
+     * Check payment status by transaction ID.
+     *
+     * Returns current state plus action hints (what can be done next).
+     *
+     * Action hints:
+     * - `canAccept`: Provider can accept (INITIATED state, before deadline)
+     * - `canComplete`: Provider can mark as delivered (COMMITTED state)
+     * - `canDispute`: Requester can dispute (DELIVERED state, within dispute window)
+     *
+     * @param txId - Transaction ID to check
+     * @returns Status with action hints
+     * @throws {Error} If transaction not found
+     *
+     * @example
+     * ```typescript
+     * const status = await adapter.checkStatus(txId);
+     * console.log('State:', status.state); // "COMMITTED"
+     * if (status.canComplete) {
+     *   // Provider can deliver now
+     * }
+     * ```
+     */
+    async checkStatus(txId) {
+        const tx = await this.runtime.getTransaction(txId);
+        if (!tx) {
+            throw new Error(`Transaction ${txId} not found`);
+        }
+        const now = this.runtime.time.now();
+        return {
+            state: tx.state,
+            canAccept: tx.state === 'INITIATED' && tx.deadline > now,
+            canComplete: tx.state === 'COMMITTED' || tx.state === 'IN_PROGRESS',
+            canDispute: tx.state === 'DELIVERED' && tx.completedAt !== null && tx.completedAt + tx.disputeWindow > now,
+        };
+    }
+}
+exports.BasicAdapter = BasicAdapter;
+//# sourceMappingURL=BasicAdapter.js.map

package/dist/adapters/BasicAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BasicAdapter.js","sourceRoot":"","sources":["../../src/adapters/BasicAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapters/BeginnerAdapter.d.ts

@@ -0,0 +1,152 @@
+/**
+ * BeginnerAdapter - 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.
+ *
+ * Key Features:
+ * - Smart defaults (24h deadline, 2-day dispute window)
+ * - Inferred requester (from constructor)
+ * - User-friendly input (strings, no BigInt)
+ * - User-friendly output (formatted amounts, ISO dates)
+ *
+ * @module adapters/BeginnerAdapter
+ */
+import { BaseAdapter } from './BaseAdapter';
+import { IACTPRuntime } from '../runtime/IACTPRuntime';
+import { EASHelper } from '../protocol/EASHelper';
+/**
+ * Parameters for creating a simple payment.
+ *
+ * This is the most beginner-friendly interface - minimal required fields.
+ */
+export interface BeginnerPayParams {
+    /** Recipient address (provider) */
+    to: string;
+    /** Amount in user-friendly format ("100", "100.50", "100 USDC", "$100") */
+    amount: string | number;
+    /** Optional: Deadline as relative time ("+24h") or Unix timestamp. Defaults to +24h */
+    deadline?: string | number;
+    /** Optional: Dispute window in seconds. Defaults to 172800 (2 days) */
+    disputeWindow?: number;
+}
+/**
+ * Result of creating a payment.
+ *
+ * Provides user-friendly formatted data (not raw protocol types).
+ */
+export interface BeginnerPayResult {
+    /** Transaction ID (bytes32 hex string) */
+    txId: string;
+    /** Provider address */
+    provider: string;
+    /** Requester address (caller) */
+    requester: string;
+    /** Amount in USDC (human-readable, e.g., "100.00 USDC") */
+    amount: string;
+    /** Deadline as ISO 8601 timestamp */
+    deadline: string;
+    /** Transaction state */
+    state: string;
+}
+/**
+ * BeginnerAdapter - High-level API for simple payment flows.
+ *
+ * This adapter provides the simplest possible interface:
+ * - `pay()` - Create and fund a transaction in one call
+ * - `checkStatus()` - Get transaction status with action hints
+ *
+ * All complexity is hidden behind smart defaults.
+ *
+ * @example
+ * ```typescript
+ * const client = await ACTPClient.create({ mode: 'mock' });
+ *
+ * // Simple payment (all defaults)
+ * const result = await client.beginner.pay({
+ *   to: '0xProvider123',
+ *   amount: '100',
+ * });
+ * console.log('Transaction ID:', result.txId);
+ * console.log('Amount:', result.amount); // "100.00 USDC"
+ *
+ * // Check status
+ * const status = await client.beginner.checkStatus(result.txId);
+ * if (status.canAccept) {
+ *   console.log('Provider can accept this transaction');
+ * }
+ * ```
+ */
+export declare class BeginnerAdapter extends BaseAdapter {
+    private runtime;
+    private easHelper?;
+    /**
+     * Creates a new BeginnerAdapter instance.
+     *
+     * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
+     * @param requesterAddress - The requester's Ethereum address
+     * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+     */
+    constructor(runtime: IACTPRuntime, requesterAddress: string, easHelper?: EASHelper | undefined);
+    /**
+     * Create a payment transaction with smart defaults.
+     *
+     * This is the simplest way to create a transaction - just specify
+     * recipient and amount. All other parameters use sensible defaults.
+     *
+     * Smart defaults:
+     * - Requester: Inferred from constructor
+     * - Deadline: 24 hours from now
+     * - Dispute window: 2 days (172800 seconds)
+     *
+     * Validations performed:
+     * - Address format (0x-prefixed hex)
+     * - Amount format (positive number)
+     * - Deadline in future
+     * - Cannot pay yourself
+     *
+     * @param params - Payment parameters
+     * @returns User-friendly payment result
+     * @throws {ValidationError} If inputs are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.pay({
+     *   to: '0xProvider123',
+     *   amount: '100.50',
+     *   deadline: '+7d', // Optional: 7 days from now
+     * });
+     * ```
+     */
+    pay(params: BeginnerPayParams): Promise<BeginnerPayResult>;
+    /**
+     * Check payment status by transaction ID.
+     *
+     * Returns current state plus action hints (what can be done next).
+     *
+     * Action hints:
+     * - `canAccept`: Provider can accept (INITIATED state, before deadline)
+     * - `canComplete`: Provider can mark as delivered (COMMITTED state)
+     * - `canDispute`: Requester can dispute (DELIVERED state, within dispute window)
+     *
+     * @param txId - Transaction ID to check
+     * @returns Status with action hints
+     * @throws {Error} If transaction not found
+     *
+     * @example
+     * ```typescript
+     * const status = await adapter.checkStatus(txId);
+     * console.log('State:', status.state); // "COMMITTED"
+     * if (status.canComplete) {
+     *   // Provider can deliver now
+     * }
+     * ```
+     */
+    checkStatus(txId: string): Promise<{
+        state: string;
+        canAccept: boolean;
+        canComplete: boolean;
+        canDispute: boolean;
+    }>;
+}
+//# sourceMappingURL=BeginnerAdapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"BeginnerAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/BeginnerAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,WAAW,EAAmD,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IAEX,2EAA2E;IAC3E,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IAExB,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAE3B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IAEb,uBAAuB;IACvB,QAAQ,EAAE,MAAM,CAAC;IAEjB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IAEf,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IAEjB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,eAAgB,SAAQ,WAAW;IAS5C,OAAO,CAAC,OAAO;IAEf,OAAO,CAAC,SAAS,CAAC;IAVpB;;;;;;OAMG;gBAEO,OAAO,EAAE,YAAY,EAC7B,gBAAgB,EAAE,MAAM,EAChB,SAAS,CAAC,uBAAW;IAK/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,GAAG,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAiDhE;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QACvC,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,OAAO,CAAC;QACnB,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC;CAgBH"}

package/dist/adapters/BeginnerAdapter.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * BeginnerAdapter - 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.
+ *
+ * Key Features:
+ * - Smart defaults (24h deadline, 2-day dispute window)
+ * - Inferred requester (from constructor)
+ * - User-friendly input (strings, no BigInt)
+ * - User-friendly output (formatted amounts, ISO dates)
+ *
+ * @module adapters/BeginnerAdapter
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BeginnerAdapter = void 0;
+const BaseAdapter_1 = require("./BaseAdapter");
+/**
+ * BeginnerAdapter - High-level API for simple payment flows.
+ *
+ * This adapter provides the simplest possible interface:
+ * - `pay()` - Create and fund a transaction in one call
+ * - `checkStatus()` - Get transaction status with action hints
+ *
+ * All complexity is hidden behind smart defaults.
+ *
+ * @example
+ * ```typescript
+ * const client = await ACTPClient.create({ mode: 'mock' });
+ *
+ * // Simple payment (all defaults)
+ * const result = await client.beginner.pay({
+ *   to: '0xProvider123',
+ *   amount: '100',
+ * });
+ * console.log('Transaction ID:', result.txId);
+ * console.log('Amount:', result.amount); // "100.00 USDC"
+ *
+ * // Check status
+ * const status = await client.beginner.checkStatus(result.txId);
+ * if (status.canAccept) {
+ *   console.log('Provider can accept this transaction');
+ * }
+ * ```
+ */
+class BeginnerAdapter extends BaseAdapter_1.BaseAdapter {
+    /**
+     * Creates a new BeginnerAdapter instance.
+     *
+     * @param runtime - ACTP runtime implementation (MockRuntime or BlockchainRuntime)
+     * @param requesterAddress - The requester's Ethereum address
+     * @param easHelper - Optional EAS helper for attestation verification (SECURITY FIX C-4)
+     */
+    constructor(runtime, requesterAddress, easHelper) {
+        super(requesterAddress);
+        this.runtime = runtime;
+        this.easHelper = easHelper;
+    }
+    /**
+     * Create a payment transaction with smart defaults.
+     *
+     * This is the simplest way to create a transaction - just specify
+     * recipient and amount. All other parameters use sensible defaults.
+     *
+     * Smart defaults:
+     * - Requester: Inferred from constructor
+     * - Deadline: 24 hours from now
+     * - Dispute window: 2 days (172800 seconds)
+     *
+     * Validations performed:
+     * - Address format (0x-prefixed hex)
+     * - Amount format (positive number)
+     * - Deadline in future
+     * - Cannot pay yourself
+     *
+     * @param params - Payment parameters
+     * @returns User-friendly payment result
+     * @throws {ValidationError} If inputs are invalid
+     *
+     * @example
+     * ```typescript
+     * const result = await adapter.pay({
+     *   to: '0xProvider123',
+     *   amount: '100.50',
+     *   deadline: '+7d', // Optional: 7 days from now
+     * });
+     * ```
+     */
+    async pay(params) {
+        // Validate and parse inputs
+        const provider = this.validateAddress(params.to, 'to');
+        const amount = this.parseAmount(params.amount);
+        const currentTime = this.runtime.time.now();
+        const deadline = this.parseDeadline(params.deadline, currentTime);
+        // SECURITY FIX (L-1): Validate dispute window bounds
+        const disputeWindow = this.validateDisputeWindow(params.disputeWindow);
+        const requester = this.requesterAddress;
+        // Additional validations
+        if (requester.toLowerCase() === provider.toLowerCase()) {
+            throw new BaseAdapter_1.ValidationError('Cannot pay yourself (requester equals provider)');
+        }
+        if (deadline <= currentTime) {
+            throw new BaseAdapter_1.ValidationError('Deadline must be in the future');
+        }
+        // Create transaction
+        const txId = await this.runtime.createTransaction({
+            provider,
+            requester,
+            amount: amount.toString(),
+            deadline,
+            disputeWindow,
+        });
+        // Link escrow (auto-transitions to COMMITTED)
+        await this.runtime.linkEscrow(txId, amount.toString());
+        // Fetch transaction details for user-friendly response
+        const tx = await this.runtime.getTransaction(txId);
+        if (!tx) {
+            throw new Error(`Transaction ${txId} not found after creation`);
+        }
+        return {
+            txId,
+            provider,
+            requester,
+            amount: this.formatAmount(amount),
+            deadline: new Date(deadline * 1000).toISOString(),
+            state: tx.state,
+        };
+    }
+    /**
+     * Check payment status by transaction ID.
+     *
+     * Returns current state plus action hints (what can be done next).
+     *
+     * Action hints:
+     * - `canAccept`: Provider can accept (INITIATED state, before deadline)
+     * - `canComplete`: Provider can mark as delivered (COMMITTED state)
+     * - `canDispute`: Requester can dispute (DELIVERED state, within dispute window)
+     *
+     * @param txId - Transaction ID to check
+     * @returns Status with action hints
+     * @throws {Error} If transaction not found
+     *
+     * @example
+     * ```typescript
+     * const status = await adapter.checkStatus(txId);
+     * console.log('State:', status.state); // "COMMITTED"
+     * if (status.canComplete) {
+     *   // Provider can deliver now
+     * }
+     * ```
+     */
+    async checkStatus(txId) {
+        const tx = await this.runtime.getTransaction(txId);
+        if (!tx) {
+            throw new Error(`Transaction ${txId} not found`);
+        }
+        const now = this.runtime.time.now();
+        return {
+            state: tx.state,
+            canAccept: tx.state === 'INITIATED' && tx.deadline > now,
+            canComplete: tx.state === 'COMMITTED' || tx.state === 'IN_PROGRESS',
+            canDispute: tx.state === 'DELIVERED' && tx.completedAt !== null && tx.completedAt + tx.disputeWindow > now,
+        };
+    }
+}
+exports.BeginnerAdapter = BeginnerAdapter;
+//# sourceMappingURL=BeginnerAdapter.js.map

package/dist/adapters/BeginnerAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BeginnerAdapter.js","sourceRoot":"","sources":["../../src/adapters/BeginnerAdapter.ts"],"names":[],"mappings":"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"}