@agirails/sdk 2.0.1-beta → 2.0.2

package/dist/level1/types/Job.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Job - Represents a work request from requester to provider
+ *
+ * This is the core data structure passed to service handlers
+ * in the Basic and Standard APIs.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Job interface - work request data
+ *
+ * @example
+ * ```typescript
+ * const job: Job = {
+ *   id: '0x1234...abcd',
+ *   service: 'translation',
+ *   input: { text: 'Hello', from: 'en', to: 'de' },
+ *   budget: 10,
+ *   deadline: new Date('2025-12-14T12:00:00Z'),
+ *   requester: '0xRequester...',
+ *   metadata: { priority: 'high' }
+ * }
+ * ```
+ */
+export interface Job {
+    /**
+     * Unique job identifier (transaction ID from ACTP protocol)
+     */
+    id: string;
+    /**
+     * Service type being requested (e.g., 'translation', 'echo', 'image-gen')
+     */
+    service: string;
+    /**
+     * Input data for the service (service-specific)
+     *
+     * This is the data the requester wants processed.
+     * Structure depends on the service type.
+     */
+    input: any;
+    /**
+     * Budget in USDC (decimal format, e.g., 10 = $10.00)
+     *
+     * This is the maximum amount the requester is willing to pay.
+     */
+    budget: number;
+    /**
+     * Deadline by which work must be completed
+     */
+    deadline: Date;
+    /**
+     * Ethereum address of the requester
+     */
+    requester: string;
+    /**
+     * Additional metadata (optional, service-specific)
+     */
+    metadata: Record<string, any>;
+}
+/**
+ * Job handler function type
+ *
+ * This is the function signature providers must implement.
+ *
+ * @param job - The job to process
+ * @param context - Job execution context
+ * @returns Promise resolving to job result (service-specific)
+ *
+ * @example
+ * ```typescript
+ * const handler: JobHandler = async (job, ctx) => {
+ *   ctx.progress(50, 'Processing...');
+ *   const result = await doWork(job.input);
+ *   ctx.progress(100, 'Done!');
+ *   return result;
+ * };
+ * ```
+ */
+export type JobHandler = (job: Job, context: JobContext) => Promise<any>;
+/**
+ * JobContext - Execution context passed to job handlers
+ *
+ * Provides utilities for progress reporting, logging, state management,
+ * and cancellation handling.
+ */
+export interface JobContext {
+    /**
+     * Reference to the Agent instance processing this job
+     */
+    agent: any;
+    /**
+     * Report job progress
+     *
+     * @param percent - Progress percentage (0-100)
+     * @param message - Optional progress message
+     *
+     * @example
+     * ```typescript
+     * ctx.progress(25, 'Downloaded input file');
+     * ctx.progress(50, 'Processing data');
+     * ctx.progress(100, 'Complete!');
+     * ```
+     */
+    progress(percent: number, message?: string): void;
+    /**
+     * Logging utilities
+     */
+    log: {
+        debug(message: string, meta?: any): void;
+        info(message: string, meta?: any): void;
+        warn(message: string, meta?: any): void;
+        error(message: string, meta?: any): void;
+    };
+    /**
+     * Job-scoped state storage
+     *
+     * Allows handlers to store intermediate state that persists
+     * across async operations (e.g., for resumable jobs).
+     *
+     * @example
+     * ```typescript
+     * // Store checkpoint
+     * ctx.state.set('lastProcessedIndex', 42);
+     *
+     * // Retrieve checkpoint
+     * const lastIndex = ctx.state.get<number>('lastProcessedIndex') || 0;
+     * ```
+     */
+    state: {
+        get<T>(key: string): T | undefined;
+        set<T>(key: string, value: T): void;
+    };
+    /**
+     * Whether the job has been cancelled
+     *
+     * Handlers should check this periodically for long-running jobs
+     * and exit gracefully if true.
+     *
+     * @example
+     * ```typescript
+     * for (let i = 0; i < items.length; i++) {
+     *   if (ctx.cancelled) {
+     *     throw new Error('Job cancelled by requester');
+     *   }
+     *   await processItem(items[i]);
+     * }
+     * ```
+     */
+    cancelled: boolean;
+    /**
+     * Register cancellation handler
+     *
+     * Called when the job is cancelled, allowing cleanup.
+     *
+     * @example
+     * ```typescript
+     * const stream = openFileStream();
+     * ctx.onCancel(() => {
+     *   stream.close();
+     *   console.log('Cleaned up resources');
+     * });
+     * ```
+     */
+    onCancel(handler: () => void): void;
+}
+//# sourceMappingURL=Job.d.ts.map

package/dist/level1/types/Job.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Job.d.ts","sourceRoot":"","sources":["../../../src/level1/types/Job.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,GAAG;IAClB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;;;;OAKG;IACH,KAAK,EAAE,GAAG,CAAC;IAEX;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,QAAQ,EAAE,IAAI,CAAC;IAEf;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,UAAU,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB;;OAEG;IACH,KAAK,EAAE,GAAG,CAAC;IAEX;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAElD;;OAEG;IACH,GAAG,EAAE;QACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;QACzC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;QACxC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;KAC1C,CAAC;IAEF;;;;;;;;;;;;;;OAcG;IACH,KAAK,EAAE;QACL,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAC;QACnC,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;KACrC,CAAC;IAEF;;;;;;;;;;;;;;;OAeG;IACH,SAAS,EAAE,OAAO,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;CACrC"}

package/dist/level1/types/Job.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Job - Represents a work request from requester to provider
+ *
+ * This is the core data structure passed to service handlers
+ * in the Basic and Standard APIs.
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Job.js.map

package/dist/level1/types/Job.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Job.js","sourceRoot":"","sources":["../../../src/level1/types/Job.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG"}

package/dist/level1/types/Options.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Options for Basic and Standard APIs
+ *
+ * @packageDocumentation
+ */
+import { Job } from './Job';
+/**
+ * Wallet configuration options
+ */
+export type WalletOption = 'auto' | 'connect' | string | {
+    privateKey: string;
+};
+/**
+ * Network options
+ */
+export type NetworkOption = 'mock' | 'testnet' | 'mainnet';
+/**
+ * Options for provide() function (Basic API)
+ */
+export interface ProvideOptions {
+    /**
+     * Wallet configuration
+     *
+     * - 'auto': SDK generates and manages a wallet automatically
+     * - 'connect': Open browser wallet connection (MetaMask, etc.) - FUTURE
+     * - string: Private key (0x-prefixed hex)
+     * - object: { privateKey: string }
+     *
+     * @default 'auto'
+     */
+    wallet?: WalletOption;
+    /**
+     * Job filtering criteria
+     *
+     * Only accept jobs matching these filters.
+     */
+    filter?: {
+        /**
+         * Minimum budget in USDC
+         *
+         * @example
+         * filter: { minBudget: 5 } // Only accept jobs with budget >= $5
+         */
+        minBudget?: number;
+        /**
+         * Maximum budget in USDC
+         *
+         * @example
+         * filter: { maxBudget: 100 } // Only accept jobs with budget <= $100
+         */
+        maxBudget?: number;
+    };
+    /**
+     * Auto-accept policy
+     *
+     * - true: Automatically accept all jobs matching filter
+     * - false: Require manual acceptance
+     * - function: Custom logic to decide whether to accept
+     *
+     * @default true
+     *
+     * @example
+     * ```typescript
+     * // Auto-accept if budget >= 10
+     * autoAccept: (job) => job.budget >= 10
+     *
+     * // Auto-accept high-priority jobs
+     * autoAccept: (job) => job.metadata?.priority === 'high'
+     * ```
+     */
+    autoAccept?: boolean | ((job: Job) => boolean | Promise<boolean>);
+    /**
+     * Network to operate on
+     *
+     * @default 'mock'
+     */
+    network?: NetworkOption;
+    /**
+     * RPC URL for blockchain connection (required for testnet/mainnet)
+     *
+     * If not provided, defaults to public RPC from network config:
+     * - testnet: https://sepolia.base.org
+     * - mainnet: https://mainnet.base.org
+     *
+     * For production, consider using a dedicated RPC provider (Alchemy, Infura, etc.)
+     * for better reliability and rate limits.
+     *
+     * @example
+     * rpcUrl: 'https://base-sepolia.g.alchemy.com/v2/YOUR_API_KEY'
+     */
+    rpcUrl?: string;
+    /**
+     * State directory for mock mode
+     *
+     * Where to store mock state file.
+     * Only used when network is 'mock'.
+     *
+     * @default process.cwd()
+     */
+    stateDirectory?: string;
+}
+/**
+ * Request status updates
+ */
+export interface RequestStatus {
+    /**
+     * Current state of the request
+     */
+    state: 'initiated' | 'quoted' | 'committed' | 'in_progress' | 'delivered' | 'settled' | 'disputed' | 'cancelled';
+    /**
+     * Progress percentage (0-100) if provider is reporting progress
+     */
+    progress?: number;
+    /**
+     * Progress message if available
+     */
+    message?: string;
+    /**
+     * Estimated time to completion (seconds)
+     */
+    eta?: number;
+}
+/**
+ * Options for request() function (Basic API)
+ */
+export interface RequestOptions {
+    /**
+     * Input data to send to the service
+     */
+    input: any;
+    /**
+     * Budget in USDC (decimal format)
+     *
+     * @example
+     * budget: 10 // $10.00
+     */
+    budget: number;
+    /**
+     * Wallet configuration (same as ProvideOptions)
+     *
+     * @default 'auto'
+     */
+    wallet?: WalletOption;
+    /**
+     * Network to operate on
+     *
+     * @default 'mock'
+     */
+    network?: NetworkOption;
+    /**
+     * Timeout in milliseconds
+     *
+     * @default 300000 (5 minutes)
+     */
+    timeout?: number;
+    /**
+     * Deadline for job completion
+     *
+     * Can be a timestamp (seconds) or Date object.
+     * If not specified, defaults to now + timeout.
+     *
+     * @example
+     * deadline: Math.floor(Date.now() / 1000) + 3600 // 1 hour from now
+     * deadline: new Date('2025-12-14T12:00:00Z')
+     */
+    deadline?: number | Date;
+    /**
+     * Provider selection strategy
+     *
+     * - string: Specific provider address
+     * - 'any': First available provider
+     * - 'best': Provider with highest reputation
+     * - 'cheapest': Provider with lowest price
+     *
+     * @default 'any'
+     */
+    provider?: string | 'any' | 'best' | 'cheapest';
+    /**
+     * Progress callback
+     *
+     * Called when provider reports progress updates.
+     *
+     * @example
+     * ```typescript
+     * onProgress: (status) => {
+     *   console.log(`${status.state}: ${status.progress}% - ${status.message}`);
+     * }
+     * ```
+     */
+    onProgress?: (status: RequestStatus) => void;
+    /**
+     * State directory for mock mode
+     *
+     * @default process.cwd()
+     */
+    stateDirectory?: string;
+    /**
+     * RPC URL for blockchain connection (required for testnet/mainnet)
+     *
+     * If not provided, defaults to public RPC from network config:
+     * - testnet: https://sepolia.base.org
+     * - mainnet: https://mainnet.base.org
+     *
+     * For production, consider using a dedicated RPC provider (Alchemy, Infura, etc.)
+     * for better reliability and rate limits.
+     *
+     * @example
+     * rpcUrl: 'https://base-sepolia.g.alchemy.com/v2/YOUR_API_KEY'
+     */
+    rpcUrl?: string;
+    /**
+     * Dispute window duration in seconds
+     *
+     * Time after delivery during which requester can dispute.
+     *
+     * @default 172800 (2 days)
+     */
+    disputeWindow?: number;
+}
+/**
+ * Result of request() function
+ */
+export interface RequestResult {
+    /**
+     * The result returned by the provider's handler
+     */
+    result: any;
+    /**
+     * Transaction metadata
+     */
+    transaction: {
+        /**
+         * Transaction ID (ACTP protocol)
+         */
+        id: string;
+        /**
+         * Provider address
+         */
+        provider: string;
+        /**
+         * Amount paid (USDC)
+         */
+        amount: number;
+        /**
+         * Platform fee (USDC)
+         */
+        fee: number;
+        /**
+         * Job duration (milliseconds)
+         */
+        duration: number;
+        /**
+         * Delivery proof hash
+         */
+        proof: string;
+    };
+}
+//# sourceMappingURL=Options.d.ts.map

package/dist/level1/types/Options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Options.d.ts","sourceRoot":"","sources":["../../../src/level1/types/Options.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAc,GAAG,EAAE,MAAM,OAAO,CAAC;AAExC;;GAEG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,SAAS,GACT,MAAM,GACN;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3B;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;;OAIG;IACH,MAAM,CAAC,EAAE;QACP;;;;;WAKG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;QAEnB;;;;;WAKG;QACH,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;IAEF;;;;;;;;;;;;;;;;;OAiBG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAElE;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,KAAK,EAAE,WAAW,GAAG,QAAQ,GAAG,WAAW,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,GAAG,UAAU,GAAG,WAAW,CAAC;IAEjH;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,KAAK,EAAE,GAAG,CAAC;IAEX;;;;;OAKG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;;OAIG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,CAAC;IAEhD;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IAE7C;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,MAAM,EAAE,GAAG,CAAC;IAEZ;;OAEG;IACH,WAAW,EAAE;QACX;;WAEG;QACH,EAAE,EAAE,MAAM,CAAC;QAEX;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;WAEG;QACH,MAAM,EAAE,MAAM,CAAC;QAEf;;WAEG;QACH,GAAG,EAAE,MAAM,CAAC;QAEZ;;WAEG;QACH,QAAQ,EAAE,MAAM,CAAC;QAEjB;;WAEG;QACH,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH"}

package/dist/level1/types/Options.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Options for Basic and Standard APIs
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=Options.js.map

package/dist/level1/types/Options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Options.js","sourceRoot":"","sources":["../../../src/level1/types/Options.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}

package/dist/level1/types/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Standard API Types - Job, Options, and related interfaces
+ *
+ * @packageDocumentation
+ */
+export { Job, JobHandler, JobContext } from './Job';
+export { ProvideOptions, RequestOptions, RequestResult, RequestStatus, WalletOption, NetworkOption } from './Options';
+//# sourceMappingURL=index.d.ts.map

package/dist/level1/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/level1/types/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC"}

package/dist/level1/types/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Standard API Types - Job, Options, and related interfaces
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=index.js.map

package/dist/level1/types/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/level1/types/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG"}