@freewaretools/outercom 0.4.0

package/src/storage.ts

@@ -0,0 +1,111 @@
+import type { ChatMessage, ChatSession, ChatRole } from "./types"
+
+/**
+ * Persistence seam. The host app supplies a concrete implementation
+ * (e.g. Postgres/Prisma) so chatkit itself stays storage-agnostic.
+ *
+ * Sessions and the agent↔visitor relay are inherently async and survive
+ * across requests/cold-starts, so a real adapter must be durable — the
+ * in-memory adapter below is for local dev and the OSS demo only.
+ */
+export interface ChatStorage {
+  createSession(session: ChatSession): Promise<void>
+  getSession(id: string): Promise<ChatSession | null>
+  /** Map an inbound transport thread back to its session. */
+  getSessionByThread(threadId: string): Promise<ChatSession | null>
+  /**
+   * Most recent thread id for a visitor email (case-insensitive), or null.
+   * Lets the engine reuse one topic per customer instead of spawning a new one
+   * each time they start a chat.
+   */
+  getThreadByEmail(email: string): Promise<string | null>
+  updateSession(id: string, patch: Partial<ChatSession>): Promise<void>
+
+  /**
+   * Non-closed sessions whose visitor hasn't been seen since `beforeTs`
+   * (using lastSeenAt, falling back to createdAt). Used to find disconnected
+   * visitors who may have unseen replies to email.
+   */
+  getSessionsIdleSince(beforeTs: number): Promise<ChatSession[]>
+
+  appendMessage(message: ChatMessage): Promise<void>
+  getMessages(
+    sessionId: string,
+    opts?: { after?: number; roles?: ChatRole[] }
+  ): Promise<ChatMessage[]>
+}
+
+/**
+ * Reference adapter — keeps everything in process memory. Fine for `next dev`
+ * on a single instance and for trying the OSS demo; do NOT use in production
+ * (state is lost on restart and not shared across instances).
+ */
+export class InMemoryStorage implements ChatStorage {
+  private sessions = new Map<string, ChatSession>()
+  private threadIndex = new Map<string, string>()
+  private messages = new Map<string, ChatMessage[]>()
+
+  async createSession(session: ChatSession): Promise<void> {
+    this.sessions.set(session.id, { ...session })
+    if (session.threadId != null) {
+      this.threadIndex.set(session.threadId, session.id)
+    }
+    if (!this.messages.has(session.id)) this.messages.set(session.id, [])
+  }
+
+  async getSession(id: string): Promise<ChatSession | null> {
+    const s = this.sessions.get(id)
+    return s ? { ...s } : null
+  }
+
+  async getSessionByThread(threadId: string): Promise<ChatSession | null> {
+    const id = this.threadIndex.get(threadId)
+    return id ? this.getSession(id) : null
+  }
+
+  async getThreadByEmail(email: string): Promise<string | null> {
+    const target = email.trim().toLowerCase()
+    let latest: ChatSession | null = null
+    for (const s of this.sessions.values()) {
+      if (s.threadId && s.visitor.email.trim().toLowerCase() === target) {
+        if (!latest || s.createdAt > latest.createdAt) latest = s
+      }
+    }
+    return latest?.threadId ?? null
+  }
+
+  async updateSession(id: string, patch: Partial<ChatSession>): Promise<void> {
+    const existing = this.sessions.get(id)
+    if (!existing) return
+    const next = { ...existing, ...patch, updatedAt: Date.now() }
+    this.sessions.set(id, next)
+    if (patch.threadId != null) {
+      this.threadIndex.set(patch.threadId, id)
+    }
+  }
+
+  async getSessionsIdleSince(beforeTs: number): Promise<ChatSession[]> {
+    const out: ChatSession[] = []
+    for (const s of this.sessions.values()) {
+      if (s.status === "closed") continue
+      if ((s.lastSeenAt ?? s.createdAt) < beforeTs) out.push({ ...s })
+    }
+    return out
+  }
+
+  async appendMessage(message: ChatMessage): Promise<void> {
+    const list = this.messages.get(message.sessionId) ?? []
+    list.push({ ...message })
+    this.messages.set(message.sessionId, list)
+  }
+
+  async getMessages(
+    sessionId: string,
+    opts?: { after?: number; roles?: ChatRole[] }
+  ): Promise<ChatMessage[]> {
+    let list = this.messages.get(sessionId) ?? []
+    if (opts?.after != null) list = list.filter((m) => m.createdAt > opts.after!)
+    if (opts?.roles) list = list.filter((m) => opts.roles!.includes(m.role))
+    return list.map((m) => ({ ...m }))
+  }
+}

package/src/telegram.ts

@@ -0,0 +1,135 @@
+import type { ChatTransport } from "./transport"
+import type { ParsedAgentReply } from "./types"
+
+export interface TelegramConfig {
+  /** Bot token from @BotFather (use a DEDICATED bot for chat, not your ops bot). */
+  botToken: string
+  /**
+   * Chat id of the support group. Must be a *forum* supergroup (Topics enabled)
+   * and the bot must be an admin with "Manage Topics" permission, otherwise
+   * `createForumTopic` fails.
+   */
+  chatId: string | number
+}
+
+/**
+ * Telegram transport. v1 of chatkit's "human handoff" surface — designed
+ * behind a thin interface so other transports (Slack, Discord, email) can be
+ * added later without touching the engine.
+ *
+ * Each chat session gets its own forum topic; the agent replies inside that
+ * topic and the webhook maps `message_thread_id` back to the session.
+ */
+export class TelegramTransport implements ChatTransport {
+  constructor(private readonly cfg: TelegramConfig) {}
+
+  private async call<T = unknown>(
+    method: string,
+    body: Record<string, unknown>
+  ): Promise<T> {
+    const res = await fetch(
+      `https://api.telegram.org/bot${this.cfg.botToken}/${method}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ chat_id: this.cfg.chatId, ...body }),
+      }
+    )
+    const data = (await res.json().catch(() => ({}))) as {
+      ok?: boolean
+      result?: T
+      description?: string
+    }
+    if (!data.ok) {
+      throw new Error(
+        `Telegram ${method} failed: ${data.description ?? res.status}`
+      )
+    }
+    return data.result as T
+  }
+
+  /** Create a forum topic and return its `message_thread_id` (as a string). */
+  async createTopic(name: string): Promise<string> {
+    // Telegram truncates topic names at 128 chars.
+    const result = await this.call<{ message_thread_id: number }>(
+      "createForumTopic",
+      { name: name.slice(0, 128) }
+    )
+    return String(result.message_thread_id)
+  }
+
+  /** Post a message into a topic. Best-effort: never throws to the caller. */
+  async sendMessage(threadId: string, text: string): Promise<void> {
+    try {
+      await this.call("sendMessage", {
+        message_thread_id: Number(threadId),
+        text,
+        parse_mode: "HTML",
+        disable_web_page_preview: true,
+      })
+    } catch (err) {
+      console.error("[chatkit] telegram sendMessage failed:", err)
+    }
+  }
+
+  /** Close a topic when a conversation ends (keeps the group tidy). */
+  async closeTopic(threadId: string): Promise<void> {
+    try {
+      await this.call("closeForumTopic", { message_thread_id: Number(threadId) })
+    } catch (err) {
+      console.error("[chatkit] telegram closeForumTopic failed:", err)
+    }
+  }
+
+  /** Reopen a closed topic (so a returning visitor reuses the same thread). */
+  async reopenTopic(threadId: string): Promise<void> {
+    try {
+      await this.call("reopenForumTopic", { message_thread_id: Number(threadId) })
+    } catch {
+      // Already open, or topic gone — non-fatal.
+    }
+  }
+
+  /**
+   * Parse an inbound webhook update into an agent reply, or `null` if it isn't
+   * a relevant human message. Bots don't receive their own messages, so AI/bot
+   * echoes never come back through here. Service messages (topic created, etc.)
+   * and non-topic chatter are ignored.
+   */
+  parseUpdate(update: unknown): ParsedAgentReply | null {
+    const msg = (update as { message?: TelegramMessage })?.message
+    if (!msg) return null
+    if (msg.message_thread_id == null) return null // not inside a topic
+    if (msg.from?.is_bot) return null
+    if (msg.forum_topic_created || msg.forum_topic_closed) return null
+
+    const text = (msg.text ?? msg.caption ?? "").trim()
+    if (!text) return null
+
+    const fromName =
+      [msg.from?.first_name, msg.from?.last_name].filter(Boolean).join(" ") ||
+      msg.from?.username
+
+    const threadId = String(msg.message_thread_id)
+    const lower = text.toLowerCase()
+    if (lower === "/close" || lower === "/end") {
+      return { threadId, text, fromName, command: "close" }
+    }
+
+    return { threadId, text, fromName }
+  }
+}
+
+interface TelegramMessage {
+  message_thread_id?: number
+  text?: string
+  caption?: string
+  forum_topic_created?: unknown
+  forum_topic_closed?: unknown
+  from?: {
+    is_bot?: boolean
+    first_name?: string
+    last_name?: string
+    username?: string
+  }
+}

package/src/transcript.ts

@@ -0,0 +1,116 @@
+import type { ChatMessage, ChatSession } from "./types"
+
+export interface TranscriptOptions {
+  /** Brand name used for the AI's label + email copy. */
+  brand?: string
+}
+
+export interface RenderedTranscript {
+  subject: string
+  html: string
+  text: string
+}
+
+/**
+ * Render a chat session into an email-ready transcript (subject + HTML + plain
+ * text). Pure and host-agnostic — the host wires it to its own mailer.
+ */
+export function renderTranscript(
+  session: ChatSession,
+  messages: ChatMessage[],
+  opts: TranscriptOptions = {}
+): RenderedTranscript {
+  const brand = opts.brand ?? "Support"
+  const subject = `Your chat with ${brand}`
+
+  const rows = messages
+    .filter((m) => m.text && m.text.trim())
+    .map((m) => ({
+      role: m.role,
+      who:
+        m.role === "visitor"
+          ? session.visitor.name
+          : m.role === "agent"
+            ? m.authorName || "Support"
+            : m.role === "ai"
+              ? brand
+              : "",
+      text: m.text,
+    }))
+
+  const htmlRows = rows
+    .map((r) =>
+      r.role === "system"
+        ? `<p style="margin:8px 0;color:#888;font-size:13px;font-style:italic">${esc(r.text)}</p>`
+        : `<p style="margin:10px 0"><strong>${esc(r.who)}:</strong> ${esc(r.text)}</p>`
+    )
+    .join("")
+
+  const html =
+    `<div style="font-family:Arial,Helvetica,sans-serif;max-width:560px;margin:0 auto;color:#0f172a">` +
+    `<h2 style="margin:0 0 4px">${esc(subject)}</h2>` +
+    `<p style="color:#475569;margin:0 0 16px">Here's a copy of your conversation with ${esc(brand)}.</p>` +
+    `<hr style="border:none;border-top:1px solid #e2e8f0"/>` +
+    htmlRows +
+    `<hr style="border:none;border-top:1px solid #e2e8f0"/>` +
+    `<p style="color:#94a3b8;font-size:12px">Sent to ${esc(session.visitor.email)}.</p>` +
+    `</div>`
+
+  const text =
+    `${subject}\n\n` +
+    rows.map((r) => (r.role === "system" ? `(${r.text})` : `${r.who}: ${r.text}`)).join("\n")
+
+  return { subject, html, text }
+}
+
+/**
+ * Render a "you have new replies" email for a visitor who disconnected before
+ * seeing the agent/AI reply(s). `replyUrl`, if given, links back to the chat.
+ */
+export function renderReplyNotification(
+  session: ChatSession,
+  unseen: ChatMessage[],
+  opts: TranscriptOptions & { replyUrl?: string } = {}
+): RenderedTranscript {
+  const brand = opts.brand ?? "Support"
+  const subject = `New reply from ${brand}`
+
+  const rows = unseen
+    .filter((m) => m.text && m.text.trim())
+    .map((m) => ({
+      who: m.role === "agent" ? m.authorName || "Support" : brand,
+      text: m.text,
+    }))
+
+  const htmlRows = rows
+    .map(
+      (r) => `<p style="margin:10px 0"><strong>${esc(r.who)}:</strong> ${esc(r.text)}</p>`
+    )
+    .join("")
+
+  const link = opts.replyUrl
+    ? `<p style="margin:16px 0"><a href="${esc(opts.replyUrl)}" style="color:#0f172a">Reply to continue the conversation →</a></p>`
+    : ""
+
+  const html =
+    `<div style="font-family:Arial,Helvetica,sans-serif;max-width:560px;margin:0 auto;color:#0f172a">` +
+    `<h2 style="margin:0 0 4px">${esc(subject)}</h2>` +
+    `<p style="color:#475569;margin:0 0 16px">Hi ${esc(session.visitor.name)}, you have a new reply to your chat:</p>` +
+    `<hr style="border:none;border-top:1px solid #e2e8f0"/>` +
+    htmlRows +
+    link +
+    `<hr style="border:none;border-top:1px solid #e2e8f0"/>` +
+    `<p style="color:#94a3b8;font-size:12px">Sent to ${esc(session.visitor.email)} because you left the chat before this reply arrived.</p>` +
+    `</div>`
+
+  const text =
+    `${subject}\n\nHi ${session.visitor.name}, you have a new reply:\n\n` +
+    rows.map((r) => `${r.who}: ${r.text}`).join("\n") +
+    (opts.replyUrl ? `\n\nReply: ${opts.replyUrl}` : "")
+
+  return { subject, html, text }
+}
+
+function esc(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;")
+}

package/src/transport.ts

@@ -0,0 +1,24 @@
+import type { ParsedAgentReply } from "./types"
+
+/**
+ * The "human handoff" seam. A transport routes a conversation to wherever your
+ * team already works and relays their replies back.
+ *
+ * v1 ships {@link TelegramTransport}. The interface is deliberately small so a
+ * SlackTransport (thread per chat in a channel), DiscordTransport, or
+ * email/SMTP transport can be added without touching the engine. Thread ids are
+ * opaque strings so any backend's native id fits (Telegram `message_thread_id`,
+ * Slack `thread_ts`, etc.).
+ */
+export interface ChatTransport {
+  /** Create a thread/topic for a new chat and return its opaque id. */
+  createTopic(name: string): Promise<string>
+  /** Post a message into a thread. Should be best-effort (not throw). */
+  sendMessage(threadId: string, text: string): Promise<void>
+  /** Close/archive a thread when the conversation ends. */
+  closeTopic(threadId: string): Promise<void>
+  /** Reopen a previously closed thread (best-effort; no-op where not applicable). */
+  reopenTopic(threadId: string): Promise<void>
+  /** Parse an inbound webhook payload into an agent reply, or null if irrelevant. */
+  parseUpdate(update: unknown): ParsedAgentReply | null
+}

package/src/types.ts

@@ -0,0 +1,83 @@
+/**
+ * chatkit — portable customer-chat module.
+ *
+ * Core domain types. Nothing in this folder imports from the host app
+ * (`@/...`); it depends only on npm packages + web/node built-ins, so the
+ * whole `src/chatkit` directory can be lifted out into its own package.
+ */
+
+/** Who authored a message. */
+export type ChatRole = "visitor" | "ai" | "agent" | "system"
+
+/**
+ * Lifecycle of a conversation.
+ * - `ai`     — the AI first-line is handling the visitor.
+ * - `live`   — a human agent has taken over (AI stays quiet).
+ * - `closed` — the conversation has ended.
+ */
+export type ChatStatus = "ai" | "live" | "closed"
+
+/** Details captured by the pre-chat form before messaging starts. */
+export interface ChatVisitor {
+  name: string
+  email: string
+  /** Optional "what do you need help with?" from the pre-chat form. */
+  topic?: string
+}
+
+export interface ChatMessage {
+  id: string
+  sessionId: string
+  role: ChatRole
+  text: string
+  /** Display name of the author (for agent replies — the staff member's name). */
+  authorName?: string
+  /** Epoch milliseconds. */
+  createdAt: number
+}
+
+export interface ChatSession {
+  /** Opaque public id (uuid) — the client holds this to read/write its session. */
+  id: string
+  visitor: ChatVisitor
+  /**
+   * Transport thread id, once the thread/topic is created. Opaque string so any
+   * backend fits (Telegram `message_thread_id`, Slack `thread_ts`, …).
+   */
+  threadId: string | null
+  status: ChatStatus
+  createdAt: number
+  updatedAt: number
+  /** Last time the visitor's widget polled/heartbeat — used to detect disconnect. */
+  lastSeenAt?: number
+  /** Timestamp up to which unseen replies have been emailed (avoids re-sending). */
+  notifiedAt?: number
+}
+
+/** A human agent's reply parsed from an inbound transport webhook update. */
+export interface ParsedAgentReply {
+  threadId: string
+  text: string
+  /** Display name of the agent who replied, if available. */
+  fromName?: string
+  /** True when the message is a control command (e.g. `/close`). */
+  command?: "close"
+}
+
+/** Result of an AI first-line turn. */
+export interface AIReply {
+  /** The text to show the visitor. */
+  text: string
+  /** True when the AI wants a human to take over. */
+  escalate: boolean
+  /** Short internal note on why it escalated (shown to agents, not the visitor). */
+  reason?: string
+}
+
+/**
+ * Optional first-line layer. Implement this to plug in a different LLM —
+ * cloud ({@link AnthropicProvider}) or local/self-hosted ({@link LocalProvider}).
+ */
+export interface AIProvider {
+  reply(history: ChatMessage[], visitor: ChatVisitor): Promise<AIReply>
+}