@freewaretools/outercom 0.4.0

package/dist/storage.js

@@ -0,0 +1,72 @@
+/**
+ * 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 {
+    constructor() {
+        this.sessions = new Map();
+        this.threadIndex = new Map();
+        this.messages = new Map();
+    }
+    async createSession(session) {
+        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) {
+        const s = this.sessions.get(id);
+        return s ? { ...s } : null;
+    }
+    async getSessionByThread(threadId) {
+        const id = this.threadIndex.get(threadId);
+        return id ? this.getSession(id) : null;
+    }
+    async getThreadByEmail(email) {
+        const target = email.trim().toLowerCase();
+        let latest = 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, patch) {
+        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) {
+        const out = [];
+        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) {
+        const list = this.messages.get(message.sessionId) ?? [];
+        list.push({ ...message });
+        this.messages.set(message.sessionId, list);
+    }
+    async getMessages(sessionId, opts) {
+        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/dist/telegram.d.ts

@@ -0,0 +1,40 @@
+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 declare class TelegramTransport implements ChatTransport {
+    private readonly cfg;
+    constructor(cfg: TelegramConfig);
+    private call;
+    /** Create a forum topic and return its `message_thread_id` (as a string). */
+    createTopic(name: string): Promise<string>;
+    /** Post a message into a topic. Best-effort: never throws to the caller. */
+    sendMessage(threadId: string, text: string): Promise<void>;
+    /** Close a topic when a conversation ends (keeps the group tidy). */
+    closeTopic(threadId: string): Promise<void>;
+    /** Reopen a closed topic (so a returning visitor reuses the same thread). */
+    reopenTopic(threadId: string): Promise<void>;
+    /**
+     * 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;
+}

package/dist/telegram.js

@@ -0,0 +1,91 @@
+/**
+ * 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 {
+    constructor(cfg) {
+        this.cfg = cfg;
+    }
+    async call(method, body) {
+        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(() => ({})));
+        if (!data.ok) {
+            throw new Error(`Telegram ${method} failed: ${data.description ?? res.status}`);
+        }
+        return data.result;
+    }
+    /** Create a forum topic and return its `message_thread_id` (as a string). */
+    async createTopic(name) {
+        // Telegram truncates topic names at 128 chars.
+        const result = await this.call("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, text) {
+        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) {
+        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) {
+        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) {
+        const msg = update?.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 };
+    }
+}

package/dist/transcript.d.ts

@@ -0,0 +1,22 @@
+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 declare function renderTranscript(session: ChatSession, messages: ChatMessage[], opts?: TranscriptOptions): RenderedTranscript;
+/**
+ * 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 declare function renderReplyNotification(session: ChatSession, unseen: ChatMessage[], opts?: TranscriptOptions & {
+    replyUrl?: string;
+}): RenderedTranscript;

package/dist/transcript.js

@@ -0,0 +1,73 @@
+/**
+ * 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, messages, opts = {}) {
+    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, unseen, opts = {}) {
+    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) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/transport.d.ts

@@ -0,0 +1,23 @@
+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/dist/transport.js

@@ -0,0 +1 @@
+export {};

package/dist/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * 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>;
+}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@freewaretools/outercom",
+  "version": "0.4.0",
+  "description": "Self-hosted live-chat widget that hands off to Telegram (Slack/Discord pluggable), with an optional Claude or local-LLM first-line. Pre-chat capture, topic-per-customer, transcript email, notification sounds.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./next": {
+      "types": "./dist/next.d.ts",
+      "default": "./dist/next.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist"
+  },
+  "//install-notes": "Published to npm as @freewaretools/outercom; also git-URL installable (dist/ is committed, so no build step on install). NO prepack/prepare/postinstall scripts on purpose: pnpm blocks build scripts on git-URL installs (ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED). No peerDependencies — react/@anthropic-ai/sdk are provided by the host (the SDK is lazy-loaded); pnpm fails to snapshot a git dep that declares peers. To release: `npm run build`, commit dist/, tag, then `npm publish`.",
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.102.0",
+    "@types/react": "^19",
+    "react": "^19",
+    "typescript": "^5.7.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freewaretools/outercom.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/ai.ts

@@ -0,0 +1,72 @@
+import type Anthropic from "@anthropic-ai/sdk"
+import type { AIProvider, ChatMessage, ChatVisitor } from "./types"
+import { buildSupportSystemPrompt, parseAIReply, toChatTurns } from "./prompt"
+
+export interface AnthropicProviderConfig {
+  apiKey: string
+  /**
+   * Model id. Defaults to Claude Haiku 4.5 — cheapest tier ($1/$5 per 1M
+   * tokens), ample for grounded first-line support. Bump to
+   * `claude-sonnet-4-6` if answers need more nuance.
+   */
+  model?: string
+  /** Product/FAQ content the AI must ground its answers in. */
+  knowledgeBase: string
+  /** Company/brand name used in the persona. */
+  brand?: string
+  /** Extra persona/policy text appended to the system prompt. */
+  systemPromptExtra?: string
+  maxTokens?: number
+}
+
+const DEFAULT_MODEL = "claude-haiku-4-5"
+
+/**
+ * Claude-backed first-line responder. Asks for a small JSON envelope and parses
+ * it defensively (falls back to plain text). No `thinking` / `effort` — both
+ * error on Haiku 4.5 and a support first-line doesn't need them.
+ */
+export class AnthropicProvider implements AIProvider {
+  private clientPromise: Promise<Anthropic> | null = null
+  private readonly model: string
+  private readonly maxTokens: number
+
+  constructor(private readonly cfg: AnthropicProviderConfig) {
+    this.model = cfg.model ?? DEFAULT_MODEL
+    this.maxTokens = cfg.maxTokens ?? 1024
+  }
+
+  // Lazy-load the SDK so it's only required when Claude is actually used —
+  // local-LLM / human-only consumers don't need @anthropic-ai/sdk installed.
+  private client(): Promise<Anthropic> {
+    if (!this.clientPromise) {
+      this.clientPromise = import("@anthropic-ai/sdk").then(
+        (m) => new m.default({ apiKey: this.cfg.apiKey })
+      )
+    }
+    return this.clientPromise
+  }
+
+  async reply(history: ChatMessage[], visitor: ChatVisitor) {
+    const turns = toChatTurns(history)
+    if (turns.length === 0 || turns[0].role !== "user") {
+      return { text: "Thanks for reaching out — how can I help?", escalate: false }
+    }
+
+    const client = await this.client()
+    const res = await client.messages.create({
+      model: this.model,
+      max_tokens: this.maxTokens,
+      system: buildSupportSystemPrompt(this.cfg, visitor),
+      messages: turns,
+    })
+
+    const raw = res.content
+      .filter((b): b is Anthropic.TextBlock => b.type === "text")
+      .map((b) => b.text)
+      .join("")
+      .trim()
+
+    return parseAIReply(raw)
+  }
+}