@mademi_dev/chatemi 1.0.0

package/docs/BACKEND_CONTRACT.md

@@ -0,0 +1,305 @@
+# ChatEmi backend contract
+
+This document describes the REST, WebSocket, and data contracts expected by the default ChatEmi API client and UI.
+
+## REST shape
+
+All JSON endpoints should return JSON. Paginated list endpoints should use:
+
+```json
+{
+  "items": [],
+  "nextCursor": null
+}
+```
+
+Errors should use:
+
+```json
+{
+  "message": "Human readable error",
+  "code": "OPTIONAL_MACHINE_CODE"
+}
+```
+
+## Authentication
+
+The browser client sends:
+
+```http
+Authorization: Bearer <token>
+```
+
+Validate the token on every REST request and socket connection. Do not trust role/member data from the client.
+
+## Users
+
+```ts
+type ChatEmiUser = {
+  id: string;
+  name: string;
+  username?: string;
+  avatarUrl?: string;
+  statusText?: string;
+  presence?: "online" | "offline" | "away" | "busy" | "invisible";
+  lastSeenAt?: string;
+};
+```
+
+Endpoints:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/me` | Current authenticated user |
+| `GET` | `/users?q=ava&limit=10` | Search users |
+| `GET` | `/users/:userId` | User details |
+| `PATCH` | `/users/:userId` | Update profile/avatar |
+
+## Conversations
+
+```ts
+type ChatEmiConversation = {
+  id: string;
+  type: "direct" | "group" | "channel" | "bot";
+  title?: string;
+  description?: string;
+  avatarUrl?: string;
+  participants: ChatEmiUser[];
+  members?: ChatEmiMember[];
+  ownerId?: string;
+  adminIds?: string[];
+  publicUsername?: string;
+  lastMessage?: ChatEmiMessage;
+  unreadCount?: number;
+  readOnly?: boolean;
+  createdAt: string;
+  updatedAt?: string;
+};
+```
+
+Endpoints:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/conversations` | List conversations |
+| `POST` | `/conversations` | Create direct/group/channel/bot conversation |
+| `GET` | `/conversations/:conversationId` | Conversation detail |
+| `PATCH` | `/conversations/:conversationId` | Update title, description, mute, archive, etc. |
+| `DELETE` | `/conversations/:conversationId` | Archive/delete conversation |
+| `PATCH` | `/conversations/:conversationId/avatar` | Update conversation avatar |
+
+## Members and admins
+
+```ts
+type ChatEmiMember = {
+  user: ChatEmiUser;
+  role: "owner" | "admin" | "moderator" | "member" | "guest";
+  permissions?: Array<
+    | "send_messages"
+    | "send_media"
+    | "pin_messages"
+    | "manage_messages"
+    | "manage_members"
+    | "manage_roles"
+    | "manage_conversation"
+    | "invite_members"
+  >;
+  joinedAt: string;
+  mutedUntil?: string | null;
+  bannedUntil?: string | null;
+  title?: string;
+};
+```
+
+Endpoints:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/conversations/:conversationId/members` | Add members `{ userIds: string[] }` |
+| `PATCH` | `/conversations/:conversationId/members/:userId` | Update role, permissions, mute, ban |
+| `DELETE` | `/conversations/:conversationId/members/:userId` | Remove member |
+
+Server rules:
+
+- Only owners/admins/moderators should manage members.
+- Only owners/admins should promote admins unless your product says otherwise.
+- Channels with `readOnly: true` should reject normal member messages.
+
+## Messages
+
+```ts
+type ChatEmiMessage = {
+  id: string;
+  conversationId: string;
+  sender: ChatEmiUser;
+  kind?: "text" | "media" | "voice" | "system";
+  text?: string;
+  html?: string;
+  attachments?: ChatEmiAttachment[];
+  replyTo?: ChatEmiMessage;
+  replyToId?: string;
+  forwardedFrom?: ChatEmiUser;
+  forwardedFromConversationId?: string;
+  forwardedFromMessageId?: string;
+  reactions?: ChatEmiReaction[];
+  status?: "queued" | "sending" | "sent" | "delivered" | "read" | "failed";
+  deliveredTo?: ChatEmiReceiptEvent[];
+  readBy?: ChatEmiReceiptEvent[];
+  createdAt: string;
+};
+```
+
+Endpoints:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `GET` | `/conversations/:conversationId/messages` | List messages |
+| `POST` | `/conversations/:conversationId/messages` | Send message |
+| `PATCH` | `/conversations/:conversationId/messages/:messageId` | Edit message |
+| `DELETE` | `/conversations/:conversationId/messages/:messageId` | Delete message |
+| `POST` | `/conversations/:conversationId/messages/:messageId/forward` | Forward message |
+
+Send message input:
+
+```json
+{
+  "conversationId": "conversation_1",
+  "text": "Hello",
+  "replyToId": "message_1",
+  "kind": "text",
+  "attachments": []
+}
+```
+
+## Attachments
+
+```ts
+type ChatEmiAttachment = {
+  id: string;
+  type: "image" | "video" | "audio" | "voice" | "file" | "location" | "contact";
+  url: string;
+  name?: string;
+  mimeType?: string;
+  size?: number;
+  width?: number;
+  height?: number;
+  duration?: number;
+  thumbnailUrl?: string;
+  caption?: string;
+};
+```
+
+Endpoint:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| `POST` | `/attachments` | Multipart upload |
+
+Expected response:
+
+```json
+{
+  "id": "attachment_1",
+  "type": "image",
+  "url": "https://cdn.example.com/file.png",
+  "name": "file.png",
+  "mimeType": "image/png",
+  "size": 12345
+}
+```
+
+## Receipts
+
+Endpoints:
+
+| Method | Path | Body |
+| --- | --- | --- |
+| `POST` | `/conversations/:conversationId/delivered` | `{ "messageIds": ["message_1"] }` |
+| `POST` | `/conversations/:conversationId/read` | `{ "messageIds": ["message_1"] }` |
+
+Socket event:
+
+```json
+{
+  "type": "message.receipt",
+  "payload": {
+    "conversationId": "conversation_1",
+    "messageIds": ["message_1"],
+    "userId": "user_2",
+    "status": "read",
+    "at": "2026-06-19T21:05:00.000Z"
+  }
+}
+```
+
+## WebSocket protocol
+
+Every event is an envelope:
+
+```json
+{
+  "type": "message.created",
+  "payload": {}
+}
+```
+
+Incoming events supported by the client:
+
+- `conversation.created`
+- `conversation.updated`
+- `conversation.deleted`
+- `conversation.member.added`
+- `conversation.member.updated`
+- `conversation.member.removed`
+- `message.created`
+- `message.updated`
+- `message.deleted`
+- `message.receipt`
+- `message.reaction`
+- `typing`
+- `presence`
+- `notification`
+
+Outgoing events sent by client helpers:
+
+- `conversation.subscribe`
+- `conversation.unsubscribe`
+- `typing`
+- `message.read`
+- `message.delivered`
+- `message.forward`
+- `conversation.member.update`
+- `conversation.avatar.update`
+- `presence`
+
+## Notification payload
+
+```json
+{
+  "type": "notification",
+  "payload": {
+    "id": "notification_1",
+    "kind": "message",
+    "title": "Ava",
+    "body": "Sent a message",
+    "conversationId": "conversation_1",
+    "messageId": "message_1",
+    "avatarUrl": "https://cdn.example.com/ava.png",
+    "read": false,
+    "createdAt": "2026-06-19T21:05:00.000Z"
+  }
+}
+```
+
+## Minimal implementation sequence
+
+1. Implement `/me`.
+2. Implement conversation list.
+3. Implement message list/send.
+4. Add WebSocket `message.created`.
+5. Add receipts.
+6. Add uploads.
+7. Add members/admins.
+8. Add notifications.
+9. Add external user directory.
+10. Add production monitoring and rate limits.

package/docs/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,306 @@
+# ChatEmi implementation guide
+
+This guide explains how to ship ChatEmi in a production application. It covers frontend setup, Next.js usage, backend API responsibilities, sockets, notifications, media, MongoDB, external user directories, theming, and release checks.
+
+## 1. Architecture
+
+ChatEmi is split into browser-safe and server-side pieces:
+
+| Area | Import | Runs in | Purpose |
+| --- | --- | --- | --- |
+| React package | `chatemi` | Browser / React client | Provider, hook, API client, socket client, launcher, messenger UI |
+| Styles | `chatemi/styles.css` | Browser | All default UI, themes, launcher modal, notification badge |
+| Server helpers | `chatemi/server` | Node.js only | MongoDB connection helper and collection/index setup |
+
+Do not expose database credentials to browser code. Browser code should call your authenticated HTTP and WebSocket APIs.
+
+## 2. Next.js setup
+
+### Install
+
+```bash
+npm install chatemi
+```
+
+If your API server uses ChatEmi MongoDB helpers:
+
+```bash
+npm install mongodb
+```
+
+### Import CSS once
+
+In App Router, import CSS from `app/layout.tsx`:
+
+```tsx
+import "chatemi/styles.css";
+```
+
+### Create a client widget
+
+The widget uses browser APIs (`localStorage`, WebSocket, notifications), so it must live in a client component:
+
+```tsx
+"use client";
+
+import { ChatEmiLauncher, ChatEmiProvider } from "chatemi";
+import { useMemo } from "react";
+
+export function ChatWidget() {
+  const config = useMemo(
+    () => ({
+      apiBaseUrl: process.env.NEXT_PUBLIC_CHAT_API_URL!,
+      socketUrl: process.env.NEXT_PUBLIC_CHAT_SOCKET_URL,
+      token: () => localStorage.getItem("access_token") ?? undefined,
+      theme: "glass" as const,
+      notifications: {
+        enabled: true,
+        browser: true,
+        showWhenOpen: false,
+        maxStored: 100
+      }
+    }),
+    []
+  );
+
+  return (
+    <ChatEmiProvider config={config}>
+      <ChatEmiLauncher placement="bottom-right" theme="glass" />
+    </ChatEmiProvider>
+  );
+}
+```
+
+## 3. Provider configuration
+
+```ts
+type ChatEmiConfig = {
+  apiBaseUrl: string;
+  socketUrl?: string;
+  token?: string | (() => string | Promise<string | undefined> | undefined);
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  currentUser?: ChatEmiUser;
+  endpoints?: ChatEmiEndpointOverrides;
+  userDirectory?: ChatEmiUserDirectoryConfig;
+  theme?: ChatEmiTheme;
+  notifications?: ChatEmiNotificationConfig;
+  reconnect?: {
+    enabled?: boolean;
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+  };
+};
+```
+
+Recommended defaults:
+
+```tsx
+<ChatEmiProvider
+  config={{
+    apiBaseUrl: "https://api.example.com/chat",
+    socketUrl: "wss://api.example.com/chat/socket",
+    token: () => auth.getAccessToken(),
+    theme: "system",
+    notifications: {
+      enabled: true,
+      browser: true,
+      showWhenOpen: false,
+      maxStored: 100
+    },
+    reconnect: {
+      enabled: true,
+      initialDelayMs: 500,
+      maxDelayMs: 8000
+    }
+  }}
+>
+  <ChatEmiLauncher />
+</ChatEmiProvider>
+```
+
+## 4. Launcher behavior
+
+`ChatEmiLauncher` is the recommended app integration:
+
+- Floating toggle button.
+- Notification count badge.
+- Draggable desktop modal.
+- Resizable desktop modal.
+- Full-width mobile modal.
+- Notification tray.
+- Keeps provider/socket running while closed.
+
+```tsx
+<ChatEmiLauncher
+  title="Support"
+  subtitle="Usually replies fast"
+  placement="bottom-right"
+  theme="midnight"
+  defaultOpen={false}
+  showNotificationList
+  markNotificationsReadOnOpen
+  initialSize={{ width: 460, height: 720 }}
+  minSize={{ width: 360, height: 520 }}
+  maxSize={{ width: 960, height: 860 }}
+/>
+```
+
+## 5. Notifications
+
+ChatEmi stores notifications inside provider state:
+
+```tsx
+const {
+  notifications,
+  unreadNotificationCount,
+  actions
+} = useChatEmi();
+
+actions.markNotificationsRead();
+actions.dismissNotification("notification_1");
+actions.clearNotifications();
+```
+
+### Socket notification event
+
+```json
+{
+  "type": "notification",
+  "payload": {
+    "id": "notif_1",
+    "kind": "message",
+    "title": "Ava",
+    "body": "Sent a new message",
+    "conversationId": "conversation_1",
+    "messageId": "message_1",
+    "read": false,
+    "createdAt": "2026-06-19T21:05:00.000Z"
+  }
+}
+```
+
+If your backend only emits `message.created`, ChatEmi automatically creates a local notification for messages sent by other users.
+
+Browser notifications are optional and require user permission. ChatEmi requests permission from a user gesture when the launcher opens.
+
+## 6. Backend responsibilities
+
+The package gives you UI and clients. Your backend owns:
+
+- Authentication and authorization.
+- Persisting conversations, messages, members, receipts, attachments.
+- Enforcing admin/member permissions.
+- Uploading media to your storage provider.
+- Broadcasting WebSocket events.
+- Mapping external users to `ChatEmiUser`.
+
+Minimum production endpoints:
+
+- `GET /me`
+- `GET /conversations`
+- `POST /conversations`
+- `GET /conversations/:conversationId/messages`
+- `POST /conversations/:conversationId/messages`
+- `POST /conversations/:conversationId/read`
+- `POST /conversations/:conversationId/delivered`
+- `POST /attachments`
+
+See `docs/BACKEND_CONTRACT.md` for full details.
+
+## 7. MongoDB integration
+
+Use `chatemi/server` only from Node.js:
+
+```ts
+import { createChatEmiMongoConnection } from "chatemi/server";
+
+const chatDb = await createChatEmiMongoConnection({
+  uri: process.env.MONGODB_URI!,
+  databaseName: "chatemi",
+  clientOptions: {
+    appName: "chatemi-api"
+  }
+});
+
+await chatDb.ensureIndexes();
+```
+
+Connection guidance:
+
+- Create the client once per process and reuse it.
+- In serverless, initialize outside the handler so warm invocations reuse the client.
+- Do not guess pool sizes. Use `clientOptions` based on deployment type, concurrency, and MongoDB metrics.
+- Monitor `connections.current`, query latency, and wait queue behavior.
+
+## 8. External user directory
+
+Use this when users live in another service:
+
+```tsx
+userDirectory: {
+  baseUrl: "https://identity.example.com",
+  searchPath: "/users/search",
+  userPath: (userId) => `/users/${userId}`,
+  headers: () => ({
+    Authorization: `Bearer ${identityToken()}`
+  }),
+  mapUser: (raw) => {
+    const user = raw as { id: string; displayName: string; photoUrl?: string };
+    return {
+      id: user.id,
+      name: user.displayName,
+      avatarUrl: user.photoUrl
+    };
+  }
+}
+```
+
+ChatEmi does not automatically send the chat API bearer token to the external user API. Add headers explicitly if needed.
+
+## 9. Themes
+
+Built-in themes:
+
+- `light`
+- `dark`
+- `system`
+- `midnight`
+- `glass`
+- `emerald`
+- `violet`
+
+Use the provider default:
+
+```tsx
+<ChatEmiProvider config={{ apiBaseUrl, theme: "violet" }}>
+  <ChatEmiLauncher />
+</ChatEmiProvider>
+```
+
+Or override per UI component:
+
+```tsx
+<ChatEmiLauncher theme="glass" />
+```
+
+## 10. Production checklist
+
+Before publishing or deploying:
+
+- Confirm package name and npm scope.
+- Confirm `apiBaseUrl` and `socketUrl` point to production services.
+- Verify auth token refresh behavior.
+- Verify CORS for REST and WebSocket APIs.
+- Verify attachment upload limits and file scanning.
+- Verify admin permissions server-side.
+- Verify socket reconnects after network loss.
+- Verify notification permission behavior in Chrome, Safari, Firefox.
+- Verify mobile launcher modal behavior.
+- Run:
+
+```bash
+npm run typecheck
+npm run build
+npm pack --dry-run
+```

package/examples/nextjs-chat-widget/README.md

@@ -0,0 +1,46 @@
+# ChatEmi Next.js widget example
+
+This example shows how to use ChatEmi in a Next.js App Router application with:
+
+- `ChatEmiProvider`
+- `ChatEmiLauncher`
+- floating notification badge
+- draggable/resizable modal
+- browser notifications
+- external user-directory configuration
+- server-side MongoDB helper usage
+
+The files are intentionally small and copy-paste friendly. They are not a standalone app inside this repository; copy them into a Next.js project that has `next`, `react`, `react-dom`, `chatemi`, and optionally `mongodb` installed.
+
+## Install in your app
+
+```bash
+npm install chatemi
+```
+
+If you also use the MongoDB server helpers:
+
+```bash
+npm install mongodb
+```
+
+## Environment variables
+
+```bash
+NEXT_PUBLIC_CHAT_API_URL=https://api.example.com/chat
+NEXT_PUBLIC_CHAT_SOCKET_URL=wss://api.example.com/chat/socket
+NEXT_PUBLIC_IDENTITY_API_URL=https://identity.example.com
+MONGODB_URI=mongodb+srv://...
+MONGODB_DB=chatemi
+```
+
+Only `NEXT_PUBLIC_*` values are sent to the browser. Keep `MONGODB_URI` server-side only.
+
+## Files
+
+- `app/layout.tsx` imports `chatemi/styles.css` once.
+- `app/components/ChatWidget.tsx` is the client-side launcher widget.
+- `app/lib/chatemi-config.ts` centralizes browser-safe config.
+- `app/lib/chatemi-mongo.ts` shows server-side MongoDB setup.
+- `app/api/chat/conversations/route.ts` shows how an API route can read MongoDB.
+- `app/api/chat/socket-events/route.ts` documents example socket event payloads.

package/examples/nextjs-chat-widget/app/api/chat/conversations/route.ts

@@ -0,0 +1,30 @@
+import { NextResponse } from "next/server";
+import { getChatEmiMongo } from "../../../lib/chatemi-mongo";
+
+export async function GET() {
+  const { collections } = await getChatEmiMongo();
+  const conversations = await collections.conversations.find({ archived: { $ne: true } }).sort({ updatedAt: -1 }).limit(50).toArray();
+
+  return NextResponse.json({
+    items: conversations,
+    nextCursor: null
+  });
+}
+
+export async function POST(request: Request) {
+  const { collections } = await getChatEmiMongo();
+  const input = await request.json();
+  const now = new Date().toISOString();
+
+  const conversation = {
+    ...input,
+    participants: [],
+    createdAt: now,
+    updatedAt: now,
+    unreadCount: 0
+  };
+
+  await collections.conversations.insertOne(conversation);
+
+  return NextResponse.json(conversation, { status: 201 });
+}