@convirza/dialer-sdk 1.0.0

package/README.md

@@ -0,0 +1,1841 @@
+# @convirza/dialer-sdk
+
+Production-ready embeddable WebRTC SIP dialer widget. Auto-configures from OAuth session, handles token refresh, cross-tab logout detection. Includes call parking, call history persistence, audio device management, call quality monitoring.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [Global Singleton API](#option-a--global-singleton-api-recommended)
+  - [Standalone Helpers](#option-b--standalone-helper-functions)
+  - [Web Component](#option-c--web-component-convirza-dialer)
+- [Authentication Flow](#authentication-flow)
+  - [How It Works](#how-it-works)
+  - [Token Refresh](#token-refresh)
+  - [Logout Detection](#logout-detection)
+- [API Reference](#api-reference)
+  - [convirzaDialer (Singleton)](#convirzadialer-singleton-dialerapi)
+  - [SipAdapter (Headless SIP)](#sipadapter)
+  - [AudioDeviceManager](#audiodevicemanager)
+  - [CallQualityMonitor](#callqualitymonitor)
+  - [PhoneNumbersAPI](#phonenumbersapi)
+  - [CallHistoryAPI](#callhistoryapi)
+- [Web Component Reference](#web-component-reference)
+  - [HTML Attributes](#web-component-attributes)
+  - [Public Methods](#web-component-public-methods)
+  - [Events](#web-component-events)
+- [Feature Guides](#feature-guides)
+  - [Call Parking](#call-parking)
+  - [Call History Persistence](#call-history-persistence)
+  - [Audio Device Management](#audio-device-management-1)
+  - [Call Quality Monitoring](#call-quality-monitoring-1)
+  - [Theming](#theming)
+- [Types](#types)
+- [Browser Support](#browser-support)
+
+---
+
+## Installation
+
+```bash
+npm install @convirza/dialer-sdk
+```
+
+**Peer dependency** — SIP.js must be loaded separately (UMD global `SIP` or `sip`):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/sip.js@0.13.8/dist/sip.js"></script>
+```
+
+Or install via npm and bundle it yourself:
+
+```bash
+npm install sip.js@^0.13.8
+```
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+User must be logged into your app with `access_token` + `refresh_token` stored in `localStorage`.
+
+### Option A — Global singleton API (recommended)
+
+Best for single-page apps where the dialer is always present.
+
+```js
+import { convirzaDialer } from '@convirza/dialer-sdk';
+
+// Get tokens from user session (set during login)
+const accessToken = localStorage.getItem('access_token');
+const refreshToken = localStorage.getItem('refresh_token');
+
+// Initialize widget (auto-fetches SIP config from OAuth session endpoint)
+convirzaDialer.init({
+	access_token: accessToken,
+	refresh_token: refreshToken,
+	oauth_endpoint: 'https://stag-5-oauth.convirza.com/oauth/internal',
+	api_url: 'https://stag-5-dialer-apis.convirza.com',
+	dark_theme: true,
+	primaryColor: '#6366f1',
+	brandName: 'Acme Corp',
+});
+
+// Listen for token refresh (only fired if access_token expires)
+window.addEventListener('dialer-token-refreshed', (e) => {
+	localStorage.setItem('access_token', e.detail.access_token);
+	localStorage.setItem('refresh_token', e.detail.refresh_token);
+	console.log('Dialer tokens refreshed');
+});
+
+// Handle auth failure (refresh_token expired)
+window.addEventListener('dialer-auth-failed', (e) => {
+	console.error('Dialer auth failed:', e.detail.error);
+	localStorage.clear();
+	window.location.href = '/login';
+});
+
+// Cross-tab logout detection (auto-destroys widget)
+// Storage event fires when another tab removes access_token
+window.addEventListener('storage', (e) => {
+	if (e.key === 'access_token' && !e.newValue) {
+		convirzaDialer.destroy();
+	}
+});
+
+// Place a call
+convirzaDialer.call('+15551234567');
+
+// Control active call
+convirzaDialer.mute(true);
+convirzaDialer.hold(true);
+
+// End the active call
+convirzaDialer.endCall();
+
+// Clean up on logout
+convirzaDialer.destroy();
+```
+
+### Option B — Standalone helper functions
+
+Same as singleton, but exposed as named exports for tree-shaking.
+
+```js
+import { initDialer, destroyDialer, isDialerInitialized } from '@convirza/dialer-sdk';
+
+const accessToken = localStorage.getItem('access_token');
+const refreshToken = localStorage.getItem('refresh_token');
+
+initDialer({
+	access_token: accessToken,
+	refresh_token: refreshToken,
+	api_url: 'https://stag-5-dialer-apis.convirza.com',
+});
+
+if (isDialerInitialized()) {
+	destroyDialer();
+}
+```
+
+### Option C — Web Component (`<convirza-dialer>`)
+
+Embed the dialer widget as a custom HTML element.
+
+```html
+<script type="module">
+	import '@convirza/dialer-sdk';
+
+	const accessToken = localStorage.getItem('access_token');
+	const refreshToken = localStorage.getItem('refresh_token');
+
+	const dialer = document.createElement('convirza-dialer');
+	dialer.setAttribute('access-token', accessToken);
+	dialer.setAttribute('refresh-token', refreshToken);
+	dialer.setAttribute('auto-configure', 'true');
+	dialer.setAttribute('oauth-endpoint', 'https://stag-5-oauth.convirza.com/oauth/internal');
+	dialer.setAttribute('theme', 'dark');
+	dialer.setAttribute('api-url', 'https://stag-5-dialer-apis.convirza.com');
+
+	// Listen for token refresh (only fires if access_token expires)
+	dialer.addEventListener('token-refreshed', (e) => {
+		localStorage.setItem('access_token', e.detail.access_token);
+		localStorage.setItem('refresh_token', e.detail.refresh_token);
+	});
+
+	// Handle auth failure
+	dialer.addEventListener('auth-failed', (e) => {
+		console.error('Auth failed:', e.detail.error);
+		window.location.href = '/login';
+	});
+
+	document.body.appendChild(dialer);
+</script>
+```
+
+**Attributes:**
+
+- `access-token` — Access token from user login (used first)
+- `refresh-token` — Refresh token (fallback if access_token expires)
+- `auto-configure="true"` — Enables auto-config flow
+- `oauth-endpoint` — OAuth base URL (default: `https://stag-5-oauth.convirza.com/oauth/internal`)
+- `api-url` — API base URL for park slots, call history
+
+**Events:**
+
+- `token-refreshed` — New tokens received (only if access_token expired)
+- `auth-failed` — Both tokens failed (redirect to login)
+
+---
+
+## Authentication Flow
+
+### How It Works
+
+Widget auto-configures SIP credentials from OAuth session data. No manual SIP configuration needed.
+
+**1. User logs into main app**
+
+Your app authenticates user → receives `access_token` + `refresh_token`:
+
+```javascript
+// Your login handler
+const response = await fetch('https://stag-5-oauth.convirza.com/oauth/internal/token', {
+	method: 'POST',
+	headers: { 'Content-Type': 'application/json' },
+	body: JSON.stringify({ email, password }),
+});
+
+const { access_token, refresh_token } = response.data;
+
+localStorage.setItem('access_token', access_token);
+localStorage.setItem('refresh_token', refresh_token);
+```
+
+**2. Initialize dialer with tokens**
+
+```javascript
+convirzaDialer.init({
+	access_token: localStorage.getItem('access_token'),
+	refresh_token: localStorage.getItem('refresh_token'),
+	oauth_endpoint: 'https://stag-5-oauth.convirza.com/oauth/internal',
+});
+```
+
+**3. Widget fetches SIP config**
+
+Widget calls `GET /oauth/internal/session` with `access_token` → gets user's dialer config:
+
+```json
+{
+	"user": {
+		"user_id": 123,
+		"dialer_config": {
+			"domains": [
+				{
+					"sip_domain": "prod-registration",
+					"sip_proxy_1": "sip.example.com",
+					"extensions": [{ "extension": "1001" }]
+				}
+			]
+		}
+	}
+}
+```
+
+**4. Widget auto-configures SIP credentials**
+
+Internally sets:
+
+- SIP username: `1001` (from extension)
+- SIP password: `123@prod-registration` (user_id @ sip_domain)
+- SIP domain: `prod-registration`
+- WebSocket server: `wss://sip.example.com:8443`
+
+**5. Widget connects to SIP server**
+
+SIP registration happens automatically. Widget ready to make calls.
+
+### Token Refresh
+
+**Automatic refresh on expiry:**
+
+1. Widget tries `GET /session` with `access_token`
+2. If 401 Unauthorized → `access_token` expired
+3. Widget calls `POST /refresh-token` with `refresh_token`
+4. Gets new `access_token` + `refresh_token`
+5. Widget emits `dialer-token-refreshed` event
+6. Your app updates localStorage
+
+```javascript
+window.addEventListener('dialer-token-refreshed', (e) => {
+	localStorage.setItem('access_token', e.detail.access_token);
+	localStorage.setItem('refresh_token', e.detail.refresh_token);
+});
+```
+
+**If refresh_token also expired:**
+
+Widget emits `dialer-auth-failed` → redirect user to login.
+
+### Logout Detection
+
+**Same-tab logout:**
+
+```javascript
+// Your logout handler
+function logout() {
+	localStorage.removeItem('access_token');
+	localStorage.removeItem('refresh_token');
+	convirzaDialer.destroy(); // Widget destroyed
+	window.location.href = '/login';
+}
+```
+
+**Cross-tab logout:**
+
+Widget automatically destroys when `access_token` removed in another tab:
+
+```javascript
+// Storage event listener (built into widget)
+window.addEventListener('storage', (e) => {
+	if (e.key === 'access_token' && !e.newValue) {
+		convirzaDialer.destroy(); // Auto-destroyed
+	}
+});
+```
+
+User logs out in Tab A → widget destroyed in Tab B automatically.
+
+### Backend Requirements
+
+Widget expects these OAuth endpoints:
+
+**Session endpoint:**
+
+```
+GET /oauth/internal/session
+Authorization: Bearer {access_token}
+
+Returns: { user: { dialer_config: {...} } }
+```
+
+**Refresh endpoint:**
+
+```
+POST /oauth/internal/refresh-token
+Body: { refresh_token: "..." }
+
+Returns: { access_token, refresh_token, user: { dialer_config: {...} } }
+```
+
+---
+
+## API Reference
+
+### `convirzaDialer` (singleton `DialerAPI`)
+
+The default export is a singleton that manages the `<convirza-dialer>` web component and provides a simple imperative API.
+
+#### `convirzaDialer.init(config)`
+
+Initialize the dialer and inject the widget into the page. **Must be called before any other method.**
+
+```ts
+convirzaDialer.init(config: DialerInitConfig): void
+```
+
+| Field            | Type      | Required | Description                                  |
+| ---------------- | --------- | -------- | -------------------------------------------- |
+| `access_token`   | `string`  | Yes      | Access token from user login session         |
+| `refresh_token`  | `string`  | Yes      | Refresh token (used if access_token expires) |
+| `oauth_endpoint` | `string`  | No       | OAuth base URL (default: internal)           |
+| `api_url`        | `string`  | No       | API base URL for park slots, call history    |
+| `brandName`      | `string`  | No       | Brand name shown in widget header            |
+| `brandLogo`      | `string`  | No       | URL of brand logo image                      |
+| `dark_theme`     | `boolean` | No       | Use dark theme (default `false`)             |
+| `showPopup`      | `boolean` | No       | Start with widget expanded                   |
+| `primaryColor`   | `string`  | No       | CSS color for primary UI elements (hex/rgb)  |
+| `accentColor`    | `string`  | No       | CSS color for accent elements                |
+
+OAuth response provides SIP credentials automatically. User never sees SIP details.
+
+**Example:**
+
+```js
+convirzaDialer.init({
+	oauth_endpoint: 'https://api.example.com/oauth/token',
+	username: 'user@example.com',
+	password: 'userpassword',
+	dark_theme: true,
+	primaryColor: '#6366f1',
+	brandName: 'Acme Corp',
+	brandLogo: 'https://example.com/logo.png',
+});
+```
+
+#### `convirzaDialer.refresh()`
+
+Re-initialize the widget using the same config. Useful after credential rotation.
+
+```ts
+convirzaDialer.refresh(): void
+```
+
+#### `convirzaDialer.call(phoneNumber?)`
+
+Place an outbound call. Opens the widget popup if collapsed.
+
+```ts
+convirzaDialer.call(phoneNumber?: string): void
+```
+
+**Parameters:**
+
+- `phoneNumber` (optional): E.164 phone number (e.g., `+15551234567`) or SIP extension. If omitted, just opens the widget.
+
+**Example:**
+
+```js
+// Dial number immediately
+convirzaDialer.call('+15551234567');
+
+// Open widget without dialing
+convirzaDialer.call();
+```
+
+#### `convirzaDialer.endCall()`
+
+Hang up the active call. Throws if there is no active call.
+
+```ts
+convirzaDialer.endCall(): void
+```
+
+**Example:**
+
+```js
+if (convirzaDialer.getActiveCallID()) {
+	convirzaDialer.endCall();
+}
+```
+
+#### `convirzaDialer.mute(enable?)`
+
+Mute or unmute the microphone. Toggles if `enable` is omitted.
+
+```ts
+convirzaDialer.mute(enable?: boolean): boolean  // returns current mute state
+```
+
+**Parameters:**
+
+- `enable` (optional): `true` to mute, `false` to unmute. Omit to toggle.
+
+**Returns:** Current mute state (`true` = muted).
+
+**Example:**
+
+```js
+// Toggle mute
+const isMuted = convirzaDialer.mute();
+
+// Explicitly mute
+convirzaDialer.mute(true);
+
+// Explicitly unmute
+convirzaDialer.mute(false);
+```
+
+#### `convirzaDialer.hold(enable?)`
+
+Place the call on hold or take it off hold.
+
+```ts
+convirzaDialer.hold(enable?: boolean): boolean
+```
+
+**Parameters:**
+
+- `enable` (optional): `true` to hold, `false` to unhold. Omit to toggle.
+
+**Returns:** Current hold state (`true` = on hold).
+
+**Example:**
+
+```js
+// Toggle hold
+const isOnHold = convirzaDialer.hold();
+
+// Explicitly hold
+convirzaDialer.hold(true);
+
+// Explicitly resume
+convirzaDialer.hold(false);
+```
+
+#### `convirzaDialer.record(enable?)`
+
+Start or stop server-side recording. Sends SIP INFO message to backend.
+
+```ts
+convirzaDialer.record(enable?: boolean): boolean  // returns current recording state
+```
+
+**Parameters:**
+
+- `enable` (optional): `true` to start recording, `false` to stop. Omit to toggle.
+
+**Returns:** Current recording state (`true` = recording).
+
+**Note:** Server must support `application/x-recording-command` SIP INFO messages.
+
+**Example:**
+
+```js
+// Start recording
+convirzaDialer.record(true);
+
+// Stop recording
+convirzaDialer.record(false);
+```
+
+#### `convirzaDialer.transfer(target)`
+
+Blind-transfer the active call to another extension or phone number.
+
+```ts
+convirzaDialer.transfer(target: string): void
+```
+
+**Parameters:**
+
+- `target`: SIP URI (e.g., `sip:1002@pbx.example.com`) or bare extension (e.g., `1002`).
+
+**Example:**
+
+```js
+// Transfer to extension
+convirzaDialer.transfer('1002');
+
+// Transfer to external number
+convirzaDialer.transfer('+15559876543');
+```
+
+#### `convirzaDialer.showPopup()`
+
+Expand the dialer widget.
+
+```ts
+convirzaDialer.showPopup(): void
+```
+
+#### `convirzaDialer.hidePopup()`
+
+Collapse the dialer widget to floating action button (FAB).
+
+```ts
+convirzaDialer.hidePopup(): void
+```
+
+#### `convirzaDialer.getActiveCallID()`
+
+Returns the ID of the active call, or `null` if idle.
+
+```ts
+convirzaDialer.getActiveCallID(): string | null
+```
+
+**Example:**
+
+```js
+const callId = convirzaDialer.getActiveCallID();
+if (callId) {
+	console.log('Active call:', callId);
+}
+```
+
+#### `convirzaDialer.callList(limit?)`
+
+Returns the in-session call history (most recent first).
+
+```ts
+convirzaDialer.callList(limit?: number): CallListItem[]
+```
+
+**Parameters:**
+
+- `limit` (optional): Max number of calls to return.
+
+**Returns:** Array of `CallListItem`:
+
+```ts
+interface CallListItem {
+	id: string;
+	phoneNumber: string;
+	timestamp: number; // Unix timestamp (ms)
+	duration?: number; // Call duration in milliseconds
+	direction: 'inbound' | 'outbound';
+	status: 'answered' | 'missed' | 'voicemail';
+}
+```
+
+**Example:**
+
+```js
+const recent = convirzaDialer.callList(10);
+recent.forEach((call) => {
+	console.log(`${call.direction} call to ${call.phoneNumber}: ${call.status}`);
+});
+```
+
+#### `convirzaDialer.destroy()`
+
+Remove the widget from DOM and clean up all event listeners. Call on logout or page unload.
+
+```ts
+convirzaDialer.destroy(): void
+```
+
+**Example:**
+
+```js
+// On user logout
+function logout() {
+	convirzaDialer.destroy();
+	// ... other cleanup
+}
+```
+
+#### Read-only properties
+
+| Property           | Type      | Description             |
+| ------------------ | --------- | ----------------------- |
+| `isMutedState`     | `boolean` | Current mute state      |
+| `isRecordingState` | `boolean` | Current recording state |
+
+---
+
+### Helper functions
+
+#### `initDialer(config)`
+
+Initialize the global dialer. Warns and no-ops if called a second time.
+
+```ts
+import { initDialer } from '@convirza/dialer-sdk';
+initDialer(config: DialerInitConfig): void
+```
+
+#### `destroyDialer()`
+
+Destroy the global dialer. Warns if not initialized.
+
+```ts
+import { destroyDialer } from '@convirza/dialer-sdk';
+destroyDialer(): void
+```
+
+#### `isDialerInitialized()`
+
+Returns `true` if the global dialer has been initialized.
+
+```ts
+import { isDialerInitialized } from '@convirza/dialer-sdk';
+isDialerInitialized(): boolean
+```
+
+---
+
+### `SipAdapter`
+
+Low-level SIP client for headless / custom-UI integrations. Requires `sip.js` as a UMD global (`window.SIP` or `window.sip`).
+
+#### Constructor
+
+```ts
+new SipAdapter(config: SipConfig, callbacks?: SipCallbacks)
+```
+
+**`SipConfig`**
+
+| Field          | Type             | Required | Description                                       |
+| -------------- | ---------------- | -------- | ------------------------------------------------- |
+| `sipUsername`  | `string`         | Yes      | SIP username                                      |
+| `sipPassword`  | `string`         | Yes      | SIP password                                      |
+| `sipDomain`    | `string`         | Yes      | SIP registrar domain                              |
+| `wsServers`    | `string[]`       | Yes      | WebSocket proxy URL(s)                            |
+| `displayName`  | `string`         | No       | Caller display name                               |
+| `iceServers`   | `RTCIceServer[]` | No       | Override STUN/TURN servers (default: Google STUN) |
+| `microphoneId` | `string`         | No       | Preferred microphone device ID                    |
+| `speakerId`    | `string`         | No       | Preferred speaker device ID                       |
+| `apiUrl`       | `string`         | No       | Backend API URL (required for call parking)       |
+| `authToken`    | `string`         | No       | Bearer token (required for authenticated APIs)    |
+
+**`SipCallbacks`**
+
+| Callback                 | Signature                                            | When it fires                                             |
+| ------------------------ | ---------------------------------------------------- | --------------------------------------------------------- |
+| `onRegistered`           | `() => void`                                         | SIP registration succeeded                                |
+| `onUnregistered`         | `() => void`                                         | SIP unregistered (intentional or expired)                 |
+| `onRegistrationFailed`   | `(cause?: string) => void`                           | Registration failed (e.g., 403 wrong password)            |
+| `onTransportError`       | `(error: Error) => void`                             | WebSocket transport error                                 |
+| `onConnecting`           | `() => void`                                         | Transport connecting (before registration)                |
+| `onCallRinging`          | `() => void`                                         | Outbound call is ringing (received 180 Ringing)           |
+| `onCallAnswered`         | `() => void`                                         | Call connected (received 200 OK)                          |
+| `onCallEnded`            | `(reason?: string) => void`                          | Call ended by any party (BYE, CANCEL, timeout)            |
+| `onCallFailed`           | `(error: Error) => void`                             | Call setup or media failure (e.g., no WebRTC permissions) |
+| `onIncomingCall`         | `(phoneNumber: string, callerName?: string) => void` | Inbound INVITE received                                   |
+| `onRemoteHold`           | `(isOnHold: boolean) => void`                        | Remote party placed call on hold                          |
+| `onQualityChange`        | `(metrics: CallQualityMetrics) => void`              | Periodic RTC quality update (every 2s)                    |
+| `onRecordingStateChange` | `(recording: boolean) => void`                       | Server recording started/stopped (via SIP INFO)           |
+| `onTransferSucceeded`    | `() => void`                                         | Blind transfer (REFER) accepted by server                 |
+| `onTransferFailed`       | `(reason: string) => void`                           | Blind transfer rejected by server                         |
+| `onDevicesChanged`       | `(devices: AudioDevice[]) => void`                   | Audio device list changed (mic/speaker plugged in/out)    |
+| `onError`                | `(error: Error) => void`                             | General unhandled error                                   |
+
+#### Methods
+
+##### `sip.connect()`
+
+Connect to the WebSocket transport and register with the SIP server. **Must be called first.**
+
+```ts
+await sip.connect(): Promise<void>
+```
+
+**Example:**
+
+```js
+await sip.connect();
+console.log('Registered with SIP server');
+```
+
+**Errors:**
+
+- Throws if SIP.js not loaded
+- Throws if WebSocket connection fails
+- Fires `onRegistrationFailed` on auth failure
+
+##### `sip.disconnect()`
+
+End any active call, unregister, and close the WebSocket transport.
+
+```ts
+await sip.disconnect(): Promise<void>
+```
+
+**Example:**
+
+```js
+await sip.disconnect();
+console.log('Disconnected from SIP server');
+```
+
+##### `sip.call(phoneNumber, options?)`
+
+Place an outbound call.
+
+```ts
+await sip.call(phoneNumber: string, options?: {
+  callerId?: string;       // P-Asserted-Identity number (E.164)
+  callerIdName?: string;   // P-Asserted-Identity display name
+}): Promise<void>
+```
+
+**Parameters:**
+
+- `phoneNumber`: E.164 phone number or SIP extension
+- `options.callerId`: Override outbound caller ID (if supported by server)
+- `options.callerIdName`: Caller display name
+
+**Example:**
+
+```js
+// Simple call
+await sip.call('+15551234567');
+
+// With custom caller ID
+await sip.call('+15551234567', {
+	callerId: '+15559876543',
+	callerIdName: 'Support Line',
+});
+```
+
+**Fires:**
+
+- `onCallRinging` when remote party rings
+- `onCallAnswered` when call connects
+- `onCallFailed` on error
+
+##### `sip.endCall()`
+
+Hang up the current call (sends BYE or CANCEL as appropriate).
+
+```ts
+await sip.endCall(): Promise<void>
+```
+
+**Example:**
+
+```js
+if (sip.hasActiveCall) {
+	await sip.endCall();
+}
+```
+
+##### `sip.answerCall()`
+
+Answer an incoming call. **Must be called after `onIncomingCall` fires.**
+
+```ts
+await sip.answerCall(): Promise<void>
+```
+
+**Example:**
+
+```js
+const sip = new SipAdapter(config, {
+	onIncomingCall: (number, name) => {
+		console.log(`Incoming call from ${name} <${number}>`);
+		sip.answerCall(); // Auto-answer
+	},
+});
+```
+
+##### `sip.rejectCall()`
+
+Reject an incoming call (sends 486 Busy Here).
+
+```ts
+await sip.rejectCall(): Promise<void>
+```
+
+**Example:**
+
+```js
+const sip = new SipAdapter(config, {
+	onIncomingCall: (number) => {
+		if (number === '+15551111111') {
+			sip.rejectCall(); // Block this caller
+		}
+	},
+});
+```
+
+##### `sip.mute(enable?)`
+
+Mute/unmute the local microphone track. Toggles if `enable` is omitted.
+
+```ts
+sip.mute(enable?: boolean): boolean  // returns new mute state
+```
+
+**Example:**
+
+```js
+// Toggle mute
+const isMuted = sip.mute();
+
+// Explicitly mute
+sip.mute(true);
+```
+
+##### `sip.hold(enable?)`
+
+Put the call on hold (`true`) or take it off hold (`false`). Defaults to `true`.
+
+```ts
+await sip.hold(enable?: boolean): Promise<void>
+```
+
+**Example:**
+
+```js
+// Put on hold
+await sip.hold(true);
+
+// Resume
+await sip.hold(false);
+```
+
+**Note:** Uses SIP re-INVITE with `sendrecv`/`sendonly` SDP attributes.
+
+##### `sip.sendDTMF(digit)`
+
+Send a DTMF digit via SIP INFO (RFC 2833 alternative).
+
+```ts
+sip.sendDTMF(digit: string): void  // digit: '0'-'9', '*', '#'
+```
+
+**Example:**
+
+```js
+// Send IVR menu choice
+sip.sendDTMF('1');
+
+// Send PIN
+'1234'.split('').forEach((d) => sip.sendDTMF(d));
+```
+
+**Note:** Uses `application/dtmf-relay` content type.
+
+##### `sip.startRecording()`
+
+Signal the server to start recording (sends SIP INFO with `application/x-recording-command: start`).
+
+```ts
+sip.startRecording(): void
+```
+
+**Example:**
+
+```js
+sip.startRecording();
+console.log('Recording started');
+```
+
+##### `sip.stopRecording()`
+
+Signal the server to stop recording.
+
+```ts
+sip.stopRecording(): void
+```
+
+##### `sip.park(parkExtension)`
+
+Park the call at a valet park slot via the Convirza REST API. Requires `apiUrl` and `authToken` in config.
+
+```ts
+await sip.park(parkExtension: string): Promise<void>
+```
+
+**Parameters:**
+
+- `parkExtension`: Park slot extension (e.g., `'700'`)
+
+**Example:**
+
+```js
+// Park call at slot 700
+await sip.park('700');
+```
+
+**See:** [Call Parking Guide](#call-parking) for full details.
+
+##### `sip.blindTransfer(target)`
+
+Blind-transfer the call via SIP REFER. `target` can be a full SIP URI or a bare extension.
+
+```ts
+await sip.blindTransfer(target: string): Promise<void>
+```
+
+**Parameters:**
+
+- `target`: SIP URI (e.g., `sip:1002@pbx.example.com`) or extension (e.g., `1002`)
+
+**Example:**
+
+```js
+// Transfer to extension
+await sip.blindTransfer('1002');
+
+// Transfer to external number
+await sip.blindTransfer('sip:+15559876543@pbx.example.com');
+```
+
+**Fires:**
+
+- `onTransferSucceeded` on 202 Accepted
+- `onTransferFailed` on rejection
+
+##### `sip.setMicrophone(deviceId)`
+
+Hot-swap the active microphone without interrupting the call.
+
+```ts
+await sip.setMicrophone(deviceId: string): Promise<void>
+```
+
+**Parameters:**
+
+- `deviceId`: MediaDeviceInfo device ID
+
+**Example:**
+
+```js
+const devices = await sip.getAudioDevices();
+const builtInMic = devices.microphones.find((d) => d.label.includes('Built-in'));
+if (builtInMic) {
+	await sip.setMicrophone(builtInMic.deviceId);
+}
+```
+
+**Note:** Uses `replaceTrack()` on the sender — no interruption to call.
+
+##### `sip.setSpeaker(deviceId)`
+
+Switch the audio output device.
+
+```ts
+await sip.setSpeaker(deviceId: string): Promise<void>
+```
+
+**Parameters:**
+
+- `deviceId`: MediaDeviceInfo device ID
+
+**Example:**
+
+```js
+const devices = await sip.getAudioDevices();
+const headphones = devices.speakers.find((d) => d.label.includes('Headphones'));
+if (headphones) {
+	await sip.setSpeaker(headphones.deviceId);
+}
+```
+
+**Browser support:** Chrome/Edge only (`setSinkId` API). Silently no-ops in Firefox/Safari.
+
+##### `sip.getAudioDevices()`
+
+Enumerate available microphones and speakers.
+
+```ts
+await sip.getAudioDevices(): Promise<{
+  microphones: Array<{ deviceId: string; label: string }>;
+  speakers:    Array<{ deviceId: string; label: string }>;
+}>
+```
+
+**Example:**
+
+```js
+const { microphones, speakers } = await sip.getAudioDevices();
+console.log(
+	'Mics:',
+	microphones.map((m) => m.label)
+);
+console.log(
+	'Speakers:',
+	speakers.map((s) => s.label)
+);
+```
+
+**Note:** Requires microphone permission. Labels are generic until permission granted.
+
+##### `sip.getCurrentDevices()`
+
+Return the currently active microphone and speaker device IDs.
+
+```ts
+sip.getCurrentDevices(): { microphoneId: string | null; speakerId: string | null }
+```
+
+**Example:**
+
+```js
+const { microphoneId, speakerId } = sip.getCurrentDevices();
+console.log('Active mic:', microphoneId);
+console.log('Active speaker:', speakerId);
+```
+
+##### `sip.getCallQuality()`
+
+Return the last WebRTC quality metrics sample, or `null` if no call is active.
+
+```ts
+sip.getCallQuality(): CallQualityMetrics | null
+```
+
+**Returns:**
+
+```ts
+interface CallQualityMetrics {
+	bitrate: number; // kbps
+	packetLoss: number; // percentage (0-100)
+	jitter: number; // ms
+	latency: number; // ms (round-trip time)
+	audioLevel: number; // 0–1 (remote audio volume)
+	quality: 'excellent' | 'good' | 'fair' | 'poor';
+}
+```
+
+**Example:**
+
+```js
+const metrics = sip.getCallQuality();
+if (metrics && metrics.quality === 'poor') {
+	console.warn('Poor call quality:', metrics.packetLoss + '% packet loss');
+}
+```
+
+##### `sip.getCallUuid()`
+
+Return the active call UUID (FreeSWITCH channel UUID or SIP Call-ID). Useful for server-side operations.
+
+```ts
+sip.getCallUuid(): string | null
+```
+
+**Example:**
+
+```js
+const uuid = sip.getCallUuid();
+console.log('Call UUID for backend lookup:', uuid);
+```
+
+##### `sip.reconnect()`
+
+Trigger an immediate reconnection attempt (resets backoff counter). Useful on the browser `online` event.
+
+```ts
+sip.reconnect(): void
+```
+
+**Example:**
+
+```js
+window.addEventListener('online', () => {
+	sip.reconnect(); // Force reconnect after network restored
+});
+```
+
+##### Read-only properties
+
+| Property        | Type      | Description                                                  |
+| --------------- | --------- | ------------------------------------------------------------ |
+| `isConnected`   | `boolean` | Whether the WebSocket transport is up                        |
+| `hasActiveCall` | `boolean` | Whether a SIP session is in progress (any state except idle) |
+
+---
+
+### `AudioDeviceManager`
+
+Standalone audio device manager. Used internally by `SipAdapter` but also exportable for custom UIs.
+
+```ts
+import { AudioDeviceManager } from '@convirza/dialer-sdk';
+
+const adm = new AudioDeviceManager({
+	onDevicesChanged: (devices) => console.log(devices),
+	onMicrophoneChanged: (id) => console.log('Mic changed:', id),
+	onSpeakerChanged: (id) => console.log('Speaker changed:', id),
+});
+
+const devices = await adm.enumerateDevices();
+const mics = adm.getMicrophones();
+const spk = adm.getSpeakers();
+
+adm.savePreferences({ microphoneId: mics[0].deviceId, speakerId: spk[0].deviceId });
+const prefs = adm.loadPreferences();
+
+await adm.applyAudioOutputDevice(audioElement, spk[0].deviceId);
+
+adm.destroy();
+```
+
+| Method                                 | Returns                           | Description                                  |
+| -------------------------------------- | --------------------------------- | -------------------------------------------- |
+| `enumerateDevices()`                   | `Promise<AudioDevice[]>`          | Refresh and return all audio devices         |
+| `refreshDevices()`                     | `Promise<AudioDevice[]>`          | Alias for `enumerateDevices()`               |
+| `getMicrophones()`                     | `AudioDevice[]`                   | Cached microphone list                       |
+| `getSpeakers()`                        | `AudioDevice[]`                   | Cached speaker list                          |
+| `savePreferences(prefs)`               | `void`                            | Persist device preferences to `localStorage` |
+| `loadPreferences()`                    | `DevicePreferences`               | Load persisted preferences                   |
+| `applyAudioOutputDevice(el, deviceId)` | `Promise<void>`                   | Set `setSinkId` on an `<audio>` element      |
+| `getAudioConstraints(microphoneId)`    | `Promise<MediaStreamConstraints>` | Build `getUserMedia` constraints             |
+| `destroy()`                            | `void`                            | Remove `devicechange` listener               |
+
+---
+
+### `CallQualityMonitor`
+
+Periodically samples WebRTC stats and emits quality metrics.
+
+```ts
+import { CallQualityMonitor } from '@convirza/dialer-sdk';
+
+const monitor = new CallQualityMonitor();
+monitor.setOnQualityChange((metrics) => {
+	console.log(metrics.quality, metrics.packetLoss, metrics.latency);
+});
+
+monitor.start(peerConnection, 2000); // sample every 2 s
+// ...
+const last = monitor.getLastMetrics();
+monitor.stop();
+```
+
+| Method                   | Description                                |
+| ------------------------ | ------------------------------------------ |
+| `start(pc, interval?)`   | Start sampling (default 2000 ms)           |
+| `stop()`                 | Stop sampling and clear state              |
+| `setOnQualityChange(cb)` | Register quality callback                  |
+| `getLastMetrics()`       | Return last `CallQualityMetrics` or `null` |
+
+---
+
+### `PhoneNumbersAPI`
+
+REST client for fetching provisioned phone numbers from the Convirza backend.
+
+```ts
+import { PhoneNumbersAPI } from '@convirza/dialer-sdk';
+
+const api = new PhoneNumbersAPI('https://api.convirza.com', 'Bearer-token');
+api.setAuthToken('new-token');
+
+const result = await api.fetchOrderedNumbers({
+	domainId: 123,
+	limit: 50,
+	status: 'provisioned',
+});
+// result: { items: OrderedPhoneNumber[], total: number }
+```
+
+| Method                        | Description                                  |
+| ----------------------------- | -------------------------------------------- |
+| `setAuthToken(token)`         | Update the bearer token                      |
+| `fetchOrderedNumbers(params)` | Fetch provisioned phone numbers for a domain |
+
+---
+
+### `CallHistoryAPI`
+
+REST client for persisting and querying call history.
+
+```ts
+import { CallHistoryAPI } from '@convirza/dialer-sdk';
+
+const api = new CallHistoryAPI('https://api.convirza.com', 'Bearer-token');
+
+const history = await api.fetchHistory({
+	userId: 'user-123',
+	sipDomain: 'sip.example.com',
+	limit: 50,
+	offset: 0,
+});
+// history: { calls: CallRecord[], total: number, hasMore: boolean }
+
+const saved = await api.saveCall({
+	callId: 'abc-123',
+	userId: 'user-123',
+	sipDomain: 'sip.example.com',
+	callerIdNumber: '+15551234567',
+	phoneNumber: '+19876543210',
+	direction: 'outbound',
+	disposition: 'answered',
+	startedAt: Date.now(),
+	durationSeconds: 42,
+	createdAt: Date.now(),
+});
+
+const updated = await api.updateCall(saved.callId, { disposition: 'missed' });
+```
+
+| Method                        | Description                      |
+| ----------------------------- | -------------------------------- |
+| `setAuthToken(token)`         | Update the bearer token          |
+| `fetchHistory(params)`        | Fetch paginated call history     |
+| `saveCall(record)`            | Create a new call history record |
+| `updateCall(callId, updates)` | Patch an existing call record    |
+
+---
+
+## Web Component Reference
+
+### Web Component Attributes
+
+The `<convirza-dialer>` custom element accepts the following HTML attributes:
+
+| Attribute            | Type                                                           | Required | Description                                      |
+| -------------------- | -------------------------------------------------------------- | -------- | ------------------------------------------------ |
+| `access-token`       | `string`                                                       | Yes\*    | Access token from user login                     |
+| `refresh-token`      | `string`                                                       | Yes\*    | Refresh token (fallback if access_token expires) |
+| `auto-configure`     | `'true' \| 'false'`                                            | Yes\*    | Enable auto-config from OAuth session            |
+| `oauth-endpoint`     | `string`                                                       | No       | OAuth base URL (default: stag-5 internal)        |
+| `api-url`            | `string`                                                       | No       | API base URL for park/history                    |
+| `brand-name`         | `string`                                                       | No       | Brand name in header                             |
+| `brand-logo`         | `string`                                                       | No       | URL for brand logo                               |
+| `theme`              | `'light' \| 'dark'`                                            | No       | UI theme (default: dark)                         |
+| `primary-color`      | `string`                                                       | No       | Primary CSS color (hex/rgb)                      |
+| `accent-color`       | `string`                                                       | No       | Accent CSS color                                 |
+| `position`           | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | No       | Widget corner position (default: bottom-right)   |
+| `state`              | `'collapsed' \| 'expanded'`                                    | No       | Initial state (default: collapsed)               |
+| `z-index`            | `number`                                                       | No       | CSS z-index of the widget                        |
+| `park-poll-interval` | `number`                                                       | No       | Park slots polling interval in ms (default 5000) |
+
+**Required only for auto-configure mode.** Widget fetches SIP credentials from OAuth session endpoint automatically.
+
+### Web Component Public Methods
+
+All methods can be called on the element reference.
+
+#### `element.placeCall(phoneNumber, options?)`
+
+Place an outbound call and return a `CallSession` handle.
+
+```ts
+placeCall(phoneNumber: string, options?: CallOptions): CallSession
+```
+
+**Parameters:**
+
+- `phoneNumber`: E.164 phone number or SIP extension
+- `options.callerId`: Override caller ID
+- `options.displayName`: Override caller display name
+
+**Returns:** `CallSession` object:
+
+```ts
+interface CallSession {
+	phoneNumber: string;
+	status: CallStatus; // Current call status
+	duration: number; // Current duration in ms
+	onAnswered(callback: () => void): void;
+	onEnded(callback: (duration: number) => void): void;
+	end(): void;
+}
+```
+
+**Example:**
+
+```js
+const el = document.querySelector('convirza-dialer');
+const session = el.placeCall('+15551234567');
+
+session.onAnswered(() => {
+	console.log('Call connected');
+});
+
+session.onEnded((duration) => {
+	console.log('Call ended after', duration, 'ms');
+});
+
+// Hang up programmatically
+setTimeout(() => session.end(), 30000); // Hang up after 30s
+```
+
+#### `element.endCall()`
+
+Hang up the active call.
+
+```ts
+endCall(): void
+```
+
+**Example:**
+
+```js
+element.endCall();
+```
+
+#### `element.mute(enable?)`
+
+Mute/unmute microphone. Toggles if `enable` omitted.
+
+```ts
+mute(enable?: boolean): boolean  // returns new mute state
+```
+
+#### `element.hold(enable?)`
+
+Put call on hold. Toggles if `enable` omitted.
+
+```ts
+hold(enable?: boolean): boolean  // returns new hold state
+```
+
+#### `element.sendDTMF(digit)`
+
+Send DTMF digit via SIP INFO.
+
+```ts
+sendDTMF(digit: string): void  // '0'-'9', '*', '#'
+```
+
+#### `element.startRecording()` / `element.stopRecording()`
+
+Start/stop server-side recording.
+
+```ts
+startRecording(): void
+stopRecording(): void
+```
+
+#### `element.open()`
+
+Expand the widget.
+
+```ts
+open(): void
+```
+
+#### `element.close()`
+
+Collapse the widget to FAB.
+
+```ts
+close(): void
+```
+
+#### `element.toggle()`
+
+Toggle widget open/closed.
+
+```ts
+toggle(): void
+```
+
+#### `element.setTheme(options)`
+
+Dynamically update theme.
+
+```ts
+setTheme(options: {
+  theme?: 'dark' | 'light';
+  primaryColor?: string;
+  accentColor?: string;
+  brandName?: string;
+}): void
+```
+
+**Example:**
+
+```js
+element.setTheme({
+	theme: 'dark',
+	primaryColor: '#6366f1',
+	brandName: 'Acme Corp',
+});
+```
+
+#### `element.clearCallHistoryCache()`
+
+Clear IndexedDB call history cache and reload from backend.
+
+```ts
+async clearCallHistoryCache(): Promise<void>
+```
+
+**Example:**
+
+```js
+await element.clearCallHistoryCache();
+```
+
+### Web Component Events
+
+The element dispatches the following `CustomEvent`s:
+
+#### Authentication Events
+
+| Event              | `detail`                                                        | Description                                |
+| ------------------ | --------------------------------------------------------------- | ------------------------------------------ |
+| `token-refreshed`  | `{ access_token: string, refresh_token: string, user: object }` | New tokens received (access_token expired) |
+| `auth-failed`      | `{ error: string }`                                             | Auth failed (both tokens expired/invalid)  |
+| `sip-registered`   | `{}`                                                            | SIP registration successful                |
+| `sip-unregistered` | `{}`                                                            | SIP registration lost                      |
+
+#### Call Events
+
+| Event              | `detail`                                                                        | Description                                      |
+| ------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `call-started`     | `{ phoneNumber: string, callerId?: string, direction?: 'inbound'\|'outbound' }` | Outbound call initiated or inbound call answered |
+| `call-ended`       | `{ phoneNumber: string, duration: number, reason?: string }`                    | Call ended (duration in ms)                      |
+| `call-answered`    | `{}`                                                                            | Call connected (200 OK received)                 |
+| `state-change`     | `{ oldState: CallStatus, newState: CallStatus, metadata?: CallMetadata }`       | Call state transition                            |
+| `sip-call-mute`    | `{ muted: boolean }`                                                            | Mute state changed                               |
+| `sip-call-hold`    | `{ onHold: boolean }`                                                           | Hold state changed                               |
+| `dtmf-sent`        | `{ digit: string }`                                                             | DTMF digit sent                                  |
+| `call-transferred` | `{}`                                                                            | Blind transfer succeeded                         |
+
+#### Widget Events
+
+| Event             | `detail`                         | Description          |
+| ----------------- | -------------------------------- | -------------------- |
+| `widget-opened`   | `{}`                             | Widget expanded      |
+| `widget-closed`   | `{}`                             | Widget collapsed     |
+| `dialer-error`    | `{ error: string }`              | Unhandled error      |
+| `history-updated` | `{ history: CallHistoryItem[] }` | Call history updated |
+
+**Example:**
+
+```js
+// Auth events
+element.addEventListener('token-refreshed', (e) => {
+	localStorage.setItem('access_token', e.detail.access_token);
+	localStorage.setItem('refresh_token', e.detail.refresh_token);
+});
+
+element.addEventListener('auth-failed', (e) => {
+	console.error('Auth failed:', e.detail.error);
+	window.location.href = '/login';
+});
+
+// Call events
+element.addEventListener('call-started', (e) => {
+	console.log('Call started:', e.detail.phoneNumber);
+});
+
+element.addEventListener('call-ended', (e) => {
+	console.log('Call ended after', e.detail.duration / 1000, 'seconds');
+});
+```
+
+---
+
+## Feature Guides
+
+### Call Parking
+
+Call parking allows transferring an active call to a shared "parking lot" where any user in the domain can retrieve it.
+
+#### How It Works
+
+1. User clicks park slot (e.g., `700`)
+2. Widget sends valet park request to backend API
+3. Backend uses FreeSWITCH ESL to park call (no SIP REFER)
+4. Server responds with success
+5. Widget ends local session (call now owned by server)
+6. Widget polls backend API to sync park slot occupancy
+7. Other users see parked call and can retrieve by dialing park extension
+
+#### Configuration
+
+**HTML Attributes:**
+
+```html
+<convirza-dialer
+	api-url="https://stag-5-dialer-apis.convirza.com"
+	auth-token="Bearer xyz"
+	park-poll-interval="5000"
+></convirza-dialer>
+```
+
+- `api-url`: Base API URL — park endpoint is `{api-url}/v3/park-slots`
+- `auth-token`: JWT or API key for backend auth
+- `park-poll-interval`: Poll interval in ms (default: 5000)
+
+#### Backend API
+
+**Required endpoint:**
+
+```
+GET /v3/park-slots?domain={sipDomain}
+Returns: [
+  {
+    extension: "700",
+    label: "Park 1",
+    occupied: true,
+    parkedCall: {
+      phoneNumber: "+12485794891",
+      parkedBy: "1001",
+      parkedAt: 1719234567890
+    }
+  },
+  ...
+]
+
+POST /v3/park-call
+Body: { extension: "700", callUuid: "abc-123", sipDomain: "pbx.example.com" }
+Returns: { success: true }
+```
+
+#### Events
+
+**`call-parked`** — fired when park succeeds
+
+```js
+element.addEventListener('call-parked', (e) => {
+	// e.detail: { parkExtension, phoneNumber, parkedBy }
+});
+```
+
+**`park-slots-updated`** — fired on successful API fetch
+
+```js
+element.addEventListener('park-slots-updated', (e) => {
+	// e.detail: { slots: ParkAccount[] }
+});
+```
+
+**`call-park-failed`** — fired if park fails
+
+```js
+element.addEventListener('call-park-failed', (e) => {
+	// e.detail: { error: string }
+});
+```
+
+### Call History Persistence
+
+Call history is saved to **two tiers**:
+
+1. **IndexedDB** (local cache) — instant load, offline support
+2. **Backend API** (source of truth) — multi-device sync, compliance
+
+Widget saves to IndexedDB immediately (non-blocking), then syncs to backend async.
+
+#### Data Flow
+
+**On call end:**
+
+1. Widget generates UUID `callId`
+2. Saves to IndexedDB (instant)
+3. POSTs to `/api/call-history` (async, retries on failure)
+4. Reloads history from IndexedDB to update UI
+
+**On SIP registration:**
+
+1. Initialize `CallHistoryService`
+2. Load from IndexedDB (fast)
+3. Background-sync from backend (replaces IndexedDB cache)
+
+**On page reload:**
+
+- IndexedDB persists → history visible immediately
+- Backend sync refreshes on reconnect
+
+#### Configuration
+
+**HTML Attributes:**
+
+```html
+<convirza-dialer api-url="https://api.example.com" auth-token="Bearer xyz"></convirza-dialer>
+```
+
+- `api-url`: Base API URL — history endpoint = `{api-url}/api/call-history`
+- `auth-token`: JWT or API key for backend auth
+
+**If `api-url` not set:**
+
+- IndexedDB-only mode (no backend sync)
+- History persists locally but not across devices
+
+#### Backend API
+
+**Required endpoints:**
+
+```
+GET  /api/call-history?userId={id}&sipDomain={domain}&limit=100&offset=0
+POST /api/call-history
+PATCH /api/call-history/{callId}
+```
+
+**Database schema (PostgreSQL):**
+
+```sql
+CREATE TABLE call_history (
+  id BIGSERIAL PRIMARY KEY,
+  call_id VARCHAR(100) UNIQUE NOT NULL,
+  user_id VARCHAR(50) NOT NULL,
+  sip_domain VARCHAR(100) NOT NULL,
+  phone_number VARCHAR(50) NOT NULL,
+  direction VARCHAR(10) NOT NULL CHECK (direction IN ('inbound', 'outbound')),
+  status VARCHAR(20) NOT NULL CHECK (status IN ('answered', 'missed', 'rejected', 'failed')),
+  started_at TIMESTAMPTZ NOT NULL,
+  ended_at TIMESTAMPTZ,
+  duration_seconds INTEGER DEFAULT 0,
+  recording_url VARCHAR(500),
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  INDEX idx_user_domain_started (user_id, sip_domain, started_at DESC),
+  INDEX idx_call_id (call_id)
+);
+```
+
+See `docs/CALL_HISTORY_API.md` for full spec, Node.js examples, security notes.
+
+#### Events
+
+**`history-updated`** — fired when history changes
+
+```js
+element.addEventListener('history-updated', (e) => {
+	// e.detail: { history: CallHistoryItem[] }
+});
+```
+
+### Audio Device Management
+
+Microphone and speaker selection with hot-swapping during calls.
+
+#### Usage
+
+```js
+const devices = await sip.getAudioDevices();
+// { microphones: [...], speakers: [...] }
+
+// Set device
+await sip.setMicrophone(deviceId);
+await sip.setSpeaker(deviceId);
+
+// Preferences saved to localStorage: convirza_audio_preferences
+```
+
+**Browser support:**
+
+- Microphone switching: Chrome, Firefox, Safari, Edge
+- Speaker switching (`setSinkId`): Chrome, Edge only (silently no-ops in Firefox/Safari)
+
+### Call Quality Monitoring
+
+Polls `RTCPeerConnection.getStats()` every 2s and emits quality metrics.
+
+**Metrics:**
+
+- **Bitrate** (kbps)
+- **Packet loss** (%)
+- **Jitter** (ms)
+- **Latency** (ms, round-trip)
+- **Audio level** (0–1)
+- **Quality** (`excellent` | `good` | `fair` | `poor`)
+
+**Usage:**
+
+```js
+const sip = new SipAdapter(config, {
+	onQualityChange: (metrics) => {
+		if (metrics.quality === 'poor') {
+			console.warn('Poor call quality:', metrics);
+		}
+	},
+});
+
+// Or poll manually
+const metrics = sip.getCallQuality();
+console.log('Packet loss:', metrics.packetLoss + '%');
+```
+
+### Theming
+
+#### HTML Attributes (static)
+
+```html
+<convirza-dialer
+	theme="dark"
+	primary-color="#6366f1"
+	accent-color="#22c55e"
+	brand-name="Convirza"
+	brand-logo="https://..."
+></convirza-dialer>
+```
+
+#### JavaScript `setTheme()` (dynamic)
+
+```js
+element.setTheme({
+	theme: 'dark',
+	primaryColor: '#6366f1',
+	accentColor: '#10b981',
+	brandName: 'Acme Corp',
+});
+```
+
+#### Direct `setAttribute()`
+
+```js
+element.setAttribute('primary-color', '#6366f1');
+```
+
+CSS vars injected at runtime via `style.setProperty('--primary-color', ...)`.
+
+---
+
+## Types
+
+```ts
+// Widget position
+type WidgetPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+// Call lifecycle state
+type CallStatus = 'idle' | 'dialing' | 'ringing' | 'connected' | 'ended' | 'error';
+
+// Widget open/closed state
+type WidgetState = 'collapsed' | 'expanded';
+
+// UI theme
+type ThemeMode = 'light' | 'dark';
+
+// Call direction and outcome
+type CallDirection = 'inbound' | 'outbound';
+type CallDisposition = 'answered' | 'missed' | 'rejected' | 'failed';
+
+// Events emitted by ConvirzaDialer class
+interface DialerEvents {
+	onOpen?: () => void;
+	onClose?: () => void;
+	onCallStarted?: (phoneNumber: string) => void;
+	onCallEnded?: (phoneNumber: string, duration: number) => void;
+	onStateChange?: (oldState: CallStatus, newState: CallStatus, metadata?: CallMetadata) => void;
+}
+
+// Returned by placeCall()
+interface CallSession {
+	phoneNumber: string;
+	status: CallStatus;
+	duration: number;
+	onAnswered(callback: () => void): void;
+	onEnded(callback: (duration: number) => void): void;
+	end(): void;
+}
+```
+
+---
+
+## Browser Support
+
+Requires a browser with WebRTC (`RTCPeerConnection`) and WebSocket support.
+
+- **Chrome** 74+
+- **Firefox** 69+
+- **Safari** 14.1+
+- **Edge** 79+
+
+**Feature availability:**
+
+- **Speaker selection** (`setSinkId`): Chrome/Edge only
+- **Microphone hot-swap**: All browsers
+- **WebRTC stats**: All browsers
+
+---
+
+## Project Structure
+
+```
+convirza-dialer-1/
+├── packages/web-sdk/
+│   ├── src/              # Source code (TypeScript)
+│   │   ├── ui/           # Web component
+│   │   ├── sip/          # SIP adapter
+│   │   ├── api/          # REST clients
+│   │   ├── media/        # Audio device management
+│   │   ├── constants/    # Configuration
+│   │   └── types/        # TypeScript types
+│   ├── test/             # Unit tests
+│   ├── dist/             # Built output (published)
+│   │   ├── index.esm.js  # ES modules
+│   │   ├── index.cjs.js  # CommonJS
+│   │   ├── index.umd.js  # UMD (browser)
+│   │   └── types/        # TypeScript declarations
+│   └── package.json      # Package metadata
+└── demo/                 # Demo files (root level, not published)
+    ├── demo.html         # Interactive demo
+    ├── sip.bundle.js     # Bundled SIP.js
+    └── README.md         # Demo instructions
+```
+
+**For development:** Work in `src/` directory.  
+**For users:** Import from `dist/` (handled automatically by package.json).
+
+## License
+
+PROPRIETARY — Copyright Convirza. All rights reserved.