madarx 2.24.0 → 2.24.1

package/lib/channels/telegram-adapter.js

@@ -0,0 +1,89 @@
+// @ts-check
+/**
+ * R2 — Telegram channel adapter.
+ *
+ * Transport-only wrapper over the Telegram Bot API. It normalizes inbound Bot API
+ * updates to the canonical {@link ChannelEvent} and sends replies through
+ * `sendMessage`. It carries no routing / allowlist / rate-limit logic — those are
+ * owned by the generic router. Credentials and `fetch` are resolved lazily at send
+ * time so the adapter is fully testable without network or env: inject
+ * `{ token, fetch }` in tests; otherwise `TELEGRAM_BOT_TOKEN` + global `fetch` are
+ * used. Inbound is webhook/poller-driven, so `connect`/`disconnect` are no-ops.
+ */
+
+import { defineAdapter, normalizeInbound } from './contract.js';
+
+/** @typedef {import('./contract.js').ChannelEvent} ChannelEvent */
+
+/**
+ * @typedef {Object} TelegramAdapterConfig
+ * @property {string} [token]   - bot token; falls back to TELEGRAM_BOT_TOKEN at send time
+ * @property {typeof fetch} [fetch] - fetch impl; falls back to global fetch at send time
+ */
+
+/**
+ * Normalize a Telegram Bot API update into a {@link ChannelEvent}.
+ * Accepts a full update (`{ update_id, message: {...} }`), a bare message, or an
+ * already-normalized event. The original payload is preserved by reference.
+ * @param {Record<string, *>} raw
+ * @returns {ChannelEvent}
+ */
+export function normalizeTelegram(raw) {
+  const src = raw && typeof raw === 'object' ? raw : {};
+  const msg = src.message || src.edited_message || src.channel_post || src;
+  const chat = msg?.chat || {};
+  const from = msg?.from || {};
+  const date = msg?.date;
+  const mapped = {
+    chat_id: chat.id,
+    sender: from.id,
+    message_id: msg?.message_id,
+    text: msg?.text ?? msg?.caption,
+    ts: date != null ? new Date(Number(date) * 1000).toISOString() : undefined,
+  };
+  const event = normalizeInbound('telegram', mapped);
+  // Preserve the original top-level payload by reference (mapped was a shim).
+  event.raw = raw;
+  return event;
+}
+
+/**
+ * Create a transport-only Telegram adapter.
+ * @param {TelegramAdapterConfig} [config]
+ * @returns {import('./contract.js').ChannelAdapter}
+ */
+export function createTelegramAdapter(config = {}) {
+  const resolveToken = () => {
+    const token = config.token || process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) throw new Error('telegram adapter: no bot token (set TELEGRAM_BOT_TOKEN or inject { token })');
+    return token;
+  };
+  const resolveFetch = () => {
+    const f = config.fetch || globalThis.fetch;
+    if (typeof f !== 'function') throw new Error('telegram adapter: no fetch available (inject { fetch })');
+    return f;
+  };
+
+  return defineAdapter({
+    channel: 'telegram',
+    // Webhook/poller-driven; nothing persistent to open or close.
+    async connect() { return { ok: true, mode: 'webhook' }; },
+    async disconnect() { return { ok: true }; },
+    /**
+     * @param {string} chatId
+     * @param {string} text
+     */
+    async send(chatId, text) {
+      const token = resolveToken();
+      const res = await resolveFetch()(`https://api.telegram.org/bot${token}/sendMessage`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ chat_id: String(chatId), text }),
+      });
+      const data = /** @type {*} */ (await res.json());
+      const id = data?.result?.message_id;
+      return { ok: data?.ok !== false, message_id: id != null ? String(id) : null, raw: data };
+    },
+    normalizeInbound: normalizeTelegram,
+  });
+}

package/lib/channels/webhook-adapter.js

@@ -0,0 +1,64 @@
+// @ts-check
+/**
+ * R2 — Webhook / generic HTTP API channel adapter.
+ *
+ * Transport-only adapter for arbitrary inbound HTTP payloads (Zapier, custom
+ * integrations, REST callbacks). It normalizes a generic HTTP payload to the
+ * canonical {@link ChannelEvent} and delivers replies through an injected egress
+ * callback. No routing / allowlist / rate-limit logic lives here. The egress
+ * callback resolves lazily at send time: inject `{ send }` in tests and explicit
+ * wiring; otherwise the reply is a no-op ack (there is no fixed outbound endpoint
+ * for a generic webhook channel — the caller supplies one). Inbound is
+ * request-driven, so `connect`/`disconnect` are no-ops.
+ */
+
+import { defineAdapter, normalizeInbound } from './contract.js';
+
+/** @typedef {import('./contract.js').ChannelEvent} ChannelEvent */
+
+/**
+ * @typedef {Object} WebhookAdapterConfig
+ * @property {(chatId: string, text: string) => Promise<*>} [send] - egress callback; falls back to a no-op ack at send time
+ */
+
+/**
+ * Normalize a generic HTTP payload into a {@link ChannelEvent}. Relies on the
+ * canonical field aliasing in {@link normalizeInbound} (e.g. `conversation_id` →
+ * `chat_id`, `body` → `text`, `id` → `message_id`). The original payload is
+ * preserved by reference.
+ * @param {Record<string, *>} raw
+ * @returns {ChannelEvent}
+ */
+export function normalizeWebhook(raw) {
+  const event = normalizeInbound('webhook', raw);
+  event.raw = raw;
+  return event;
+}
+
+/**
+ * Create a transport-only Webhook adapter.
+ * @param {WebhookAdapterConfig} [config]
+ * @returns {import('./contract.js').ChannelAdapter}
+ */
+export function createWebhookAdapter(config = {}) {
+  const send = typeof config.send === 'function' ? config.send : null;
+
+  return defineAdapter({
+    channel: 'webhook',
+    // Request-driven; nothing persistent to open or close.
+    async connect() { return { ok: true, mode: 'http' }; },
+    async disconnect() { return { ok: true }; },
+    /**
+     * @param {string} chatId
+     * @param {string} text
+     */
+    async send(chatId, text) {
+      // With an injected egress callback, the reply leaves through it. Without
+      // one there is no fixed outbound endpoint for a generic webhook channel,
+      // so the reply is acknowledged as a no-op egress result.
+      if (send) return send(String(chatId), text);
+      return { ok: true, message_id: null, egress: 'noop' };
+    },
+    normalizeInbound: normalizeWebhook,
+  });
+}

package/lib/connectivity-status.js

@@ -0,0 +1,110 @@
+import { getBridgeHealth } from './whatsapp.js';
+import { channelAllowlistSummary, listChannelAllowlist, normalizeChannel } from './channel-allowlist.js';
+
+export const CONNECTIVITY_CHANNELS = [
+  {
+    channel: 'whatsapp',
+    label: 'WhatsApp',
+    kind: 'qr_pair',
+    requirements: ['npm run whatsapp:bridge', 'Dedicated WhatsApp number paired through Baileys'],
+  },
+  {
+    channel: 'telegram',
+    label: 'Telegram',
+    kind: 'api_token',
+    env: ['TELEGRAM_BOT_TOKEN'],
+    requirements: ['TELEGRAM_BOT_TOKEN'],
+  },
+  {
+    channel: 'slack',
+    label: 'Slack',
+    kind: 'api_token',
+    env: ['SLACK_BOT_TOKEN'],
+    requirements: ['SLACK_BOT_TOKEN with chat:write and Events API wiring'],
+  },
+  {
+    channel: 'discord',
+    label: 'Discord',
+    kind: 'api_token',
+    env: ['DISCORD_BOT_TOKEN'],
+    requirements: ['DISCORD_BOT_TOKEN'],
+  },
+  {
+    channel: 'imessage',
+    label: 'iMessage',
+    kind: 'local_bridge',
+    requirements: ['macOS Messages account', 'osascript automation permission'],
+  },
+  {
+    channel: 'signal',
+    label: 'Signal',
+    kind: 'local_cli',
+    env: ['SIGNAL_CLI_ACCOUNT'],
+    requirements: ['signal-cli installed', 'SIGNAL_CLI_ACCOUNT registered/linked'],
+  },
+  {
+    channel: 'webhook',
+    label: 'Webhook/API',
+    kind: 'webhook',
+    env: ['MADARX_WEBHOOK_REPLY_URL'],
+    requirements: ['Inbound endpoint or reply callback URL for live response smoke'],
+  },
+];
+
+function envPresent(name) {
+  return Boolean(String(process.env[name] || '').trim());
+}
+
+function channelConfigState(def, health) {
+  if (def.channel === 'whatsapp') {
+    const state = health?.pairing_state || (health?.ok === false ? 'offline' : 'unknown');
+    return {
+      configured: state === 'paired',
+      state,
+      missing: state === 'paired' ? [] : ['whatsapp_pairing'],
+      health: health || null,
+    };
+  }
+  const missing = (def.env || []).filter(name => !envPresent(name));
+  if (def.channel === 'imessage') {
+    const isMac = process.platform === 'darwin';
+    return { configured: isMac, state: isMac ? 'available' : 'unavailable', missing: isMac ? [] : ['macos'] };
+  }
+  return {
+    configured: missing.length === 0,
+    state: missing.length === 0 ? 'configured' : 'missing_requirements',
+    missing,
+  };
+}
+
+export async function getConnectivityStatus({ includeHealth = true } = {}) {
+  let whatsappHealth = null;
+  if (includeHealth) {
+    try { whatsappHealth = await getBridgeHealth(); }
+    catch (err) { whatsappHealth = { ok: false, pairing_state: 'offline', error: err?.message || String(err) }; }
+  }
+  const allowlistCounts = channelAllowlistSummary();
+  const channels = CONNECTIVITY_CHANNELS.map(def => {
+    const state = channelConfigState(def, whatsappHealth);
+    const allowlist_count = allowlistCounts[def.channel] || 0;
+    return {
+      channel: def.channel,
+      label: def.label,
+      kind: def.kind,
+      configured: state.configured,
+      state: state.state,
+      missing: state.missing,
+      requirements: def.requirements,
+      allowlist_count,
+      allowlist_required: true,
+      ready_for_live_smoke: state.configured && allowlist_count > 0,
+      ...(state.health ? { health: state.health } : {}),
+    };
+  });
+  return { ok: true, channels, allowlist: listChannelAllowlist() };
+}
+
+export function getConnectivityChannel(channel) {
+  const ch = normalizeChannel(channel);
+  return CONNECTIVITY_CHANNELS.find(c => c.channel === ch) || null;
+}