@nordsym/apiclaw 1.5.16 → 1.5.18

package/dist/src/capability-router.js

@@ -1,240 +0,0 @@
-/**
- * APIClaw Capability Router
- * Routes capability requests to the best available provider
- */
-import { executeAPICall } from './execute.js';
-import { logAPICall } from './analytics.js';
-// Convex HTTP API for capability queries
-const CONVEX_URL = process.env.NEXT_PUBLIC_CONVEX_URL || 'https://adventurous-avocet-799.convex.cloud';
-/**
- * Query Convex for providers that support a capability
- */
-async function getProvidersForCapability(capabilityId, region) {
-    try {
-        const res = await fetch(`${CONVEX_URL}/api/query`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                path: 'capabilities:getProviders',
-                args: { capabilityId, region },
-            }),
-        });
-        if (!res.ok)
-            return [];
-        const data = await res.json();
-        if (Array.isArray(data))
-            return data;
-        return (data.value || []);
-    }
-    catch (e) {
-        console.error('Failed to fetch capability providers:', e);
-        return [];
-    }
-}
-/**
- * Map capability params to provider-specific params
- */
-function mapParams(params, mapping) {
-    const result = {};
-    for (const [capParam, value] of Object.entries(params)) {
-        const providerParam = mapping[capParam] || capParam;
-        result[providerParam] = value;
-    }
-    return result;
-}
-/**
- * Log capability usage to Convex
- */
-async function logCapabilityUsage(params) {
-    try {
-        await fetch(`${CONVEX_URL}/api/mutation`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                path: 'capabilities:logUsage',
-                args: params,
-            }),
-        });
-    }
-    catch (e) {
-        console.error('Failed to log capability usage:', e);
-    }
-}
-/**
- * Execute a capability request with automatic provider selection and fallback
- */
-export async function executeCapability(capabilityId, action, params, userId, preferences = {}) {
-    const startTime = Date.now();
-    const enableFallback = preferences.fallback !== false; // Default true
-    // Get providers for this capability
-    const providers = await getProvidersForCapability(capabilityId, preferences.region);
-    if (providers.length === 0) {
-        return {
-            success: false,
-            capability: capabilityId,
-            action,
-            fallbackAttempted: false,
-            error: `No providers available for capability: ${capabilityId}`,
-        };
-    }
-    // Filter by max price if specified
-    let filteredProviders = providers;
-    if (preferences.maxPrice !== undefined) {
-        filteredProviders = providers.filter(p => p.pricePerUnit <= preferences.maxPrice);
-    }
-    // Prefer specific provider if requested
-    if (preferences.preferredProvider) {
-        const preferred = filteredProviders.find(p => p.providerId === preferences.preferredProvider);
-        if (preferred) {
-            filteredProviders = [preferred, ...filteredProviders.filter(p => p.providerId !== preferences.preferredProvider)];
-        }
-    }
-    if (filteredProviders.length === 0) {
-        return {
-            success: false,
-            capability: capabilityId,
-            action,
-            fallbackAttempted: false,
-            error: 'No providers match your preferences (region/price)',
-        };
-    }
-    // Try providers in order
-    let fallbackAttempted = false;
-    let lastError = '';
-    for (let i = 0; i < filteredProviders.length; i++) {
-        const provider = filteredProviders[i];
-        const isFirstAttempt = i === 0;
-        if (!isFirstAttempt) {
-            fallbackAttempted = true;
-        }
-        try {
-            // Map params to provider-specific format
-            const mappedParams = mapParams(params, provider.paramMapping || {});
-            // Execute via existing executeAPICall
-            const result = await executeAPICall(provider.providerId, action, mappedParams, userId);
-            const latencyMs = Date.now() - startTime;
-            if (result.success) {
-                // Log successful usage
-                logCapabilityUsage({
-                    capabilityId,
-                    providerId: provider.providerId,
-                    userId,
-                    action,
-                    success: true,
-                    fallbackUsed: fallbackAttempted,
-                    fallbackReason: fallbackAttempted ? lastError : undefined,
-                    latencyMs,
-                    cost: provider.pricePerUnit,
-                    currency: provider.currency,
-                });
-                // Also log to file-based analytics
-                logAPICall({
-                    timestamp: new Date().toISOString(),
-                    provider: provider.providerId,
-                    action,
-                    type: 'direct',
-                    userId,
-                    success: true,
-                    latencyMs,
-                });
-                return {
-                    success: true,
-                    capability: capabilityId,
-                    action,
-                    providerUsed: provider.providerId,
-                    fallbackAttempted,
-                    fallbackReason: fallbackAttempted ? lastError : undefined,
-                    data: result.data,
-                    cost: provider.pricePerUnit,
-                    currency: provider.currency,
-                    latencyMs,
-                };
-            }
-            // Provider returned error, try next
-            lastError = result.error || 'Unknown error';
-            if (!enableFallback) {
-                break;
-            }
-        }
-        catch (e) {
-            lastError = e.message || 'Provider execution failed';
-            if (!enableFallback) {
-                break;
-            }
-        }
-    }
-    // All providers failed
-    const latencyMs = Date.now() - startTime;
-    logCapabilityUsage({
-        capabilityId,
-        providerId: filteredProviders[0].providerId,
-        userId,
-        action,
-        success: false,
-        fallbackUsed: fallbackAttempted,
-        fallbackReason: lastError,
-        latencyMs,
-        cost: 0,
-        currency: 'SEK',
-    });
-    return {
-        success: false,
-        capability: capabilityId,
-        action,
-        fallbackAttempted,
-        error: `All providers failed. Last error: ${lastError}`,
-        latencyMs,
-    };
-}
-/**
- * List available capabilities
- */
-export async function listCapabilities() {
-    try {
-        const res = await fetch(`${CONVEX_URL}/api/query`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                path: 'capabilities:list',
-                args: {},
-            }),
-        });
-        if (!res.ok)
-            return [];
-        const data = await res.json();
-        const capabilities = Array.isArray(data) ? data : (data.value || []);
-        return capabilities.map(c => ({
-            id: c.id,
-            name: c.name,
-            category: c.category,
-        }));
-    }
-    catch (e) {
-        return [];
-    }
-}
-/**
- * Check if a capability exists
- */
-export async function hasCapability(capabilityId) {
-    try {
-        const res = await fetch(`${CONVEX_URL}/api/query`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                path: 'capabilities:getById',
-                args: { id: capabilityId },
-            }),
-        });
-        if (!res.ok)
-            return false;
-        const data = await res.json();
-        if (data && typeof data === 'object' && 'value' in data) {
-            return !!data.value;
-        }
-        return !!data;
-    }
-    catch (e) {
-        return false;
-    }
-}

package/dist/src/chainExecutor.js

@@ -1,451 +0,0 @@
-/**
- * APIClaw Chain Executor
- *
- * Orchestrates multi-step API chains with:
- * - Sequential execution
- * - Parallel batches
- * - Conditional branching
- * - ForEach loops
- * - Error handling and retry
- * - Full execution trace
- */
-import { executeAPICall } from './execute.js';
-import { resolveReferences, validateReferences, evaluateCondition, } from './chainResolver.js';
-// ============================================================================
-// MAIN EXECUTOR
-// ============================================================================
-/**
- * Execute a chain of API calls
- */
-export async function executeChain(chain, credentials, inputs, options = {}) {
-    const chainId = chain.id || generateChainId();
-    const startedAt = new Date().toISOString();
-    const startTime = Date.now();
-    // Initialize context
-    const context = {
-        results: {},
-        inputs: inputs || {},
-        currentIndex: 0,
-        startedAt,
-        env: process.env,
-    };
-    // Initialize result
-    const result = {
-        success: false,
-        chainId,
-        startedAt,
-        completedAt: '',
-        totalLatencyMs: 0,
-        totalCost: { cents: 0 },
-        results: {},
-        completedSteps: [],
-        trace: [],
-        canResume: false,
-    };
-    try {
-        // Validate inputs
-        if (chain.inputs) {
-            validateInputs(inputs || {}, chain.inputs);
-        }
-        // Validate references before execution
-        const validation = validateReferences(chain.steps);
-        if (!validation.valid) {
-            const errorMsg = validation.errors.map(e => `${e.stepId}: ${e.message}`).join('; ');
-            throw new Error(`Reference validation failed: ${errorMsg}`);
-        }
-        // Log warnings
-        if (options.verbose && validation.warnings.length > 0) {
-            console.log('[Chain] Warnings:', validation.warnings);
-        }
-        // Check limits
-        if (chain.limits?.maxSteps && chain.steps.length > chain.limits.maxSteps) {
-            throw new Error(`Chain exceeds maxSteps limit (${chain.steps.length} > ${chain.limits.maxSteps})`);
-        }
-        // Execute steps
-        let lastStepResult;
-        for (let i = 0; i < chain.steps.length; i++) {
-            const step = chain.steps[i];
-            context.currentIndex = i;
-            // Check timeout
-            if (chain.timeout && Date.now() - startTime > chain.timeout) {
-                throw new TimeoutError(`Chain exceeded timeout of ${chain.timeout}ms`);
-            }
-            // Execute based on step type
-            if (isParallelStep(step)) {
-                lastStepResult = await executeParallelStep(step, context, credentials, options, result);
-            }
-            else if (isConditionalStep(step)) {
-                lastStepResult = await executeConditionalStep(step, context, credentials, options, result);
-            }
-            else if (isForEachStep(step)) {
-                lastStepResult = await executeForEachStep(step, context, credentials, options, result, chain.limits);
-            }
-            else {
-                lastStepResult = await executeSingleStep(step, context, credentials, options, result, chain.errorPolicy);
-            }
-        }
-        // Success!
-        result.success = true;
-        result.finalResult = lastStepResult;
-        result.results = { ...context.results };
-    }
-    catch (error) {
-        // Handle failure
-        result.success = false;
-        result.error = {
-            stepId: result.failedStep?.stepId || 'unknown',
-            code: error.code || 'CHAIN_ERROR',
-            message: error.message,
-            retryAfter: error.retryAfter,
-        };
-        result.results = { ...context.results };
-        // Handle rollback for transactional mode
-        if (chain.errorPolicy?.mode === 'transactional' && chain.errorPolicy.rollback) {
-            await executeRollback(chain.errorPolicy.rollback, context, credentials, options, result);
-        }
-        // Can resume if we have completed steps
-        result.canResume = result.completedSteps.length > 0;
-        if (result.canResume) {
-            result.resumeToken = `${chainId}_step_${result.completedSteps.length}`;
-        }
-    }
-    // Finalize
-    result.completedAt = new Date().toISOString();
-    result.totalLatencyMs = Date.now() - startTime;
-    return result;
-}
-// ============================================================================
-// STEP TYPE GUARDS
-// ============================================================================
-function isParallelStep(step) {
-    return 'parallel' in step;
-}
-function isConditionalStep(step) {
-    return 'if' in step;
-}
-function isForEachStep(step) {
-    return 'forEach' in step;
-}
-// ============================================================================
-// SINGLE STEP EXECUTION
-// ============================================================================
-async function executeSingleStep(step, context, credentials, options, result, errorPolicy) {
-    const stepStart = Date.now();
-    const stepTrace = {
-        stepId: step.id,
-        stepIndex: context.currentIndex,
-        provider: step.provider,
-        action: step.action,
-        startedAt: new Date().toISOString(),
-        completedAt: '',
-        latencyMs: 0,
-        success: false,
-        input: {},
-    };
-    options.onStepStart?.(step.id, context.currentIndex);
-    try {
-        // Resolve references in params
-        const resolvedParams = step.params ? resolveReferences(step.params, context) : {};
-        stepTrace.input = resolvedParams;
-        // Execute with retry if configured
-        const maxRetries = step.onError?.retry?.attempts || 0;
-        let lastError;
-        for (let attempt = 0; attempt <= maxRetries; attempt++) {
-            try {
-                // Get customer key for this provider
-                const customerKey = credentials.customerKeys?.[step.provider];
-                // Execute the API call
-                const apiResult = await executeAPICall(step.provider, step.action, resolvedParams, credentials.userId, customerKey);
-                if (!apiResult.success) {
-                    throw new StepError(apiResult.error || 'API call failed', apiResult.code || 'PROVIDER_ERROR');
-                }
-                // Success!
-                stepTrace.success = true;
-                stepTrace.output = apiResult.data;
-                stepTrace.cost = apiResult.cost ? { cents: Math.round(apiResult.cost * 100) } : undefined;
-                // Update context
-                context.results[step.id] = apiResult.data;
-                context.prevStepId = step.id;
-                // Update result
-                result.completedSteps.push(step.id);
-                if (stepTrace.cost) {
-                    result.totalCost.cents += stepTrace.cost.cents;
-                }
-                return apiResult.data;
-            }
-            catch (error) {
-                lastError = error;
-                stepTrace.retries = attempt;
-                if (attempt < maxRetries) {
-                    // Wait before retry
-                    const backoff = step.onError?.retry?.backoff?.[attempt] || 1000 * Math.pow(2, attempt);
-                    await sleep(backoff);
-                }
-            }
-        }
-        // All retries exhausted
-        throw lastError;
-    }
-    catch (error) {
-        stepTrace.success = false;
-        stepTrace.error = error.message;
-        stepTrace.errorCode = error.code;
-        // Handle error based on policy
-        const shouldAbort = step.onError?.abort !== false && errorPolicy?.mode !== 'best-effort';
-        // Try fallback if configured
-        if (step.onError?.fallback && !options.dryRun) {
-            try {
-                const fallbackResult = await executeSingleStep(step.onError.fallback, context, credentials, options, result, errorPolicy);
-                // Use fallback result as this step's result
-                context.results[step.id] = fallbackResult;
-                context.prevStepId = step.id;
-                stepTrace.success = true;
-                stepTrace.output = { fallback: true, result: fallbackResult };
-                result.completedSteps.push(step.id);
-                return fallbackResult;
-            }
-            catch (fallbackError) {
-                // Fallback also failed
-                stepTrace.error = `Original: ${error.message}; Fallback: ${fallbackError.message}`;
-            }
-        }
-        result.failedStep = stepTrace;
-        if (shouldAbort) {
-            throw error;
-        }
-        // Best-effort mode: continue despite failure
-        context.results[step.id] = { error: error.message };
-        context.prevStepId = step.id;
-        return { error: error.message };
-    }
-    finally {
-        stepTrace.completedAt = new Date().toISOString();
-        stepTrace.latencyMs = Date.now() - stepStart;
-        result.trace.push(stepTrace);
-        options.onStepComplete?.(stepTrace);
-    }
-}
-// ============================================================================
-// PARALLEL EXECUTION
-// ============================================================================
-async function executeParallelStep(step, context, credentials, options, result) {
-    const parallelResults = await Promise.all(step.parallel.map(async (ps, idx) => {
-        // Create a copy of context for each parallel step
-        const parallelContext = {
-            ...context,
-            currentIndex: context.currentIndex,
-        };
-        try {
-            return await executeSingleStep(ps, parallelContext, credentials, options, result);
-        }
-        catch (error) {
-            // Return error as result for best-effort
-            return { error: error.message };
-        }
-    }));
-    // Store parallel results
-    context.parallelResults = parallelResults;
-    // Copy results from parallel steps to main context
-    for (let i = 0; i < step.parallel.length; i++) {
-        const ps = step.parallel[i];
-        context.results[ps.id] = parallelResults[i];
-    }
-    // Last parallel step becomes prev
-    context.prevStepId = step.parallel[step.parallel.length - 1].id;
-    return parallelResults;
-}
-// ============================================================================
-// CONDITIONAL EXECUTION
-// ============================================================================
-async function executeConditionalStep(step, context, credentials, options, result) {
-    // Evaluate condition
-    const conditionResult = evaluateCondition(step.if, context);
-    // Choose branch
-    const branch = conditionResult ? step.then : step.else;
-    if (!branch) {
-        // No else branch and condition is false
-        return null;
-    }
-    // Execute branch (can be single step or array)
-    const steps = Array.isArray(branch) ? branch : [branch];
-    let lastResult;
-    for (const branchStep of steps) {
-        lastResult = await executeSingleStep(branchStep, context, credentials, options, result);
-    }
-    return lastResult;
-}
-// ============================================================================
-// FOREACH EXECUTION
-// ============================================================================
-async function executeForEachStep(step, context, credentials, options, result, limits) {
-    // Resolve the array to iterate over
-    const arrayRef = step.forEach;
-    let items;
-    // Handle reference vs direct array
-    if (arrayRef.startsWith('$')) {
-        // It's a reference - resolve it
-        const resolved = resolveReferences({ items: arrayRef }, context);
-        items = resolved.items;
-    }
-    else {
-        // Try to parse as JSON array
-        try {
-            items = JSON.parse(arrayRef);
-        }
-        catch {
-            throw new Error(`forEach value must be a reference or JSON array: ${arrayRef}`);
-        }
-    }
-    if (!Array.isArray(items)) {
-        throw new Error(`forEach target must resolve to an array, got: ${typeof items}`);
-    }
-    // Check max iterations
-    if (limits?.maxSteps && items.length > limits.maxSteps) {
-        throw new Error(`forEach exceeds maxSteps limit (${items.length} iterations)`);
-    }
-    const forEachResults = [];
-    for (let i = 0; i < items.length; i++) {
-        // Set up forEach context
-        context.forEachItem = items[i];
-        context.forEachIndex = i;
-        context.forEachResults = forEachResults;
-        // Create step with dynamic ID
-        const dynamicStep = {
-            ...step.do,
-            id: step.do.id.replace(/\$index/g, String(i)),
-        };
-        const itemResult = await executeSingleStep(dynamicStep, context, credentials, options, result);
-        forEachResults.push(itemResult);
-    }
-    // Clean up forEach context
-    delete context.forEachItem;
-    delete context.forEachIndex;
-    context.forEachResults = forEachResults;
-    // Store aggregate results
-    context.results['$forEach'] = { results: forEachResults };
-    return forEachResults;
-}
-// ============================================================================
-// ROLLBACK EXECUTION
-// ============================================================================
-async function executeRollback(rollbackSteps, context, credentials, options, result) {
-    for (const rb of rollbackSteps) {
-        try {
-            const shouldRollback = evaluateCondition(rb.if, context);
-            if (shouldRollback) {
-                await executeSingleStep(rb.do, context, credentials, { ...options, verbose: false }, result);
-            }
-        }
-        catch (error) {
-            // Log but don't fail on rollback errors
-            console.error('[Chain] Rollback failed:', error);
-        }
-    }
-}
-// ============================================================================
-// INPUT VALIDATION
-// ============================================================================
-function validateInputs(inputs, definitions) {
-    for (const [name, def] of Object.entries(definitions)) {
-        const value = inputs[name];
-        // Check required
-        if (def.required && value === undefined) {
-            if (def.default !== undefined) {
-                inputs[name] = def.default;
-            }
-            else {
-                throw new Error(`Missing required input: ${name}`);
-            }
-        }
-        // Apply default
-        if (value === undefined && def.default !== undefined) {
-            inputs[name] = def.default;
-        }
-        // Type check (if value provided)
-        if (inputs[name] !== undefined) {
-            const actualType = Array.isArray(inputs[name]) ? 'array' : typeof inputs[name];
-            if (actualType !== def.type) {
-                throw new Error(`Input '${name}' must be ${def.type}, got ${actualType}`);
-            }
-        }
-    }
-}
-// ============================================================================
-// UTILITIES
-// ============================================================================
-function generateChainId() {
-    return `chain_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-}
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
-}
-// ============================================================================
-// CUSTOM ERRORS
-// ============================================================================
-export class StepError extends Error {
-    constructor(message, code, retryAfter) {
-        super(message);
-        this.name = 'StepError';
-        this.code = code;
-        this.retryAfter = retryAfter;
-    }
-}
-export class TimeoutError extends Error {
-    constructor(message) {
-        super(message);
-        this.code = 'TIMEOUT';
-        this.name = 'TimeoutError';
-    }
-}
-// ============================================================================
-// CHAIN STATUS & RESUME (Stubs for future implementation)
-// ============================================================================
-// In-memory store for running chains (would be Redis/DB in production)
-const runningChains = new Map();
-/**
- * Get status of a running or completed chain
- */
-export async function getChainStatus(chainId) {
-    const entry = runningChains.get(chainId);
-    if (!entry) {
-        return { chainId, status: 'not_found' };
-    }
-    return {
-        chainId,
-        status: entry.status,
-        result: entry.result,
-    };
-}
-/**
- * Resume a failed chain from a resume token
- */
-export async function resumeChain(resumeToken, chain, credentials, inputs, overrides, options = {}) {
-    // Parse resume token: chain_xyz_step_N
-    const match = resumeToken.match(/^(.+)_step_(\d+)$/);
-    if (!match) {
-        throw new Error(`Invalid resume token: ${resumeToken}`);
-    }
-    const [, chainId, stepIndexStr] = match;
-    const resumeFromIndex = parseInt(stepIndexStr, 10);
-    // Create a modified chain starting from the resume point
-    const resumedChain = {
-        ...chain,
-        id: chainId,
-        steps: chain.steps.slice(resumeFromIndex),
-    };
-    // Apply any overrides to the resumed steps
-    if (overrides) {
-        for (const step of resumedChain.steps) {
-            if ('id' in step && overrides[step.id]) {
-                step.params = { ...step.params, ...overrides[step.id] };
-            }
-        }
-    }
-    // Execute the resumed chain
-    // Note: In a real implementation, we'd restore the context from the previous run
-    return executeChain(resumedChain, credentials, inputs, options);
-}
-// ============================================================================
-// RE-EXPORTS
-// ============================================================================
-export { resolveReferences, validateReferences, evaluateCondition, } from './chainResolver.js';