@nordsym/apiclaw 1.2.10 → 1.3.0

package/convex/_generated/api.d.ts

@@ -9,6 +9,7 @@
  */
 
 import type * as analytics from "../analytics.js";
+import type * as capabilities from "../capabilities.js";
 import type * as credits from "../credits.js";
 import type * as directCall from "../directCall.js";
 import type * as http from "../http.js";
@@ -27,6 +28,7 @@ import type {
 
 declare const fullApi: ApiFromModules<{
   analytics: typeof analytics;
+  capabilities: typeof capabilities;
   credits: typeof credits;
   directCall: typeof directCall;
   http: typeof http;

package/convex/capabilities.ts

@@ -0,0 +1,157 @@
+import { v } from "convex/values";
+import { query, mutation } from "./_generated/server";
+
+// Get a capability by ID
+export const getById = query({
+  args: { id: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("capabilities")
+      .withIndex("by_capability_id", (q) => q.eq("id", args.id))
+      .first();
+  },
+});
+
+// List all capabilities
+export const list = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("capabilities").collect();
+  },
+});
+
+// List capabilities by category
+export const listByCategory = query({
+  args: { category: v.string() },
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("capabilities")
+      .withIndex("by_category", (q) => q.eq("category", args.category))
+      .collect();
+  },
+});
+
+// Get providers for a capability (sorted by priority, filtered by enabled + healthy)
+export const getProviders = query({
+  args: { capabilityId: v.string(), region: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    let providers = await ctx.db
+      .query("providerCapabilities")
+      .withIndex("by_capabilityId_enabled", (q) => 
+        q.eq("capabilityId", args.capabilityId).eq("enabled", true)
+      )
+      .collect();
+    
+    // Filter by region if specified
+    if (args.region) {
+      providers = providers.filter(p => p.regions.includes(args.region!));
+    }
+    
+    // Filter out unhealthy providers
+    providers = providers.filter(p => p.healthStatus !== "down");
+    
+    // Sort by priority, then price, then latency
+    providers.sort((a, b) => {
+      if (a.priority !== b.priority) return a.priority - b.priority;
+      if (a.pricePerUnit !== b.pricePerUnit) return a.pricePerUnit - b.pricePerUnit;
+      return a.avgLatencyMs - b.avgLatencyMs;
+    });
+    
+    return providers;
+  },
+});
+
+// Create a capability
+export const create = mutation({
+  args: {
+    id: v.string(),
+    name: v.string(),
+    description: v.string(),
+    category: v.string(),
+    standardParams: v.array(v.object({
+      name: v.string(),
+      type: v.string(),
+      required: v.boolean(),
+      description: v.string(),
+      default: v.optional(v.any()),
+    })),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    return await ctx.db.insert("capabilities", {
+      ...args,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+// Add provider to capability
+export const addProvider = mutation({
+  args: {
+    providerId: v.string(),
+    capabilityId: v.string(),
+    priority: v.number(),
+    regions: v.array(v.string()),
+    pricePerUnit: v.number(),
+    currency: v.string(),
+    avgLatencyMs: v.number(),
+    paramMapping: v.any(),
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    return await ctx.db.insert("providerCapabilities", {
+      ...args,
+      enabled: true,
+      healthStatus: "healthy",
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+// Update provider health status
+export const updateHealth = mutation({
+  args: {
+    providerId: v.string(),
+    capabilityId: v.string(),
+    healthStatus: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const mapping = await ctx.db
+      .query("providerCapabilities")
+      .withIndex("by_providerId", (q) => q.eq("providerId", args.providerId))
+      .filter((q) => q.eq(q.field("capabilityId"), args.capabilityId))
+      .first();
+    
+    if (mapping) {
+      await ctx.db.patch(mapping._id, {
+        healthStatus: args.healthStatus,
+        lastHealthCheck: Date.now(),
+        updatedAt: Date.now(),
+      });
+    }
+  },
+});
+
+// Log capability usage
+export const logUsage = mutation({
+  args: {
+    capabilityId: v.string(),
+    providerId: v.string(),
+    userId: v.string(),
+    action: v.string(),
+    success: v.boolean(),
+    fallbackUsed: v.boolean(),
+    fallbackReason: v.optional(v.string()),
+    latencyMs: v.number(),
+    cost: v.number(),
+    currency: v.string(),
+  },
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("capabilityLogs", {
+      ...args,
+      timestamp: Date.now(),
+    });
+  },
+});

package/convex/schema.ts

@@ -307,4 +307,67 @@ export default defineSchema({
   })
     .index("by_email", ["email"])
     .index("by_type", ["type"]),
+
+  // ============================================
+  // CAPABILITY LAYER (abstraction over providers)
+  // ============================================
+
+  // Capability definitions (sms, email, invoice, search, etc.)
+  capabilities: defineTable({
+    id: v.string(),              // "sms", "email", "invoice"
+    name: v.string(),            // "SMS Messaging"
+    description: v.string(),
+    category: v.string(),        // "communication", "business", "ai"
+    standardParams: v.array(v.object({
+      name: v.string(),
+      type: v.string(),          // "string" | "number" | "boolean"
+      required: v.boolean(),
+      description: v.string(),
+      default: v.optional(v.any()),
+    })),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_capability_id", ["id"])
+    .index("by_category", ["category"]),
+
+  // Provider → Capability mappings (which providers offer which capabilities)
+  providerCapabilities: defineTable({
+    providerId: v.string(),      // "46elks", "twilio"
+    capabilityId: v.string(),    // "sms"
+    priority: v.number(),        // 1 = primary, 2 = fallback
+    regions: v.array(v.string()), // ["SE", "EU", "US"]
+    pricePerUnit: v.number(),    // in smallest currency unit (cents/öre)
+    currency: v.string(),        // "SEK", "USD"
+    avgLatencyMs: v.number(),
+    paramMapping: v.any(),       // Record<string, string> - capability param → provider param
+    enabled: v.boolean(),
+    healthStatus: v.string(),    // "healthy" | "degraded" | "down"
+    lastHealthCheck: v.optional(v.number()),
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  })
+    .index("by_providerId", ["providerId"])
+    .index("by_capabilityId", ["capabilityId"])
+    .index("by_capabilityId_enabled", ["capabilityId", "enabled"])
+    .index("by_healthStatus", ["healthStatus"]),
+
+  // Capability usage logs (for analytics and billing)
+  capabilityLogs: defineTable({
+    capabilityId: v.string(),
+    providerId: v.string(),
+    userId: v.string(),
+    action: v.string(),
+    success: v.boolean(),
+    fallbackUsed: v.boolean(),
+    fallbackReason: v.optional(v.string()),
+    latencyMs: v.number(),
+    cost: v.number(),
+    currency: v.string(),
+    timestamp: v.number(),
+  })
+    .index("by_capabilityId", ["capabilityId"])
+    .index("by_providerId", ["providerId"])
+    .index("by_userId", ["userId"])
+    .index("by_timestamp", ["timestamp"]),
 });

package/dist/capability-router.d.ts

@@ -0,0 +1,41 @@
+/**
+ * APIClaw Capability Router
+ * Routes capability requests to the best available provider
+ */
+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;
+}
+/**
+ * Execute a capability request with automatic provider selection and fallback
+ */
+export declare function executeCapability(capabilityId: string, action: string, params: Record<string, unknown>, userId: string, preferences?: CapabilityPreferences): Promise<CapabilityResult>;
+/**
+ * List available capabilities
+ */
+export declare function listCapabilities(): Promise<{
+    id: string;
+    name: string;
+    category: string;
+}[]>;
+/**
+ * Check if a capability exists
+ */
+export declare function hasCapability(capabilityId: string): Promise<boolean>;
+export {};
+//# sourceMappingURL=capability-router.d.ts.map

package/dist/capability-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-router.d.ts","sourceRoot":"","sources":["../src/capability-router.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAqBH,UAAU,qBAAqB;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,UAAU,gBAAgB;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,OAAO,CAAC;IAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4ED;;GAEG;AACH,wBAAsB,iBAAiB,CACrC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,EAAE,MAAM,EACd,WAAW,GAAE,qBAA0B,GACtC,OAAO,CAAC,gBAAgB,CAAC,CAmJ3B;AAED;;GAEG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAwBlG;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAqB1E"}

package/dist/capability-router.js

@@ -0,0 +1,241 @@
+/**
+ * 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;
+    }
+}
+//# sourceMappingURL=capability-router.js.map

package/dist/capability-router.js.map

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

package/dist/index.js

@@ -20,6 +20,7 @@ import { executeAPICall, getConnectedProviders } from './execute.js';
 import { logAPICall } from './analytics.js';
 import { isOpenAPI, executeOpenAPI, listOpenAPIs } from './open-apis.js';
 import { requiresConfirmationAsync, createPendingAction, consumePendingAction, 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';
 /**
@@ -196,6 +197,46 @@ const tools = [
             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: {}
+        }
     }
 ];
 // Create server
@@ -594,6 +635,63 @@ Docs: https://apiclaw.nordsym.com
                     ]
                 };
             }
+            case 'capability': {
+                const capabilityId = args?.capability;
+                const action = args?.action;
+                const params = args?.params || {};
+                const preferences = args?.preferences || {};
+                // 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: [