@nordsym/apiclaw 1.2.10 → 1.3.1

package/src/capability-router.ts

@@ -0,0 +1,331 @@
+/**
+ * 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';
+
+interface ProviderMapping {
+  providerId: string;
+  capabilityId: string;
+  priority: number;
+  regions: string[];
+  pricePerUnit: number;
+  currency: string;
+  avgLatencyMs: number;
+  paramMapping: Record<string, string>;
+  enabled: boolean;
+  healthStatus: string;
+}
+
+interface CapabilityPreferences {
+  region?: string;
+  maxPrice?: number;
+  preferredProvider?: string;
+  fallback?: boolean;
+}
+
+interface CapabilityResult {
+  success: boolean;
+  capability: string;
+  action: string;
+  providerUsed?: string;
+  fallbackAttempted: boolean;
+  fallbackReason?: string;
+  data?: unknown;
+  error?: string;
+  cost?: number;
+  currency?: string;
+  latencyMs?: number;
+}
+
+/**
+ * Query Convex for providers that support a capability
+ */
+async function getProvidersForCapability(
+  capabilityId: string, 
+  region?: string
+): Promise<ProviderMapping[]> {
+  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() as { value?: ProviderMapping[] } | ProviderMapping[];
+    if (Array.isArray(data)) return data;
+    return (data.value || []) as ProviderMapping[];
+  } catch (e) {
+    console.error('Failed to fetch capability providers:', e);
+    return [];
+  }
+}
+
+/**
+ * Map capability params to provider-specific params
+ */
+function mapParams(
+  params: Record<string, unknown>,
+  mapping: Record<string, string>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  
+  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: {
+  capabilityId: string;
+  providerId: string;
+  userId: string;
+  action: string;
+  success: boolean;
+  fallbackUsed: boolean;
+  fallbackReason?: string;
+  latencyMs: number;
+  cost: number;
+  currency: string;
+}): Promise<void> {
+  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: string,
+  action: string,
+  params: Record<string, unknown>,
+  userId: string,
+  preferences: CapabilityPreferences = {}
+): Promise<CapabilityResult> {
+  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: any) {
+      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(): Promise<{ id: string; name: string; category: string }[]> {
+  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() as { value?: any[] } | any[];
+    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: string): Promise<boolean> {
+  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() as { value?: unknown } | unknown;
+    if (data && typeof data === 'object' && 'value' in data) {
+      return !!data.value;
+    }
+    return !!data;
+  } catch (e) {
+    return false;
+  }
+}

package/src/index.ts

@@ -40,6 +40,7 @@ import {
   generatePreview,
   validateParams 
 } from './confirmation.js';
+import { executeCapability, listCapabilities, hasCapability } from './capability-router.js';
 
 // Default agent ID for MVP (in production, this would come from auth)
 const DEFAULT_AGENT_ID = 'agent_default';
@@ -222,6 +223,46 @@ const tools: Tool[] = [
       type: 'object',
       properties: {}
     }
+  },
+  {
+    name: 'capability',
+    description: 'Execute an action by capability, not provider. APIClaw automatically selects the best provider, handles fallback, and optimizes for cost/speed. Example: capability("sms", "send", {to: "+46...", message: "Hello"})',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        capability: {
+          type: 'string',
+          description: 'Capability ID: "sms", "email", "search", "tts", "invoice", "llm"'
+        },
+        action: {
+          type: 'string',
+          description: 'Action to perform: "send", "search", "generate", etc.'
+        },
+        params: {
+          type: 'object',
+          description: 'Parameters for the action (capability-standard params, not provider-specific)'
+        },
+        preferences: {
+          type: 'object',
+          description: 'Optional routing preferences',
+          properties: {
+            region: { type: 'string', description: 'Preferred region: "SE", "EU", "US"' },
+            maxPrice: { type: 'number', description: 'Max price per unit in cents/öre' },
+            preferredProvider: { type: 'string', description: 'Hint to prefer a specific provider' },
+            fallback: { type: 'boolean', description: 'Enable fallback to other providers (default: true)' }
+          }
+        }
+      },
+      required: ['capability', 'action', 'params']
+    }
+  },
+  {
+    name: 'list_capabilities',
+    description: 'List all available capabilities and their providers.',
+    inputSchema: {
+      type: 'object',
+      properties: {}
+    }
   }
 ];
 
@@ -664,6 +705,75 @@ Docs: https://apiclaw.nordsym.com
         };
       }
 
+      case 'capability': {
+        const capabilityId = args?.capability as string;
+        const action = args?.action as string;
+        const params = (args?.params as Record<string, any>) || {};
+        const preferences = (args?.preferences as Record<string, any>) || {};
+
+        // Check if capability exists
+        const exists = await hasCapability(capabilityId);
+        if (!exists) {
+          // Try to help with available capabilities
+          const available = await listCapabilities();
+          return {
+            content: [{
+              type: 'text',
+              text: JSON.stringify({
+                status: 'error',
+                error: `Unknown capability: ${capabilityId}`,
+                available_capabilities: available.map(c => c.id),
+                hint: 'Use list_capabilities to see all available capabilities.'
+              }, null, 2)
+            }],
+            isError: true
+          };
+        }
+
+        // Execute capability
+        const result = await executeCapability(
+          capabilityId,
+          action,
+          params,
+          DEFAULT_AGENT_ID,
+          preferences
+        );
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              status: result.success ? 'success' : 'error',
+              capability: result.capability,
+              action: result.action,
+              provider_used: result.providerUsed,
+              fallback_attempted: result.fallbackAttempted,
+              ...(result.fallbackReason ? { fallback_reason: result.fallbackReason } : {}),
+              ...(result.success ? { data: result.data } : { error: result.error }),
+              ...(result.cost !== undefined ? { cost: result.cost, currency: result.currency } : {}),
+              latency_ms: result.latencyMs,
+            }, null, 2)
+          }],
+          isError: !result.success
+        };
+      }
+
+      case 'list_capabilities': {
+        const capabilities = await listCapabilities();
+
+        return {
+          content: [{
+            type: 'text',
+            text: JSON.stringify({
+              status: 'success',
+              message: 'Available capabilities - use capability() to execute',
+              capabilities,
+              usage: 'capability("sms", "send", {to: "+46...", message: "Hello"})'
+            }, null, 2)
+          }]
+        };
+      }
+
       default:
         return {
           content: [

package/src/open-apis.ts

@@ -128,6 +128,35 @@ export const openAPIs: Record<string, OpenAPIConfig> = {
       },
     },
   },
+
+  // Kroki - Diagrams as code (returns URL, not JSON)
+  kroki: {
+    name: 'Kroki',
+    description: 'Generate diagram URLs from text (Mermaid, PlantUML, GraphViz, C4)',
+    baseUrl: 'https://kroki.io',
+    actions: {
+      render: {
+        method: 'GET',
+        path: () => '', // Custom handling
+        transform: (_, params) => {
+          const type = params.type || 'mermaid';
+          const format = params.format || 'svg';
+          const diagram = params.diagram || '';
+          
+          // Base64url encode the diagram
+          const encoded = Buffer.from(diagram).toString('base64url');
+          const url = `https://kroki.io/${type}/${format}/${encoded}`;
+          
+          return {
+            url,
+            type,
+            format,
+            note: 'Open this URL to see/download the diagram',
+          };
+        },
+      },
+    },
+  },
 };
 
 /**
@@ -175,6 +204,38 @@ export async function executeOpenAPI(
   }
 
   try {
+    // Special handling for Kroki - no fetch needed, just compute URL
+    if (providerId === 'kroki') {
+      const type = params.type || 'mermaid';
+      const format = params.format || 'svg';
+      const diagram = params.diagram || '';
+      
+      if (!diagram) {
+        return {
+          success: false,
+          provider: providerId,
+          action,
+          error: 'Missing required param: diagram',
+        };
+      }
+      
+      const encoded = Buffer.from(diagram).toString('base64url');
+      const diagramUrl = `https://kroki.io/${type}/${format}/${encoded}`;
+      
+      return {
+        success: true,
+        provider: providerId,
+        action,
+        data: {
+          url: diagramUrl,
+          type,
+          format,
+          supported_types: ['mermaid', 'plantuml', 'graphviz', 'c4plantuml', 'blockdiag', 'bpmn', 'excalidraw'],
+          supported_formats: ['svg', 'png', 'pdf'],
+        },
+      };
+    }
+
     const url = config.baseUrl + actionConfig.path(params);
     const response = await fetch(url, { method: actionConfig.method });