@intentfi/agent-sdk 0.1.0

package/dist/client.js

@@ -0,0 +1,322 @@
+const MCP_PROTOCOL_VERSION = "2025-11-25";
+export class IntentFiClient {
+    baseUrl;
+    apiKey;
+    transport;
+    fetchImpl;
+    mcpSessionId;
+    constructor(options = {}) {
+        this.baseUrl = (options.baseUrl ?? process.env.INTENTFI_BASE_URL ?? "https://agentic.intentfi.io").replace(/\/+$/, "");
+        this.apiKey = options.apiKey ?? process.env.INTENTFI_API_KEY;
+        this.transport = resolveTransportMode(options.transport ?? process.env.INTENTFI_TRANSPORT);
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async requestSiweChallenge(args) {
+        const response = await this.fetchJson("/agent/v1/auth/siwe/challenge", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                address: args.address,
+                walletType: args.walletType ?? "eoa",
+                chainId: args.chainId ?? 8453,
+            }),
+        });
+        return response;
+    }
+    async mintApiKeyWithSiwe(args) {
+        return await this.fetchJson("/agent/v1/auth/siwe/mint-key", {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(args),
+        });
+    }
+    async createWorkflow(args) {
+        this.assertApiKey("createWorkflow");
+        if (this.transport === "mcp") {
+            return await this.mcpToolCall("intentfi.create_workflow", args);
+        }
+        return await this.createWorkflowRest(args);
+    }
+    async getWorkflow(args) {
+        this.assertApiKey("getWorkflow");
+        if (this.transport === "mcp") {
+            const result = await this.mcpToolCall("intentfi.get_workflow", args, { stream: (args.waitMs ?? 0) > 0 });
+            const workflow = (result.workflow ??
+                result);
+            const waitKind = result.wait?.kind;
+            const retryAfterMs = toOptionalRetryAfterMs(result.wait?.retryAfterMs);
+            return {
+                workflow,
+                status: waitKind === "timeout" ? 202 : 200,
+                ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+            };
+        }
+        return await this.getWorkflowRest(args);
+    }
+    async prepareActive(args) {
+        this.assertApiKey("prepareActive");
+        if (this.transport === "mcp") {
+            const result = await this.mcpToolCall("intentfi.prepare_active", args, { stream: (args.waitMs ?? 0) > 0 });
+            return {
+                result,
+                status: result.kind === "pending" ? 202 : 200,
+            };
+        }
+        return await this.prepareActiveRest(args);
+    }
+    async getActiveSubmissionContext(args) {
+        this.assertApiKey("getActiveSubmissionContext");
+        if (this.transport === "mcp") {
+            return await this.mcpToolCall("intentfi.get_active_submission_context", args);
+        }
+        return await this.fetchJson(`/agent/v1/workflows/${args.workflowId}/active-submission-context`, {
+            headers: this.withApiKey(),
+        });
+    }
+    async submitActiveTransactions(args) {
+        this.assertApiKey("submitActiveTransactions");
+        if (this.transport === "mcp") {
+            const result = await this.mcpToolCall("intentfi.submit_active_transactions", args, { stream: (args.waitMs ?? 0) > 0 });
+            const waitKind = result.wait?.kind;
+            return {
+                result,
+                status: waitKind === "timeout" ? 202 : 200,
+            };
+        }
+        return await this.submitActiveTransactionsRest(args);
+    }
+    async submitActiveSendCalls(args) {
+        this.assertApiKey("submitActiveSendCalls");
+        if (this.transport === "mcp") {
+            const result = await this.mcpToolCall("intentfi.submit_active_sendcalls", args, { stream: (args.waitMs ?? 0) > 0 });
+            const waitKind = result.wait?.kind;
+            return {
+                result,
+                status: waitKind === "timeout" ? 202 : 200,
+            };
+        }
+        return await this.submitActiveSendCallsRest(args);
+    }
+    async createWorkflowRest(args) {
+        return await this.fetchJson("/agent/v1/workflows", {
+            method: "POST",
+            headers: this.withApiKey({
+                "content-type": "application/json",
+            }),
+            body: JSON.stringify(args),
+        });
+    }
+    async getWorkflowRest(args) {
+        const query = args.waitMs !== undefined ? `?waitMs=${args.waitMs}` : "";
+        const response = await this.fetchEnvelope(`/agent/v1/workflows/${args.workflowId}${query}`, {
+            headers: this.withApiKey(),
+        });
+        return {
+            workflow: response.data,
+            status: response.status,
+            ...(parseRetryAfterHeader(response.headers.get("retry-after")) !== undefined
+                ? { retryAfterMs: parseRetryAfterHeader(response.headers.get("retry-after")) }
+                : {}),
+        };
+    }
+    async prepareActiveRest(args) {
+        const response = await this.fetchEnvelope(`/agent/v1/workflows/${args.workflowId}/prepare`, {
+            method: "POST",
+            headers: this.withApiKey({ "content-type": "application/json" }),
+            body: JSON.stringify({
+                requestId: args.requestId,
+                ...(args.waitMs !== undefined ? { waitMs: args.waitMs } : {}),
+            }),
+        });
+        return { result: response.data, status: response.status };
+    }
+    async submitActiveTransactionsRest(args) {
+        const response = await this.fetchEnvelope(`/agent/v1/workflows/${args.workflowId}/submit-transactions`, {
+            method: "POST",
+            headers: this.withApiKey({ "content-type": "application/json" }),
+            body: JSON.stringify(args),
+        });
+        return { result: response.data, status: response.status };
+    }
+    async submitActiveSendCallsRest(args) {
+        const response = await this.fetchEnvelope(`/agent/v1/workflows/${args.workflowId}/submit-sendcalls`, {
+            method: "POST",
+            headers: this.withApiKey({ "content-type": "application/json" }),
+            body: JSON.stringify(args),
+        });
+        return { result: response.data, status: response.status };
+    }
+    async mcpInitialize() {
+        const response = await this.fetchImpl(`${this.baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: 1,
+                method: "initialize",
+                params: {},
+            }),
+        });
+        const body = (await response.json());
+        if (!response.ok || !body.result?.protocolVersion) {
+            throw new Error("MCP initialize failed");
+        }
+        const sessionId = response.headers.get("MCP-Session-Id");
+        if (!sessionId) {
+            throw new Error("MCP initialize did not return MCP-Session-Id");
+        }
+        this.mcpSessionId = sessionId;
+        const notification = await this.fetchImpl(`${this.baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+                "MCP-Session-Id": this.mcpSessionId,
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                method: "notifications/initialized",
+            }),
+        });
+        if (notification.status !== 202) {
+            throw new Error(`MCP initialized notification failed (${notification.status})`);
+        }
+    }
+    async mcpToolCall(name, args, options, attempt = 0) {
+        if (!this.mcpSessionId) {
+            await this.mcpInitialize();
+        }
+        const response = await this.fetchImpl(`${this.baseUrl}/mcp`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                accept: options?.stream ? "application/json, text/event-stream" : "application/json",
+                "MCP-Protocol-Version": MCP_PROTOCOL_VERSION,
+                "MCP-Session-Id": String(this.mcpSessionId),
+                ...this.withApiKey(),
+            },
+            body: JSON.stringify({
+                jsonrpc: "2.0",
+                id: Date.now(),
+                method: "tools/call",
+                params: {
+                    name,
+                    arguments: args,
+                },
+            }),
+        });
+        const returnedSessionId = response.headers.get("MCP-Session-Id");
+        if (returnedSessionId) {
+            this.mcpSessionId = returnedSessionId;
+        }
+        const contentType = (response.headers.get("content-type") ?? "").toLowerCase();
+        if (contentType.includes("text/event-stream")) {
+            const text = await response.text();
+            const messages = text
+                .split("\n\n")
+                .map((chunk) => chunk.trim())
+                .filter((chunk) => chunk.startsWith("data:"))
+                .map((chunk) => chunk.slice(5).trim())
+                .map((chunk) => JSON.parse(chunk));
+            const final = messages.reverse().find((entry) => entry.result !== undefined || entry.error !== undefined);
+            if (!final) {
+                throw new Error("MCP stream response did not contain a final message");
+            }
+            if (final.error) {
+                if (final.error.data?.code === "MCP_SESSION_REQUIRED" && attempt === 0) {
+                    await this.mcpInitialize();
+                    return await this.mcpToolCall(name, args, options, attempt + 1);
+                }
+                throw createClientError(final.error.message ?? "MCP tool call failed", final.error.data?.code, response.status);
+            }
+            return final.result;
+        }
+        const text = await response.text();
+        let body;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            throw new Error(`MCP tool call failed (${response.status})`);
+        }
+        if (body.error?.data?.code === "MCP_SESSION_REQUIRED" && attempt === 0) {
+            await this.mcpInitialize();
+            return await this.mcpToolCall(name, args, options, attempt + 1);
+        }
+        if (!response.ok || body.error) {
+            throw createClientError(body.error?.message ?? `MCP tool call failed (${response.status})`, body.error?.data?.code, response.status);
+        }
+        return body.result;
+    }
+    withApiKey(headers = {}) {
+        if (!this.apiKey) {
+            return headers;
+        }
+        return {
+            ...headers,
+            "x-api-key": this.apiKey,
+        };
+    }
+    assertApiKey(operation) {
+        if (!this.apiKey) {
+            throw new Error(`INTENTFI_API_KEY is required for ${operation}. Set apiKey in IntentFiClient options or INTENTFI_API_KEY in the environment.`);
+        }
+    }
+    async fetchJson(path, init) {
+        const result = await this.fetchEnvelope(path, init);
+        return result.data;
+    }
+    async fetchEnvelope(path, init) {
+        const response = await this.fetchImpl(`${this.baseUrl}${path}`, init);
+        const body = (await response.json());
+        if (!response.ok || body.ok === false) {
+            const errorCode = body.ok === false ? body.error.code : "HTTP_ERROR";
+            const errorMessage = body.ok === false ? body.error.message : `HTTP ${response.status}`;
+            throw createClientError(`${errorCode}: ${errorMessage}`, errorCode, response.status);
+        }
+        return {
+            data: body.data,
+            status: response.status,
+            headers: response.headers,
+        };
+    }
+}
+function createClientError(message, code, status) {
+    const error = new Error(message);
+    if (code) {
+        error.code = code;
+    }
+    if (status !== undefined) {
+        error.status = status;
+    }
+    return error;
+}
+function parseRetryAfterHeader(value) {
+    if (!value) {
+        return undefined;
+    }
+    const numeric = Number(value);
+    if (Number.isFinite(numeric) && numeric > 0) {
+        return Math.round(numeric * 1000);
+    }
+    return undefined;
+}
+function toOptionalRetryAfterMs(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        return undefined;
+    }
+    return Math.round(value);
+}
+function resolveTransportMode(raw) {
+    if (!raw) {
+        return "rest";
+    }
+    const normalized = raw.trim().toLowerCase();
+    if (normalized === "rest" || normalized === "mcp") {
+        return normalized;
+    }
+    throw new Error("transport must be 'rest' or 'mcp'.");
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { IntentFiClient } from "./client";
+export type { ActiveSubmissionContext, ExecutionArtifactInput, Envelope, GatewayWalletType, PrepareActiveResult, SubmittedTransaction, TransportMode, WorkflowDetail, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,YAAY,EACV,uBAAuB,EACvB,sBAAsB,EACtB,QAAQ,EACR,iBAAiB,EACjB,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,cAAc,GACf,MAAM,SAAS,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { IntentFiClient } from "./client";

package/dist/types.d.ts

@@ -0,0 +1,111 @@
+export type Envelope<T> = {
+    ok: true;
+    data: T;
+    traceId: string;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        category?: string;
+        retryable?: boolean;
+        details?: Record<string, unknown>;
+    };
+    traceId: string;
+};
+export type TransportMode = "rest" | "mcp";
+export type WorkflowDetail = {
+    _id: string;
+    status: string;
+    nextAction?: {
+        type?: string;
+        batchIndex?: number;
+        [key: string]: unknown;
+    } | null;
+    batchesTotal?: number;
+    batchesConfirmed?: number;
+    currentBatchIndex?: number;
+    [key: string]: unknown;
+};
+export type PrepareActiveResult = {
+    kind: "pending";
+    retryAfterMs: number;
+    reason: "WORKFLOW_PLANNING" | "BATCH_PREPARING";
+} | {
+    kind: "ready";
+    batchId: string;
+    manifestHash: string;
+    manifestVersion: number;
+    validUntilMs: number;
+    callCount: number;
+    manifest: {
+        version: number;
+        chainId: number;
+        calls: Array<{
+            to: string;
+            data: string;
+            value?: string;
+            gasLimit?: string | number;
+            stepId?: string;
+        }>;
+    };
+};
+export type ActiveSubmissionContext = {
+    workflowId: string;
+    batchId: string;
+    batchIndex: number;
+    batchStatus: string;
+    manifestHash: string;
+    manifestVersion: number;
+    validUntilMs: number;
+    callCount: number;
+    manifest: {
+        version: number;
+        chainId: number;
+        calls: Array<{
+            to: string;
+            data: string;
+            value?: string;
+            gasLimit?: string | number;
+            stepId?: string;
+        }>;
+    };
+};
+export type GatewayWalletType = "porto" | "base" | "eoa";
+export type ExecutionCallInput = {
+    executionCallIndex: number;
+    type: "manifest" | "wallet-preCall" | "wallet-postCall" | "wallet-internal";
+    manifestCallIndex?: number;
+    stepId?: string;
+    request: {
+        to: string;
+        data: string;
+        value?: string;
+        chainId?: number;
+        gasLimit?: string | number;
+    };
+    metadata?: unknown;
+};
+export type ExecutionArtifactInput = {
+    manifestVersion: number;
+    manifestHash: string;
+    manifestSize: number;
+    capturedAtIso: string;
+    bundle: {
+        id: string;
+        chainId?: number;
+        walletType: GatewayWalletType;
+        walletProvider: "porto" | "coinbase";
+    };
+    calls: ExecutionCallInput[];
+    checksum?: {
+        manifestCallIndices: number[];
+        executionCallIndices: number[];
+    };
+    notes?: unknown;
+};
+export type SubmittedTransaction = {
+    manifestCallIndex: number;
+    txHash: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@intentfi/agent-sdk",
+  "version": "0.1.0",
+  "description": "TypeScript SDK and CLI for the IntentFi agentic DeFi gateway — create, monitor, and execute intent-based workflows via REST or MCP",
+  "type": "module",
+  "license": "Apache-2.0",
+  "author": "IntentFi",
+  "homepage": "https://intentfi.io",
+  "bugs": {
+    "url": "https://intentfi.io"
+  },
+  "keywords": [
+    "defi",
+    "intent",
+    "agent",
+    "sdk",
+    "mcp",
+    "ethereum",
+    "web3",
+    "intentfi"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "bin": {
+    "intentfi": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "viem": "^2.45.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.10",
+    "typescript": "^5.9.3"
+  }
+}