squidclaw 0.1.0

package/lib/ai/gateway.js

@@ -0,0 +1,283 @@
+/**
+ * 🦑 AI Gateway
+ * Multi-provider AI router with auto-fallback
+ */
+
+import { logger } from '../core/logger.js';
+import { MODEL_MAP, MODEL_PRICING } from '../core/config.js';
+
+export class AIGateway {
+  constructor(config) {
+    this.config = config;
+    this.providers = {};
+    this._initProviders();
+  }
+
+  _initProviders() {
+    const providerConfigs = this.config.ai?.providers || {};
+    for (const [name, conf] of Object.entries(providerConfigs)) {
+      if (conf.key) {
+        this.providers[name] = conf;
+      }
+    }
+    logger.info('ai-gateway', `Initialized providers: ${Object.keys(this.providers).join(', ') || 'none'}`);
+  }
+
+  /**
+   * Send a chat completion request with auto-fallback
+   */
+  async chat(messages, options = {}) {
+    const model = options.model || this.config.ai?.defaultModel;
+    const fallbackChain = options.fallbackChain || this.config.ai?.fallbackChain || [];
+    const modelsToTry = [model, ...fallbackChain].filter(Boolean);
+
+    if (modelsToTry.length === 0) {
+      throw new Error('No AI model configured. Run: squidclaw brain set <model>');
+    }
+
+    let lastError;
+    for (const m of modelsToTry) {
+      try {
+        const result = await this._callProvider(m, messages, options);
+        return result;
+      } catch (err) {
+        lastError = err;
+        logger.warn('ai-gateway', `${m} failed: ${err.message}, trying next...`);
+      }
+    }
+    throw lastError;
+  }
+
+  /**
+   * Route to the correct provider based on model name
+   */
+  async _callProvider(model, messages, options) {
+    const provider = this._resolveProvider(model);
+    const modelId = MODEL_MAP[model] || model;
+
+    switch (provider) {
+      case 'anthropic': return this._callAnthropic(modelId, messages, options);
+      case 'openai': return this._callOpenAI(modelId, messages, options);
+      case 'google': return this._callGoogle(modelId, messages, options);
+      case 'groq': return this._callOpenAICompat(model, modelId, messages, options, 'https://api.groq.com/openai/v1', 'groq');
+      case 'together': return this._callOpenAICompat(model, modelId, messages, options, 'https://api.together.xyz/v1', 'together');
+      case 'cerebras': return this._callOpenAICompat(model, modelId, messages, options, 'https://api.cerebras.ai/v1', 'cerebras');
+      case 'openrouter': return this._callOpenAICompat(model, modelId, messages, options, 'https://openrouter.ai/api/v1', 'openrouter');
+      case 'mistral': return this._callOpenAICompat(model, modelId, messages, options, 'https://api.mistral.ai/v1', 'mistral');
+      case 'ollama': return this._callOpenAICompat(model, modelId, messages, options, this.providers.ollama?.baseUrl || 'http://localhost:11434/v1', 'ollama');
+      case 'lmstudio': return this._callOpenAICompat(model, modelId, messages, options, this.providers.lmstudio?.baseUrl || 'http://localhost:1234/v1', 'lmstudio');
+      default: throw new Error(`Unknown provider for model: ${model}`);
+    }
+  }
+
+  _resolveProvider(model) {
+    if (model.startsWith('claude')) return 'anthropic';
+    if (model.startsWith('gpt') || model.startsWith('o3') || model.startsWith('o4')) return 'openai';
+    if (model.startsWith('gemini')) return 'google';
+    if (model.startsWith('groq/')) return 'groq';
+    if (model.startsWith('together/')) return 'together';
+    if (model.startsWith('cerebras/')) return 'cerebras';
+    if (model.startsWith('mistral')) return 'mistral';
+    if (model.startsWith('ollama/')) return 'ollama';
+    if (model.startsWith('lmstudio/')) return 'lmstudio';
+    if (model.startsWith('openrouter/')) return 'openrouter';
+    // Check if model exists in any provider
+    for (const [prov, conf] of Object.entries(this.config.ai?.providers || {})) {
+      if (conf.models?.includes(model)) return prov;
+    }
+    return 'openai'; // default fallback
+  }
+
+  _isOAuthToken(key) {
+    return key?.includes('sk-ant-oat');
+  }
+
+  async _callAnthropic(modelId, messages, options) {
+    const key = this.providers.anthropic?.key;
+    if (!key) throw new Error('Anthropic API key not configured');
+
+    const isOAuth = this._isOAuthToken(key);
+    const systemMessage = messages.find(m => m.role === 'system')?.content || '';
+    const chatMessages = messages.filter(m => m.role !== 'system').map(m => ({
+      role: m.role === 'assistant' ? 'assistant' : 'user',
+      content: m.content,
+    }));
+
+    const headers = {
+      'content-type': 'application/json',
+      'anthropic-version': '2023-06-01',
+    };
+
+    if (isOAuth) {
+      headers['authorization'] = `Bearer ${key}`;
+      headers['anthropic-beta'] = 'claude-code-20250219,oauth-2025-04-20';
+      headers['user-agent'] = 'squidclaw/0.1.0';
+      headers['x-app'] = 'squidclaw';
+      headers['anthropic-dangerous-direct-browser-access'] = 'true';
+    } else {
+      headers['x-api-key'] = key;
+    }
+
+    const body = {
+      model: modelId,
+      max_tokens: options.maxTokens || 4096,
+      system: systemMessage,
+      messages: chatMessages,
+      ...(options.temperature != null ? { temperature: options.temperature } : {}),
+    };
+
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`Anthropic API error ${res.status}: ${err.error?.message || res.statusText}`);
+    }
+
+    const data = await res.json();
+    const content = data.content?.map(c => c.text).join('') || '';
+    const inputTokens = data.usage?.input_tokens || 0;
+    const outputTokens = data.usage?.output_tokens || 0;
+
+    return {
+      content,
+      model: data.model,
+      provider: 'anthropic',
+      inputTokens,
+      outputTokens,
+      costUsd: this._calculateCost(options.model || 'claude-sonnet-4', inputTokens, outputTokens),
+    };
+  }
+
+  async _callOpenAI(modelId, messages, options) {
+    const key = this.providers.openai?.key;
+    if (!key) throw new Error('OpenAI API key not configured');
+
+    const res = await fetch('https://api.openai.com/v1/chat/completions', {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'authorization': `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        model: modelId,
+        messages,
+        max_completion_tokens: options.maxTokens || 4096,
+        ...(options.temperature != null ? { temperature: options.temperature } : {}),
+      }),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`OpenAI API error ${res.status}: ${err.error?.message || res.statusText}`);
+    }
+
+    const data = await res.json();
+    const content = data.choices?.[0]?.message?.content || '';
+    const inputTokens = data.usage?.prompt_tokens || 0;
+    const outputTokens = data.usage?.completion_tokens || 0;
+
+    return {
+      content,
+      model: data.model,
+      provider: 'openai',
+      inputTokens,
+      outputTokens,
+      costUsd: this._calculateCost(options.model || 'gpt-4o', inputTokens, outputTokens),
+    };
+  }
+
+  async _callGoogle(modelId, messages, options) {
+    const key = this.providers.google?.key;
+    if (!key) throw new Error('Google API key not configured');
+
+    const systemMessage = messages.find(m => m.role === 'system')?.content;
+    const chatMessages = messages.filter(m => m.role !== 'system').map(m => ({
+      role: m.role === 'assistant' ? 'model' : 'user',
+      parts: [{ text: m.content }],
+    }));
+
+    const body = {
+      contents: chatMessages,
+      ...(systemMessage ? { systemInstruction: { parts: [{ text: systemMessage }] } } : {}),
+      generationConfig: {
+        maxOutputTokens: options.maxTokens || 4096,
+        ...(options.temperature != null ? { temperature: options.temperature } : {}),
+      },
+    };
+
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/${modelId}:generateContent?key=${key}`;
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`Google API error ${res.status}: ${err.error?.message || res.statusText}`);
+    }
+
+    const data = await res.json();
+    const content = data.candidates?.[0]?.content?.parts?.map(p => p.text).join('') || '';
+    const inputTokens = data.usageMetadata?.promptTokenCount || 0;
+    const outputTokens = data.usageMetadata?.candidatesTokenCount || 0;
+
+    return {
+      content,
+      model: modelId,
+      provider: 'google',
+      inputTokens,
+      outputTokens,
+      costUsd: this._calculateCost(options.model || 'gemini-2.5-flash', inputTokens, outputTokens),
+    };
+  }
+
+  /**
+   * OpenAI-compatible API (Groq, Together, Cerebras, Mistral, Ollama, LM Studio, OpenRouter)
+   */
+  async _callOpenAICompat(friendlyModel, modelId, messages, options, baseUrl, providerName) {
+    const key = this.providers[providerName]?.key;
+    const headers = { 'content-type': 'application/json' };
+    if (key && key !== 'local') headers['authorization'] = `Bearer ${key}`;
+
+    const res = await fetch(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model: modelId,
+        messages,
+        max_tokens: options.maxTokens || 4096,
+        ...(options.temperature != null ? { temperature: options.temperature } : {}),
+      }),
+    });
+
+    if (!res.ok) {
+      const err = await res.json().catch(() => ({}));
+      throw new Error(`${providerName} API error ${res.status}: ${err.error?.message || res.statusText}`);
+    }
+
+    const data = await res.json();
+    const content = data.choices?.[0]?.message?.content || '';
+    const inputTokens = data.usage?.prompt_tokens || 0;
+    const outputTokens = data.usage?.completion_tokens || 0;
+
+    return {
+      content,
+      model: data.model || modelId,
+      provider: providerName,
+      inputTokens,
+      outputTokens,
+      costUsd: this._calculateCost(friendlyModel, inputTokens, outputTokens),
+    };
+  }
+
+  _calculateCost(model, inputTokens, outputTokens) {
+    const pricing = MODEL_PRICING[model];
+    if (!pricing) return 0;
+    return (inputTokens * pricing.input / 1_000_000) + (outputTokens * pricing.output / 1_000_000);
+  }
+}

package/lib/ai/prompt-builder.js

@@ -0,0 +1,149 @@
+/**
+ * 🦑 Prompt Builder
+ * Assembles system prompt from soul + rules + memory + knowledge + behavior
+ */
+
+import { logger } from '../core/logger.js';
+
+export class PromptBuilder {
+  constructor(storage) {
+    this.storage = storage;
+  }
+
+  /**
+   * Build full system prompt for an agent
+   */
+  async build(agent, contactId, userMessage) {
+    const parts = [];
+
+    // 1. Soul / Identity
+    if (agent.soul) {
+      parts.push(agent.soul);
+    } else {
+      parts.push(this._defaultSoul(agent));
+    }
+
+    // 2. Behavior rules
+    const behavior = agent.behavior || {};
+    parts.push(this._buildBehaviorRules(behavior));
+
+    // 3. Long-term memories
+    const memories = await this.storage.getMemories(agent.id);
+    if (memories.length > 0) {
+      parts.push('\n## What You Remember\n');
+      for (const mem of memories.slice(0, 30)) {
+        parts.push(`- ${mem.key}: ${mem.value}`);
+      }
+    }
+
+    // 4. Contact context
+    const contact = await this.storage.getContact(agent.id, contactId);
+    if (contact) {
+      parts.push(`\n## About This Person`);
+      if (contact.name) parts.push(`- Name: ${contact.name}`);
+      parts.push(`- Messages exchanged: ${contact.message_count || 0}`);
+      parts.push(`- First seen: ${contact.first_seen || 'just now'}`);
+    }
+
+    // 5. Knowledge base (RAG)
+    // TODO: implement vector search, for now inject all chunks
+    const docs = await this.storage.listDocuments(agent.id);
+    if (docs.length > 0) {
+      const allChunks = [];
+      for (const doc of docs.slice(0, 5)) {
+        const chunks = await this.storage.searchKnowledge(agent.id, null, 10);
+        allChunks.push(...chunks);
+      }
+      if (allChunks.length > 0) {
+        parts.push('\n## Knowledge Base\nUse this information to answer questions:\n');
+        for (const chunk of allChunks.slice(0, 10)) {
+          parts.push(chunk.content);
+        }
+      }
+    }
+
+    // 6. Current context
+    const now = new Date();
+    parts.push(`\n## Current Context`);
+    parts.push(`- Date: ${now.toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' })}`);
+    parts.push(`- Time: ${now.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit', timeZone: agent.timezone || 'UTC' })} (${agent.timezone || 'UTC'})`);
+
+    // 7. Business hours context
+    if (behavior.businessHours) {
+      const isOpen = this._isBusinessHours(behavior.businessHours, agent.timezone);
+      if (!isOpen) {
+        parts.push(`- ⚠️ Currently OUTSIDE business hours. ${behavior.afterHoursMessage || 'Let them know and offer to follow up.'}`);
+      }
+    }
+
+    return parts.join('\n');
+  }
+
+  _defaultSoul(agent) {
+    return `# ${agent.name || 'Assistant'}
+
+You are ${agent.name || 'an AI assistant'}. 
+
+## How You Communicate
+- Language: ${agent.language === 'ar' ? 'Arabic' : agent.language === 'bilingual' ? 'Bilingual (Arabic & English) — match the language the person writes in' : 'English'}
+- Tone: ${agent.tone > 60 ? 'Casual and friendly' : agent.tone > 30 ? 'Professional but warm' : 'Formal and polished'}
+- Platform: WhatsApp — keep messages short, conversational, use emojis naturally
+- Never write walls of text. Short messages, like a real person texting.
+- Never say "As an AI" or "I'd be happy to help" or "Great question!"
+- Be direct. Be human. Be useful.`;
+  }
+
+  _buildBehaviorRules(behavior) {
+    const rules = ['\n## Behavior Rules'];
+
+    if (behavior.avoidPhrases?.length) {
+      rules.push('Never say:');
+      for (const phrase of behavior.avoidPhrases) {
+        rules.push(`  - "${phrase}"`);
+      }
+    }
+
+    rules.push('\n### Response Format');
+    rules.push('- Split long responses into 2-4 short messages (marked with ---SPLIT--- between them)');
+    rules.push('- Each message should be under 200 characters when possible');
+    rules.push('- Use ---SPLIT--- to indicate where to break messages');
+    rules.push('- Example: "Hey! 👋---SPLIT---How can I help you today?"');
+    
+    rules.push('\n### Reactions');
+    rules.push('- When someone says "thanks", "ok", "👍" or similar → respond with just ---REACT:❤️--- (no text reply needed)');
+    rules.push('- You can react AND reply: ---REACT:😍---That looks amazing!');
+    rules.push('- Available reactions: 👍 ❤️ 😂 😮 😢 🙏 🔥 👏');
+
+    rules.push('\n### Conversation Endings');
+    rules.push('- Recognize when a conversation is over');
+    rules.push('- Don\'t keep asking "anything else?" — just react and let it end naturally');
+
+    rules.push('\n### Memory');
+    rules.push('- Remember important facts about people (name, preferences, past orders/requests)');
+    rules.push('- Reference past interactions naturally ("The usual?" "How was that thing you mentioned?")');
+    rules.push('- If you learn something important, note it with ---MEMORY:key:value---');
+    rules.push('- Example: ---MEMORY:food_preference:vegetarian---');
+
+    if (behavior.handoff?.enabled) {
+      rules.push('\n### Escalation');
+      rules.push('- If you cannot help or the person is very upset, say ---HANDOFF:reason--- to escalate');
+      rules.push('- Tell the person you\'re connecting them with the team');
+    }
+
+    return rules.join('\n');
+  }
+
+  _isBusinessHours(schedule, timezone) {
+    // Simple business hours check
+    // schedule format: "sun-thu 9:00-18:00"
+    try {
+      const now = new Date();
+      const options = { timeZone: timezone || 'UTC', weekday: 'short', hour: '2-digit', minute: '2-digit', hour12: false };
+      const localTime = now.toLocaleString('en-US', options);
+      // Simplified — always return true for now, implement properly later
+      return true;
+    } catch {
+      return true;
+    }
+  }
+}

package/lib/api/server.js

@@ -0,0 +1,235 @@
+/**
+ * 🦑 API Server
+ * REST API for dashboard integration and external access
+ */
+
+import express from 'express';
+import { logger } from '../core/logger.js';
+
+export function createAPIServer(engine) {
+  const app = express();
+  app.use(express.json());
+
+  const { agentManager, whatsappManager, storage, config } = engine;
+
+  // ── Health ──
+  app.get('/health', (req, res) => {
+    const agents = agentManager.getAll();
+    const waStatuses = whatsappManager.getStatuses();
+    res.json({
+      status: 'ok',
+      service: 'squidclaw',
+      version: '0.1.0',
+      agents: agents.length,
+      whatsapp: Object.values(waStatuses).filter(s => s.connected).length,
+      uptime: process.uptime(),
+    });
+  });
+
+  // ── Agents CRUD ──
+  app.get('/api/agents', async (req, res) => {
+    const agents = agentManager.getAll().map(a => ({
+      id: a.id, name: a.name, model: a.model, language: a.language,
+      status: a.status, whatsappNumber: a.whatsappNumber,
+      whatsappConnected: whatsappManager.getStatuses()[a.id]?.connected || false,
+    }));
+    res.json(agents);
+  });
+
+  app.get('/api/agents/:id', async (req, res) => {
+    const agent = agentManager.get(req.params.id);
+    if (!agent) return res.status(404).json({ error: 'Agent not found' });
+    const usage = await storage.getUsage(agent.id, '30d');
+    res.json({
+      id: agent.id, name: agent.name, soul: agent.soul, model: agent.model,
+      language: agent.language, tone: agent.tone, behavior: agent.behavior,
+      timezone: agent.timezone, status: agent.status,
+      whatsappNumber: agent.whatsappNumber,
+      whatsappConnected: whatsappManager.getStatuses()[agent.id]?.connected || false,
+      usage,
+    });
+  });
+
+  app.post('/api/agents', async (req, res) => {
+    try {
+      const agent = await agentManager.create(req.body);
+      res.json({ id: agent.id, name: agent.name, status: 'created' });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.put('/api/agents/:id', async (req, res) => {
+    try {
+      await agentManager.update(req.params.id, req.body);
+      res.json({ status: 'updated' });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  app.delete('/api/agents/:id', async (req, res) => {
+    try {
+      await whatsappManager.stopSession(req.params.id);
+      await agentManager.delete(req.params.id);
+      res.json({ status: 'deleted' });
+    } catch (err) {
+      res.status(400).json({ error: err.message });
+    }
+  });
+
+  // ── Chat ──
+  app.post('/api/agents/:id/chat', async (req, res) => {
+    const agent = agentManager.get(req.params.id);
+    if (!agent) return res.status(404).json({ error: 'Agent not found' });
+
+    const { message, contactId } = req.body;
+    if (!message) return res.status(400).json({ error: 'message required' });
+
+    const sender = contactId || 'dashboard';
+    const result = await agent.processMessage(sender, message, { pushName: 'Dashboard' });
+    res.json({
+      messages: result.messages,
+      reaction: result.reaction,
+      usage: result.usage,
+    });
+  });
+
+  app.get('/api/agents/:id/history', async (req, res) => {
+    const contactId = req.query.contactId || 'dashboard';
+    const limit = parseInt(req.query.limit) || 50;
+    const history = await storage.getConversation(req.params.id, contactId, limit);
+    res.json(history);
+  });
+
+  // ── WhatsApp ──
+  app.post('/api/agents/:id/whatsapp/pair', async (req, res) => {
+    const { phone } = req.body;
+    if (!phone) return res.status(400).json({ error: 'phone required' });
+
+    try {
+      // Start session if not exists
+      await whatsappManager.startSession(req.params.id);
+      // Wait for socket to be ready
+      await new Promise(r => setTimeout(r, 3000));
+      const code = await whatsappManager.requestPairingCode(req.params.id, phone);
+      const formatted = code.length === 8 ? `${code.slice(0, 4)}-${code.slice(4)}` : code;
+      res.json({ pairingCode: formatted, status: 'code_ready' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/agents/:id/whatsapp/start', async (req, res) => {
+    try {
+      await whatsappManager.startSession(req.params.id);
+      res.json({ status: 'starting' });
+    } catch (err) {
+      res.status(500).json({ error: err.message });
+    }
+  });
+
+  app.post('/api/agents/:id/whatsapp/stop', async (req, res) => {
+    await whatsappManager.stopSession(req.params.id);
+    res.json({ status: 'stopped' });
+  });
+
+  app.get('/api/whatsapp/status', (req, res) => {
+    res.json(whatsappManager.getStatuses());
+  });
+
+  // ── Memory ──
+  app.get('/api/agents/:id/memory', async (req, res) => {
+    const memories = await storage.getMemories(req.params.id);
+    res.json(memories);
+  });
+
+  app.delete('/api/agents/:id/memory', async (req, res) => {
+    await storage.clearMemories(req.params.id);
+    res.json({ status: 'cleared' });
+  });
+
+  // ── Knowledge ──
+  app.get('/api/agents/:id/knowledge', async (req, res) => {
+    const docs = await storage.listDocuments(req.params.id);
+    res.json(docs);
+  });
+
+  app.delete('/api/knowledge/:docId', async (req, res) => {
+    await storage.deleteDocument(req.params.docId);
+    res.json({ status: 'deleted' });
+  });
+
+  // ── Usage ──
+  app.get('/api/usage', async (req, res) => {
+    const period = req.query.period || '30d';
+    const agentId = req.query.agentId;
+    if (agentId) {
+      res.json(await storage.getUsage(agentId, period));
+    } else {
+      res.json(await storage.getUsageAll(period));
+    }
+  });
+
+  // ── Handoffs ──
+  app.get('/api/handoffs', async (req, res) => {
+    res.json(await storage.getActiveHandoffs());
+  });
+
+  app.post('/api/handoffs/:id/resolve', async (req, res) => {
+    await storage.resolveHandoff(req.params.id);
+    // Also resolve in agent memory
+    const handoffs = await storage.getActiveHandoffs();
+    const handoff = handoffs.find(h => h.id == req.params.id);
+    if (handoff) {
+      const agent = agentManager.get(handoff.agent_id);
+      agent?.resolveHandoff(handoff.contact_id);
+    }
+    res.json({ status: 'resolved' });
+  });
+
+  // ── Webhooks ──
+  app.get('/api/webhooks', async (req, res) => {
+    res.json(await storage.getWebhooks());
+  });
+
+  app.post('/api/webhooks', async (req, res) => {
+    const { url, events } = req.body;
+    if (!url) return res.status(400).json({ error: 'url required' });
+    const id = await storage.addWebhook(url, events);
+    res.json({ id, status: 'created' });
+  });
+
+  app.delete('/api/webhooks/:id', async (req, res) => {
+    await storage.removeWebhook(req.params.id);
+    res.json({ status: 'deleted' });
+  });
+
+  // ── Contacts ──
+  app.get('/api/agents/:id/contacts', async (req, res) => {
+    res.json(await storage.listContacts(req.params.id));
+  });
+
+  // ── Broadcast ──
+  app.post('/api/agents/:id/broadcast', async (req, res) => {
+    const { message, contactIds } = req.body;
+    if (!message || !contactIds?.length) {
+      return res.status(400).json({ error: 'message and contactIds required' });
+    }
+
+    let sent = 0, failed = 0;
+    for (const contactId of contactIds) {
+      try {
+        await whatsappManager.sendMessage(req.params.id, contactId, message);
+        sent++;
+        // Rate limit: 1 message per 2 seconds
+        await new Promise(r => setTimeout(r, 2000));
+      } catch {
+        failed++;
+      }
+    }
+    res.json({ sent, failed, total: contactIds.length });
+  });
+
+  return app;
+}