@worca/ui 0.9.0 → 0.11.0

package/server/integrations/adapters/discord.js

@@ -0,0 +1,109 @@
+/**
+ * Discord adapter — outbound only, REST POST /channels/{id}/messages (markdown).
+ * @module adapters/discord
+ */
+
+const DISCORD_API = 'https://discord.com/api/v10';
+const SEND_BACKOFF_DELAYS = [1000, 5000, 30000];
+
+// ---------------------------------------------------------------------------
+// Markdown renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a NormalizedMessage to Discord markdown.
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {string}
+ */
+export function renderToMarkdown(msg) {
+  const parts = [];
+  if (msg.title) {
+    parts.push(`**${msg.title}**\n`);
+  }
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(seg.value);
+        break;
+      case 'bold':
+        parts.push(`**${seg.value}**`);
+        break;
+      case 'code':
+        parts.push(`\`${seg.value}\``);
+        break;
+      case 'code_block':
+        parts.push(`\`\`\`\n${seg.value}\n\`\`\``);
+        break;
+      case 'link':
+        parts.push(`[${seg.value}](${seg.href ?? ''})`);
+        break;
+      default: // 'text'
+        parts.push(seg.value);
+    }
+  }
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   botToken: string,
+ *   channelId?: string,
+ *   fetchFn?: typeof fetch,
+ *   _sleep?: (ms: number) => Promise<void>
+ * }} options
+ * @returns {import('../adapter.js').ChatAdapter}
+ */
+export function createDiscordAdapter({
+  botToken,
+  channelId: _defaultChannelId,
+  fetchFn = globalThis.fetch,
+  _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+  const authHeader = botToken.startsWith('Bot ') ? botToken : `Bot ${botToken}`;
+
+  return {
+    name: 'discord',
+    supportsInbound: false,
+    persistent: false,
+
+    connectionState() {
+      return { state: 'n/a', error: null };
+    },
+
+    async start() {},
+    async stop() {},
+
+    async send(chatId, msg) {
+      const content = renderToMarkdown(msg);
+      const url = `${DISCORD_API}/channels/${chatId}/messages`;
+      const body = JSON.stringify({ content });
+      const headers = {
+        'Content-Type': 'application/json',
+        Authorization: authHeader,
+      };
+
+      for (let attempt = 0; attempt <= SEND_BACKOFF_DELAYS.length; attempt++) {
+        const res = await fetchFn(url, { method: 'POST', headers, body });
+        if (res.status !== 429) {
+          if (!res.ok)
+            console.warn(`[discord] send failed: HTTP ${res.status}`);
+          return;
+        }
+        if (attempt === SEND_BACKOFF_DELAYS.length) {
+          console.warn('[discord] send dropped after retries (429)');
+          return;
+        }
+        const data = await res.json().catch(() => ({}));
+        const ms =
+          (data.retry_after ?? 0) * 1000 || SEND_BACKOFF_DELAYS[attempt];
+        await _sleep(ms);
+      }
+    },
+
+    onInbound(_cb) {},
+  };
+}

package/server/integrations/adapters/slack.js

@@ -0,0 +1,106 @@
+/**
+ * Slack adapter — outbound only, POST to incoming webhook URL (mrkdwn).
+ * @module adapters/slack
+ */
+
+import { toSlackMrkdwn } from '../markdown.js';
+
+const SEND_BACKOFF_DELAYS = [1000, 5000, 30000];
+
+// ---------------------------------------------------------------------------
+// mrkdwn renderer
+// ---------------------------------------------------------------------------
+
+/**
+ * Render a NormalizedMessage to Slack mrkdwn.
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {string}
+ */
+export function renderToMrkdwn(msg) {
+  const parts = [];
+  if (msg.title) {
+    parts.push(`*${msg.title}*\n`);
+  }
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(toSlackMrkdwn(seg.value));
+        break;
+      case 'bold':
+        parts.push(`*${seg.value}*`);
+        break;
+      case 'code':
+        parts.push(`\`${seg.value}\``);
+        break;
+      case 'code_block':
+        parts.push(`\`\`\`\n${seg.value}\n\`\`\``);
+        break;
+      case 'link':
+        parts.push(`<${seg.href ?? ''}|${seg.value}>`);
+        break;
+      default: // 'text'
+        parts.push(seg.value);
+    }
+  }
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   webhookUrl?: string,
+ *   fetchFn?: typeof fetch,
+ *   _sleep?: (ms: number) => Promise<void>
+ * }} options
+ * @returns {import('../adapter.js').ChatAdapter}
+ */
+export function createSlackAdapter({
+  webhookUrl = process.env.SLACK_WEBHOOK_URL,
+  fetchFn = globalThis.fetch,
+  _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  return {
+    name: 'slack',
+    supportsInbound: false,
+    persistent: false,
+
+    connectionState() {
+      return { state: 'n/a', error: null };
+    },
+
+    async start() {},
+    async stop() {},
+
+    async send(_chatId, msg) {
+      const text = renderToMrkdwn(msg);
+      const body = JSON.stringify({ text });
+      const headers = { 'Content-Type': 'application/json' };
+
+      for (let attempt = 0; attempt <= SEND_BACKOFF_DELAYS.length; attempt++) {
+        const res = await fetchFn(webhookUrl, {
+          method: 'POST',
+          headers,
+          body,
+        });
+        if (res.status !== 429) {
+          if (!res.ok) console.warn(`[slack] send failed: HTTP ${res.status}`);
+          return;
+        }
+        if (attempt === SEND_BACKOFF_DELAYS.length) {
+          console.warn('[slack] send dropped after retries (429)');
+          return;
+        }
+        const retryAfter = res.headers?.get('retry-after');
+        const ms = retryAfter
+          ? Number(retryAfter) * 1000
+          : SEND_BACKOFF_DELAYS[attempt];
+        await _sleep(ms);
+      }
+    },
+
+    onInbound(_cb) {},
+  };
+}

package/server/integrations/adapters/telegram.js

@@ -0,0 +1,231 @@
+/**
+ * Telegram adapter — two-way, long-poll getUpdates + sendMessage (HTML parse_mode).
+ * @module adapters/telegram
+ */
+
+import { mkdir, open, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { toTelegramHtml } from '../markdown.js';
+
+const TELEGRAM_API = 'https://api.telegram.org';
+const LONG_POLL_TIMEOUT_SEC = 30;
+const SEND_BACKOFF_DELAYS = [1000, 5000, 30000];
+
+// ---------------------------------------------------------------------------
+// HTML escaping + renderer
+// ---------------------------------------------------------------------------
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Render a NormalizedMessage to Telegram HTML.
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {string}
+ */
+export function renderToHtml(msg) {
+  const parts = [];
+  if (msg.title) {
+    parts.push(`<b>${escapeHtml(msg.title)}</b>\n`);
+  }
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(toTelegramHtml(seg.value));
+        break;
+      case 'bold':
+        parts.push(`<b>${escapeHtml(seg.value)}</b>`);
+        break;
+      case 'code':
+        parts.push(`<code>${escapeHtml(seg.value)}</code>`);
+        break;
+      case 'code_block':
+        parts.push(`<pre>${escapeHtml(seg.value)}</pre>`);
+        break;
+      case 'link':
+        parts.push(
+          `<a href="${escapeHtml(seg.href ?? '')}">${escapeHtml(seg.value)}</a>`,
+        );
+        break;
+      default: // 'text'
+        parts.push(escapeHtml(seg.value));
+    }
+  }
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Cursor persistence (fsynced)
+// ---------------------------------------------------------------------------
+
+async function readCursor(cursorPath) {
+  try {
+    const data = await readFile(cursorPath, 'utf8');
+    const n = parseInt(data.trim(), 10);
+    return Number.isFinite(n) ? n : 0;
+  } catch {
+    return 0;
+  }
+}
+
+async function writeCursor(cursorPath, offset) {
+  await mkdir(dirname(cursorPath), { recursive: true });
+  const fh = await open(cursorPath, 'w');
+  try {
+    await fh.write(String(offset));
+    await fh.datasync();
+  } finally {
+    await fh.close();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   token: string,
+ *   cursorPath: string,
+ *   fetchFn?: typeof fetch,
+ *   _sleep?: (ms: number) => Promise<void>
+ * }} options
+ * @returns {import('../adapter.js').ChatAdapter}
+ */
+export function createTelegramAdapter({
+  token,
+  cursorPath,
+  fetchFn = globalThis.fetch,
+  _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+}) {
+  let inboundCb = null;
+  let running = false;
+  // Connection health tracking
+  let connState = 'connecting'; // 'connecting' | 'connected' | 'disconnected'
+  let connError = null;
+  let lastPollOk = null; // ISO timestamp of last successful poll
+
+  async function pollLoop() {
+    let cursor = await readCursor(cursorPath);
+    let firstPoll = true;
+    while (running) {
+      try {
+        const pollTimeout = firstPoll ? 0 : LONG_POLL_TIMEOUT_SEC;
+        const url =
+          `${TELEGRAM_API}/bot${token}/getUpdates` +
+          `?offset=${cursor}&timeout=${pollTimeout}`;
+        const res = await fetchFn(url);
+        firstPoll = false;
+        if (res.status === 429) {
+          const data = await res.json().catch(() => ({}));
+          const ms = (data.parameters?.retry_after ?? 1) * 1000;
+          await _sleep(ms);
+          continue;
+        }
+        if (!res.ok) {
+          connState = 'disconnected';
+          connError = `HTTP ${res.status}`;
+          if (running) await _sleep(5000);
+          continue;
+        }
+        connState = 'connected';
+        connError = null;
+        lastPollOk = new Date().toISOString();
+        const data = await res.json();
+        if (data.ok && data.result.length > 0) {
+          for (const update of data.result) {
+            cursor = update.update_id + 1;
+            if (inboundCb && update.message) {
+              const m = update.message;
+              inboundCb({
+                platform: 'telegram',
+                chatId: String(m.chat.id),
+                userId: String(m.from?.id ?? m.chat.id),
+                text: m.text ?? '',
+                raw: update,
+              });
+            }
+          }
+          await writeCursor(cursorPath, cursor);
+        }
+      } catch (err) {
+        connState = 'disconnected';
+        connError = err.message;
+        console.error('[telegram] poll error:', err.message);
+        if (running) await _sleep(1000);
+      }
+    }
+  }
+
+  return {
+    name: 'telegram',
+    supportsInbound: true,
+    persistent: true,
+
+    connectionState() {
+      // If the last successful poll is older than 2× the poll timeout,
+      // the connection is stale (e.g. network dropped, fetch is hanging).
+      let effectiveState = connState;
+      let effectiveError = connError;
+      if (connState === 'connected' && lastPollOk) {
+        const staleMs = (LONG_POLL_TIMEOUT_SEC * 2 + 10) * 1000; // ~70s
+        if (Date.now() - new Date(lastPollOk).getTime() > staleMs) {
+          effectiveState = 'disconnected';
+          effectiveError = 'Connection stale — no poll response';
+        }
+      }
+      return { state: effectiveState, error: effectiveError, lastPollOk };
+    },
+
+    async start() {
+      running = true;
+      connState = 'connecting';
+      connError = null;
+      pollLoop().catch((err) =>
+        console.error('[telegram] fatal poll error:', err.message),
+      );
+    },
+
+    async stop() {
+      running = false;
+    },
+
+    async send(chatId, msg) {
+      const text = renderToHtml(msg);
+      const url = `${TELEGRAM_API}/bot${token}/sendMessage`;
+      const body = JSON.stringify({
+        chat_id: chatId,
+        text,
+        parse_mode: 'HTML',
+      });
+      const headers = { 'Content-Type': 'application/json' };
+
+      for (let attempt = 0; attempt <= SEND_BACKOFF_DELAYS.length; attempt++) {
+        const res = await fetchFn(url, { method: 'POST', headers, body });
+        if (res.status !== 429) {
+          if (!res.ok)
+            console.warn(`[telegram] sendMessage failed: HTTP ${res.status}`);
+          return;
+        }
+        if (attempt === SEND_BACKOFF_DELAYS.length) {
+          console.warn('[telegram] sendMessage dropped after retries (429)');
+          return;
+        }
+        const data = await res.json().catch(() => ({}));
+        const ms =
+          (data.parameters?.retry_after ?? 0) * 1000 ||
+          SEND_BACKOFF_DELAYS[attempt];
+        await _sleep(ms);
+      }
+    },
+
+    onInbound(cb) {
+      inboundCb = cb;
+    },
+  };
+}

package/server/integrations/adapters/webhook_out.js

@@ -0,0 +1,253 @@
+/**
+ * Generic outbound webhook adapter — POSTs to configured URL(s) with templated payloads.
+ * @module adapters/webhook_out
+ */
+
+import { toDiscordMarkdown, toPlainText, toSlackMrkdwn } from '../markdown.js';
+
+const SEND_BACKOFF_DELAYS = [1000, 5000, 30000];
+
+// ---------------------------------------------------------------------------
+// Internal text helpers
+// ---------------------------------------------------------------------------
+
+function bodyToPlain(msg) {
+  return msg.body
+    .map((seg) =>
+      seg.kind === 'markdown' ? toPlainText(seg.value) : seg.value,
+    )
+    .join('');
+}
+
+function bodyToMrkdwn(msg) {
+  const parts = [];
+  if (msg.title) parts.push(`*${msg.title}*\n`);
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(toSlackMrkdwn(seg.value));
+        break;
+      case 'bold':
+        parts.push(`*${seg.value}*`);
+        break;
+      case 'code':
+        parts.push(`\`${seg.value}\``);
+        break;
+      case 'code_block':
+        parts.push(`\`\`\`\n${seg.value}\n\`\`\``);
+        break;
+      case 'link':
+        parts.push(`<${seg.href ?? ''}|${seg.value}>`);
+        break;
+      default:
+        parts.push(seg.value);
+    }
+  }
+  return parts.join('');
+}
+
+function bodyToMarkdown(msg) {
+  const parts = [];
+  if (msg.title) parts.push(`**${msg.title}**\n`);
+  for (const seg of msg.body) {
+    switch (seg.kind) {
+      case 'markdown':
+        parts.push(toDiscordMarkdown(seg.value));
+        break;
+      case 'bold':
+        parts.push(`**${seg.value}**`);
+        break;
+      case 'code':
+        parts.push(`\`${seg.value}\``);
+        break;
+      case 'code_block':
+        parts.push(`\`\`\`\n${seg.value}\n\`\`\``);
+        break;
+      case 'link':
+        parts.push(`[${seg.value}](${seg.href ?? ''})`);
+        break;
+      default:
+        parts.push(seg.value);
+    }
+  }
+  return parts.join('');
+}
+
+// ---------------------------------------------------------------------------
+// Payload templates
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {object}
+ */
+export function renderAsGenericJson(msg) {
+  return {
+    title: msg.title,
+    severity: msg.severity,
+    text: bodyToPlain(msg),
+    segments: msg.body,
+  };
+}
+
+/**
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {{ text: string }}
+ */
+export function renderAsSlackCompatible(msg) {
+  return { text: bodyToMrkdwn(msg) };
+}
+
+/**
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {{ content: string }}
+ */
+export function renderAsDiscordCompatible(msg) {
+  return { content: bodyToMarkdown(msg) };
+}
+
+/**
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {object}
+ */
+export function renderAsTeamsCard(msg) {
+  const cardBody = [];
+  if (msg.title) {
+    cardBody.push({
+      type: 'TextBlock',
+      text: msg.title,
+      weight: 'bolder',
+      size: 'medium',
+    });
+  }
+  cardBody.push({ type: 'TextBlock', text: bodyToPlain(msg), wrap: true });
+  return {
+    type: 'message',
+    attachments: [
+      {
+        contentType: 'application/vnd.microsoft.card.adaptive',
+        content: {
+          type: 'AdaptiveCard',
+          $schema: 'https://adaptivecards.io/schemas/adaptive-card.json',
+          version: '1.2',
+          body: cardBody,
+        },
+      },
+    ],
+  };
+}
+
+const NTFY_PRIORITY = { info: 2, success: 3, warning: 4, error: 5 };
+
+/**
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {object}
+ */
+export function renderAsNtfy(msg) {
+  return {
+    title: msg.title ?? undefined,
+    message: bodyToPlain(msg),
+    priority: NTFY_PRIORITY[msg.severity] ?? 3,
+  };
+}
+
+/**
+ * @param {import('../adapter.js').NormalizedMessage} msg
+ * @returns {string}
+ */
+export function renderAsPlainText(msg) {
+  const parts = [];
+  if (msg.title) parts.push(msg.title);
+  const body = bodyToPlain(msg);
+  if (body) parts.push(body);
+  return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Template registry
+// ---------------------------------------------------------------------------
+
+const TEMPLATES = {
+  'generic-json': renderAsGenericJson,
+  'slack-compatible': renderAsSlackCompatible,
+  'discord-compatible': renderAsDiscordCompatible,
+  'teams-card': renderAsTeamsCard,
+  ntfy: renderAsNtfy,
+  'plain-text': renderAsPlainText,
+};
+
+// ---------------------------------------------------------------------------
+// Internal: send to one endpoint
+// ---------------------------------------------------------------------------
+
+async function sendToEndpoint(ep, msg, fetchFn, _sleep) {
+  const render = TEMPLATES[ep.format] ?? renderAsGenericJson;
+  const payload = render(msg);
+  const isPlainText = ep.format === 'plain-text';
+  const body = isPlainText ? payload : JSON.stringify(payload);
+  const headers = {
+    'Content-Type': isPlainText ? 'text/plain' : 'application/json',
+    ...ep.headers,
+  };
+
+  for (let attempt = 0; attempt <= SEND_BACKOFF_DELAYS.length; attempt++) {
+    const res = await fetchFn(ep.url, { method: 'POST', headers, body });
+    if (res.status !== 429) {
+      if (!res.ok)
+        console.warn(
+          `[webhook_out] send to ${ep.name ?? ep.url} failed: HTTP ${res.status}`,
+        );
+      return;
+    }
+    if (attempt === SEND_BACKOFF_DELAYS.length) {
+      console.warn(
+        `[webhook_out] send to ${ep.name ?? ep.url} dropped after retries (429)`,
+      );
+      return;
+    }
+    const retryAfter = res.headers?.get?.('retry-after');
+    const ms = retryAfter
+      ? Number(retryAfter) * 1000
+      : SEND_BACKOFF_DELAYS[attempt];
+    await _sleep(ms);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Adapter factory
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   endpoints?: Array<{url: string, format: string, headers?: object, name?: string}>,
+ *   fetchFn?: typeof fetch,
+ *   _sleep?: (ms: number) => Promise<void>
+ * }} options
+ * @returns {import('../adapter.js').ChatAdapter}
+ */
+export function createWebhookOutAdapter({
+  endpoints = [],
+  fetchFn = globalThis.fetch,
+  _sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
+  return {
+    name: 'webhook_out',
+    supportsInbound: false,
+    persistent: false,
+
+    connectionState() {
+      return { state: 'n/a', error: null };
+    },
+
+    async start() {},
+    async stop() {},
+
+    async send(_chatId, msg) {
+      await Promise.all(
+        endpoints.map((ep) => sendToEndpoint(ep, msg, fetchFn, _sleep)),
+      );
+    },
+
+    onInbound(_cb) {},
+  };
+}