@nordsym/apiclaw 1.2.2 → 1.2.3

package/src/execute-dynamic.ts

@@ -0,0 +1,589 @@
+/**
+ * APIClaw Dynamic Executor
+ * Executes provider-configured actions via self-service Direct Call
+ */
+
+import { decryptKey, validateBaseUrl } from './crypto.js';
+
+// Types for dynamic provider config
+export interface ProviderDirectCallConfig {
+  _id: string;
+  providerId: string;
+  apiId: string;
+  baseUrl: string;
+  authType: 'bearer' | 'basic' | 'api_key' | 'none';
+  authHeader: string;
+  authPrefix: string;
+  encryptedMasterKey: string;
+  rateLimitPerUser: number;
+  rateLimitPerDay: number;
+  pricePerRequest: number;
+  status: 'draft' | 'testing' | 'live';
+  // Customer key passthrough settings
+  allowCustomerKeys?: boolean; // Allow agents to pass their own API key (default: true)
+  requireCustomerKeys?: boolean; // Require customer key, no master key fallback (default: false)
+}
+
+export interface ActionParam {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'object';
+  required: boolean;
+  description: string;
+  default?: unknown;
+  in: 'body' | 'query' | 'path';
+}
+
+export interface ResponseMapping {
+  name: string;
+  path: string; // JSONPath expression
+}
+
+export interface ProviderAction {
+  _id: string;
+  directCallId: string;
+  name: string;
+  displayName: string;
+  description: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  params: ActionParam[];
+  responseMapping: ResponseMapping[];
+  enabled: boolean;
+}
+
+export interface ExecuteResult {
+  success: boolean;
+  provider: string;
+  action: string;
+  data?: unknown;
+  error?: string;
+  cost?: number;
+  latencyMs?: number;
+}
+
+interface UsageStats {
+  minute: number;
+  day: number;
+}
+
+// Convex HTTP API
+const CONVEX_URL = process.env.NEXT_PUBLIC_CONVEX_URL || 'https://brilliant-puffin-712.eu-west-1.convex.cloud';
+
+async function convexQuery<T>(path: string, args: Record<string, unknown>): Promise<T | null> {
+  try {
+    const res = await fetch(`${CONVEX_URL}/api/query`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path, args }),
+    });
+    if (!res.ok) {
+      console.error(`Convex query failed: ${res.status}`);
+      return null;
+    }
+    const data = await res.json() as { value?: T } | T;
+    return (data && typeof data === 'object' && 'value' in data) ? data.value as T : data as T;
+  } catch (error) {
+    console.error('Convex query error:', error);
+    return null;
+  }
+}
+
+async function convexMutation(path: string, args: Record<string, unknown>): Promise<boolean> {
+  try {
+    const res = await fetch(`${CONVEX_URL}/api/mutation`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ path, args }),
+    });
+    return res.ok;
+  } catch (error) {
+    console.error('Convex mutation error:', error);
+    return false;
+  }
+}
+
+/**
+ * Check if a provider has dynamic (self-service) config
+ */
+export async function hasDynamicConfig(providerId: string): Promise<boolean> {
+  const config = await getProviderConfig(providerId);
+  return config !== null && config.status === 'live';
+}
+
+/**
+ * Fetch provider direct call configuration from Convex
+ */
+export async function getProviderConfig(providerId: string): Promise<ProviderDirectCallConfig | null> {
+  // First try by API slug (for agent execution by name)
+  const bySlug = await convexQuery<ProviderDirectCallConfig>('directCall:getByApiSlug', { slug: providerId });
+  // Check for error response from Convex (not a real config)
+  const bySlugAny = bySlug as any;
+  if (bySlug && !(bySlugAny.status === 'error' || bySlugAny.errorMessage)) {
+    return bySlug;
+  }
+  
+  // Only try direct provider ID lookup if it looks like a Convex ID (starts with valid prefix)
+  // Convex IDs typically look like: k97xxx...
+  if (providerId.match(/^[a-z][a-z0-9]{2,}/)) {
+    const byId = await convexQuery<ProviderDirectCallConfig>('directCall:getDirectCallConfig', { providerId });
+    const byIdAny = byId as any;
+    if (byId && !(byIdAny.status === 'error' || byIdAny.errorMessage)) {
+      return byId;
+    }
+  }
+  
+  return null;
+}
+
+/**
+ * Fetch action configuration from Convex
+ */
+export async function getActionConfig(providerId: string, actionName: string): Promise<ProviderAction | null> {
+  // First get the direct call config to get directCallId
+  const config = await getProviderConfig(providerId);
+  if (!config) return null;
+  
+  return convexQuery<ProviderAction>('directCall:getActionByName', { 
+    directCallId: config._id, 
+    name: actionName 
+  });
+}
+
+/**
+ * Get user's current usage for rate limiting
+ */
+export async function getUserUsage(userId: string, providerId: string): Promise<UsageStats> {
+  const usage = await convexQuery<UsageStats>('usage:getUserUsage', { userId, providerId });
+  return usage || { minute: 0, day: 0 };
+}
+
+/**
+ * Build the full URL with path and query parameters
+ */
+export function buildUrl(
+  baseUrl: string, 
+  path: string, 
+  params: Record<string, unknown>, 
+  paramDefs: ActionParam[]
+): string {
+  let finalPath = path;
+  const queryParams = new URLSearchParams();
+  
+  for (const paramDef of paramDefs) {
+    const value = params[paramDef.name] ?? paramDef.default;
+    if (value === undefined) continue;
+    
+    const stringValue = typeof value === 'object' ? JSON.stringify(value) : String(value);
+    
+    if (paramDef.in === 'path') {
+      // Replace path parameter: /users/{id} -> /users/123
+      finalPath = finalPath.replace(`{${paramDef.name}}`, encodeURIComponent(stringValue));
+    } else if (paramDef.in === 'query') {
+      queryParams.set(paramDef.name, stringValue);
+    }
+  }
+  
+  // Ensure baseUrl doesn't end with slash and path starts with slash
+  const cleanBase = baseUrl.replace(/\/$/, '');
+  const cleanPath = finalPath.startsWith('/') ? finalPath : `/${finalPath}`;
+  
+  const queryString = queryParams.toString();
+  return queryString ? `${cleanBase}${cleanPath}?${queryString}` : `${cleanBase}${cleanPath}`;
+}
+
+/**
+ * Build request body from parameters
+ */
+export function buildBody(
+  params: Record<string, unknown>, 
+  paramDefs: ActionParam[]
+): string | undefined {
+  const bodyParams: Record<string, unknown> = {};
+  
+  for (const paramDef of paramDefs) {
+    if (paramDef.in === 'body') {
+      const value = params[paramDef.name] ?? paramDef.default;
+      if (value !== undefined) {
+        bodyParams[paramDef.name] = value;
+      }
+    }
+  }
+  
+  if (Object.keys(bodyParams).length === 0) {
+    return undefined;
+  }
+  
+  return JSON.stringify(bodyParams);
+}
+
+/**
+ * Build authentication headers based on auth type
+ */
+export function buildAuthHeaders(
+  config: ProviderDirectCallConfig, 
+  decryptedKey: string
+): Record<string, string> {
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/json',
+    'User-Agent': 'APIClaw/1.0',
+  };
+  
+  const headerName = config.authHeader || 'Authorization';
+  const prefix = config.authPrefix || '';
+  
+  switch (config.authType) {
+    case 'bearer':
+      headers[headerName] = prefix ? `${prefix} ${decryptedKey}` : `Bearer ${decryptedKey}`;
+      break;
+      
+    case 'basic':
+      // Assume decryptedKey is "username:password"
+      const base64 = Buffer.from(decryptedKey).toString('base64');
+      headers[headerName] = `Basic ${base64}`;
+      break;
+      
+    case 'api_key':
+      // Custom header with the key directly
+      headers[headerName] = prefix ? `${prefix} ${decryptedKey}` : decryptedKey;
+      break;
+      
+    case 'none':
+      // No auth header needed
+      break;
+  }
+  
+  return headers;
+}
+
+/**
+ * Extract value from object using simple JSONPath-like expression
+ * Supports: $.field, $.field.nested, $.array[0], $.array[*].field
+ */
+export function extractJsonPath(data: unknown, path: string): unknown {
+  if (!path.startsWith('$')) {
+    return undefined;
+  }
+  
+  const parts = path.slice(1).split('.').filter(Boolean);
+  let current: unknown = data;
+  
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    
+    // Handle array index: field[0] or field[*]
+    const arrayMatch = part.match(/^(\w+)\[(\d+|\*)\]$/);
+    if (arrayMatch) {
+      const [, field, index] = arrayMatch;
+      if (typeof current !== 'object') return undefined;
+      current = (current as Record<string, unknown>)[field];
+      
+      if (!Array.isArray(current)) return undefined;
+      
+      if (index === '*') {
+        // Return all elements (will need further processing)
+        continue;
+      } else {
+        current = current[parseInt(index)];
+      }
+    } else {
+      if (typeof current !== 'object') return undefined;
+      current = (current as Record<string, unknown>)[part];
+    }
+  }
+  
+  return current;
+}
+
+/**
+ * Map response data using configured response mappings
+ */
+export function mapResponse(
+  data: unknown, 
+  responseMapping: ResponseMapping[]
+): Record<string, unknown> {
+  if (!responseMapping || responseMapping.length === 0) {
+    // No mapping configured, return raw data
+    return { raw: data };
+  }
+  
+  const result: Record<string, unknown> = {};
+  
+  for (const mapping of responseMapping) {
+    const value = extractJsonPath(data, mapping.path);
+    if (value !== undefined) {
+      result[mapping.name] = value;
+    }
+  }
+  
+  return result;
+}
+
+/**
+ * Log usage to Convex
+ */
+export async function logUsage(params: {
+  userId: string;
+  providerId: string;
+  actionName: string;
+  timestamp: number;
+  success: boolean;
+  latencyMs: number;
+  creditsUsed: number;
+}): Promise<void> {
+  await convexMutation('usage:logUsage', params);
+}
+
+/**
+ * Main function: Execute a dynamically configured action
+ */
+export async function executeDynamicAction(
+  providerId: string,
+  actionName: string,
+  params: Record<string, unknown>,
+  userId: string,
+  customerKey?: string
+): Promise<ExecuteResult> {
+  const startTime = Date.now();
+  
+  // 1. Get provider config
+  const config = await getProviderConfig(providerId);
+  if (!config) {
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'Provider not found' 
+    };
+  }
+  
+  if (config.status !== 'live') {
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'Provider not available (not live)' 
+    };
+  }
+  
+  // 2. Validate base URL (SSRF prevention)
+  const urlValidation = validateBaseUrl(config.baseUrl);
+  if (!urlValidation.valid) {
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: `Invalid provider URL: ${urlValidation.error}` 
+    };
+  }
+  
+  // 3. Check rate limits
+  const usage = await getUserUsage(userId, providerId);
+  if (usage.minute >= config.rateLimitPerUser) {
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'Rate limit exceeded (per minute)' 
+    };
+  }
+  if (usage.day >= config.rateLimitPerDay) {
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'Rate limit exceeded (daily)' 
+    };
+  }
+  
+  // 4. Get action config
+  const action = await getActionConfig(providerId, actionName);
+  if (!action) {
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'Action not found' 
+    };
+  }
+  
+  if (!action.enabled) {
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'Action is disabled' 
+    };
+  }
+  
+  // 5. Validate required parameters
+  for (const paramDef of action.params) {
+    if (paramDef.required && params[paramDef.name] === undefined && paramDef.default === undefined) {
+      return { 
+        success: false, 
+        provider: providerId, 
+        action: actionName,
+        error: `Missing required parameter: ${paramDef.name}` 
+      };
+    }
+  }
+  
+  // 6. Resolve API key (customer key takes priority over master key)
+  let apiKey: string;
+  let usingCustomerKey = false;
+  
+  // Check if provider requires customer keys (like CoAccept)
+  const requiresCustomerKey = config.requireCustomerKeys === true;
+  const allowsCustomerKey = config.allowCustomerKeys !== false; // Default true
+  
+  if (customerKey && allowsCustomerKey) {
+    // Customer provided their own key - use it, skip usage tracking
+    apiKey = customerKey;
+    usingCustomerKey = true;
+  } else if (requiresCustomerKey) {
+    // Provider requires customer key but none provided
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'This provider requires your own API key. Pass it via customer_key parameter.' 
+    };
+  } else if (config.encryptedMasterKey) {
+    // Use provider's master key - track usage for billing
+    try {
+      apiKey = decryptKey(config.encryptedMasterKey);
+    } catch (error) {
+      console.error('Failed to decrypt provider key:', error);
+      return { 
+        success: false, 
+        provider: providerId, 
+        action: actionName,
+        error: 'Provider configuration error' 
+      };
+    }
+  } else {
+    // No key available
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: 'No API key available. Provide your own key via customer_key parameter.' 
+    };
+  }
+  
+  // 7. Build request
+  const url = buildUrl(config.baseUrl, action.path, params, action.params);
+  const headers = buildAuthHeaders(config, apiKey);
+  const body = action.method === 'GET' ? undefined : buildBody(params, action.params);
+  
+  // 8. Execute request
+  let response: Response;
+  try {
+    response = await fetch(url, { 
+      method: action.method, 
+      headers, 
+      body,
+    });
+  } catch (error) {
+    const latencyMs = Date.now() - startTime;
+    // Only log usage when using master key (for billing)
+    if (!usingCustomerKey) {
+      await logUsage({ 
+        userId, 
+        providerId, 
+        actionName, 
+        timestamp: Date.now(), 
+        success: false, 
+        latencyMs, 
+        creditsUsed: 0 
+      });
+    }
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: `Network error: ${error instanceof Error ? error.message : 'Unknown error'}`,
+      latencyMs 
+    };
+  }
+  
+  const latencyMs = Date.now() - startTime;
+  
+  // 9. Parse response
+  let data: unknown;
+  try {
+    const contentType = response.headers.get('content-type');
+    if (contentType?.includes('application/json')) {
+      data = await response.json();
+    } else {
+      data = await response.text();
+    }
+  } catch {
+    data = null;
+  }
+  
+  // 10. Log usage (only when using master key for billing)
+  if (!usingCustomerKey) {
+    await logUsage({ 
+      userId, 
+      providerId, 
+      actionName, 
+      timestamp: Date.now(), 
+      success: response.ok, 
+      latencyMs, 
+      creditsUsed: response.ok ? config.pricePerRequest : 0 
+    });
+  }
+  
+  // 11. Handle error response
+  if (!response.ok) {
+    let errorMessage = `HTTP ${response.status}`;
+    if (data && typeof data === 'object') {
+      const errorObj = data as Record<string, unknown>;
+      errorMessage = (errorObj.message as string) || 
+                     (errorObj.error as string) || 
+                     (errorObj.detail as string) ||
+                     errorMessage;
+    }
+    return { 
+      success: false, 
+      provider: providerId, 
+      action: actionName,
+      error: errorMessage,
+      latencyMs 
+    };
+  }
+  
+  // 12. Map response and return
+  const mappedData = mapResponse(data, action.responseMapping);
+  
+  return { 
+    success: true, 
+    provider: providerId, 
+    action: actionName,
+    data: mappedData,
+    cost: config.pricePerRequest,
+    latencyMs 
+  };
+}
+
+/**
+ * List available actions for a dynamic provider
+ */
+export async function listDynamicActions(providerId: string): Promise<string[]> {
+  const config = await getProviderConfig(providerId);
+  if (!config || config.status !== 'live') {
+    return [];
+  }
+  
+  const actions = await convexQuery<ProviderAction[]>('directCall:getActions', { 
+    directCallId: config._id 
+  });
+  
+  if (!actions) return [];
+  
+  return actions
+    .filter(a => a.enabled)
+    .map(a => a.name);
+}

package/src/execute.ts

@@ -4,6 +4,7 @@
 
 import { getCredentials } from './credentials.js';
 import { callProxy, PROXY_PROVIDERS } from './proxy.js';
+import { executeDynamicAction, hasDynamicConfig, listDynamicActions } from './execute-dynamic.js';
 
 interface ExecuteResult {
   success: boolean;
@@ -734,12 +735,24 @@ const handlers: Record<string, Record<string, (params: any, creds: any) => Promi
   },
 };
 
-// Get available actions for a provider
+// Get available actions for a provider (static handlers only)
 export function getProviderActions(providerId: string): string[] {
   return Object.keys(handlers[providerId] || {});
 }
 
-// Get all connected providers with their actions
+// Get available actions for a provider (includes dynamic providers)
+export async function getProviderActionsAsync(providerId: string): Promise<string[]> {
+  // First check static handlers
+  const staticActions = Object.keys(handlers[providerId] || {});
+  if (staticActions.length > 0) {
+    return staticActions;
+  }
+  
+  // Then check dynamic providers
+  return listDynamicActions(providerId);
+}
+
+// Get all connected providers with their actions (static handlers only)
 export function getConnectedProviders(): { provider: string; actions: string[] }[] {
   return Object.entries(handlers).map(([provider, actions]) => ({
     provider,
@@ -751,11 +764,32 @@ export function getConnectedProviders(): { provider: string; actions: string[] }
 export async function executeAPICall(
   providerId: string, 
   action: string, 
-  params: Record<string, any>
+  params: Record<string, any>,
+  userId?: string,
+  customerKey?: string
 ): Promise<ExecuteResult> {
+  // Check for dynamic (self-service) provider config first
+  if (userId) {
+    const isDynamic = await hasDynamicConfig(providerId);
+    if (isDynamic) {
+      return executeDynamicAction(providerId, action, params, userId, customerKey);
+    }
+  }
+  
+  // Fall back to hardcoded handlers
   // Check if provider exists
   const providerHandlers = handlers[providerId];
   if (!providerHandlers) {
+    // Check if it might be a dynamic provider without userId
+    const dynamicActions = await listDynamicActions(providerId);
+    if (dynamicActions.length > 0) {
+      return {
+        success: false,
+        provider: providerId,
+        action,
+        error: `Provider '${providerId}' requires userId for dynamic execution. Available actions: ${dynamicActions.join(', ')}`,
+      };
+    }
     return {
       success: false,
       provider: providerId,
@@ -775,8 +809,10 @@ export async function executeAPICall(
     };
   }
 
-  // Get credentials - fallback to proxy if not available locally
-  const creds = getCredentials(providerId);
+  // Get credentials - customer key takes priority, then local secrets, then proxy
+  let creds = customerKey ? { apiKey: customerKey, apiSecret: '' } : getCredentials(providerId);
+  const usingCustomerKey = !!customerKey;
+  
   if (!creds) {
     // Try proxy for supported providers
     if (PROXY_PROVIDERS.includes(providerId)) {