@qemuguest/site-chat-server 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 qemuguest
+
+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

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @qemuguest/site-chat-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Backend for website live chat. Web-standard handlers (`Request → Response`), pluggable storage, and relays
+to **SimpleX** (one chat per customer, via [`@qemuguest/site-chat-simplex-bridge`](https://www.npmjs.com/package/@qemuguest/site-chat-simplex-bridge)),
+**Telegram** (two-way) and **email**. Pairs with [`@qemuguest/site-chat-widget`](https://www.npmjs.com/package/@qemuguest/site-chat-widget).
+
+```sh
+npm i @qemuguest/site-chat-server
+```
+
+```ts
+import { createSiteChat, sqlStore, d1Driver, simplexRelay, telegram, emailAlerts, resendEmail } from "@qemuguest/site-chat-server";
+
+const chat = createSiteChat({
+  store: sqlStore(d1Driver(env.DB)),
+  basePath: "/api/site-chat",              // where you mount it (default)
+  channels: [
+    simplexRelay({ secret: env.SITE_CHAT_SECRET }),
+    telegram({ botToken: env.TELEGRAM_BOT_TOKEN, webhookSecret: env.TELEGRAM_WEBHOOK_SECRET }),
+    emailAlerts({ to: "me@example.com", send: resendEmail({ apiKey: env.RESEND_API_KEY, from: "Site <chat@example.com>" }) }),
+  ],
+  adminUrl: (id) => `https://example.com/admin/messages?c=${id}`,   // linked from alerts
+});
+
+// Any framework: hand it the Request.
+export default { fetch: (req: Request) => chat.fetch(req) };             // Cloudflare Worker
+export const GET = (req: Request) => chat.fetch(req), POST = GET;        // Next.js app/api/site-chat/[...path]/route.ts
+app.all("/api/site-chat/*", (c) => chat.fetch(c.req.raw));               // Hono
+```
+
+`chat.handle(req)` resolves to `null` for paths that aren't its own, so you can mount it alongside other routes.
+
+## Endpoints (under `basePath`)
+
+| Method & path | Who | What |
+| --- | --- | --- |
+| `POST /messages` | widget | start / continue a chat, send `{ text }` or `{ details: { name, email, phone } }` |
+| `GET /messages?id&token&after` | widget | poll for replies |
+| `POST /contact` | widget | contact form `{ name, email, phone?, business?, message }` |
+| `POST /telegram/webhook` | Telegram | bot updates (checked against `webhookSecret`) |
+| `GET /relay/outbox`, `POST /relay/ack`, `POST /relay/reply` | SimpleX bridge | `Authorization: Bearer <secret>` |
+
+Built in: per-IP limit on new conversations, per-conversation message limit, honeypot field, visitor tokens
+(only the visitor can read their thread), IPs stored only as salted hashes.
+
+## Storage
+
+- `memoryStore()` for tests and dev.
+- `sqlStore(driver, { prefix: "sc_" })` with `d1Driver(env.DB)` (Cloudflare D1) or `sqliteDriver(db)`
+  (better-sqlite3, `node:sqlite`). Create tables with `await store.migrate()` or run `schemaSql()` as a migration.
+- Or implement the `ChatStore` interface for anything else.
+
+## Admin
+
+```ts
+await chat.admin.list();                // conversations with last message + unread state
+await chat.admin.get(id);               // { conversation, messages }
+await chat.admin.reply(id, "On it!");   // appears live in the visitor's chat, mirrored to Telegram / SimpleX
+await chat.admin.markRead(id);
+await chat.admin.unreadCount();
+```
+
+## Telegram
+
+1. Create a bot with @BotFather; pick any long random `webhookSecret`.
+2. `const tg = telegram({ botToken, webhookSecret })`, pass it in `channels`, then once:
+   `const { link } = await tg.connect("https://example.com/api/site-chat/telegram/webhook")`.
+3. Open `link` and press Start. That chat is now the only one that gets messages and can answer.
+   Reply to a relayed message to answer the visitor live.
+
+## SimpleX
+
+Add `simplexRelay({ secret })` and run the bridge next to your SimpleX app. See
+[`@qemuguest/site-chat-simplex-bridge`](https://www.npmjs.com/package/@qemuguest/site-chat-simplex-bridge).
+
+## Custom channels
+
+```ts
+const slack: Channel = {
+  name: "slack",
+  async notify(e, ctx) { if (e.type === "visitor") await postToSlack(e.conversation, e.body); },
+  routes: { async "POST /slack/events"(req, ctx) { /* … */ await ctx.agentReply(conversationId, text, "slack"); return new Response("ok"); } },
+};
+```
+
+MIT