@rizvanua/contact-chat 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Ivanytskyi
+
+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,496 @@
+# @rizvanua/contact-chat
+
+<!-- npm version, tests, license badges go here after first publish -->
+
+[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+Telegram-backed contact-chat widget: framework-agnostic server core, headless React hooks, and unstyled UI reference components. Extracted from the CV-webpage project.
+
+---
+
+## Install
+
+```bash
+pnpm add @rizvanua/contact-chat
+# or
+npm install @rizvanua/contact-chat
+# or
+yarn add @rizvanua/contact-chat
+```
+
+**Peer dependencies** — install alongside the package:
+
+```bash
+# Required for the server store (Upstash Redis):
+pnpm add @upstash/redis
+
+# Required for React hooks:
+pnpm add react react-dom jotai
+
+# Optional for the /ui reference components (headless dialog, icons, class merging):
+pnpm add @headlessui/react lucide-react tailwind-merge
+```
+
+Node 18+ is required (Web `fetch`, `crypto.randomUUID`).
+
+---
+
+## Quick start (server)
+
+```ts
+import {
+  createChatServer,
+  upstashRedisStore,
+  telegramTransport,
+} from '@rizvanua/contact-chat/server';
+
+const url = process.env.UPSTASH_REDIS_REST_URL || process.env.KV_REST_API_URL;
+const token = process.env.UPSTASH_REDIS_REST_TOKEN || process.env.KV_REST_API_TOKEN;
+if (!url || !token) throw new Error('Redis is not configured.');
+
+export const chatServer = createChatServer({
+  store: upstashRedisStore({ url, token }),
+  // The transport owns the webhook secret — pass it here, not to createChatServer.
+  transport: telegramTransport({
+    botToken:      process.env.TELEGRAM_BOT_TOKEN ?? '',
+    chatId:        process.env.TELEGRAM_CHAT_ID ?? '',
+    webhookSecret: process.env.TELEGRAM_WEBHOOK_SECRET ?? '',
+  }),
+  ipHashSalt: process.env.CHAT_IP_HASH_SALT ?? '',
+});
+```
+
+For local dev and demos without Redis, use `inMemoryStore()` instead:
+
+```ts
+import { createChatServer, inMemoryStore, telegramTransport } from '@rizvanua/contact-chat/server';
+
+export const chatServer = createChatServer({
+  store: inMemoryStore(),
+  // The transport owns the webhook secret — pass it here, not to createChatServer.
+  transport: telegramTransport({ botToken: '...', chatId: '...', webhookSecret: '...' }),
+  ipHashSalt: 'dev-salt',
+});
+```
+
+---
+
+## Server
+
+All handlers are Web-standard `(request: Request) => Promise<Response>`. Use `toNextRoute` to wire them into a Next.js App Router project.
+
+### Route files
+
+**`app/api/chat/send/route.ts`**
+```ts
+import { toNextRoute } from '@rizvanua/contact-chat/server/nextjs';
+import { chatServer } from '@/lib/chat-server';
+export const POST = toNextRoute(chatServer.send);
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+```
+
+**`app/api/chat/poll/route.ts`**
+```ts
+import { toNextRoute } from '@rizvanua/contact-chat/server/nextjs';
+import { chatServer } from '@/lib/chat-server';
+export const GET = toNextRoute(chatServer.poll);
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+```
+
+**`app/api/chat/telegram-webhook/route.ts`**
+```ts
+import { toNextRoute } from '@rizvanua/contact-chat/server/nextjs';
+import { chatServer } from '@/lib/chat-server';
+export const POST = toNextRoute(chatServer.webhook);
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+```
+
+See `examples/nextjs-app/` for the complete reference wiring.
+
+### Env resolution
+
+The consumer's app resolves credentials — the package never reads `process.env` directly.
+
+The Vercel Upstash integration provisions `KV_REST_API_URL` / `KV_REST_API_TOKEN`. The standalone Upstash integration uses `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN`. Support both with `||` (not `??`), because `vercel env pull` can write blank entries:
+
+```ts
+const url = process.env.UPSTASH_REDIS_REST_URL || process.env.KV_REST_API_URL;
+const token = process.env.UPSTASH_REDIS_REST_TOKEN || process.env.KV_REST_API_TOKEN;
+if (!url || !token) throw new Error('Redis is not configured.');
+```
+
+Full set of env vars the consumer configures:
+
+| Variable | Description |
+| --- | --- |
+| `UPSTASH_REDIS_REST_URL` / `KV_REST_API_URL` | Redis REST URL (dual Upstash pair) |
+| `UPSTASH_REDIS_REST_TOKEN` / `KV_REST_API_TOKEN` | Redis REST token (dual Upstash pair) |
+| `TELEGRAM_BOT_TOKEN` | Bot token from BotFather |
+| `TELEGRAM_CHAT_ID` | Telegram group/supergroup numeric ID |
+| `TELEGRAM_WEBHOOK_SECRET` | Secret for webhook verification |
+| `CHAT_IP_HASH_SALT` | Salt for hashing visitor IPs |
+
+### setWebhook
+
+Register your webhook URL with Telegram once (or whenever your domain changes). See [Telegram docs: setWebhook](https://core.telegram.org/bots/api#setwebhook).
+
+```bash
+curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
+  -H 'Content-Type: application/json' \
+  -d "{\"url\":\"https://your.domain/api/chat/telegram-webhook\",\"secret_token\":\"$TELEGRAM_WEBHOOK_SECRET\",\"allowed_updates\":[\"message\"]}"
+```
+
+### Telegram + Upstash setup
+
+- **Telegram bot:** create via [@BotFather](https://t.me/BotFather); add the bot to your supergroup and enable forum topics in the group settings.
+- **Upstash Redis:** [Upstash Console](https://console.upstash.com/); or via the [Vercel Upstash integration](https://vercel.com/integrations/upstash) which provisions `KV_REST_API_*` variables automatically.
+
+---
+
+## React (client)
+
+Import from `@rizvanua/contact-chat/react`. Requires `react`, `react-dom`, and `jotai` as peers.
+
+### `<ChatClientProvider>`
+
+Wrap your app (or the subtree containing the chat widget) with `ChatClientProvider`. All props are optional — defaults work out of the box.
+
+```tsx
+// app/providers.tsx  (Next.js App Router example)
+'use client';
+
+import { ChatClientProvider } from '@rizvanua/contact-chat/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ChatClientProvider
+      basePath="/api/chat"
+      chime={process.env.NEXT_PUBLIC_CHAT_CHIME !== 'false'}
+      onEvent={(e) => {
+        if (e.type === 'chat.send.success') {
+          // e.g. gtag('event', 'contact_chat_sent')
+        }
+      }}
+    >
+      {children}
+    </ChatClientProvider>
+  );
+}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `basePath` | `string` | `'/api/chat'` | Base path for the three route files (`/send`, `/poll`, `/telegram-webhook`). |
+| `sessionStorageKey` | `string` | `'contact-chat-session'` | `localStorage` key for the session id. |
+| `nameStorageKey` | `string` | `'contact-chat-name'` | `localStorage` key for the visitor's name. |
+| `chime` | `boolean` | `true` | Play a two-note synthesized chime when an owner reply arrives. |
+| `maxMessageLength` | `number` | `2000` | Client-side max message length; should match the server's `ChatLimits.maxMessageLength`. |
+| `onEvent` | `(e: ChatClientEvent) => void` | — | Optional analytics callback fired on lifecycle events (`chat.open`, `chat.close`, `chat.send.attempt`, `chat.send.success`, `chat.send.error`). |
+
+### `useChatActions()`
+
+Reads chat state and provides action callbacks. Safe to call from any number of components — it contains no polling effects.
+
+```tsx
+'use client';
+
+import { useChatActions } from '@rizvanua/contact-chat/react';
+
+export function MyComposer() {
+  const { open, setOpen, messages, unread, status, error, name, setName, send, canSend } =
+    useChatActions();
+
+  if (!open) {
+    return (
+      <button onClick={() => setOpen(true)}>
+        Chat {unread > 0 && <span>{unread}</span>}
+      </button>
+    );
+  }
+
+  return (
+    <div>
+      {messages.map((msg) => (
+        <p key={msg.id}>{msg.text}</p>
+      ))}
+      {status === 'error' && <p>{error}</p>}
+      <button
+        disabled={!canSend}
+        onClick={() => send('Hello from my bespoke composer')}
+      >
+        Send
+      </button>
+      <button onClick={() => setOpen(false)}>Close</button>
+    </div>
+  );
+}
+```
+
+Return shape:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `open` | `boolean` | Whether the chat panel is open. |
+| `setOpen` | `(v: boolean \| ((prev: boolean) => boolean)) => void` | Opens or closes the panel. Fires `chat.open` / `chat.close` on the `onEvent` callback. |
+| `messages` | `ChatMessage[]` | All messages in the session, sorted by server timestamp. |
+| `unread` | `number` | Count of owner replies that arrived while the panel was closed. |
+| `status` | `'idle' \| 'sending' \| 'error' \| 'unavailable'` | Send status. |
+| `error` | `string \| null` | Human-readable error message when `status === 'error'`. |
+| `name` | `string \| null` | The visitor's name once set. |
+| `setName` | `(raw: string) => boolean` | Sanitizes and stores the name; returns `false` when the name is unusable (empty after stripping). |
+| `send` | `(text: string) => Promise<void>` | Sends a message; appends it optimistically. |
+| `canSend` | `boolean` | `false` while a send is in-flight (`status === 'sending'`). |
+
+### `useChatSync()`
+
+Owns the polling lifecycle: hydrates session/name from `localStorage`, runs adaptive polling (4 s while open, 15 s when idle, pauses for backgrounded tabs), and fires the chime on owner replies.
+
+**Mount this exactly once** in the component tree. Two mounts run two racing polling loops on the same cursor. The simplest placement is inside `<ChatLauncher>` (which calls it internally), or inside a single `<providers.tsx>` component that is guaranteed to mount once.
+
+```tsx
+// app/providers.tsx  — mount useChatSync once alongside the provider
+'use client';
+
+import { ChatClientProvider } from '@rizvanua/contact-chat/react';
+import { useChatSync } from '@rizvanua/contact-chat/react';
+
+function ChatSync() {
+  useChatSync();
+  return null;
+}
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ChatClientProvider>
+      <ChatSync />
+      {children}
+    </ChatClientProvider>
+  );
+}
+```
+
+If you use `<ChatLauncher>` from the `/ui` entry, skip the manual `useChatSync` mount — `ChatLauncher` already calls it.
+
+### Advanced exports
+
+`mergeMessages`, the Jotai atoms (`chatOpenAtom`, `chatMessagesAtom`, etc.), and `playChime` are all exported from `@rizvanua/contact-chat/react` for advanced consumers who want to integrate the state into an existing Jotai store or trigger the chime from custom logic.
+
+---
+
+## UI (unstyled reference components)
+
+Import from `@rizvanua/contact-chat/ui`. Requires `@headlessui/react`, `lucide-react`, and `tailwind-merge` as optional peers.
+
+```bash
+pnpm add @headlessui/react lucide-react tailwind-merge
+```
+
+All components ship with sensible Tailwind defaults (dark theme, purple accent). Override any class with the `classNames` prop — classes are merged via `tailwind-merge` so specificity conflicts are resolved correctly.
+
+### `<ChatLauncher>`
+
+A floating button that opens the chat panel. Internally calls `useChatSync()`, so mount it exactly once.
+
+```tsx
+import { MessageCircle } from 'lucide-react';
+import { ChatLauncher } from '@rizvanua/contact-chat/ui';
+
+export default function Page() {
+  return (
+    <main>
+      <h1>My page</h1>
+      <ChatLauncher
+        icon={<MessageCircle size={18} />}
+        labels={{ button: 'Talk to me' }}
+        classNames={{ button: 'bg-blue-600 hover:bg-blue-700' }}
+        onEvent={(e) => console.log(e.type)}
+      />
+    </main>
+  );
+}
+```
+
+Props:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `labels.button` | `string` | `'Contact me'` | Button text. |
+| `labels.unreadAriaLabel` | `(n: number) => string` | `'N unread replies'` | ARIA label for the unread badge. |
+| `classNames.button` | `string` | — | Extra classes merged onto the button. |
+| `classNames.unreadBadge` | `string` | — | Extra classes merged onto the badge dot. |
+| `icon` | `React.ReactNode` | — | Icon rendered inside the button. Pass `<MessageCircle />` or any SVG. |
+| `onEvent` | `(e: { type: 'ui.launcher.open' }) => void` | — | Fires when the launcher button is clicked. |
+| `children` | `React.ReactNode` | `<ChatDialog />` | Custom dialog; pass `null` to skip the dialog mount. |
+
+### `<ChatDialog>`
+
+The chat panel: header with name, message list, name gate, and composer. Uses `@headlessui/react` `<Dialog>` with transition.
+
+```tsx
+import { ChatDialog } from '@rizvanua/contact-chat/ui';
+
+// Used inside a ChatLauncher's children prop to provide a custom dialog:
+<ChatLauncher>
+  <ChatDialog
+    labels={{
+      title: 'Get in touch',
+      greeting: (name) => `Hey ${name}! Drop me a line.`,
+      unavailableFallback: <a href="mailto:me@example.com">Email me instead</a>,
+    }}
+    classNames={{ panel: 'max-w-sm' }}
+  />
+</ChatLauncher>
+```
+
+Key props:
+
+| Prop | Description |
+| --- | --- |
+| `labels.title` | Header title. Default: `'Chat'`. |
+| `labels.titleWithName` | Suffix appended when name is set. Default: `(n) => ' · ' + n`. |
+| `labels.greeting` | Shown once name is accepted. |
+| `labels.composerPlaceholder` | `(nameOk: boolean) => string`. |
+| `labels.unavailableFallback` | `React.ReactNode` shown on `'unavailable'` status. |
+| `classNames.*` | Per-element class overrides (overlay, panel, header, body, composer, textarea, sendButton, …). |
+| `renderMessage` | `(message: ChatMessage) => React.ReactNode` — replaces `<MessageBubble>`. |
+| `nameGate` | `React.ReactNode` — replaces `<NameGate>`. |
+
+### `<NameGate>`
+
+An inline name-entry form. Rendered automatically by `<ChatDialog>` until the visitor enters a valid name. Pass `nameGate={<NameGate labels={{ prompt: 'Who are you?' }} />}` to `<ChatDialog>` to customise it.
+
+| Prop | Description |
+| --- | --- |
+| `labels.prompt` | Default: `"Before we start — what's your name?"` |
+| `labels.placeholder` | Default: `'Your name'` |
+| `labels.submitButton` | Default: `'Start chat'` |
+| `labels.error` | Default: `'Please enter your name.'` |
+| `classNames.*` | Per-element class overrides (container, prompt, inputRow, input, submitButton, error). |
+
+### `<MessageBubble>`
+
+Renders a single `ChatMessage` as a chat bubble (visitor right-aligned purple, owner left-aligned grey). Usually rendered internally by `<ChatDialog>`, but exported for consumers who pass a custom `renderMessage`.
+
+```tsx
+import { MessageBubble } from '@rizvanua/contact-chat/ui';
+
+renderMessage={(msg) => <MessageBubble message={msg} classNames={{ bubble: 'text-base' }} />}
+```
+
+### Working styled reference
+
+See [`examples/nextjs-app/app/page.tsx`](./examples/nextjs-app/app/page.tsx) for a complete, styled implementation using all four components together.
+
+---
+
+## Migration guide
+
+Moving from a vendored `lib/chat/` copy to `@rizvanua/contact-chat`:
+
+### Server
+
+**Before (vendored):**
+```ts
+// lib/chat-server.ts
+import { createChatServer } from '@/lib/chat/server';
+import { upstashRedisStore } from '@/lib/chat/stores/upstash-redis';
+import { telegramTransport } from '@/lib/chat/transports/telegram';
+```
+
+**After (package):**
+```ts
+// lib/chat-server.ts
+import {
+  createChatServer,
+  upstashRedisStore,
+  telegramTransport,
+} from '@rizvanua/contact-chat/server';
+```
+
+**Route files — before (verbose):**
+```ts
+// app/api/chat/send/route.ts  (20+ lines importing internal handlers)
+```
+
+**Route files — after (5 lines each):**
+```ts
+import { toNextRoute } from '@rizvanua/contact-chat/server/nextjs';
+import { chatServer } from '@/lib/chat-server';
+export const POST = toNextRoute(chatServer.send);
+export const runtime = 'nodejs';
+export const dynamic = 'force-dynamic';
+```
+
+### React state (Jotai atoms)
+
+**Before:**
+```ts
+import { chatOpenAtom, chatMessagesAtom } from '@/store/chat';
+```
+
+**After:**
+```ts
+import { chatOpenAtom, chatMessagesAtom } from '@rizvanua/contact-chat/react';
+```
+
+### UI components
+
+**Before:**
+```tsx
+import { ChatLauncher } from '@/components/ContactChat/ChatLauncher';
+import { ChatDialog } from '@/components/ContactChat/ChatDialog';
+```
+
+**After:**
+```tsx
+import { ChatLauncher, ChatDialog } from '@rizvanua/contact-chat/ui';
+```
+
+### Env vars
+
+Env vars are the consumer's responsibility — the package never reads `process.env` directly. Configure these in your `.env.local` / Vercel environment settings:
+
+```
+UPSTASH_REDIS_REST_URL=...
+UPSTASH_REDIS_REST_TOKEN=...
+# or, if using the Vercel Upstash integration:
+KV_REST_API_URL=...
+KV_REST_API_TOKEN=...
+
+TELEGRAM_BOT_TOKEN=...
+TELEGRAM_CHAT_ID=...
+TELEGRAM_WEBHOOK_SECRET=...
+CHAT_IP_HASH_SALT=...
+```
+
+### Feature flags / hooks
+
+DOS-mode protection, feature flags, and analytics hooks are handled via the package's own extension points:
+
+- **Feature flag / gtag events** — pass `onEvent` to `<ChatClientProvider>` or `<ChatLauncher>`.
+- **Custom classNames** — pass `classNames` to `<ChatLauncher>` / `<ChatDialog>` to apply your design system classes.
+- **Unavailability fallback** — pass `labels.unavailableFallback` to `<ChatDialog>` (e.g. an email link).
+
+### What to delete
+
+After migrating, remove:
+- `lib/chat/` — the vendored server core.
+- `store/chat.ts` — replaced by atoms from `/react`.
+- `components/ContactChat/` — replaced by components from `/ui`.
+- The old verbose route files under `app/api/chat/`.
+
+---
+
+## Development
+
+This package is extracted from the CV-webpage project. See the extraction plan:
+[`docs/plans/2026-08-25-contact-chat-npm-package.md`](./docs/plans/2026-08-25-contact-chat-npm-package.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).