@jack-kernel/sdk 1.0.0

package/dist/esm/agent.js

@@ -0,0 +1,317 @@
+/**
+ * Agent utilities for the JACK SDK
+ *
+ * This module provides the AgentUtils class with high-level abstractions
+ * for batch operations, dry-run validation, policy enforcement, and
+ * event subscriptions for automated agent systems.
+ *
+ * Requirements: 8.1, 8.2, 8.3, 8.4, 8.5
+ */
+import { IntentManager } from './intents.js';
+import { ExecutionTracker } from './execution.js';
+import { validateIntentParams } from './validation.js';
+/**
+ * Utilities for agent-based intent orchestration
+ *
+ * Provides batch operations, dry-run validation, policy enforcement,
+ * and multi-intent subscriptions for automated systems.
+ *
+ * @example
+ * ```typescript
+ * const client = new JackClient({ baseUrl: 'https://api.jack.example' });
+ * const agent = new AgentUtils(client);
+ *
+ * // Batch submit multiple intents
+ * const results = await agent.batchSubmit([
+ *   { params: intent1, signature: sig1 },
+ *   { params: intent2, signature: sig2 }
+ * ]);
+ *
+ * results.forEach(result => {
+ *   if (result.success) {
+ *     console.log('Submitted:', result.intentId);
+ *   } else {
+ *     console.error('Failed:', result.error);
+ *   }
+ * });
+ * ```
+ */
+export class AgentUtils {
+    client;
+    intentManager;
+    executionTracker;
+    /**
+     * Creates a new AgentUtils instance
+     *
+     * @param client - The JackClient instance to use for API requests
+     */
+    constructor(client) {
+        this.client = client;
+        this.intentManager = new IntentManager(client);
+        this.executionTracker = new ExecutionTracker(client);
+    }
+    /**
+     * Submit multiple intents in parallel
+     *
+     * Uses Promise.allSettled() to submit all intents concurrently,
+     * ensuring that failures in individual submissions don't affect others.
+     * The result array length always matches the input array length,
+     * with each result corresponding to the same index in the input.
+     *
+     * @param intents - Array of intent parameters and signatures to submit
+     * @returns Promise resolving to array of BatchSubmitResult objects
+     *
+     * @example
+     * ```typescript
+     * const results = await agent.batchSubmit([
+     *   { params: intent1, signature: sig1 },
+     *   { params: intent2, signature: sig2 },
+     *   { params: intent3, signature: sig3 }
+     * ]);
+     *
+     * // Results array has same length as input
+     * console.log(results.length); // 3
+     *
+     * // Check individual results
+     * results.forEach((result, index) => {
+     *   if (result.success) {
+     *     console.log(`Intent ${index} submitted: ${result.intentId}`);
+     *   } else {
+     *     console.error(`Intent ${index} failed:`, result.error?.message);
+     *   }
+     * });
+     *
+     * // Count successes and failures
+     * const successes = results.filter(r => r.success).length;
+     * const failures = results.filter(r => !r.success).length;
+     * console.log(`${successes} succeeded, ${failures} failed`);
+     * ```
+     *
+     * **Validates: Requirements 8.1, 8.2**
+     */
+    async batchSubmit(intents) {
+        // Submit all intents in parallel using Promise.allSettled
+        // This ensures all submissions are attempted regardless of individual failures
+        const promises = intents.map(async ({ params, signature }) => {
+            return this.intentManager.submit(params, signature);
+        });
+        const results = await Promise.allSettled(promises);
+        // Transform PromiseSettledResult to BatchSubmitResult
+        // Ensure result array length matches input array length
+        return results.map((result, index) => {
+            if (result.status === 'fulfilled') {
+                return {
+                    intentId: result.value,
+                    success: true
+                };
+            }
+            else {
+                return {
+                    intentId: '', // Empty string for failed submissions
+                    success: false,
+                    error: result.reason instanceof Error ? result.reason : new Error(String(result.reason))
+                };
+            }
+        });
+    }
+    /**
+     * Simulate intent execution without submission
+     *
+     * Validates intent parameters and estimates costs without actually
+     * submitting the intent to the API. Useful for testing and validation.
+     *
+     * @param params - Intent parameters to validate
+     * @returns Promise resolving to DryRunResult with validation status
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.dryRun(params);
+     * if (result.valid) {
+     *   console.log('Estimated cost:', result.estimatedCost);
+     * } else {
+     *   console.error('Validation errors:', result.errors);
+     * }
+     * ```
+     *
+     * **Validates: Requirement 8.4**
+     */
+    async dryRun(params) {
+        const validation = validateIntentParams(params);
+        if (!validation.valid) {
+            return {
+                valid: false,
+                errors: validation.errors
+            };
+        }
+        // In a real implementation, this might call an API endpoint
+        // to get cost estimates. For now, we just return validation status.
+        return {
+            valid: true,
+            estimatedCost: undefined, // Could be populated by API call
+            errors: []
+        };
+    }
+    /**
+     * Validate intent parameters against policy rules
+     *
+     * Checks that intent parameters comply with the specified policy,
+     * including amount limits, allowed chains, tokens, and deadline constraints.
+     *
+     * @param params - Intent parameters to validate
+     * @param policy - Policy rules to enforce
+     * @returns ValidationResult with valid flag and error messages
+     *
+     * @example
+     * ```typescript
+     * const policy: Policy = {
+     *   maxAmountIn: '1000000000',
+     *   allowedSourceChains: ['arbitrum', 'optimism'],
+     *   allowedDestinationChains: ['base', 'ethereum'],
+     *   maxDeadlineOffset: 3600000 // 1 hour
+     * };
+     *
+     * const result = agent.validatePolicy(params, policy);
+     * if (!result.valid) {
+     *   console.error('Policy violations:', result.errors);
+     * }
+     * ```
+     *
+     * **Validates: Requirement 8.5**
+     */
+    validatePolicy(params, policy) {
+        const errors = [];
+        // Check maximum amount in
+        if (policy.maxAmountIn !== undefined) {
+            const maxAmount = BigInt(policy.maxAmountIn);
+            const amount = BigInt(params.amountIn);
+            if (amount > maxAmount) {
+                errors.push(`Amount in ${params.amountIn} exceeds maximum ${policy.maxAmountIn}`);
+            }
+        }
+        // Check minimum amount out
+        if (policy.minAmountOut !== undefined) {
+            const minAmount = BigInt(policy.minAmountOut);
+            const amount = BigInt(params.minAmountOut);
+            if (amount < minAmount) {
+                errors.push(`Minimum amount out ${params.minAmountOut} is below policy minimum ${policy.minAmountOut}`);
+            }
+        }
+        // Check allowed source chains
+        if (policy.allowedSourceChains !== undefined) {
+            if (!policy.allowedSourceChains.includes(params.sourceChain)) {
+                errors.push(`Source chain ${params.sourceChain} is not in allowed list: ${policy.allowedSourceChains.join(', ')}`);
+            }
+        }
+        // Check allowed destination chains
+        if (policy.allowedDestinationChains !== undefined) {
+            if (!policy.allowedDestinationChains.includes(params.destinationChain)) {
+                errors.push(`Destination chain ${params.destinationChain} is not in allowed list: ${policy.allowedDestinationChains.join(', ')}`);
+            }
+        }
+        // Check allowed input tokens
+        if (policy.allowedTokensIn !== undefined) {
+            if (!policy.allowedTokensIn.includes(params.tokenIn)) {
+                errors.push(`Input token ${params.tokenIn} is not in allowed list`);
+            }
+        }
+        // Check allowed output tokens
+        if (policy.allowedTokensOut !== undefined) {
+            if (!policy.allowedTokensOut.includes(params.tokenOut)) {
+                errors.push(`Output token ${params.tokenOut} is not in allowed list`);
+            }
+        }
+        // Check maximum deadline offset
+        if (policy.maxDeadlineOffset !== undefined) {
+            const now = Date.now();
+            const deadlineOffset = params.deadline - now;
+            if (deadlineOffset > policy.maxDeadlineOffset) {
+                errors.push(`Deadline offset ${deadlineOffset}ms exceeds maximum ${policy.maxDeadlineOffset}ms`);
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+    /**
+     * Subscribe to status changes for multiple intents
+     *
+     * Polls multiple intents in parallel and invokes the callback whenever
+     * any intent's status changes. Returns a Subscription object that can
+     * be used to unsubscribe and stop polling.
+     *
+     * @param intentIds - Array of intent IDs to monitor
+     * @param callback - Function to call when any intent status changes
+     * @param options - Polling options (interval, timeout)
+     * @returns Subscription object with unsubscribe() method
+     *
+     * @example
+     * ```typescript
+     * const subscription = agent.subscribeToUpdates(
+     *   ['JK-ABC123456', 'JK-DEF789012'],
+     *   (intentId, intent) => {
+     *     console.log(`${intentId} status changed to ${intent.status}`);
+     *   },
+     *   { interval: 5000 }
+     * );
+     *
+     * // Later, stop polling
+     * subscription.unsubscribe();
+     * ```
+     *
+     * **Validates: Requirement 8.3**
+     */
+    subscribeToUpdates(intentIds, callback, options) {
+        const interval = options?.interval ?? 2000;
+        const timeout = options?.timeout;
+        const startTime = Date.now();
+        // Track last known status for each intent
+        const lastStatuses = new Map();
+        let intervalId = null;
+        let stopped = false;
+        const poll = async () => {
+            if (stopped)
+                return;
+            // Check timeout
+            if (timeout && Date.now() - startTime > timeout) {
+                stopped = true;
+                if (intervalId)
+                    clearInterval(intervalId);
+                return;
+            }
+            // Poll all intents in parallel
+            const promises = intentIds.map(async (intentId) => {
+                try {
+                    const intent = await this.intentManager.get(intentId);
+                    // Check if status changed
+                    const lastStatus = lastStatuses.get(intentId);
+                    if (lastStatus !== intent.status) {
+                        lastStatuses.set(intentId, intent.status);
+                        callback(intentId, intent);
+                    }
+                }
+                catch (error) {
+                    // Silently ignore errors in polling
+                    // In a production implementation, might want to expose error callbacks
+                }
+            });
+            await Promise.allSettled(promises);
+        };
+        // Start polling
+        intervalId = setInterval(poll, interval);
+        // Do initial poll
+        poll().catch(() => {
+            // Ignore initial poll errors
+        });
+        return {
+            unsubscribe() {
+                stopped = true;
+                if (intervalId) {
+                    clearInterval(intervalId);
+                    intervalId = null;
+                }
+            }
+        };
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/esm/agent.js.map

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

package/dist/esm/cache.js

@@ -0,0 +1,54 @@
+/**
+ * Simple in-memory cache with TTL support
+ */
+export class Cache {
+    store = new Map();
+    defaultTTL;
+    constructor(defaultTTL = 60000) {
+        this.defaultTTL = defaultTTL;
+    }
+    /**
+     * Get value from cache if not expired
+     */
+    get(key) {
+        const entry = this.store.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.store.delete(key);
+            return null;
+        }
+        return entry.value;
+    }
+    /**
+     * Set value in cache with TTL
+     */
+    set(key, value, ttl) {
+        const expiresAt = Date.now() + (ttl ?? this.defaultTTL);
+        this.store.set(key, { value, expiresAt });
+    }
+    /**
+     * Clear cache entries matching pattern
+     */
+    clear(pattern) {
+        if (!pattern) {
+            this.store.clear();
+            return;
+        }
+        const regex = new RegExp(pattern);
+        for (const key of this.store.keys()) {
+            if (regex.test(key)) {
+                this.store.delete(key);
+            }
+        }
+    }
+    /**
+     * Get cache size
+     */
+    size() {
+        return this.store.size;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/esm/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,OAAO,KAAK;IACR,KAAK,GAA4B,IAAI,GAAG,EAAE,CAAC;IAClC,UAAU,CAAS;IAEpC,YAAY,aAAqB,KAAK;QACpC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED;;OAEG;IACH,GAAG,CAAI,GAAW;QAChB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,IAAI,CAAC;QACd,CAAC;QAED,mBAAmB;QACnB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,KAAK,CAAC,KAAU,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,GAAG,CAAI,GAAW,EAAE,KAAQ,EAAE,GAAY;QACxC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC;QACxD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,OAAgB;QACpB,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACnB,OAAO;QACT,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC;QAClC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACzB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/esm/client.js

@@ -0,0 +1,192 @@
+import { NetworkError, APIError, ValidationError, TimeoutError, RetryError } from './errors.js';
+import { Cache } from './cache.js';
+/**
+ * Core HTTP client for JACK API with retry logic, timeout handling, and caching
+ */
+export class JackClient {
+    config;
+    cache;
+    constructor(config) {
+        this.validateConfig(config);
+        this.config = {
+            baseUrl: config.baseUrl,
+            timeout: config.timeout ?? 30000,
+            maxRetries: config.maxRetries ?? 3,
+            retryDelay: config.retryDelay ?? 1000,
+            retryBackoff: config.retryBackoff ?? 2,
+            enableCache: config.enableCache ?? true,
+            cacheTTL: config.cacheTTL ?? 60000,
+            headers: config.headers ?? {},
+        };
+        this.cache = new Cache(this.config.cacheTTL);
+    }
+    /**
+     * Validate client configuration
+     */
+    validateConfig(config) {
+        const errors = [];
+        if (!config.baseUrl || config.baseUrl.trim() === '') {
+            errors.push('baseUrl is required and cannot be empty');
+        }
+        if (config.timeout !== undefined && config.timeout <= 0) {
+            errors.push('timeout must be positive');
+        }
+        if (config.maxRetries !== undefined && config.maxRetries < 0) {
+            errors.push('maxRetries cannot be negative');
+        }
+        if (config.retryDelay !== undefined && config.retryDelay < 0) {
+            errors.push('retryDelay cannot be negative');
+        }
+        if (config.retryBackoff !== undefined && config.retryBackoff < 1) {
+            errors.push('retryBackoff must be >= 1');
+        }
+        if (config.cacheTTL !== undefined && config.cacheTTL < 0) {
+            errors.push('cacheTTL cannot be negative');
+        }
+        if (errors.length > 0) {
+            throw new ValidationError('Invalid client configuration', errors);
+        }
+    }
+    /**
+     * Perform GET request with caching support
+     */
+    async get(path, options) {
+        const cacheKey = this.getCacheKey(path, options);
+        // Check cache if enabled
+        if (this.config.enableCache && !options?.skipCache) {
+            const cached = this.cache.get(cacheKey);
+            if (cached !== null) {
+                return cached;
+            }
+        }
+        // Execute request with retry
+        const result = await this.executeWithRetry(() => this.executeRequest('GET', path, undefined, options));
+        // Cache successful GET responses
+        if (this.config.enableCache && !options?.skipCache) {
+            this.cache.set(cacheKey, result);
+        }
+        return result;
+    }
+    /**
+     * Perform POST request (never cached)
+     */
+    async post(path, body, options) {
+        return this.executeWithRetry(() => this.executeRequest('POST', path, body, options));
+    }
+    /**
+     * Clear cache entries matching pattern
+     */
+    clearCache(pattern) {
+        this.cache.clear(pattern);
+    }
+    /**
+     * Generate cache key from URL and options
+     */
+    getCacheKey(path, options) {
+        const params = options?.params ? JSON.stringify(options.params) : '';
+        return `${path}${params}`;
+    }
+    /**
+     * Execute HTTP request with timeout
+     */
+    async executeRequest(method, path, body, options) {
+        const url = `${this.config.baseUrl}${path}`;
+        const timeout = options?.timeout ?? this.config.timeout;
+        // Create abort controller for timeout
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+            const headers = {
+                'Content-Type': 'application/json',
+                ...this.config.headers,
+                ...options?.headers,
+            };
+            const response = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let errorMessage;
+                try {
+                    const errorJson = JSON.parse(errorBody);
+                    errorMessage = errorJson.message || errorJson.error || response.statusText;
+                }
+                catch {
+                    errorMessage = errorBody || response.statusText;
+                }
+                throw new APIError(errorMessage, response.status, errorBody);
+            }
+            const data = await response.json();
+            return data;
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof APIError) {
+                throw error;
+            }
+            if (error instanceof Error) {
+                if (error.name === 'AbortError') {
+                    throw new TimeoutError(`Request timed out after ${timeout}ms`, timeout);
+                }
+                throw new NetworkError(`Network request failed: ${error.message}`, error);
+            }
+            throw new NetworkError('Unknown network error', new Error(String(error)));
+        }
+    }
+    /**
+     * Execute function with retry logic and exponential backoff
+     */
+    async executeWithRetry(fn) {
+        let lastError = null;
+        let delay = this.config.retryDelay;
+        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (error) {
+                lastError = error;
+                // Don't retry on non-retryable errors - throw immediately
+                if (error instanceof APIError && !this.isRetryable(error)) {
+                    throw error;
+                }
+                if (error instanceof ValidationError) {
+                    throw error;
+                }
+                if (error instanceof TimeoutError) {
+                    throw error;
+                }
+                // Don't retry if we've exhausted attempts
+                if (attempt === this.config.maxRetries) {
+                    // If maxRetries is 0, throw the original error, not RetryError
+                    if (this.config.maxRetries === 0) {
+                        throw error;
+                    }
+                    break;
+                }
+                // Wait before retrying
+                await this.sleep(delay);
+                delay *= this.config.retryBackoff;
+            }
+        }
+        // All retries exhausted
+        throw new RetryError(`Request failed after ${this.config.maxRetries + 1} attempts`, this.config.maxRetries + 1, lastError);
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(error) {
+        // Retry on 5xx server errors and 429 rate limit
+        return error.statusCode >= 500 || error.statusCode === 429;
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/client.js.map

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