@freewaretools/outercom 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 freewaretools
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @freewaretools/outercom
+
+A small, self-hosted **live-chat widget that hands off to the messenger your team already uses**. Telegram in v1 (a forum **topic per customer**), with an optional **Claude or local-LLM** first-line that answers common questions and escalates to a human when it can't.
+
+No SaaS, no per-seat fees — you own the data and the code.
+
+> **Status:** in production. Portable by design — the package has **no host-app imports** and **no brand baked in** (the brand name, AI label, knowledge base, and theming are all injected by the host); persistence, transport, and AI are pluggable interfaces. Open-source under the MIT license.
+
+## Install
+
+From npm:
+
+```bash
+npm i @freewaretools/outercom
+```
+
+Or straight from GitHub (git-URL install — `dist/` is committed, so no build step):
+
+```bash
+npm i github:freewaretools/outercom#v0.4.0
+```
+
+Peer deps (install whichever you use): `react` (for the widget), `@anthropic-ai/sdk` (only if you use the Claude provider — it's lazy-loaded, so local-LLM / human-only setups don't need it).
+
+Entry points: `@freewaretools/outercom` (core), `@freewaretools/outercom/react` (widget), `@freewaretools/outercom/next` (App Router route factories).
+
+## How it works
+
+```
+Visitor ──► ChatWidget ──► /api/chat ──► ChatEngine ──┬─► AIProvider (Claude / local, first-line)
+   ▲                                                  └─► ChatTransport (Telegram topic)
+   │                                                            │
+   └──────────── /api/chat/poll ◄── ChatStorage ◄── /api/chat/telegram (agent reply webhook)
+```
+
+1. The widget collects **name + email** (+ optional question) before any messaging.
+2. On start, the engine reuses (or opens) a **forum topic per customer** named `Name · email` and posts the details.
+3. The AI answers first-line from your knowledge base; if it can't, it **escalates** (pings the topic, tells the visitor a human is coming).
+4. An agent replies **inside the topic** → the webhook maps `message_thread_id` → session → the visitor sees it on the next poll. The AI goes quiet once a human joins.
+
+## Architecture (the seams)
+
+| Piece | Interface | Ships | Swap for… |
+|---|---|---|---|
+| Persistence | `ChatStorage` | `InMemoryStorage` (dev only) | a Postgres/Prisma adapter (the host provides one) |
+| Handoff | `ChatTransport` | `TelegramTransport` | `SlackTransport`, `DiscordTransport`, email… |
+| First-line AI | `AIProvider` | `AnthropicProvider` (Claude Haiku 4.5) · `LocalProvider` (any OpenAI-compatible server) | any LLM, or omit for human-only |
+
+Thread ids are **opaque strings**, so a transport's native id fits as-is (Telegram `message_thread_id`, Slack `thread_ts`, …).
+
+## Quick start (Next.js App Router)
+
+```ts
+// build the engine once (host app supplies storage + secrets)
+import { ChatEngine, TelegramTransport, AnthropicProvider, renderTranscript } from "@freewaretools/outercom"
+import { createChatRoutes } from "@freewaretools/outercom/next"
+import { PrismaChatStorage } from "@/lib/chat/prisma-storage"
+import { sendEmail } from "@/lib/email"
+
+const engine = new ChatEngine({
+  storage: new PrismaChatStorage(),
+  transport: new TelegramTransport({ botToken: TOKEN, chatId: GROUP_ID }),
+  ai: new AnthropicProvider({ apiKey: KEY, knowledgeBase: KB, brand: "Acme" }),
+  topicName: (v) => `${v.name} · ${v.email}`,
+  sendTranscript: async (session, messages) => {
+    const { subject, html, text } = renderTranscript(session, messages, { brand: "Acme" })
+    await sendEmail({ to: session.visitor.email, subject, html, text })
+  },
+})
+
+export const routes = createChatRoutes(() => engine, { webhookSecret: SECRET })
+```
+
+```ts
+// src/app/api/chat/route.ts
+import { routes } from "@/lib/chat/config"
+export const runtime = "nodejs"
+export const POST = routes.chat.POST
+```
+
+…and likewise `app/api/chat/poll/route.ts` → `routes.poll.GET`, `app/api/chat/telegram/route.ts` → `routes.webhook.POST`.
+
+```tsx
+// mount the widget — self-gates via a runtime config route so on/off isn't baked into a build
+import { ChatWidget } from "@freewaretools/outercom/react"
+<ChatWidget configUrl="/api/chat/config" title="Live Chat" accentColor="#0f172a" />
+```
+
+## Features
+
+- **Topic-per-customer** — reused (and reopened) by email, so one thread per person, not a pile of duplicates.
+- **AI first-line** — Claude (`AnthropicProvider`, default Haiku 4.5) or any OpenAI-compatible local model (`LocalProvider`: Ollama / LM Studio / llama.cpp / vLLM). Same persona + `{reply, escalate, reason}` contract, defensive JSON parsing with plain-text fallback.
+- **Agent names** — the replying staff member's name is shown on their bubbles.
+- **Transcript email** — auto-sent on close, plus an "Email me a copy" button (`renderTranscript` + a host `sendTranscript` hook).
+- **Notification sounds** — soft Web-Audio "boop" on incoming replies, with mute toggle + unread dot on the launcher.
+- **Reset/abandon** — visitor reset posts a notice into the topic and closes it, so agents don't reply into a dead chat.
+
+## AI: cloud or local
+
+```ts
+// Cloud — Claude Haiku 4.5 (cheapest tier)
+new AnthropicProvider({ apiKey, knowledgeBase, brand: "Acme" })
+
+// Local — anything speaking the OpenAI Chat Completions API
+new LocalProvider({
+  baseUrl: "http://192.168.x.x:11434/v1", // Ollama; LM Studio :1234, llama.cpp :8080, vLLM :8000
+  model: "gemma3:12b",
+  knowledgeBase,
+  brand: "Acme",
+})
+```
+
+A local model keeps all chat data on your own infrastructure with no per-token cost. From inside Docker, point `baseUrl` at the LAN IP / `host.docker.internal`, not `localhost`, and bind the model server to `0.0.0.0`.
+
+## Telegram setup
+
+1. **@BotFather → `/newbot`** → copy the token (a *dedicated* bot — a bot can only have one webhook URL).
+2. Create a **group**, make it a **forum** (Group → Edit → *Topics* on).
+3. Add the bot as **admin** — and crucially enable the **Manage Topics** admin right (being an admin alone isn't enough to create topics).
+4. Get the group's chat id (negative `-100…`); confirm with `getChat` → `is_forum: true`.
+5. Register the webhook with a secret:
+   ```
+   curl "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://yoursite/api/chat/telegram&secret_token=<SECRET>"
+   ```
+
+## Extending: Slack (or anything)
+
+Implement `ChatTransport` and pass it to the engine — no engine changes:
+
+```ts
+class SlackTransport implements ChatTransport {
+  createTopic(name) { /* post a parent message → return its thread_ts */ }
+  sendMessage(threadId, text) { /* chat.postMessage thread_ts=threadId */ }
+  closeTopic(threadId) { /* archive / post a "closed" note */ }
+  reopenTopic(threadId) { /* optional */ }
+  parseUpdate(evt) { /* Events API message in a thread → { threadId, text } */ }
+}
+```
+
+## Notes
+
+- **Storage must be durable in prod** — agent replies arrive asynchronously; sessions must survive cold starts / multiple instances. Use a Postgres adapter, not `InMemoryStorage`.
+- **Delivery to the visitor is poll-based** (robust + serverless-friendly). SSE is a possible upgrade.
+- **Rate limiting / spam protection** on `/api/chat` is the host's responsibility.
+- The session id is an unguessable UUID held by the client; it grants access to that session only. For authenticated apps, derive the visitor server-side rather than trusting the client.
+
+## Releasing
+
+`dist/` is committed so git-URL installs need no build step. To cut a release: `npm run build`, commit `dist/`, tag (`git tag v0.x.0 && git push --tags`), then `npm publish`. Consumers use `npm i @freewaretools/outercom` or pin `github:freewaretools/outercom#v0.x.0`.
+
+---
+
+MIT — see [LICENSE](./LICENSE).

package/dist/ai.d.ts

@@ -0,0 +1,31 @@
+import type { AIProvider, ChatMessage, ChatVisitor } from "./types";
+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;
+}
+/**
+ * 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 declare class AnthropicProvider implements AIProvider {
+    private readonly cfg;
+    private clientPromise;
+    private readonly model;
+    private readonly maxTokens;
+    constructor(cfg: AnthropicProviderConfig);
+    private client;
+    reply(history: ChatMessage[], visitor: ChatVisitor): Promise<import("./types").AIReply>;
+}

package/dist/ai.js

@@ -0,0 +1,42 @@
+import { buildSupportSystemPrompt, parseAIReply, toChatTurns } from "./prompt";
+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 {
+    constructor(cfg) {
+        this.cfg = cfg;
+        this.clientPromise = null;
+        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.
+    client() {
+        if (!this.clientPromise) {
+            this.clientPromise = import("@anthropic-ai/sdk").then((m) => new m.default({ apiKey: this.cfg.apiKey }));
+        }
+        return this.clientPromise;
+    }
+    async reply(history, visitor) {
+        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.type === "text")
+            .map((b) => b.text)
+            .join("")
+            .trim();
+        return parseAIReply(raw);
+    }
+}

package/dist/engine.d.ts

@@ -0,0 +1,96 @@
+import type { ChatStorage } from "./storage";
+import type { ChatTransport } from "./transport";
+import type { AIProvider, ChatMessage, ChatSession, ChatVisitor } from "./types";
+export interface ChatEngineOptions {
+    storage: ChatStorage;
+    transport: ChatTransport;
+    /** Optional first-line AI. Omit (or pass `aiEnabled: false`) for human-only chat. */
+    ai?: AIProvider;
+    aiEnabled?: boolean;
+    /** Builds the forum-topic title for a new chat. Default: "Name · email". */
+    topicName?: (visitor: ChatVisitor) => string;
+    /** Message shown to the visitor when a chat is escalated to a human. */
+    escalationMessage?: string;
+    /**
+     * Optional hook to email/send a transcript. Called when a chat is closed and
+     * when the visitor requests a copy. Host-provided (e.g. render + Resend) so
+     * chatkit stays mailer-agnostic.
+     */
+    sendTranscript?: (session: ChatSession, messages: ChatMessage[]) => Promise<void>;
+    /**
+     * Optional hook to email a visitor replies they haven't seen (because they
+     * disconnected). Called by {@link flushUnseen}. Host-provided.
+     */
+    sendReplyNotification?: (session: ChatSession, unseen: ChatMessage[]) => Promise<void>;
+}
+/**
+ * Orchestrates a conversation across the storage, Telegram transport, and the
+ * optional AI first-line. Transport-agnostic at heart — `transport` is the only
+ * Telegram-specific dependency and sits behind a small surface.
+ */
+export declare class ChatEngine {
+    private readonly storage;
+    private readonly transport;
+    private readonly ai?;
+    private readonly aiEnabled;
+    private readonly topicName;
+    private readonly escalationMessage;
+    private readonly sendTranscript?;
+    private readonly sendReplyNotification?;
+    constructor(opts: ChatEngineOptions);
+    /** Email the visitor a transcript on demand. Returns false if no mailer is wired. */
+    emailTranscript(sessionId: string): Promise<boolean>;
+    /**
+     * Start a new chat: create the session, open a Telegram topic, and post the
+     * captured visitor details. The pre-chat form has already collected name +
+     * email (+ optional question) so a topic-per-chat is created up front.
+     */
+    startSession(visitor: ChatVisitor): Promise<{
+        sessionId: string;
+    }>;
+    /**
+     * Handle a visitor message: persist + mirror to Telegram, then (if the AI is
+     * handling) generate a reply. Returns any new client-facing messages produced
+     * synchronously (the AI reply / escalation note) so the widget can render
+     * them immediately; async agent replies arrive via {@link poll}.
+     */
+    handleVisitorMessage(sessionId: string, text: string): Promise<{
+        session: ChatSession;
+        newMessages: ChatMessage[];
+    }>;
+    /**
+     * Handle an inbound Telegram webhook update — a human agent replying in a
+     * topic. Flips the session to `live` so the AI stays quiet, or closes it on
+     * `/close`. Returns true if the update mapped to a known session.
+     */
+    handleWebhookUpdate(update: unknown): Promise<boolean>;
+    /**
+     * Poll for messages the visitor hasn't seen yet, plus the live status. Also
+     * records the visitor as "seen" now (a present visitor is polling/heartbeating)
+     * — the disconnect detector keys off this.
+     */
+    poll(sessionId: string, after?: number): Promise<{
+        status: ChatSession["status"];
+        messages: ChatMessage[];
+    }>;
+    /**
+     * Email visitors who disconnected (no poll for >= thresholdMs) the agent/AI
+     * replies they never saw. Idempotent via `notifiedAt`. Call from a cron.
+     * Returns how many sessions were emailed.
+     */
+    flushUnseen(thresholdMs: number): Promise<number>;
+    /**
+     * The visitor ended/reset the chat from their side. Post a notice into the
+     * topic so agents know replies won't reach them, then close it. No transcript
+     * email (the visitor chose to start over, not to wrap up).
+     */
+    abandonSession(sessionId: string): Promise<void>;
+    closeSession(sessionId: string): Promise<void>;
+    private requireSession;
+    private append;
+    private mirror;
+}
+export declare class ChatSessionNotFound extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string);
+}

package/dist/engine.js

@@ -0,0 +1,282 @@
+const DEFAULT_ESCALATION = "I've passed this to our team — someone will jump in here shortly. Feel free to add any extra detail in the meantime.";
+/** Messages the client should render (everything except the visitor's own echoes). */
+const CLIENT_ROLES = ["ai", "agent", "system"];
+/**
+ * Orchestrates a conversation across the storage, Telegram transport, and the
+ * optional AI first-line. Transport-agnostic at heart — `transport` is the only
+ * Telegram-specific dependency and sits behind a small surface.
+ */
+export class ChatEngine {
+    constructor(opts) {
+        this.storage = opts.storage;
+        this.transport = opts.transport;
+        this.ai = opts.ai;
+        this.aiEnabled = (opts.aiEnabled ?? true) && !!opts.ai;
+        this.topicName =
+            opts.topicName ?? ((v) => `${v.name} · ${v.email}`);
+        this.escalationMessage = opts.escalationMessage ?? DEFAULT_ESCALATION;
+        this.sendTranscript = opts.sendTranscript;
+        this.sendReplyNotification = opts.sendReplyNotification;
+    }
+    /** Email the visitor a transcript on demand. Returns false if no mailer is wired. */
+    async emailTranscript(sessionId) {
+        if (!this.sendTranscript)
+            return false;
+        const session = await this.storage.getSession(sessionId);
+        if (!session)
+            return false;
+        try {
+            const messages = await this.storage.getMessages(sessionId);
+            await this.sendTranscript(session, messages);
+            return true;
+        }
+        catch (err) {
+            console.error("[chatkit] sendTranscript failed:", err);
+            return false;
+        }
+    }
+    /**
+     * Start a new chat: create the session, open a Telegram topic, and post the
+     * captured visitor details. The pre-chat form has already collected name +
+     * email (+ optional question) so a topic-per-chat is created up front.
+     */
+    async startSession(visitor) {
+        const id = crypto.randomUUID();
+        const now = Date.now();
+        // Reuse one topic per customer email; reopen it if a prior chat closed it.
+        let threadId = await this.storage.getThreadByEmail(visitor.email);
+        const reused = threadId !== null;
+        if (threadId !== null) {
+            await this.transport.reopenTopic(threadId);
+        }
+        else {
+            try {
+                threadId = await this.transport.createTopic(this.topicName(visitor));
+            }
+            catch (err) {
+                // If topic creation fails (misconfigured group/perms), the chat still
+                // works AI-only; agent relay just won't be available until fixed.
+                console.error("[chatkit] could not create transport thread:", err);
+                threadId = null;
+            }
+        }
+        const session = {
+            id,
+            visitor,
+            threadId,
+            status: this.aiEnabled ? "ai" : "live",
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.storage.createSession(session);
+        // Post the Telegram intro + handle the opening question in the BACKGROUND so
+        // "Start chat" returns immediately. Awaiting these blocked the widget on two
+        // Telegram round-trips plus the full AI generation. The widget shows the
+        // opening message optimistically and the AI reply arrives via poll().
+        void (async () => {
+            try {
+                if (threadId != null) {
+                    const header = reused
+                        ? "🔁 <b>Returning visitor — new chat</b>"
+                        : "🆕 <b>New chat</b>";
+                    const intro = `${header}\n` +
+                        `From: ${esc(visitor.name)} (${esc(visitor.email)})\n` +
+                        (visitor.topic ? `Topic: ${esc(visitor.topic)}\n` : "") +
+                        (this.aiEnabled
+                            ? `\nThe AI assistant is handling this. Reply in this topic to take over.`
+                            : `\nReply in this topic to respond.`);
+                    await this.transport.sendMessage(threadId, intro);
+                }
+                // The pre-chat question becomes the visitor's opening message.
+                if (visitor.topic) {
+                    await this.handleVisitorMessage(id, visitor.topic);
+                }
+            }
+            catch (err) {
+                console.error("[chatkit] post-start tasks failed:", err);
+            }
+        })();
+        return { sessionId: id };
+    }
+    /**
+     * Handle a visitor message: persist + mirror to Telegram, then (if the AI is
+     * handling) generate a reply. Returns any new client-facing messages produced
+     * synchronously (the AI reply / escalation note) so the widget can render
+     * them immediately; async agent replies arrive via {@link poll}.
+     */
+    async handleVisitorMessage(sessionId, text) {
+        const session = await this.requireSession(sessionId);
+        const clean = text.trim();
+        if (!clean)
+            return { session, newMessages: [] };
+        await this.append(session, "visitor", clean);
+        await this.mirror(session, `💬 <b>${esc(session.visitor.name)}:</b> ${esc(clean)}`);
+        const produced = [];
+        if (session.status === "ai" && this.aiEnabled && this.ai) {
+            try {
+                const history = await this.storage.getMessages(sessionId);
+                const ai = await this.ai.reply(history, session.visitor);
+                if (ai.escalate) {
+                    await this.mirror(session, `🙋 <b>AI requested a human</b>${ai.reason ? ` — ${esc(ai.reason)}` : ""}`);
+                    const note = await this.append(session, "system", this.escalationMessage);
+                    produced.push(note);
+                    await this.storage.updateSession(sessionId, { status: "live" });
+                }
+                else {
+                    const reply = await this.append(session, "ai", ai.text);
+                    produced.push(reply);
+                    await this.mirror(session, `🤖 <b>AI:</b> ${esc(ai.text)}`);
+                }
+            }
+            catch (err) {
+                console.error("[chatkit] AI reply failed, escalating:", err);
+                const note = await this.append(session, "system", this.escalationMessage);
+                produced.push(note);
+                await this.storage.updateSession(sessionId, { status: "live" });
+                await this.mirror(session, `⚠️ <b>AI error — needs a human.</b>`);
+            }
+        }
+        return { session: await this.requireSession(sessionId), newMessages: produced };
+    }
+    /**
+     * Handle an inbound Telegram webhook update — a human agent replying in a
+     * topic. Flips the session to `live` so the AI stays quiet, or closes it on
+     * `/close`. Returns true if the update mapped to a known session.
+     */
+    async handleWebhookUpdate(update) {
+        const parsed = this.transport.parseUpdate(update);
+        if (!parsed)
+            return false;
+        const session = await this.storage.getSessionByThread(parsed.threadId);
+        if (!session)
+            return false;
+        if (parsed.command === "close") {
+            await this.closeSession(session.id);
+            return true;
+        }
+        await this.append(session, "agent", parsed.text, parsed.fromName);
+        if (session.status !== "live") {
+            await this.storage.updateSession(session.id, { status: "live" });
+        }
+        return true;
+    }
+    /**
+     * Poll for messages the visitor hasn't seen yet, plus the live status. Also
+     * records the visitor as "seen" now (a present visitor is polling/heartbeating)
+     * — the disconnect detector keys off this.
+     */
+    async poll(sessionId, after = 0) {
+        const session = await this.requireSession(sessionId);
+        const messages = await this.storage.getMessages(sessionId, {
+            after,
+            roles: CLIENT_ROLES,
+        });
+        if (session.status !== "closed") {
+            await this.storage.updateSession(sessionId, { lastSeenAt: Date.now() });
+        }
+        return { status: session.status, messages };
+    }
+    /**
+     * Email visitors who disconnected (no poll for >= thresholdMs) the agent/AI
+     * replies they never saw. Idempotent via `notifiedAt`. Call from a cron.
+     * Returns how many sessions were emailed.
+     */
+    async flushUnseen(thresholdMs) {
+        if (!this.sendReplyNotification || thresholdMs <= 0)
+            return 0;
+        const now = Date.now();
+        const idle = await this.storage.getSessionsIdleSince(now - thresholdMs);
+        let sent = 0;
+        for (const session of idle) {
+            const since = Math.max(session.lastSeenAt ?? 0, session.notifiedAt ?? 0);
+            const unseen = await this.storage.getMessages(session.id, {
+                after: since,
+                roles: ["ai", "agent"],
+            });
+            if (unseen.length === 0)
+                continue;
+            try {
+                await this.sendReplyNotification(session, unseen);
+                await this.storage.updateSession(session.id, { notifiedAt: now });
+                sent++;
+            }
+            catch (err) {
+                console.error("[chatkit] reply notification failed:", err);
+            }
+        }
+        return sent;
+    }
+    /**
+     * The visitor ended/reset the chat from their side. Post a notice into the
+     * topic so agents know replies won't reach them, then close it. No transcript
+     * email (the visitor chose to start over, not to wrap up).
+     */
+    async abandonSession(sessionId) {
+        const session = await this.storage.getSession(sessionId);
+        if (!session || session.status === "closed")
+            return;
+        await this.mirror(session, "🚪 <b>The visitor left / reset the chat.</b> Replies here won't reach them.");
+        await this.storage.updateSession(sessionId, { status: "closed" });
+        if (session.threadId != null) {
+            await this.transport.closeTopic(session.threadId);
+        }
+    }
+    async closeSession(sessionId) {
+        const session = await this.storage.getSession(sessionId);
+        if (!session)
+            return;
+        const alreadyClosed = session.status === "closed";
+        if (!alreadyClosed) {
+            await this.append(session, "system", "This chat has been closed. Thanks for getting in touch!");
+        }
+        await this.storage.updateSession(sessionId, { status: "closed" });
+        // Email the transcript once, on the transition to closed.
+        if (!alreadyClosed && this.sendTranscript) {
+            try {
+                const messages = await this.storage.getMessages(sessionId);
+                await this.sendTranscript(session, messages);
+            }
+            catch (err) {
+                console.error("[chatkit] transcript on close failed:", err);
+            }
+        }
+        if (session.threadId != null) {
+            await this.transport.closeTopic(session.threadId);
+        }
+    }
+    // --- internals -----------------------------------------------------------
+    async requireSession(id) {
+        const s = await this.storage.getSession(id);
+        if (!s)
+            throw new ChatSessionNotFound(id);
+        return s;
+    }
+    async append(session, role, text, authorName) {
+        const message = {
+            id: crypto.randomUUID(),
+            sessionId: session.id,
+            role,
+            text,
+            createdAt: Date.now(),
+            ...(authorName ? { authorName } : {}),
+        };
+        await this.storage.appendMessage(message);
+        return message;
+    }
+    async mirror(session, html) {
+        if (session.threadId != null) {
+            await this.transport.sendMessage(session.threadId, html);
+        }
+    }
+}
+export class ChatSessionNotFound extends Error {
+    constructor(sessionId) {
+        super(`chat session not found: ${sessionId}`);
+        this.sessionId = sessionId;
+        this.name = "ChatSessionNotFound";
+    }
+}
+/** Escape text for Telegram HTML parse mode. */
+function esc(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * chatkit — a portable, self-hosted customer-chat module.
+ *
+ * A floating chat widget that routes conversations to wherever your team works
+ * (Telegram in v1; the transport seam makes Slack/Discord/email pluggable),
+ * with an optional Claude first-line that deflects common questions and
+ * escalates to a human when needed.
+ *
+ * This is the framework-agnostic core. Entry points:
+ *   - `chatkit`        → core (this file)
+ *   - `chatkit/next`   → Next.js App Router route factories
+ *   - `chatkit/react`  → the widget component
+ *
+ * The folder has no host-app imports, so it can be lifted into its own package.
+ */
+export * from "./types";
+export * from "./storage";
+export * from "./transport";
+export * from "./telegram";
+export * from "./ai";
+export * from "./local";
+export * from "./transcript";
+export * from "./engine";

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * chatkit — a portable, self-hosted customer-chat module.
+ *
+ * A floating chat widget that routes conversations to wherever your team works
+ * (Telegram in v1; the transport seam makes Slack/Discord/email pluggable),
+ * with an optional Claude first-line that deflects common questions and
+ * escalates to a human when needed.
+ *
+ * This is the framework-agnostic core. Entry points:
+ *   - `chatkit`        → core (this file)
+ *   - `chatkit/next`   → Next.js App Router route factories
+ *   - `chatkit/react`  → the widget component
+ *
+ * The folder has no host-app imports, so it can be lifted into its own package.
+ */
+export * from "./types";
+export * from "./storage";
+export * from "./transport";
+export * from "./telegram";
+export * from "./ai";
+export * from "./local";
+export * from "./transcript";
+export * from "./engine";