@traiyani/chatsdk-react 1.0.0

package/README.md

@@ -0,0 +1,250 @@
+# @traiyani/chatsdk-react
+
+Pre-built, plug-and-play React SDK for real-time chat. Ships as compiled JavaScript (ESM + CJS) with a single CSS file and full TypeScript declarations — works with any bundler.
+
+## Installation
+
+```bash
+npm install @traiyani/chatsdk-react axios socket.io-client
+```
+
+### Peer Dependencies
+
+| Package             | Version  |
+| ------------------- | -------- |
+| `react`             | >=16.8.0 |
+| `react-dom`         | >=16.8.0 |
+| `axios`             | >=0.21.0 |
+| `socket.io-client`  | >=4.0.0  |
+
+## Quick Start
+
+```tsx
+import React, { useState, useEffect } from 'react';
+import { ChatSDK, ConversationList, ChatWindow } from '@traiyani/chatsdk-react';
+import '@traiyani/chatsdk-react/dist/chatsdk.css';
+
+function App() {
+  const [sdk] = useState(() => ChatSDK.getInstance());
+  const [currentUser, setCurrentUser] = useState(null);
+  const [selectedConversation, setSelectedConversation] = useState(null);
+
+  useEffect(() => {
+    async function init() {
+      await sdk.init({
+        apiBaseUrl: 'https://your-api.example.com',
+        appId: 'your-app-id',
+        environment: 'production',
+      });
+
+      const user = await sdk.connect('external-user-id');
+      setCurrentUser(user);
+    }
+    init();
+  }, []);
+
+  if (!currentUser) return <div>Loading…</div>;
+
+  return (
+    <div style={{ display: 'flex', height: '100vh' }}>
+      <ConversationList
+        currentUser={currentUser}
+        onSelectConversation={setSelectedConversation}
+        selectedConversationId={selectedConversation?.id}
+      />
+      <ChatWindow
+        conversation={selectedConversation}
+        currentUser={currentUser}
+        onClose={() => setSelectedConversation(null)}
+        onBack={() => setSelectedConversation(null)}
+      />
+    </div>
+  );
+}
+
+export default App;
+```
+
+## Components
+
+### `<ConversationList />`
+
+Displays the list of conversations for the current user.
+
+| Prop                       | Type                                | Required | Description                            |
+| -------------------------- | ----------------------------------- | -------- | -------------------------------------- |
+| `currentUser`              | `ChatSDKUser`                       | Yes      | The authenticated user                 |
+| `onSelectConversation`     | `(conv: Conversation) => void`      | Yes      | Callback when a conversation is tapped |
+| `selectedConversationId`   | `string`                            | No       | Highlights the active conversation     |
+
+### `<ChatWindow />`
+
+Full chat window with messaging, file sharing, and real-time updates.
+
+| Prop             | Type                    | Required | Description                     |
+| ---------------- | ----------------------- | -------- | ------------------------------- |
+| `conversation`   | `Conversation \| null`  | Yes      | The active conversation         |
+| `currentUser`    | `ChatSDKUser`           | Yes      | The authenticated user          |
+| `onClose`        | `() => void`            | No       | Called when close button pressed |
+| `onBack`         | `() => void`            | No       | Called when back button pressed  |
+
+### `<ThemeToggle />`
+
+A button that cycles through light, dark, and auto themes.
+
+| Prop         | Type      | Required | Description              |
+| ------------ | --------- | -------- | ------------------------ |
+| `className`  | `string`  | No       | Additional CSS classes   |
+| `showLabel`  | `boolean` | No       | Show current theme label |
+
+> Wrap your app with `<ThemeProvider>` to use `<ThemeToggle />`.
+
+## Hooks
+
+### `useTheme()`
+
+Standalone hook for theme management.
+
+```tsx
+import { useTheme } from '@traiyani/chatsdk-react';
+
+function MyComponent() {
+  const { theme, actualTheme, setTheme, toggleTheme } = useTheme();
+  return <button onClick={toggleTheme}>Current: {actualTheme}</button>;
+}
+```
+
+### `useThemeContext()`
+
+Same API as `useTheme()`, but reads from the nearest `<ThemeProvider>` so all descendants share state.
+
+## Theme System
+
+```tsx
+import { ThemeProvider, ThemeToggle } from '@traiyani/chatsdk-react';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <ThemeToggle showLabel />
+      {/* chat components */}
+    </ThemeProvider>
+  );
+}
+```
+
+You can also initialize the theme imperatively:
+
+```tsx
+import { initializeTheme } from '@traiyani/chatsdk-react';
+
+initializeTheme(); // applies saved or system theme to <html>
+```
+
+## SDK Configuration
+
+```tsx
+const sdk = ChatSDK.getInstance();
+
+await sdk.init({
+  apiBaseUrl: 'https://your-api.example.com',
+  wsUrl: 'wss://your-ws.example.com',       // optional
+  appId: 'your-app-id',
+  apiKey: 'your-api-key',                    // optional
+  environment: 'production',
+  enableLogging: false,                      // optional
+  autoConnect: true,                         // optional
+  timeout: 30000,                            // optional, ms
+});
+```
+
+## Manager Classes (Advanced)
+
+For fine-grained control you can access individual managers through the SDK instance:
+
+```tsx
+const sdk = ChatSDK.getInstance();
+
+// Users
+const users = await sdk.users.searchUsers({ query: 'john', limit: 10 });
+
+// Conversations
+const convos = await sdk.conversations.getConversations({ limit: 20 });
+
+// Messages
+const msgs = await sdk.messages.getMessages({ conversationId: 'abc', limit: 50 });
+
+// Media
+const result = await sdk.media.uploadMedia({ file, type: 'image', conversationId: 'abc' });
+
+// Real-time events
+sdk.socket.on('message_received', (data) => console.log('New message:', data));
+```
+
+Or import the classes directly:
+
+```tsx
+import {
+  AuthManager,
+  UserManager,
+  ConversationManager,
+  MessageManager,
+  MediaManager,
+  EventManager,
+  SocketManager,
+} from '@traiyani/chatsdk-react';
+```
+
+## i18n
+
+```tsx
+import { changeLanguage, getCurrentLanguage, isRTL, t } from '@traiyani/chatsdk-react';
+
+changeLanguage('ar'); // switches to Arabic + sets RTL
+console.log(t('conversations_title')); // translated string
+```
+
+Supported locales: `en`, `ar`.
+
+## TypeScript
+
+Full type declarations ship with the package — no extra `@types/*` install needed.
+
+```tsx
+import type {
+  ChatSDKConfig,
+  ChatSDKUser,
+  ChatSDKMessage,
+  ChatSDKConversation,
+  ProductContext,
+  ChatWindowProps,
+  ConversationListProps,
+} from '@traiyani/chatsdk-react';
+```
+
+## Bundler Compatibility
+
+| Bundler           | Works? |
+| ----------------- | ------ |
+| Vite              | Yes    |
+| webpack / CRA     | Yes    |
+| Next.js           | Yes    |
+| Parcel            | Yes    |
+| Rollup            | Yes    |
+
+No aliases, no special plugins — just `npm install` and import.
+
+## What's Inside the Package
+
+```
+dist/
+  chatsdk-react.mjs   – ES module build
+  chatsdk-react.cjs   – CommonJS build
+  chatsdk.css          – single merged stylesheet
+  index.d.ts           – TypeScript declarations
+  *.map                – source maps
+```
+
+## License
+
+MIT