@illalabs/sdk 0.0.0 → 0.1.0-canary.9fc2c20f

package/LICENSE

@@ -1,6 +1,21 @@
 MIT License
 
-Copyright (c) 2025
+Copyright (c) 2025 Wonderland
+
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction...
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,258 @@
 # @illalabs/sdk
 
-Reserved package name. Actual code will be published in a later version.
+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
+
+The SDK provides a simple interface (`IllaSDK`) that handles all the complexity of managing chats, context, and API communication:
+
+```typescript
+import { IllaSDK } from "@illalabs/sdk";
+
+// Initialize the SDK with your API key
+const sdk = new IllaSDK({
+    apiKey: "your-api-key",
+});
+
+// Start a conversation
+const result = await sdk.sendMessage("What is my wallet balance on Base?", {
+    userContext: { address: "0x..." },
+});
+
+console.log("Response:", result.response.text);
+console.log("Chat ID:", result.chatId);
+```
+
+### Multi-turn Conversations
+
+Continue a conversation by passing the chat ID from previous messages:
+
+```typescript
+// Start a new conversation
+const result1 = await sdk.sendMessage("What can you help me with?", {
+    userContext: { address: "0x..." },
+});
+
+// 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,
+});
+```
+
+### Handling Tool Execution
+
+When the AI needs to execute blockchain operations, it will return pending tools:
+
+```typescript
+const result = await sdk.sendMessage("Swap 1 ETH for USDC on Base", {
+    userContext: { address: "0x..." },
+});
+
+// Check if there are tools to execute
+if (result.response.pendingTools && result.response.pendingTools.length > 0) {
+    const tool = result.response.pendingTools[0];
+
+    // Execute the tool (e.g., send a transaction)
+    const executionResult = await executeTool(tool);
+
+    // Send the result back to the AI
+    const toolResult = {
+        toolCallId: tool.toolCallId,
+        toolName: tool.toolName,
+        result: executionResult,
+    };
+
+    const followUp = await sdk.sendToolResult(result.chatId, toolResult);
+    console.log(followUp.response.text);
+}
+```
+
+## 🔧 Advanced Usage
+
+For more control over the SDK's behavior, you can directly instantiate and configure individual components:
+
+### Custom Cache and Context Manager
+
+```typescript
+import { ContextManager, IllaSDK, InMemoryCache } from "@illalabs/sdk";
+
+// Create a custom cache
+const cache = new InMemoryCache();
+
+// Initialize SDK with custom cache
+const sdk = new IllaSDK({ apiKey: "your-api-key" }, { cache });
+
+// Or create a custom context manager with specific configuration
+const contextManager = IllaSDK.createNewContextManager(cache, {
+    defaultToolsConfig: {
+        autoRouter: { swapOrBridge: "lifi" },
+    },
+});
+
+const customSdk = new IllaSDK({ apiKey: "your-api-key" }, { contextManager });
+```
+
+### Direct Component Usage
+
+For maximum flexibility, you can use the SDK components directly:
+
+```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 using Prompt
+const prompt = new Prompt({ text: "What is my wallet balance on Base?" });
+const result = await chat.sendMessage(prompt);
+
+console.log("Response:", result.response.text);
+```
+
+### Managing Multiple Chats
+
+```typescript
+import { IllaSDK } from "@illalabs/sdk";
+
+const sdk = new IllaSDK({ apiKey: "your-api-key" });
+
+// Create chat instances explicitly
+const chat1 = sdk.createChat({
+    userContext: { address: "0x123..." },
+});
+
+const chat2 = sdk.createChat({
+    userContext: { address: "0x456..." },
+    id: "custom-chat-id", // Optional: provide your own ID
+});
+
+// Get all active chat IDs
+const chatIds = sdk.chatIds;
+console.log("Active chats:", chatIds);
+```
+
+## 🧪 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/
+├── sdk.ts             # Main SDK facade (IllaSDK class)
+├── 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/asyncToolChecker/AsyncToolChecker.d.ts

@@ -0,0 +1,39 @@
+import type { AsyncCheckerEvents, AsyncToolCheckerCheckParams, AsyncToolCheckerOptions, EventSubscription, PollingConfig } from "../interfaces/index.js";
+import type { AwaitActionResult } from "./types.js";
+/**
+ * Provides high level tooling to monitor asynchronous Core API executions.
+ */
+export declare class AsyncToolChecker {
+    private readonly coreApiProvider;
+    /**
+     * Creates a new {@link AsyncToolChecker} instance.
+     *
+     * @param options Dependencies required to perform asynchronous checks.
+     */
+    constructor(options: AsyncToolCheckerOptions);
+    /**
+     * Retrieves the latest status for a specific tool execution.
+     *
+     * The method delegates the long polling request to the injected {@link ICoreApiProvider}
+     * and normalizes the resulting payload into an {@link AwaitActionResult} discriminated union
+     * to simplify downstream handling.
+     *
+     * @param params Parameters describing the tool execution to inspect.
+     *
+     * @returns Latest status returned by the Core API.
+     */
+    check(params: AsyncToolCheckerCheckParams): Promise<AwaitActionResult>;
+    /**
+     * Subscribes to status updates for a tool execution using a polling strategy.
+     *
+     * TODO: Implement polling orchestration and event dispatch once the execution
+     * checker workflow is defined.
+     *
+     * @param events Callback handlers invoked during the subscription lifecycle.
+     * @param pollingConfig Configuration that controls polling cadence and retries.
+     *
+     * @returns Subscription handle that allows callers to cancel the polling loop.
+     */
+    subscribe<TPayload, TError>(params: AsyncToolCheckerCheckParams, events: AsyncCheckerEvents<TPayload, TError>, pollingConfig: PollingConfig): EventSubscription;
+}
+//# sourceMappingURL=AsyncToolChecker.d.ts.map

package/dist/src/asyncToolChecker/AsyncToolChecker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncToolChecker.d.ts","sourceRoot":"","sources":["../../../src/asyncToolChecker/AsyncToolChecker.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACR,kBAAkB,EAClB,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EAEjB,aAAa,EAEhB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAIpD;;GAEG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmB;IAEnD;;;;OAIG;gBACgB,OAAO,EAAE,uBAAuB;IAInD;;;;;;;;;;OAUG;IACU,KAAK,CAAC,MAAM,EAAE,2BAA2B,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoBnF;;;;;;;;;;OAUG;IACI,SAAS,CAAC,QAAQ,EAAE,MAAM,EAC7B,MAAM,EAAE,2BAA2B,EACnC,MAAM,EAAE,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,EAC5C,aAAa,EAAE,aAAa,GAC7B,iBAAiB;CAqMvB"}

package/dist/src/asyncToolChecker/AsyncToolChecker.js

@@ -0,0 +1,209 @@
+import { AsyncToolCheckerMaxRetriesExceeded, AsyncToolCheckerTimeout } from "./errors/index.js";
+import { isErrorResponse, normalizeTimeout } from "./utils/index.js";
+/**
+ * Provides high level tooling to monitor asynchronous Core API executions.
+ */
+export class AsyncToolChecker {
+    coreApiProvider;
+    /**
+     * Creates a new {@link AsyncToolChecker} instance.
+     *
+     * @param options Dependencies required to perform asynchronous checks.
+     */
+    constructor(options) {
+        this.coreApiProvider = options.coreApiProvider;
+    }
+    /**
+     * Retrieves the latest status for a specific tool execution.
+     *
+     * The method delegates the long polling request to the injected {@link ICoreApiProvider}
+     * and normalizes the resulting payload into an {@link AwaitActionResult} discriminated union
+     * to simplify downstream handling.
+     *
+     * @param params Parameters describing the tool execution to inspect.
+     *
+     * @returns Latest status returned by the Core API.
+     */
+    async check(params) {
+        const response = await this.coreApiProvider.awaitTransaction({
+            toolName: params.toolName,
+            protocol: params.protocol,
+            args: params.descriptor,
+        });
+        if (isErrorResponse(response)) {
+            return {
+                isError: true,
+                error: response,
+            };
+        }
+        return {
+            isError: false,
+            response,
+        };
+    }
+    /**
+     * Subscribes to status updates for a tool execution using a polling strategy.
+     *
+     * TODO: Implement polling orchestration and event dispatch once the execution
+     * checker workflow is defined.
+     *
+     * @param events Callback handlers invoked during the subscription lifecycle.
+     * @param pollingConfig Configuration that controls polling cadence and retries.
+     *
+     * @returns Subscription handle that allows callers to cancel the polling loop.
+     */
+    subscribe(params, events, pollingConfig) {
+        const intervalMs = normalizeTimeout(pollingConfig.interval);
+        const retryThresholdMs = normalizeTimeout(pollingConfig.retryThreshold);
+        const maxRetries = Math.max(0, Math.floor(pollingConfig.maxRetries));
+        const maxDurationSeconds = Math.max(0, pollingConfig.maxDuration);
+        const maxDurationMs = maxDurationSeconds > 0 ? normalizeTimeout(maxDurationSeconds) : undefined;
+        let retries = 0;
+        let isActive = true;
+        let previous = null;
+        let pollingTimer;
+        let maxDurationTimer;
+        let inFlightController = null;
+        const clearTimer = (timer) => {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+        };
+        const finalize = (error, notifyError = error !== undefined) => {
+            if (!isActive) {
+                return;
+            }
+            isActive = false;
+            clearTimer(pollingTimer);
+            pollingTimer = undefined;
+            clearTimer(maxDurationTimer);
+            maxDurationTimer = undefined;
+            if (inFlightController !== null) {
+                inFlightController.abort();
+                inFlightController = null;
+            }
+            if (notifyError && error !== undefined) {
+                events.onError?.(error);
+            }
+        };
+        if (maxDurationMs !== undefined) {
+            maxDurationTimer = setTimeout(() => {
+                finalize(new AsyncToolCheckerTimeout(maxDurationSeconds));
+            }, maxDurationMs);
+        }
+        const emitStatus = (current) => {
+            if (!isActive) {
+                return false;
+            }
+            // Avoids duplicate notifications when no state transition occurred.
+            if (previous === current) {
+                return true;
+            }
+            const event = {
+                previous,
+                current,
+            };
+            try {
+                events.onStatusChange(event);
+            }
+            catch (handlerError) {
+                finalize(handlerError);
+                return false;
+            }
+            previous = current;
+            return true;
+        };
+        const scheduleNext = (delayMs) => {
+            if (!isActive) {
+                return;
+            }
+            clearTimer(pollingTimer);
+            pollingTimer = setTimeout(() => {
+                pollingTimer = undefined;
+                void tick();
+            }, delayMs);
+        };
+        const handleRetryableError = (error) => {
+            retries += 1;
+            if (retries > maxRetries) {
+                finalize(new AsyncToolCheckerMaxRetriesExceeded(maxRetries, error));
+                return;
+            }
+            scheduleNext(retryThresholdMs);
+        };
+        const handleSuccessResponse = (response) => {
+            retries = 0;
+            if (!emitStatus(response)) {
+                return;
+            }
+            if (response.pollStatus === "pending") {
+                scheduleNext(intervalMs);
+                return;
+            }
+            finalize();
+        };
+        /**
+         * Normalizes successful polling responses by preserving pending and completed states.
+         */
+        const normalizeSuccessResponse = (response) => {
+            if (response.pollStatus !== "failed") {
+                return response;
+            }
+            return {
+                ...response,
+                error: response.error,
+            };
+        };
+        const tick = async () => {
+            if (!isActive) {
+                return;
+            }
+            const controller = new AbortController();
+            inFlightController = controller;
+            let response;
+            try {
+                response = await this.coreApiProvider.awaitTransaction({
+                    toolName: params.toolName,
+                    protocol: params.protocol,
+                    args: params.descriptor,
+                }, { signal: controller.signal });
+            }
+            catch (error) {
+                if (!isActive) {
+                    return;
+                }
+                if (controller.signal.aborted) {
+                    finalize(undefined, false);
+                    return;
+                }
+                finalize(error);
+                return;
+            }
+            finally {
+                if (inFlightController === controller) {
+                    inFlightController = null;
+                }
+            }
+            if (!isActive) {
+                return;
+            }
+            if (isErrorResponse(response)) {
+                const statusCode = response.statusCode;
+                if (statusCode === 400 || statusCode === 429) {
+                    handleRetryableError(response);
+                    return;
+                }
+                finalize(response);
+                return;
+            }
+            handleSuccessResponse(normalizeSuccessResponse(response));
+        };
+        void tick();
+        return {
+            unsubscribe: () => {
+                finalize(undefined, false);
+            },
+        };
+    }
+}
+//# sourceMappingURL=AsyncToolChecker.js.map

package/dist/src/asyncToolChecker/AsyncToolChecker.js.map

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

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMaxRetriesExceeded.d.ts

@@ -0,0 +1,23 @@
+import type { LongPollingActionErrorResponse } from "@illalabs/interfaces";
+/**
+ * Error emitted when the async tool checker exhausts the configured retry attempts for recoverable errors.
+ */
+export declare class AsyncToolCheckerMaxRetriesExceeded extends Error {
+    /**
+     * Number of retry attempts that were configured.
+     */
+    readonly maxRetries: number;
+    /**
+     * Last error response received from the Core API.
+     */
+    readonly lastError: LongPollingActionErrorResponse;
+    /**
+     * Creates a new {@link AsyncToolCheckerMaxRetriesExceeded} instance.
+     *
+     * @param maxRetries Maximum number of retries allowed before failing.
+     * @param lastError Last error emitted by the Core API.
+     * @param options Error options.
+     */
+    constructor(maxRetries: number, lastError: LongPollingActionErrorResponse, options?: ErrorOptions);
+}
+//# sourceMappingURL=AsyncToolCheckerMaxRetriesExceeded.d.ts.map

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMaxRetriesExceeded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncToolCheckerMaxRetriesExceeded.d.ts","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/AsyncToolCheckerMaxRetriesExceeded.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AAE3E;;GAEG;AACH,qBAAa,kCAAmC,SAAQ,KAAK;IACzD;;OAEG;IACH,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC;;OAEG;IACH,SAAgB,SAAS,EAAE,8BAA8B,CAAC;IAE1D;;;;;;OAMG;gBAEC,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,8BAA8B,EACzC,OAAO,CAAC,EAAE,YAAY;CAU7B"}

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMaxRetriesExceeded.js

@@ -0,0 +1,30 @@
+/**
+ * Error emitted when the async tool checker exhausts the configured retry attempts for recoverable errors.
+ */
+export class AsyncToolCheckerMaxRetriesExceeded extends Error {
+    /**
+     * Number of retry attempts that were configured.
+     */
+    maxRetries;
+    /**
+     * Last error response received from the Core API.
+     */
+    lastError;
+    /**
+     * Creates a new {@link AsyncToolCheckerMaxRetriesExceeded} instance.
+     *
+     * @param maxRetries Maximum number of retries allowed before failing.
+     * @param lastError Last error emitted by the Core API.
+     * @param options Error options.
+     */
+    constructor(maxRetries, lastError, options) {
+        super(`Async tool checker exceeded maximum retry attempts (${maxRetries}).`, {
+            cause: lastError,
+            ...options,
+        });
+        this.name = "AsyncToolCheckerMaxRetriesExceeded";
+        this.maxRetries = maxRetries;
+        this.lastError = lastError;
+    }
+}
+//# sourceMappingURL=AsyncToolCheckerMaxRetriesExceeded.js.map

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMaxRetriesExceeded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncToolCheckerMaxRetriesExceeded.js","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/AsyncToolCheckerMaxRetriesExceeded.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,OAAO,kCAAmC,SAAQ,KAAK;IACzD;;OAEG;IACa,UAAU,CAAS;IAEnC;;OAEG;IACa,SAAS,CAAiC;IAE1D;;;;;;OAMG;IACH,YACI,UAAkB,EAClB,SAAyC,EACzC,OAAsB;QAEtB,KAAK,CAAC,uDAAuD,UAAU,IAAI,EAAE;YACzE,KAAK,EAAE,SAAS;YAChB,GAAG,OAAO;SACb,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,GAAG,oCAAoC,CAAC;QACjD,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC/B,CAAC;CACJ"}

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMethodNotImplemented.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error thrown when an {@link AsyncToolChecker} method is invoked prior to its implementation.
+ */
+export declare class AsyncToolCheckerMethodNotImplemented extends Error {
+    /**
+     * Additional context useful for debugging the method invocation.
+     */
+    readonly context?: unknown;
+    /**
+     * Creates a new {@link AsyncToolCheckerMethodNotImplemented} instance.
+     *
+     * @param methodName Name of the method that is not implemented.
+     * @param context Optional contextual information describing the invocation.
+     */
+    constructor(methodName: string, context?: unknown);
+}
+//# sourceMappingURL=AsyncToolCheckerMethodNotImplemented.d.ts.map

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMethodNotImplemented.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncToolCheckerMethodNotImplemented.d.ts","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/AsyncToolCheckerMethodNotImplemented.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,oCAAqC,SAAQ,KAAK;IAC3D;;OAEG;IACH,SAAgB,OAAO,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;OAKG;gBACgB,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO;CAU3D"}

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMethodNotImplemented.js

@@ -0,0 +1,26 @@
+/**
+ * Error thrown when an {@link AsyncToolChecker} method is invoked prior to its implementation.
+ */
+export class AsyncToolCheckerMethodNotImplemented extends Error {
+    /**
+     * Additional context useful for debugging the method invocation.
+     */
+    context;
+    /**
+     * Creates a new {@link AsyncToolCheckerMethodNotImplemented} instance.
+     *
+     * @param methodName Name of the method that is not implemented.
+     * @param context Optional contextual information describing the invocation.
+     */
+    constructor(methodName, context) {
+        super(`AsyncToolChecker method "${methodName}" is not implemented.`);
+        this.name = "AsyncToolCheckerMethodNotImplemented";
+        if (context !== undefined) {
+            Object.defineProperty(this, "context", {
+                value: context,
+                enumerable: true,
+            });
+        }
+    }
+}
+//# sourceMappingURL=AsyncToolCheckerMethodNotImplemented.js.map

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerMethodNotImplemented.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncToolCheckerMethodNotImplemented.js","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/AsyncToolCheckerMethodNotImplemented.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,oCAAqC,SAAQ,KAAK;IAC3D;;OAEG;IACa,OAAO,CAAW;IAElC;;;;;OAKG;IACH,YAAmB,UAAkB,EAAE,OAAiB;QACpD,KAAK,CAAC,4BAA4B,UAAU,uBAAuB,CAAC,CAAC;QACrE,IAAI,CAAC,IAAI,GAAG,sCAAsC,CAAC;QACnD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE;gBACnC,KAAK,EAAE,OAAO;gBACd,UAAU,EAAE,IAAI;aACnB,CAAC,CAAC;QACP,CAAC;IACL,CAAC;CACJ"}

package/dist/src/asyncToolChecker/errors/AsyncToolCheckerTimeout.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error emitted when an asynchronous polling operation exceeds the configured maximum duration.
+ */
+export declare class AsyncToolCheckerTimeout extends Error {
+    /**
+     * Maximum duration, expressed in seconds, that was exceeded.
+     */
+    readonly maxDuration: number;
+    /**
+     * Creates a new {@link AsyncToolCheckerTimeout} instance.
+     *
+     * @param maxDuration Maximum duration, in seconds, permitted for the polling loop.
+     * @param options Error options.
+     */
+    constructor(maxDuration: number, options?: ErrorOptions);
+}
+//# sourceMappingURL=AsyncToolCheckerTimeout.d.ts.map