@openserv-labs/client 2.0.2 → 2.1.1

package/dist/erc8004-api.d.ts

@@ -0,0 +1,318 @@
+import type { PlatformClient } from "./client";
+import type { Erc8004DeployRequest, Web3Wallet, ImportWeb3WalletRequest, CallableTrigger, PresignIpfsUrlResponse, SignFeedbackAuthResponse, WorkflowData } from "./types";
+/**
+ * API for ERC-8004 agent identity operations on the OpenServ platform.
+ *
+ * ERC-8004 is an on-chain agent identity standard. This API enables:
+ * - Deploying workspace agents to the blockchain as ERC-8004 tokens
+ * - Managing web3 wallets associated with workspaces
+ * - Presigning IPFS URLs for uploading agent registration files
+ * - Querying callable triggers for on-chain service registration
+ * - Signing feedback auth for reputation interactions
+ *
+ * @example
+ * ```typescript
+ * const client = new PlatformClient({ apiKey: 'your-key' });
+ *
+ * // Generate a web3 wallet for the workspace
+ * const wallet = await client.erc8004.generateWallet({ workflowId: 123 });
+ *
+ * // Get a presigned IPFS URL for uploading the agent card
+ * const { url } = await client.erc8004.presignIpfsUrl({ workflowId: 123 });
+ *
+ * // Deploy to ERC-8004
+ * await client.erc8004.deploy({
+ *   workflowId: 123,
+ *   erc8004AgentId: '8453:42',
+ *   stringifiedAgentCard: JSON.stringify(registrationFile),
+ *   walletAddress: '0x...',
+ *   network: 'base',
+ *   chainId: 8453,
+ * });
+ * ```
+ */
+export declare class Erc8004API {
+    private client;
+    constructor(client: PlatformClient);
+    /**
+     * Deploy a workspace agent to the ERC-8004 identity registry.
+     *
+     * This records the deployment details in the platform database. The actual
+     * on-chain registration should be performed separately using the agent0 SDK.
+     * Call this method both before and after blockchain registration to keep
+     * the platform in sync.
+     *
+     * If the deploy fails (e.g. insufficient ETH for gas), the error is
+     * enriched with the workspace wallet address and instructions for funding
+     * it so you can retry.
+     *
+     * @param params - Deployment parameters
+     * @param params.workflowId - The workflow (workspace) ID to deploy
+     * @param params.erc8004AgentId - Agent ID in format "chainId:tokenId"
+     * @param params.stringifiedAgentCard - JSON-stringified registration file
+     * @param params.latestDeploymentTransactionHash - Transaction hash from on-chain registration
+     * @param params.latestDeploymentTimestamp - Timestamp of the deployment
+     * @param params.walletAddress - Wallet address that performed the deployment
+     * @param params.network - Network name (e.g., "base")
+     * @param params.chainId - Chain ID (e.g., 8453 for Base mainnet)
+     * @param params.rpcUrl - RPC URL for the chain
+     * @param params.swap - If true, swap USDC in the wallet to ETH for gas before deploying (not yet implemented)
+     * @returns The updated workflow data
+     *
+     * @example
+     * ```typescript
+     * // Before blockchain registration (save initial state)
+     * await client.erc8004.deploy({
+     *   workflowId: 123,
+     *   erc8004AgentId: '',
+     *   stringifiedAgentCard: JSON.stringify(registrationFile),
+     *   walletAddress: '0x...',
+     *   network: 'base',
+     *   chainId: 8453,
+     *   rpcUrl: 'https://mainnet.base.org',
+     * });
+     *
+     * // ... perform on-chain registration ...
+     *
+     * // After blockchain registration (save final state with tx hash)
+     * await client.erc8004.deploy({
+     *   workflowId: 123,
+     *   erc8004AgentId: '8453:42',
+     *   stringifiedAgentCard: JSON.stringify(updatedRegistrationFile),
+     *   latestDeploymentTransactionHash: '0xabc...',
+     *   latestDeploymentTimestamp: new Date(),
+     *   walletAddress: '0x...',
+     *   network: 'base',
+     *   chainId: 8453,
+     *   rpcUrl: 'https://mainnet.base.org',
+     * });
+     * ```
+     */
+    deploy(params: Erc8004DeployRequest & {
+        workflowId: number;
+    }): Promise<WorkflowData>;
+    /**
+     * Enrich a deploy error with the workspace wallet address and funding
+     * instructions. Called automatically when deploy() fails.
+     */
+    private enrichDeployError;
+    /**
+     * Register (or re-deploy) a workspace agent on-chain as an ERC-8004 identity.
+     *
+     * This is a high-level method that orchestrates the entire deployment:
+     * 1. Reads workspace wallet and callable triggers
+     * 2. Builds the ERC-8004 agent card JSON
+     * 3. Uploads the agent card to IPFS via a presigned Pinata URL
+     * 4. Registers on-chain (first deploy) or updates the URI (re-deploy)
+     * 5. Saves the deployment state to the platform
+     *
+     * @param params.workflowId - The workflow (workspace) ID
+     * @param params.privateKey - Funded private key for on-chain transactions (must have ETH for gas)
+     * @param params.chainId - Chain ID (default: 8453 for Base mainnet)
+     * @param params.rpcUrl - RPC URL (default: "https://mainnet.base.org")
+     * @param params.name - Agent name override (falls back to "ERC-8004 Agent")
+     * @param params.description - Agent description override
+     * @returns Deployment result with agentId, IPFS CID, transaction hash, and URLs
+     *
+     * @example
+     * ```typescript
+     * const result = await client.erc8004.registerOnChain({
+     *   workflowId: 123,
+     *   privateKey: '0x...',
+     *   name: 'My AI Agent',
+     *   description: 'An agent that does amazing things',
+     * });
+     * console.log(result.agentId);         // "8453:42"
+     * console.log(result.txHash);           // "0xabc..."
+     * console.log(result.ipfsCid);          // "bafkrei..."
+     * console.log(result.blockExplorerUrl); // "https://basescan.org/tx/0xabc..."
+     * console.log(result.scanUrl);          // "https://www.8004scan.io/agents/base/42"
+     * ```
+     */
+    registerOnChain(params: {
+        workflowId: number;
+        privateKey: string;
+        chainId?: number;
+        rpcUrl?: string;
+        name?: string;
+        description?: string;
+    }): Promise<RegisterOnChainResult>;
+    /**
+     * Upload a JSON string to IPFS using a presigned Pinata URL.
+     */
+    private uploadToIpfs;
+    /**
+     * Extract the agent token ID from a registration transaction receipt.
+     * Looks for the Registered event first, then falls back to Transfer event.
+     */
+    private extractAgentIdFromReceipt;
+    /**
+     * Get a presigned IPFS URL for uploading an agent registration file.
+     *
+     * The returned URL is a signed Pinata upload URL that expires in 60 seconds.
+     * Use it to upload the agent's registration file (agent card) to IPFS before
+     * on-chain registration.
+     *
+     * @param params - Parameters
+     * @param params.workflowId - The workflow (workspace) ID
+     * @returns Object containing the presigned IPFS upload URL
+     *
+     * @example
+     * ```typescript
+     * const { url } = await client.erc8004.presignIpfsUrl({ workflowId: 123 });
+     * // Use the URL to upload agent card to IPFS within 60 seconds
+     * ```
+     */
+    presignIpfsUrl(params: {
+        workflowId: number;
+    }): Promise<PresignIpfsUrlResponse>;
+    /**
+     * Get the web3 wallet associated with a workspace.
+     *
+     * @param params - Parameters
+     * @param params.workflowId - The workflow (workspace) ID
+     * @returns The web3 wallet details
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.erc8004.getWallet({ workflowId: 123 });
+     * console.log(wallet.address, wallet.deployed, wallet.erc8004AgentId);
+     * ```
+     */
+    getWallet(params: {
+        workflowId: number;
+    }): Promise<Web3Wallet>;
+    /**
+     * Generate a new web3 wallet for a workspace.
+     *
+     * Creates a fresh wallet with a server-generated private key. The wallet
+     * is stored securely on the platform and used for ERC-8004 operations.
+     * A workspace can only have one web3 wallet.
+     *
+     * @param params - Parameters
+     * @param params.workflowId - The workflow (workspace) ID
+     * @returns The generated web3 wallet
+     * @throws Error if the workspace already has a web3 wallet
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.erc8004.generateWallet({ workflowId: 123 });
+     * console.log('Wallet address:', wallet.address);
+     * ```
+     */
+    generateWallet(params: {
+        workflowId: number;
+    }): Promise<Web3Wallet>;
+    /**
+     * Import an existing web3 wallet into a workspace.
+     *
+     * Use this to associate a pre-existing wallet (e.g., one that already has
+     * an ERC-8004 registration) with a workspace.
+     * A workspace can only have one web3 wallet.
+     *
+     * @param params - Import parameters
+     * @param params.workflowId - The workflow (workspace) ID
+     * @param params.address - Wallet address
+     * @param params.network - Network name (e.g., "base")
+     * @param params.chainId - Chain ID (e.g., 8453)
+     * @param params.privateKey - Wallet private key
+     * @returns The imported web3 wallet
+     * @throws Error if the workspace already has a web3 wallet
+     *
+     * @example
+     * ```typescript
+     * const wallet = await client.erc8004.importWallet({
+     *   workflowId: 123,
+     *   address: '0x...',
+     *   network: 'base',
+     *   chainId: 8453,
+     *   privateKey: '0x...',
+     * });
+     * ```
+     */
+    importWallet(params: ImportWeb3WalletRequest & {
+        workflowId: number;
+    }): Promise<Web3Wallet>;
+    /**
+     * Delete the web3 wallet associated with a workspace.
+     *
+     * This removes the wallet record from the platform. Note that the on-chain
+     * ERC-8004 registration is not affected -- this only removes the platform's
+     * association.
+     *
+     * @param params - Parameters
+     * @param params.workflowId - The workflow (workspace) ID
+     *
+     * @example
+     * ```typescript
+     * await client.erc8004.deleteWallet({ workflowId: 123 });
+     * ```
+     */
+    deleteWallet(params: {
+        workflowId: number;
+    }): Promise<void>;
+    /**
+     * Sign a feedback auth message for a buyer address.
+     *
+     * This is used for the ERC-8004 reputation system. The workspace's web3 wallet
+     * signs an auth message that allows a buyer to submit feedback/reputation
+     * for the agent on-chain.
+     *
+     * @param params - Parameters
+     * @param params.workflowId - The workflow (workspace) ID
+     * @param params.buyerAddress - The buyer's wallet address to authorize
+     * @returns Object containing the signed feedback auth
+     *
+     * @example
+     * ```typescript
+     * const { signature } = await client.erc8004.signFeedbackAuth({
+     *   workflowId: 123,
+     *   buyerAddress: '0xBuyer...',
+     * });
+     * ```
+     */
+    signFeedbackAuth(params: {
+        workflowId: number;
+        buyerAddress: string;
+    }): Promise<SignFeedbackAuthResponse>;
+    /**
+     * Get callable triggers for a workspace.
+     *
+     * Returns the list of triggers that can be called externally, along with
+     * their input schemas and endpoint URLs. This is used during ERC-8004
+     * deployment to register the agent's available services on-chain.
+     *
+     * @param params - Parameters
+     * @param params.workflowId - The workflow (workspace) ID
+     * @returns Array of callable triggers with their schemas and endpoints
+     *
+     * @example
+     * ```typescript
+     * const triggers = await client.erc8004.getCallableTriggers({ workflowId: 123 });
+     * for (const trigger of triggers) {
+     *   console.log(trigger.name, trigger.webEndpoint);
+     * }
+     * ```
+     */
+    getCallableTriggers(params: {
+        workflowId: number;
+    }): Promise<CallableTrigger[]>;
+}
+/**
+ * Result of a successful on-chain ERC-8004 registration.
+ */
+export interface RegisterOnChainResult {
+    /** ERC-8004 agent ID in format "chainId:tokenId" (e.g., "8453:42") */
+    agentId: string;
+    /** IPFS CID of the uploaded agent card */
+    ipfsCid: string;
+    /** Transaction hash of the final on-chain transaction */
+    txHash: string;
+    /** URL to view the agent card on IPFS */
+    agentCardUrl: string;
+    /** URL to view the transaction on the block explorer */
+    blockExplorerUrl: string;
+    /** URL to view the agent on 8004scan.io (e.g., "https://www.8004scan.io/agents/base/42") */
+    scanUrl: string;
+}
+//# sourceMappingURL=erc8004-api.d.ts.map

package/dist/erc8004-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc8004-api.d.ts","sourceRoot":"","sources":["../src/erc8004-api.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,uBAAuB,EACvB,eAAe,EACf,sBAAsB,EACtB,wBAAwB,EACxB,YAAY,EACb,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,UAAU;IACT,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAM1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACG,MAAM,CACV,MAAM,EAAE,oBAAoB,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,GACpD,OAAO,CAAC,YAAY,CAAC;IAsBxB;;;OAGG;YACW,iBAAiB;IAiC/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,eAAe,CAAC,MAAM,EAAE;QAC5B,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IA+LlC;;OAEG;YACW,YAAY;IAyB1B;;;OAGG;IACH,OAAO,CAAC,yBAAyB;IA8CjC;;;;;;;;;;;;;;;;OAgBG;IACG,cAAc,CAAC,MAAM,EAAE;QAC3B,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAUnC;;;;;;;;;;;;OAYG;IACG,SAAS,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAIpE;;;;;;;;;;;;;;;;;OAiBG;IACG,cAAc,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,CAAC;IAMzE;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACG,YAAY,CAChB,MAAM,EAAE,uBAAuB,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,GACvD,OAAO,CAAC,UAAU,CAAC;IAQtB;;;;;;;;;;;;;;OAcG;IACG,YAAY,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE;;;;;;;;;;;;;;;;;;;OAmBG;IACG,gBAAgB,CAAC,MAAM,EAAE;QAC7B,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;KACtB,GAAG,OAAO,CAAC,wBAAwB,CAAC;IAWrC;;;;;;;;;;;;;;;;;;OAkBG;IACG,mBAAmB,CAAC,MAAM,EAAE;QAChC,UAAU,EAAE,MAAM,CAAC;KACpB,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;CAK/B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,gBAAgB,EAAE,MAAM,CAAC;IACzB,4FAA4F;IAC5F,OAAO,EAAE,MAAM,CAAC;CACjB"}