@droponair/sdk-js 0.3.0 → 0.3.1

package/README.md

@@ -1,865 +1,160 @@
 # DropOnAir JS SDK
 
-**End-to-End Encrypted Real-Time Messaging SDK**
+End-to-end encrypted messaging, group chat, voice/video calls, and broadcast channels for any app.
 
-The DropOnAir SDK provides seamless client-side end-to-end encryption for real-time messaging, group messaging, and voice/video calls. DropOnAir operates as a **blind encrypted relay** - it never sees, stores, or manages your encryption keys or message plaintext.
+DropOnAir operates as a **blind encrypted relay** - your users' encryption keys and message content never leave their devices.
 
----
+## Getting Started
 
-## 🔐 Security Architecture
+1. Create a free account at [panel.droponair.com](https://panel.droponair.com)
+2. Create an app in the dashboard to get your **App ID** and **Public API Key**
+3. Install the SDK:
 
-### Key Ownership Model
-
-- **Client-Side:** SDK generates X25519 keypairs locally, stores private keys in IndexedDB/SecureStorage
-- **Your Backend:** Serves as public key directory (users publish public keys via `/api/messaging/keys/me`)
-- **DropOnAir Service:** **NEVER** stores, validates, or accesses user keys - operates as blind relay
-
-### Encryption Flow
-
-1. **Identity Generation:** SDK generates X25519 keypair on first use, stores in local secure storage
-2. **Key Exchange:** SDK fetches recipient's public key from key directory (not DropOnAir)
-3. **Shared Secret Derivation:** SDK derives shared secret via X25519 ECDH, caches in-memory per peer
-4. **Message Encryption:** SDK encrypts message with AES-256-GCM using derived shared secret
-5. **Wire Format:** Binary protobuf Envelope with opaque `encryptedPayload` bytes
-6. **Decryption:** Recipient SDK derives same shared secret, decrypts payload client-side
-
-### Cryptographic Primitives
-
-- **X25519 (Curve25519 ECDH):** Key agreement for deriving shared secrets
-- **HKDF-SHA256:** Shared secret → AES-256 symmetric key derivation
-- **AES-256-GCM:** Authenticated encryption with 96-bit nonce, 128-bit auth tag
-- **Additional Authenticated Data (AAD):** Binds messageId, senderId, recipientId, timestamp to ciphertext
-
----
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @droponair/sdk-js
 ```
 
----
-
-## 🚀 Quick Start
-
-### Basic Usage (TypeScript)
+## Quick Start
 
 ```typescript
 import { initialize } from '@droponair/sdk-js';
 
-// Initialize SDK with backend integration
 const client = await initialize({
-  appId: 'your-app-id',
-  publicApiKey: 'your-public-api-key',
-  
-  // JWT callback: fetch fresh JWT from your backend
+  appId: 'your-app-id',                  // From the DropOnAir dashboard
+  publicApiKey: 'your-public-api-key',    // From the DropOnAir dashboard
   getUserJwt: async () => {
-    const response = await fetch('/api/auth/me', { credentials: 'include' });
-    const data = await response.json();
-    return data.jwt;
+    const res = await fetch('/api/auth/me', { credentials: 'include' });
+    const { jwt } = await res.json();
+    return jwt;
   },
-
-  // Key directory endpoint (your backend serves public keys)
   keyDirectoryEndpoint: '/api/messaging/keys',
-
-  // Token exchange endpoint (your backend → DropOnAir JWT)
   tokenExchangeEndpoint: '/api/messaging/token-exchange',
-
-  // Optional: custom WebSocket/HTTP endpoints
-  messagingWsUrl: 'wss://sdk.droponair.com/ws/messages',
-  messagingHttpUrl: 'https://sdk.droponair.com',
-
-  // Auto-connect on initialization (default: true)
-  autoConnect: true
 });
 
-// Listen for incoming messages (receives decrypted plaintext)
-client.onMessage(({ messageId, fromUserId, toUserId, timestamp, plaintext }) => {
-  console.log(`Message from ${fromUserId}: ${plaintext}`);
+// Listen for incoming messages (already decrypted)
+client.onMessage(({ fromUserId, plaintext, timestamp }) => {
+  console.log(`${fromUserId}: ${plaintext}`);
 });
 
-// Listen for system events
-client.onEvent(({ type, reason, metadata }) => {
-  if (type === 'LIMIT_REACHED') {
-    console.error('Rate limit reached');
-  } else if (type === 'ERROR') {
-    console.error('Error:', reason);
-  }
-});
-
-// Send encrypted message (SDK handles encryption automatically)
-const { messageId } = await client.sendMessage('recipient-user-id', 'Hello from Alice!');
-console.log('Message sent:', messageId);
-
-// Disconnect when done
-client.disconnect();
+// Send an E2EE message
+await client.sendMessage('recipient-user-id', 'Hello!');
 ```
 
-### Manual Connection Control
-
-```typescript
-const client = await initialize({
-  appId: 'your-app-id',
-  publicApiKey: 'your-public-api-key',
-  getUserJwt: async () => fetchJwt(),
-  autoConnect: false  // Don't connect immediately
-});
-
-// Connect manually when ready
-await client.connect();
-
-// Disconnect and prevent auto-reconnect
-client.disconnect();
-```
-
----
-
-## 🔧 API Reference
-
-### `initialize(options)`
-
-Initializes the DropOnAir client with end-to-end encryption.
+## Features
 
-**Options:**
-- `appId` (string, required): Your your backend app ID
-- `publicApiKey` (string, required): Your DropOnAir public API key
-- `getUserJwt` (function, required): Async function returning fresh user JWT
-- `keyDirectoryEndpoint` (string, optional): public key directory endpoint (default: `/api/messaging/keys`)
-- `tokenExchangeEndpoint` (string, optional): token exchange endpoint (default: `/api/messaging/token-exchange`)
-- `messagingWsUrl` (string, optional): DropOnAir WebSocket URL (default: `wss://sdk.droponair.com/ws/messages`)
-- `messagingHttpUrl` (string, optional): DropOnAir HTTP URL (default: `https://sdk.droponair.com`)
-- `autoConnect` (boolean, optional): Auto-connect on initialization (default: `true`)
-- `storage` (KeyStorageAdapter, optional): Custom storage adapter (default: IndexedDB with in-memory fallback)
-- `fetchFn` (function, optional): Custom fetch implementation (default: `globalThis.fetch`)
+- **E2EE Messaging** - X25519 key agreement, AES-256-GCM encryption, multi-device support
+- **Cleartext Messaging** - Lightweight messages without E2EE overhead
+- **Broadcast Channels** - Pub/sub for announcements and notifications
+- **Group Messaging** - Server-managed groups with member roles
+- **Voice & Video Calls** - 1-to-1 WebRTC call signaling with TURN support
+- **Group Calls** - Mesh WebRTC group calls with per-participant signaling
+- **Offline Delivery** - Messages queued and delivered when recipients reconnect
+- **Multi-Device** - Per-device encryption with automatic self-sync
 
-**Returns:** `Promise<DropOnAirClient>`
+## API Reference
 
----
+### Initialization
 
-### `client.connect()`
-
-Connects to DropOnAir messaging service. Automatically:
-- Generates or retrieves X25519 identity keypair from secure storage
-- Publishes public key to key directory (PUT `/api/messaging/keys/me`)
-- Exchanges user JWT for DropOnAir JWT
-- Opens WebSocket connection with JWT authentication
-- Fetches and decrypts offline messages
-
-**Returns:** `Promise<void>`
-
----
-
-### `client.disconnect()`
-
-Disconnects from DropOnAir and stops auto-reconnect.
-
-**Returns:** `void`
-
----
-
-### `client.sendMessage(toUserId, plaintext)`
-
-Encrypts and sends a message to a recipient.
-
-**Parameters:**
-- `toUserId` (string): Recipient's user ID (must match JWT subject in their their identity)
-- `plaintext` (string): Message content (will be encrypted client-side)
-
-**Flow:**
-1. Fetch recipient's public key from key directory (if not cached)
-2. Derive shared secret via X25519 ECDH
-3. Encrypt plaintext with AES-256-GCM
-4. Build protobuf Envelope with opaque encrypted payload
-5. Send binary WebSocket frame to DropOnAir
-
-**Returns:** `Promise<{ messageId: string }>`
-
-**Throws:**
-- WebSocket not connected
-- Sender identity missing
-- Rate limit reached (`LIMIT_REACHED` event)
-
----
-
-### `client.onMessage(callback)`
-
-Registers a callback for incoming decrypted messages.
-
-**Callback signature:**
 ```typescript
-(message: DecryptedMessage) => void
-
-interface DecryptedMessage {
-  messageId: string;
-  fromUserId: string;
-  toUserId: string;
-  timestamp: number;
-  plaintext: string;  // Already decrypted by SDK
-}
-```
-
-**Returns:** Unsubscribe function `() => void`
-
----
-
-### `client.onEvent(callback)`
-
-Registers a callback for system events.
-
-**Event Types:**
-- `CONNECTED`: WebSocket connected
-- `DISCONNECTED`: WebSocket disconnected
-- `RECONNECTING`: Auto-reconnect in progress
-- `SERVER_RECEIVED`: DropOnAir received message
-- `DELIVERED`: Message delivered to recipient's WebSocket
-- `PROCESSED`: Recipient acknowledged message
-- `LIMIT_REACHED`: Rate limit exceeded (sending blocked until reset)
-- `IMPERSONATION_DETECTED`: Sender tried to spoof fromUserId
-- `ERROR`: Decryption failed or other error
-
-**Callback signature:**
-```typescript
-(event: DropOnAirEvent) => void
-
-interface DropOnAirEvent {
-  type: string;
-  reason?: string;
-  metadata?: string;
-}
-```
-
-**Returns:** Unsubscribe function `() => void`
-
----
-
-### `client.ack(messageId)`
-
-Acknowledges a received message (sends `PROCESSED` ACK to DropOnAir).
-
-**Parameters:**
-- `messageId` (string): Message ID to acknowledge
-
-**Returns:** `Promise<void>`
-
-**Note:** SDK automatically sends `PROCESSED` ACK after successfully decrypting incoming messages. You typically don't need to call this method unless implementing custom acknowledgment logic.
-
----
-
-## 📞 Voice & Video Calls
-
-DropOnAir includes built-in WebRTC call signaling. The SDK handles the call lifecycle (invite → ring → accept/reject → signal exchange → end) over the same encrypted WebSocket used for messaging. Your app is responsible for the WebRTC peer connection itself; the SDK provides the signaling transport.
-
-### Quick Example
-
-```typescript
-import { initialize, CallEvent } from '@droponair/sdk-js';
-
-const client = await initialize({ ... });
-
-// ── Listen for incoming & status events ──────────────────────────────────────
-client.onCallEvent(async (event: CallEvent) => {
-  switch (event.type) {
-
-    case 'CALL_INVITE':
-      // Incoming call, show answer/reject UI
-      showIncomingCallUI(event.callId!, event.targetUserId!);
-      break;
-
-    case 'CALL_RINGING':
-      // Callee is ringing, show "ringing" state in UI
-      console.log('Ringing:', event.callId);
-      break;
-
-    case 'CALL_ACCEPTED':
-      // Create RTCPeerConnection and send SDP offer
-      await startWebRtcOffer(event.callId!);
-      break;
-
-    case 'CALL_SDP_OFFER':
-      // Received SDP offer from caller, create answer
-      await handleSdpOffer(event.callId!, event.payload!);
-      break;
-
-    case 'CALL_SDP_ANSWER':
-      await handleSdpAnswer(event.callId!, event.payload!);
-      break;
-
-    case 'CALL_ICE_CANDIDATE':
-      await handleIceCandidate(event.callId!, event.payload!);
-      break;
-
-    case 'CALL_VIDEO_TOGGLE':
-      handleVideoToggle(event.callId!, event.payload!);
-      break;
-
-    case 'CALL_REJECTED':
-    case 'CALL_ENDED':
-      closeCall(event.callId!);
-      break;
-
-    case 'CALL_DENIED_LIMIT_REACHED':
-      showError('Call limit reached. Upgrade your plan to continue.');
-      break;
-  }
-});
-
-// ── TURN credentials (required for calls behind NAT/firewall) ────────────────
-const turn = await client.fetchTurnCredentials();
-const pc = new RTCPeerConnection({
-  iceServers: [{ urls: turn.uri, username: turn.username, credential: turn.password }]
-});
-
-// ── Initiate an outgoing call ────────────────────────────────────────────────
-const callId = await client.startCall('recipient-user-id');
-
-// ── Accept / reject incoming call ────────────────────────────────────────────
-await client.acceptCall(callId);
-await client.rejectCall(callId);
-
-// ── Send WebRTC signals through DropOnAir relay ──────────────────────────────
-pc.onicecandidate = ({ candidate }) => {
-  if (candidate) {
-    client.sendCallSignal('CALL_ICE_CANDIDATE', callId, JSON.stringify(candidate));
-  }
-};
-
-const offer = await pc.createOffer();
-await pc.setLocalDescription(offer);
-client.sendCallSignal('CALL_SDP_OFFER', callId, JSON.stringify(offer));
-
-// ── Toggle video on/off during a call ────────────────────────────────────────
-client.toggleVideo(callId, true);   // Enable video
-client.toggleVideo(callId, false);  // Disable video (voice-only)
-
-// ── End call ─────────────────────────────────────────────────────────────────
-await client.endCall(callId);
-```
-
----
-
-### Call API Reference
-
-#### `client.startCall(targetUserId)`
-
-Initiates an outgoing call to a user. Resolves with the server-assigned `callId` once the remote party starts ringing.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `targetUserId` | string | Recipient's DropOnAir user ID |
-
-**Returns:** `Promise<string>`, the `callId`
-
----
-
-#### `client.acceptCall(callId)`
-
-Accepts an incoming call. After resolving, initiate WebRTC negotiation via `sendCallSignal`.
-
-**Returns:** `Promise<void>`
-
----
-
-#### `client.rejectCall(callId)`
-
-Rejects an incoming call invitation.
-
-**Returns:** `Promise<void>`
-
----
-
-#### `client.endCall(callId)`
-
-Ends an active call or cancels an unanswered outgoing invite.
-
-**Returns:** `Promise<void>`
-
----
-
-#### `client.toggleVideo(callId, enabled)`
-
-Toggles the local video track on or off. Sends a `CALL_VIDEO_TOGGLE` signal to the peer so their UI can reflect the change.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `callId` | string | Active call ID |
-| `enabled` | boolean | `true` = video on, `false` = voice-only |
-
-**Returns:** `void`
-
----
-
-#### `client.sendCallSignal(type, callId, payload)`
-
-Sends a raw WebRTC signaling frame to the peer over the DropOnAir relay.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `type` | `'CALL_SDP_OFFER'` \| `'CALL_SDP_ANSWER'` \| `'CALL_ICE_CANDIDATE'` | Signal type |
-| `callId` | string | Active call ID |
-| `payload` | string | JSON-serialized SDP or ICE candidate |
-
-**Returns:** `void`
-
----
-
-#### `client.onCallEvent(callback)`
-
-Registers a listener for all call lifecycle and signaling events.
-
-**Callback signature:**
-```typescript
-(event: CallEvent) => void
-
-interface CallEvent {
-  type: CallEventType | string;
-  callId?: string;
-  targetUserId?: string;
-  payload?: string;  // JSON, SDP, ICE candidate, or metadata
-}
-
-type CallEventType =
-  | 'CALL_INVITE'           // Incoming call from another user
-  | 'CALL_RINGING'          // Remote party is ringing
-  | 'CALL_ACCEPTED'         // Call accepted, begin WebRTC negotiation
-  | 'CALL_REJECTED'         // Call rejected by remote party
-  | 'CALL_ENDED'            // Call ended (by either party)
-  | 'CALL_SDP_OFFER'        // WebRTC SDP offer received
-  | 'CALL_SDP_ANSWER'       // WebRTC SDP answer received
-  | 'CALL_ICE_CANDIDATE'    // ICE candidate received
-  | 'CALL_VIDEO_TOGGLE'     // Remote peer toggled video
-  | 'CALL_DENIED_LIMIT_REACHED'; // Call rejected, plan limit reached
-```
-
-**Returns:** Unsubscribe function `() => void`
-
----
-
-#### `client.fetchTurnCredentials()`
-
-Fetches short-lived TURN server credentials from DropOnAir for ICE negotiation. Always call this before creating an `RTCPeerConnection` to ensure NAT traversal works reliably.
-
-**Returns:** `Promise<TurnCredentials>`
-
-```typescript
-interface TurnCredentials {
-  username: string;
-  password: string;
-  uri: string;       // e.g. "turn:turn.droponair.com:3478"
-  ttlSeconds: number;
-}
-```
-
----
-
-## 👥 Group Messaging & Calls
-
-Groups support both E2EE and cleartext messaging, plus mesh WebRTC group calls.
-
-### Group Management
-
-```typescript
-// Create a group
-const group = await client.createGroup('Project Chat', ['user-1', 'user-2']);
-
-// List your groups
-const groups = await client.listGroups();
-
-// Manage members
-await client.addGroupMembers(group.groupId, ['user-3']);
-await client.removeGroupMembers(group.groupId, ['user-1']);
-
-// Get group details
-const members = await client.getGroupMembers(group.groupId);
-
-// Delete a group (owner only)
-await client.deleteGroup(group.groupId);
-```
-
-### Sending Group Messages
-
-```typescript
-// E2EE group message (sender-side fan-out, encrypts per member per device)
-await client.sendGroupMessage(groupId, 'Hello team!');
-
-// Cleartext group message (no crypto overhead)
-await client.sendGroupMessage(groupId, 'Public announcement', { cleartext: true });
-```
-
-### Receiving Group Messages
-
-```typescript
-client.onGroupMessage((msg) => {
-  console.log(`[${msg.groupId}] ${msg.senderId}: ${msg.plaintext}`);
-});
-
-// Remove listener
-client.offGroupMessage(handler);
-```
-
-### Group Calls (Mesh WebRTC)
-
-```typescript
-// Start a group call
-await client.startGroupCall(groupId, 'video');
-
-// Join an existing group call
-await client.joinGroupCall(groupId);
-
-// Listen for group call events (OFFER, ANSWER, ICE, JOIN, LEAVE, END)
-client.onGroupCallEvent((event) => {
-  switch (event.type) {
-    case 'OFFER':
-      // Handle incoming SDP offer from a participant
-      break;
-    case 'ANSWER':
-      // Handle SDP answer
-      break;
-    case 'ICE':
-      // Handle ICE candidate
-      break;
-    case 'JOIN':
-      // Participant joined
-      break;
-    case 'LEAVE':
-      // Participant left
-      break;
-  }
-});
-
-// Leave a group call
-await client.leaveGroupCall(groupId);
-```
-
-### Group API Reference
-
-| Method | Description |
-|--------|-------------|
-| `createGroup(name, memberIds)` | Create group with initial members |
-| `listGroups()` | List groups the user belongs to |
-| `getGroupMembers(groupId)` | Get group member list |
-| `addGroupMembers(groupId, userIds)` | Add members (owner/admin) |
-| `removeGroupMembers(groupId, userIds)` | Remove members (owner/admin) |
-| `deleteGroup(groupId)` | Delete group (owner only) |
-| `sendGroupMessage(groupId, text, opts?)` | Send E2EE or cleartext group message |
-| `onGroupMessage(callback)` | Listen for inbound group messages |
-| `offGroupMessage(callback)` | Remove group message listener |
-| `startGroupCall(groupId, type)` | Start a group voice/video call |
-| `joinGroupCall(groupId)` | Join an existing group call |
-| `leaveGroupCall(groupId)` | Leave a group call |
-| `endGroupCall(groupId)` | End a group call (initiator) |
-| `sendGroupCallSignal(type, callId, target, payload)` | Send SDP/ICE to a peer |
-| `onGroupCallEvent(callback)` | Listen for group call events |
-| `offGroupCallEvent(callback)` | Remove group call event listener |
-
-### Per-Plan Group Limits
-
-| Limit | FREE | PRO | GROWTH | PAYG | ENTERPRISE |
-|-------|------|-----|--------|------|------------|
-| Groups / app | 1 | 20 | 100 | ∞ | ∞ |
-| Members / group | 5 | 50 | 100 | ∞ | ∞ |
-| Group messages / month | 500 | 10,000 | 50,000 | ∞ | ∞ |
-| Group call minutes / month | 50 | 1,000 | 5,000 | ∞ | ∞ |
-| Group call participants | 4 | 8 | 16 | 32 | Custom |
-
----
-
-## 🏗️ Architecture
-
-### Module Structure
-
-```
-droponair-sdk-js/
-├── src/
-│   ├── index.ts                  # Public API exports
-│   ├── version.ts                # SDK_VERSION, PROTOCOL_VERSION, PAYLOAD_FORMAT_VERSION
-│   ├── core/
-│   │   ├── messaging-client.ts   # WebSocket client + message routing
-│   │   ├── session-manager.ts    # Shared secret caching
-│   │   ├── types.ts              # TypeScript interfaces
-│   │   └── bytes.ts              # Encoding utilities
-│   ├── crypto/
-│   │   ├── crypto-service.ts     # X25519 + AES-256-GCM encryption
-│   │   └── payload-format.ts     # Binary payload packing
-│   ├── transport/
-│   │   └── protobuf-codec.ts     # Envelope/Ack/Event encoding
-│   └── storage/
-│       ├── indexeddb-key-storage.ts  # Browser key storage
-│       └── memory-key-storage.ts     # In-memory fallback
-└── test-e2ee.js                  # E2EE validation test
-```
-
-### Versioning
-
-The SDK uses three distinct version numbers to ensure backward compatibility:
-
-| Version | Location | Purpose |
-|---------|----------|---------|
-| **SDK_VERSION** (`0.2.0`) | `src/version.ts`, `package.json` | Semver of the JS/TS SDK package itself. Sent as `X-SDK-Version` header on token exchange and `sdkVersion` query param on WebSocket handshake. |
-| **PROTOCOL_VERSION** (`1`) | `src/version.ts` | Wire protocol version, sent as `protocolVersion` query param on WebSocket connect. Increment when adding required proto fields or changing frame semantics. |
-| **PAYLOAD_FORMAT_VERSION** (`1`) | `src/version.ts` | First byte of every encrypted payload. Receivers check this before decrypting. Increment when changing the ciphertext binary layout. |
-
-**Version negotiation:** The server exposes `GET /api/info` (no auth required) which returns `protocolVersion`, `minSdkVersion`, and supported `features`. Clients can call this at startup to validate compatibility.
-
-**Backward compatibility rules:**
-- New proto fields are always additive (proto3 silently ignores unknown fields)
-- The `encryptedPayload` (field 6) legacy path is preserved alongside multi-device `devicePayloads` (field 8)
-- Encrypted payload version byte is checked on decrypt; unknown versions throw a clear error
-- Bumping `SDK_VERSION` or `PROTOCOL_VERSION` must update this README and `CHANGELOG.md`
-
-### Multi-Device Support
-
-The SDK supports per-device encryption for multi-device messaging:
-
-**How it works:**
-1. Each device generates its own X25519 identity keypair on first use
-2. Device public keys are published to the key directory (your backend) with a unique `deviceId`
-3. When sending a message, the SDK fetches ALL device keys for the recipient and encrypts once per device
-4. The sender also encrypts for their OWN other devices (self-sync)
-5. Each `Envelope` carries `devicePayloads[]`, one entry per device with device-specific ciphertext
-6. The receiver picks the `DeviceEncryptedPayload` matching their `deviceId` and decrypts
-
-**Wire format (Envelope proto):**
-```protobuf
-message Envelope {
-  string messageId = 1;
-  string appId = 2;
-  string fromUserId = 3;
-  string toUserId = 4;
-  int64 timestamp = 5;
-  bytes encryptedPayload = 6;  // legacy single-device (empty when devicePayloads used)
-  string clientMessageId = 7;
-  repeated DeviceEncryptedPayload devicePayloads = 8;  // multi-device
-  string senderDeviceId = 9;
-}
-```
-
-**Backward compatibility:**
-- If the recipient has no device keys (old SDK), the sender falls back to the legacy single `encryptedPayload` path
-- Incoming envelopes with `devicePayloads.length > 0` use the multi-device decryption path; otherwise the legacy path is used
-
-### Encrypted Payload Format
-
-```
-+--------+--------+--------+--------+----------+-------------+-------+------------+
-| Version| Algor  | Nonce  | Flags  | Cipher   | Signature   | Nonce | Ciphertext |
-| (1B)   | (1B)   | Len(1B)| (1B)   | Len(4B)  | Len(4B)     | (12B) | (variable) |
-+--------+--------+--------+--------+----------+-------------+-------+------------+
-```
-
-- **Version:** Payload format version (1)
-- **Algorithm:** Encryption algorithm (1 = AES-256-GCM)
-- **Nonce Length:** GCM nonce length (12 bytes)
-- **Flags:** Optional signature flag (0 = no signature, 1 = Ed25519 signature)
-- **Cipher Length:** Ciphertext length (big-endian uint32)
-- **Signature Length:** Signature length if present (big-endian uint32)
-- **Nonce:** 96-bit GCM nonce (random per message)
-- **Ciphertext:** AES-256-GCM encrypted plaintext + 128-bit auth tag
-
-**Forward Compatibility:** Future versions may add Ed25519 signatures for sender authenticity.
-
----
-
-## 🔒 Security Considerations
-
-### ✅ What DropOnAir SDK Protects
-
-- **Confidentiality:** All message content encrypted with AES-256-GCM before leaving device
-- **Integrity:** GCM authentication tag prevents tampering
-- **Forward Secrecy:** Shared secrets derived per peer, cleared on disconnect
-- **Context Binding:** AAD prevents message replay/substitution attacks
-- **Key Isolation:** Private keys never leave device, never sent to DropOnAir
-
-### ⚠️ Security Responsibilities
-
-1. **JWT Security:** Protect user JWT in secure HTTP-only cookies (never localStorage)
-2. **HTTPS Required:** Use HTTPS for your backend to protect JWT during token exchange
-3. **CSP Headers:** Enable Content Security Policy to prevent XSS attacks on IndexedDB
-4. **Key Backup:** SDK does NOT support key backup - users who lose device lose message access
-5. **Public Key Authenticity:** your backend must verify user identity before accepting public key uploads
-
-### 🚨 Known Limitations
-
-- **No Forward Secrecy Between Messages:** Uses static X25519 keys (no ratcheting like Signal Protocol)
-- **No Sender Authentication:** Recipient cannot verify sender identity (consider adding Ed25519 signatures)
-- **Metadata Leakage:** DropOnAir sees fromUserId, toUserId, timestamp, message size
-- **IndexedDB Vulnerability:** Browser storage vulnerable to XSS (use secure CSP)
-- **No Multi-Device Key Sharing:** Each device generates a separate identity; the SDK encrypts per-device but does not synchronize private keys across devices
-
----
-
-## 🧪 Testing
-
-Run the E2EE validation test:
-
-```bash
-npm run build
-node test-e2ee.js
-```
-
-**Test Coverage:**
-- ✅ Local identity generation (X25519 keypairs)
-- ✅ ECDH shared secret derivation
-- ✅ AES-256-GCM encryption/decryption
-- ✅ Binary payload format validation
-- ✅ Tampering detection (GCM auth tag)
-- ✅ AAD binding (prevents context manipulation)
-- ✅ Session caching (performance optimization)
-
----
-
-## 📚 Integration Examples
-
-### Angular/Ionic Example
-
-```typescript
-import { initialize, DropOnAirClient } from '@droponair/sdk-js';
-import { Injectable } from '@angular/core';
-import { HttpClient } from '@angular/common/http';
-import { firstValueFrom } from 'rxjs';
-
-@Injectable({ providedIn: 'root' })
-export class MessagingService {
-  private client?: DropOnAirClient;
-
-  constructor(private http: HttpClient) {}
-
-  async connect() {
-    this.client = await initialize({
-      appId: environment.appId,
-      publicApiKey: environment.droponairApiKey,
-      getUserJwt: async () => {
-        const { jwt } = await firstValueFrom(this.http.get<{ jwt: string }>('/api/auth/me'));
-        return jwt;
-      },
-      keyDirectoryEndpoint: '/api/messaging/keys',
-      tokenExchangeEndpoint: '/api/messaging/token-exchange'
-    });
-
-    this.client.onMessage(({ fromUserId, plaintext, timestamp }) => {
-      this.handleIncomingMessage(fromUserId, plaintext, timestamp);
-    });
-
-    this.client.onEvent(({ type, reason }) => {
-      if (type === 'LIMIT_REACHED') {
-        this.showRateLimitWarning();
-      }
-    });
-  }
-
-  async sendMessage(recipientId: string, message: string) {
-    if (!this.client) throw new Error('Not connected');
-    return this.client.sendMessage(recipientId, message);
-  }
-
-  disconnect() {
-    this.client?.disconnect();
-  }
-
-  private handleIncomingMessage(fromUserId: string, plaintext: string, timestamp: number) {
-    // Update UI, store in local DB, etc.
-  }
-
-  private showRateLimitWarning() {
-    // Show user notification
-  }
-}
-```
-
-### React Example
-
-```typescript
-import { initialize, DropOnAirClient } from '@droponair/sdk-js';
-import { useEffect, useState } from 'react';
-
-export function useMessaging() {
-  const [client, setClient] = useState<DropOnAirClient | null>(null);
-  const [messages, setMessages] = useState<any[]>([]);
-
-  useEffect(() => {
-    initialize({
-      appId: process.env.REACT_APP_APP_ID!,
-      publicApiKey: process.env.REACT_APP_DROPONAIR_API_KEY!,
-      getUserJwt: async () => {
-        const res = await fetch('/api/auth/me', { credentials: 'include' });
-        const { jwt } = await res.json();
-        return jwt;
-      },
-      keyDirectoryEndpoint: '/api/messaging/keys',
-      tokenExchangeEndpoint: '/api/messaging/token-exchange'
-    }).then((c) => {
-      c.onMessage((msg) => {
-        setMessages((prev) => [...prev, msg]);
-      });
-      setClient(c);
-    });
-
-    return () => client?.disconnect();
-  }, []);
-
-  const sendMessage = async (toUserId: string, text: string) => {
-    if (!client) throw new Error('Not connected');
-    await client.sendMessage(toUserId, text);
-  };
-
-  return { messages, sendMessage, connected: !!client };
-}
-```
-
----
-
-## 🛠️  Development
-
-### Build
-
-```bash
-npm run build
-```
-
-### Run Tests
-
-```bash
-npm run build
-node test-e2ee.js
-```
-
-### Lint
-
-```bash
-npm run lint
-```
-
----
-
-## 📄 License
+const client = await initialize(options);
+```
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `appId` | string | Yes | Your DropOnAir app ID |
+| `publicApiKey` | string | Yes | Your DropOnAir public API key |
+| `getUserJwt` | `() => Promise<string>` | Yes | Returns a fresh user JWT from your backend |
+| `keyDirectoryEndpoint` | string | No | Public key directory URL (default: `/api/messaging/keys`) |
+| `tokenExchangeEndpoint` | string | No | Token exchange URL (default: `/api/messaging/token-exchange`) |
+| `messagingWsUrl` | string | No | WebSocket URL (default: `wss://sdk.droponair.com/ws/messages`) |
+| `messagingHttpUrl` | string | No | HTTP URL (default: `https://sdk.droponair.com`) |
+| `autoConnect` | boolean | No | Connect on init (default: `true`) |
+| `storage` | KeyStorageAdapter | No | Custom key storage (default: IndexedDB) |
+| `debug` | boolean | No | Enable debug logging (default: `false`) |
+
+### Connection
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `connect()` | `Promise<void>` | Connect to DropOnAir (generates keys, exchanges JWT, opens WebSocket) |
+| `disconnect()` | `void` | Disconnect and stop auto-reconnect |
+
+### E2EE Messaging
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `sendMessage(toUserId, plaintext)` | `Promise<{ messageId }>` | Send an encrypted message |
+| `sendCleartextMessage(toUserId, plaintext)` | `Promise<{ messageId }>` | Send a cleartext message (no E2EE) |
+| `onMessage(callback)` | `() => void` | Listen for incoming messages. Returns unsubscribe function |
+| `onEvent(callback)` | `() => void` | Listen for system events (CONNECTED, DELIVERED, ERROR, etc.) |
+| `ack(messageId)` | `Promise<void>` | Manually acknowledge a message |
+
+### Broadcast Channels
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `subscribeBroadcast(channelId)` | `Promise<void>` | Subscribe to a channel |
+| `unsubscribeBroadcast(channelId)` | `Promise<void>` | Unsubscribe from a channel |
+| `publishBroadcast(channelId, plaintext)` | `Promise<{ broadcastId }>` | Publish to a channel |
+| `onBroadcast(callback)` | `() => void` | Listen for broadcast messages |
+
+### Groups
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `createGroup(name, memberUserIds?)` | `Promise<GroupInfo>` | Create a group with optional members |
+| `listGroups()` | `Promise<GroupInfo[]>` | List your groups |
+| `getGroup(groupId)` | `Promise<GroupInfo>` | Get group details |
+| `addGroupMembers(groupId, userIds)` | `Promise<GroupInfo>` | Add members (owner/admin) |
+| `removeGroupMember(groupId, userId)` | `Promise<GroupInfo>` | Remove a member (owner/admin) |
+| `deleteGroup(groupId)` | `Promise<void>` | Delete a group (owner only) |
+| `sendGroupMessage(groupId, plaintext)` | `Promise<{ messageId }>` | Send a group message |
+| `onGroupMessage(callback)` | `() => void` | Listen for group messages |
+
+### 1-to-1 Calls
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `startCall(targetUserId)` | `Promise<string>` | Start a call, returns callId |
+| `acceptCall(callId)` | `Promise<void>` | Accept incoming call |
+| `rejectCall(callId)` | `Promise<void>` | Reject incoming call |
+| `endCall(callId)` | `Promise<void>` | End or cancel a call |
+| `toggleVideo(callId, enabled)` | `void` | Toggle video on/off |
+| `sendCallSignal(type, callId, payload)` | `void` | Send SDP/ICE signaling data |
+| `onCallEvent(callback)` | `() => void` | Listen for call events |
+| `fetchTurnCredentials()` | `Promise<TurnCredentials>` | Get TURN server credentials for NAT traversal |
+
+### Group Calls
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `startGroupCall(groupId)` | `Promise<string>` | Start a group call, returns callId |
+| `joinGroupCall(callId, groupId)` | `Promise<void>` | Join an active group call |
+| `leaveGroupCall(callId)` | `Promise<void>` | Leave a group call |
+| `endGroupCall(callId)` | `Promise<void>` | End a group call for all |
+| `sendGroupCallSignal(type, callId, groupId, targetUserId, payload)` | `void` | Send SDP/ICE to a peer |
+| `onGroupCallEvent(callback)` | `() => void` | Listen for group call events |
+
+## Security
+
+- **X25519 ECDH** key agreement for shared secrets
+- **HKDF-SHA256** key derivation
+- **AES-256-GCM** authenticated encryption with AAD binding (messageId, senderId, recipientId, timestamp)
+- Private keys generated and stored locally, never sent to DropOnAir
+- Multi-device: each device has its own keypair, messages encrypted per-device
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Browser with Web Crypto API support (all modern browsers)
+
+## License
 
 MIT
 
----
-
-## 🤝 Support
-
-For issues or questions:
-- **GitHub Issues:** https://github.com/droponair/droponair-sdk-js
-- **Documentation:** https://docs.droponair.com
-- **Email:** support@droponair.com
-
----
-
-## 🎯 Final Security Validation Checklist
-
-Validation test results:
-
-```
-✅ SDK generates identity keys locally (X25519)
-✅ DropOnAir never stores user keys (server refactored)
-✅ Encryption fully client-side (AES-256-GCM)
-✅ Payload opaque over wire (binary protobuf)
-✅ Two users exchange encrypted messages
-✅ Recipient decrypts correctly
-✅ DropOnAir never accesses plaintext (blind relay)
-✅ Tampering detection (GCM auth tag)
-✅ AAD binding prevents context attacks
-✅ Session caching for performance
-```
+## Support
 
-**🔒 End-to-End Encryption is FULLY FUNCTIONAL**
+- **Website:** [droponair.com](https://droponair.com)
+- **Email:** info@droponair.com

package/dist/version.d.ts

@@ -7,7 +7,7 @@
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-export declare const SDK_VERSION = "0.3.0";
+export declare const SDK_VERSION = "0.3.1";
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/dist/version.js

@@ -10,7 +10,7 @@ exports.PROTOCOL_VERSION = exports.PAYLOAD_FORMAT_VERSION = exports.SDK_VERSION
  *   MINOR, additive feature (e.g. multi-device payloads, new call event type)
  *   PATCH, bug-fix / perf improvement with no wire or API change
  */
-exports.SDK_VERSION = '0.3.0';
+exports.SDK_VERSION = '0.3.1';
 /**
  * Binary encrypted-payload format version.
  * Included as the first byte of every encrypted payload so receivers can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@droponair/sdk-js",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "DropOnAir SDK for end-to-end encrypted messaging",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",