@thibautrey/chatons-channel-whatsapp 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# WhatsApp Channel for Chatons
+
+A channel extension that bridges WhatsApp chats as Chatons conversations. Connect via QR code scanning, automatically sync messages, and use Chatons AI to reply to WhatsApp messages.
+
+## Features
+
+- **QR Code Connection**: Scan a QR code with your WhatsApp to securely connect
+- **Message Polling**: Continuously polls WhatsApp for new messages (configurable)
+- **Automatic Reply Mirror**: Sends Chatons AI responses back to WhatsApp
+- **Chat Mapping**: Maps WhatsApp chats to Chatons conversations automatically
+- **Media Support**: Handles media files (photos, videos, documents, audio)
+- **Contact Filtering**: Whitelist specific phone numbers to limit which chats are processed
+- **Background Service**: Runs polling and mirroring even when UI is not visible
+- **Model Selection**: Choose which AI model to use for new conversations
+
+## Installation
+
+1. Clone the repository into your Chatons extensions directory:
+```bash
+cd ~/.chaton/extensions
+git clone https://github.com/thibautrey/chatons-channel-whatsapp.git @thibautrey/chatons-channel-whatsapp
+```
+
+2. Restart Chatons
+
+3. Go to **Channels** > **WhatsApp** to start using the extension
+
+## Configuration
+
+### QR Code Connection
+
+1. Click **"Generate QR Code"** in the WhatsApp Channel UI
+2. Scan the displayed QR code with your WhatsApp phone
+3. The connection will establish automatically when confirmed
+
+### Settings
+
+- **Poll limit**: Number of messages to fetch per polling cycle (1-100, default: 10)
+- **Allowed phone numbers** (optional): Comma-separated list to whitelist specific contacts
+- **Mirror replies**: Enable/disable automatic sending of Chatons responses to WhatsApp
+- **Handle media**: Enable/disable downloading of photos, videos, and documents
+- **Model**: Choose the AI model for new conversations
+
+### Phone Number Whitelist
+
+Leave empty to allow all contacts, or specify comma-separated phone numbers (with or without + prefix):
+```
++1234567890, +0987654321
+1234567890, 0987654321
+```
+
+## How It Works
+
+### Inbound Flow
+1. WhatsApp messages are polled every 5 seconds
+2. Each chat is automatically mapped to a Chatons conversation
+3. The message is ingested and processed by the selected AI model
+4. If a synchronous reply is available, it's immediately sent back to WhatsApp
+
+### Outbound Flow
+1. Every 4 seconds, the extension checks for new AI responses
+2. Any new assistant messages are automatically sent to the original WhatsApp chat
+3. Messages are tracked to avoid duplicates
+
+### Background Service
+- Polling continues even when the UI tab is closed
+- Outbound mirroring runs in the background
+- Keepalive timer ensures services resume if interrupted
+
+## Technical Details
+
+### State Management
+All configuration and state is persisted to Chatons' storage:
+- `whatsapp.config`: Connection settings and status
+- `whatsapp.mappings`: Chat to conversation mappings
+- `whatsapp.lastUpdates`: Recent activity log
+- `whatsapp.outboundMirrorState`: Tracking of sent messages
+
+### Message Deduplication
+- Uses message IDs and timestamps as idempotency keys
+- Tracks which assistant messages have been sent to avoid duplicates
+- Automatically recreates stale conversation mappings
+
+### Error Handling
+- Graceful polling failure handling
+- Automatic connection recovery via keepalive timer
+- Detailed error notifications to user
+
+## Backend Integration
+
+This extension uses a QR-code based connection approach similar to WhatsApp Web. In production, it should integrate with:
+
+- **whatsapp-web.js**: A Node.js library that interfaces with WhatsApp Web
+- **Backend API**: A service that manages WhatsApp Web.js instances and message polling
+
+The current implementation includes mock functions that can be connected to a backend:
+- `initializeWhatsAppSession()`: Generate QR code
+- `pollOnce()`: Fetch new messages
+- `sendWhatsAppMessage()`: Send message to WhatsApp
+
+## Security Considerations
+
+- Session data (including phone number) is stored locally in Chatons' encrypted storage
+- QR codes are session-based and expire after connection
+- No credentials or API keys are stored
+- Messages are only sent to whitelisted contacts (if configured)
+
+## Limitations
+
+- Currently simulates connection (needs backend integration)
+- Media downloading is prepared but needs backend implementation
+- Requires stable internet connection for polling to work
+- QR code changes with each reconnection for security
+
+## Contributing
+
+Please open an issue or pull request to suggest improvements.
+
+## License
+
+MIT

package/chaton.extension.json

@@ -0,0 +1,35 @@
+{
+  "id": "@thibautrey/chatons-channel-whatsapp",
+  "name": "WhatsApp Channel",
+  "version": "1.0.0",
+  "kind": "channel",
+  "description": "WhatsApp channel bridge for Chatons. Connect via QR code scanning, automatically syncs messages, and runs in the background using the shared Chatons UI component library.",
+  "icon": "icon.svg",
+  "capabilities": [
+    "ui.mainView",
+    "queue.publish",
+    "queue.consume",
+    "storage.kv",
+    "host.notifications",
+    "host.conversations.read",
+    "host.conversations.write"
+  ],
+  "ui": {
+    "mainViews": [
+      {
+        "viewId": "whatsapp.main",
+        "title": "WhatsApp",
+        "icon": "MessageCircle",
+        "webviewUrl": "chaton-extension://@thibautrey/chatons-channel-whatsapp/index.html",
+        "initialRoute": "/"
+      }
+    ]
+  },
+  "apis": {
+    "exposes": [
+      { "name": "channels.upsertGlobalThread", "version": "1.0.0" },
+      { "name": "channels.ingestMessage", "version": "1.0.0" },
+      { "name": "conversations.getMessages", "version": "1.0.0" }
+    ]
+  }
+}

package/icon.svg

@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 192 192">
+  <!-- WhatsApp green background -->
+  <defs>
+    <style>
+      .wa-bg { fill: #25D366; }
+      .wa-white { fill: white; }
+      .wa-phone { fill: #25D366; }
+    </style>
+  </defs>
+  
+  <rect class="wa-bg" width="192" height="192" rx="36"/>
+  
+  <!-- Main chat bubble -->
+  <path class="wa-white" d="M 28 20 L 144 20 C 156.7 20 167 30.3 167 43 L 167 127 C 167 139.7 156.7 150 144 150 L 80 150 L 30 180 L 55 150 L 28 150 C 15.3 150 5 139.7 5 127 L 5 43 C 5 30.3 15.3 20 28 20 Z"/>
+  
+  <!-- Phone handset icon inside bubble -->
+  <g transform="translate(50, 60)">
+    <!-- Left curved part of receiver -->
+    <path class="wa-phone" d="M 20 50 Q 8 42 8 28 Q 8 14 20 6 L 32 -6 Q 35 -8 38 -5 L 50 7 Q 52 9 52 12 Q 52 32 32 52 L 35 56 Q 55 36 55 12 Q 55 6 52 0 L 40 -12 Q 35 -16 32 -12 L 20 0 Q 2 10 2 28 Q 2 44 20 56 L 20 50"/>
+    
+    <!-- Right curved part of receiver -->
+    <path class="wa-phone" d="M 60 50 Q 72 42 72 28 Q 72 14 60 6 L 48 -6 Q 45 -8 42 -5 L 30 7 Q 28 9 28 12 Q 28 32 48 52 L 45 56 Q 25 36 25 12 Q 25 6 28 0 L 40 -12 Q 45 -16 48 -12 L 60 0 Q 78 10 78 28 Q 78 44 60 56 L 60 50"/>
+  </g>
+</svg>

package/index.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>WhatsApp Channel</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+        'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+        sans-serif;
+      -webkit-font-smoothing: antialiased;
+      -moz-osx-font-smoothing: grayscale;
+      background: var(--ce-bg, #ffffff);
+      color: var(--ce-fg, #000000);
+    }
+    #app {
+      width: 100%;
+      min-height: 100vh;
+    }
+  </style>
+</head>
+<body>
+  <div id="app"></div>
+  <script src="index.js"></script>
+</body>
+</html>

package/index.js

@@ -0,0 +1,893 @@
+(function () {
+  'use strict';
+
+  // Error handlers
+  window.addEventListener('error', function (event) {
+    try {
+      console.error('[whatsapp-ext] window.error:', event?.message, event?.error?.stack || '');
+    } catch (_) {}
+  });
+  window.addEventListener('unhandledrejection', function (event) {
+    try {
+      console.error('[whatsapp-ext] unhandledrejection:', event?.reason?.stack || String(event?.reason || 'unknown'));
+    } catch (_) {}
+  });
+
+  var EXTENSION_ID = '@thibautrey/chatons-channel-whatsapp';
+  var POLL_INTERVAL_MS = 5000;
+  var OUTBOUND_INTERVAL_MS = 4000;
+  var MAX_STATUS_UPDATES = 30;
+  var KEEPALIVE_INTERVAL_MS = 30000;
+
+  // ============================================================================
+  // STATE MANAGEMENT
+  // ============================================================================
+
+  var state = {
+    polling: false,
+    sending: false,
+    pollTimer: null,
+    outboundTimer: null,
+    keepaliveTimer: null,
+    piUnsubscribe: null,
+    uiRenderFn: null,
+    config: {
+      connected: false,
+      sessionId: '',
+      phoneNumber: '',
+      pollLimit: 10,
+      outboundEnabled: true,
+      downloadMedia: true,
+      modelKey: '',
+      allowedNumbers: '',
+      lastUpdateTimestamp: 0,
+      lastInboundAt: null,
+      lastOutboundAt: null,
+      qrCode: '',
+      connectionStatus: 'disconnected' // disconnected, qr_ready, connected, error
+    },
+    mappings: {},
+    updates: [],
+    lastMirroredMessageByConversation: {},
+  };
+
+  // ============================================================================
+  // UTILITIES
+  // ============================================================================
+
+  function asArray(v) { return Array.isArray(v) ? v : []; }
+  function asRecord(v) { return v && typeof v === 'object' && !Array.isArray(v) ? v : {}; }
+  function safeJsonParse(v, fallback) { try { return JSON.parse(v); } catch (_) { return fallback; } }
+  function nowIso() { return new Date().toISOString(); }
+  function escapeHtml(v) {
+    return String(v || '')
+      .replace(/&/g, '&')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  }
+  function shorten(t, m) { t = String(t || ''); return t.length <= m ? t : t.slice(0, Math.max(0, m - 1)) + '…'; }
+  function relTime(iso) {
+    var ts = Date.parse(iso || '');
+    if (!Number.isFinite(ts)) return 'never';
+    var diff = Date.now() - ts;
+    if (diff < 5000) return 'just now';
+    if (diff < 60000) return Math.floor(diff / 1000) + 's ago';
+    if (diff < 3600000) return Math.floor(diff / 60000) + 'm ago';
+    if (diff < 86400000) return Math.floor(diff / 3600000) + 'h ago';
+    return Math.floor(diff / 86400000) + 'd ago';
+  }
+
+  function parseAllowedNumbers(raw) {
+    return String(raw || '').split(/[\s,]+/).map(function (i) { return i.trim(); }).filter(Boolean);
+  }
+  function normalizePhoneNumber(v) { return v === null || typeof v === 'undefined' ? '' : String(v); }
+  function mappingKeyForChat(phoneOrId) { return 'whatsapp:' + normalizePhoneNumber(phoneOrId); }
+  function isAllowedNumber(phoneOrId) {
+    var allowed = parseAllowedNumbers(state.config.allowedNumbers);
+    if (!allowed.length) return true;
+    return allowed.indexOf(normalizePhoneNumber(phoneOrId)) >= 0;
+  }
+
+  function notify(msg) {
+    if (!msg) return;
+    if (window.chaton && typeof window.chaton.extensionHostCall === 'function') {
+      void window.chaton.extensionHostCall(EXTENSION_ID, 'notifications.notify', {
+        title: 'WhatsApp',
+        body: String(msg)
+      });
+    }
+  }
+
+  // ============================================================================
+  // STORAGE
+  // ============================================================================
+
+  async function kvGet(key, fallback) {
+    var res = await window.chaton.extensionStorageKvGet(EXTENSION_ID, key);
+    if (!res || !res.ok) return fallback;
+    return typeof res.data === 'undefined' || res.data === null ? fallback : res.data;
+  }
+
+  async function kvSet(key, value) {
+    return window.chaton.extensionStorageKvSet(EXTENSION_ID, key, value);
+  }
+
+  async function hostCall(method, params) {
+    return window.chaton.extensionHostCall(EXTENSION_ID, method, params || {});
+  }
+
+  // ============================================================================
+  // PERSISTENCE
+  // ============================================================================
+
+  async function loadPersistedState() {
+    var config = asRecord(await kvGet('whatsapp.config', {}));
+    state.mappings = asRecord(await kvGet('whatsapp.mappings', {}));
+    state.updates = asArray(await kvGet('whatsapp.lastUpdates', [])).slice(0, MAX_STATUS_UPDATES);
+    state.lastMirroredMessageByConversation = asRecord(await kvGet('whatsapp.outboundMirrorState', {}));
+    state.config = {
+      connected: config.connected === true,
+      sessionId: typeof config.sessionId === 'string' ? config.sessionId : '',
+      phoneNumber: typeof config.phoneNumber === 'string' ? config.phoneNumber : '',
+      pollLimit: typeof config.pollLimit === 'number' ? config.pollLimit : 10,
+      outboundEnabled: config.outboundEnabled !== false,
+      downloadMedia: config.downloadMedia !== false,
+      modelKey: typeof config.modelKey === 'string' ? config.modelKey : '',
+      allowedNumbers: asArray(config.allowedNumbers).join(', '),
+      lastUpdateTimestamp: typeof config.lastUpdateTimestamp === 'number' ? config.lastUpdateTimestamp : 0,
+      lastInboundAt: typeof config.lastInboundAt === 'string' ? config.lastInboundAt : null,
+      lastOutboundAt: typeof config.lastOutboundAt === 'string' ? config.lastOutboundAt : null,
+      qrCode: '',
+      connectionStatus: config.connected ? 'connected' : 'disconnected'
+    };
+  }
+
+  async function persistConfig(extra) {
+    var payload = {
+      connected: state.config.connected,
+      sessionId: state.config.sessionId,
+      phoneNumber: state.config.phoneNumber,
+      pollLimit: state.config.pollLimit,
+      outboundEnabled: state.config.outboundEnabled,
+      downloadMedia: state.config.downloadMedia,
+      modelKey: state.config.modelKey,
+      allowedNumbers: parseAllowedNumbers(state.config.allowedNumbers),
+      lastUpdateTimestamp: state.config.lastUpdateTimestamp,
+      lastInboundAt: state.config.lastInboundAt,
+      lastOutboundAt: state.config.lastOutboundAt,
+      updatedAt: nowIso()
+    };
+    if (extra && typeof extra === 'object') {
+      Object.keys(extra).forEach(function (k) { payload[k] = extra[k]; });
+    }
+    await kvSet('whatsapp.config', payload);
+  }
+
+  async function saveMappings() { await kvSet('whatsapp.mappings', state.mappings); }
+  async function saveUpdates() { await kvSet('whatsapp.lastUpdates', state.updates.slice(0, MAX_STATUS_UPDATES)); }
+  async function saveMirrorState() { await kvSet('whatsapp.outboundMirrorState', state.lastMirroredMessageByConversation); }
+
+  // ============================================================================
+  // WhatsApp BACKEND SIMULATION (in production, use Whatsapp Web.js or similar)
+  // ============================================================================
+
+  async function generateQrCode() {
+    // In production, use your backend service that generates QR codes
+    // For now, use qrserver.com API to generate a proper QR code
+    // The QR code will encode the session ID
+    
+    try {
+      var sessionId = state.config.sessionId || 'whatsapp-' + Date.now();
+      // Generate a QR code using the public QR server API
+      // The data encodes the session ID which backend will validate
+      var qrData = 'https://whatsapp-session.local/' + encodeURIComponent(sessionId);
+      var qrUrl = 'https://api.qrserver.com/v1/create-qr-code/?size=300x300&data=' + encodeURIComponent(qrData);
+      
+      state.config.sessionId = sessionId;
+      state.config.qrCode = qrUrl;
+      state.config.connectionStatus = 'qr_ready';
+      return qrUrl;
+    } catch (error) {
+      console.error('[whatsapp-ext] QR generation error:', error);
+      return null;
+    }
+  }
+
+  async function initializeWhatsAppSession() {
+    // In production, this would initialize whatsapp-web.js and generate QR
+    // Mock implementation for demonstration
+    try {
+      var qr = await generateQrCode();
+      notify('QR Code generated. Scan with your phone to connect.');
+      if (state.uiRenderFn) state.uiRenderFn();
+      return { ok: true, qrCode: qr };
+    } catch (error) {
+      state.config.connectionStatus = 'error';
+      notify('Failed to generate QR code: ' + (error instanceof Error ? error.message : String(error)));
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  async function simulateQrScanned(phoneNumber) {
+    // Mock session creation
+    state.config.sessionId = 'session-' + Date.now();
+    state.config.phoneNumber = phoneNumber;
+    state.config.connected = true;
+    state.config.connectionStatus = 'connected';
+    state.config.qrCode = '';
+    await persistConfig();
+    notify('✓ WhatsApp connected as ' + phoneNumber);
+  }
+
+  // ============================================================================
+  // MESSAGE INGESTION
+  // ============================================================================
+
+  async function ensureConversationForMessage(chatId, chatName) {
+    var key = mappingKeyForChat(chatId);
+    var existing = asRecord(state.mappings[key]);
+    if (existing.chatonsConversationId) {
+      console.log('[whatsapp-ext] ensureConversation: reusing existing conversation', { key: key, conversationId: existing.chatonsConversationId });
+      return { key: key, conversationId: String(existing.chatonsConversationId) };
+    }
+
+    var title = shorten('WhatsApp - ' + (chatName || chatId), 72);
+    console.log('[whatsapp-ext] ensureConversation: creating new thread', { key: key, title: title, modelKey: state.config.modelKey });
+    var res = await hostCall('channels.upsertGlobalThread', {
+      mappingKey: key,
+      title: title,
+      modelKey: state.config.modelKey || undefined
+    });
+
+    if (!res || !res.ok || !res.data || !res.data.conversation) {
+      console.error('[whatsapp-ext] upsertGlobalThread response:', JSON.stringify(res, null, 2));
+      throw new Error((res && res.error && res.error.message) || 'Unable to create conversation');
+    }
+
+    return { key: key, conversationId: res.data.conversation.id };
+  }
+
+  function buildWhatsAppText(message) {
+    var parts = [];
+    if (typeof message.text === 'string' && message.text.trim()) {
+      parts.push(message.text.trim());
+    }
+    if (message.hasMedia) {
+      parts.push('');
+      parts.push('**Attachment:** ' + (message.mediaType || 'file') + (message.mediaName ? ' (' + message.mediaName + ')' : ''));
+    }
+    return parts.length ? parts.join('\n') : '[WhatsApp message without text content]';
+  }
+
+  async function ingestNormalizedMessage(message) {
+    var chatId = message.chatId;
+    if (!isAllowedNumber(chatId)) return { skipped: true, reason: 'number_not_allowed' };
+
+    var remoteUserId = message.fromId;
+    var remoteUserName = message.fromName;
+    var text = buildWhatsAppText(message);
+    var ensured = await ensureConversationForMessage(chatId, message.chatName);
+    var idempotencyKey = String(message.messageId) + ':' + String(message.timestamp || 0);
+
+    console.log('[whatsapp-ext] ingestNormalizedMessage: about to ingest', {
+      conversationId: ensured.conversationId,
+      messageId: message.messageId,
+      idempotencyKey: idempotencyKey,
+      textLength: text.length
+    });
+
+    var ingestRes = await hostCall('channels.ingestMessage', {
+      conversationId: ensured.conversationId,
+      message: text,
+      idempotencyKey: idempotencyKey,
+      metadata: {
+        provider: 'whatsapp',
+        messageId: message.messageId,
+        chatId: chatId,
+        fromId: remoteUserId,
+        fromName: remoteUserName,
+        hasMedia: message.hasMedia,
+      }
+    });
+
+    if (!ingestRes || !ingestRes.ok) {
+      console.error('[whatsapp-ext] ingestMessage response:', JSON.stringify(ingestRes, null, 2));
+      var errMsg = (ingestRes && ingestRes.message) || (ingestRes && ingestRes.error && ingestRes.error.message) || '';
+      if (errMsg && errMsg.toLowerCase().includes('conversation not found')) {
+        var staleKey = mappingKeyForChat(chatId);
+        console.warn('[whatsapp-ext] stale mapping detected, clearing and retrying', { key: staleKey });
+        delete state.mappings[staleKey];
+        await saveMappings();
+        var retried = await ensureConversationForMessage(chatId, message.chatName);
+        var retryRes = await hostCall('channels.ingestMessage', {
+          conversationId: retried.conversationId,
+          message: text,
+          idempotencyKey: idempotencyKey,
+          metadata: {
+            provider: 'whatsapp',
+            messageId: message.messageId,
+            chatId: chatId,
+            fromId: remoteUserId,
+            fromName: remoteUserName,
+            hasMedia: message.hasMedia,
+          }
+        });
+        if (!retryRes || !retryRes.ok) {
+          throw new Error('Failed to ingest message after retry: ' + JSON.stringify(retryRes));
+        }
+        ingestRes = retryRes;
+        ensured = retried;
+      } else {
+        throw new Error('Failed to ingest message: ' + (ingestRes ? JSON.stringify(ingestRes) : 'no response'));
+      }
+    }
+
+    state.mappings[mappingKeyForChat(chatId)] = {
+      remoteThreadId: normalizePhoneNumber(chatId),
+      remoteChatName: message.chatName || '',
+      remoteUserId: remoteUserId,
+      remoteUserName: remoteUserName,
+      chatonsConversationId: ensured.conversationId,
+      updatedAt: nowIso(),
+    };
+    await saveMappings();
+
+    state.config.lastInboundAt = nowIso();
+    await persistConfig({ lastInboundAt: state.config.lastInboundAt, connected: true });
+
+    state.updates.unshift({
+      direction: 'inbound',
+      at: nowIso(),
+      chatId: normalizePhoneNumber(chatId),
+      user: remoteUserName,
+      textPreview: shorten(text.replace(/\s+/g, ' ').trim(), 100),
+      messageId: message.messageId,
+      conversationId: ensured.conversationId,
+      hasMedia: message.hasMedia
+    });
+    state.updates = state.updates.slice(0, MAX_STATUS_UPDATES);
+    await saveUpdates();
+
+    // Handle synchronous reply if available
+    var directReply = ingestRes && typeof ingestRes.reply === 'string' ? ingestRes.reply.trim() : '';
+    if (directReply && state.config.outboundEnabled) {
+      await sendWhatsAppMessage(normalizePhoneNumber(chatId), directReply, ensured.conversationId);
+      var messagesRes = await hostCall('conversations.getMessages', { conversationId: ensured.conversationId });
+      if (messagesRes && messagesRes.ok && Array.isArray(messagesRes.data)) {
+        var assistantMessages = messagesRes.data.filter(function(m) { return m && m.role === 'assistant'; });
+        var latest = assistantMessages.length ? assistantMessages[assistantMessages.length - 1] : null;
+        if (latest && latest.id) {
+          state.lastMirroredMessageByConversation[ensured.conversationId] = latest.id;
+          await saveMirrorState();
+        }
+      }
+    }
+  }
+
+  // ============================================================================
+  // POLLING
+  // ============================================================================
+
+  async function pollOnce() {
+    if (state.polling || !state.config.connected) return;
+    state.polling = true;
+
+    try {
+      // In production, this would call a backend API that queries WhatsApp Web.js
+      // For now, simulate no new messages
+      console.log('[whatsapp-ext] polling for messages...');
+      // Simulated: no messages
+      state.config.lastUpdateTimestamp = Date.now();
+    } catch (error) {
+      console.error('[whatsapp-ext] poll error:', error);
+      notify('WhatsApp poll error: ' + (error instanceof Error ? error.message : String(error)));
+    } finally {
+      state.polling = false;
+      if (state.uiRenderFn) state.uiRenderFn();
+    }
+  }
+
+  function startPolling() {
+    if (state.pollTimer) return;
+    state.pollTimer = setInterval(function () { void pollOnce(); }, POLL_INTERVAL_MS);
+    void pollOnce();
+  }
+
+  function stopPolling() {
+    if (state.pollTimer) {
+      clearInterval(state.pollTimer);
+      state.pollTimer = null;
+    }
+  }
+
+  // ============================================================================
+  // OUTBOUND MIRRORING
+  // ============================================================================
+
+  function extractAssistantText(payload) {
+    if (!payload) return '';
+    if (typeof payload.content === 'string') return payload.content.trim();
+    if (Array.isArray(payload.content)) {
+      return payload.content
+        .map(function (i) {
+          if (!i) return '';
+          if (typeof i === 'string') return i;
+          if (i.type === 'text' && typeof i.text === 'string') return i.text;
+          return '';
+        })
+        .join('\n')
+        .trim();
+    }
+    if (typeof payload.text === 'string') return payload.text.trim();
+    if (typeof payload.message === 'string') return payload.message.trim();
+    return '';
+  }
+
+  async function sendWhatsAppMessage(chatId, text, conversationId) {
+    // In production, this would use WhatsApp Web.js client.sendMessage(chatId, text)
+    console.log('[whatsapp-ext] sendWhatsAppMessage to', chatId, ':', text);
+    state.config.lastOutboundAt = nowIso();
+    await persistConfig({ lastOutboundAt: state.config.lastOutboundAt });
+  }
+
+  async function mirrorOutboundReplies() {
+    if (!state.config.connected || !state.config.outboundEnabled || state.sending) return;
+    state.sending = true;
+
+    try {
+      var mappingKeys = Object.keys(state.mappings || {});
+      for (var i = 0; i < mappingKeys.length; i++) {
+        var key = mappingKeys[i];
+        var mapping = asRecord(state.mappings[key]);
+        var conversationId = typeof mapping.chatonsConversationId === 'string' ? mapping.chatonsConversationId : '';
+        var remoteThreadId = typeof mapping.remoteThreadId === 'string' ? mapping.remoteThreadId : '';
+        if (!conversationId || !remoteThreadId) continue;
+
+        var messagesRes = await hostCall('conversations.getMessages', { conversationId: conversationId });
+        if (!messagesRes || !messagesRes.ok || !Array.isArray(messagesRes.data)) continue;
+
+        var assistantMessages = messagesRes.data.filter(function (m) { return m && m.role === 'assistant'; });
+        if (!assistantMessages.length) continue;
+
+        var latest = assistantMessages[assistantMessages.length - 1];
+        if (!latest || !latest.id) continue;
+        if (state.lastMirroredMessageByConversation[conversationId] === latest.id) continue;
+
+        var payload = safeJsonParse(latest.payloadJson || '{}', {});
+        var text = extractAssistantText(payload);
+        if (!text) continue;
+
+        await sendWhatsAppMessage(remoteThreadId, text, conversationId);
+        state.lastMirroredMessageByConversation[conversationId] = latest.id;
+        await saveMirrorState();
+
+        state.updates.unshift({
+          direction: 'outbound',
+          at: nowIso(),
+          chatId: remoteThreadId,
+          user: 'Chatons',
+          textPreview: shorten(text.replace(/\s+/g, ' ').trim(), 100),
+          conversationId: conversationId,
+          hasMedia: false
+        });
+        state.updates = state.updates.slice(0, MAX_STATUS_UPDATES);
+        await saveUpdates();
+      }
+    } catch (error) {
+      console.error('[whatsapp-ext] mirror error:', error);
+    } finally {
+      state.sending = false;
+      if (state.uiRenderFn) state.uiRenderFn();
+    }
+  }
+
+  function startOutboundLoop() {
+    if (state.outboundTimer) return;
+    state.outboundTimer = setInterval(function () { void mirrorOutboundReplies(); }, OUTBOUND_INTERVAL_MS);
+  }
+
+  function stopOutboundLoop() {
+    if (state.outboundTimer) {
+      clearInterval(state.outboundTimer);
+      state.outboundTimer = null;
+    }
+  }
+
+  // ============================================================================
+  // KEEPALIVE & Pi EVENT LISTENER
+  // ============================================================================
+
+  function startPiMirrorListener() {
+    if (state.piUnsubscribe || !window.chaton || typeof window.chaton.onPiEvent !== 'function') return;
+    state.piUnsubscribe = window.chaton.onPiEvent(function (event) {
+      try {
+        if (!event || !event.event || event.event.type !== 'agent_end') return;
+        void mirrorOutboundReplies();
+      } catch (error) {
+        console.error('[whatsapp-ext] pi listener error:', error);
+      }
+    });
+  }
+
+  function startKeepalive() {
+    if (state.keepaliveTimer) return;
+    state.keepaliveTimer = setInterval(function () {
+      if (state.config.connected && !state.pollTimer) {
+        console.log('[whatsapp-ext] keepalive: resuming polling');
+        startPolling();
+      }
+    }, KEEPALIVE_INTERVAL_MS);
+  }
+
+  function stopKeepalive() {
+    if (state.keepaliveTimer) {
+      clearInterval(state.keepaliveTimer);
+      state.keepaliveTimer = null;
+    }
+  }
+
+  function stopAllBackgroundServices() {
+    stopPolling();
+    stopOutboundLoop();
+    stopKeepalive();
+    if (state.piUnsubscribe) {
+      state.piUnsubscribe();
+      state.piUnsubscribe = null;
+    }
+  }
+
+  // ============================================================================
+  // UI
+  // ============================================================================
+
+  var app = document.getElementById('app');
+
+  function render() {
+    if (!app) return;
+
+    var UI = window.chatonExtensionComponents;
+    if (!UI) {
+      app.innerHTML = '<div style="padding:24px">Component library not loaded</div>';
+      return;
+    }
+
+    UI.ensureStyles();
+    var clear = function (node) { while (node.firstChild) node.removeChild(node.firstChild); };
+
+    clear(app);
+    var root = UI.el('div', 'ce-page');
+
+    // Header
+    var header = UI.el('div', 'ce-page-header');
+    var titleGroup = UI.el('div', 'ce-page-title-group');
+    titleGroup.appendChild(UI.el('h1', 'ce-page-title', 'WhatsApp Channel'));
+    titleGroup.appendChild(UI.el('p', 'ce-page-description', 'Bridge WhatsApp chats as Chatons conversations. Scan QR code to connect and automatically sync messages.'));
+    header.appendChild(titleGroup);
+
+    var statusBadge = UI.createBadge({
+      variant: state.config.connected ? 'default' : 'secondary',
+      text: state.config.connected ? '✓ Connected' : (state.config.connectionStatus === 'qr_ready' ? '⚙ QR Ready' : '○ Not connected')
+    });
+    header.appendChild(statusBadge);
+    root.appendChild(header);
+
+    // KPIs
+    var kpis = UI.el('div', 'ce-grid ce-grid--2');
+    [
+      ['Mapped chats', String(Object.keys(state.mappings).length)],
+      ['Polling', state.pollTimer ? 'On' : 'Off'],
+      ['Outbound sync', state.config.outboundEnabled ? 'Enabled' : 'Disabled'],
+      ['Last inbound', relTime(state.config.lastInboundAt)]
+    ].forEach(function (entry) {
+      var card = UI.el('div', 'ce-card');
+      card.appendChild(UI.el('div', 'ce-card__body'));
+      card.querySelector('.ce-card__body').innerHTML =
+        '<div class="ce-section-copy">' + escapeHtml(entry[0]) + '</div>' +
+        '<div style="font-size:18px;font-weight:600;margin-top:8px">' + escapeHtml(entry[1]) + '</div>';
+      kpis.appendChild(card);
+    });
+    root.appendChild(kpis);
+
+    // QR Code Section (if not connected)
+    if (!state.config.connected) {
+      var qrCard = UI.createCard();
+      qrCard.root.className += ' ce-card';
+      qrCard.body.innerHTML = '<h2 class="ce-section-title">Connect via QR Code</h2>';
+      
+      var qrContainer = UI.el('div', '');
+      qrContainer.style.textAlign = 'center';
+      qrContainer.style.padding = '24px';
+      
+      if (state.config.connectionStatus === 'qr_ready' && state.config.qrCode) {
+        var qrImg = UI.el('img', '');
+        // QR code can be:
+        // - data: URL (base64 or SVG)
+        // - blob: URL (browser object URL)
+        // - https: URL (remote server or API)
+        qrImg.src = state.config.qrCode;
+        qrImg.style.maxWidth = '300px';
+        qrImg.style.height = 'auto';
+        qrImg.style.border = '2px solid #25D366';
+        qrImg.style.borderRadius = '8px';
+        qrImg.style.backgroundColor = 'white';
+        qrImg.style.padding = '8px';
+        qrContainer.appendChild(qrImg);
+        qrContainer.appendChild(UI.el('p', '', 'Scan this code with your WhatsApp to connect'));
+      } else {
+        qrContainer.appendChild(UI.el('p', '', 'Click "Generate QR Code" to get started'));
+      }
+      
+      qrCard.body.appendChild(qrContainer);
+      
+      var generateBtn = UI.createButton({ text: 'Generate QR Code', variant: 'default' });
+      generateBtn.onclick = async function () {
+        try {
+          var res = await initializeWhatsAppSession();
+          if (res.ok) {
+            render();
+          }
+        } catch (error) {
+          notify('Failed to generate QR: ' + (error instanceof Error ? error.message : String(error)));
+        }
+      };
+      
+      qrCard.body.appendChild(generateBtn);
+      root.appendChild(qrCard.root);
+    }
+
+    // Configuration Section
+    var setupCard = UI.createCard();
+    setupCard.root.className += ' ce-card';
+    setupCard.body.innerHTML = '<h2 class="ce-section-title">Configuration</h2>';
+
+    var pollLimitInput = UI.el('input', '');
+    pollLimitInput.id = 'pollLimitInput';
+    pollLimitInput.type = 'number';
+    pollLimitInput.min = '1';
+    pollLimitInput.max = '100';
+    pollLimitInput.value = String(state.config.pollLimit || 10);
+    setupCard.body.appendChild((function() {
+      var f = UI.el('div', 'ce-field');
+      f.appendChild(UI.el('label', 'ce-label', 'Poll limit (messages per cycle)'));
+      f.appendChild(pollLimitInput);
+      f.appendChild(UI.el('div', 'ce-help', '1-100 messages fetched every 5 seconds'));
+      return f;
+    })());
+
+    var allowedNumbersInput = UI.el('textarea', '');
+    allowedNumbersInput.id = 'allowedNumbersInput';
+    allowedNumbersInput.placeholder = 'Leave empty to allow all, or paste comma-separated phone numbers';
+    allowedNumbersInput.value = state.config.allowedNumbers || '';
+    setupCard.body.appendChild((function() {
+      var f = UI.el('div', 'ce-field');
+      f.appendChild(UI.el('label', 'ce-label', 'Allowed phone numbers (optional)'));
+      f.appendChild(allowedNumbersInput);
+      f.appendChild(UI.el('div', 'ce-help', 'Whitelist specific contacts. Leave blank to allow all.'));
+      return f;
+    })());
+
+    // Model picker
+    var modelWrap = UI.el('div', 'ce-field');
+    modelWrap.appendChild(UI.el('label', 'ce-label', 'Model for new conversations'));
+    var modelHost = UI.el('div', '');
+    modelHost.id = 'modelPickerHost';
+    modelWrap.appendChild(modelHost);
+    setupCard.body.appendChild(modelWrap);
+
+    // Checkboxes
+    var outboundChk = UI.el('input', '');
+    outboundChk.id = 'outboundEnabledInput';
+    outboundChk.type = 'checkbox';
+    outboundChk.checked = state.config.outboundEnabled;
+    var outboundLabel = UI.el('label', '');
+    outboundLabel.style.display = 'flex';
+    outboundLabel.style.alignItems = 'center';
+    outboundLabel.style.gap = '10px';
+    outboundLabel.appendChild(outboundChk);
+    outboundLabel.appendChild(UI.el('span', '', 'Mirror Chatons replies back to WhatsApp'));
+    setupCard.body.appendChild((function() {
+      var w = UI.el('div', 'ce-field');
+      w.appendChild(outboundLabel);
+      return w;
+    })());
+
+    var mediaChk = UI.el('input', '');
+    mediaChk.id = 'downloadMediaInput';
+    mediaChk.type = 'checkbox';
+    mediaChk.checked = state.config.downloadMedia;
+    var mediaLabel = UI.el('label', '');
+    mediaLabel.style.display = 'flex';
+    mediaLabel.style.alignItems = 'center';
+    mediaLabel.style.gap = '10px';
+    mediaLabel.appendChild(mediaChk);
+    mediaLabel.appendChild(UI.el('span', '', 'Handle media (photos, videos, documents)'));
+    setupCard.body.appendChild((function() {
+      var w = UI.el('div', 'ce-field');
+      w.appendChild(mediaLabel);
+      return w;
+    })());
+
+    // Buttons
+    var toolbar = UI.el('div', 'ce-toolbar');
+    toolbar.style.marginTop = '16px';
+
+    if (state.config.connected) {
+      var saveBtn = UI.createButton({ text: 'Save Settings', variant: 'default' });
+      saveBtn.onclick = async function () {
+        try {
+          state.config.pollLimit = Math.max(1, Math.min(100, Number(pollLimitInput.value) || 10));
+          state.config.allowedNumbers = String(allowedNumbersInput.value || '');
+          state.config.outboundEnabled = !!outboundChk.checked;
+          state.config.downloadMedia = !!mediaChk.checked;
+          if (state.modelPicker && typeof state.modelPicker.getSelected === 'function') {
+            state.config.modelKey = state.modelPicker.getSelected() || '';
+          }
+          await persistConfig();
+          notify('✓ Settings saved');
+          render();
+        } catch (error) {
+          notify('✗ Failed to save: ' + (error instanceof Error ? error.message : String(error)));
+        }
+      };
+
+      var pollNowBtn = UI.createButton({ text: 'Poll now', variant: 'outline' });
+      pollNowBtn.onclick = async function () { await pollOnce(); render(); };
+
+      var disconnectBtn = UI.createButton({ text: 'Disconnect', variant: 'ghost' });
+      disconnectBtn.onclick = async function () {
+        state.config.connected = false;
+        state.config.connectionStatus = 'disconnected';
+        state.config.sessionId = '';
+        state.config.qrCode = '';
+        await persistConfig({ connected: false, sessionId: '', connectionStatus: 'disconnected' });
+        stopAllBackgroundServices();
+        notify('Disconnected from WhatsApp');
+        render();
+      };
+
+      toolbar.appendChild(saveBtn);
+      toolbar.appendChild(pollNowBtn);
+      toolbar.appendChild(disconnectBtn);
+    }
+
+    setupCard.body.appendChild(toolbar);
+    root.appendChild(setupCard.root);
+
+    // Diagnostics
+    if (state.config.connected) {
+      var diagCard = UI.createCard();
+      diagCard.root.className += ' ce-card';
+      diagCard.body.innerHTML = '<h2 class="ce-section-title">Status & Diagnostics</h2>';
+      diagCard.body.innerHTML += '<div style="display:grid;gap:12px;margin-top:12px">' +
+        '<div><div class="ce-section-copy">Phone Number</div><div style="font-family:monospace;font-size:12px">' + escapeHtml(state.config.phoneNumber || 'unknown') + '</div></div>' +
+        '<div><div class="ce-section-copy">Last inbound</div><div style="font-family:monospace;font-size:12px">' + escapeHtml(state.config.lastInboundAt ? relTime(state.config.lastInboundAt) : 'never') + '</div></div>' +
+        '<div><div class="ce-section-copy">Last outbound</div><div style="font-family:monospace;font-size:12px">' + escapeHtml(state.config.lastOutboundAt ? relTime(state.config.lastOutboundAt) : 'never') + '</div></div>' +
+        '<div><div class="ce-section-copy">Session ID</div><div style="font-family:monospace;font-size:12px">' + escapeHtml(state.config.sessionId || 'none') + '</div></div>' +
+        '</div>';
+      root.appendChild(diagCard.root);
+
+      // Thread Mappings
+      var mappingsCard = UI.createCard();
+      mappingsCard.root.className += ' ce-card';
+      mappingsCard.body.innerHTML = '<h2 class="ce-section-title">Mapped chats</h2>';
+      var mappingList = UI.el('div', 'ce-list');
+      var mappingKeys = Object.keys(state.mappings || {});
+      if (!mappingKeys.length) {
+        mappingList.appendChild(UI.el('div', 'ce-empty', 'No mapped WhatsApp chats yet'));
+      } else {
+        mappingKeys.forEach(function (key) {
+          var mapping = asRecord(state.mappings[key]);
+          var row = UI.el('div', 'ce-list-row');
+          row.innerHTML =
+            '<div class="ce-list-row__main">' +
+            '<div class="ce-list-row__content">' +
+            '<div class="ce-list-row__title">' + escapeHtml(String(mapping.remoteChatName || mapping.remoteUserName || key)) + '</div>' +
+            '<div class="ce-list-row__meta">Chat ' + escapeHtml(String(mapping.remoteThreadId || '?')) + ' → ' + escapeHtml(String(mapping.chatonsConversationId || '?')) + '</div>' +
+            '<div class="ce-list-row__meta" style="margin-top:6px">Updated ' + escapeHtml(relTime(mapping.updatedAt || '')) + '</div>' +
+            '</div>' +
+            '</div>';
+          mappingList.appendChild(row);
+        });
+      }
+      mappingsCard.body.appendChild(mappingList);
+      root.appendChild(mappingsCard.root);
+
+      // Activity
+      var activityCard = UI.createCard();
+      activityCard.root.className += ' ce-card';
+      activityCard.body.innerHTML = '<h2 class="ce-section-title">Recent activity</h2>';
+      var activityList = UI.el('div', 'ce-list');
+      if (!state.updates.length) {
+        activityList.appendChild(UI.el('div', 'ce-empty', 'No activity yet'));
+      } else {
+        state.updates.forEach(function (entry) {
+          var row = UI.el('div', 'ce-list-row');
+          row.innerHTML =
+            '<div class="ce-list-row__main">' +
+            '<div class="ce-list-row__content">' +
+            '<div class="ce-list-row__title">' + escapeHtml(String(entry.direction || '?')) + ' • ' + escapeHtml(String(entry.user || '?')) + '</div>' +
+            '<div class="ce-list-row__meta">' + escapeHtml(relTime(entry.at || '')) + '</div>' +
+            '<div style="margin-top:8px;color:var(--ce-fg)">' + escapeHtml(String(entry.textPreview || '')) + '</div>' +
+            '</div>' +
+            '</div>';
+          activityList.appendChild(row);
+        });
+      }
+      activityCard.body.appendChild(activityList);
+      root.appendChild(activityCard.root);
+    }
+
+    app.appendChild(root);
+
+    // Initialize model picker
+    if (window.chatonUi && typeof window.chatonUi.createModelPicker === 'function') {
+      if (state.modelPicker && typeof state.modelPicker.destroy === 'function') state.modelPicker.destroy();
+      state.modelPicker = window.chatonUi.createModelPicker({
+        host: document.getElementById('modelPickerHost'),
+        onChange: function (modelKey) {
+          state.config.modelKey = modelKey || '';
+          persistConfig().catch(function (err) {
+            console.error('[whatsapp-ext] failed to persist model selection:', err);
+          });
+        },
+        labels: {
+          filterPlaceholder: 'Filter models...',
+          more: 'more',
+          scopedOnly: 'scoped only',
+          noScoped: 'No scoped models',
+          noModels: 'No models available'
+        }
+      });
+      window.chaton.listPiModels().then(function (res) {
+        if (!res || !res.ok || !state.modelPicker) return;
+        state.modelPicker.setModels(res.models || []);
+        state.modelPicker.setSelected(state.config.modelKey || null);
+      }).catch(function (err) {
+        console.error('[whatsapp-ext] failed to list models:', err);
+      });
+    }
+  }
+
+  // ============================================================================
+  // INITIALIZATION
+  // ============================================================================
+
+  async function init() {
+    if (!window.chaton) {
+      if (app) app.innerHTML = '<div style="padding:24px;font-family:system-ui">Chatons bridge unavailable</div>';
+      throw new Error('window.chaton is not available');
+    }
+
+    await loadPersistedState();
+
+    console.log('[whatsapp-ext] initialized state:', {
+      connected: state.config.connected,
+      phoneNumber: state.config.phoneNumber,
+      modelKey: state.config.modelKey,
+      outboundEnabled: state.config.outboundEnabled
+    });
+
+    state.uiRenderFn = function () { if (app) render(); };
+
+    if (app) render();
+
+    startOutboundLoop();
+    startPiMirrorListener();
+    startKeepalive();
+
+    if (state.config.connected) {
+      console.log('[whatsapp-ext] resuming polling (already connected)');
+      startPolling();
+    }
+
+    window.addEventListener('beforeunload', function () {
+      void persistConfig();
+    });
+
+    console.log('[whatsapp-ext] initialized. connected=' + state.config.connected);
+  }
+
+  void init();
+})();

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@thibautrey/chatons-channel-whatsapp",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "WhatsApp channel bridge for Chatons. Connect via QR code, automatically syncs messages, and runs in the background using the shared Chatons UI component library.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "index.html",
+    "icon.svg",
+    "chaton.extension.json",
+    "README.md"
+  ],
+  "keywords": [
+    "chatons",
+    "extension",
+    "channel",
+    "whatsapp",
+    "bridge",
+    "messaging",
+    "qr-code"
+  ],
+  "author": "Thibaut Rey",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thibautrey/chatons-channel-whatsapp"
+  },
+  "bugs": {
+    "url": "https://github.com/thibautrey/chatons-channel-whatsapp/issues"
+  },
+  "homepage": "https://github.com/thibautrey/chatons-channel-whatsapp",
+  "chatonExtension": {
+    "kind": "channel",
+    "capabilities": [
+      "ui.mainView",
+      "queue.publish",
+      "queue.consume",
+      "storage.kv",
+      "host.notifications",
+      "host.conversations.read",
+      "host.conversations.write"
+    ]
+  }
+}