@illalabs/sdk 0.1.0 → 0.3.0

package/dist/src/sdk.js

@@ -0,0 +1,288 @@
+import { AsyncToolChecker, Chat, ContextManager, CoreApiProvider, InMemoryCache, Prompt, UserContextMissing, } from "./internal.js";
+/**
+ * Error raised when attempting to interact with a chat that doesn't exist.
+ *
+ * This typically occurs when using an invalid or expired chat ID with methods
+ * like {@link IllaSDK.sendToolResult}.
+ */
+class ChatNotFound extends Error {
+    /**
+     * The ID of the chat that was not found.
+     */
+    chatId;
+    /**
+     * Creates a new {@link ChatNotFound} instance.
+     *
+     * @param chatId The ID of the chat that was not found.
+     * @param options Error options for error chaining.
+     */
+    constructor(chatId, options) {
+        super(`Chat with ID ${chatId} not found`, options);
+        this.name = "ChatNotFound";
+        this.chatId = chatId;
+    }
+}
+/**
+ * The main entry point for interacting with the ILLA AI SDK.
+ * This class provides methods for creating and managing chat sessions,
+ * sending messages, handling tool results, and configuring async tool checkers.
+ *
+ * @example
+ * ```typescript
+ * import { IllaSDK } from '@illalabs/sdk';
+ *
+ * const sdk = new IllaSDK({
+ *   apiKey: 'your-api-key'
+ * });
+ *
+ * // Start a conversation
+ * const result = await sdk.sendMessage(
+ *   "What can you help me with?",
+ *   { userContext: { address: "0x1234..." } }
+ * );
+ *
+ * console.log(result.response.text);
+ * ```
+ */
+class IllaSDK {
+    coreApiProvider;
+    contextManager;
+    chats = new Map();
+    /**
+     * Creates a new instance of the IllaSDK.
+     *
+     * @param config - Configuration object containing API key and optional base URL
+     * @param options - Optional configuration for cache and context manager
+     *
+     * @example
+     * ```typescript
+     * // Basic initialization
+     * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
+     *
+     * // With custom cache
+     * const cache = new InMemoryCache();
+     * const sdk = new IllaSDK(
+     *   { apiKey: 'your-api-key' },
+     *   { cache }
+     * );
+     *
+     * // With custom context manager
+     * const contextManager = new ContextManager(cache, { defaultToolsConfig: { autoRouter: { swapOrBridge: 'lifi' } } });
+     * const sdk = new IllaSDK(
+     *   { apiKey: 'your-api-key' },
+     *   { contextManager }
+     * );
+     * ```
+     */
+    constructor(config, options) {
+        this.coreApiProvider = new CoreApiProvider({
+            baseURL: config.baseURL,
+            headers: {
+                "x-api-key": config.apiKey,
+            },
+        });
+        if (options && options.contextManager) {
+            this.contextManager = options.contextManager;
+        }
+        else {
+            this.contextManager = new ContextManager(options?.cache ?? new InMemoryCache(), options?.contextManagerOptions ?? {});
+        }
+    }
+    /**
+     * Gets an array of all active chat IDs managed by this SDK instance.
+     *
+     * @returns {string[]} Array of chat IDs
+     *
+     * @example
+     * ```typescript
+     * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
+     *
+     * await sdk.sendMessage("Hello", { userContext: { address: "0x123" } });
+     * await sdk.sendMessage("Hi", { userContext: { address: "0x456" } });
+     *
+     * const chatIds = sdk.chatIds;
+     * console.log(chatIds); // ['chat-id-1', 'chat-id-2']
+     * ```
+     */
+    get chatIds() {
+        return Array.from(this.chats.keys());
+    }
+    /**
+     * Creates a new ContextManager instance. This is a factory method for creating
+     * context managers with custom configurations.
+     *
+     * @param cache - The cache implementation to use for storing context
+     * @param options - Configuration options for the context manager
+     * @returns {ContextManager} A new ContextManager instance
+     *
+     * @example
+     * ```typescript
+     * const cache = new InMemoryCache();
+     * const contextManager = IllaSDK.createNewContextManager(cache, {
+     *  defaultToolsConfig: {
+     *    autoRouter: { swapOrBridge: 'lifi' }
+     *  }
+     * });
+     *
+     * const sdk = new IllaSDK(
+     *   { apiKey: 'your-api-key' },
+     *   { contextManager }
+     * );
+     * ```
+     */
+    static createNewContextManager(cache, options) {
+        return new ContextManager(cache, options);
+    }
+    /**
+     * Creates a new Chat instance with the specified options.
+     * The chat is automatically registered with this SDK instance.
+     *
+     * @param options - Options for creating the chat, including user context and optional ID
+     * @param contextManager - Optional custom context manager for this chat. If not provided, uses the SDK's default
+     * @returns {Chat} A new Chat instance
+     *
+     * @example
+     * ```typescript
+     * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
+     *
+     * // Create a new chat
+     * const chat = sdk.createChat({
+     *   userContext: { address: "0x1234..." }
+     * });
+     *
+     * // Send messages directly through the chat instance
+     * const result = await chat.sendMessage(new Prompt({ text: "Hello!" }));
+     * ```
+     */
+    createChat(options, contextManager) {
+        const chat = new Chat({
+            coreApiProvider: this.coreApiProvider,
+            contextManager: contextManager ?? this.contextManager,
+            userContext: options.userContext,
+            id: options.id,
+            asyncToolChecker: new AsyncToolChecker({
+                coreApiProvider: this.coreApiProvider,
+            }),
+            personalityContext: options.personalityContext,
+        });
+        this.chats.set(chat.getId(), chat);
+        return chat;
+    }
+    /**
+     * Sends a message to a chat session. This is the primary method for interacting with the AI.
+     * If a chatId is provided, the message will be sent to the existing chat.
+     * If a chatId is not provided, a new chat will be created with the provided userContext.
+     *
+     * @param msg - The message text to send
+     * @param context - Context containing either chatId for existing chat or userContext for new chat
+     * @returns {Promise<SendMessageResult>} The AI's response including chat ID, response text, and any pending tools
+     *
+     * @example
+     * ```typescript
+     * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
+     *
+     * // Start a new conversation
+     * const result1 = await sdk.sendMessage(
+     *   "What can you help me with?",
+     *   { userContext: { address: "0x1234..." } }
+     * );
+     * console.log(result1.response.text);
+     * console.log("Chat ID:", result1.chatId);
+     *
+     * // Continue the conversation using the chat ID
+     * const result2 = await sdk.sendMessage(
+     *   "I want to swap 1 ETH for USDC on Base",
+     *   { chatId: result1.chatId }
+     * );
+     *
+     * // Check if there are tools to execute
+     * if (result2.response.pendingTools && result2.response.pendingTools.length > 0) {
+     *   console.log("Tool to execute:", result2.response.pendingTools[0]);
+     * }
+     * ```
+     */
+    sendMessage(msg, context) {
+        if (context.chatId && this.chats.get(context.chatId) !== undefined) {
+            return this.chats.get(context.chatId).sendMessage(new Prompt({ text: msg }));
+        }
+        if (!context.userContext) {
+            throw new UserContextMissing();
+        }
+        const chat = this.createChat({ userContext: context.userContext });
+        this.chats.set(chat.getId(), chat);
+        return chat.sendMessage(new Prompt({ text: msg }));
+    }
+    /**
+     * Sends the result of a tool execution back to the AI. This method is used to complete
+     * the tool execution loop when the AI requests a tool to be executed.
+     *
+     * @param chatId - The ID of the chat to send the tool result to
+     * @param toolResult - The result of the tool execution
+     * @returns {Promise<SendMessageResult>} The AI's response after processing the tool result
+     * @throws {Error} If the chat with the specified chatId is not found
+     *
+     * @example
+     * ```typescript
+     * const sdk = new IllaSDK({ apiKey: 'your-api-key' });
+     *
+     * // Start a conversation that will request a tool execution
+     * const result1 = await sdk.sendMessage(
+     *   "Swap 1 ETH for USDC on Base",
+     *   { userContext: { address: "0x1234..." } }
+     * );
+     *
+     * // Check if there are pending tools to execute
+     * if (result1.response.pendingTools && result1.response.pendingTools.length > 0) {
+     *   const tool = result1.response.pendingTools[0];
+     *
+     *   // Execute the tool (e.g., send a transaction)
+     *   const executionResult = await executeTool(tool);
+     *
+     *   // Send the result back to the ILLA
+     *   const toolResult: ToolResultType = {
+     *     toolCallId: tool.toolCallId,
+     *     toolName: tool.toolName,
+     *     result?: executionResult,
+     *     error?: executionResult.error,
+     *   };
+     *
+     *   const result2 = await sdk.sendToolResult(result1.chatId, toolResult);
+     *   console.log(result2.response.text); // ILLA's response after processing the tool result
+     * }
+     * ```
+     */
+    async sendToolResult(chatId, toolResult) {
+        if (this.chats.get(chatId) === undefined) {
+            throw new ChatNotFound(chatId);
+        }
+        return await this.chats.get(chatId).sendMessage(new Prompt({ toolResult }));
+    }
+    /**
+     * Gets the messages for a given chat ID.
+     *
+     * @param chatId - The ID of the chat to get the messages for
+     * @returns {Promise<MessageHistoryType>} The messages for the chat
+     * @throws {ChatNotFound} If the chat with the specified chatId is not found
+     */
+    async getMessages(chatId) {
+        const chat = this.chats.get(chatId);
+        if (!chat) {
+            throw new ChatNotFound(chatId);
+        }
+        return chat.messages;
+    }
+}
+/**
+ * Exports the public API of the SDK.
+ * A user could import IllaSDK as a single entry point to the SDK.
+ * Or they could import the individual components of the SDK for advanced usage.
+ */
+export { IllaSDK, ChatNotFound };
+export { InMemoryCache } from "./caching/index.js";
+export { Prompt } from "./prompt/index.js";
+export { Chat } from "./chat/index.js";
+export { ContextManager } from "./context/index.js";
+export { AsyncToolChecker } from "./asyncToolChecker/index.js";
+export { CoreApiProvider } from "./providers/index.js";
+export { UserContextMissing } from "./chat/errors/index.js";
+//# sourceMappingURL=sdk.js.map

package/dist/src/sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../src/sdk.ts"],"names":[],"mappings":"AAeA,OAAO,EACH,gBAAgB,EAChB,IAAI,EACJ,cAAc,EACd,eAAe,EACf,aAAa,EACb,MAAM,EACN,kBAAkB,GACrB,MAAM,eAAe,CAAC;AAyDvB;;;;;GAKG;AACH,MAAM,YAAa,SAAQ,KAAK;IAC5B;;OAEG;IACa,MAAM,CAAS;IAE/B;;;;;OAKG;IACH,YAAmB,MAAc,EAAE,OAAsB;QACrD,KAAK,CAAC,gBAAgB,MAAM,YAAY,EAAE,OAAO,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;CACJ;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO;IACD,eAAe,CAAkB;IACjC,cAAc,CAAkB;IAEhC,KAAK,GAAsB,IAAI,GAAG,EAAE,CAAC;IAE7C;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,YAAY,MAAqB,EAAE,OAAwB;QACvD,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,CAAC;YACvC,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE;gBACL,WAAW,EAAE,MAAM,CAAC,MAAM;aAC7B;SACJ,CAAC,CAAC;QAEH,IAAI,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;YACpC,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;QACjD,CAAC;aAAM,CAAC;YACJ,IAAI,CAAC,cAAc,GAAG,IAAI,cAAc,CACpC,OAAO,EAAE,KAAK,IAAI,IAAI,aAAa,EAAE,EACrC,OAAO,EAAE,qBAAqB,IAAI,EAAE,CACvC,CAAC;QACN,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAW,OAAO;QACd,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,MAAM,CAAC,uBAAuB,CACjC,KAAa,EACb,OAA8B;QAE9B,OAAO,IAAI,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACI,UAAU,CAAC,OAAoB,EAAE,cAA+B;QACnE,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC;YAClB,eAAe,EAAE,IAAI,CAAC,eAAe;YACrC,cAAc,EAAE,cAAc,IAAI,IAAI,CAAC,cAAc;YACrD,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,gBAAgB,EAAE,IAAI,gBAAgB,CAAC;gBACnC,eAAe,EAAE,IAAI,CAAC,eAAe;aACxC,CAAC;YACF,kBAAkB,EAAE,OAAO,CAAC,kBAAkB;SACjD,CAAC,CAAC;QAEH,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IAChB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACI,WAAW,CAAC,GAAW,EAAE,OAA2B;QACvD,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YACjE,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,MAAM,CAAE,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QAClF,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,IAAI,kBAAkB,EAAE,CAAC;QACnC,CAAC;QACD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;QACnE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACI,KAAK,CAAC,cAAc,CACvB,MAAc,EACd,UAA0B;QAE1B,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,SAAS,EAAE,CAAC;YACvC,MAAM,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC,WAAW,CAAC,IAAI,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;IACjF,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,WAAW,CAAC,MAAc;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,EAAE,CAAC;YACR,MAAM,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC;IACzB,CAAC;CACJ;AAED;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACpD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illalabs/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "TypeScript SDK for interacting with Illa's Core API",
   "license": "MIT",
@@ -23,12 +23,16 @@
     "axios": "1.12.2",
     "uuid": "13.0.0",
     "viem": "2.37.13",
-    "@illalabs/interfaces": "0.1.0"
+    "@illalabs/interfaces": "0.2.0"
+  },
+  "devDependencies": {
+    "zod": "4.1.12"
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "anvil": "./scripts/start-anvil.sh",
     "build": "tsc -p tsconfig.build.json",
     "check-types": "tsc --noEmit -p tsconfig.json",
     "clean": "rm -rf dist",
@@ -37,6 +41,8 @@
     "lint": "eslint \"{src,test}/**/*.{ts,js,json}\"",
     "lint:fix": "pnpm lint --fix",
     "test": "vitest run --config vitest.config.ts --passWithNoTests",
-    "test:cov": "vitest run --config vitest.config.ts --coverage"
+    "test:cov": "vitest run --config vitest.config.ts --coverage",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "test:e2e:anvil": "./scripts/test-with-anvil.sh"
   }
 }

package/dist/src/providers/coreApiProvider/CoreApiProviderConfig.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"CoreApiProviderConfig.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/CoreApiProviderConfig.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAClD"}

package/dist/src/providers/coreApiProvider/CoreApiProviderConfig.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=CoreApiProviderConfig.js.map

package/dist/src/providers/coreApiProvider/CoreApiProviderConfig.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"CoreApiProviderConfig.js","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/CoreApiProviderConfig.ts"],"names":[],"mappings":""}

package/dist/src/providers/coreApiProvider/RequestOptions.d.ts

@@ -1,10 +0,0 @@
-/**
- * Options for Core API requests
- */
-export interface RequestOptions {
-    /**
-     * Abort signal used to cancel the request
-     */
-    readonly signal?: AbortSignal;
-}
-//# sourceMappingURL=RequestOptions.d.ts.map

package/dist/src/providers/coreApiProvider/RequestOptions.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"RequestOptions.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/RequestOptions.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CACjC"}

package/dist/src/providers/coreApiProvider/RequestOptions.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=RequestOptions.js.map

package/dist/src/providers/coreApiProvider/RequestOptions.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"RequestOptions.js","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/RequestOptions.ts"],"names":[],"mappings":""}