@cemscale-voip/voip-sdk 2.0.11 → 2.0.12

package/dist/client.js

@@ -45,7 +45,35 @@ export class VoIPClient {
     setApiKey(apiKey) { this.apiKey = apiKey; }
     /** Get the current API key */
     getApiKey() { return this.apiKey; }
-    /** Set JWT token (only for browser login flows — most apps should use apiKey) */
+    /**
+     * Set JWT token manually (only for browser login flows — most apps should use apiKey).
+     *
+     * @description
+     * Restores a previously-obtained JWT token into the client so all subsequent API calls
+     * use Bearer authentication. Use this to rehydrate a session after a page reload:
+     * get the token from localStorage/sessionStorage and call `voip.setToken(token)`.
+     *
+     * @param token — The JWT token string from a prior `login()`, `adminLogin()`, or `superadminLogin()` call.
+     *
+     * @example
+     * ```typescript
+     * // Page reload: restore token from localStorage
+     * const savedToken = localStorage.getItem('voip-token');
+     * if (savedToken) {
+     *   voip.setToken(savedToken);
+     *   // Verify it's still valid
+     *   try {
+     *     const { user } = await voip.me();
+     *     console.log('Session restored:', user.displayName);
+     *   } catch {
+     *     // Token expired — redirect to login
+     *     localStorage.removeItem('voip-token');
+     *   }
+     * }
+     * ```
+     *
+     * @see login, adminLogin, superadminLogin
+     */
     setToken(token) { this.token = token; }
     /** Get current JWT token */
     getToken() { return this.token; }
@@ -133,14 +161,103 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Auth
     // -------------------------------------------------------------------
-    /** Login as an extension user */
+    /**
+     * Log in as an extension user with username, password, and tenant ID.
+     *
+     * @description
+     * Authenticates a PBX extension user (e.g. 1001, 1002) and returns a JWT token.
+     * The token is automatically stored in the client instance for subsequent requests.
+     * This is the login flow for softphone users, desk phone users, and CRM integrations
+     * that authenticate as a specific extension rather than as a tenant admin.
+     *
+     * After successful login, the client:
+     * - Stores the JWT token for all future API calls
+     * - Sets the tenant ID from the `tenantId` parameter
+     *
+     * For admin login, use `adminLogin()`. For platform superadmin, use `superadminLogin()`.
+     *
+     * @param params — Login parameters
+     * @param params.username — The extension number (e.g. `'1001'` or `'2002'`)
+     * @param params.password — The extension's SIP password
+     * @param params.tenantId — The UUID of the tenant this extension belongs to
+     *
+     * @returns An object containing:
+     *   - `token: string` — JWT token (also stored internally in the client)
+     *   - `user?: object` — User info including `id`, `extension`, `displayName`, `tenantId`
+     *
+     * @throws {HttpError} 401 — Invalid credentials (wrong username, password, or tenant)
+     *
+     * @example
+     * ```typescript
+     * const voip = new VoIPClient({ apiUrl: 'https://voip-api.cemscale.com' });
+     *
+     * const { token, user } = await voip.login({
+     *   username: '1001',
+     *   password: 'sip-password-here',
+     *   tenantId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
+     * });
+     *
+     * console.log(`Logged in as ${user?.displayName} (${user?.extension})`);
+     * ```
+     *
+     * @see POST /api/auth/login
+     */
     async login(params) {
         const result = await this.request('POST', '/api/auth/login', params);
         this.token = result.token;
         this.tenantId = params.tenantId;
         return result;
     }
-    /** Login as a tenant admin */
+    /**
+     * Log in as a tenant administrator with email and password.
+     *
+     * @description
+     * Authenticates a tenant admin user and returns a JWT token. The admin role has
+     * full CRUD access to all resources within their tenant: extensions, DIDs, IVR menus,
+     * ring groups, queues, webhooks, schedules, blocklist, recordings, voicemails, and reports.
+     *
+     * After successful login, the client:
+     * - Stores the JWT token for all future API calls
+     * - Automatically sets the tenant ID from the response (the admin's own tenant)
+     *
+     * Use this for dashboard/admin panel logins. For extension-level (softphone) login,
+     * use `login()`. For cross-tenant superadmin access, use `superadminLogin()`.
+     *
+     * **CRM UI guidance:** Store the returned token in localStorage/sessionStorage and
+     * rehydrate it on page load via `setToken(token)`. Redirect to the dashboard
+     * after successful login. Show a "Forgot password?" link and rate-limit the login
+     * button to prevent brute-force attempts (the API enforces rate limiting server-side).
+     *
+     * @param params — Login parameters
+     * @param params.email — The admin's email address
+     * @param params.password — The admin's password
+     *
+     * @returns An object containing:
+     *   - `token: string` — JWT token (also stored internally in the client)
+     *   - `user?: object` — User info including `id`, `extension`, `displayName`, `tenantId`
+     *   - `tenant?: object` — Tenant info including `id`, `subdomain`, `companyName`
+     *
+     * @throws {HttpError} 401 — Invalid credentials (wrong email or password)
+     * @throws {HttpError} 403 — Account is disabled or suspended
+     *
+     * @example
+     * ```typescript
+     * const voip = new VoIPClient({ apiUrl: 'https://voip-api.cemscale.com' });
+     *
+     * const { token, user, tenant } = await voip.adminLogin({
+     *   email: 'admin@acmecorp.com',
+     *   password: 'secure-password',
+     * });
+     *
+     * console.log(`Logged in to ${tenant?.companyName} as ${user?.displayName}`);
+     *
+     * // CRM UI: store token for page reloads
+     * localStorage.setItem('voip-token', token);
+     * localStorage.setItem('voip-tenant', JSON.stringify(tenant));
+     * ```
+     *
+     * @see POST /api/auth/admin-login
+     */
     async adminLogin(params) {
         const result = await this.request('POST', '/api/auth/admin-login', params);
         this.token = result.token;
@@ -148,7 +265,61 @@ export class VoIPClient {
             this.tenantId = result.tenant.id;
         return result;
     }
-    /** Login as platform superadmin */
+    /**
+     * Log in as a platform superadmin with email and password.
+     *
+     * @description
+     * Authenticates a platform superadmin — the highest privilege level that has access
+     * to ALL tenants and global resources. Superadmins can manage tenants, create global
+     * SIP trunks, administer API keys for any tenant, and view cross-tenant reports.
+     *
+     * Unlike `adminLogin()`, this does NOT auto-set a tenant ID because superadmins
+     * operate across all tenants. Use `setTenantId()` or the per-request `options.tenantId`
+     * parameter when acting on behalf of a specific tenant.
+     *
+     * Superadmin can also impersonate any tenant by setting the `X-Tenant-ID` header,
+     * which is passed automatically when you use `options.tenantId` on any SDK method.
+     *
+     * **CRM UI guidance:** After login, show the tenant selector dropdown so the superadmin
+     * can pick which tenant to manage. Store the selected tenant ID in state and pass it
+     * as `{ tenantId }` on every SDK call. Show "Superadmin" badge in the header.
+     *
+     * @param params — Login parameters
+     * @param params.email — The superadmin's email address
+     * @param params.password — The superadmin's password
+     *
+     * @returns An object containing:
+     *   - `token: string` — JWT token (also stored internally in the client)
+     *   - `user?: object` — User info including `id`, `extension`, `displayName`, `tenantId`
+     *   - `tenant?: object` — Tenant info (typically null for superadmin)
+     *
+     * @throws {HttpError} 401 — Invalid credentials (wrong email or password)
+     * @throws {HttpError} 403 — Account is not a superadmin
+     *
+     * @example
+     * ```typescript
+     * const voip = new VoIPClient({ apiUrl: 'https://voip-api.cemscale.com' });
+     *
+     * const { token, user } = await voip.superadminLogin({
+     *   email: 'superadmin@cemscale.com',
+     *   password: 'secure-password',
+     * });
+     *
+     * // Superadmin: list ALL tenants
+     * const { tenants } = await voip.listTenants();
+     * console.log(`Managing ${tenants.length} tenants`);
+     *
+     * // Superadmin: view calls for a specific tenant
+     * const { calls } = await voip.listCalls({ tenantId: 'a1b2c3d4-...' });
+     *
+     * // CRM UI: tenant selector
+     * tenants.forEach(t => {
+     *   renderTenantOption({ value: t.id, label: `${t.companyName} (${t.subdomain})` });
+     * });
+     * ```
+     *
+     * @see POST /api/auth/superadmin-login
+     */
     async superadminLogin(params) {
         const result = await this.request('POST', '/api/auth/superadmin-login', params);
         this.token = result.token;
@@ -158,7 +329,55 @@ export class VoIPClient {
     async me() {
         return this.request('GET', '/api/auth/me');
     }
-    /** Get TURN credentials for WebRTC */
+    /**
+     * Get TURN/STUN credentials for establishing WebRTC media connections.
+     *
+     * @description
+     * Returns time-limited TURN credentials (username, credential, TURN server URLs) used
+     * to establish peer-to-peer WebRTC media connections through the coTURN server.
+     * These credentials are auto-generated per tenant and expire after the TTL period.
+     *
+     * **When to call this:**
+     * - Before creating a `WebRTCPhone` instance — pass the credentials to the SIP.js UA config
+     * - When TURN credentials expire during a long call — re-fetch and update the ICE transport
+     * - On page load in a WebRTC-based softphone app
+     *
+     * The TTL (time-to-live) indicates how many seconds the credential is valid.
+     * Re-fetch credentials before the TTL expires if the user is on a long call.
+     *
+     * **CRM UI guidance:** Call this once when the WebRTC softphone initializes.
+     * Show a "Connecting..." spinner while fetching. If it fails, show
+     * "Unable to connect to media server — please check your network" with a Retry button.
+     *
+     * @returns An object containing:
+     *   - `urls: string[]` — Array of TURN server URLs (e.g. `['turn:3.20.219.41:3478?transport=udp']`)
+     *   - `username: string` — Time-limited TURN username
+     *   - `credential: string` — Time-limited TURN password
+     *   - `ttl: number` — Time-to-live in seconds before the credential expires
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key/token
+     * @throws {HttpError} 500 — TURN server configuration error
+     *
+     * @example
+     * ```typescript
+     * // Fetch credentials for WebRTC phone setup
+     * const { urls, username, credential, ttl } = await voip.getTurnCredentials();
+     *
+     * // Pass to WebRTCPhone or SIP.js UA
+     * const phone = new WebRTCPhone({
+     *   iceServers: [{ urls, username, credential }],
+     *   // ...
+     * });
+     *
+     * // Refresh before TTL expires on long calls
+     * setTimeout(async () => {
+     *   const newCreds = await voip.getTurnCredentials();
+     *   phone.updateIceServers([{ urls: newCreds.urls, username: newCreds.username, credential: newCreds.credential }]);
+     * }, (ttl - 30) * 1000); // Refresh 30s before expiry
+     * ```
+     *
+     * @see GET /api/auth/turn-credentials
+     */
     async getTurnCredentials() {
         return this.request('GET', '/api/auth/turn-credentials');
     }
@@ -179,27 +398,77 @@ export class VoIPClient {
     //   See the CallRecord type JSDoc for the full playback guide.
     // -------------------------------------------------------------------
     /**
-     * List call records (CDR) with pagination and filters.
+     * List historical call records (CDR — Call Detail Records) with pagination, filtering, and search.
+     *
+     * @description
+     * Retrieves a paginated list of completed/missed/failed call records for the current tenant.
+     * Think of this as your "call history" table — every call that went through the phone system
+     * appears here, with caller ID, destination, duration, status, and optional recording URLs.
+     *
+     * **Recording playback:** Each call with a recording includes `cdn_url` (CloudFront, instant
+     * playback, no auth required) and `audio_url` (API fallback, requires auth). The `cdn_url`
+     * is a permanent URL cached at 400+ global edge locations — you can store it in your database,
+     * send it in emails, or embed it in `<audio>` tags directly.
+     *
+     * **Superadmin mode:** When using a global superadmin API key, calls from ALL tenants are
+     * returned. Each call includes `company_name` and `subdomain` fields for tenant identification.
      *
-     * Each call with a recording includes `cdn_url` (CloudFront, instant playback)
-     * and `audio_url` (API fallback). Always prefer `cdn_url` when non-null.
+     * @param params — Optional filters and pagination
+     * @param params.page — Page number (1-based, default 1)
+     * @param params.limit — Records per page (max 500, default 50). Example: `50`
+     * @param params.direction — Filter by call direction. `'inbound'` = someone called you,
+     *   `'outbound'` = you called someone, `'internal'` = extension-to-extension, `'all'` = everything
+     * @param params.status — Filter by call outcome. `'completed'` = answered, `'failed'` = error,
+     *   `'missed'` = no answer, `'voicemail'` = went to voicemail
+     * @param params.dateFrom — ISO date string: only calls on or after this date. Example: `'2026-04-01'`
+     * @param params.dateTo — ISO date string: only calls on or before this date. Example: `'2026-04-30'`
+     * @param params.extension — Filter by extension number (matches caller or destination). Example: `'1001'`
+     * @param params.number — Search by phone number or name (partial match, case-insensitive). Example: `'+1555123'`
+     * @param params.forwarded — `'true'` = only forwarded calls, `'false'` = only non-forwarded
+     * @param params.forwardedTo — Search by the external number a call was forwarded to. Example: `'+1555999'`
+     * @param params.tenantId — Filter by tenant (superadmin only, alternative to X-Tenant-ID header)
+     *
+     * @returns An object containing:
+     *   - `calls: CallRecord[]` — Array of call records. Each record has `id`, `call_uuid`,
+     *     `direction`, `caller_id_number`, `caller_id_name`, `destination`, `status`,
+     *     `duration_seconds`, `billsec` (billed seconds), `forwarded_to`, `was_voicemail`,
+     *     `cdn_url` (CloudFront recording URL, no auth), `audio_url` (API fallback),
+     *     `started_at`, `answered_at`, `ended_at`, and optional `company_name`/`subdomain` (superadmin).
+     *   - `pagination: PaginationInfo` — `{ page, limit, total, pages }`. Use `total` for
+     *     "Showing 1-50 of 342 calls" and `pages` for page navigation.
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 403 — API key doesn't have access to the tenant
      *
      * @example
      * ```typescript
+     * // Basic list — show last 50 calls
+     * const { calls, pagination } = await voip.listCalls({ limit: 50 });
+     *
+     * // Filtered list — all inbound answered calls this month
      * const { calls, pagination } = await voip.listCalls({
      *   direction: 'inbound',
      *   status: 'completed',
-     *   dateFrom: '2026-04-01',
-     *   limit: 50,
+     *   dateFrom: '2026-06-01',
+     *   dateTo: '2026-06-30',
+     *   limit: 100,
      * });
      *
+     * // CRM UI: build a call history table
+     * const formatDuration = (s: number | null) => s ? `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}` : '—';
      * calls.forEach(call => {
-     *   console.log(`${call.caller_id_number} -> ${call.destination}`);
-     *   if (call.cdn_url) {
-     *     console.log(`  Recording: ${call.cdn_url}`); // instant CDN playback
-     *   }
+     *   const recordingSrc = call.cdn_url ?? voip.buildUrl(`/api/recordings/${call.id}/audio`);
+     *   console.log(`${call.started_at} | ${call.direction} | ${call.caller_id_number} → ${call.destination} | ${formatDuration(call.billsec)} | ${recordingSrc ? '🔊' : '—'}`);
      * });
+     *
+     * // Pagination — page through all results
+     * for (let page = 1; page <= pagination.pages; page++) {
+     *   const { calls } = await voip.listCalls({ page, limit: 50 });
+     *   // render each page
+     * }
      * ```
+     *
+     * @see GET /api/calls
      */
     async listCalls(params) {
         return this.request('GET', '/api/calls', undefined, params);
@@ -224,45 +493,322 @@ export class VoIPClient {
     async getCall(id) {
         return this.request('GET', `/api/calls/${id}`);
     }
-    /** Originate a call via FreeSWITCH. Pass `options.tenantId` when using a global superadmin key. */
+    /**
+     * Start a new outbound phone call from an extension to any destination number.
+     *
+     * @description
+     * Tells the phone system to dial an external or internal number FROM a specific extension.
+     * The extension's physical phone (desk phone, softphone, or WebRTC phone) will ring first,
+     * and when answered, the system connects it to the destination.
+     *
+     * This is the primary way to make outbound calls programmatically — also known as
+     * "click-to-call." The CRM clicks a phone number, the user's phone rings, they pick up,
+     * and the system dials the customer.
+     *
+     * **Superadmin mode:** Pass `{ tenantId: 'uuid-here' }` as the `options` parameter when
+     * using a global superadmin API key to originate calls on behalf of a specific tenant.
+     *
+     * @param params — Call parameters
+     * @param params.fromExtension — The extension number making the call. This extension's
+     *   phone will ring first. Example: `'1001'`
+     * @param params.toNumber — The destination phone number in E.164 format (+country code +
+     *   number) or an internal extension number. Examples: `'+17865551234'` (PSTN), `'1002'` (internal)
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only).
+     *   Example: `'a1b2c3d4-...'`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Human-readable confirmation (e.g. "Call originated successfully")
+     *   - `callUuid: string` — The FreeSWITCH call UUID for tracking. Use this to monitor the
+     *     call via WebSocket events (`call.answered`, `call.end`) and to call `hangup()`,
+     *     `transfer()`, `holdCall()`, or `parkCall()`
+     *
+     * @throws {HttpError} 400 — `fromExtension` doesn't exist, `toNumber` is invalid, or extension is disabled
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH connection failed or originate error
+     *
+     * @example
+     * ```typescript
+     * // Click-to-call from extension 1001 to customer +17865551234
+     * const { callUuid, message } = await voip.originate({
+     *   fromExtension: '1001',
+     *   toNumber: '+17865551234',
+     * });
+     * console.log(message); // "Call originated successfully"
+     * console.log(`Tracking UUID: ${callUuid}`);
+     *
+     * // CRM UI: Click a phone number in the contact card
+     * async function handleClickToCall(extension: string, customerPhone: string) {
+     *   try {
+     *     const { callUuid } = await voip.originate({
+     *       fromExtension: extension,
+     *       toNumber: customerPhone,
+     *     });
+     *     // Show "Dialing..." state in the UI
+     *     // Listen for WebSocket 'call_start' event to confirm the call connected
+     *     showCallBanner(callUuid, customerPhone, 'dialing');
+     *   } catch (err) {
+     *     if (err instanceof HttpError && err.status === 400) {
+     *       showError('Invalid phone number — please check the format');
+     *     }
+     *   }
+     * }
+     *
+     * // Superadmin: originate for a specific tenant
+     * const { callUuid } = await voip.originate(
+     *   { fromExtension: '1001', toNumber: '+17865551234' },
+     *   { tenantId: 'a1b2c3d4-...' },
+     * );
+     * ```
+     *
+     * @see POST /api/calls/originate
+     */
     async originate(params, options) {
         return this.request('POST', '/api/calls/originate', params, undefined, options);
     }
-    /** Hang up an active call */
+    /**
+     * End (hang up) an active call immediately.
+     *
+     * @description
+     * Terminates an in-progress call identified by its FreeSWITCH channel UUID.
+     * This is the server-side equivalent of physically hanging up the phone — both parties
+     * are disconnected. Works on any active call: WebRTC, desk phone, PSTN, or conference leg.
+     *
+     * After calling this, expect a `call_end` WebSocket event confirming the call terminated.
+     *
+     * @param uuid — The FreeSWITCH channel UUID of the active call to hang up.
+     *   You get this from:
+     *   - `originate()` → `callUuid`
+     *   - `getActiveCalls()` → `activeCalls[].uuid`
+     *   - `getParkedCalls()` → `parkedCalls[].uuid`
+     *   - WebSocket `call_start` event → `call.uuid`
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. "Call hung up successfully")
+     *
+     * @throws {HttpError} 400 — The call UUID is not found or the call is already terminated
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH communication error
+     *
+     * @example
+     * ```typescript
+     * // Hang up the call that was just originated
+     * const { callUuid } = await voip.originate({
+     *   fromExtension: '1001',
+     *   toNumber: '+17865551234',
+     * });
+     *
+     * // ... later, when the user clicks "End Call" in the UI
+     * await voip.hangup(callUuid);
+     *
+     * // CRM UI: End Call button
+     * async function handleEndCall(callUuid: string) {
+     *   await voip.hangup(callUuid);
+     *   hideCallBanner();
+     *   showNotification('Call ended');
+     * }
+     *
+     * // Hang up from getActiveCalls
+     * const { activeCalls } = await voip.getActiveCalls();
+     * const currentCall = activeCalls.find(c => c.caller_id_number === '+17865551234');
+     * if (currentCall) {
+     *   await voip.hangup(currentCall.uuid);
+     * }
+     * ```
+     *
+     * @see POST /api/calls/{uuid}/hangup
+     */
     async hangup(uuid) {
         return this.request('POST', `/api/calls/${uuid}/hangup`);
     }
-    /** Transfer an active call (blind or attended) */
+    /**
+     * Transfer an active call to another extension.
+     *
+     * @description
+     * Moves an in-progress call from one extension to another. Two transfer modes:
+     *
+     * - **Blind transfer** (`type: 'blind'`, default): Immediately transfers the caller
+     *   to the target extension without consulting the target first. The original extension
+     *   is disconnected. Use this for "I'll transfer you now" — the caller hears hold music
+     *   until the target picks up.
+     *
+     * - **Attended transfer** (`type: 'attended'`): The original extension calls the target
+     *   first, talks to them ("I have Mr. Smith on the line about his invoice"), and then
+     *   the call is connected. Requires a two-step UI flow with `addCallParticipant()`
+     *   and `mergeCalls()` for the full attended transfer sequence.
+     *
+     * @param uuid — The FreeSWITCH channel UUID of the active call to transfer.
+     *   Get this from `originate()` → `callUuid` or `getActiveCalls()`.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param params — Transfer parameters
+     * @param params.targetExtension — The extension to transfer the call TO.
+     *   This is the recipient — the person who will receive the call.
+     *   Example: `'1002'` (extension), `'+17865551234'` (external number)
+     * @param params.type — Transfer type: `'blind'` (default, immediate) or `'attended'`
+     *   (talk to target first, then connect). Example: `'blind'`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. "Call transferred successfully")
+     *
+     * @throws {HttpError} 400 — Call UUID not found, target extension doesn't exist, or target is the same as caller
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH communication error
+     *
+     * @example
+     * ```typescript
+     * // Blind transfer — send the caller directly to extension 1002
+     * const { callUuid } = await voip.originate({
+     *   fromExtension: '1001',
+     *   toNumber: '+17865551234',
+     * });
+     * await voip.transfer(callUuid, { targetExtension: '1002', type: 'blind' });
+     *
+     * // CRM UI: Transfer button with extension picker
+     * async function handleTransfer(callUuid: string, targetExt: string) {
+     *   await voip.transfer(callUuid, { targetExtension: targetExt, type: 'blind' });
+     *   showNotification(`Call transferred to ${targetExt}`);
+     *   hideCallBanner();
+     * }
+     *
+     * // Blind transfer to an external number
+     * await voip.transfer(callUuid, { targetExtension: '+17865559999', type: 'blind' });
+     * ```
+     *
+     * @see POST /api/calls/{uuid}/transfer
+     */
     async transfer(uuid, params) {
         return this.request('POST', `/api/calls/${uuid}/transfer`, params);
     }
-    /** List active calls from FreeSWITCH */
+    /**
+     * Get all currently active (in-progress) calls in the phone system.
+     *
+     * @description
+     * Queries FreeSWITCH for every live call channel — calls that are ringing, connected,
+     * on hold, or in a conference. This is the real-time snapshot of what's happening
+     * on your phone system RIGHT NOW. Unlike `listCalls()` which shows historical CDRs,
+     * this shows only live calls.
+     *
+     * **CRM usage:** Build a "Live Calls" dashboard panel or operator console showing
+     * all active conversations. Poll this every 3-5 seconds for a near-real-time view,
+     * or use WebSocket events for true real-time updates.
+     *
+     * Each ActiveCall includes:
+     * - `uuid` — FreeSWITCH channel UUID. Required for `hangup()`, `transfer()`,
+     *   `holdCall()`, `parkCall()`, and three-way operations
+     * - `call_uuid` — The unique call identifier (shared across both legs of the same call)
+     * - `caller_id_number` / `caller_id_name` — Who's calling
+     * - `destination` — Who's being called
+     * - `direction` — `'inbound'` (someone called you) or `'outbound'` (you called them)
+     * - `status` — Channel state: `'active'`, `'ringing'`, `'held'`
+     * - `answered` — `true` if the call was picked up, `false` if still ringing
+     * - `on_hold` — `true` if the call is currently on hold
+     * - `started_at` — When the call started (ISO timestamp)
+     *
+     * @returns An object containing:
+     *   - `activeCalls: ActiveCall[]` — Array of live calls. Empty array `[]` if no calls are active.
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH connection error
+     *
+     * @example
+     * ```typescript
+     * // Build a live calls panel
+     * const { activeCalls } = await voip.getActiveCalls();
+     *
+     * // Show in a table
+     * activeCalls.forEach(call => {
+     *   const status = call.answered ? (call.on_hold ? '⏸ On Hold' : '🗣 Active') : '📞 Ringing';
+     *   console.log(`${status} | ${call.caller_id_number} → ${call.destination} | ${call.uuid}`);
+     * });
+     *
+     * // CRM UI: Live Calls widget — poll every 5 seconds
+     * setInterval(async () => {
+     *   const { activeCalls } = await voip.getActiveCalls();
+     *   updateLiveCallsTable(activeCalls);
+     * }, 5000);
+     *
+     * // CRM UI: Show/hide logic
+     * if (activeCalls.length === 0) {
+     *   showEmptyState('No active calls right now');
+     * } else {
+     *   const activeCount = activeCalls.filter(c => c.answered && !c.on_hold).length;
+     *   const ringingCount = activeCalls.filter(c => !c.answered).length;
+     *   showStats(`${activeCount} active, ${ringingCount} ringing`);
+     * }
+     *
+     * // Find a specific call by phone number
+     * const customerCall = activeCalls.find(c => c.caller_id_number === '+17865551234');
+     * if (customerCall) {
+     *   // Show call controls: Hang Up, Transfer, Hold
+     *   showCallControls(customerCall.uuid);
+     * }
+     * ```
+     *
+     * @see GET /api/calls/active
+     */
     async getActiveCalls() {
         return this.request('GET', '/api/calls/active');
     }
     /**
-     * Resolve a call's FreeSWITCH channel UUID from the current active calls.
+     * Look up the FreeSWITCH channel UUID for a specific call by matching extension + remote number.
+     *
+     * @description
+     * When building three-way calling features, you need FreeSWITCH channel UUIDs — not the
+     * local SIP.js session IDs that the SDK's WebRTC phone uses internally. This helper
+     * searches the active calls list and returns the matching FS UUID.
      *
-     * This is required for three-way calling operations — the SDK's WebRTC phone
-     * uses local SIP.js session IDs internally, but the server needs FreeSWITCH
-     * channel UUIDs for `addCallParticipant`, `mergeCalls`, and `mergeDirectCalls`.
+     * This is a **client-side convenience method** — it calls `getActiveCalls()` under the hood
+     * and does a fuzzy match on caller/destination numbers. It's best used in WebRTC-based
+     * applications where you have the extension number and the remote party's number but
+     * don't have the FreeSWITCH UUID.
      *
-     * **CRM developers:** you can use this function to map your SIP.js session IDs
-     * to server-side UUIDs when building custom three-way UIs.
+     * **Important:** This method only works for calls that are currently active in FreeSWITCH.
+     * It returns `null` if the call isn't found (e.g. the call already ended, or the numbers
+     * don't match any active channel).
      *
-     * @param extension - The user's extension number (e.g., "1001")
-     * @param remoteNumber - The remote party's phone number or extension
-     * @param direction - 'inbound' or 'outbound'
-     * @returns The FreeSWITCH channel UUID, or `null` if not found
+     * @param extension — The user's extension number. This is the LOCAL party — the one
+     *   registered in your phone system. Example: `'1001'`
+     * @param remoteNumber — The remote party's phone number or extension. This is the OTHER
+     *   party in the call. Example: `'+17865551234'` (external) or `'1002'` (internal)
+     * @param direction — The direction of the call relative to your system:
+     *   - `'outbound'`: the extension called the remote number (extension is caller_id_number)
+     *   - `'inbound'`: the remote number called the extension (extension is destination)
+     *
+     * @returns The FreeSWITCH channel UUID (e.g. `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`)
+     *   or `null` if no matching active call was found.
      *
      * @example
      * ```typescript
-     * // After a call connects, resolve the FS UUID for three-way operations
-     * const fsUuid = await voip.resolveCallFsUuid('1001', '+15551234567', 'outbound');
+     * // After originating a call, look up its FS UUID for three-way operations
+     * const { callUuid } = await voip.originate({
+     *   fromExtension: '1001',
+     *   toNumber: '+17865551234',
+     * });
+     *
+     * // Wait for the call to connect, then:
+     * const fsUuid = await voip.resolveCallFsUuid('1001', '+17865551234', 'outbound');
      * if (fsUuid) {
-     *   await voip.addCallParticipant(fsUuid, { toNumber: '+15559999999' });
+     *   // Now we can add a third party
+     *   const { newCallUuid } = await voip.addCallParticipant(fsUuid, { toNumber: '+17865559999' });
+     *   // ... wait for B to answer, then merge
+     *   await voip.mergeCalls({ callUuidA: fsUuid, callUuidB: newCallUuid });
+     * }
+     *
+     * // CRM UI: Three-way call button
+     * async function startThreeWay(extension: string, customerPhone: string, thirdParty: string) {
+     *   const fsUuid = await voip.resolveCallFsUuid(extension, customerPhone, 'outbound');
+     *   if (!fsUuid) {
+     *     showError('Call not found — it may have ended');
+     *     return;
+     *   }
+     *   const { newCallUuid } = await voip.addCallParticipant(fsUuid, { toNumber: thirdParty });
+     *   showNotification(`Dialing ${thirdParty}...`);
+     *   // Listen for WebSocket 'call_start' event on newCallUuid, then auto-merge
      * }
      * ```
+     *
+     * @see GET /api/calls/active (used internally)
      */
     async resolveCallFsUuid(extension, remoteNumber, direction) {
         try {
@@ -291,15 +837,173 @@ export class VoIPClient {
             return null;
         }
     }
-    /** Get call statistics for a period */
+    /**
+     * Get aggregate call statistics for a time period.
+     *
+     * @description
+     * Returns total call counts broken down by direction (inbound, outbound, internal)
+     * for the specified period. Use this for dashboard KPI cards showing "Calls Today",
+     * "Calls This Week", "Calls This Month", etc.
+     *
+     * **CRM UI guidance:** Display the stats as KPI cards at the top of the dashboard:
+     * - "Total Calls: 342" (large number, counts don't change often)
+     * - "Inbound: 210 | Outbound: 98 | Internal: 34" (breakdown rows)
+     * - Show a period selector: Today | 7 Days | 30 Days | 90 Days
+     * - Refresh every 60 seconds or on manual "Refresh" button click
+     * - Show a loading skeleton while fetching
+     *
+     * @param period — The time window for statistics:
+     *   - `'today'` — Since midnight today
+     *   - `'7d'` — Last 7 days (default if omitted)
+     *   - `'30d'` — Last 30 days
+     *   - `'90d'` — Last 90 days
+     *
+     * @returns An object containing:
+     *   - `stats: object` — `{ total, inbound, outbound, internal, period }`
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Get today's stats for the dashboard
+     * const { stats } = await voip.getCallStats('today');
+     *
+     * // Render KPI cards
+     * console.log(`${stats.total} calls today`);
+     * console.log(`↘ ${stats.inbound} inbound  |  ↗ ${stats.outbound} outbound  |  ↔ ${stats.internal} internal`);
+     *
+     * // CRM UI: period selector
+     * const periods = [
+     *   { value: 'today', label: 'Today' },
+     *   { value: '7d', label: '7 Days' },
+     *   { value: '30d', label: '30 Days' },
+     *   { value: '90d', label: '90 Days' },
+     * ];
+     * // <select onChange={e => fetchStats(e.target.value)}>
+     * ```
+     *
+     * @see GET /api/calls/stats
+     */
     async getCallStats(period) {
         return this.request('GET', '/api/calls/stats', undefined, period ? { period } : undefined);
     }
-    /** Place a call on hold or resume */
+    /**
+     * Place an active call on hold or resume it from hold.
+     *
+     * @description
+     * When you put a call on hold, the remote party hears hold music (or silence) and
+     * cannot hear anything from your end. This is useful when you need to consult with
+     * someone else, look up information, or set up a three-way call.
+     *
+     * Call `holdCall(uuid, false)` to resume the call — both parties can hear each other again.
+     * You can also use this as a toggle: `holdCall(uuid, !isCurrentlyOnHold)`.
+     *
+     * @param uuid — The FreeSWITCH channel UUID of the active call.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param hold — `true` to put the call ON hold, `false` to resume (take OFF hold).
+     *   Default is `true`. Example: `true`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation (e.g. "Call placed on hold" or "Call resumed")
+     *
+     * @throws {HttpError} 400 — Call UUID not found or call already ended
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Put a call on hold
+     * await voip.holdCall(callUuid, true);
+     *
+     * // Resume a call
+     * await voip.holdCall(callUuid, false);
+     *
+     * // CRM UI: Hold/Resume toggle button
+     * let isOnHold = false;
+     *
+     * async function toggleHold(callUuid: string) {
+     *   isOnHold = !isOnHold;
+     *   await voip.holdCall(callUuid, isOnHold);
+     *   updateHoldButton(isOnHold ? 'Resume' : 'Hold', isOnHold ? '▶' : '⏸');
+     * }
+     *
+     * // Put on hold before starting a three-way call
+     * await voip.holdCall(callUuid, true);
+     * const { newCallUuid } = await voip.addCallParticipant(callUuid, { toNumber: '+17865559999' });
+     * // ... when third party answers, merge
+     * ```
+     *
+     * @see POST /api/calls/{uuid}/hold
+     */
     async holdCall(uuid, hold = true) {
         return this.request('POST', `/api/calls/${uuid}/hold`, { hold });
     }
-    /** Park an active call */
+    /**
+     * Park an active call in a numbered parking slot so another extension can pick it up.
+     *
+     * @description
+     * Call parking is like putting a call "on hold in the cloud" — the caller hears hold
+     * music, and any extension in the tenant can retrieve the call by dialing the parking
+     * slot number. This is the telephony equivalent of "please hold while I transfer you"
+     * followed by an overhead page: "John, pick up on line 701."
+     *
+     * **How it works:**
+     * 1. Agent receives a call
+     * 2. Agent parks the call → system assigns a parking slot (e.g. `701`)
+     * 3. System announces "Call parked on 701"
+     * 4. Another agent dials `701` to pick up the call
+     *
+     * If you don't specify a slot number, the system auto-assigns the next available slot.
+     * Parked calls can be listed with `getParkedCalls()`.
+     *
+     * @param uuid — The FreeSWITCH channel UUID of the active call to park.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param slot — Optional parking slot number. If omitted, the system assigns the next
+     *   available slot (recommended). If specified, this exact slot number is used.
+     *   Example: `701`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. "Call parked in slot 701")
+     *   - `slot: string` — The parking slot number where the call is parked.
+     *     Display this prominently in the UI so agents know which slot to dial.
+     *
+     * @throws {HttpError} 400 — Call UUID not found, slot already occupied, or call already ended
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Park a call — let the system assign a slot
+     * const { slot } = await voip.parkCall(callUuid);
+     * console.log(`Call parked in slot ${slot} — tell the agent to dial ${slot}`);
+     *
+     * // Park in a specific slot
+     * const { slot } = await voip.parkCall(callUuid, 702);
+     *
+     * // CRM UI: Park Call button
+     * async function handleParkCall(callUuid: string) {
+     *   const { slot } = await voip.parkCall(callUuid);
+     *   showNotification(`Call parked on ${slot}`, 'success');
+     *   showParkedCallBanner(slot, callUuid);
+     * }
+     *
+     * // List all parked calls (e.g. for a "Parked Calls" widget)
+     * const { parkedCalls } = await voip.getParkedCalls();
+     * parkedCalls.forEach(parked => {
+     *   console.log(`Slot ${parked.slot}: ${parked.caller_id_number} → ${parked.destination}`);
+     *   // Show "Pick Up" button next to each parked call
+     * });
+     *
+     * // CRM UI: Show/hide parked calls panel
+     * const { parkedCalls } = await voip.getParkedCalls();
+     * if (parkedCalls.length === 0) {
+     *   hideParkedCallsPanel();
+     * } else {
+     *   showParkedCallsPanel(parkedCalls); // Shows slot numbers and caller info
+     * }
+     * ```
+     *
+     * @see POST /api/calls/{uuid}/park
+     * @see GET /api/calls/parked (getParkedCalls)
+     */
     async parkCall(uuid, slot) {
         return this.request('POST', `/api/calls/${uuid}/park`, slot ? { slot } : undefined);
     }
@@ -308,8 +1012,69 @@ export class VoIPClient {
      * an incoming call. When answered, audio from the target call is bridged
      * to the monitoring extension.
      *
-     * DTMF controls after answering:
-     *   1 = whisper, 2 = barge, 3 = mute, 0 = toggle mute
+     * @description
+     * Allows a supervisor or admin to silently monitor, coach, or intervene in an active
+     * call. Three modes are available:
+     *
+     * - **`listen`** (default): The supervisor hears the call audio but neither party
+     *   hears the supervisor. Useful for quality monitoring and training.
+     * - **`whisper`**: The supervisor can speak to the agent (extension) privately
+     *   without the remote party hearing. Used for real-time coaching.
+     * - **`barge`**: The supervisor enters the call — all three parties can hear each
+     *   other. Used for escalations and intervention.
+     *
+     * After the monitoring extension answers the incoming call, DTMF controls are available:
+     *   - Press `1` — whisper mode
+     *   - Press `2` — barge mode
+     *   - Press `3` — mute
+     *   - Press `0` — toggle mute
+     *
+     * **CRM UI guidance:** Show an "Eavesdrop" button on active calls (visible to admins
+     * and supervisors only). Display a mode selector (Listen / Whisper / Barge). After
+     * initiating, show "Monitoring [caller]..." with mode indicator and DTMF instructions.
+     *
+     * @param callUuid — The FreeSWITCH channel UUID of the active call to monitor.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param extension — The extension number of the monitoring supervisor.
+     *   This extension's phone will ring — when answered, monitoring begins.
+     *   Example: `'1001'`
+     * @param mode — Eavesdrop mode: `'listen'` (default, silent), `'whisper'` (coach agent),
+     *   or `'barge'` (join call). Example: `'listen'`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message
+     *   - `spyUuid: string` — The monitoring session UUID (used with `switchEavesdropMode()`)
+     *
+     * @throws {HttpError} 400 — Call UUID not found or extension is not registered
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 403 — Extension doesn't have eavesdrop permission
+     * @throws {HttpError} 500 — FreeSWITCH operation failed
+     *
+     * @example
+     * ```typescript
+     * // Silent monitoring — supervisor hears but is not heard
+     * const { spyUuid } = await voip.eavesdropCall(callUuid, '1001', 'listen');
+     *
+     * // Coach the agent privately (whisper mode)
+     * await voip.eavesdropCall(callUuid, '1001', 'whisper');
+     *
+     * // CRM UI: Supervisor panel
+     * async function startMonitoring(callUuid: string, supervisorExt: string, mode: string) {
+     *   showMonitoringBanner(`Connecting supervisor ${supervisorExt}...`);
+     *   try {
+     *     const { spyUuid } = await voip.eavesdropCall(callUuid, supervisorExt, mode);
+     *     showMonitoringActive(spyUuid, mode);
+     *     showDtmfInstructions(mode); // "Press 1 for whisper, 2 for barge"
+     *   } catch (err) {
+     *     if (err instanceof HttpError && err.status === 400) {
+     *       showError('Call not found — it may have ended');
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @see POST /api/calls/{uuid}/eavesdrop
+     * @see switchEavesdropMode (change mode during monitoring)
      */
     async eavesdropCall(callUuid, extension, mode = 'listen') {
         return this.request('POST', `/api/calls/${callUuid}/eavesdrop`, { extension, mode });
@@ -322,7 +1087,66 @@ export class VoIPClient {
     async getParkedCalls() {
         return this.request('GET', '/api/calls/parked');
     }
-    /** Export CDR as CSV. Returns raw CSV text. */
+    /**
+     * Export CDR (Call Detail Records) as CSV text.
+     *
+     * @description
+     * Generates a CSV file containing filtered call records for the specified date range.
+     * The response is raw CSV text — you need to handle downloading or displaying it.
+     * This is useful for:
+     * - "Export to CSV" buttons in the call history UI
+     * - Downloading call records for billing/invoicing
+     * - Importing into external analytics tools
+     *
+     * **CRM UI guidance:** Show an "Export CSV" button near the call history table.
+     * When clicked, filter by the current date range and download. Create a Blob from
+     * the response text and trigger a browser download via a temporary anchor element.
+     *
+     * @param params — Optional filters to narrow the export
+     * @param params.dateFrom — ISO date string: only calls on or after this date. Example: `'2026-04-01'`
+     * @param params.dateTo — ISO date string: only calls on or before this date. Example: `'2026-04-30'`
+     * @param params.direction — Filter by direction: `'inbound'`, `'outbound'`, `'internal'`, or `'all'` (default)
+     * @param params.limit — Maximum number of records to export (default: no limit)
+     *
+     * @returns Raw CSV text string with headers and call records
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Export last month's calls
+     * const csv = await voip.exportCalls({
+     *   dateFrom: '2026-05-01',
+     *   dateTo: '2026-05-31',
+     *   direction: 'outbound',
+     * });
+     *
+     * // Trigger browser download
+     * const blob = new Blob([csv], { type: 'text/csv' });
+     * const url = URL.createObjectURL(blob);
+     * const a = document.createElement('a');
+     * a.href = url;
+     * a.download = 'calls-may-2026.csv';
+     * a.click();
+     * URL.revokeObjectURL(url);
+     *
+     * // CRM UI: Export button in call history
+     * async function handleExport(dateFrom: string, dateTo: string) {
+     *   showExportingSpinner();
+     *   try {
+     *     const csv = await voip.exportCalls({ dateFrom, dateTo });
+     *     downloadFile(csv, `calls-${dateFrom}-to-${dateTo}.csv`);
+     *     showNotification('Export complete');
+     *   } catch {
+     *     showError('Export failed — please try again');
+     *   } finally {
+     *     hideExportingSpinner();
+     *   }
+     * }
+     * ```
+     *
+     * @see GET /api/calls/export
+     */
     async exportCalls(params) {
         return this.request('GET', '/api/calls/export', undefined, params);
     }
@@ -330,41 +1154,371 @@ export class VoIPClient {
     // Three-Way Calls
     // -------------------------------------------------------------------
     /**
-     * Step 1 — Hold the current call and originate a new leg to a third party.
-     * The caller should watch for a `call.answered` WebSocket event on `newCallUuid`,
-     * then call `mergeCalls()` to bring all three into a conference.
+     * Add a third participant to an existing two-party call (Step 1 of three-way calling).
      *
-     * @param callUuid  UUID of the user's active WebRTC session
-     * @param params    `{ toNumber }` for PSTN or `{ toExtension }` for internal
-     */
-    async addCallParticipant(callUuid, params, options) {
+     * @description
+     * This is the first step in setting up a three-way conference call. It:
+     * 1. Places the existing call on hold (the remote party hears hold music)
+     * 2. Originates a NEW call from you to a third party (the `toNumber` or `toExtension`)
+     * 3. Returns the new call UUID so you can track when the third party answers
+     *
+     * **Three-way call flow (3 steps):**
+     * 1. `addCallParticipant()` — Hold person A, dial person B
+     * 2. Wait for WebSocket `call_start` / `call_answer` event on `newCallUuid` (person B answers)
+     * 3. `mergeCalls()` — Join A + you + B into a conference room
+     *
+     * **CRM UI guidance:**
+     * - After calling this, show "Dialing [name/number]..." in the three-way panel
+     * - Gray out the Merge button until the WebSocket confirms person B answered
+     * - Show an inline timer ("Dialing... 10s")
+     * - If person B doesn't answer within 30s, show "No answer" and an "End" button
+     *
+     * @param callUuid — The FreeSWITCH channel UUID of YOUR leg in the active two-party call.
+     *   This is your own WebRTC/desk phone channel, NOT the remote party's channel.
+     *   Get it from `originate()` → `callUuid`, `resolveCallFsUuid()`, or `getActiveCalls()`.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param params — Who to invite into the call
+     * @param params.toNumber — An external PSTN phone number to call.
+     *   Example: `'+17865559999'`. Use this OR `toExtension`, not both.
+     * @param params.toExtension — An internal extension to add.
+     *   Example: `'1002'`. Use this OR `toNumber`, not both.
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message
+     *   - `newCallUuid: string` — The UUID of the NEW call leg (person B). Watch for
+     *     WebSocket `call_start` and `call_answer` events with this UUID to know when
+     *     person B answers. This UUID goes into `mergeCalls({ callUuidB })`.
+     *   - `originalBridgedLeg: string` — The UUID of person A's PSTN leg (the original
+     *     remote party). Pass this to `mergeCalls({ bridgedLegA })` for optimal routing.
+     *
+     * @throws {HttpError} 400 — `callUuid` not found, both `toNumber` and `toExtension` missing, or extension is disabled
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH originate failed
+     *
+     * @example
+     * ```typescript
+     * // Full three-way call flow
+     * // 1. Start the add
+     * const { newCallUuid, originalBridgedLeg } = await voip.addCallParticipant(
+     *   currentCallUuid,
+     *   { toNumber: '+17865559999' },
+     * );
+     *
+     * // 2. Listen for the WebSocket event that person B answered
+     * voip.on('call_answer', (data) => {
+     *   if (data.call_uuid === newCallUuid) {
+     *     // 3. Now merge all three parties
+     *     voip.mergeCalls({
+     *       callUuidA: currentCallUuid,
+     *       callUuidB: newCallUuid,
+     *       bridgedLegA: originalBridgedLeg,
+     *     });
+     *   }
+     * });
+     *
+     * // CRM UI: Three-way call with an internal extension
+     * async function startThreeWayWithColleague(callUuid: string, colleagueExt: string) {
+     *   showThreeWayPanel('dialing');
+     *   try {
+     *     const { newCallUuid, originalBridgedLeg } = await voip.addCallParticipant(
+     *       callUuid,
+     *       { toExtension: colleagueExt },
+     *     );
+     *     // Store these for the merge step
+     *     pendingThreeWay = { callUuidA: callUuid, callUuidB: newCallUuid, bridgedLegA: originalBridgedLeg };
+     *     showNotification(`Dialing ${colleagueExt}...`);
+     *   } catch (err) {
+     *     showError('Could not add participant — extension may be busy or offline');
+     *     hideThreeWayPanel();
+     *   }
+     * }
+     * ```
+     *
+     * @see POST /api/calls/{uuid}/add-participant
+     * @see mergeCalls (step 2 — join all three parties)
+     * @see swapCallParticipant (go private with one party)
+     */
+    async addCallParticipant(callUuid, params, options) {
         return this.request('POST', `/api/calls/${callUuid}/add-participant`, params, undefined, options);
     }
     /**
-     * Step 2 — Merge two active call legs into a FreeSWITCH conference room.
-     * All three parties (user + A + B) will hear each other.
+     * Merge two active call legs into a three-way conference room (Step 2 of three-way calling).
+     *
+     * @description
+     * After using `addCallParticipant()` to dial a third party and waiting for them to answer,
+     * call this method to join all three parties (you + person A + person B) into a single
+     * conference room. Everyone hears everyone.
+     *
+     * **Behind the scenes:** This creates a FreeSWITCH conference, moves your call leg and
+     * both remote parties into it, and returns the conference name and participant details.
+     * The conference stays alive as long as you (the moderator) are in it.
+     *
+     * **Three-way call flow (3 steps):**
+     * 1. `addCallParticipant()` — Hold A, dial B
+     * 2. Wait for person B to answer
+     * 3. `mergeCalls()` — Join everyone into a conference  ← **YOU ARE HERE**
+     *
+     * **After merging, you can:**
+     * - `swapCallParticipant()` — Talk privately with one person while the other is on hold
+     * - `kickFromConference()` — Remove someone from the call
+     * - `muteConferenceMember()` — Mute/unmute a participant
+     *
+     * **CRM UI guidance:**
+     * - After merging, show a "Conference Active" panel with all 3 participant avatars/names
+     * - Show per-participant controls: Mute, Hold (private swap), Kick
+     * - The merge button should be disabled until person B answers
+     * - If merge fails, show "Could not merge calls" and offer "End" or "Retry"
+     *
+     * @param params — Merge parameters
+     * @param params.callUuidA — Your own WebRTC/desk phone UUID (the moderator's channel).
+     *   This is the same UUID you passed to `addCallParticipant()` as `callUuid`.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param params.callUuidB — The third party's UUID, returned by `addCallParticipant()`
+     *   as `newCallUuid`. Example: `'b2c3d4e5-f6a7-8901-bcde-f12345678901'`
+     * @param params.bridgedLegA — Optional. The original remote party's PSTN leg UUID,
+     *   returned by `addCallParticipant()` as `originalBridgedLeg`. Passing this avoids
+     *   an extra server-side lookup and ensures the correct leg is used.
+     *   Example: `'c3d4e5f6-a7b8-9012-cdef-123456789012'`
+     * @param params.conferenceName — Optional custom name for the conference room.
+     *   Auto-generated if omitted (recommended). Example: `'support-three-way'`
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message
+     *   - `conferenceName: string` — The conference room name. Use this for subsequent
+     *     operations (`swapCallParticipant`, `kickFromConference`, `muteConferenceMember`).
+     *   - `participants: ThreeWayParticipant[]` — Array of all 3 participants in the conference.
+     *     Each has `uuid` (FS channel UUID), `memberId` (needed for kick/mute),
+     *     `callerIdNumber`, `callerIdName`, `muted` (boolean), and `status` (`'active'` or `'held'`).
+     *
+     * @throws {HttpError} 400 — One or both call UUIDs not found, or calls already terminated
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH conference creation failed
+     *
+     * @example
+     * ```typescript
+     * // Complete three-way call flow
+     * // Step 1: Add third party
+     * const { newCallUuid, originalBridgedLeg } = await voip.addCallParticipant(
+     *   currentCallUuid,
+     *   { toNumber: '+17865559999' },
+     * );
+     *
+     * // Step 2: Wait for answer (via WebSocket or polling)
+     * voip.on('call_answer', async (data) => {
+     *   if (data.call_uuid === newCallUuid) {
+     *     // Step 3: Merge — all three parties now connected
+     *     const { conferenceName, participants } = await voip.mergeCalls({
+     *       callUuidA: currentCallUuid,
+     *       callUuidB: newCallUuid,
+     *       bridgedLegA: originalBridgedLeg,
+     *     });
+     *
+     *     console.log(`Conference "${conferenceName}" is live`);
+     *     participants.forEach(p => {
+     *       console.log(`  ${p.callerIdName} (${p.callerIdNumber}) — ${p.status}`);
+     *     });
+     *   }
+     * });
+     *
+     * // CRM UI: Build participant list after merge
+     * function renderParticipants(participants: ThreeWayParticipant[]) {
+     *   participants.forEach(p => {
+     *     // Show avatar, name, number, and controls
+     *     renderParticipantCard({
+     *       name: p.callerIdName || p.callerIdNumber,
+     *       number: p.callerIdNumber,
+     *       isMuted: p.muted,
+     *       onMute: () => voip.muteConferenceMember(conferenceName, p.memberId, !p.muted),
+     *       onKick: () => voip.kickFromConference(conferenceName, p.memberId),
+     *     });
+     *   });
+     * }
+     * ```
      *
-     * @param params  `{ callUuidA, callUuidB, conferenceName? }`
+     * @see POST /api/calls/three-way/merge
+     * @see addCallParticipant (step 1)
+     * @see swapCallParticipant (go private with one party)
+     * @see mergeDirectCalls (skip addCallParticipant — merge two existing calls)
      */
     async mergeCalls(params, options) {
         return this.request('POST', '/api/calls/three-way/merge', params, undefined, options);
     }
     /**
-     * Swap — go "private" with one participant by removing the other from the
-     * conference and placing them on hold. Call `mergeCalls()` again to restore.
+     * Swap which participant is active in a three-way conference — go "private"
+     * with one person while the other is placed on hold.
+     *
+     * @description
+     * In a three-way conference call, you might need to have a private conversation with
+     * just one participant while the other waits on hold. This method removes one
+     * participant from the conference (they hear hold music) and keeps the other
+     * connected. The held participant can be brought back by calling `mergeCalls()` again.
+     *
+     * **Use case:** You're on a call with a customer (A) and your manager (B).
+     * You need to discuss something privately with your manager:
+     * 1. `swapCallParticipant({ keepUuid: managerUuid, holdUuid: customerUuid })`
+     * 2. Now you and your manager can talk privately — the customer hears hold music
+     * 3. `mergeCalls()` — Bring all three back together
+     *
+     * **CRM UI guidance:**
+     * - Show a "Private" or "Talk Privately" button next to each participant
+     * - After swapping, the held participant's card should show "On Hold" with a "Rejoin" button
+     * - The active participant's card should show "Private Conversation"
+     * - Show a "Rejoin All" button that calls `mergeCalls()` to restore the full conference
+     *
+     * @param params — Swap parameters
+     * @param params.conferenceName — The conference room name, returned by `mergeCalls()`
+     *   or `mergeDirectCalls()`. Example: `'conf-abc123'`
+     * @param params.keepUuid — The FreeSWITCH channel UUID of the participant to KEEP
+     *   active in the conference (talk privately with this person).
+     *   Get this from `mergeCalls()` → `participants[].uuid`.
+     *   Example: `'b2c3d4e5-f6a7-8901-bcde-f12345678901'`
+     * @param params.holdUuid — The FreeSWITCH channel UUID of the participant to PLACE
+     *   ON HOLD (remove from conference — they hear hold music).
+     *   Get this from `mergeCalls()` → `participants[].uuid`.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message
+     *   - `conferenceName: string` — The same conference name (for subsequent operations)
+     *   - `activeUuid: string` — The UUID of the participant still in the conference (the one you kept)
+     *   - `heldUuid: string` — The UUID of the participant now on hold (the one you held)
+     *
+     * @throws {HttpError} 400 — Conference not found, UUIDs don't match participants, or invalid state
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH operation failed
+     *
+     * @example
+     * ```typescript
+     * // After mergeCalls, talk privately with the manager
+     * const { conferenceName, participants } = await voip.mergeCalls({
+     *   callUuidA: selfUuid,
+     *   callUuidB: newCallUuid,
+     * });
+     *
+     * const customer = participants.find(p => p.callerIdNumber === '+17865551234');
+     * const manager = participants.find(p => p.callerIdNumber === '1002');
+     *
+     * // Go private with the manager — customer goes on hold
+     * await voip.swapCallParticipant({
+     *   conferenceName,
+     *   keepUuid: manager.uuid,
+     *   holdUuid: customer.uuid,
+     * });
+     *
+     * // CRM UI: Private conversation with manager
+     * showPrivateBanner('Talking privately with Manager');
+     * showOnHoldBanner(customer.callerIdNumber);
+     *
+     * // Bring everyone back
+     * document.getElementById('rejoin-all-btn').onclick = async () => {
+     *   await voip.mergeCalls({
+     *     callUuidA: selfUuid,
+     *     callUuidB: manager.uuid,
+     *   });
+     *   showConferenceActiveBanner();
+     * };
+     *
+     * // CRM UI: Swap to talk privately with customer while manager waits
+     * await voip.swapCallParticipant({
+     *   conferenceName,
+     *   keepUuid: customer.uuid,
+     *   holdUuid: manager.uuid,
+     * });
+     * ```
      *
-     * @param params  `{ conferenceName, keepUuid, holdUuid }`
+     * @see POST /api/calls/three-way/swap
+     * @see mergeCalls (restore full three-way)
      */
     async swapCallParticipant(params, options) {
         return this.request('POST', '/api/calls/three-way/swap', params, undefined, options);
     }
     /**
-     * Merge two independently-created calls directly into a conference.
-     * Does NOT require `addCallParticipant()` first — works with any two active
-     * call UUIDs (e.g. from a desk phone where the user held call A and dialed
-     * call B manually).
+     * Merge two independently-created calls directly into a conference — no
+     * `addCallParticipant()` step required.
+     *
+     * @description
+     * Unlike `mergeCalls()` which requires the `addCallParticipant()` → merge flow,
+     * this method works with ANY two active call UUIDs from any source. Use this when:
+     *
+     * - A desk phone user puts call A on hold (using the phone's Hold button),
+     *   dials call B manually, and then wants to merge them
+     * - Two WebRTC calls were originated separately via `originate()`
+     * - You have two active call UUIDs from `getActiveCalls()` and want to merge them
+     *
+     * This is the lower-level "merge any two calls" endpoint. For the guided three-way
+     * flow with auto-hold and dialing, use `addCallParticipant()` + `mergeCalls()` instead.
+     *
+     * **CRM UI guidance:**
+     * - Use this for a "Merge" button in a multi-call view where the user has two
+     *   separate active calls
+     * - Show both calls side by side with a "Merge Calls" button between them
+     * - After merge, show the same conference participant panel as `mergeCalls()`
+     *
+     * @param params — Merge parameters
+     * @param params.callUuidA — UUID of the first active call leg.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param params.callUuidB — UUID of the second active call leg.
+     *   Example: `'b2c3d4e5-f6a7-8901-bcde-f12345678901'`
+     * @param params.conferenceName — Optional custom conference name. Auto-generated if omitted.
+     *   Example: `'manual-merge'`
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message
+     *   - `conferenceName: string` — The conference room name for subsequent operations
+     *   - `participants: ThreeWayParticipant[]` — All participants now in the conference.
+     *     Each has `uuid`, `memberId`, `callerIdNumber`, `callerIdName`, `muted`, and `status`.
+     *
+     * @throws {HttpError} 400 — One or both call UUIDs not found or already terminated
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH conference creation failed
+     *
+     * @example
+     * ```typescript
+     * // Desk phone user: held call A, dialed call B, now wants to merge
+     * const { activeCalls } = await voip.getActiveCalls();
      *
-     * @param params  `{ callUuidA, callUuidB, conferenceName? }`
+     * // Find the two calls (one on hold, one active)
+     * const heldCall = activeCalls.find(c => c.on_hold);
+     * const activeCall = activeCalls.find(c => !c.on_hold && c.uuid !== heldCall?.uuid);
+     *
+     * if (heldCall && activeCall) {
+     *   const { conferenceName, participants } = await voip.mergeDirectCalls({
+     *     callUuidA: heldCall.uuid,
+     *     callUuidB: activeCall.uuid,
+     *   });
+     *   console.log(`Merged into conference: ${conferenceName}`);
+     * }
+     *
+     * // CRM UI: Merge button for two active calls
+     * async function mergeTwoCalls(uuid1: string, uuid2: string) {
+     *   try {
+     *     const { conferenceName, participants } = await voip.mergeDirectCalls({
+     *       callUuidA: uuid1,
+     *       callUuidB: uuid2,
+     *     });
+     *     showConferencePanel(conferenceName, participants);
+     *     hideMergeButton();
+     *   } catch (err) {
+     *     showError('Could not merge calls — one may have ended');
+     *   }
+     * }
+     *
+     * // After merge, use the same conference operations
+     * await voip.muteConferenceMember(conferenceName, participants[1].memberId, true);
+     * await voip.kickFromConference(conferenceName, participants[2].memberId);
+     * ```
+     *
+     * @see POST /api/calls/three-way/merge-direct
+     * @see mergeCalls (guided three-way flow with addCallParticipant)
+     * @see swapCallParticipant (go private with one party)
      */
     async mergeDirectCalls(params, options) {
         return this.request('POST', '/api/calls/three-way/merge-direct', params, undefined, options);
@@ -372,23 +1526,298 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Extensions
     // -------------------------------------------------------------------
-    /** List extensions for the current tenant */
+    /**
+     * List all extensions for the current tenant.
+     *
+     * @description
+     * Retrieves every PBX extension in the tenant, including SIP registration details,
+     * voicemail configuration, call forwarding settings, and real-time presence status.
+     * This is the primary method for populating extension lists in admin dashboards,
+     * user directories, and CRM extension pickers.
+     *
+     * Each extension includes:
+     * - `id` — UUID (used for update/delete/SIP credential lookups)
+     * - `extension` — The extension number (e.g. `'1001'`)
+     * - `display_name` — Human-readable name (e.g. `'John Smith'`)
+     * - `presence` — Real-time status: `'available'`, `'on_call'`, `'offline'`, `'do_not_disturb'`
+     * - `voicemail_enabled`, `recording_enabled`, `do_not_disturb`, `status`
+     * - `crm_user_id` — Linked CRM user ID (for mapping extensions to CRM records)
+     *
+     * **Superadmin mode:** Returns extensions from ALL tenants. Each extension includes
+     * a `tenants` field with `{ id, company_name, subdomain }`.
+     *
+     * **CRM UI guidance:** Show this as a table with columns: Extension, Display Name,
+     * Presence (colored dot), Status (active/disabled), Voicemail (on/off), Actions
+     * (Edit, Delete, SIP Credentials). Add a search bar and presence filter.
+     *
+     * @returns An object containing:
+     *   - `extensions: Extension[]` — Array of extension objects
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { extensions } = await voip.listExtensions();
+     *
+     * // Show extensions table
+     * extensions.forEach(ext => {
+     *   const presenceColor = {
+     *     available: 'green', on_call: 'orange',
+     *     offline: 'gray', do_not_disturb: 'red',
+     *   }[ext.presence || 'offline'];
+     *   console.log(`${presenceColor} ${ext.extension} | ${ext.display_name} | ${ext.presence}`);
+     * });
+     *
+     * // CRM UI: build a call transfer extension picker
+     * const onlineExtensions = extensions.filter(e =>
+     *   e.presence === 'available' && e.status === 'active'
+     * );
+     * // Show in a dropdown for blind transfer
+     * ```
+     *
+     * @see GET /api/extensions
+     */
     async listExtensions() {
         return this.request('GET', '/api/extensions');
     }
-    /** Get a single extension */
+    /**
+     * Get a single extension by its UUID.
+     *
+     * @description
+     * Returns full details for one extension including SIP settings, voicemail config,
+     * call forwarding, CRM mapping, and real-time presence status. Use this to populate
+     * an "Extension Detail" panel or edit form in the admin dashboard.
+     *
+     * **CRM UI guidance:** Show all fields in a detail view with an "Edit" button.
+     * Display presence as a colored dot with status text. Show voicemail settings
+     * (enabled/disabled, PIN, greeting type). Show call forwarding destination if active.
+     *
+     * @param id — The UUID of the extension (from `listExtensions()` → `extensions[].id`)
+     *
+     * @returns An object containing:
+     *   - `extension: Extension` — The full extension object
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Extension not found
+     *
+     * @example
+     * ```typescript
+     * const { extension } = await voip.getExtension('a1b2c3d4-e5f6-7890-abcd-ef1234567890');
+     *
+     * console.log(`Extension: ${extension.extension}`);
+     * console.log(`Name: ${extension.display_name}`);
+     * console.log(`Presence: ${extension.presence}`);
+     * console.log(`Voicemail: ${extension.voicemail_enabled ? 'On' : 'Off'}`);
+     * console.log(`CRM User: ${extension.crm_user_id || 'Not mapped'}`);
+     * ```
+     *
+     * @see GET /api/extensions/{id}
+     */
     async getExtension(id) {
         return this.request('GET', `/api/extensions/${id}`);
     }
-    /** Create an extension (also creates Kamailio subscriber). Pass `options.tenantId` when using a global superadmin key. */
+    /**
+     * Create a new extension (also creates a Kamailio SIP subscriber for registration).
+     *
+     * @description
+     * Provisions a new PBX extension for the tenant. This creates:
+     * - An extension record in the PostgreSQL database
+     * - A Kamailio SIP subscriber entry so the extension can register (softphone/desk phone)
+     * - Optional voicemail box with PIN protection
+     *
+     * The returned `sip` object contains the provisioning info needed to configure
+     * a SIP softphone or desk phone: `username`, `domain`, and `server`.
+     *
+     * **Superadmin mode:** Pass `{ tenantId: 'uuid' }` as the second parameter when
+     * using a global superadmin API key to create an extension in a specific tenant.
+     *
+     * **CRM UI guidance:** Show a form with fields: Extension Number (required),
+     * Display Name (required), Password (required), Voicemail Enabled (checkbox),
+     * Voicemail PIN (optional, 4-6 digits), Recording Enabled (checkbox, default on),
+     * Outbound Caller ID (dropdown of tenant DIDs). Validate before submit.
+     *
+     * @param params — Extension creation parameters
+     * @param params.extension — The extension number (e.g. `'2001'`). Must be unique within the tenant
+     * @param params.password — SIP password for registration (min 8 chars recommended)
+     * @param params.displayName — Human-readable display name (e.g. `'Alice Johnson'`)
+     * @param params.voicemailEnabled — Enable voicemail for this extension (default `false`)
+     * @param params.voicemailPin — 4-6 digit PIN for voicemail access via *97 (optional)
+     * @param params.doNotDisturb — Enable Do Not Disturb mode (default `false`)
+     * @param params.recordingEnabled — Enable call recording (default `true`)
+     * @param params.noiseCancellationEnabled — Enable server-side RNNoise noise cancellation (default `true`)
+     * @param params.outboundCallerId — Outbound caller ID DID number (must be a tenant DID).
+     *   Set to `null` to fall back to the tenant's first active DID
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `extension: Extension` — The created extension object
+     *   - `sip: SipProvisioningInfo` — SIP provisioning info with `username`, `domain`, `server`
+     *
+     * @throws {HttpError} 400 — Extension number already exists, invalid outbound caller ID, or missing required fields
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Create a new extension for the tenant
+     * const { extension, sip } = await voip.createExtension({
+     *   extension: '2001',
+     *   password: 'secure-sip-password',
+     *   displayName: 'Alice Johnson',
+     *   voicemailEnabled: true,
+     *   voicemailPin: '1234',
+     *   recordingEnabled: true,
+     * });
+     *
+     * console.log(`Created extension ${sip.username}@${sip.domain} (server: ${sip.server})`);
+     *
+     * // Superadmin: create extension in a specific tenant
+     * const { extension } = await voip.createExtension(
+     *   { extension: '3001', password: 'pass123', displayName: 'Bob' },
+     *   { tenantId: 'a1b2c3d4-...' },
+     * );
+     *
+     * // CRM UI: handle form submission
+     * async function handleCreateExtension(formData: CreateExtensionParams) {
+     *   try {
+     *     const { extension, sip } = await voip.createExtension(formData);
+     *     showNotification(`Extension ${extension.extension} created successfully`);
+     *     showProvisioningInfo(sip); // Show SIP config for the user
+     *   } catch (err) {
+     *     if (err instanceof HttpError && err.status === 400) {
+     *       showError('Extension number already exists — choose another');
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @see POST /api/extensions
+     */
     async createExtension(params, options) {
         return this.request('POST', '/api/extensions', params, undefined, options);
     }
-    /** Update an extension */
+    /**
+     * Update an existing extension's settings.
+     *
+     * @description
+     * Modifies one or more fields on an extension. All parameters are optional —
+     * only the fields you provide will be updated. Common use cases:
+     * - Change display name when an employee's name changes
+     * - Reset SIP password for a user who forgot it
+     * - Enable/disable voicemail or change the PIN
+     * - Toggle Do Not Disturb for vacation/after-hours
+     * - Enable/disable recording per extension
+     * - Activate or disable an extension
+     *
+     * **CRM UI guidance:** Show an edit form pre-populated with current values from `getExtension()`.
+     * Use a modal or slide-over panel. Show a "Save" button that only lights up when a value
+     * has changed. For password changes, show a "Show/Hide" toggle button.
+     *
+     * @param id — The UUID of the extension to update (from `listExtensions()` → `extensions[].id`)
+     * @param params — Fields to update (all optional, omit unchanged fields)
+     * @param params.displayName — New display name. Example: `'Alicia Johnson'`
+     * @param params.password — New SIP password. Example: `'new-secure-password'`
+     * @param params.voicemailEnabled — Enable or disable voicemail
+     * @param params.voicemailPin — New 4-6 digit voicemail PIN. Set to `null` to remove PIN protection
+     * @param params.doNotDisturb — Enable or disable Do Not Disturb
+     * @param params.status — `'active'` or `'disabled'`. Disabled extensions cannot make/receive calls
+     * @param params.recordingEnabled — Enable or disable call recording
+     * @param params.noiseCancellationEnabled — Enable or disable server-side noise cancellation
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. `'Extension updated'`)
+     *
+     * @throws {HttpError} 400 — Invalid field value or extension not found
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Update display name and enable voicemail
+     * await voip.updateExtension('ext-uuid-here', {
+     *   displayName: 'Alicia Johnson',
+     *   voicemailEnabled: true,
+     *   voicemailPin: '5678',
+     * });
+     *
+     * // Disable an extension (temporarily)
+     * await voip.updateExtension('ext-uuid-here', { status: 'disabled' });
+     *
+     * // Re-enable
+     * await voip.updateExtension('ext-uuid-here', { status: 'active' });
+     *
+     * // CRM UI: Edit form submit
+     * async function handleUpdateExtension(id: string, changes: UpdateExtensionParams) {
+     *   if (Object.keys(changes).length === 0) return; // Nothing changed
+     *   try {
+     *     await voip.updateExtension(id, changes);
+     *     showNotification('Extension updated');
+     *     closeEditModal();
+     *     refreshExtensionList();
+     *   } catch (err) {
+     *     showError('Update failed — please try again');
+     *   }
+     * }
+     * ```
+     *
+     * @see PUT /api/extensions/{id}
+     */
     async updateExtension(id, params, options) {
         return this.request('PUT', `/api/extensions/${id}`, params, undefined, options);
     }
-    /** Delete an extension */
+    /**
+     * Delete an extension permanently.
+     *
+     * @description
+     * Removes the extension from the database and cleans up associated resources:
+     * - Extension record (PostgreSQL)
+     * - Kamailio SIP subscriber (can no longer register)
+     * - Voicemail messages and greeting audio files
+     * - Ring group / queue / paging group memberships
+     * - CRM mapping associations
+     *
+     * This operation is irreversible. Call records (CDRs) belonging to this extension
+     * are preserved for audit purposes.
+     *
+     * **CRM UI guidance:** Show a confirmation dialog before deleting:
+     * "Are you sure you want to delete extension [number] ([name])? This will also
+     * delete all associated voicemail messages, greetings, and group memberships."
+     * Use a red "Delete" button. After deletion, remove the row from the table.
+     *
+     * @param id — The UUID of the extension to delete (from `listExtensions()` → `extensions[].id`)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. `'Extension deleted'`)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Extension not found
+     *
+     * @example
+     * ```typescript
+     * // Delete extension 2001
+     * await voip.deleteExtension('ext-uuid-here');
+     *
+     * // CRM UI: Delete button with confirmation
+     * async function handleDeleteExtension(ext: Extension) {
+     *   const confirmed = confirm(
+     *     `Delete extension ${ext.extension} (${ext.display_name})?\n\n` +
+     *     'This will also delete all voicemail messages and greetings.'
+     *   );
+     *   if (!confirmed) return;
+     *
+     *   try {
+     *     await voip.deleteExtension(ext.id);
+     *     removeExtensionRow(ext.id);
+     *     showNotification(`Extension ${ext.extension} deleted`);
+     *   } catch (err) {
+     *     showError('Delete failed — please try again');
+     *   }
+     * }
+     * ```
+     *
+     * @see DELETE /api/extensions/{id}
+     */
     async deleteExtension(id) {
         return this.request('DELETE', `/api/extensions/${id}`);
     }
@@ -409,19 +1838,77 @@ export class VoIPClient {
         return this.request('PUT', `/api/extensions/${extensionId}/crm-mapping`, params);
     }
     /**
-     * Get SIP credentials for connecting a WebRTC softphone.
-     * Returns everything needed to register: extension, password, SIP domain, WebSocket URI.
-     * Use this so your app never needs to store SIP passwords.
+     * Get SIP credentials for connecting a WebRTC softphone or SIP device.
+     *
+     * @description
+     * Returns everything needed to register a softphone or desk phone with the SIP server:
+     * extension number, SIP password, SIP domain, WebSocket URI (for WebRTC), and registrar address.
+     * Use this so your app never needs to store SIP passwords — fetch them on demand
+     * when the user opens the softphone page.
+     *
+     * **Two lookup modes:**
+     * - **By UUID** (default): `getSipCredentials('extension-uuid')` — use the `id` from `listExtensions()`
+     * - **By number**: `getSipCredentials('1001', { byNumber: true, tenantId: 'uuid' })` — look up
+     *   by extension number string. `tenantId` is required for by-number lookup (the extension
+     *   number is only unique within a tenant).
+     *
+     * **CRM UI guidance:** Call this when the user clicks "Connect Softphone" or opens the
+     * WebRTC dialer. Pass the credentials to the `WebRTCPhone` constructor. Never display
+     * the password in the UI — use a "Copy" button with `type="password"` input.
+     *
+     * @param target — Extension UUID (default mode), or extension number string when `byNumber: true`
+     * @param options — Optional overrides. Include `{ byNumber: true, tenantId: 'uuid' }` to look
+     *   up by extension number instead of UUID. `tenantId` is required for by-number lookups.
      *
-     * @param target - Extension UUID, or extension number when `byNumber: true`
-     * @param options - Optional `{ tenantId }` for superadmin context, plus `{ byNumber: true }` to look up by extension number
+     * @returns An object containing:
+     *   - `sipCredentials: SipCredentials` — Object with `extension`, `displayName`, `password`,
+     *     `sipDomain`, `wsUri` (WebSocket URI for WebRTC), and `registrar`
+     *
+     * @throws {HttpError} 400 — `tenantId` is required when using `byNumber: true`
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Extension not found
      *
      * @example
-     * // By UUID (default)
+     * ```typescript
+     * // By UUID (default) — pass id from listExtensions()
      * const { sipCredentials } = await voip.getSipCredentials('extension-uuid');
      *
-     * // By extension number (e.g. "1001")
-     * const { sipCredentials } = await voip.getSipCredentials('1001', { byNumber: true, tenantId: 'tenant-uuid' });
+     * // By extension number — requires tenantId
+     * const { sipCredentials } = await voip.getSipCredentials('1001', {
+     *   byNumber: true,
+     *   tenantId: 'a1b2c3d4-...',
+     * });
+     *
+     * // Use credentials with WebRTCPhone
+     * const phone = new WebRTCPhone({
+     *   extension: sipCredentials.extension,
+     *   password: sipCredentials.password,
+     *   sipDomain: sipCredentials.sipDomain,
+     *   wsUri: sipCredentials.wsUri,
+     * });
+     *
+     * // CRM UI: "Connect Phone" button
+     * async function connectSoftphone(extensionId: string) {
+     *   showConnectingSpinner();
+     *   try {
+     *     const { sipCredentials } = await voip.getSipCredentials(extensionId);
+     *     const phone = new WebRTCPhone({
+     *       extension: sipCredentials.extension,
+     *       password: sipCredentials.password,
+     *       sipDomain: sipCredentials.sipDomain,
+     *       wsUri: sipCredentials.wsUri,
+     *       audioElement: document.getElementById('remote-audio') as HTMLAudioElement,
+     *     });
+     *     await phone.connect();
+     *     showPhoneReady(sipCredentials.extension);
+     *   } catch (err) {
+     *     showError('Failed to connect softphone');
+     *   }
+     * }
+     * ```
+     *
+     * @see GET /api/extensions/{id}/sip-credentials
+     * @see GET /api/extensions/by-number/{number}/sip-credentials
      */
     async getSipCredentials(target, options) {
         const byNumber = options && 'byNumber' in options ? options.byNumber : false;
@@ -433,7 +1920,45 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Tenants (superadmin)
     // -------------------------------------------------------------------
-    /** List all tenants (superadmin only) */
+    /**
+     * List all tenants (superadmin only).
+     *
+     * @description
+     * Returns every tenant in the platform. This is a superadmin-only endpoint — tenant
+     * admins cannot see other tenants. Each tenant includes company name, subdomain,
+     * SIP domain, Twilio integration settings, and feature flags.
+     *
+     * **CRM UI guidance (superadmin):** Show as a table with columns: Company Name,
+     * Subdomain, Extensions Count (use `getTenantStats()`), Status (active/disabled),
+     * and an Actions menu (View, Edit, Delete). Add a search bar to filter by company
+     * name. Show a "Create Tenant" button at the top.
+     *
+     * @returns An object containing:
+     *   - `tenants: Tenant[]` — Array of tenant objects
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 403 — Not a superadmin
+     *
+     * @example
+     * ```typescript
+     * const { tenants } = await voip.listTenants();
+     *
+     * tenants.forEach(t => {
+     *   console.log(`${t.companyName} (${t.subdomain}) — ${t.status}`);
+     * });
+     *
+     * // CRM UI: superadmin tenant list
+     * const { tenants } = await voip.listTenants();
+     * renderTenantTable(tenants.map(t => ({
+     *   id: t.id,
+     *   name: t.companyName,
+     *   subdomain: t.subdomain,
+     *   status: t.status,
+     * })));
+     * ```
+     *
+     * @see GET /api/tenants
+     */
     async listTenants() {
         return this.request('GET', '/api/tenants');
     }
@@ -476,7 +2001,53 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // DIDs
     // -------------------------------------------------------------------
-    /** List DID numbers */
+    /**
+     * List all DID (Direct Inward Dialing) phone numbers for the current tenant.
+     *
+     * @description
+     * Retrieves every phone number assigned to the tenant. Each DID includes:
+     * - The phone number itself (the DID)
+     * - Inbound routing configuration (IVR, extension, queue, ring group, AI agent, etc.)
+     * - Route target (e.g. IVR menu name, extension number)
+     * - Emergency caller ID flag
+     * - Status (active/inactive)
+     *
+     * DIDs are how external callers reach your phone system — someone dials the DID
+     * number, and the system routes the call according to the inbound route settings.
+     *
+     * **CRM UI guidance:** Show as a table with columns: Phone Number, Route Type
+     * (Extension/IVR/Queue/etc.), Route Target, Status (active/inactive), Actions
+     * (Edit, Delete). Show a "Create DID" button. Use a badge/tag for the route type.
+     *
+     * @returns An object containing:
+     *   - `dids: DidNumber[]` — Array of DID number objects
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { dids } = await voip.listDids();
+     *
+     * dids.forEach(did => {
+     *   console.log(`${did.number} → ${did.inbound_route} / ${did.route_target}`);
+     * });
+     *
+     * // CRM UI: DID list with route badges
+     * dids.forEach(did => {
+     *   const routeLabel = {
+     *     extension: '📞 Extension',
+     *     ivr: '🌳 IVR',
+     *     queue: '👥 Queue',
+     *     ring_group: '🔔 Ring Group',
+     *     ai_agent: '🤖 AI Agent',
+     *     whatsapp: '💬 WhatsApp',
+     *   }[did.inbound_route] || did.inbound_route;
+     *   renderDidRow(did.number, routeLabel, did.route_target, did.status);
+     * });
+     * ```
+     *
+     * @see GET /api/dids
+     */
     async listDids() {
         return this.request('GET', '/api/dids');
     }
@@ -961,61 +2532,161 @@ export class VoIPClient {
     //
     // -------------------------------------------------------------------
     /**
-     * List recordings with pagination.
+     * List call recordings with pagination and filtering.
      *
-     * Each recording includes `cdn_url` (CloudFront CDN, instant) and `audio_url` (API fallback).
-     * Always prefer `cdn_url` when non-null for the fastest playback.
+     * @description
+     * Retrieves a paginated list of call recordings for the current tenant. Each recording
+     * includes `cdn_url` (CloudFront CDN, instant, no auth) and `audio_url` (API fallback).
+     * Always prefer `cdn_url` when non-null for the fastest playback from the nearest
+     * CloudFront edge location.
+     *
+     * **CRM UI guidance:** Show a "Recordings" table with columns: Date/Time, Caller,
+     * Destination, Duration, and a Play button. The Play button should use `cdn_url` if
+     * available (no API call needed), falling back to `buildUrl(audio_url)`. Show a
+     * loading spinner state. If recordings exist, show pagination controls at the bottom.
+     *
+     * **Playback decision tree:**
+     * ```
+     * if (rec.cdn_url) → use cdn_url directly (<audio src={rec.cdn_url} />)
+     * else if (rec.audio_url) → use voip.buildUrl(`/api/recordings/${rec.id}/audio`)
+     * else → "No recording" state
+     * ```
+     *
+     * @param params — Optional filters and pagination
+     * @param params.page — Page number (1-based, default 1)
+     * @param params.limit — Records per page (default 50)
+     * @param params.direction — Filter by call direction: `'inbound'`, `'outbound'`, `'internal'`, or `'all'`
+     * @param params.dateFrom — ISO date string: recordings on or after this date
+     * @param params.dateTo — ISO date string: recordings on or before this date
+     * @param params.extension — Filter by extension number
+     *
+     * @returns An object containing:
+     *   - `recordings: Recording[]` — Array of recording objects with `id`, `cdn_url`,
+     *     `audio_url`, `caller_id_number`, `destination`, `duration_seconds`, `started_at`,
+     *     `format`, and optional `company_name`/`subdomain` (superadmin)
+     *   - `pagination: PaginationInfo` — `{ page, limit, total, pages }`
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
      *
      * @example
      * ```typescript
      * const { recordings, pagination } = await voip.listRecordings({
      *   page: 1,
      *   limit: 20,
+     *   dateFrom: '2026-06-01',
+     *   dateTo: '2026-06-30',
      *   direction: 'inbound',
      * });
      *
+     * console.log(`Found ${pagination.total} recordings`);
+     *
      * recordings.forEach(rec => {
-     *   // Always prefer CDN URL — instant playback from nearest edge
      *   const src = rec.cdn_url ?? voip.buildUrl(`/api/recordings/${rec.id}/audio`);
-     *   render(`<audio src="${src}" preload="none" controls />`);
+     *   // Render <audio src={src} preload="none" controls />
      * });
+     *
+     * // CRM UI: pagination through all recordings
+     * for (let page = 1; page <= pagination.pages; page++) {
+     *   const { recordings } = await voip.listRecordings({ page, limit: 50 });
+     *   renderRecordingPage(recordings, page);
+     * }
      * ```
+     *
+     * @see GET /api/recordings
      */
     async listRecordings(params) {
         return this.request('GET', '/api/recordings', undefined, params);
     }
     /**
-     * Get the best available URL to play a recording.
+     * Get the best available URL to play a recording, with source and format metadata.
      *
-     * Returns a response with:
-     * - `url` — CloudFront CDN URL (if in S3) or API URL (local fallback)
-     * - `source` — `'cdn'` (fast, ~5-20ms) or `'local'` (slower, disk stream)
-     * - `format` — `'mp3'` or `'wav'`
+     * @description
+     * Resolves the optimal recording URL by checking S3/CloudFront availability first,
+     * then falling back to local disk streaming. Returns metadata about which source
+     * was selected so you can optimize future calls.
      *
      * **For most CRM use cases**, you don't need this method. Just read `cdn_url` from
-     * `listCalls()` or `getCall()` directly. Use this only when you need to resolve the
-     * URL programmatically before rendering.
+     * `listCalls()` or `getCall()` directly — it's the same CDN URL with zero API calls.
+     * Use this only when you need to programmatically resolve the URL before rendering
+     * and need to know the source and format.
+     *
+     * @param id — The recording ID (from `listCalls()` → `calls[].id` or `listRecordings()` → `recordings[].id`)
+     *
+     * @returns An object containing:
+     *   - `url: string` — The full URL to play this recording (CDN or API)
+     *   - `source: 'cdn' | 'local'` — `'cdn'` = CloudFront (fast, ~5-20ms) or `'local'` = disk stream (slower)
+     *   - `format: 'mp3' | 'wav'` — Audio file format
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Recording not found
      *
      * @example
      * ```typescript
      * const { url, source, format } = await voip.getRecordingUrl(callId);
-     * console.log(`Playing from ${source}: ${url} (${format})`);
+     *
+     * if (source === 'cdn') {
+     *   console.log(`Playing from CDN: ${url} (${format})`);
+     * } else {
+     *   console.log(`Playing from local disk: ${url} (${format})`);
+     * }
+     *
+     * // Pass to audio element
      * audioElement.src = url;
+     * audioElement.load();
+     * audioElement.play();
      * ```
+     *
+     * @see GET /api/recordings/{id}/url
      */
     async getRecordingUrl(id) {
         return this.request('GET', `/api/recordings/${id}/url`);
     }
     /**
-     * Delete a recording permanently.
+     * Delete a recording permanently from all storage.
+     *
+     * @description
+     * Removes the audio file from S3 cloud storage (if uploaded), local server disk, and
+     * Redis cache. The `recording_url`, `s3_key`, `cdn_url`, and `audio_url` fields for
+     * this call record will become null after deletion. The call record (CDR) itself is
+     * preserved — only the audio file is removed.
+     *
+     * This is irreversible. Use with care, especially when complying with data retention
+     * policies or GDPR deletion requests.
+     *
+     * **CRM UI guidance:** Show a confirmation dialog: "Permanently delete this recording?
+     * The call history entry will remain, but the audio file cannot be recovered."
+     * Use a red "Delete" button with a trash icon. After deletion, update the row to show
+     * "Recording deleted" or remove the Play button.
+     *
+     * @param id — The recording/call ID (from `listCalls()` → `calls[].id` or `listRecordings()` → `recordings[].id`)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. `'Recording deleted'`)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Recording not found
      *
-     * Removes the audio file from:
-     * - S3 cloud storage (if uploaded)
-     * - Local server disk
-     * - Redis cache
+     * @example
+     * ```typescript
+     * // Delete a specific recording
+     * await voip.deleteRecording('recording-id-here');
+     *
+     * // CRM UI: Delete button with confirmation
+     * async function handleDeleteRecording(recordingId: string) {
+     *   if (!confirm('Permanently delete this recording? The audio file cannot be recovered.')) {
+     *     return;
+     *   }
+     *   try {
+     *     await voip.deleteRecording(recordingId);
+     *     showNotification('Recording deleted');
+     *     removePlayButton(recordingId); // Remove Play button from the row
+     *   } catch (err) {
+     *     showError('Failed to delete recording');
+     *   }
+     * }
+     * ```
      *
-     * The `recording_url`, `s3_key`, `cdn_url`, and `audio_url` fields for this call
-     * will become null after deletion.
+     * @see DELETE /api/recordings/{id}
      */
     async deleteRecording(id) {
         return this.request('DELETE', `/api/recordings/${id}`);
@@ -1023,27 +2694,305 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Conferences
     // -------------------------------------------------------------------
-    /** List active conferences */
+    /**
+     * List all active conferences in the phone system.
+     *
+     * @description
+     * Returns every live conference room currently running in FreeSWITCH. Each
+     * conference includes:
+     * - `name` — Conference room name (used for join/kick/mute operations)
+     * - `memberCount` — Number of participants
+     * - `locked` — Whether the conference is locked (no new participants)
+     * - `runTime` — How long the conference has been active (HH:MM:SS)
+     * - `members` — Array of conference member objects with caller info
+     *
+     * Conferences are created automatically by three-way calling (`mergeCalls()`,
+     * `mergeDirectCalls()`) or manually via `transferToConference()`.
+     *
+     * **CRM UI guidance:** Show as a "Active Conferences" panel or monitor view.
+     * Each conference row shows: Name, Participant Count, Duration, Lock Status.
+     * Expand a row to show member details with per-participant controls (Mute, Kick).
+     * Poll every 3-5 seconds for a near-real-time view.
+     *
+     * @returns An object containing:
+     *   - `conferences: Conference[]` — Array of active conference objects
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH connection error
+     *
+     * @example
+     * ```typescript
+     * const { conferences } = await voip.listConferences();
+     *
+     * if (conferences.length === 0) {
+     *   console.log('No active conferences');
+     * } else {
+     *   conferences.forEach(conf => {
+     *     console.log(`${conf.name}: ${conf.memberCount} participants, ${conf.runTime}`);
+     *   });
+     * }
+     *
+     * // CRM UI: live conference monitor
+     * setInterval(async () => {
+     *   const { conferences } = await voip.listConferences();
+     *   updateConferenceList(conferences);
+     * }, 5000);
+     * ```
+     *
+     * @see GET /api/conferences
+     */
     async listConferences() {
         return this.request('GET', '/api/conferences');
     }
-    /** Get conference details */
-    async getConference(name) {
-        return this.request('GET', `/api/conferences/${name}`);
-    }
-    /** Join a call to a conference */
-    async joinConference(conferenceName, callUuid) {
-        return this.request('POST', `/api/conferences/${conferenceName}/join`, { callUuid });
-    }
-    /** Transfer a call to conference */
-    async transferToConference(uuid, conferenceName) {
-        return this.request('POST', `/api/calls/${uuid}/conference`, conferenceName ? { conferenceName } : undefined);
-    }
-    /** Kick a member from conference */
+    /**
+     * Get detailed information about a specific conference by name.
+     *
+     * @description
+     * Returns full conference details including the member list with per-participant
+     * caller ID, mute status, and other metadata. Use this to populate a conference
+     * detail panel in an operator console or monitoring dashboard.
+     *
+     * **CRM UI guidance:** Show as a detail view with conference name, runtime, lock
+     * button, and participant list with individual controls (Mute/Unmute toggle,
+     * Kick button). Show a "Record" button if recording is supported. Display each
+     * participant's caller ID and mute status.
+     *
+     * @param name — The conference room name (from `listConferences()` → `conferences[].name`
+     *   or returned by `mergeCalls()` → `conferenceName`)
+     *
+     * @returns An object containing:
+     *   - `conference: Conference` — Full conference object with `members` array
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Conference not found
+     * @throws {HttpError} 500 — FreeSWITCH communication error
+     *
+     * @example
+     * ```typescript
+     * const { conference } = await voip.getConference('conf-abc123');
+     *
+     * console.log(`Conference: ${conference.name}`);
+     * console.log(`Participants: ${conference.memberCount}`);
+     * console.log(`Locked: ${conference.locked}`);
+     *
+     * conference.members.forEach(member => {
+     *   console.log(`  ${member.caller_id_number} — ${member.muted ? 'Muted' : 'Unmuted'}`);
+     * });
+     * ```
+     *
+     * @see GET /api/conferences/{name}
+     */
+    async getConference(name) {
+        return this.request('GET', `/api/conferences/${name}`);
+    }
+    /** Join a call to a conference */
+    async joinConference(conferenceName, callUuid) {
+        return this.request('POST', `/api/conferences/${conferenceName}/join`, { callUuid });
+    }
+    /**
+     * Transfer an active call into a conference room.
+     *
+     * @description
+     * Moves an existing active call into a FreeSWITCH conference room. If a
+     * `conferenceName` is specified, the call is added to that existing conference.
+     * If omitted, a new conference room is created automatically.
+     *
+     * Use this for:
+     * - Adding a caller to a scheduled conference call
+     * - Transferring a support call from an agent to a team conference
+     * - Creating a "join conference" button in the call controls
+     *
+     * **CRM UI guidance:** Show a "Transfer to Conference" button in the call controls.
+     * On click, show a selector: pick from existing conferences (`listConferences()`) or
+     * create a new one. After transfer, show "Call moved to conference [name]".
+     *
+     * @param uuid — The FreeSWITCH channel UUID of the active call to transfer.
+     *   Example: `'a1b2c3d4-e5f6-7890-abcd-ef1234567890'`
+     * @param conferenceName — Optional conference room to join. If omitted, a new
+     *   conference is created automatically. Example: `'support-team'` or omitted
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message
+     *
+     * @throws {HttpError} 400 — Call UUID not found or already ended
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH operation failed
+     *
+     * @example
+     * ```typescript
+     * // Transfer a call to an existing conference
+     * await voip.transferToConference(callUuid, 'support-team');
+     *
+     * // Transfer to a new auto-created conference
+     * await voip.transferToConference(callUuid);
+     *
+     * // CRM UI: transfer to conference button
+     * async function handleTransferToConference(callUuid: string) {
+     *   const { conferences } = await voip.listConferences();
+     *   const chosenConf = showConferencePicker(conferences);
+     *   if (chosenConf) {
+     *     await voip.transferToConference(callUuid, chosenConf);
+     *     showNotification(`Call transferred to conference "${chosenConf}"`);
+     *   }
+     * }
+     * ```
+     *
+     * @see POST /api/calls/{uuid}/conference
+     */
+    async transferToConference(uuid, conferenceName) {
+        return this.request('POST', `/api/calls/${uuid}/conference`, conferenceName ? { conferenceName } : undefined);
+    }
+    /**
+     * Remove (kick) a participant from a conference room.
+     *
+     * @description
+     * Forcefully removes a single participant from an active conference. The kicked
+     * participant is disconnected immediately. This is used for moderator control in
+     * three-way calls and multi-party conferences — for example, removing a disruptive
+     * participant or ending a consult call while keeping the main call active.
+     *
+     * **CRM UI guidance:**
+     * - Show a "Remove" or "Kick" button/icon next to each participant
+     * - Show a confirmation dialog: "Remove [name] from the call?"
+     * - After kicking, remove their card from the participant list immediately
+     * - If only 2 participants remain, automatically leave the conference (three-way → two-way)
+     *
+     * @param conferenceName — The conference room name, returned by `mergeCalls()`,
+     *   `mergeDirectCalls()`, or `listConferences()`.
+     *   Example: `'conf-abc123'`
+     * @param memberId — The conference member ID to kick (NOT the FS channel UUID).
+     *   Get this from `mergeCalls()` → `participants[].memberId`.
+     *   Example: `'1'` or `'2'`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. "Member kicked from conference")
+     *
+     * @throws {HttpError} 400 — Conference or member not found, or member ID is invalid
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH operation failed
+     *
+     * @example
+     * ```typescript
+     * // After mergeCalls, kick the third party
+     * const { conferenceName, participants } = await voip.mergeCalls({
+     *   callUuidA: selfUuid,
+     *   callUuidB: newCallUuid,
+     * });
+     *
+     * const thirdParty = participants.find(p => p.callerIdNumber === '+17865559999');
+     * if (thirdParty) {
+     *   await voip.kickFromConference(conferenceName, thirdParty.memberId);
+     * }
+     *
+     * // CRM UI: Kick button per participant
+     * function renderParticipantControls(participant: ThreeWayParticipant) {
+     *   const kickBtn = document.createElement('button');
+     *   kickBtn.textContent = 'Remove';
+     *   kickBtn.onclick = async () => {
+     *     if (confirm(`Remove ${participant.callerIdName || participant.callerIdNumber} from the call?`)) {
+     *       await voip.kickFromConference(conferenceName, participant.memberId);
+     *       removeParticipantCard(participant.memberId);
+     *     }
+     *   };
+     *   return kickBtn;
+     * }
+     *
+     * // CRM UI: Show/hide kick button
+     * // Only show kick for non-self participants
+     * participants
+     *   .filter(p => p.uuid !== selfUuid)
+     *   .forEach(p => showKickButton(p));
+     * ```
+     *
+     * @see POST /api/conferences/{conferenceName}/kick
+     * @see mergeCalls (get conferenceName and memberId)
+     */
     async kickFromConference(conferenceName, memberId) {
         return this.request('POST', `/api/conferences/${conferenceName}/kick`, { memberId });
     }
-    /** Mute/unmute a conference member */
+    /**
+     * Mute or unmute a participant in a conference room.
+     *
+     * @description
+     * Toggles the microphone for a single conference participant. When muted, the
+     * participant can still hear everyone, but nobody can hear them. This is the
+     * moderator control for managing who can speak in a three-way or multi-party call.
+     *
+     * Common use cases:
+     * - Mute a noisy participant (background noise, typing, echoes)
+     * - Mute yourself temporarily while looking up information
+     * - Mute a third party during a private consultation with the other participant
+     *
+     * **CRM UI guidance:**
+     * - Show a microphone icon next to each participant
+     * - Filled mic = unmuted, crossed-out mic = muted
+     * - Click to toggle: `muteConferenceMember(name, memberId, !currentMutedState)`
+     * - For your own card, label it "Mute Me" instead of just "Mute"
+     * - After muting, show a pulsing "Muted" indicator on their card
+     *
+     * @param conferenceName — The conference room name, returned by `mergeCalls()`,
+     *   `mergeDirectCalls()`, or `listConferences()`.
+     *   Example: `'conf-abc123'`
+     * @param memberId — The conference member ID to mute/unmute (NOT the FS channel UUID).
+     *   Get this from `mergeCalls()` → `participants[].memberId`.
+     *   Example: `'1'` or `'2'`
+     * @param mute — `true` to mute (silence the participant's microphone), `false` to unmute
+     *   (allow them to speak again). Default is `true`.
+     *   Example: `true`
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. "Member muted" or "Member unmuted")
+     *
+     * @throws {HttpError} 400 — Conference or member not found, or member ID is invalid
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH operation failed
+     *
+     * @example
+     * ```typescript
+     * // Mute a noisy participant
+     * const { conferenceName, participants } = await voip.mergeCalls({
+     *   callUuidA: selfUuid,
+     *   callUuidB: newCallUuid,
+     * });
+     *
+     * const noisyParticipant = participants.find(p => p.callerIdNumber === '+17865559999');
+     * if (noisyParticipant) {
+     *   await voip.muteConferenceMember(conferenceName, noisyParticipant.memberId, true);
+     * }
+     *
+     * // Unmute them when the noise is gone
+     * await voip.muteConferenceMember(conferenceName, noisyParticipant.memberId, false);
+     *
+     * // CRM UI: Mute/Unmute toggle button per participant
+     * function renderMuteButton(participant: ThreeWayParticipant, conferenceName: string) {
+     *   let isMuted = participant.muted;
+     *   const btn = document.createElement('button');
+     *
+     *   function updateButton() {
+     *     btn.textContent = isMuted ? '🔇 Unmute' : '🎤 Mute';
+     *     btn.className = isMuted ? 'btn-warning' : 'btn-default';
+     *   }
+     *
+     *   btn.onclick = async () => {
+     *     isMuted = !isMuted;
+     *     updateButton();
+     *     await voip.muteConferenceMember(conferenceName, participant.memberId, isMuted);
+     *   };
+     *
+     *   updateButton();
+     *   return btn;
+     * }
+     *
+     * // Mute yourself (the local participant)
+     * async function muteMyself(conferenceName: string, myMemberId: string) {
+     *   await voip.muteConferenceMember(conferenceName, myMemberId, true);
+     *   showSelfMutedIndicator();
+     * }
+     * ```
+     *
+     * @see POST /api/conferences/{conferenceName}/mute
+     * @see mergeCalls (get conferenceName and memberId)
+     */
     async muteConferenceMember(conferenceName, memberId, mute = true) {
         return this.request('POST', `/api/conferences/${conferenceName}/mute`, { memberId, mute });
     }
@@ -1062,7 +3011,44 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Ring Groups
     // -------------------------------------------------------------------
-    /** List ring groups */
+    /**
+     * List all ring groups for the current tenant.
+     *
+     * @description
+     * Returns every ring group configured for the tenant. A ring group rings multiple
+     * extensions simultaneously or sequentially when a DID is dialed. Common strategies:
+     *
+     * - **`simultaneous`** — All extensions ring at once. First to answer gets the call.
+     * - **`sequential`** — Extensions ring one at a time in priority order.
+     * - **`random`** — A random extension is selected to receive the call.
+     *
+     * Each ring group includes:
+     * - Name, strategy, ring timeout, no-answer action
+     * - Member list with extensions, priorities, and delay seconds
+     *
+     * **CRM UI guidance:** Show as a table with columns: Name, Strategy,
+     * Members (count), No Answer Action, Status, and Actions (Edit, Delete).
+     * Each row should expand to show member details.
+     *
+     * @returns An object containing:
+     *   - `ringGroups: RingGroup[]` — Array of ring group objects with members
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { ringGroups } = await voip.listRingGroups();
+     *
+     * ringGroups.forEach(rg => {
+     *   console.log(`${rg.name} — ${rg.strategy} — ${rg.members.length} members`);
+     *   rg.members.forEach(m => {
+     *     console.log(`  ${m.extension} (priority: ${m.priority}, delay: ${m.delay_seconds}s)`);
+     *   });
+     * });
+     * ```
+     *
+     * @see GET /api/ring-groups
+     */
     async listRingGroups() {
         return this.request('GET', '/api/ring-groups');
     }
@@ -1070,7 +3056,84 @@ export class VoIPClient {
     async getRingGroup(id) {
         return this.request('GET', `/api/ring-groups/${id}`);
     }
-    /** Create a ring group. Pass `options.tenantId` when using a global superadmin key. */
+    /**
+     * Create a new ring group.
+     *
+     * @description
+     * Configures a group of extensions that ring together when a DID or internal number
+     * is dialed. This is the primary way to implement "ring all phones in the sales
+     * department" or "try John, then Jane, then voicemail" routing patterns.
+     *
+     * **Strategies:**
+     * - `'simultaneous'` (default) — All extensions ring at the same time
+     * - `'sequential'` — One at a time, in priority order
+     * - `'random'` — Randomly pick one extension to ring
+     *
+     * **No-answer handling:** When no member answers within `ringTimeout` seconds,
+     * the call is routed according to `noAnswerAction` and `noAnswerTarget`.
+     *
+     * **Superadmin mode:** Pass `{ tenantId: 'uuid' }` when using a global superadmin
+     * key to create a ring group for a specific tenant.
+     *
+     * **CRM UI guidance:** Show a form with: Name (required), Strategy (dropdown),
+     * Ring Timeout (seconds slider, 5-60), No Answer Action (dropdown),
+     * No Answer Target (dynamic based on action), and Member picker (multi-select
+     * from extension list with priority and delay settings per member).
+     *
+     * @param params — Ring group creation parameters
+     * @param params.name — Ring group name. Example: `'Sales Team'`
+     * @param params.strategy — Ring strategy: `'simultaneous'` (default), `'sequential'`, or `'random'`
+     * @param params.ringTimeout — Max seconds to ring before no-answer action (default: 30).
+     *   Example: `20`
+     * @param params.noAnswerAction — What to do when nobody answers:
+     *   `'voicemail'`, `'ivr'`, `'extension'`, `'hangup'`, `'ai_agent'`
+     * @param params.noAnswerTarget — Target for no-answer action
+     *   (extension number, IVR name, etc.)
+     * @param params.members — Array of member extensions.
+     *   Each has: `extension` (string), `priority` (number, lower = rings first for sequential),
+     *   `delaySeconds` (seconds to delay before ringing this member)
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `ringGroup: RingGroup` — The created ring group with members
+     *
+     * @throws {HttpError} 400 — Duplicate name, invalid extension in members, or missing required fields
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Create a sales team ring group — ring all at once
+     * const { ringGroup } = await voip.createRingGroup({
+     *   name: 'Sales Team',
+     *   strategy: 'simultaneous',
+     *   ringTimeout: 20,
+     *   noAnswerAction: 'voicemail',
+     *   noAnswerTarget: '1001',
+     *   members: [
+     *     { extension: '1001', priority: 1, delaySeconds: 0 },
+     *     { extension: '1002', priority: 1, delaySeconds: 0 },
+     *     { extension: '1003', priority: 1, delaySeconds: 0 },
+     *   ],
+     * });
+     *
+     * // Sequential ring group — try primary first, then backup
+     * const { ringGroup } = await voip.createRingGroup({
+     *   name: 'Support Escalation',
+     *   strategy: 'sequential',
+     *   ringTimeout: 15,
+     *   noAnswerAction: 'extension',
+     *   noAnswerTarget: '2000',
+     *   members: [
+     *     { extension: '1001', priority: 1, delaySeconds: 0 },
+     *     { extension: '1002', priority: 2, delaySeconds: 5 },
+     *     { extension: '1003', priority: 3, delaySeconds: 10 },
+     *   ],
+     * });
+     * ```
+     *
+     * @see POST /api/ring-groups
+     */
     async createRingGroup(params, options) {
         return this.request('POST', '/api/ring-groups', params, undefined, options);
     }
@@ -1085,7 +3148,46 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Paging Groups
     // -------------------------------------------------------------------
-    /** List paging groups */
+    /**
+     * List all paging groups for the current tenant.
+     *
+     * @description
+     * Returns every paging/intercom group configured for the tenant. A paging group
+     * enables one-way audio broadcast (PA system) to multiple extensions simultaneously
+     * with auto-answer. Use this for announcements, emergency alerts, or overhead paging.
+     *
+     * Each paging group includes:
+     * - `name` — Group name (e.g. "All Employees")
+     * - `extension_code` — The dial code that triggers paging (e.g. `*801`)
+     * - `members` — List of member extensions that receive the broadcast
+     *
+     * **CRM UI guidance:** Show as a table with columns: Name, Code, Members (count),
+     * Status, and Actions (Broadcast, Edit, Delete). The Broadcast button opens a
+     * modal to select a caller extension and sends the page. Show "No paging groups
+     * configured" empty state with a Create button if the list is empty.
+     *
+     * @returns An object containing:
+     *   - `pagingGroups: PagingGroup[]` — Array of paging group objects with members
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { pagingGroups } = await voip.listPagingGroups();
+     *
+     * pagingGroups.forEach(pg => {
+     *   console.log(`${pg.name} (${pg.extension_code}) — ${pg.members.length} members`);
+     * });
+     *
+     * // CRM UI: show broadcast button
+     * pagingGroups.forEach(pg => {
+     *   renderPagingRow(pg.name, pg.extension_code, pg.members.length);
+     *   renderBroadcastButton(pg.id, pg.name);
+     * });
+     * ```
+     *
+     * @see GET /api/paging-groups
+     */
     async listPagingGroups() {
         return this.request('GET', '/api/paging-groups');
     }
@@ -1093,7 +3195,76 @@ export class VoIPClient {
     async getPagingGroup(id) {
         return this.request('GET', `/api/paging-groups/${id}`);
     }
-    /** Create a paging group */
+    /**
+     * Create a new paging group for one-way audio broadcast.
+     *
+     * @description
+     * Sets up a group of extensions that receive auto-answer audio broadcasts when
+     * someone dials the `extensionCode` (e.g. `*801`). All online members hear the
+     * caller through their speaker — useful for announcements, emergency alerts,
+     * and overhead paging.
+     *
+     * **How it works:**
+     * 1. Admin creates a paging group with a dial code and member extensions
+     * 2. A user dials the code (e.g. `*801`) from their phone
+     * 3. All online members auto-answer — the caller's audio is broadcast
+     * 4. When the caller hangs up, all member calls end
+     *
+     * **Superadmin mode:** Pass `{ tenantId: 'uuid' }` when using a global superadmin
+     * key to create a paging group for a specific tenant.
+     *
+     * **CRM UI guidance:** Show a form with: Name (required, e.g. "All Employees"),
+     * Extension Code (required, e.g. `*801` — must be unique per tenant),
+     * Description (optional), and Members (multi-select from extension list).
+     * Show a preview of the dial code with "Users will dial *801 to page" hint.
+     *
+     * @param params — Paging group creation parameters
+     * @param params.name — Group name. Must be unique within the tenant.
+     *   Example: `'All Employees'`
+     * @param params.description — Optional description. Example: `'Broadcast to all office phones'`
+     * @param params.extensionCode — Dial code that triggers the page. Must start with `*`.
+     *   Example: `'*801'`. Must be unique within the tenant
+     * @param params.members — Array of member extensions to page.
+     *   Each has: `extension` (string, the extension number).
+     *   Example: `[{ extension: '1001' }, { extension: '1002' }]`
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `pagingGroup: PagingGroup` — The created paging group with members
+     *
+     * @throws {HttpError} 400 — Duplicate name or extension code, invalid code format, or extension doesn't exist
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Create an All Employees paging group
+     * const { pagingGroup } = await voip.createPagingGroup({
+     *   name: 'All Employees',
+     *   description: 'Emergency broadcast to all employees',
+     *   extensionCode: '*801',
+     *   members: [
+     *     { extension: '1001' },
+     *     { extension: '1002' },
+     *     { extension: '1003' },
+     *   ],
+     * });
+     *
+     * console.log(`Paging group created: dial ${pagingGroup.extension_code} to page ${pagingGroup.members.length} members`);
+     *
+     * // Create a department paging group
+     * const { pagingGroup } = await voip.createPagingGroup({
+     *   name: 'Support Floor',
+     *   extensionCode: '*802',
+     *   members: [
+     *     { extension: '2001' },
+     *     { extension: '2002' },
+     *   ],
+     * });
+     * ```
+     *
+     * @see POST /api/paging-groups
+     */
     async createPagingGroup(params, options) {
         return this.request('POST', '/api/paging-groups', params, undefined, options);
     }
@@ -1105,14 +3276,131 @@ export class VoIPClient {
     async deletePagingGroup(id) {
         return this.request('DELETE', `/api/paging-groups/${id}`);
     }
-    /** Broadcast a paging announcement to all online members */
+    /**
+     * Broadcast a paging announcement to all online members of a paging group via the API.
+     *
+     * @description
+     * Triggers a one-way audio broadcast to all currently online members of the specified
+     * paging group. The caller extension initiates the broadcast — all online members
+     * auto-answer and hear the caller through their speaker.
+     *
+     * This is the API-based alternative to dialing the paging code (`*801`) from a phone.
+     * Use this for programmatic paging — e.g. a "Broadcast" button in the admin dashboard,
+     * automated emergency alerts, or scheduled announcements.
+     *
+     * **How it works:**
+     * 1. The API creates a conference room with the caller as moderator
+     * 2. All online members are auto-called into the conference (listen-only, muted)
+     * 3. The caller speaks — all members hear through their speaker
+     * 4. When the caller hangs up, the conference auto-destroys
+     *
+     * **CRM UI guidance:** Show a "Broadcast" button next to each paging group.
+     * On click, open a modal: select the caller extension (dropdown of online extensions),
+     * and a "Start Broadcast" button. During broadcast, show a "Broadcasting..." indicator
+     * with the number of members reached vs offline. After completion, show results
+     * (membersOnline, membersContacted, status per extension).
+     *
+     * @param id — The UUID of the paging group (from `listPagingGroups()` → `pagingGroups[].id`)
+     * @param callerExtension — The extension number initiating the broadcast.
+     *   This extension will be the speaker. Example: `'1001'`
+     *
+     * @returns An object containing:
+     *   - `jobId: string` — Unique broadcast job ID for tracking
+     *   - `groupName: string` — The paging group name
+     *   - `conferenceName: string` — The conference room name created for this broadcast
+     *   - `membersContacted: number` — Number of members successfully reached
+     *   - `membersOnline: number` — Number of members that were online at broadcast time
+     *   - `membersTotal: number` — Total number of members in the group
+     *   - `results: Array<{ extension: string; status: 'online' | 'offline' }>` — Per-member status
+     *
+     * @throws {HttpError} 400 — Paging group not found, caller extension doesn't exist, or no members online
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 500 — FreeSWITCH conference creation failed
+     *
+     * @example
+     * ```typescript
+     * // Broadcast an emergency alert to all employees
+     * const result = await voip.broadcastPaging('paging-group-uuid', '1001');
+     *
+     * console.log(`Broadcasting to ${result.groupName}`);
+     * console.log(`Reached ${result.membersContacted}/${result.membersTotal} members`);
+     * console.log(`Online: ${result.membersOnline}, Offline: ${result.membersTotal - result.membersOnline}`);
+     *
+     * result.results.forEach(r => {
+     *   console.log(`  ${r.extension}: ${r.status}`);
+     * });
+     *
+     * // CRM UI: broadcast button with results modal
+     * async function handleBroadcast(pagingGroupId: string, callerExt: string) {
+     *   showBroadcastingModal(callerExt);
+     *   try {
+     *     const result = await voip.broadcastPaging(pagingGroupId, callerExt);
+     *     showBroadcastResultsModal({
+     *       reached: result.membersContacted,
+     *       online: result.membersOnline,
+     *       total: result.membersTotal,
+     *       results: result.results,
+     *     });
+     *   } catch (err) {
+     *     if (err instanceof HttpError && err.status === 400) {
+     *       showError('No members are online to receive the broadcast');
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @see POST /api/paging-groups/{id}/broadcast
+     */
     async broadcastPaging(id, callerExtension) {
         return this.request('POST', `/api/paging-groups/${id}/broadcast`, { callerExtension });
     }
     // -------------------------------------------------------------------
     // Call Queues
     // -------------------------------------------------------------------
-    /** List call queues */
+    /**
+     * List all call queues for the current tenant.
+     *
+     * @description
+     * Retrieves every call queue configured for the tenant. Each queue includes:
+     * - Queue name, strategy (round-robin, ring-all, longest-idle, etc.)
+     * - Music on hold, announcements, timeout settings
+     * - Agent list with priorities and penalties
+     * - Fallback actions when no agents are available or the caller times out
+     *
+     * Call queues are used for call center / ACD (Automatic Call Distribution) scenarios
+     * where multiple agents handle incoming calls.
+     *
+     * **CRM UI guidance:** Show as a table with columns: Queue Name, Strategy,
+     * Agents (count), Active Status, and Actions (Edit, Delete, Stats). Show a
+     * "Create Queue" button. Each row should link to a detail view showing agents,
+     * real-time stats, and queue configuration.
+     *
+     * @returns An object containing:
+     *   - `queues: CallQueue[]` — Array of call queue objects with agents
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { queues } = await voip.listQueues();
+     *
+     * queues.forEach(q => {
+     *   console.log(`${q.name} — ${q.strategy} — ${q.agents.length} agents`);
+     * });
+     *
+     * // CRM UI: queue overview with agent counts
+     * queues.forEach(q => {
+     *   const agentStatus = {
+     *     available: q.agents.filter(a => a.status === 'available').length,
+     *     busy: q.agents.filter(a => a.status === 'busy').length,
+     *     paused: q.agents.filter(a => a.status === 'paused').length,
+     *   };
+     *   renderQueueRow(q.name, q.strategy, agentStatus);
+     * });
+     * ```
+     *
+     * @see GET /api/queues
+     */
     async listQueues() {
         return this.request('GET', '/api/queues');
     }
@@ -1147,7 +3435,50 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Webhooks
     // -------------------------------------------------------------------
-    /** List webhooks */
+    /**
+     * List all webhook subscriptions for the current tenant, along with supported event types.
+     *
+     * @description
+     * Returns every webhook endpoint the tenant has configured, plus the list of all
+     * supported event types that can be subscribed to. Each webhook includes:
+     * - Name, URL, subscribed events, active status
+     * - Whether a signing secret is configured (`hasSecret`)
+     * - Custom headers, max retries, retry delay
+     *
+     * Webhooks are HTTP callbacks that fire when specific events occur in the phone system
+     * (call started, call ended, voicemail received, etc.). Use them to integrate the
+     * VoIP platform with external CRMs, ticketing systems, or analytics tools.
+     *
+     * **CRM UI guidance:** Show as a table with columns: Name, URL, Events (badge list),
+     * Status (active/inactive), and Actions (Edit, Delete, Test). Show the supported
+     * events list in a sidebar or tooltip for reference when creating/editing webhooks.
+     *
+     * @returns An object containing:
+     *   - `webhooks: Webhook[]` — Array of webhook subscription objects
+     *   - `supportedEvents: string[]` — All event types available for subscription.
+     *     Examples: `'call.start'`, `'call.end'`, `'call.answer'`, `'voicemail.received'`,
+     *     `'recording.ready'`, `'presence.change'`, `'queue.agent.login'`
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { webhooks, supportedEvents } = await voip.listWebhooks();
+     *
+     * console.log(`Available events: ${supportedEvents.join(', ')}`);
+     *
+     * webhooks.forEach(wh => {
+     *   console.log(`${wh.name} → ${wh.url} [${wh.events.join(', ')}] — ${wh.active ? 'Active' : 'Inactive'}`);
+     * });
+     *
+     * // CRM UI: populate event checkboxes when creating a webhook
+     * supportedEvents.forEach(event => {
+     *   renderEventCheckbox(event, `${event}.description`);
+     * });
+     * ```
+     *
+     * @see GET /api/webhooks
+     */
     async listWebhooks() {
         return this.request('GET', '/api/webhooks');
     }
@@ -1155,7 +3486,76 @@ export class VoIPClient {
     async getWebhook(id) {
         return this.request('GET', `/api/webhooks/${id}`);
     }
-    /** Create a webhook. Pass `options.tenantId` when using a global superadmin key. */
+    /**
+     * Create a new webhook subscription.
+     *
+     * @description
+     * Registers a URL to receive HTTP POST callbacks when specific events occur in the
+     * phone system. The response includes the signing secret (`secret`) — store this
+     * immediately because it is only returned once (during creation).
+     *
+     * **Signing secret:** The secret is used to verify that incoming webhook requests
+     * actually came from the VoIP platform. The platform sends an `X-Webhook-Signature`
+     * header with each delivery — your endpoint should compute the HMAC-SHA256 of the
+     * request body using this secret and compare it to the header value.
+     *
+     * **Superadmin mode:** Pass `{ tenantId: 'uuid' }` when using a global superadmin
+     * key to create a webhook for a specific tenant.
+     *
+     * **CRM UI guidance:** Show a form with fields: Name (required), URL (required),
+     * Events (checkboxes — use `supportedEvents` from `listWebhooks()`), Secret
+     * (optional, auto-generate button), Custom Headers (optional, key-value editor),
+     * Max Retries, Retry Delay. After creation, show the secret prominently:
+     * "Copy this secret now — it will not be shown again" with a Copy button.
+     *
+     * @param params — Webhook creation parameters
+     * @param params.name — Human-readable name for this webhook. Example: `'CRM Call Logger'`
+     * @param params.url — The HTTPS URL to send events to. Example: `'https://my-crm.example.com/api/webhooks/voip'`
+     * @param params.events — Array of event types to subscribe to.
+     *   Example: `['call.start', 'call.end', 'voicemail.received', 'recording.ready']`
+     * @param params.secret — Optional signing secret (auto-generated if omitted, recommended)
+     * @param params.headers — Optional custom HTTP headers to include in each delivery.
+     *   Example: `{ 'X-Custom-Header': 'value' }`
+     * @param params.maxRetries — Max delivery retry attempts (default: 5)
+     * @param params.retryDelaySeconds — Delay between retries in seconds (default: 60)
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `webhook: Webhook & { secret: string }` — The created webhook object with
+     *     the signing secret (only returned once!)
+     *
+     * @throws {HttpError} 400 — Invalid URL, duplicate name, or invalid event types
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Create a webhook for call logging
+     * const { webhook } = await voip.createWebhook({
+     *   name: 'CRM Call Logger',
+     *   url: 'https://my-crm.example.com/api/webhooks/voip',
+     *   events: ['call.start', 'call.end', 'call.answer'],
+     *   maxRetries: 3,
+     * });
+     *
+     * console.log(`Webhook secret (save this!): ${webhook.secret}`);
+     *
+     * // CRM UI: handle webhook creation
+     * async function handleCreateWebhook(formData: CreateWebhookParams) {
+     *   try {
+     *     const { webhook } = await voip.createWebhook(formData);
+     *     showSecretModal(webhook.secret); // "Copy and save this secret!"
+     *     showNotification(`Webhook "${formData.name}" created`);
+     *   } catch (err) {
+     *     if (err instanceof HttpError && err.status === 400) {
+     *       showError('Invalid URL or duplicate webhook name');
+     *     }
+     *   }
+     * }
+     * ```
+     *
+     * @see POST /api/webhooks
+     */
     async createWebhook(params, options) {
         return this.request('POST', '/api/webhooks', params, undefined, options);
     }
@@ -1178,23 +3578,251 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // Voicemail
     // -------------------------------------------------------------------
-    /** List voicemail messages with pagination */
+    /**
+     * List voicemail messages with pagination and optional filters.
+     *
+     * @description
+     * Retrieves a paginated list of voicemail messages for the current tenant. Each message
+     * includes caller ID, duration, read status, urgency, and an `audio_url` for playback.
+     * Use this to populate a voicemail inbox UI — similar to an email inbox but for voice.
+     *
+     * Each voicemail includes:
+     * - `id` — UUID for read/delete operations
+     * - `caller_id` — Phone number or extension that left the message
+     * - `caller_name` — Name if Caller ID lookup was performed
+     * - `duration_seconds` — Length of the message
+     * - `is_read` — Whether the message has been heard
+     * - `is_urgent` — Whether the caller marked it urgent (pressing * after recording)
+     * - `audio_url` — URL to stream the audio (append `?apiKey=...` for browser playback)
+     * - `created_at` — ISO timestamp when the message was left
+     *
+     * **CRM UI guidance:** Show as an inbox-style list with columns: Status (unread dot),
+     * Caller, Duration, Date, and a Play button. Unread messages should be bold or have
+     * a blue dot indicator. Urgent messages should have a red exclamation mark. Show
+     * "Mark Read" button per message and a "Delete" button with confirmation.
+     * Show pagination at the bottom.
+     *
+     * @param params — Optional filters and pagination
+     * @param params.page — Page number (1-based, default 1)
+     * @param params.limit — Records per page (default 50)
+     * @param params.unreadOnly — Show only unread messages when `true`
+     * @param params.extension — Filter by extension number (e.g. `'1001'`)
+     *
+     * @returns An object containing:
+     *   - `messages: VoicemailMessage[]` — Array of voicemail messages
+     *   - `unread: number` — Total count of unread messages (for badge)
+     *   - `pagination: PaginationInfo` — `{ page, limit, total, pages }`
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // List all voicemails
+     * const { messages, unread, pagination } = await voip.listVoicemails({ limit: 25 });
+     *
+     * console.log(`${unread} unread voicemails (${pagination.total} total)`);
+     *
+     * // Show unread messages first
+     * const { messages } = await voip.listVoicemails({ unreadOnly: true });
+     *
+     * // Play a voicemail in the browser
+     * messages.forEach(msg => {
+     *   const audioUrl = voip.buildUrl(msg.audio_url);
+     *   // Render: <audio src={audioUrl} preload="none" controls />
+     * });
+     *
+     * // CRM UI: voicemail inbox with unread badge
+     * const { messages, unread } = await voip.listVoicemails({ page: 1, limit: 50 });
+     * updateUnreadBadge(unread); // Show "3" badge on Voicemail tab
+     * renderVoicemailInbox(messages);
+     * ```
+     *
+     * @see GET /api/voicemail
+     */
     async listVoicemails(params) {
         return this.request('GET', '/api/voicemail', undefined, params);
     }
-    /** Get voicemail count (total and unread) */
+    /**
+     * Get voicemail count (total and unread) for an extension.
+     *
+     * @description
+     * Returns the total number of voicemail messages and the unread count for the specified
+     * extension. This is ideal for displaying a badge counter on the voicemail tab or
+     * menu item — poll this periodically to keep the badge up to date.
+     *
+     * If no extension is specified, returns counts for the authenticated user's extension
+     * (when using JWT/extension-level auth). When using an API key with admin scope,
+     * you must specify the extension.
+     *
+     * **CRM UI guidance:** Call this every 15-30 seconds via `setInterval` to keep the
+     * unread badge updated. Show the count as a red circle badge: "Voicemail (3⦁)".
+     * When counts are zero, hide the badge or show a gray "(0)" indicator.
+     *
+     * @param extension — Optional extension number (e.g. `'1001'`). If not specified,
+     *   uses the authenticated user's extension
+     *
+     * @returns An object containing:
+     *   - `total: number` — Total number of voicemail messages
+     *   - `unread: number` — Number of unread messages (for badge display)
+     *   - `extension: string` — The extension these counts belong to
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Check unread count for extension 1001
+     * const { total, unread } = await voip.getVoicemailCount('1001');
+     * console.log(`${unread} unread / ${total} total voicemails for 1001`);
+     *
+     * // CRM UI: update badge every 30 seconds
+     * setInterval(async () => {
+     *   const { unread } = await voip.getVoicemailCount('1001');
+     *   updateVoicemailBadge(unread > 0 ? unread : null);
+     * }, 30000);
+     * ```
+     *
+     * @see GET /api/voicemail/count
+     */
     async getVoicemailCount(extension) {
         return this.request('GET', '/api/voicemail/count', undefined, extension ? { extension } : undefined);
     }
-    /** Get a single voicemail */
+    /**
+     * Get a single voicemail message by its UUID.
+     *
+     * @description
+     * Returns full details for one voicemail message including caller ID, duration,
+     * read status, urgency, audio URL for playback, and any linked call record.
+     * Use this to show a detailed voicemail view with playback controls and metadata.
+     *
+     * @param id — The UUID of the voicemail message (from `listVoicemails()` → `messages[].id`)
+     *
+     * @returns A `VoicemailMessage` object containing:
+     *   - `id` — UUID for read/delete operations
+     *   - `caller_id` — Phone number or extension that left the message
+     *   - `caller_name` — Name if Caller ID lookup was performed
+     *   - `duration_seconds` — Length of the message in seconds
+     *   - `is_read` — Whether the message has been heard
+     *   - `is_urgent` — Whether the caller marked it urgent
+     *   - `audio_url` — URL to stream the audio (use `buildUrl()` for browser playback)
+     *   - `call` — Linked call record (null if no matching call found)
+     *   - `created_at` — ISO timestamp when the message was left
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Voicemail not found
+     *
+     * @example
+     * ```typescript
+     * const msg = await voip.getVoicemail('voicemail-uuid-here');
+     *
+     * console.log(`From: ${msg.caller_id}`);
+     * console.log(`Name: ${msg.caller_name || 'Unknown'}`);
+     * console.log(`Duration: ${msg.duration_seconds}s`);
+     * console.log(`Urgent: ${msg.is_urgent ? 'Yes' : 'No'}`);
+     *
+     * // Play the audio
+     * const audioUrl = voip.buildUrl(msg.audio_url);
+     * audioElement.src = audioUrl;
+     * audioElement.play();
+     * ```
+     *
+     * @see GET /api/voicemail/{id}
+     */
     async getVoicemail(id) {
         return this.request('GET', `/api/voicemail/${id}`);
     }
-    /** Mark voicemail as read */
+    /**
+     * Mark a voicemail message as read (heard).
+     *
+     * @description
+     * Sets the `is_read` flag to `true` and records the `read_at` timestamp for the
+     * specified voicemail message. This also decrements the unread count for the
+     * associated extension.
+     *
+     * **CRM UI guidance:** Call this automatically when the user clicks "Play" on a
+     * voicemail — don't wait for them to finish listening. Also show a "Mark as Read"
+     * button for messages the user has already heard but wants to acknowledge.
+     * After marking, update the row to remove the bold/unread indicator and update
+     * the unread badge count.
+     *
+     * @param id — The UUID of the voicemail message (from `listVoicemails()` → `messages[].id`)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. `'Voicemail marked as read'`)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Voicemail not found
+     *
+     * @example
+     * ```typescript
+     * // Mark as read when user clicks Play
+     * async function handlePlayVoicemail(msg: VoicemailMessage) {
+     *   const audioUrl = voip.buildUrl(msg.audio_url);
+     *   audioElement.src = audioUrl;
+     *   audioElement.play();
+     *
+     *   // Mark as read immediately on play
+     *   if (!msg.is_read) {
+     *     await voip.markVoicemailRead(msg.id);
+     *     markRowAsRead(msg.id); // Remove bold/unread dot
+     *     decrementUnreadBadge();
+     *   }
+     * }
+     *
+     * // CRM UI: "Mark Read" button
+     * async function handleMarkRead(voicemailId: string) {
+     *   await voip.markVoicemailRead(voicemailId);
+     *   markRowAsRead(voicemailId);
+     *   showNotification('Marked as read');
+     * }
+     * ```
+     *
+     * @see PUT /api/voicemail/{id}/read
+     */
     async markVoicemailRead(id) {
         return this.request('PUT', `/api/voicemail/${id}/read`);
     }
-    /** Delete a voicemail (hard delete — removes audio file from disk) */
+    /**
+     * Permanently delete a voicemail message (hard delete — removes audio file from disk).
+     *
+     * @description
+     * Deletes the voicemail record from the database AND removes the audio file from
+     * disk storage. This is irreversible. The voicemail will disappear from the inbox
+     * and cannot be recovered.
+     *
+     * **CRM UI guidance:** Show a confirmation dialog before deleting: "Permanently
+     * delete this voicemail from [caller]? This cannot be undone." After deletion,
+     * remove the row from the list immediately to avoid showing a stale entry.
+     *
+     * @param id — The UUID of the voicemail message (from `listVoicemails()` → `messages[].id`)
+     *
+     * @returns An object containing:
+     *   - `message: string` — Confirmation message (e.g. `'Voicemail deleted'`)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Voicemail not found
+     *
+     * @example
+     * ```typescript
+     * // Delete a single voicemail
+     * await voip.deleteVoicemail('voicemail-uuid-here');
+     *
+     * // CRM UI: Delete button with confirmation
+     * async function handleDeleteVoicemail(msg: VoicemailMessage) {
+     *   if (!confirm(`Delete voicemail from ${msg.caller_id}? This cannot be undone.`)) {
+     *     return;
+     *   }
+     *   try {
+     *     await voip.deleteVoicemail(msg.id);
+     *     removeVoicemailRow(msg.id); // Remove from list immediately
+     *     showNotification('Voicemail deleted');
+     *   } catch (err) {
+     *     showError('Failed to delete voicemail');
+     *   }
+     * }
+     * ```
+     *
+     * @see DELETE /api/voicemail/{id}
+     */
     async deleteVoicemail(id) {
         return this.request('DELETE', `/api/voicemail/${id}`);
     }
@@ -1273,17 +3901,59 @@ export class VoIPClient {
     // Presence (REST)
     // -------------------------------------------------------------------
     /**
-     * Get presence for all extensions.
-     * Pass `{ detailed: true }` to include call info (callUuid, caller, direction, etc.).
+     * Get presence status for all extensions in the tenant.
+     *
+     * @description
+     * Retrieves real-time presence information for every extension. Two modes:
+     *
+     * - **Simple** (default): Returns a map of extension number → status string.
+     *   Status values: `'available'`, `'on_call'`, `'offline'`, `'do_not_disturb'`
+     * - **Detailed** (`{ detailed: true }`): Returns rich objects with call info when
+     *   the extension is on a call, including `callUuid`, `caller`, `direction`, `since`.
+     *
+     * Use simple mode for status indicators (colored dots) and detailed mode for
+     * call-aware features like "Busy — on call with +1555..." tooltips.
+     *
+     * **CRM UI guidance (simple):** Show presence as a colored dot next to each
+     * extension name. Green = available, orange = on call, gray = offline,
+     * red = do not disturb. Poll every 5-10 seconds.
+     *
+     * **CRM UI guidance (detailed):** Hover over the colored dot to show a tooltip:
+     * "On call with +17865551234 (3:42)". Use this for the extension detail panel
+     * or operator console.
+     *
+     * @param options — Optional mode selector
+     * @param options.detailed — When `true`, returns detailed presence with call info.
+     *   Each value is a `PresenceDetail` object instead of a string
+     *
+     * @returns An object containing:
+     *   - `presence: PresenceMap | PresenceDetailMap` — Map of `extension_number → status_string`
+     *     (simple) or `extension_number → PresenceDetail` (detailed)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
      *
      * @example
-     * // Simple presence
+     * ```typescript
+     * // Simple presence — extension list with colored dots
      * const { presence } = await voip.getPresence();
-     * // { '1001': 'available', '1002': 'on_call' }
+     * // { '1001': 'available', '1002': 'on_call', '1003': 'offline' }
+     *
+     * Object.entries(presence).forEach(([ext, status]) => {
+     *   const color = { available: 'green', on_call: 'orange', offline: 'gray', do_not_disturb: 'red' }[status];
+     *   console.log(`${ext}: ${color} ${status}`);
+     * });
      *
      * // Detailed presence with call info
      * const { presence } = await voip.getPresence({ detailed: true });
-     * // { '1001': { status: 'on_call', callUuid: '...', caller: '+1555...' } }
+     * // { '1002': { status: 'on_call', callUuid: '...', caller: '+1555...', direction: 'inbound' } }
+     *
+     * if (presence['1002'].status === 'on_call') {
+     *   console.log(`1002 is on call with ${presence['1002'].caller}`);
+     * }
+     * ```
+     *
+     * @see GET /api/presence
+     * @see GET /api/presence/detailed
      */
     async getPresence(options) {
         if (options?.detailed) {
@@ -1291,33 +3961,318 @@ export class VoIPClient {
         }
         return this.request('GET', '/api/presence');
     }
-    /** Set manual presence status for an extension (busy / available / offline) */
+    /**
+     * Set manual presence status for an extension.
+     *
+     * @description
+     * Overrides the automatic presence detection (which is based on SIP registration and
+     * call activity) with a manual status. Use this when an agent wants to appear
+     * "busy" even though they're not on a call, or "offline" when they're leaving for
+     * the day.
+     *
+     * Manual presence is sticky — it remains until the extension changes it again
+     * or until the extension's call activity forces a natural status update (e.g.
+     * the extension goes on a call, which sets it to `'on_call'`).
+     *
+     * **CRM UI guidance:** Show a presence selector dropdown next to the user's name:
+     * Available (green dot), Busy (orange dot), Offline (gray dot). Store the selected
+     * value in local state. On change, call `setPresence()` and update the local UI.
+     *
+     * @param extensionId — The UUID of the extension (from `listExtensions()` → `extensions[].id`)
+     * @param status — The desired manual presence:
+     *   - `'available'` — Available to take calls (green)
+     *   - `'busy'` — Not accepting calls (orange)
+     *   - `'offline'` — Signed out / away (gray)
+     *
+     * @returns An object containing:
+     *   - `ok: boolean` — `true` if the status was set
+     *   - `extension: string` — The extension number
+     *   - `status: string` — The new presence status
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Extension not found
+     *
+     * @example
+     * ```typescript
+     * // Set yourself as busy — don't route calls to me
+     * await voip.setPresence('extension-uuid', 'busy');
+     *
+     * // Set yourself as available again
+     * await voip.setPresence('extension-uuid', 'available');
+     *
+     * // Go offline at end of day
+     * await voip.setPresence('extension-uuid', 'offline');
+     *
+     * // CRM UI: presence selector dropdown
+     * async function handlePresenceChange(extId: string, newStatus: string) {
+     *   try {
+     *     await voip.setPresence(extId, newStatus);
+     *     updatePresenceIndicator(newStatus);
+     *     showNotification(`Status changed to ${newStatus}`);
+     *   } catch (err) {
+     *     showError('Failed to update presence');
+     *   }
+     * }
+     * ```
+     *
+     * @see PUT /api/extensions/{id}/presence
+     */
     async setPresence(extensionId, status) {
         return this.request('PUT', `/api/extensions/${extensionId}/presence`, { status });
     }
     // -------------------------------------------------------------------
     // Reports
     // -------------------------------------------------------------------
-    /** Get dashboard summary stats */
+    /**
+     * Get dashboard summary statistics for the current tenant.
+     *
+     * @description
+     * Returns high-level KPIs for the admin dashboard landing page:
+     * - Total extensions configured
+     * - Total DIDs (phone numbers) assigned
+     * - Calls today (since midnight)
+     * - Calls this month
+     *
+     * **CRM UI guidance:** Display as 4 KPI cards at the top of the dashboard.
+     * Each card shows a large number with a label below, using icons:
+     * - 📞 Extensions (phone icon)
+     * - 📱 DIDs (smartphone icon)
+     * - 📊 Calls Today (chart icon)
+     * - 📅 Calls This Month (calendar icon)
+     * Refresh every 60 seconds or on page reload.
+     *
+     * @returns An object containing:
+     *   - `dashboard: object` — `{ extensions, dids, callsToday, callsThisMonth }`
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { dashboard } = await voip.getDashboardStats();
+     *
+     * console.log(`Extensions: ${dashboard.extensions}`);
+     * console.log(`DIDs: ${dashboard.dids}`);
+     * console.log(`Calls Today: ${dashboard.callsToday}`);
+     * console.log(`Calls This Month: ${dashboard.callsThisMonth}`);
+     *
+     * // CRM UI: render KPI cards
+     * function renderDashboardStats(stats: DashboardStats['dashboard']) {
+     *   showKpiCard('Extensions', stats.extensions, '📞');
+     *   showKpiCard('DIDs', stats.dids, '📱');
+     *   showKpiCard('Calls Today', stats.callsToday, '📊');
+     *   showKpiCard('Calls This Month', stats.callsThisMonth, '📅');
+     * }
+     * ```
+     *
+     * @see GET /api/reports/dashboard
+     */
     async getDashboardStats() {
         return this.request('GET', '/api/reports/dashboard');
     }
-    /** Get calls grouped by day */
+    /**
+     * Get call counts grouped by day for charting and trend analysis.
+     *
+     * @description
+     * Returns a date → stats map showing call volume per day, broken down by direction
+     * (inbound, outbound, internal) with total duration. Use this to render a bar chart
+     * or line chart showing call trends over time.
+     *
+     * **CRM UI guidance:** Render as a bar chart with days on the X-axis and call counts
+     * on the Y-axis. Use stacked bars for inbound/outbound/internal. Hover over a bar
+     * to show a tooltip: "Mon: 45 calls (28 inbound, 12 outbound, 5 internal)".
+     * Use a chart library like Chart.js, Recharts, or visx.
+     *
+     * @param days — Number of recent days to include. Default: 7. Example: `30` for a monthly chart
+     *
+     * @returns An object containing:
+     *   - `callsByDay: Record<string, DayStats>` — Map of `'YYYY-MM-DD'` → `{ total, inbound, outbound, internal, totalDuration }`
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Get last 7 days for a weekly trend chart
+     * const { callsByDay } = await voip.getCallsByDay(7);
+     *
+     * // Format for charting
+     * const chartData = Object.entries(callsByDay).map(([date, stats]) => ({
+     *   date,
+     *   inbound: stats.inbound,
+     *   outbound: stats.outbound,
+     *   internal: stats.internal,
+     *   total: stats.total,
+     * }));
+     *
+     * // Last 30 days for monthly trend
+     * const { callsByDay } = await voip.getCallsByDay(30);
+     *
+     * // CRM UI: chart rendering
+     * const labels = chartData.map(d => d.date.slice(5)); // '06-01', '06-02', ...
+     * const inboundData = chartData.map(d => d.inbound);
+     * const outboundData = chartData.map(d => d.outbound);
+     * renderStackedBarChart(labels, [
+     *   { label: 'Inbound', data: inboundData, color: '#4CAF50' },
+     *   { label: 'Outbound', data: outboundData, color: '#2196F3' },
+     * ]);
+     * ```
+     *
+     * @see GET /api/reports/calls-by-day
+     */
     async getCallsByDay(days) {
         return this.request('GET', '/api/reports/calls-by-day', undefined, days ? { days } : undefined);
     }
-    /** Get top extensions by call volume */
+    /**
+     * Get top extensions ranked by call volume.
+     *
+     * @description
+     * Returns the busiest extensions in the tenant, ranked by total call count and
+     * total call duration. Use this for:
+     * - "Top Performers" leaderboard on the dashboard
+     * - Identifying overloaded extensions that need backup
+     * - Call center agent performance reports
+     *
+     * **CRM UI guidance:** Render as a horizontal bar chart or ranked table.
+     * Show: Rank, Extension Number, Display Name, Total Calls, Total Duration.
+     * Use a podium icon for the top 3. Show a period selector (7d, 30d, 90d).
+     *
+     * @param days — Number of recent days to analyze. Default: 7. Example: `30`
+     * @param limit — Maximum number of extensions to return. Default: 10. Example: `5`
+     *
+     * @returns An object containing:
+     *   - `topExtensions: TopExtension[]` — Array of `{ extension, totalCalls, totalDuration }` sorted by call count descending
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Top 10 extensions in last 7 days
+     * const { topExtensions } = await voip.getTopExtensions(7, 10);
+     *
+     * topExtensions.forEach((ext, i) => {
+     *   const hours = Math.floor(ext.totalDuration / 3600);
+     *   const mins = Math.floor((ext.totalDuration % 3600) / 60);
+     *   console.log(`#${i + 1} ${ext.extension}: ${ext.totalCalls} calls (${hours}h ${mins}m)`);
+     * });
+     *
+     * // CRM UI: leaderboard
+     * function renderTopExtensions(extensions: TopExtension[]) {
+     *   extensions.forEach((ext, i) => {
+     *     const rank = i + 1;
+     *     const medal = rank <= 3 ? ['🥇', '🥈', '🥉'][i] : `#${rank}`;
+     *     const duration = formatDuration(ext.totalDuration); // "3h 24m"
+     *     renderLeaderboardRow(medal, ext.extension, ext.totalCalls, duration);
+     *   });
+     * }
+     * ```
+     *
+     * @see GET /api/reports/top-extensions
+     */
     async getTopExtensions(days, limit) {
         return this.request('GET', '/api/reports/top-extensions', undefined, { days, limit });
     }
     // -------------------------------------------------------------------
     // Blocklist (Call Blocking)
     // -------------------------------------------------------------------
-    /** List all blocked numbers for the tenant */
+    /**
+     * List all blocked phone numbers for the tenant.
+     *
+     * @description
+     * Returns every number that has been added to the tenant's call blocklist.
+     * Inbound calls from blocked numbers are automatically rejected with a "Number
+     * not in service" tone or a custom message. Outbound calls to blocked numbers
+     * are prevented.
+     *
+     * Each blocked number includes:
+     * - `number` — The blocked phone number
+     * - `reason` — Optional reason for blocking (e.g. "Spam caller")
+     * - `direction` — `'inbound'` (block incoming), `'outbound'` (block outgoing), or `'both'`
+     * - `created_at` — When the number was blocked
+     *
+     * **CRM UI guidance:** Show as a table with columns: Phone Number, Direction,
+     * Reason, Blocked Date, and an "Unblock" button. Add a search bar to find
+     * specific numbers. Show a "Block Number" button that opens a form with
+     * number, direction selector, and reason field.
+     *
+     * @returns An object containing:
+     *   - `blocked: BlockedNumber[]` — Array of blocked number entries
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { blocked } = await voip.listBlockedNumbers();
+     *
+     * blocked.forEach(b => {
+     *   console.log(`${b.number} — ${b.direction || 'both'} — ${b.reason || 'No reason'}`);
+     * });
+     * ```
+     *
+     * @see GET /api/blocklist
+     */
     async listBlockedNumbers() {
         return this.request('GET', '/api/blocklist');
     }
-    /** Block a phone number. Pass `options.tenantId` when using a global superadmin key. */
+    /**
+     * Block a phone number from calling or being called.
+     *
+     * @description
+     * Adds a number to the tenant's call blocklist. Once blocked:
+     * - Inbound calls from this number are automatically rejected
+     * - Outbound calls to this number are prevented (when direction is `'outbound'` or `'both'`)
+     *
+     * **Superadmin mode:** Pass `{ tenantId: 'uuid' }` when using a global superadmin
+     * key to block a number in a specific tenant.
+     *
+     * **CRM UI guidance:** Show a "Block Number" button on call records, voicemail
+     * messages, and the blocklist page. On click, open a form with: Number (pre-filled
+     * if coming from a call record), Direction (inbound/outbound/both), Reason (optional
+     * text — "Spam", "Harassment", "Wrong number", etc.). After blocking, show a
+     * confirmation and refresh the blocklist.
+     *
+     * @param params — Block parameters
+     * @param params.number — The phone number to block (E.164 format recommended).
+     *   Example: `'+17865559999'`
+     * @param params.reason — Optional reason for blocking. Example: `'Spam caller'`
+     * @param params.direction — Which direction to block:
+     *   `'inbound'` — Calls FROM this number are blocked,
+     *   `'outbound'` — Calls TO this number are blocked,
+     *   `'both'` — Both directions (default)
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `blocked: BlockedNumber` — The created blocklist entry with `id`, `number`, `reason`, `direction`, `created_at`
+     *
+     * @throws {HttpError} 400 — Number is already blocked or format is invalid
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Block a spam caller
+     * await voip.blockNumber({ number: '+17865559999', reason: 'Spam caller', direction: 'inbound' });
+     *
+     * // Block outgoing calls to a premium number
+     * await voip.blockNumber({ number: '+19005551234', reason: 'Premium rate', direction: 'outbound' });
+     *
+     * // Block both directions
+     * await voip.blockNumber({ number: '+17865558888', reason: 'Harassment', direction: 'both' });
+     *
+     * // CRM UI: Block button on call detail
+     * async function blockCaller(call: CallRecord) {
+     *   if (!confirm(`Block ${call.caller_id_number}? They will no longer be able to call you.`)) {
+     *     return;
+     *   }
+     *   await voip.blockNumber({
+     *     number: call.caller_id_number,
+     *     reason: 'Blocked by user',
+     *     direction: 'inbound',
+     *   });
+     *   showNotification(`${call.caller_id_number} has been blocked`);
+     * }
+     * ```
+     *
+     * @see POST /api/blocklist
+     */
     async blockNumber(params, options) {
         return this.request('POST', '/api/blocklist', params, undefined, options);
     }
@@ -1325,14 +4280,108 @@ export class VoIPClient {
     async unblockNumber(id) {
         return this.request('DELETE', `/api/blocklist/${id}`);
     }
-    /** Check if a specific number is blocked */
+    /**
+     * Check if a specific phone number is blocked.
+     *
+     * @description
+     * Looks up a phone number in the tenant's blocklist and returns whether it's blocked
+     * along with the blocklist entry details. Use this for:
+     * - Incoming call screen pop — check if the caller is blocked before answering
+     * - Warning indicator on call detail pages — show "Number is blocked" banner
+     * - Pre-dial validation — check if a number is blocked before originating a call
+     *
+     * **CRM UI guidance:** Call this when a call comes in (in the WebSocket `call_start`
+     * handler) and show a red "BLOCKED" banner if the number is on the blocklist.
+     * Also call this before originating outbound calls — show a warning if the
+     * destination is blocked.
+     *
+     * @param number — The phone number to check (E.164 format recommended).
+     *   Example: `'+17865559999'`
+     *
+     * @returns An object containing:
+     *   - `blocked: boolean` — `true` if the number is in the blocklist
+     *   - `entry: BlockedNumber | null` — The blocklist entry if blocked, `null` otherwise.
+     *     Contains `id`, `number`, `reason`, `direction`, `created_at`
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Check a caller before answering
+     * const { blocked, entry } = await voip.checkBlocked('+17865559999');
+     * if (blocked) {
+     *   console.log(`Blocked: ${entry.number} — Reason: ${entry.reason}`);
+     *   showBlockedBanner(entry);
+     * } else {
+     *   showIncomingCallBanner('+17865559999');
+     * }
+     *
+     * // Pre-dial check before originating a call
+     * async function safeOriginate(fromExt: string, toNumber: string) {
+     *   const { blocked, entry } = await voip.checkBlocked(toNumber);
+     *   if (blocked) {
+     *     showWarning(`Cannot call ${toNumber} — it is blocked (${entry.reason || 'no reason given'})`);
+     *     return;
+     *   }
+     *   return voip.originate({ fromExtension: fromExt, toNumber });
+     * }
+     *
+     * // CRM UI: screen pop on incoming call
+     * voip.on('call_start', async (data) => {
+     *   const { blocked, entry } = await voip.checkBlocked(data.caller_id_number);
+     *   if (blocked) {
+     *     showScreenPop({ type: 'blocked', caller: data.caller_id_number, reason: entry.reason });
+     *   } else {
+     *     showScreenPop({ type: 'incoming', caller: data.caller_id_number, name: data.caller_id_name });
+     *   }
+     * });
+     * ```
+     *
+     * @see GET /api/blocklist/check/{number}
+     */
     async checkBlocked(number) {
         return this.request('GET', `/api/blocklist/check/${encodeURIComponent(number)}`);
     }
     // -------------------------------------------------------------------
     // Business Hours / Schedules
     // -------------------------------------------------------------------
-    /** List business hour schedules */
+    /**
+     * List all business hour schedules for the tenant.
+     *
+     * @description
+     * Returns every business hours schedule configured for the tenant. Each schedule
+     * defines open hours per day of the week, holidays, and after-hours call routing.
+     *
+     * Each schedule includes:
+     * - `name` — Schedule name (e.g. "Standard Business Hours")
+     * - `timezone` — IANA timezone (e.g. `'America/Chicago'`)
+     * - `schedules` — Array of day definitions with enabled flag and start/end times
+     * - `holidays` — Holiday dates with names
+     * - `after_hours_action` — What happens when the schedule is closed
+     *   (`'voicemail'`, `'ivr'`, `'extension'`, `'hangup'`, `'ai_agent'`)
+     * - `after_hours_target` — The target for after-hours routing
+     *
+     * **CRM UI guidance:** Show as a table with columns: Name, Timezone, Open Days
+     * (icons for each day), After-Hours Action, Status, Actions (Edit, Delete).
+     * Add a "Check Status" button that calls `getScheduleStatus()`.
+     *
+     * @returns An object containing:
+     *   - `schedules: BusinessSchedule[]` — Array of schedule objects
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * const { schedules } = await voip.listSchedules();
+     *
+     * schedules.forEach(s => {
+     *   const openDays = s.schedules?.filter(d => d.enabled).map(d => d.day).join(', ') || 'None';
+     *   console.log(`${s.name} | ${s.timezone} | Open: ${openDays}`);
+     * });
+     * ```
+     *
+     * @see GET /api/schedules
+     */
     async listSchedules() {
         return this.request('GET', '/api/schedules');
     }
@@ -1340,7 +4389,67 @@ export class VoIPClient {
     async getSchedule(id) {
         return this.request('GET', `/api/schedules/${id}`);
     }
-    /** Create a business hours schedule. Pass `options.tenantId` when using a global superadmin key. */
+    /**
+     * Create a business hours schedule.
+     *
+     * @description
+     * Defines when a business is open/closed for call routing purposes. Incoming calls
+     * during open hours follow normal routing; calls outside open hours are routed
+     * according to the `afterHoursAction` setting (voicemail, IVR, another extension,
+     * or an external number).
+     *
+     * **Superadmin mode:** Pass `{ tenantId: 'uuid' }` when using a global superadmin
+     * key to create a schedule for a specific tenant.
+     *
+     * **CRM UI guidance:** Show a form with: Name (required), Timezone (dropdown of
+     * IANA timezones), Day-of-week grid (toggle + start/end time per day), Holidays
+     * (date picker + name), After-Hours Action (select: voicemail/IVR/extension),
+     * After-Hours Target (dynamic based on action type).
+     *
+     * @param params — Schedule creation parameters
+     * @param params.name — Human-readable schedule name. Example: `'Standard Business Hours'`
+     * @param params.timezone — IANA timezone string. Example: `'America/Chicago'`
+     * @param params.schedules — Array of day definitions. Each has:
+     *   `day` (`'monday'`-`'sunday'`), `enabled` (boolean), `startTime` (HH:MM), `endTime` (HH:MM)
+     * @param params.holidays — Array of holiday dates with optional names.
+     *   Example: `[{ date: '2026-12-25', name: 'Christmas' }]`
+     * @param params.afterHoursAction — Action when closed:
+     *   `'voicemail'`, `'ivr'`, `'extension'`, `'hangup'`, `'external'`, `'ai_agent'`
+     * @param params.afterHoursTarget — Target for after-hours routing
+     *   (extension number, IVR name, phone number, etc.)
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `schedule: BusinessSchedule` — The created schedule object
+     *
+     * @throws {HttpError} 400 — Invalid timezone, missing required fields, or name already exists
+     * @throws {HttpError} 401 — Missing or invalid API key
+     *
+     * @example
+     * ```typescript
+     * // Create standard 9-to-5 business hours
+     * const { schedule } = await voip.createSchedule({
+     *   name: 'Standard Business Hours',
+     *   timezone: 'America/Chicago',
+     *   schedules: [
+     *     { day: 'monday', enabled: true, startTime: '09:00', endTime: '17:00' },
+     *     { day: 'tuesday', enabled: true, startTime: '09:00', endTime: '17:00' },
+     *     { day: 'wednesday', enabled: true, startTime: '09:00', endTime: '17:00' },
+     *     { day: 'thursday', enabled: true, startTime: '09:00', endTime: '17:00' },
+     *     { day: 'friday', enabled: true, startTime: '09:00', endTime: '17:00' },
+     *   ],
+     *   holidays: [
+     *     { date: '2026-12-25', name: 'Christmas Day' },
+     *     { date: '2027-01-01', name: "New Year's Day" },
+     *   ],
+     *   afterHoursAction: 'voicemail',
+     *   afterHoursTarget: '1001',
+     * });
+     * ```
+     *
+     * @see POST /api/schedules
+     */
     async createSchedule(params, options) {
         return this.request('POST', '/api/schedules', params, undefined, options);
     }
@@ -1352,14 +4461,93 @@ export class VoIPClient {
     async deleteSchedule(id) {
         return this.request('DELETE', `/api/schedules/${id}`);
     }
-    /** Check if a schedule is currently open or closed */
+    /**
+     * Check if a schedule is currently open or closed based on its timezone and current time.
+     *
+     * @description
+     * Evaluates the schedule's day-of-week definitions and holiday list against the
+     * current time in the schedule's timezone. Returns whether the business is
+     * currently "open" (accepting calls normally) or "closed" (after-hours routing active).
+     *
+     * **CRM UI guidance:** Show an "Open" or "Closed" badge on the schedule detail
+     * page and in the schedule list. Use a green badge for "Open", red for "Closed".
+     * Poll this every 60 seconds to keep the status indicator accurate.
+     *
+     * @param id — The UUID of the schedule to check (from `listSchedules()` → `schedules[].id`)
+     *
+     * @returns An object containing:
+     *   - `isOpen: boolean` — `true` if current time is within business hours
+     *   - `schedule: string` — The schedule name
+     *   - `timezone: string` — The schedule's timezone
+     *   - `currentTime: string` — Current time in the schedule's timezone (ISO string)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 404 — Schedule not found
+     *
+     * @example
+     * ```typescript
+     * const { isOpen, schedule, currentTime } = await voip.getScheduleStatus('schedule-uuid');
+     *
+     * if (isOpen) {
+     *   console.log(`${schedule} is OPEN — ${currentTime}`);
+     * } else {
+     *   console.log(`${schedule} is CLOSED — calls go to after-hours routing`);
+     * }
+     *
+     * // CRM UI: show open/closed badge
+     * const { isOpen } = await voip.getScheduleStatus(scheduleId);
+     * if (isOpen) {
+     *   showBadge('Open', 'green');
+     * } else {
+     *   showBadge('Closed', 'red');
+     * }
+     * ```
+     *
+     * @see GET /api/schedules/{id}/status
+     */
     async getScheduleStatus(id) {
         return this.request('GET', `/api/schedules/${id}/status`);
     }
     // -------------------------------------------------------------------
     // SIP Trunks
     // -------------------------------------------------------------------
-    /** List SIP trunks (passwords masked) */
+    /**
+     * List all SIP trunks (passwords are masked in the response).
+     *
+     * @description
+     * Returns every SIP trunk configured in the system. Trunks can be:
+     * - **Global** (`tenant_id: null`) — Shared across all tenants for outbound calling
+     * - **Tenant-specific** — Assigned to a single tenant
+     *
+     * Each trunk includes gateway configuration (proxy, username, transport, codec prefs),
+     * registration settings, channel limits, and optional live gateway status from FreeSWITCH.
+     *
+     * For security, SIP passwords are ALWAYS masked in list/get responses.
+     * Only `createTrunk()` returns the raw password (and only if you're a superadmin).
+     *
+     * **CRM UI guidance (superadmin only):** Show as a table with columns: Name,
+     * Provider, Gateway, Status (active/inactive), Tenant (or "Global"), and Actions
+     * (Edit, Sync, Delete). Show a live gateway status indicator (UP/DOWN) if available.
+     *
+     * @returns An object containing:
+     *   - `trunks: SipTrunk[]` — Array of SIP trunk objects (passwords masked)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 403 — Not a superadmin
+     *
+     * @example
+     * ```typescript
+     * const { trunks } = await voip.listTrunks();
+     *
+     * trunks.forEach(t => {
+     *   const scope = t.tenant_id ? `Tenant: ${t.tenants?.company_name}` : 'Global';
+     *   const gwStatus = t.gatewayStatus?.status || 'Unknown';
+     *   console.log(`${t.name} | ${t.provider} | ${scope} | Gateway: ${gwStatus}`);
+     * });
+     * ```
+     *
+     * @see GET /api/trunks
+     */
     async listTrunks() {
         return this.request('GET', '/api/trunks');
     }
@@ -1406,7 +4594,51 @@ export class VoIPClient {
     // -------------------------------------------------------------------
     // API Keys
     // -------------------------------------------------------------------
-    /** List API keys for the current tenant (admin only) */
+    /**
+     * List all API keys for the current tenant (admin only).
+     *
+     * @description
+     * Returns every API key created for the tenant. For security, the full key value
+     * is NEVER returned — only a masked preview (e.g. `csk_live_••••••••abcd1234`).
+     * The full key is returned only once during `createApiKey()` or `regenerateApiKey()`.
+     *
+     * Each API key includes:
+     * - `name` — Human-readable label
+     * - `keyPreview` — Masked preview of the key (e.g. `csk_live_••••••••abcd1234`)
+     * - `role` — `'admin'`, `'readonly'`, `'user'`, or `'superadmin'`
+     * - `scopes` — Granular permission scopes
+     * - `lastUsedAt` — Last time the key was used (null if never)
+     * - `expiresAt` — Expiration date (null if never expires)
+     * - `status` — `'active'` or `'revoked'`
+     *
+     * **CRM UI guidance:** Show as a table with columns: Name, Key Preview (masked),
+     * Role, Last Used, Expires, Status (active/revoked badge), and Actions
+     * (Regenerate, Revoke). Show a warning banner if any keys are expiring soon.
+     * Never display full keys in the list — only on create/regenerate modals.
+     *
+     * @returns An object containing:
+     *   - `apiKeys: ApiKey[]` — Array of API key objects (keys are masked)
+     *
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 403 — Not an admin
+     *
+     * @example
+     * ```typescript
+     * const { apiKeys } = await voip.listApiKeys();
+     *
+     * // CRM UI: API key table
+     * apiKeys.forEach(key => {
+     *   console.log(`${key.name} | ${key.keyPreview} | ${key.role} | ${key.status}`);
+     *
+     *   // Warning: key expires soon
+     *   if (key.expiresAt && new Date(key.expiresAt).getTime() - Date.now() < 7 * 86400000) {
+     *     showWarning(`Key "${key.name}" expires soon`);
+     *   }
+     * });
+     * ```
+     *
+     * @see GET /api/api-keys
+     */
     async listApiKeys() {
         return this.request('GET', '/api/api-keys');
     }
@@ -1414,7 +4646,95 @@ export class VoIPClient {
     async getApiKeyDetail(id) {
         return this.request('GET', `/api/api-keys/${id}`);
     }
-    /** Create a new API key. The full key is only returned once in the response. Pass `options.tenantId` when using a global superadmin key. */
+    /**
+     * Create a new API key. The full key value is only returned once in this response.
+     *
+     * @description
+     * Generates a new API key for programmatic access to the VoIP API. The full key
+     * (in the format `csk_live_...`) is returned in the `key` field of the response —
+     * **this is the ONLY time you will see the full key**. Store it immediately in a
+     * secure location (password manager, environment variable, or secrets vault).
+     *
+     * API keys support granular role-based access:
+     * - `'admin'` — Full CRUD access within the tenant
+     * - `'readonly'` — Read-only access (GET endpoints only)
+     * - `'user'` — Extension-level access (make/receive calls)
+     * - `'superadmin'` — Cross-tenant access (superadmin only, requires `global: true`)
+     *
+     * **Superadmin mode:** Set `global: true` to create a global key with no tenant
+     * binding (access to ALL tenants). Pass `tenantId` to create a key for a specific
+     * tenant when authenticated as superadmin.
+     *
+     * **CRM UI guidance:** After creation, show a modal with the full key prominently
+     * displayed: "Copy this key now — it will not be shown again." Include a "Copy"
+     * button and a "I have saved this key" confirmation before closing. Never store
+     * or log the full key client-side.
+     *
+     * @param params — API key creation parameters
+     * @param params.name — Human-readable name for this key. Example: `'CRM Integration Key'`
+     * @param params.role — Access role: `'admin'` (default), `'readonly'`, `'user'`, or `'superadmin'`
+     * @param params.scopes — Optional granular permission scopes. Example: `['calls:read', 'extensions:write']`
+     * @param params.expiresAt — Optional ISO date string when the key expires.
+     *   Example: `'2027-01-01T00:00:00Z'`. Omit for no expiry
+     * @param params.global — Superadmin only: create a global key with no tenant binding
+     * @param params.tenantId — Superadmin only: specify the tenant this key belongs to
+     * @param options — Optional request overrides
+     * @param options.tenantId — Target tenant UUID (required for superadmin keys only)
+     *
+     * @returns An object containing:
+     *   - `apiKey: ApiKey` — The created API key object. The full key is in `apiKey.key`
+     *     (only returned once). Also includes `keyPreview` (masked), `role`, `scopes`,
+     *     `expiresAt`, `status`, `createdAt`
+     *
+     * @throws {HttpError} 400 — Invalid role, scope, or duplicate name
+     * @throws {HttpError} 401 — Missing or invalid API key
+     * @throws {HttpError} 403 — Not an admin or trying to create a superadmin key without permission
+     *
+     * @example
+     * ```typescript
+     * // Create an admin key for the CRM integration
+     * const { apiKey } = await voip.createApiKey({
+     *   name: 'CRM Integration',
+     *   role: 'admin',
+     * });
+     *
+     * console.log(`Full key (save this!): ${apiKey.key}`); // csk_live_xxxx...
+     * console.log(`Masked preview: ${apiKey.keyPreview}`); // csk_live_••••••••xxxx
+     *
+     * // Create a readonly key that expires in 90 days
+     * const expiry = new Date(Date.now() + 90 * 86400000).toISOString();
+     * const { apiKey } = await voip.createApiKey({
+     *   name: 'Read-Only Report Key',
+     *   role: 'readonly',
+     *   scopes: ['calls:read', 'recordings:read'],
+     *   expiresAt: expiry,
+     * });
+     *
+     * // Superadmin: create a global key
+     * const { apiKey } = await voip.createApiKey({
+     *   name: 'Superadmin Global',
+     *   role: 'superadmin',
+     *   global: true,
+     * });
+     *
+     * // CRM UI: handle key creation with secret modal
+     * async function handleCreateApiKey(formData: CreateApiKeyParams) {
+     *   try {
+     *     const { apiKey } = await voip.createApiKey(formData);
+     *     showSecretModal({
+     *       title: 'API Key Created',
+     *       secret: apiKey.key,
+     *       message: 'Copy this key now — it will not be shown again.',
+     *     });
+     *     refreshApiKeyList();
+     *   } catch (err) {
+     *     showError('Failed to create API key');
+     *   }
+     * }
+     * ```
+     *
+     * @see POST /api/api-keys
+     */
     async createApiKey(params, options) {
         return this.request('POST', '/api/api-keys', params, undefined, options);
     }