hazo_chat 2.1.1 → 3.2.0

package/README.md

@@ -1,11 +1,18 @@
 # hazo_chat
 
-A full-featured React chat component library for 1-1 communication with document sharing, file attachments, and real-time messaging capabilities.
+A full-featured React chat component library for group-based communication with document sharing, file attachments, and real-time messaging capabilities.
 
-**Version 2.0** - Now with API-first architecture! No server-side dependencies in client components.
+**Version 3.1** - Generic schema supporting multiple chat patterns: support (client-to-staff), peer (1:1), and group conversations.
+
+**Version 3.0** - Introduced group-based chat architecture. Multiple users can participate in a single chat group, perfect for support staff rotating on client sessions.
+
+**Version 2.0** introduced API-first architecture with no server-side dependencies in client components.
 
 ## Features
 
+- 👥 **Group-Based Chat** - Multiple users can participate in a single chat group
+- 🏗️ **Multiple Chat Patterns** - Support for support (client-to-staff), peer (1:1), and group conversations
+- 🔄 **Role-Based Access** - Support for 'client', 'staff', 'owner', 'admin', and 'member' roles within groups
 - 📱 **Responsive Design** - Works on desktop and mobile with adaptive layout
 - 💬 **Real-time Messaging** - Polling or manual refresh modes for message updates with optimistic UI
 - 📎 **File Attachments** - Support for documents and images with preview
@@ -478,7 +485,7 @@ export default function ChatPage() {
   return (
     <div className="h-screen">
       <HazoChat
-        receiver_user_id="recipient-uuid"
+        chat_group_id="group-uuid"
         reference_id="conversation-123"
         reference_type="support"
         title="Chat with Support"
@@ -497,13 +504,15 @@ hazo_chat requires these API endpoints:
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/api/hazo_chat/messages` | GET | Fetch chat messages |
-| `/api/hazo_chat/messages` | POST | Send a new message |
+| `/api/hazo_chat/messages` | GET | Fetch chat messages (requires `chat_group_id` param) |
+| `/api/hazo_chat/messages` | POST | Send a new message (requires `chat_group_id` in body) |
 | `/api/hazo_chat/messages/[id]/read` | PATCH | Mark a message as read (automatic) |
-| `/api/hazo_chat/unread_count` | GET | Get unread message counts by reference_id (optional) |
+| `/api/hazo_chat/unread_count` | GET | Get unread message counts by chat_group_id (optional) |
 | `/api/hazo_auth/me` | GET | Get current authenticated user |
 | `/api/hazo_auth/profiles` | POST | Fetch user profiles by IDs |
 
+**Breaking Change (v3.0):** Messages API now uses `chat_group_id` instead of `receiver_user_id`. All group members can see and send messages.
+
 ### Using Exportable Handlers (Recommended)
 
 ```typescript
@@ -563,9 +572,11 @@ hazo_chat provides server-side library functions that can be used in API routes,
 
 ### hazo_chat_get_unread_count
 
-Get unread message counts grouped by reference_id for a receiver user.
+Get unread message counts grouped by chat_group_id for a user.
 
-**Purpose:** Returns an array of reference IDs with the count of unread messages (where `read_at` is `null`) for a given receiver user ID. Useful for displaying unread message badges or notifications.
+**Purpose:** Returns an array of chat group IDs with the count of unread messages (where `read_at` is `null`) for a given user ID. Useful for displaying unread message badges or notifications.
+
+**Breaking Change (v3.0):** Now groups by `chat_group_id` instead of `reference_id`. Accepts optional `chat_group_ids` filter.
 
 **Usage:**
 
@@ -579,11 +590,13 @@ const hazo_chat_get_unread_count = createUnreadCountFunction({
 });
 
 // Use the function
-const unreadCounts = await hazo_chat_get_unread_count('receiver-user-id-123');
+const unreadCounts = await hazo_chat_get_unread_count({
+  user_id: 'user-id-123',
+  chat_group_ids: ['group-1', 'group-2'] // Optional: filter by specific groups
+});
 // Returns: [
-//   { reference_id: 'ref-1', count: 5 },
-//   { reference_id: 'ref-2', count: 3 },
-//   { reference_id: '', count: 1 }  // Empty reference_id for general messages
+//   { chat_group_id: 'group-1', count: 5 },
+//   { chat_group_id: 'group-2', count: 3 }
 // ]
 ```
 
@@ -591,14 +604,16 @@ const unreadCounts = await hazo_chat_get_unread_count('receiver-user-id-123');
 
 ```typescript
 interface UnreadCountResult {
-  reference_id: string;  // The reference ID (empty string for messages without reference)
-  count: number;         // Number of unread messages for this reference
+  chat_group_id: string; // The chat group ID
+  count: number;         // Number of unread messages in this group
 }
 ```
 
 **Function Behavior:**
 - Only counts messages where `read_at` is `null` and `deleted_at` is `null`
-- Groups results by `reference_id`
+- Only counts messages in groups where the user is a member
+- Groups results by `chat_group_id`
+- Optionally filters by specific `chat_group_ids` if provided
 - Sorts results by count (descending - most unread first)
 - Returns empty array if no unread messages found
 - Returns empty array on errors (doesn't throw)
@@ -620,33 +635,41 @@ const hazo_chat_get_unread_count = createUnreadCountFunction({
 export async function GET(request: NextRequest) {
   try {
     const { searchParams } = new URL(request.url);
-    const receiver_user_id = searchParams.get('receiver_user_id');
+    const user_id = searchParams.get('user_id');
+    const chat_group_ids_param = searchParams.get('chat_group_ids');
 
-    if (!receiver_user_id) {
+    if (!user_id) {
       return NextResponse.json(
-        { 
-          success: false, 
-          error: 'receiver_user_id is required',
+        {
+          success: false,
+          error: 'user_id is required',
           unread_counts: []
         },
         { status: 400 }
       );
     }
 
-    const unread_counts = await hazo_chat_get_unread_count(receiver_user_id);
+    const chat_group_ids = chat_group_ids_param
+      ? chat_group_ids_param.split(',')
+      : undefined;
+
+    const unread_counts = await hazo_chat_get_unread_count({
+      user_id,
+      chat_group_ids
+    });
 
     return NextResponse.json({
       success: true,
-      receiver_user_id,
+      user_id,
       unread_counts,
-      total_references: unread_counts.length,
+      total_groups: unread_counts.length,
       total_unread: unread_counts.reduce((sum, item) => sum + item.count, 0)
     });
   } catch (error) {
     const error_message = error instanceof Error ? error.message : 'Unknown error';
     return NextResponse.json(
-      { 
-        success: false, 
+      {
+        success: false,
         error: error_message,
         unread_counts: []
       },
@@ -714,7 +737,7 @@ export async function getUnreadCounts(receiver_user_id: string) {
 
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
-| `receiver_user_id` | `string` | ✅ | - | UUID of the chat recipient |
+| `chat_group_id` | `string` | ✅ | - | UUID of the chat group (CHANGED from `receiver_user_id` in v3.0) |
 | `reference_id` | `string` | ❌ | - | Reference ID for chat context grouping |
 | `reference_type` | `string` | ❌ | `'chat'` | Type of reference |
 | `api_base_url` | `string` | ❌ | `'/api/hazo_chat'` | Base URL for API endpoints |
@@ -735,7 +758,7 @@ export async function getUnreadCounts(receiver_user_id: string) {
 
 ```tsx
 <HazoChat
-  receiver_user_id="user-123"
+  chat_group_id="group-123"
   reference_id="project-456"
   reference_type="project_chat"
   api_base_url="/api/hazo_chat"
@@ -803,7 +826,7 @@ To make all chat bubbles fully round (instead of the default style with a tail):
 
 ```tsx
 <HazoChat
-  receiver_user_id="user-123"
+  chat_group_id="group-123"
   reference_id="project-456"
   show_sidebar_toggle={false}    // Hide hamburger menu
   show_delete_button={false}     // Hide delete buttons
@@ -954,7 +977,7 @@ const {
   mark_as_read,       // (message_id) => Promise<void>
   refresh,            // () => void - Reload messages
 } = useChatMessages({
-  receiver_user_id: 'user-456',
+  chat_group_id: 'group-456',  // CHANGED from receiver_user_id in v3.0
   reference_id: 'chat-123',
   reference_type: 'direct',
   api_base_url: '/api/hazo_chat',
@@ -1017,7 +1040,7 @@ interface ChatMessage {
   reference_id: string;
   reference_type: string;
   sender_user_id: string;
-  receiver_user_id: string;
+  chat_group_id: string;  // CHANGED from receiver_user_id in v3.0
   message_text: string | null;
   reference_list: ChatReferenceItem[] | null;
   read_at: string | null;
@@ -1025,7 +1048,7 @@ interface ChatMessage {
   created_at: string;
   changed_at: string;
   sender_profile?: HazoUserProfile;
-  receiver_profile?: HazoUserProfile;
+  // receiver_profile removed in v3.0
   is_sender: boolean;
   send_status?: 'sending' | 'sent' | 'failed';
 }
@@ -1059,32 +1082,204 @@ interface ChatReferenceItem {
 
 **Note on MIME Type:** The `mime_type` property is optional. If not provided, the component will automatically infer the MIME type from the file extension (e.g., `.jpg` → `image/jpeg`, `.pdf` → `application/pdf`). This ensures document preview works even when `mime_type` is not explicitly set. Supported file extensions for inference include: `pdf`, `png`, `jpg`, `jpeg`, `gif`, `webp`, `txt`, `doc`, `docx`.
 
+### ChatGroup (NEW in v3.0, UPDATED in v3.1)
+
+```typescript
+interface ChatGroup {
+  id: string;
+  client_user_id: string | null | undefined;  // NULLABLE in v3.1 (only required for 'support' groups)
+  group_type: ChatGroupType;                   // NEW in v3.1
+  name?: string | null;
+  created_at: string;
+  changed_at: string;
+}
+```
+
+### ChatGroupType (NEW in v3.1)
+
+```typescript
+type ChatGroupType = 'support' | 'peer' | 'group';
+```
+
+**Group Type Definitions:**
+- `'support'`: Client-to-staff support conversation (requires `client_user_id`)
+- `'peer'`: Peer-to-peer direct message between two users
+- `'group'`: Multi-user group conversation
+
+### ChatGroupUser (NEW in v3.0, UPDATED in v3.1)
+
+```typescript
+interface ChatGroupUser {
+  chat_group_id: string;
+  user_id: string;
+  role: ChatGroupUserRole;  // EXPANDED in v3.1
+  created_at: string;
+  changed_at: string;
+}
+```
+
+### ChatGroupUserRole (NEW in v3.0, EXPANDED in v3.1)
+
+```typescript
+// v3.0
+type ChatGroupUserRole = 'client' | 'staff';
+
+// v3.1 (expanded)
+type ChatGroupUserRole = 'client' | 'staff' | 'owner' | 'admin' | 'member';
+```
+
+**Role Definitions:**
+- `'client'`: Customer/end-user in support scenarios
+- `'staff'`: Support personnel in support scenarios
+- `'owner'`: Creator/owner of peer or group chats
+- `'admin'`: Delegated administrator in group chats
+- `'member'`: Standard participant in peer or group chats
+
+### ChatGroupWithMembers (NEW in v3.0, UPDATED in v3.1)
+
+```typescript
+interface ChatGroupWithMembers extends ChatGroup {
+  members: (ChatGroupUser & { profile?: HazoUserProfile })[];
+  owner_profile?: HazoUserProfile;  // NEW in v3.1 - profile of the group owner
+}
+```
+
 ## Database Schema
 
-### hazo_chat Table
+**Breaking Changes in v3.0:** The database schema has been updated to support group-based chat. Migration required.
+
+**New in v3.1:** Generic schema supporting multiple chat patterns - support, peer, and group conversations.
+
+### PostgreSQL Enum Types (RECOMMENDED)
+
+For PostgreSQL installations, create these custom enum types for type safety and consistency:
+
+```sql
+-- Reference type for chat contexts
+CREATE TYPE hazo_enum_chat_type AS ENUM ('chat', 'field', 'project', 'support', 'general');
+
+-- Group type for conversation patterns (v3.1)
+CREATE TYPE hazo_enum_group_type AS ENUM ('support', 'peer', 'group');
+
+-- Membership roles (v3.1)
+CREATE TYPE hazo_enum_group_role AS ENUM ('client', 'staff', 'owner', 'admin', 'member');
+```
+
+### Group Types
+
+hazo_chat supports three distinct group types to accommodate different conversation patterns:
+
+| Type | Description | Use Case | `client_user_id` | Typical Roles |
+|------|-------------|----------|------------------|---------------|
+| **support** | Client-to-staff support conversation | Customer support, helpdesk | Required (identifies the client) | 'client', 'staff' |
+| **peer** | Peer-to-peer direct message (1:1) | Direct messaging between equals | Not used (null) | 'owner', 'member' |
+| **group** | Multi-user group conversation | Team collaboration, channels | Not used (null) | 'owner', 'admin', 'member' |
+
+### Role Types
+
+The `role` field in `hazo_chat_group_users` defines each member's permissions and relationship to the group:
+
+| Role | Description | Used In | Capabilities |
+|------|-------------|---------|--------------|
+| **client** | Customer/end-user receiving support | support groups | Send messages, view messages |
+| **staff** | Support personnel helping clients | support groups | Send messages, view messages, assist client |
+| **owner** | Creator/owner of the conversation | peer, group | Full control, can add/remove members |
+| **admin** | Delegated administrator | group | Can manage members, moderate content |
+| **member** | Standard participant | peer, group | Send messages, view messages |
+
+### hazo_chat_group Table (UPDATED in v3.1)
+
+```sql
+-- PostgreSQL with enums (RECOMMENDED)
+CREATE TABLE hazo_chat_group (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  client_user_id UUID REFERENCES hazo_users(id),  -- NULLABLE in v3.1
+  group_type hazo_enum_group_type NOT NULL DEFAULT 'support',  -- NEW in v3.1
+  name VARCHAR(255),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+-- PostgreSQL without enums (alternative)
+CREATE TABLE hazo_chat_group (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  client_user_id UUID REFERENCES hazo_users(id),  -- NULLABLE in v3.1
+  group_type VARCHAR(20) NOT NULL DEFAULT 'support' CHECK (group_type IN ('support', 'peer', 'group')),  -- NEW in v3.1
+  name VARCHAR(255),
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX idx_hazo_chat_group_client ON hazo_chat_group(client_user_id);
+CREATE INDEX idx_hazo_chat_group_type ON hazo_chat_group(group_type);  -- NEW in v3.1
+```
+
+**Column Changes in v3.1:**
+- `client_user_id`: Changed from `NOT NULL` to nullable - only required for 'support' type groups
+- `group_type`: NEW field - defines the conversation pattern ('support', 'peer', 'group')
+
+### hazo_chat_group_users Table (UPDATED in v3.1)
+
+```sql
+-- PostgreSQL with enums (RECOMMENDED)
+CREATE TABLE hazo_chat_group_users (
+  chat_group_id UUID NOT NULL REFERENCES hazo_chat_group(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  role hazo_enum_group_role NOT NULL,  -- EXPANDED in v3.1
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (chat_group_id, user_id)
+);
+
+-- PostgreSQL without enums (alternative)
+CREATE TABLE hazo_chat_group_users (
+  chat_group_id UUID NOT NULL REFERENCES hazo_chat_group(id) ON DELETE CASCADE,
+  user_id UUID NOT NULL REFERENCES hazo_users(id) ON DELETE CASCADE,
+  role VARCHAR(20) NOT NULL CHECK (role IN ('client', 'staff', 'owner', 'admin', 'member')),  -- EXPANDED in v3.1
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  PRIMARY KEY (chat_group_id, user_id)
+);
+
+CREATE INDEX idx_hazo_chat_group_users_user ON hazo_chat_group_users(user_id);
+CREATE INDEX idx_hazo_chat_group_users_group ON hazo_chat_group_users(chat_group_id);
+CREATE INDEX idx_hazo_chat_group_users_role ON hazo_chat_group_users(role);  -- NEW in v3.1
+```
+
+**Column Changes in v3.1:**
+- `role`: EXPANDED from ('client', 'staff') to ('client', 'staff', 'owner', 'admin', 'member')
+
+### hazo_chat Table (MODIFIED in v3.0)
 
 ```sql
+-- PostgreSQL
 CREATE TABLE hazo_chat (
-  id TEXT PRIMARY KEY,
-  reference_id TEXT NOT NULL,
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  reference_id UUID NOT NULL,
   reference_type TEXT DEFAULT 'chat',
-  sender_user_id TEXT NOT NULL,
-  receiver_user_id TEXT NOT NULL,
+  sender_user_id UUID NOT NULL REFERENCES hazo_users(id),
+  chat_group_id UUID NOT NULL REFERENCES hazo_chat_group(id),  -- CHANGED from receiver_user_id
   message_text TEXT,
-  reference_list TEXT,  -- JSON array of ChatReferenceItem
-  read_at TEXT,
-  deleted_at TEXT,
-  created_at TEXT NOT NULL,
-  changed_at TEXT NOT NULL
+  reference_list JSONB,  -- JSON array of ChatReferenceItem
+  read_at TIMESTAMPTZ,
+  deleted_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
 -- Indexes for performance
 CREATE INDEX idx_hazo_chat_reference_id ON hazo_chat(reference_id);
 CREATE INDEX idx_hazo_chat_sender ON hazo_chat(sender_user_id);
-CREATE INDEX idx_hazo_chat_receiver ON hazo_chat(receiver_user_id);
-CREATE INDEX idx_hazo_chat_created ON hazo_chat(created_at);
+CREATE INDEX idx_hazo_chat_group ON hazo_chat(chat_group_id);  -- CHANGED from receiver index
+CREATE INDEX idx_hazo_chat_created ON hazo_chat(created_at DESC);
 ```
 
+**Migration Notes:**
+- Rename column: `receiver_user_id` → `chat_group_id`
+- Create new tables: `hazo_chat_group`, `hazo_chat_group_users`
+- Migrate existing 1-1 chats to groups with both users as members
+- Update foreign key constraints
+
 ## UI Behavior & Responsive Design
 
 ### Hamburger Menu Button
@@ -1148,56 +1343,261 @@ max_file_size_mb = 10
 allowed_types = pdf,png,jpg,jpeg,gif,txt,doc,docx
 ```
 
-## Migration from v1.x
+## Migration from v3.0 to v3.1
+
+**Version 3.1** introduces schema changes to support multiple chat patterns (support, peer, group) while maintaining backward compatibility.
+
+### What Changed in v3.1
+
+| v3.0 | v3.1 |
+|------|------|
+| Fixed support pattern only | Three patterns: support, peer, group |
+| `client_user_id` always required | `client_user_id` nullable (only for support groups) |
+| 2 roles: 'client', 'staff' | 5 roles: 'client', 'staff', 'owner', 'admin', 'member' |
+| No `group_type` field | NEW `group_type` field ('support', 'peer', 'group') |
+
+### Migration Steps (v3.0 to v3.1)
+
+**Important:** v3.1 is backward compatible with v3.0 schema. Existing support-type groups continue to work without changes.
+
+1. **Create PostgreSQL Enum Types (Optional but Recommended):**
+
+```sql
+-- Reference type for chat contexts
+CREATE TYPE hazo_enum_chat_type AS ENUM ('chat', 'field', 'project', 'support', 'general');
+
+-- Group type for conversation patterns
+CREATE TYPE hazo_enum_group_type AS ENUM ('support', 'peer', 'group');
+
+-- Membership roles
+CREATE TYPE hazo_enum_group_role AS ENUM ('client', 'staff', 'owner', 'admin', 'member');
+```
+
+2. **Add group_type Column to hazo_chat_group:**
+
+```sql
+-- Add group_type column (defaults to 'support' for backward compatibility)
+ALTER TABLE hazo_chat_group
+  ADD COLUMN group_type VARCHAR(20) NOT NULL DEFAULT 'support'
+  CHECK (group_type IN ('support', 'peer', 'group'));
+
+-- Or with enum type (if you created the enum):
+ALTER TABLE hazo_chat_group
+  ADD COLUMN group_type hazo_enum_group_type NOT NULL DEFAULT 'support';
+
+-- Add index for group_type
+CREATE INDEX idx_hazo_chat_group_type ON hazo_chat_group(group_type);
+```
+
+3. **Make client_user_id Nullable:**
+
+```sql
+-- Remove NOT NULL constraint from client_user_id
+ALTER TABLE hazo_chat_group
+  ALTER COLUMN client_user_id DROP NOT NULL;
+```
+
+4. **Update Role Constraint in hazo_chat_group_users:**
+
+```sql
+-- Drop old constraint
+ALTER TABLE hazo_chat_group_users
+  DROP CONSTRAINT IF EXISTS hazo_chat_group_users_role_check;
+
+-- Add new constraint with expanded roles
+ALTER TABLE hazo_chat_group_users
+  ADD CONSTRAINT hazo_chat_group_users_role_check
+  CHECK (role IN ('client', 'staff', 'owner', 'admin', 'member'));
+
+-- Or with enum type (if you created the enum):
+ALTER TABLE hazo_chat_group_users
+  ALTER COLUMN role TYPE hazo_enum_group_role
+  USING role::hazo_enum_group_role;
+
+-- Add index for role
+CREATE INDEX idx_hazo_chat_group_users_role ON hazo_chat_group_users(role);
+```
+
+5. **Verify Existing Data:**
+
+```sql
+-- All existing groups should have group_type = 'support'
+SELECT group_type, COUNT(*)
+FROM hazo_chat_group
+GROUP BY group_type;
+
+-- All existing members should have role IN ('client', 'staff')
+SELECT role, COUNT(*)
+FROM hazo_chat_group_users
+GROUP BY role;
+```
+
+### Creating New Group Types
+
+After migration, you can create peer and group conversations:
+
+```typescript
+// Support group (v3.0 style - still works)
+await db.insert_with_result('hazo_chat_group', {
+  client_user_id: 'client-uuid',
+  group_type: 'support',
+  name: 'Customer Support'
+});
+
+// Peer-to-peer chat (v3.1)
+await db.insert_with_result('hazo_chat_group', {
+  client_user_id: null,  // Not used for peer chats
+  group_type: 'peer',
+  name: 'Alice & Bob'
+});
+
+// Group conversation (v3.1)
+await db.insert_with_result('hazo_chat_group', {
+  client_user_id: null,  // Not used for group chats
+  group_type: 'group',
+  name: 'Project Team'
+});
+```
+
+### No Code Changes Required
+
+The v3.1 schema changes are transparent to the component API. Your existing code continues to work:
+
+```tsx
+// This works for all group types (support, peer, group)
+<HazoChat
+  chat_group_id="group-123"
+  reference_id="chat-456"
+  reference_type="support"
+/>
+```
+
+### TypeScript Type Updates
+
+If you use TypeScript types from hazo_chat:
+
+```typescript
+// v3.1 types (automatically available after updating package)
+import type {
+  ChatGroup,           // client_user_id is now optional
+  ChatGroupType,       // 'support' | 'peer' | 'group'
+  ChatGroupUserRole    // 'client' | 'staff' | 'owner' | 'admin' | 'member'
+} from 'hazo_chat';
+
+const group: ChatGroup = {
+  id: 'group-123',
+  client_user_id: null,        // ✅ Now optional
+  group_type: 'peer',          // ✅ New field
+  name: 'Chat',
+  created_at: new Date().toISOString(),
+  changed_at: new Date().toISOString()
+};
+```
+
+## Migration from v2.x to v3.0
 
-Version 2.0 introduces breaking changes for a simpler, more reliable architecture.
+**Version 3.0** introduces breaking changes to support group-based chat architecture.
 
 ### What Changed
 
-| v1.x | v2.x |
+| v2.x | v3.0 |
 |------|------|
-| Pass `hazo_connect` prop | Not needed - uses API calls |
-| Pass `hazo_auth` prop | Not needed - uses API calls |
-| Pass `document_save_location` prop | Not needed |
-| Direct database access | API-based data access |
+| `receiver_user_id` prop | `chat_group_id` prop |
+| 1-1 chat only | Group-based chat with multiple participants |
+| `receiver_user_id` in API calls | `chat_group_id` in API calls |
+| Single `hazo_chat` table | Three tables: `hazo_chat_group`, `hazo_chat_group_users`, `hazo_chat` (modified) |
+| Unread count by `reference_id` | Unread count by `chat_group_id` |
+| `ChatMessage.receiver_profile` field | Field removed |
 
 ### Migration Steps
 
-1. **Remove adapter props:**
+1. **Database Migration:**
+
+```sql
+-- Step 1: Create new tables
+CREATE TABLE hazo_chat_group (...);  -- See Database Schema section
+CREATE TABLE hazo_chat_group_users (...);
+
+-- Step 2: Migrate existing data (example)
+-- For each unique sender-receiver pair, create a chat group
+INSERT INTO hazo_chat_group (id, client_user_id, name)
+SELECT
+  gen_random_uuid(),
+  receiver_user_id,
+  'Migrated Chat ' || sender_user_id
+FROM hazo_chat
+GROUP BY sender_user_id, receiver_user_id;
+
+-- Step 3: Rename column
+ALTER TABLE hazo_chat RENAME COLUMN receiver_user_id TO chat_group_id;
+
+-- Step 4: Update foreign keys
+ALTER TABLE hazo_chat
+  ADD CONSTRAINT fk_chat_group
+  FOREIGN KEY (chat_group_id)
+  REFERENCES hazo_chat_group(id);
+```
+
+2. **Update Component Props:**
 
 ```tsx
-// Before (v1.x)
+// Before (v2.x)
 <HazoChat
-  hazo_connect={adapter}
-  hazo_auth={authService}
-  document_save_location="/uploads"
-  receiver_user_id="..."
+  receiver_user_id="user-123"
+  reference_id="chat-456"
 />
 
-// After (v2.x)
+// After (v3.0)
 <HazoChat
-  receiver_user_id="..."
+  chat_group_id="group-123"
+  reference_id="chat-456"
 />
 ```
 
-2. **Create API routes** (see [API Routes Setup](#api-routes-setup))
+3. **Update API Calls:**
+
+```typescript
+// Before (v2.x)
+const response = await fetch(
+  `/api/hazo_chat/messages?receiver_user_id=${userId}`
+);
+
+// After (v3.0)
+const response = await fetch(
+  `/api/hazo_chat/messages?chat_group_id=${groupId}`
+);
+```
 
-3. **Update imports:**
+4. **Update Type References:**
 
 ```typescript
-// The API handler factory is new
-import { createMessagesHandler } from 'hazo_chat/api';
+// Remove receiver_profile usage
+// message.receiver_profile → removed
+
+// Update CreateMessagePayload
+// receiver_user_id → chat_group_id
 ```
 
 ### Why the Change?
 
-The v1.x architecture required passing server-side adapters (`hazo_connect`, `hazo_auth`) to client components. This caused issues:
+The v2.x architecture supported only 1-1 communication. This was limiting for scenarios where:
+
+- Multiple support staff need to rotate on a single client chat
+- Team collaboration is required within a chat context
+- Client needs to see all staff responses in one unified thread
+
+The v3.0 group-based architecture solves these by:
+
+- Supporting multiple users in a single chat group
+- Role-based access (client vs staff)
+- Unified message history for all group members
+- Better scalability for team-based support scenarios
+
+## Migration from v1.x to v2.0
 
-- "Module not found: Can't resolve 'fs'" errors
-- Hydration mismatches
-- Complex webpack configuration
+Version 2.0 introduced API-first architecture (no server-side dependencies in client components).
 
-The v2.x API-first architecture solves these by keeping all server code in API routes.
+See [v2.0 release notes](https://github.com/pub12/hazo_chat/releases/tag/v2.0.0) for details.
 
 ## Development