@illalabs/sdk 0.0.0 → 0.1.0

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/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

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

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncToolCheckerTimeout.d.ts","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/AsyncToolCheckerTimeout.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAC9C;;OAEG;IACH,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;;;;OAKG;gBACgB,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKjE"}

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

@@ -0,0 +1,21 @@
+/**
+ * Error emitted when an asynchronous polling operation exceeds the configured maximum duration.
+ */
+export class AsyncToolCheckerTimeout extends Error {
+    /**
+     * Maximum duration, expressed in seconds, that was exceeded.
+     */
+    maxDuration;
+    /**
+     * Creates a new {@link AsyncToolCheckerTimeout} instance.
+     *
+     * @param maxDuration Maximum duration, in seconds, permitted for the polling loop.
+     * @param options Error options.
+     */
+    constructor(maxDuration, options) {
+        super(`Async tool checker exceeded maximum duration of ${maxDuration} seconds.`, options);
+        this.name = "AsyncToolCheckerTimeout";
+        this.maxDuration = maxDuration;
+    }
+}
+//# sourceMappingURL=AsyncToolCheckerTimeout.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AsyncToolCheckerTimeout.js","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/AsyncToolCheckerTimeout.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAC9C;;OAEG;IACa,WAAW,CAAS;IAEpC;;;;;OAKG;IACH,YAAmB,WAAmB,EAAE,OAAsB;QAC1D,KAAK,CAAC,mDAAmD,WAAW,WAAW,EAAE,OAAO,CAAC,CAAC;QAC1F,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACnC,CAAC;CACJ"}

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

@@ -0,0 +1,4 @@
+export { AsyncToolCheckerMethodNotImplemented } from "./AsyncToolCheckerMethodNotImplemented.js";
+export { AsyncToolCheckerTimeout } from "./AsyncToolCheckerTimeout.js";
+export { AsyncToolCheckerMaxRetriesExceeded } from "./AsyncToolCheckerMaxRetriesExceeded.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oCAAoC,EAAE,MAAM,2CAA2C,CAAC;AACjG,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,kCAAkC,EAAE,MAAM,yCAAyC,CAAC"}

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

@@ -0,0 +1,4 @@
+export { AsyncToolCheckerMethodNotImplemented } from "./AsyncToolCheckerMethodNotImplemented.js";
+export { AsyncToolCheckerTimeout } from "./AsyncToolCheckerTimeout.js";
+export { AsyncToolCheckerMaxRetriesExceeded } from "./AsyncToolCheckerMaxRetriesExceeded.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/asyncToolChecker/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oCAAoC,EAAE,MAAM,2CAA2C,CAAC;AACjG,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,kCAAkC,EAAE,MAAM,yCAAyC,CAAC"}

package/dist/src/asyncToolChecker/index.d.ts

@@ -0,0 +1,6 @@
+export { AsyncToolChecker } from "./AsyncToolChecker.js";
+export type { AsyncCheckerEvents, AsyncToolCheckerCheckParams, AsyncToolCheckerOptions, EventSubscription, PollingConfig, StatusChangedEvent, } from "../interfaces/index.js";
+export { AsyncToolCheckerMaxRetriesExceeded, AsyncToolCheckerMethodNotImplemented, AsyncToolCheckerTimeout, } from "./errors/index.js";
+export * from "./types.js";
+export * from "./utils/index.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/asyncToolChecker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EACR,kBAAkB,EAClB,2BAA2B,EAC3B,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,kBAAkB,GACrB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACH,kCAAkC,EAClC,oCAAoC,EACpC,uBAAuB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}

package/dist/src/asyncToolChecker/index.js

@@ -0,0 +1,5 @@
+export { AsyncToolChecker } from "./AsyncToolChecker.js";
+export { AsyncToolCheckerMaxRetriesExceeded, AsyncToolCheckerMethodNotImplemented, AsyncToolCheckerTimeout, } from "./errors/index.js";
+export * from "./types.js";
+export * from "./utils/index.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/asyncToolChecker/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AASzD,OAAO,EACH,kCAAkC,EAClC,oCAAoC,EACpC,uBAAuB,GAC1B,MAAM,mBAAmB,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC"}

package/dist/src/asyncToolChecker/types.d.ts

@@ -0,0 +1,24 @@
+import type { ActionStatus, BaseLongPollingArgs, LongPollingActionErrorResponse, LongPollingActionParams } from "@illalabs/interfaces";
+/**
+ * Descriptor containing parameters for an action whose execution can be awaited.
+ */
+export type AwaitableActionDescriptor<T extends BaseLongPollingArgs = BaseLongPollingArgs> = LongPollingActionParams<T>;
+/**
+ * Successful result emitted after awaiting a long running tool execution.
+ */
+export type AwaitActionSuccess<TPayload = unknown, TError = unknown> = {
+    readonly isError: false;
+    readonly response: ActionStatus<TPayload, TError>;
+};
+/**
+ * Error result emitted when awaiting a long running tool execution fails.
+ */
+export type AwaitActionFailure = {
+    readonly isError: true;
+    readonly error: LongPollingActionErrorResponse;
+};
+/**
+ * Discriminated union representing the result of awaiting a long running tool execution.
+ */
+export type AwaitActionResult<TPayload = unknown, TError = unknown> = AwaitActionSuccess<TPayload, TError> | AwaitActionFailure;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/asyncToolChecker/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,YAAY,EACZ,mBAAmB,EACnB,8BAA8B,EAC9B,uBAAuB,EAC1B,MAAM,sBAAsB,CAAC;AAE9B;;GAEG;AACH,MAAM,MAAM,yBAAyB,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB,IACrF,uBAAuB,CAAC,CAAC,CAAC,CAAC;AAE/B;;GAEG;AACH,MAAM,MAAM,kBAAkB,CAAC,QAAQ,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI;IACnE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;CACrD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC7B,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,8BAA8B,CAAC;CAClD,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,QAAQ,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,IAC5D,kBAAkB,CAAC,QAAQ,EAAE,MAAM,CAAC,GACpC,kBAAkB,CAAC"}

package/dist/src/asyncToolChecker/types.js

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

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

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

package/dist/src/asyncToolChecker/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { isErrorResponse } from "./isErrorResponse.js";
+export { normalizeTimeout } from "./normalizeTimeout.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/asyncToolChecker/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/asyncToolChecker/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/asyncToolChecker/utils/index.js

@@ -0,0 +1,3 @@
+export { isErrorResponse } from "./isErrorResponse.js";
+export { normalizeTimeout } from "./normalizeTimeout.js";
+//# sourceMappingURL=index.js.map

package/dist/src/asyncToolChecker/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/asyncToolChecker/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/src/asyncToolChecker/utils/isErrorResponse.d.ts

@@ -0,0 +1,11 @@
+import type { LongPollingActionErrorResponse, LongPollingActionResponse } from "@illalabs/interfaces";
+/**
+ * Type guard to determine if a long polling response represents an error state.
+ *
+ * @typeParam TPayload - Payload type associated with successful responses.
+ * @param response Response from the Core API long polling endpoint.
+ *
+ * @returns True if the response contains an error, false otherwise.
+ */
+export declare function isErrorResponse<TPayload = unknown>(response: LongPollingActionResponse<TPayload>): response is LongPollingActionErrorResponse;
+//# sourceMappingURL=isErrorResponse.d.ts.map

package/dist/src/asyncToolChecker/utils/isErrorResponse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isErrorResponse.d.ts","sourceRoot":"","sources":["../../../../src/asyncToolChecker/utils/isErrorResponse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,8BAA8B,EAC9B,yBAAyB,EAC5B,MAAM,sBAAsB,CAAC;AAE9B;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,QAAQ,GAAG,OAAO,EAC9C,QAAQ,EAAE,yBAAyB,CAAC,QAAQ,CAAC,GAC9C,QAAQ,IAAI,8BAA8B,CAE5C"}

package/dist/src/asyncToolChecker/utils/isErrorResponse.js

@@ -0,0 +1,12 @@
+/**
+ * Type guard to determine if a long polling response represents an error state.
+ *
+ * @typeParam TPayload - Payload type associated with successful responses.
+ * @param response Response from the Core API long polling endpoint.
+ *
+ * @returns True if the response contains an error, false otherwise.
+ */
+export function isErrorResponse(response) {
+    return response.statusCode !== undefined;
+}
+//# sourceMappingURL=isErrorResponse.js.map

package/dist/src/asyncToolChecker/utils/isErrorResponse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"isErrorResponse.js","sourceRoot":"","sources":["../../../../src/asyncToolChecker/utils/isErrorResponse.ts"],"names":[],"mappings":"AAKA;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC3B,QAA6C;IAE7C,OAAQ,QAA2C,CAAC,UAAU,KAAK,SAAS,CAAC;AACjF,CAAC"}

package/dist/src/asyncToolChecker/utils/normalizeTimeout.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalizes a timeout value expressed in seconds.
+ *
+ * @param value Timeout expressed in seconds.
+ *
+ * @returns Timeout converted to milliseconds. Values less than zero are coerced to zero.
+ */
+export declare function normalizeTimeout(value: number): number;
+//# sourceMappingURL=normalizeTimeout.d.ts.map

package/dist/src/asyncToolChecker/utils/normalizeTimeout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeTimeout.d.ts","sourceRoot":"","sources":["../../../../src/asyncToolChecker/utils/normalizeTimeout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMtD"}

package/dist/src/asyncToolChecker/utils/normalizeTimeout.js

@@ -0,0 +1,14 @@
+/**
+ * Normalizes a timeout value expressed in seconds.
+ *
+ * @param value Timeout expressed in seconds.
+ *
+ * @returns Timeout converted to milliseconds. Values less than zero are coerced to zero.
+ */
+export function normalizeTimeout(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.max(0, value) * 1000;
+}
+//# sourceMappingURL=normalizeTimeout.js.map

package/dist/src/asyncToolChecker/utils/normalizeTimeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeTimeout.js","sourceRoot":"","sources":["../../../../src/asyncToolChecker/utils/normalizeTimeout.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,CAAC,CAAC;IACb,CAAC;IAED,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,IAAI,CAAC;AACrC,CAAC"}

package/dist/src/caching/InMemoryCache.d.ts

@@ -0,0 +1,14 @@
+import type { CacheEntryOptions, ICache } from "../interfaces/cache.interface.js";
+/**
+ * Default cache implementation that keeps values in memory.
+ */
+export declare class InMemoryCache implements ICache {
+    private readonly store;
+    /** @inheritdoc */
+    get<TValue>(key: string): Promise<TValue | undefined>;
+    /** @inheritdoc */
+    set(key: string, value: unknown, options?: CacheEntryOptions): Promise<void>;
+    /** @inheritdoc */
+    del(key: string): Promise<void>;
+}
+//# sourceMappingURL=InMemoryCache.d.ts.map