@mademi_dev/chatemi 1.0.0 → 1.0.1

package/README.md

@@ -13,12 +13,34 @@ ChatEmi is a publish-ready React messaging package for building in-app messenger
 - `useChatEmi` for product code that needs chat actions and state.
 - `ChatEmiMessenger`, a default responsive light/dark Telegram-style UI that can be used immediately or customized.
 
+Repository: [github.com/mademi-dev/ChatEmi](https://github.com/mademi-dev/ChatEmi)
+
+## Requirements
+
+- React `>=18`
+- React DOM `>=18`
+- MongoDB driver `>=7` (optional, server-side only)
+
 ## Install
 
 ```bash
-npm install chatemi
+npm install @mademi_dev/chatemi react react-dom
 ```
 
+For MongoDB server helpers in your API backend:
+
+```bash
+npm install @mademi_dev/chatemi mongodb
+```
+
+## Package exports
+
+| Import | Purpose |
+| --- | --- |
+| `@mademi_dev/chatemi` | Provider, hook, API client, socket client, launcher, messenger UI, and types |
+| `@mademi_dev/chatemi/styles.css` | Default UI, themes, launcher modal, and notification badge styles |
+| `@mademi_dev/chatemi/server` | Node.js MongoDB connection helper and index setup |
+
 ## Documentation and examples
 
 - Full implementation guide: [`docs/IMPLEMENTATION_GUIDE.md`](docs/IMPLEMENTATION_GUIDE.md)
@@ -26,8 +48,8 @@ npm install chatemi
 - Next.js launcher example: [`examples/nextjs-chat-widget`](examples/nextjs-chat-widget)
 
 ```tsx
-import { ChatEmiLauncher, ChatEmiMessenger, ChatEmiProvider, useChatEmi } from "chatemi";
-import "chatemi/styles.css";
+import { ChatEmiLauncher, ChatEmiMessenger, ChatEmiProvider, useChatEmi } from "@mademi_dev/chatemi";
+import "@mademi_dev/chatemi/styles.css";
 
 export function App() {
   return (
@@ -62,7 +84,7 @@ export function App() {
 Import package CSS once from `app/layout.tsx`:
 
 ```tsx
-import "chatemi/styles.css";
+import "@mademi_dev/chatemi/styles.css";
 import type { Metadata } from "next";
 
 export const metadata: Metadata = {
@@ -83,7 +105,7 @@ Create a client component for the widget:
 ```tsx
 "use client";
 
-import { ChatEmiLauncher, ChatEmiProvider } from "chatemi";
+import { ChatEmiLauncher, ChatEmiProvider } from "@mademi_dev/chatemi";
 
 export function ChatWidget() {
   return (
@@ -114,10 +136,50 @@ export function ChatWidget() {
 
 Then render `<ChatWidget />` from any client component or include it in a page layout. The provider keeps the socket connected while the launcher modal is closed, so incoming `notification` and `message.created` events continue updating the badge in the background.
 
+## Provider configuration
+
+`ChatEmiProvider` accepts:
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `config` | required | API, socket, auth, theme, and notification settings |
+| `autoConnect` | `true` | Connect the socket on mount when `socketUrl` is set |
+| `initialConversations` | `[]` | Seed conversation list before the first REST fetch |
+| `initialActiveConversationId` | first conversation | Pre-select a conversation |
+| `initialNotifications` | `[]` | Seed notification tray state |
+
+`config` fields:
+
+```ts
+type ChatEmiConfig = {
+  apiBaseUrl: string;
+  socketUrl?: string;
+  token?: string | (() => string | Promise<string | undefined> | undefined);
+  headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  currentUser?: ChatEmiUser;
+  fetchImpl?: typeof fetch;
+  websocketFactory?: (url: string) => WebSocket;
+  endpoints?: ChatEmiEndpointOverrides;
+  userDirectory?: ChatEmiUserDirectoryConfig;
+  theme?: ChatEmiTheme;
+  notifications?: ChatEmiNotificationConfig;
+  reconnect?: {
+    enabled?: boolean;
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+  };
+};
+```
+
+The socket appends `?token=<token>` to `socketUrl` when a token is configured. Override any REST path with `config.endpoints`.
+
 ## Hook usage
 
+`useChatEmi()` returns provider state, low-level clients, and actions:
+
 ```tsx
-import { useChatEmi } from "chatemi";
+import { useChatEmi } from "@mademi_dev/chatemi";
 
 export function SendWelcomeButton({ conversationId }: { conversationId: string }) {
   const { actions, activeMessages, connectionStatus } = useChatEmi();
@@ -138,6 +200,51 @@ export function SendWelcomeButton({ conversationId }: { conversationId: string }
 }
 ```
 
+State highlights:
+
+- `currentUser`, `conversations`, `activeConversation`, `activeMessages`
+- `notifications`, `unreadNotificationCount`
+- `typingByConversation`, `presenceByUser`
+- `connectionStatus`, `loading`, `error`, `theme`
+- `api`, `socket`
+
+Action highlights:
+
+- Conversations: `refreshConversations`, `openConversation`, `createConversation`
+- Messages: `sendMessage`, `editMessage`, `deleteMessage`, `forwardMessage`, `searchMessages`
+- Receipts: `markRead`, `markDelivered`
+- Reactions and media: `addReaction`, `removeReaction`, `uploadAttachment`, `updateAvatar`
+- Members: `addMembers`, `updateMember`, `removeMember`
+- Presence: `startTyping`, `stopTyping`, `setPresence`
+- Notifications: `dismissNotification`, `markNotificationsRead`, `clearNotifications`, `requestNotificationPermission`
+- Connection: `connect`, `disconnect`
+
+## Low-level clients
+
+You can use the typed clients outside React when needed:
+
+```ts
+import { ChatEmiApi, ChatEmiSocket } from "@mademi_dev/chatemi";
+
+const api = new ChatEmiApi({
+  apiBaseUrl: "https://api.example.com/chat",
+  token: () => getAccessToken()
+});
+
+const socket = new ChatEmiSocket({
+  apiBaseUrl: "https://api.example.com/chat",
+  socketUrl: "wss://api.example.com/chat/socket",
+  token: () => getAccessToken()
+});
+
+await socket.connect();
+socket.on("message.created", (message) => {
+  console.log(message);
+});
+```
+
+`ChatEmiApiError` is exported for typed REST error handling.
+
 ## Expected REST API contract
 
 By default ChatEmi calls these paths under `apiBaseUrl`:
@@ -159,7 +266,7 @@ By default ChatEmi calls these paths under `apiBaseUrl`:
 | Attachment upload | `POST /attachments` multipart form data |
 | Search | `GET /search/messages?q=...` |
 
-If your backend uses different paths, pass `config.endpoints` to override any route.
+If your backend uses different paths, pass `config.endpoints` to override any route. See [`docs/BACKEND_CONTRACT.md`](docs/BACKEND_CONTRACT.md) for request/response shapes.
 
 ## Socket event contract
 
@@ -211,12 +318,27 @@ Use `ChatEmiLauncher` when you want a floating in-app messenger:
   theme="midnight"
   title="Messages"
   subtitle="Team chat"
+  defaultOpen={false}
+  showNotificationList
+  markNotificationsReadOnOpen
   initialSize={{ width: 460, height: 720 }}
   minSize={{ width: 360, height: 520 }}
   maxSize={{ width: 960, height: 860 }}
 />
 ```
 
+Launcher props:
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `placement` | `bottom-right` | `bottom-right`, `bottom-left`, `top-right`, or `top-left` |
+| `defaultOpen` | `false` | Whether the modal starts open |
+| `showNotificationList` | `true` | Show the compact tray above the chat |
+| `markNotificationsReadOnOpen` | `true` | Mark notifications read when opening |
+| `badgeCount` | unread notifications or conversation unread total | Override launcher badge count |
+| `launcherIcon` | built-in icon | Custom toggle button content |
+| `initialSize` / `minSize` / `maxSize` | `420x680` / `340x480` / `920x860` | Desktop modal sizing |
+
 The launcher includes:
 
 - toggle button with unread notification badge
@@ -379,11 +501,11 @@ Use `config.userDirectory` when users live outside your chat backend. ChatEmi wi
 MongoDB must be connected from your API server, not from browser React code. Install the optional peer dependency in your backend:
 
 ```bash
-npm install chatemi mongodb
+npm install @mademi_dev/chatemi mongodb
 ```
 
 ```ts
-import { createChatEmiMongoConnection } from "chatemi/server";
+import { createChatEmiMongoConnection, ensureChatEmiIndexes } from "@mademi_dev/chatemi/server";
 
 const chatDb = await createChatEmiMongoConnection({
   uri: process.env.MONGODB_URI!,
@@ -405,6 +527,16 @@ export const receipts = chatDb.collections.receipts;
 export const attachments = chatDb.collections.attachments;
 ```
 
+Default collection names:
+
+- `chatemi_conversations`
+- `chatemi_messages`
+- `chatemi_members`
+- `chatemi_receipts`
+- `chatemi_attachments`
+
+Override them with `collectionNames` when creating the connection. The helper reuses one MongoDB client per process and URI/options pair.
+
 Connection guidance:
 
 - Create one MongoDB client per server process and reuse it.
@@ -422,6 +554,18 @@ Use `theme="light"`, `theme="dark"`, `theme="system"`, `theme="midnight"`, `them
 
 ## Customizing the UI
 
+`ChatEmiMessenger` props:
+
+| Prop | Default | Purpose |
+| --- | --- | --- |
+| `showSidebar` | `true` | Conversation list sidebar |
+| `enableAdminControls` | `true` | Member management panel for admins |
+| `enableMessageActions` | `true` | Reply, react, and forward actions |
+| `enableMediaPreview` | `true` | Inline image/video/audio previews |
+| `composerPlaceholder` | `Write a message...` | Composer input placeholder |
+| `renderConversation` | built-in row | Custom conversation list item |
+| `renderMessage` | built-in bubble | Custom message renderer |
+
 ```tsx
 <ChatEmiMessenger
   composerPlaceholder="Message the team"
@@ -442,10 +586,12 @@ npm run typecheck
 npm run build
 ```
 
+`prepublishOnly` runs `npm run build` automatically before publish.
+
 ## Publishing
 
-Update the version in `package.json`, then run:
+This package is published under the `@mademi_dev` scope. Update the version in `package.json`, then run:
 
 ```bash
-npm publish
+npm publish --access public
 ```

package/docs/IMPLEMENTATION_GUIDE.md

@@ -8,9 +8,9 @@ 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 |
+| React package | `@mademi_dev/chatemi` | Browser / React client | Provider, hook, API client, socket client, launcher, messenger UI |
+| Styles | `@mademi_dev/chatemi/styles.css` | Browser | All default UI, themes, launcher modal, notification badge |
+| Server helpers | `@mademi_dev/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.
 
@@ -19,7 +19,7 @@ Do not expose database credentials to browser code. Browser code should call you
 ### Install
 
 ```bash
-npm install chatemi
+npm install @mademi_dev/chatemi
 ```
 
 If your API server uses ChatEmi MongoDB helpers:
@@ -33,7 +33,7 @@ npm install mongodb
 In App Router, import CSS from `app/layout.tsx`:
 
 ```tsx
-import "chatemi/styles.css";
+import "@mademi_dev/chatemi/styles.css";
 ```
 
 ### Create a client widget
@@ -43,7 +43,7 @@ The widget uses browser APIs (`localStorage`, WebSocket, notifications), so it m
 ```tsx
 "use client";
 
-import { ChatEmiLauncher, ChatEmiProvider } from "chatemi";
+import { ChatEmiLauncher, ChatEmiProvider } from "@mademi_dev/chatemi";
 import { useMemo } from "react";
 
 export function ChatWidget() {
@@ -210,10 +210,10 @@ See `docs/BACKEND_CONTRACT.md` for full details.
 
 ## 7. MongoDB integration
 
-Use `chatemi/server` only from Node.js:
+Use `@mademi_dev/chatemi/server` only from Node.js:
 
 ```ts
-import { createChatEmiMongoConnection } from "chatemi/server";
+import { createChatEmiMongoConnection } from "@mademi_dev/chatemi/server";
 
 const chatDb = await createChatEmiMongoConnection({
   uri: process.env.MONGODB_URI!,

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

@@ -10,12 +10,12 @@ This example shows how to use ChatEmi in a Next.js App Router application with:
 - 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.
+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`, `@mademi_dev/chatemi`, and optionally `mongodb` installed.
 
 ## Install in your app
 
 ```bash
-npm install chatemi
+npm install @mademi_dev/chatemi
 ```
 
 If you also use the MongoDB server helpers:
@@ -38,7 +38,7 @@ Only `NEXT_PUBLIC_*` values are sent to the browser. Keep `MONGODB_URI` server-s
 
 ## Files
 
-- `app/layout.tsx` imports `chatemi/styles.css` once.
+- `app/layout.tsx` imports `@mademi_dev/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.

package/examples/nextjs-chat-widget/app/components/ChatWidget.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { ChatEmiLauncher, ChatEmiProvider } from "chatemi";
+import { ChatEmiLauncher, ChatEmiProvider } from "@mademi_dev/chatemi";
 import { useMemo } from "react";
 import { createChatEmiConfig } from "../lib/chatemi-config";
 

package/examples/nextjs-chat-widget/app/layout.tsx

@@ -1,4 +1,4 @@
-import "chatemi/styles.css";
+import "@mademi_dev/chatemi/styles.css";
 import type { Metadata } from "next";
 import type { ReactNode } from "react";
 import { ChatWidget } from "./components/ChatWidget";

package/examples/nextjs-chat-widget/app/lib/chatemi-config.ts

@@ -1,4 +1,4 @@
-import type { ChatEmiConfig } from "chatemi";
+import type { ChatEmiConfig } from "@mademi_dev/chatemi";
 
 export function createChatEmiConfig(): ChatEmiConfig {
   return {

package/examples/nextjs-chat-widget/app/lib/chatemi-mongo.ts

@@ -1,4 +1,4 @@
-import { createChatEmiMongoConnection } from "chatemi/server";
+import { createChatEmiMongoConnection } from "@mademi_dev/chatemi/server";
 
 let connectionPromise: ReturnType<typeof createChatEmiMongoConnection> | undefined;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mademi_dev/chatemi",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A React messaging kit with API clients, realtime socket support, hooks, provider state, and default Telegram-style UI.",
   "type": "module",
   "main": "dist/chatemi.umd.cjs",