@chaterafrikang/sdk 0.1.0-beta.0

package/README.md

@@ -0,0 +1,118 @@
+# @chatafrika/sdk
+
+Headless JavaScript SDK for ChatAfrika chat, presence, typing, and support features.
+
+## Installation
+
+```bash
+npm install @chatafrika/sdk
+```
+
+## Quick Start
+
+Your **backend** issues SDK tokens via `POST /api/v1/apps/:appId/tokens` (JWT or API key). Your **frontend** receives only the **token**—never App ID, public key, or secret key. See the ChatAfrika API docs for **Issue SDK Token** (`POST /apps/:id/tokens`).
+
+```typescript
+import { ChatAfrika } from '@chatafrika/sdk';
+
+// token from your backend—never use keys in the frontend
+const sdk = new ChatAfrika({
+  wsUrl: 'wss://ws.dev.chaterafrika.com/ws',
+  token,
+  debug: true,
+});
+
+await sdk.connect();
+
+const convo = sdk.conversations.get('conv-123');
+await sdk.conversations.join('conv-123');
+
+convo.on('message', (msg) => {
+  console.log('Message:', msg.content);
+});
+
+convo.sendMessage('Hello!');
+```
+
+## Features
+
+- ✅ WebSocket transport with auto-reconnection
+- ✅ Optimistic message updates
+- ✅ Message deduplication & reconciliation
+- ✅ Typing indicators with auto-expiry
+- ✅ Presence tracking
+- ✅ Read receipts lifecycle
+- ✅ Support session semantics (customer/agent roles)
+- ✅ Event-driven architecture
+- ✅ TypeScript support
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm run test:quick  # Quick test against real server
+```
+
+## Testing
+
+See [TESTING.md](./TESTING.md) for detailed testing guide.
+
+Quick test (use a token from your backend, e.g. `POST /apps/:id/tokens`):
+```bash
+WS_URL=ws://localhost:8080/ws SDK_TOKEN=<token-from-backend> npm run test:quick
+```
+
+## API Documentation
+
+### Core
+
+- `ChatAfrika` - Main SDK class
+- `ConnectionState` - Connection state enum
+- `ClientConfig` - Configuration interface
+
+### Conversations
+
+- `sdk.conversations.get(id)` - Get conversation
+- `sdk.conversations.join(id)` - Join conversation
+- `sdk.conversations.leave(id)` - Leave conversation
+
+### Support Sessions
+
+- `sdk.support.get(id, role?)` - Get support session
+- `session.isCustomer()` - Check if customer
+- `session.isAgent()` - Check if agent
+- `session.getStatus()` - Get session status
+
+### Events
+
+All classes extend EventEmitter. Listen to:
+- `message` - New message received
+- `typing` - Typing indicator
+- `presence` - Presence update
+- `receipt` - Receipt update
+- `assigned` - Support session assigned
+- `bot_takeover` - Bot took over
+- `closed` - Support session closed
+
+## Publish for testing
+
+Base URL for **dev**: **https://dev.chaterafrika.com/** (API: `https://dev.chaterafrika.com/api/v1`, WebSocket: `wss://ws.dev.chaterafrika.com/ws`).
+
+See **[PUBLISH_FOR_TESTING.md](./PUBLISH_FOR_TESTING.md)** for:
+
+- Publishing to npm with `--tag beta` (`npm install @chatafrika/sdk@beta`)
+- Installing from Git or local path (no publish)
+- Using `npm link` for local development
+- Dev vs local URLs
+
+## Documentation
+
+- [Capabilities & Usage Guide](./CAPABILITIES.md) - What the SDK can do and where to use it
+- [Testing Guide](./TESTING.md) - How to test the SDK
+- [Publish for testing](./PUBLISH_FOR_TESTING.md) - Publish / install SDK for testing with dev
+
+## License
+
+UNLICENSED