@illalabs/sdk 0.0.0-dev-3-9cae6c3-20251024213833 → 0.1.0-canary.48bfe253

package/README.md

@@ -0,0 +1,143 @@
+# @illalabs/sdk
+
+TypeScript SDK for building chat-based blockchain interactions with Illa's Core API.
+
+## 🚀 Installation
+
+```bash
+npm install @illalabs/sdk
+# or
+pnpm add @illalabs/sdk
+```
+
+## 📖 Quick Start
+
+```typescript
+import { Chat, ContextManager, CoreApiProvider, InMemoryCache, Prompt } from "@illalabs/sdk";
+
+// Configure the API provider
+const provider = new CoreApiProvider({
+    baseURL: "https://api-dev.illalabs.io",
+    headers: {
+        "x-api-key": "your-api-key",
+    },
+});
+
+// Set up context management with caching
+const cache = new InMemoryCache();
+const contextManager = new ContextManager(cache);
+
+// Create a chat instance
+const chat = new Chat({
+    coreApiProvider: provider,
+    contextManager,
+    userContext: {
+        address: "0x...", // User's wallet address
+    },
+});
+
+// Send a message
+const prompt = new Prompt({ text: "What is my wallet balance on Base?" });
+const result = await chat.sendMessage(prompt);
+
+console.log("Response:", result.response.text);
+```
+
+## 🧪 Testing
+
+### Unit Tests
+
+```bash
+pnpm test              # Run unit tests
+pnpm test:cov          # Run with coverage
+```
+
+### E2E Tests
+
+The SDK provides comprehensive E2E testing using Anvil to fork Base mainnet. This ensures tests run against a realistic blockchain environment that's compatible with the Core API (chain ID 8453).
+
+#### Prerequisites
+
+E2E tests **require** a Base RPC URL for forking:
+
+```bash
+# Set Base fork URL (required for E2E tests)
+export E2E_FORK_BASE_RPC_URL="https://mainnet.base.org"
+
+# Get a faster RPC from:
+# - Alchemy: https://www.alchemy.com/
+# - Infura: https://www.infura.io/
+# - QuickNode: https://www.quicknode.com/
+```
+
+#### Quick Start
+
+```bash
+# Mocked API + Anvil (Base fork)
+E2E_FORK_BASE_RPC_URL="https://mainnet.base.org" pnpm test:e2e:anvil
+
+# Real API + Anvil (Base fork) - full integration
+E2E_API_KEY=your-api-key E2E_FORK_BASE_RPC_URL="https://mainnet.base.org" pnpm test:e2e:anvil
+```
+
+#### Configuration Options
+
+**Required:**
+
+-   `E2E_FORK_BASE_RPC_URL`: Base mainnet RPC URL for forking (required for all E2E tests)
+
+**Optional:**
+
+-   `E2E_API_KEY`: API key for authentication (if not provided, uses mocked API)
+-   `E2E_BASE_URL`: Base URL for the API endpoint (default: `https://api-dev.illalabs.io`)
+-   `E2E_TEST_ADDRESS`: Test wallet address (default: `0x5527E7744df42A56ABE7451cbFEDa1601Fa35196`)
+
+**Note:** Environment variables use the `E2E_` prefix to avoid conflicts with vitest/vite built-in variables.
+
+## 📚 Documentation
+
+-   [Introduction](./docs/introduction.mdx)
+-   [Authentication](./docs/authentication.mdx)
+-   [Quickstart](./docs/quickstart.mdx)
+-   [Configuration](./docs/concepts/configuration.mdx)
+-   [Error Handling](./docs/concepts/error-handling.mdx)
+-   [TypeScript Support](./docs/concepts/typescript-support.mdx)
+-   [Testing Guide](./docs/testing.mdx)
+
+## Features
+
+-   **Chat-based Interface**: Intuitive conversational API for blockchain interactions
+-   **Context Management**: Automatic conversation history and state management
+-   **Multi-turn Conversations**: Seamless context preservation across messages
+-   **Session Persistence**: Resume conversations across different instances
+-   **Async Tool Monitoring**: Built-in support for long-running blockchain operations
+-   **TypeScript-first**: Full type safety with comprehensive type definitions
+-   **Flexible Caching**: Pluggable cache implementations (in-memory, Redis, etc.)
+
+## 📦 Project Structure
+
+```plaintext
+src/
+├── chat/              # Chat class and related utilities
+├── context/           # Context management
+├── caching/           # Cache implementations
+├── prompt/            # Prompt creation and formatting
+├── providers/         # API provider implementations
+├── interfaces/        # TypeScript interfaces
+└── asyncToolChecker/  # Tool execution monitoring
+
+test/
+├── unit/              # Unit tests
+├── e2e/              # End-to-end tests organized by class
+└── utils/            # Shared test utilities and helpers
+```
+
+## Contributing
+
+Wonderland is a team of top Web3 researchers, developers, and operators who believe that the future needs to be open-source, permissionless, and decentralized
+
+[DeFi sucks](https://defi.sucks), but Wonderland is here to make it better
+
+## 📄 License
+
+MIT - See [LICENSE](../../LICENSE) for details.

package/dist/src/interfaces/coreApiProvider.interface.d.ts

@@ -1,5 +1,5 @@
 import type { CoreApiChatRequest, CoreApiChatResponse, LongPollingActionRequest, LongPollingActionResponse } from "@illalabs/interfaces";
-import type { RequestOptions } from "../providers/coreApiProvider/index.js";
+import type { CoreApiProviderRoutes, RequestOptions } from "../providers/coreApiProvider/index.js";
 /**
  * Contract for the Core API provider
  */
@@ -22,5 +22,11 @@ export interface ICoreApiProvider {
      * @returns Core API execution checker response
      */
     awaitTransaction(request: LongPollingActionRequest["params"], options?: RequestOptions): Promise<LongPollingActionResponse>;
+    /**
+     * Retrieves the configured routes for the Core API endpoints used by the provider.
+     *
+     * @returns Route configuration including chat and action status paths.
+     */
+    getRoutes(): Required<CoreApiProviderRoutes>;
 }
 //# sourceMappingURL=coreApiProvider.interface.d.ts.map

package/dist/src/interfaces/coreApiProvider.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"coreApiProvider.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/coreApiProvider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;OAOG;IACH,WAAW,CACP,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,EACnC,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEhC;;;;;;;OAOG;IACH,gBAAgB,CACZ,OAAO,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAC3C,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,yBAAyB,CAAC,CAAC;CACzC"}
+{"version":3,"file":"coreApiProvider.interface.d.ts","sourceRoot":"","sources":["../../../src/interfaces/coreApiProvider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAEnG;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;OAOG;IACH,WAAW,CACP,OAAO,EAAE,kBAAkB,CAAC,MAAM,CAAC,EACnC,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEhC;;;;;;;OAOG;IACH,gBAAgB,CACZ,OAAO,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAC3C,OAAO,CAAC,EAAE,cAAc,GACzB,OAAO,CAAC,yBAAyB,CAAC,CAAC;IAEtC;;;;OAIG;IACH,SAAS,IAAI,QAAQ,CAAC,qBAAqB,CAAC,CAAC;CAChD"}

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

@@ -1,7 +1,8 @@
 import type { CoreApiChatRequest, CoreApiChatResponse, LongPollingActionRequest, LongPollingActionResponse } from "@illalabs/interfaces";
 import type { AxiosInstance } from "axios";
 import type { ICoreApiProvider } from "../../interfaces/index.js";
-import type { CoreApiProviderConfig, RequestOptions } from "./index.js";
+import type { CoreApiProviderConfig, CoreApiProviderRoutes } from "./interfaces/index.js";
+import type { RequestOptions } from "./types.js";
 /**
  * Axios based Core API provider implementation
  */
@@ -10,10 +11,14 @@ export declare class CoreApiProvider implements ICoreApiProvider {
      * Axios instance configured for the Core API
      */
     protected readonly client: AxiosInstance;
+    /**
+     * Routes used by the provider when issuing requests.
+     */
+    protected readonly routes: Required<CoreApiProviderRoutes>;
     /**
      * @param config Core API provider configuration
      */
-    constructor({ baseURL, timeout, headers, httpClientFactory }: CoreApiProviderConfig);
+    constructor({ baseURL, timeout, headers, httpClientFactory, routes }: CoreApiProviderConfig);
     /**
      * Sends a chat message to the Core API
      */
@@ -22,6 +27,8 @@ export declare class CoreApiProvider implements ICoreApiProvider {
      * Polls the Core API for transaction status
      */
     awaitTransaction(params: LongPollingActionRequest["params"], options?: RequestOptions): Promise<LongPollingActionResponse>;
+    /** @inheritdoc */
+    getRoutes(): Required<CoreApiProviderRoutes>;
     /**
      * Builds request configuration shared across endpoints
      */

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

@@ -1 +1 @@
-{"version":3,"file":"CoreApiProvider.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/CoreApiProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAER,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,OAAO,CAAC;AAG/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIxE;;GAEG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACpD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAEzC;;OAEG;gBACS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,EAAE,qBAAqB;IAcnF;;OAEG;IACU,WAAW,CACpB,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAChC,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAsB/B;;OAEG;IACU,gBAAgB,CACzB,MAAM,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAC1C,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,yBAAyB,CAAC;IA0BrC;;OAEG;IACH,SAAS,CAAC,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;IAM/E,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,iBAAiB;CAO5B"}
+{"version":3,"file":"CoreApiProvider.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/CoreApiProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAER,kBAAkB,EAClB,mBAAmB,EACnB,wBAAwB,EACxB,yBAAyB,EAC5B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,aAAa,EAAsB,MAAM,OAAO,CAAC;AAG/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,KAAK,EAAqB,cAAc,EAAE,MAAM,YAAY,CAAC;AAGpE;;GAEG;AACH,qBAAa,eAAgB,YAAW,gBAAgB;IACpD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAEzC;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;IAE3D;;OAEG;gBACS,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,EAAE,EAAE,qBAAqB;IAmB3F;;OAEG;IACU,WAAW,CACpB,IAAI,EAAE,kBAAkB,CAAC,MAAM,CAAC,EAChC,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,mBAAmB,CAAC;IAsB/B;;OAEG;IACU,gBAAgB,CACzB,MAAM,EAAE,wBAAwB,CAAC,QAAQ,CAAC,EAC1C,OAAO,GAAE,cAAmB,GAC7B,OAAO,CAAC,yBAAyB,CAAC;IA6BrC,kBAAkB;IACX,SAAS,IAAI,QAAQ,CAAC,qBAAqB,CAAC;IAInD;;OAEG;IACH,SAAS,CAAC,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;IAM/E,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,iBAAiB;CAO5B"}

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

@@ -8,10 +8,14 @@ export class CoreApiProvider {
      * Axios instance configured for the Core API
      */
     client;
+    /**
+     * Routes used by the provider when issuing requests.
+     */
+    routes;
     /**
      * @param config Core API provider configuration
      */
-    constructor({ baseURL, timeout, headers, httpClientFactory }) {
+    constructor({ baseURL, timeout, headers, httpClientFactory, routes }) {
         const authHeaders = this.ensureAuthHeaders(headers);
         const resolveClientFactory = httpClientFactory ??
             ((configuration) => axios.create(configuration));
@@ -20,13 +24,17 @@ export class CoreApiProvider {
             timeout,
             headers: this.buildDefaultHeaders(authHeaders),
         });
+        this.routes = {
+            chat: routes?.chat ?? "/api/v1/chat/",
+            actionStatus: routes?.actionStatus ?? "/api/v1/actions/check",
+        };
     }
     /**
      * Sends a chat message to the Core API
      */
     async sendMessage(body, options = {}) {
         const requestConfig = this.buildRequestConfig(options);
-        const response = await this.client.post("/api/v1/chat", body, requestConfig);
+        const response = await this.client.post(this.routes.chat, body, requestConfig);
         return response.data;
         //TODO: Handle errors
         // try{
@@ -45,7 +53,7 @@ export class CoreApiProvider {
      */
     async awaitTransaction(params, options = {}) {
         const requestConfig = this.buildRequestConfig(options);
-        const response = await this.client.get("/api/v1/actions/check", {
+        const response = await this.client.get(this.routes.actionStatus, {
             ...requestConfig,
             params: {
                 toolName: params.toolName,
@@ -66,6 +74,10 @@ export class CoreApiProvider {
         //    return errorResponse;
         // }
     }
+    /** @inheritdoc */
+    getRoutes() {
+        return this.routes;
+    }
     /**
      * Builds request configuration shared across endpoints
      */
@@ -75,7 +87,8 @@ export class CoreApiProvider {
         };
     }
     resolveBaseUrl(baseURL) {
-        return baseURL ?? "https://app.illa.network";
+        // TODO: update base URL depending on final deployment
+        return baseURL ?? "https://api-dev.illalabs.io";
     }
     buildDefaultHeaders(headers) {
         return {
@@ -84,7 +97,7 @@ export class CoreApiProvider {
         };
     }
     ensureAuthHeaders(headers) {
-        if (headers?.["x-auth-token"] === undefined) {
+        if (headers?.["x-api-key"] === undefined) {
             throw new CoreApiAuthenticationMissing();
         }
         return headers;

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

@@ -1 +1 @@
-{"version":3,"file":"CoreApiProvider.js","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/CoreApiProvider.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,MAAM,OAAO,CAAC;AAK1B,OAAO,EAAE,4BAA4B,EAAE,MAAM,mBAAmB,CAAC;AAEjE;;GAEG;AACH,MAAM,OAAO,eAAe;IACxB;;OAEG;IACgB,MAAM,CAAgB;IAEzC;;OAEG;IACH,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAyB;QAC/E,MAAM,WAAW,GAAG,IAAI,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAEpD,MAAM,oBAAoB,GACtB,iBAAiB;YACjB,CAAC,CAAC,aAAkC,EAAiB,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;QAEzF,IAAI,CAAC,MAAM,GAAG,oBAAoB,CAAC;YAC/B,OAAO,EAAE,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC;YACrC,OAAO;YACP,OAAO,EAAE,IAAI,CAAC,mBAAmB,CAAC,WAAW,CAAC;SACjD,CAAC,CAAC;IACP,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,WAAW,CACpB,IAAgC,EAChC,UAA0B,EAAE;QAE5B,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QACvD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CACnC,cAAc,EACd,IAAI,EACJ,aAAa,CAChB,CAAC;QAEF,OAAO,QAAQ,CAAC,IAAI,CAAC;QACrB,qBAAqB;QACrB,OAAO;QACP,wDAAwD;QACxD,2BAA2B;QAC3B,IAAI;QACJ,gBAAgB;QAChB,gFAAgF;QAChF,qCAAqC;QACrC,qFAAqF;QACrF,2BAA2B;QAC3B,IAAI;IACR,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,gBAAgB,CACzB,MAA0C,EAC1C,UAA0B,EAAE;QAE5B,MAAM,aAAa,GAAG,IAAI,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;QAEvD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAA4B,uBAAuB,EAAE;YACvF,GAAG,aAAa;YAChB,MAAM,EAAE;gBACJ,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,IAAI,EAAE,MAAM,CAAC,IAAI;aACpB;SACJ,CAAC,CAAC;QAEH,OAAO,QAAQ,CAAC,IAAI,CAAC;QACrB,qBAAqB;QACrB,OAAO;QACP,6DAA6D;QAC7D,2BAA2B;QAC3B,IAAI;QACJ,gBAAgB;QAChB,gFAAgF;QAChF,qCAAqC;QACrC,uGAAuG;QACvG,2BAA2B;QAC3B,IAAI;IACR,CAAC;IAED;;OAEG;IACO,kBAAkB,CAAC,OAAuB;QAChD,OAAO;YACH,MAAM,EAAE,OAAO,CAAC,MAAM;SACzB,CAAC;IACN,CAAC;IAEO,cAAc,CAAC,OAAyC;QAC5D,OAAO,OAAO,IAAI,0BAA0B,CAAC;IACjD,CAAC;IAEO,mBAAmB,CAAC,OAA2B;QACnD,OAAO;YACH,cAAc,EAAE,kBAAkB;YAClC,GAAG,OAAO;SACb,CAAC;IACN,CAAC;IAEO,iBAAiB,CAAC,OAA4B;QAClD,IAAI,OAAO,EAAE,CAAC,cAAc,CAAC,KAAK,SAAS,EAAE,CAAC;YAC1C,MAAM,IAAI,4BAA4B,EAAE,CAAC;QAC7C,CAAC;QAED,OAAO,OAAO,CAAC;IACnB,CAAC;CACJ"}
+{"version":3,"file":"CoreApiProvider.js","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/CoreApiProvider.ts"],"names":[],"mappings":"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"}

package/dist/src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.d.ts

@@ -1,10 +1,8 @@
 /**
- * Raised when the authentication token is not provided
+ * Raised when the API key is not provided
  */
-export declare class CoreApiAuthenticationMissing {
+export declare class CoreApiAuthenticationMissing extends Error {
     readonly statusCode = 401;
-    readonly name: string;
-    readonly message: string;
     constructor();
 }
 //# sourceMappingURL=CoreApiAuthenticationMissing.d.ts.map

package/dist/src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CoreApiAuthenticationMissing.d.ts","sourceRoot":"","sources":["../../../../../src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,4BAA4B;IACrC,SAAgB,UAAU,OAAO;IACjC,SAAgB,IAAI,EAAE,MAAM,CAAC;IAC7B,SAAgB,OAAO,EAAE,MAAM,CAAC;;CAMnC"}
+{"version":3,"file":"CoreApiAuthenticationMissing.d.ts","sourceRoot":"","sources":["../../../../../src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACnD,SAAgB,UAAU,OAAO;;CAWpC"}

package/dist/src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.js

@@ -1,14 +1,15 @@
 /**
- * Raised when the authentication token is not provided
+ * Raised when the API key is not provided
  */
-export class CoreApiAuthenticationMissing {
+export class CoreApiAuthenticationMissing extends Error {
     statusCode = 401;
-    name;
-    message;
     constructor() {
-        this.statusCode = 401;
+        const message = "Core API key is required";
+        super(message);
         this.name = "CoreApiAuthenticationMissing";
-        this.message = "Core API authentication token is required";
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CoreApiAuthenticationMissing);
+        }
     }
 }
 //# sourceMappingURL=CoreApiAuthenticationMissing.js.map

package/dist/src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.js.map

@@ -1 +1 @@
-{"version":3,"file":"CoreApiAuthenticationMissing.js","sourceRoot":"","sources":["../../../../../src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,4BAA4B;IACrB,UAAU,GAAG,GAAG,CAAC;IACjB,IAAI,CAAS;IACb,OAAO,CAAS;IAChC;QACI,IAAI,CAAC,UAAU,GAAG,GAAG,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,IAAI,CAAC,OAAO,GAAG,2CAA2C,CAAC;IAC/D,CAAC;CACJ"}
+{"version":3,"file":"CoreApiAuthenticationMissing.js","sourceRoot":"","sources":["../../../../../src/providers/coreApiProvider/errors/CoreApiAuthenticationMissing.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IACnC,UAAU,GAAG,GAAG,CAAC;IAEjC;QACI,MAAM,OAAO,GAAG,0BAA0B,CAAC;QAC3C,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAE3C,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC1B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,4BAA4B,CAAC,CAAC;QAChE,CAAC;IACL,CAAC;CACJ"}

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

@@ -1,7 +1,6 @@
 export * from "./CoreApiProvider.js";
 export type { ICoreApiProvider } from "../../interfaces/index.js";
-export type { CoreApiProviderConfig } from "./CoreApiProviderConfig.js";
-export type { HttpClientFactory } from "./types.js";
-export type { RequestOptions } from "./RequestOptions.js";
+export type { CoreApiProviderConfig, CoreApiProviderRoutes } from "./interfaces/index.js";
+export type { HttpClientFactory, RequestOptions } from "./types.js";
 export * from "./errors/index.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AACrC,YAAY,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAClE,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACpE,cAAc,mBAAmB,CAAC"}

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AAKrC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/index.ts"],"names":[],"mappings":"AAAA,cAAc,sBAAsB,CAAC;AAIrC,cAAc,mBAAmB,CAAC"}

package/dist/src/providers/coreApiProvider/{CoreApiProviderConfig.d.ts → interfaces/CoreApiProviderConfig.interface.d.ts}

@@ -1,5 +1,6 @@
 import type { CoreApiAuthHeaders } from "@illalabs/interfaces";
-import type { HttpClientFactory } from "./types.js";
+import type { HttpClientFactory } from "../types.js";
+import type { CoreApiProviderRoutes } from "./CoreApiProviderRoutes.interface.js";
 /**
  * Core API provider configuration
  */
@@ -20,5 +21,9 @@ export interface CoreApiProviderConfig {
      * Optional factory used to create a configured axios instance. Primarily used for testing.
      */
     readonly httpClientFactory?: HttpClientFactory;
+    /**
+     * Optional overrides for API routes used by the provider.
+     */
+    readonly routes?: CoreApiProviderRoutes;
 }
-//# sourceMappingURL=CoreApiProviderConfig.d.ts.map
+//# sourceMappingURL=CoreApiProviderConfig.interface.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CoreApiProviderConfig.interface.d.ts","sourceRoot":"","sources":["../../../../../src/providers/coreApiProvider/interfaces/CoreApiProviderConfig.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAElF;;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;IAE/C;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;CAC3C"}

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

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

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

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

package/dist/src/providers/coreApiProvider/interfaces/CoreApiProviderRoutes.interface.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Optional route overrides used by the {@link CoreApiProvider}.
+ */
+export interface CoreApiProviderRoutes {
+    /**
+     * Path used when sending chat requests. Defaults to `/api/v1/chat/`.
+     */
+    readonly chat?: string;
+    /**
+     * Path used when polling asynchronous tool executions. Defaults to `/api/v1/actions/check`.
+     */
+    readonly actionStatus?: string;
+}
+//# sourceMappingURL=CoreApiProviderRoutes.interface.d.ts.map

package/dist/src/providers/coreApiProvider/interfaces/CoreApiProviderRoutes.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CoreApiProviderRoutes.interface.d.ts","sourceRoot":"","sources":["../../../../../src/providers/coreApiProvider/interfaces/CoreApiProviderRoutes.interface.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IAClC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAClC"}

package/dist/src/providers/coreApiProvider/interfaces/CoreApiProviderRoutes.interface.js

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

package/dist/src/providers/coreApiProvider/interfaces/CoreApiProviderRoutes.interface.js.map

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

package/dist/src/providers/coreApiProvider/interfaces/index.d.ts

@@ -0,0 +1,3 @@
+export type { CoreApiProviderRoutes } from "./CoreApiProviderRoutes.interface.js";
+export type { CoreApiProviderConfig } from "./CoreApiProviderConfig.interface.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/providers/coreApiProvider/interfaces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/providers/coreApiProvider/interfaces/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAClF,YAAY,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC"}

package/dist/src/providers/coreApiProvider/interfaces/index.js

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

package/dist/src/providers/coreApiProvider/interfaces/index.js.map

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

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

@@ -4,4 +4,13 @@ import type { AxiosInstance, AxiosRequestConfig } from "axios";
  * Kept separate to enable reuse in tests and other providers.
  */
 export type HttpClientFactory = (config?: AxiosRequestConfig) => AxiosInstance;
+/**
+ * Options for Core API requests
+ */
+export interface RequestOptions {
+    /**
+     * Abort signal used to cancel the request
+     */
+    readonly signal?: AbortSignal;
+}
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,CAAC,EAAE,kBAAkB,KAAK,aAAa,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/providers/coreApiProvider/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,OAAO,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,MAAM,CAAC,EAAE,kBAAkB,KAAK,aAAa,CAAC;AAE/E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;OAEG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CACjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illalabs/sdk",
-  "version": "0.0.0-dev-3-9cae6c3-20251024213833",
+  "version": "0.1.0-canary.48bfe253",
   "private": false,
   "description": "TypeScript SDK for interacting with Illa's Core API",
   "license": "MIT",
@@ -23,13 +23,16 @@
     "axios": "1.12.2",
     "uuid": "13.0.0",
     "viem": "2.37.13",
-    "@illalabs/interfaces": "0.0.0-dev-3-9cae6c3-20251024213833"
+    "@illalabs/interfaces": "0.1.0-canary.48bfe253"
+  },
+  "devDependencies": {
+    "zod": "4.1.12"
   },
   "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
+    "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",
@@ -38,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":""}