@cemscale-voip/voip-sdk 2.0.10 → 2.0.12

package/dist/types.d.ts

@@ -1,30 +1,108 @@
+/**
+ * Parameters for logging in as an extension user (softphone / SDK consumer).
+ *
+ * Extensions authenticate with their extension number + password, scoped to a tenant.
+ * After login you receive a JWT token valid for the tenant.
+ *
+ * @example
+ * ```ts
+ * const { token, user } = await voip.login({
+ *   username: '1001',
+ *   password: 'my-sip-password',
+ *   tenantId: 'uuid-of-tenant',
+ * });
+ * ```
+ */
 export interface LoginParams {
+    /** Extension number (e.g. `"1001"`, `"2005"`). 3-6 digit identifier within a tenant. */
     username: string;
+    /** SIP password set on the extension. Case-sensitive, min 6 characters. */
     password: string;
+    /** UUID of the tenant this extension belongs to. Obtain this from the dashboard or from the list of tenants. */
     tenantId: string;
 }
+/**
+ * Parameters for logging in as a tenant admin (dashboard user).
+ *
+ * Tenant admins authenticate with email + password and get a JWT that allows
+ * management of their own tenant's resources (extensions, DIDs, queues, etc.).
+ *
+ * @example
+ * ```ts
+ * const { token, tenant } = await voip.adminLogin({
+ *   email: 'admin@acme.com',
+ *   password: 'admin-password',
+ * });
+ * ```
+ */
 export interface AdminLoginParams {
+    /** Admin email address for the tenant (set during tenant creation). */
     email: string;
+    /** Admin password for the tenant admin account. */
     password: string;
 }
+/**
+ * Response from both `login()` (extension) and `adminLogin()` (admin).
+ *
+ * Always contains a JWT `token`. The SDK stores this internally and attaches it
+ * to subsequent requests as `Authorization: Bearer <token>`.
+ *
+ * For extension login, `user` is populated with the extension profile.
+ * For admin login, `tenant` is populated. Global superadmin login populates both.
+ */
 export interface AuthResponse {
+    /** JWT token (HS256). Store this and pass it to the SDK constructor or set on the client. Expires based on server config (default 24h). */
     token: string;
+    /** Extension profile — populated when logging in as an extension user. Null for admin logins. */
     user?: {
+        /** Extension UUID in the database (not the extension number). */
         id: string;
+        /** Extension number string (e.g. `"1001"`). */
         extension: string;
+        /** Human-readable display name. `null` if not set on the extension. */
         displayName: string | null;
+        /** UUID of the tenant this extension belongs to. */
         tenantId: string;
     };
+    /** Tenant info — populated when logging in as an admin or superadmin. Null for extension-only logins. */
     tenant?: {
+        /** Tenant UUID. */
         id: string;
+        /** Subdomain slug (e.g. `"acme"`). Used in URLs like `acme.demo.cemscale.com`. */
         subdomain: string;
+        /** Company/tenant display name (e.g. `"Acme Corp"`). */
         companyName: string;
     };
 }
+/**
+ * TURN/STUN credentials for WebRTC ICE negotiation.
+ *
+ * The TURN server relays media when a direct peer-to-peer connection can't be
+ * established (NAT, firewall). These credentials are time-limited (default 86400s).
+ *
+ * Retrieve via `getTurnCredentials()`. Pass to the WebRTCPhone constructor.
+ *
+ * @example
+ * ```ts
+ * const creds = await voip.getTurnCredentials();
+ * const phone = new WebRTCPhone({
+ *   ...sipConfig,
+ *   turnServers: [{
+ *     urls: creds.urls,
+ *     username: creds.username,
+ *     credential: creds.credential,
+ *   }],
+ * });
+ * ```
+ */
 export interface TurnCredentials {
+    /** TURN server URLs (e.g. `["turn:3.20.219.41:3478?transport=udp", "turns:3.20.219.41:5349?transport=tcp"]`). */
     urls: string[];
+    /** Temporary TURN username generated for this session. Format: `<expiry_timestamp>:<extension>`. */
     username: string;
+    /** HMAC-SHA1 credential derived from the TURN secret + username. Valid only until expiry. */
     credential: string;
+    /** Time-to-live in seconds (default 86400 = 24 hours). Credentials expire after this. */
     ttl: number;
 }
 /**
@@ -77,20 +155,31 @@ export interface TurnCredentials {
  * database, send them in emails, or cache them indefinitely.
  */
 export interface CallRecord {
+    /** Database record UUID. Use this for `getCall(id)`, `getRecordingUrl(id)`, and the recording audio endpoint `/api/recordings/<id>/audio`. Distinguish from `call_uuid` which is the FreeSWITCH-level identifier. */
     id: string;
+    /** Tenant UUID the call belongs to. Present for tenant-scoped queries; may be absent if querying as superadmin across all tenants. */
     tenant_id?: string;
+    /** FreeSWITCH call UUID. This is the server-side channel identifier used in FreeSWITCH commands (e.g. `uuid_kill`). Different from `id` (the DB record UUID). Use `call_uuid` for live call operations, `id` for API/CDR lookups. Example: `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`. */
     call_uuid: string;
+    /** Direction of the call relative to the tenant: `'inbound'` (PSTN → extension), `'outbound'` (extension → PSTN), `'internal'` (extension → extension within same tenant). */
     direction: 'inbound' | 'outbound' | 'internal';
+    /** Display name from the caller's SIP header. `null` if not provided by the carrier. Example: `"John Doe"`. */
     caller_id_name: string | null;
+    /** E.164 caller phone number. `null` if the caller number was hidden/unknown. Example: `"+17865551234"`. */
     caller_id_number: string | null;
+    /** Destination of the call. For inbound calls this is the DID or extension DNIS. For outbound calls this is the dialed PSTN number. `null` for some internal calls. Example: `"+17869876543"` or `"1001"`. */
     destination: string | null;
+    /** Call outcome: `'completed'` (answered + hung up normally), `'failed'` (never connected), `'missed'` (rang but not answered), `'voicemail'` (went to voicemail). `null` for in-progress or unknown state. */
     status: string | null;
+    /** FreeSWITCH hangup cause code string (e.g. `"NORMAL_CLEARING"`, `"NO_ANSWER"`, `"USER_BUSY"`). `null` if the call hasn't ended. */
     hangup_cause: string | null;
+    /** Total call duration in seconds from start to end. `null` for active/unfinished calls. */
     duration_seconds: number | null;
+    /** Billable seconds — from answer to hangup. `null` if call was never answered. Always ≤ `duration_seconds`. */
     billsec: number | null;
-    /** External number the call was forwarded to. Null if no forwarding occurred. */
+    /** External number the call was forwarded to. Null if no forwarding occurred. Example: `"+13051234567"`. */
     forwarded_to?: string | null;
-    /** Whether a voicemail message was left by the caller */
+    /** Whether a voicemail message was left by the caller. `true` = voicemail left, `false` or `null` = no voicemail. */
     was_voicemail?: boolean | null;
     /**
      * API endpoint URL for streaming/downloading the call recording.
@@ -138,42 +227,81 @@ export interface CallRecord {
      * ```
      */
     cdn_url: string | null;
+    /** ISO 8601 timestamp when the call was initiated. `null` for pre-CDR records. Example: `"2025-06-04T14:30:00.000Z"`. */
     started_at: string | null;
+    /** ISO 8601 timestamp when the call was answered (picked up). `null` if never answered. Example: `"2025-06-04T14:30:05.000Z"`. */
     answered_at: string | null;
+    /** ISO 8601 timestamp when the call ended (hung up). `null` for active calls. Example: `"2025-06-04T14:32:30.000Z"`. */
     ended_at: string | null;
+    /** Arbitrary key-value metadata attached to the call. `null` if no metadata was set. */
     metadata?: Record<string, unknown> | null;
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin — contains tenant details for this call. */
     tenants?: TenantInfo;
-    /** Present when queried as global superadmin (convenience top-level fields) */
+    /** Present when queried as global superadmin (convenience top-level fields). Tenant company name. */
     company_name?: string;
+    /** Present when queried as global superadmin (convenience top-level fields). Tenant subdomain. */
     subdomain?: string;
 }
+/**
+ * Standard pagination metadata returned by all list endpoints.
+ *
+ * Use `pages` to render page controls and `total` for summary text.
+ * On the last page, `page` === `pages`.
+ */
 export interface PaginationInfo {
+    /** Current page number (1-indexed). Example: `1`. */
     page: number;
+    /** Number of items per page as requested. Example: `50`. */
     limit: number;
+    /** Total number of items across all pages. Example: `142`. */
     total: number;
+    /** Total number of pages. Example: `3`. Computed as `Math.ceil(total / limit)`. */
     pages: number;
 }
+/**
+ * Response from `listCalls()` — a paginated list of call detail records.
+ *
+ * Use `pagination.total` for a summary badge and `pagination.pages` for pagination controls.
+ */
 export interface CallListResponse {
     calls: CallRecord[];
     pagination: PaginationInfo;
 }
+/**
+ * Filtering/pagination params for `listCalls()`.
+ *
+ * All fields are optional. Omitted fields are not filtered (returns all matching records).
+ * Combine filters: `{ direction: 'inbound', status: 'completed', dateFrom: '2025-06-01' }`
+ * returns only completed inbound calls since June 1.
+ *
+ * @example
+ * ```ts
+ * // Get last 10 missed inbound calls
+ * const { calls } = await voip.listCalls({
+ *   direction: 'inbound',
+ *   status: 'missed',
+ *   limit: 10,
+ * });
+ * ```
+ */
 export interface CallListParams {
+    /** Page number (1-indexed). Default: `1`. */
     page?: number;
-    /** Max 500 per page */
+    /** Max 500 per page. Default: `50`. */
     limit?: number;
+    /** Filter by call direction. Default: `'all'` (no filter). */
     direction?: 'inbound' | 'outbound' | 'internal' | 'all';
-    /** Filter by call status */
+    /** Filter by call status. Default: `'all'` (no filter). */
     status?: 'completed' | 'failed' | 'missed' | 'voicemail' | 'all';
-    /** ISO date string — calls started on or after this date */
+    /** ISO date string — calls started on or after this date. Example: `"2025-06-01T00:00:00.000Z"`. */
     dateFrom?: string;
-    /** ISO date string — calls started on or before this date */
+    /** ISO date string — calls started on or before this date. Example: `"2025-06-04T23:59:59.999Z"`. */
     dateTo?: string;
-    /** Filter by extension number (matches caller or destination) */
+    /** Filter by extension number (matches caller or destination). Example: `"1001"`. */
     extension?: string;
-    /** Search by phone number or name (matches caller_id_number, destination, caller_id_name) */
+    /** Search by phone number or name (matches caller_id_number, destination, caller_id_name). Partial match, case-insensitive. Example: `"+1786"`. */
     number?: string;
-    /** Filter by tenant ID (superadmin only — alternative to X-Tenant-ID header) */
+    /** Filter by tenant ID (superadmin only — alternative to X-Tenant-ID header). */
     tenantId?: string;
     /**
      * Filter by forwarding status.
@@ -182,52 +310,178 @@ export interface CallListParams {
      * - omit:      return all calls regardless of forwarding
      */
     forwarded?: 'true' | 'false';
-    /** Search by the external number the call was forwarded to (partial match, case-insensitive) */
+    /** Search by the external number the call was forwarded to (partial match, case-insensitive). */
     forwardedTo?: string;
 }
+/**
+ * Parameters for originating (placing) a new outbound call from a webphone/extension.
+ *
+ * The server creates a new call leg from the specified extension to the PSTN number
+ * and bridges it to the extension's WebRTC session.
+ *
+ * @example
+ * ```ts
+ * const { callUuid } = await voip.originateCall({
+ *   fromExtension: '1001',
+ *   toNumber: '+17865551234',
+ * });
+ * ```
+ */
 export interface OriginateParams {
+    /** Extension number to originate the call from. Must be an active extension in your tenant. Example: `"1001"`. */
     fromExtension: string;
+    /** Destination PSTN number in E.164 format. Example: `"+17865551234"`. */
     toNumber: string;
 }
+/**
+ * Response from `originateCall()`.
+ *
+ * Contains the FreeSWITCH UUID of the outbound call leg for monitoring.
+ */
 export interface OriginateResponse {
+    /** Human-readable status message. Example: `"Call originated successfully"`. */
     message: string;
+    /** FreeSWITCH call UUID of the originated outbound leg. Use this to track the call. */
     callUuid: string;
 }
+/**
+ * Parameters for transferring an active call to another destination.
+ *
+ * Supports blind transfer (immediate, no consultation) and attended transfer
+ * (speak to the target first, then merge).
+ *
+ * @example
+ * ```ts
+ * // Blind transfer — caller goes directly to target
+ * await voip.transferCall(callId, {
+ *   targetExtension: '1002',
+ *   type: 'blind',
+ * });
+ *
+ * // Attended transfer — you speak first, then complete the transfer
+ * await voip.transferCall(callId, {
+ *   targetExtension: '1002',
+ *   type: 'attended',
+ * });
+ * ```
+ */
 export interface TransferParams {
+    /** Target extension number to transfer the call to. Example: `"1002"`. */
     targetExtension: string;
+    /** Transfer type. `'blind'` = immediate (SIP REFER). `'attended'` = consult then complete (conference bridge). Default: `'blind'`. */
     type?: 'blind' | 'attended';
 }
+/**
+ * Response from call eavesdropping (listen in on an active call).
+ *
+ * Returned by `eavesdropCall()`. Supports whisper (coach can talk to the agent
+ * without the caller hearing), spy (listen-only), and full (3-way join).
+ */
 export interface EavesdropResponse {
+    /** Human-readable message. Example: `"Whisper session started"`. */
     message: string;
+    /** FreeSWITCH UUID of the eavesdrop channel. */
     spyUuid: string;
+    /** FreeSWITCH UUID of the target call being monitored. */
     targetCallUuid: string;
+    /** Eavesdrop mode: `'whisper'`, `'spy'`, or `'full'`. */
     mode: string;
 }
+/**
+ * A currently active (in-progress) call on the FreeSWITCH server.
+ *
+ * Returned by `listActiveCalls()`. Each entry represents one call leg (channel).
+ * For a two-party call, you'll see two entries — one for each leg.
+ *
+ * **Key field:** `uuid` — this is the FreeSWITCH channel UUID required for
+ * three-way calling operations (`addCallParticipant`, `mergeCalls`).
+ * It is NOT the same as `call_uuid` (which is the logical call identifier).
+ *
+ * @example
+ * ```ts
+ * // List all active calls and show the caller/destination
+ * const { calls } = await voip.listActiveCalls();
+ * calls.forEach(c => {
+ *   console.log(`${c.caller_id_number} → ${c.destination} (${c.status})`);
+ * });
+ * ```
+ */
 export interface ActiveCall {
+    /** FreeSWITCH channel UUID — required for three-way operations. This is the server-side channel identifier. Example: `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`. */
+    uuid: string;
+    /** Logical call UUID (same across both legs of a bridged call). Use for CDR matching and WebSocket event correlation. Example: `"c0ffee00-dead-beef-0000-000000000001"`. */
     call_uuid: string;
+    /** Caller display name from SIP header. Example: `"John Smith"`. */
     caller_id_name: string;
+    /** Caller phone number. Example: `"+17865551234"` or `"1001"` for internal calls. */
     caller_id_number: string;
+    /** Destination of the call. For outbound calls this is the PSTN number being dialed. For inbound this is the DID or extension. Example: `"+17869876543"`. */
     destination: string;
+    /** Call direction: `'inbound'`, `'outbound'`, or `'internal'`. */
     direction: string;
+    /** Channel state: `'CS_EXECUTE'`, `'CS_CONSUME_MEDIA'`, `'CS_HIBERNATE'`, etc. Use `answered` boolean for high-level state. */
     status: string;
+    /** ISO 8601 timestamp when the call channel was created. Example: `"2025-06-04T14:30:00Z"`. */
     started_at: string;
+    /** Whether the call has been answered (both parties connected). `false` during ringing/early-media. */
     answered: boolean;
+    /** Whether this channel currently has music-on-hold active. */
     on_hold: boolean;
 }
+/**
+ * Quick call statistics for the current tenant (today and this month).
+ *
+ * Returned by `getCallStats()`. Use for dashboard summary badges.
+ *
+ * @example
+ * ```ts
+ * const { stats } = await voip.getCallStats();
+ * console.log(`Today: ${stats.total} calls (${stats.inbound} in, ${stats.outbound} out)`);
+ * ```
+ */
 export interface CallStats {
     stats: {
+        /** Total calls in the current period. */
         total: number;
+        /** Inbound calls in the current period. */
         inbound: number;
+        /** Outbound calls in the current period. */
         outbound: number;
+        /** Internal (extension-to-extension) calls in the current period. */
         internal: number;
+        /** Period description: `'today'` or `'month'`. */
         period: string;
     };
 }
+/**
+ * A SIP extension (phone user) within a tenant.
+ *
+ * Extensions are the core entity — every person who makes/receives calls has one.
+ * Each extension has a SIP password for registration, voicemail settings,
+ * call forwarding rules, recording preferences, and real-time presence status.
+ *
+ * Returned by `listExtensions()`, `getExtension()`, `createExtension()`, and `updateExtension()`.
+ *
+ * @example
+ * ```ts
+ * // List all extensions and show their presence
+ * const { extensions } = await voip.listExtensions();
+ * extensions.forEach(ext => {
+ *   const presenceIcon = ext.presence === 'on_call' ? '🟢' : ext.presence === 'offline' ? '⚫' : '⭕';
+ *   console.log(`${presenceIcon} ${ext.extension} — ${ext.display_name}`);
+ * });
+ * ```
+ */
 export interface Extension {
+    /** Database UUID of the extension record. */
     id: string;
+    /** Tenant UUID this extension belongs to. Present for tenant-scoped queries; may be absent in superadmin global lists. */
     tenant_id?: string;
+    /** Extension number (3-6 digits). Used for dialing internally and as the SIP username. Example: `"1001"`. */
     extension: string;
+    /** Human-readable display name shown to other callers and in the dashboard. `null` if not set. Example: `"John Smith"`. */
     display_name: string | null;
+    /** Whether voicemail is enabled for this extension. When enabled, unanswered calls go to voicemail after the ring timeout. Example: `true`. */
     voicemail_enabled: boolean;
     /**
      * Whether call recording is enabled for this extension.
@@ -241,31 +495,68 @@ export interface Extension {
      * The tenant must also have `noise_cancellation_enabled = true` (the default) for NC to apply.
      */
     noise_cancellation_enabled?: boolean;
+    /** 4-6 digit PIN required to access voicemail via *97. `null` if no PIN is set (voicemail has no password protection). */
     voicemail_pin?: string | null;
+    /** Type of voicemail greeting: `'default'`, `'name'`, `'custom_audio'`, `'custom_tts'`. `null` if using default system greeting. */
     voicemail_greeting_type?: VoicemailGreetingType | null;
+    /** Text spoken for TTS greeting. `null` if not using TTS. Example: `"You've reached John. Please leave a message."`. */
     voicemail_greeting_text?: string | null;
+    /** Server path to uploaded custom audio greeting file. `null` if no custom audio. */
     voicemail_greeting_audio_path?: string | null;
+    /** Whether Do Not Disturb is enabled. When true, calls go directly to voicemail without ringing. */
     do_not_disturb: boolean;
+    /** Outbound caller ID (DID number) shown to recipients when this extension makes outbound calls. Falls back to tenant's first active DID if `null`. Example: `"+17868392727"`. */
     outbound_caller_id?: string | null;
+    /** Extension status: `'active'` (can register and make/receive calls), `'disabled'` (cannot register or call). */
     status: string;
-    /** Real-time presence status: 'available', 'on_call', 'offline', 'do_not_disturb' */
+    /** Real-time presence status from Redis: `'available'`, `'on_call'`, `'offline'`, `'do_not_disturb'`. Use for presence indicators in the UI. Not persisted — comes from live registration/call state. */
     presence?: string;
+    /** ISO 8601 timestamp when this extension was created. Example: `"2025-01-15T10:30:00.000Z"`. */
     created_at: string;
+    /** Whether unconditional call forwarding is enabled. */
     call_forward_enabled?: boolean;
+    /** Number to forward calls to when `call_forward_enabled` is true. E.164 for external, extension number for internal. Example: `"+13051234567"`. */
     call_forward_number?: string | null;
+    /** Forward type: `'always'`, `'busy'`, or `'no-answer'`. `null` when forwarding is disabled. */
     call_forward_type?: string | null;
+    /** External CRM user ID for integration mapping. `null` if not linked to a CRM record. */
     crm_user_id?: string | null;
+    /** Arbitrary JSON metadata from CRM integration. `null` if no metadata set. */
     crm_metadata?: Record<string, unknown> | null;
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin — contains tenant details. */
     tenants?: TenantInfo;
 }
+/**
+ * Parameters for creating a new SIP extension.
+ *
+ * At minimum, provide `extension`, `password`, and `displayName`.
+ * All other fields are optional with sensible defaults.
+ *
+ * @example
+ * ```ts
+ * // Create a basic extension with voicemail PIN
+ * const { extension: ext } = await voip.createExtension({
+ *   extension: '2001',
+ *   password: 'secure123',
+ *   displayName: 'Alice Jones',
+ *   voicemailEnabled: true,
+ *   voicemailPin: '1234',
+ *   outboundCallerId: '+17868392727',
+ * }, { tenantId: 'tenant-uuid' });
+ * ```
+ */
 export interface CreateExtensionParams {
+    /** Extension number (3-6 digits). Must be unique within the tenant. Example: `"2001"`. */
     extension: string;
+    /** SIP password for registration. Min 6 characters. Used by desk phones and WebRTC softphones to authenticate. Example: `"secure123"`. */
     password: string;
+    /** Human-readable display name. Shown to other callers via caller ID name. Example: `"Alice Jones"`. */
     displayName: string;
+    /** Enable voicemail for this extension. Default: `true`. */
     voicemailEnabled?: boolean;
-    /** 4-6 digit PIN required to check voicemail via *97. If not set, voicemail has no PIN protection. */
+    /** 4-6 digit PIN required to check voicemail via *97. If not set, voicemail has no PIN protection. Example: `"1234"`. */
     voicemailPin?: string;
+    /** Initial Do Not Disturb state. Default: `false`. */
     doNotDisturb?: boolean;
     /**
      * Whether to record all calls for this extension.
@@ -290,13 +581,38 @@ export interface CreateExtensionParams {
      */
     outboundCallerId?: string | null;
 }
+/**
+ * Parameters for updating an existing SIP extension.
+ *
+ * All fields are optional — only include fields you want to change.
+ * Send `null` for string fields (like `voicemailPin`, `outboundCallerId`, `crmUserId`) to clear them.
+ *
+ * @example
+ * ```ts
+ * // Rename extension and enable DND
+ * await voip.updateExtension(extId, {
+ *   displayName: 'Alice J.',
+ *   doNotDisturb: true,
+ * });
+ *
+ * // Clear the outbound caller ID (revert to tenant default)
+ * await voip.updateExtension(extId, {
+ *   outboundCallerId: null,
+ * });
+ * ```
+ */
 export interface UpdateExtensionParams {
+    /** New display name. Example: `"Alice Jones-Smith"`. */
     displayName?: string;
+    /** New SIP password. Min 6 characters. */
     password?: string;
+    /** Enable or disable voicemail. */
     voicemailEnabled?: boolean;
     /** 4-6 digit PIN for voicemail access. Set to null to remove PIN protection. */
     voicemailPin?: string | null;
+    /** Enable or disable Do Not Disturb. When true, calls go straight to voicemail. */
     doNotDisturb?: boolean;
+    /** Set extension status: `'active'` (can register/call) or `'disabled'` (blocked). */
     status?: 'active' | 'disabled';
     /**
      * Enable or disable call recording for this extension.
@@ -317,7 +633,9 @@ export interface UpdateExtensionParams {
      * Set to `null` to clear (calls will fall back to the tenant's first active DID).
      */
     outboundCallerId?: string | null;
+    /** CRM user ID for integration mapping. Set to `null` to unlink. */
     crmUserId?: string | null;
+    /** Arbitrary JSON metadata from CRM. Set to `null` to clear. */
     crmMetadata?: Record<string, unknown> | null;
 }
 export interface Tenant {
@@ -741,12 +1059,21 @@ export interface RecordingUrlResponse {
     /** Always `null` — CDN URLs and local URLs don't expire. */
     expiresIn: number | null;
 }
+/**
+ * Filtering/pagination params for `listRecordings()`.
+ *
+ * All fields optional. Omit a field to skip that filter.
+ */
 export interface RecordingListParams {
+    /** Page number (1-indexed). Default: `1`. */
     page?: number;
+    /** Items per page. Default: `50`. */
     limit?: number;
+    /** ISO date string — recordings after this date. Example: `"2025-06-01T00:00:00.000Z"`. */
     dateFrom?: string;
+    /** ISO date string — recordings before this date. Example: `"2025-06-04T23:59:59.999Z"`. */
     dateTo?: string;
-    /** Filter by direction */
+    /** Filter by direction. `'inbound'` for incoming call recordings, `'outbound'` for outgoing. */
     direction?: 'inbound' | 'outbound';
 }
 export interface RecordingListResponse {
@@ -754,6 +1081,25 @@ export interface RecordingListResponse {
     pagination: PaginationInfo;
 }
 export type PresenceStatus = 'available' | 'registered' | 'on_call' | 'busy' | 'ringing' | 'dnd' | 'idle' | 'offline';
+/**
+ * Map of extension numbers to their current presence status.
+ *
+ * Keys are extension numbers (e.g. `"1001"`), values are presence status strings.
+ * Use this for a quick presence overview — iterate keys and show status badges.
+ *
+ * For detailed presence (with call UUID, caller info, direction, timestamps),
+ * use `listPresenceSubscriptions()` which returns `PresenceDetailMap`.
+ *
+ * @example
+ * ```ts
+ * const presence = await voip.getPresence();
+ * // presence = { "1001": "on_call", "1002": "available", "1003": "offline" }
+ * Object.entries(presence).forEach(([ext, status]) => {
+ *   const color = status === 'on_call' ? 'green' : status === 'offline' ? 'gray' : 'blue';
+ *   renderBadge(ext, status, color);
+ * });
+ * ```
+ */
 export interface PresenceMap {
     [extension: string]: PresenceStatus | string;
 }
@@ -885,16 +1231,75 @@ export interface WebRTCConfig {
      */
     jwtToken?: string;
 }
+/**
+ * Information about an active WebRTC call managed by the SIP.js softphone.
+ *
+ * ## CRITICAL: `id` vs `fsChannelUuid` — these are NOT the same thing
+ *
+ * | Field | What it is | When populated | Used for |
+ * |-------|-----------|---------------|----------|
+ * | `id` | sip.js session ID (local, client-generated) | Immediately (ringing) | Answer, reject, hold, mute, DTMF, hangup |
+ * | `fsChannelUuid` | FreeSWITCH channel UUID (server-side) | AFTER connect (`state: 'established'`) | Three-way operations (`addCallParticipant`, `mergeCalls`) |
+ *
+ * **Never pass `id` to three-way methods.** Always use `fsChannelUuid` for
+ * server-side operations. `id` is a sip.js internal identifier and has no meaning
+ * on the FreeSWITCH server.
+ *
+ * ## Lifecycle
+ *
+ * ```
+ * idle → connecting → ringing → established → terminating → terminated
+ *                                 ↕
+ *                               held
+ * ```
+ *
+ * - `idle`: No active call. Phone ready.
+ * - `connecting`: Outbound call — sending INVITE, waiting for provisional response.
+ * - `ringing`: Outbound — receiving 180 Ringing. Inbound — incoming call, waiting for answer.
+ * - `established`: Call is connected, audio flows. `fsChannelUuid` becomes non-null here.
+ * - `held`: Call is on hold (re-INVITE with sendonly). Music-on-hold plays to remote party.
+ * - `terminating`: BYE sent or received, waiting for final ACK.
+ * - `terminated`: Call ended. Resources released.
+ *
+ * ## UI guidelines
+ *
+ * - Show DTMF dialpad when `state === 'established'` and NOT `held`.
+ * - Grey out hold button during `connecting` and `ringing` — hold is only available when established.
+ * - Show "Calling..." during `connecting`, "Ringing..." during `ringing`, timer during `established`.
+ * - If `isPaging === true`, auto-answer and route audio to speaker (no earpiece).
+ * - Use `pagingGroup` and `pagingInitiator` to display "Paging: Sales Floor by 1001" in the UI.
+ * - Use `callType` to show "WhatsApp Call" badge in the call screen.
+ */
 export interface WebRTCCallInfo {
+    /**
+     * sip.js session ID — a locally generated string (e.g. `"abc123"`).
+     *
+     * **This is NOT the FreeSWITCH UUID.** Use this for client-side operations only:
+     * `answer()`, `reject()`, `hold()`, `mute()`, `sendDtmf()`, `hangup()`.
+     *
+     * Available immediately when the call is created (during `ringing` state).
+     *
+     * **DO NOT** pass this to `addCallParticipant()`, `mergeCalls()`, or any other
+     * server-side method — those require `fsChannelUuid`.
+     */
     id: string;
+    /** Call direction relative to this phone: `'inbound'` (someone called us) or `'outbound'` (we called someone). */
     direction: 'inbound' | 'outbound';
+    /** Remote party's phone number. For inbound calls this is the caller's number. For outbound calls this is the dialed number. Example: `"+17865551234"`. Initially `"unknown"` during very early ringing. */
     remoteIdentity: string;
+    /** Remote party's display name from SIP header. Example: `"John Doe"`. May be empty string if not provided. */
     remoteDisplayName: string;
+    /** Current state in the call lifecycle. See the type-level docs for the full state machine. */
     state: WebRTCCallState;
+    /** `Date` object when the call started (outbound INVITE sent or inbound INVITE received). `null` when `state === 'idle'`. */
     startTime: Date | null;
+    /** `Date` object when the call was answered (200 OK received/sent). `null` until `state === 'established'`. */
     answerTime: Date | null;
+    /** Whether the local user has placed this call on hold. `true` only during `held` state. */
     held: boolean;
+    /** Whether the local microphone is muted. Toggle via `phone.mute()`. The remote party hears silence but the call stays active. */
     muted: boolean;
+    /** String of DTMF digits sent during this call. Example: `""` (none sent), `"123"` (digits 1, 2, 3 sent). Accumulates over the call life. */
     dtmfSent: string;
     /**
      * Channel type of the inbound call.
@@ -916,6 +1321,8 @@ export interface WebRTCCallInfo {
     /**
      * Whether this is a paging/intercom broadcast call.
      * When `true`, the phone should auto-answer and play through the speaker (bocina).
+     * The SDK handles auto-answer automatically via the `autoAnswer` config and the
+     * `pagingCall` event on `WebRTCEventMap`.
      */
     isPaging?: boolean;
     /**
@@ -928,6 +1335,23 @@ export interface WebRTCCallInfo {
      * @example "1001"
      */
     pagingInitiator?: string | null;
+    /**
+     * FreeSWITCH channel UUID for this call.
+     *
+     * This is the server-side UUID that must be used for three-way calling
+     * operations (`addCallParticipant`, `mergeCalls`, `mergeDirectCalls`).
+     * It is resolved automatically after the call connects by matching the
+     * caller/callee info against FreeSWITCH's active channels.
+     *
+     * **Populated in `state: 'established'`** — `null` during ringing/connecting.
+     *
+     * **Critical:** Do NOT confuse this with `id` (the sip.js session ID).
+     * `fsChannelUuid` is the FreeSWITCH channel UUID needed for server-side operations.
+     * `id` is the local sip.js session ID for client-side operations.
+     *
+     * @example "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+     */
+    fsChannelUuid: string | null;
 }
 export interface WebRTCEventMap {
     registered: () => void;
@@ -953,40 +1377,104 @@ export interface WebRTCEventMap {
     }) => void;
     error: (error: Error) => void;
 }
+/**
+ * A participant in a conference room.
+ *
+ * Each member has a FreeSWITCH channel UUID (`uuid`) and a conference-specific
+ * member ID (`id`). Use `id` for conference operations like mute/kick/deaf.
+ */
 export interface ConferenceMember {
+    /** Conference member ID (integer). Used for mute/kick/deaf operations within the conference. Example: `"1"`. */
     id: string;
+    /** FreeSWITCH channel UUID for this member's call leg. Example: `"a1b2c3d4-e5f6-7890-abcd-ef1234567890"`. */
     uuid: string;
+    /** Caller ID name for this participant. Example: `"John Smith"`. */
     callerIdName: string;
+    /** Caller ID number for this participant. Example: `"+17865551234"` or `"1001"`. */
     callerIdNumber: string;
+    /** Whether this member is muted (cannot speak into conference). */
     muted: boolean;
+    /** Whether this member is deafened (cannot hear conference). */
     deaf: boolean;
+    /** ISO 8601 timestamp when this member joined the conference. Example: `"2025-06-04T14:30:00Z"`. */
     joinTime: string;
 }
+/**
+ * An active conference room on the FreeSWITCH server.
+ *
+ * Returned by `listConferences()`. Shows the conference name, number of members,
+ * lock status, runtime, and full member list with mute/deaf state.
+ *
+ * @example
+ * ```ts
+ * const { conferences } = await voip.listConferences();
+ * conferences.forEach(conf => {
+ *   console.log(`${conf.name}: ${conf.memberCount} members, ${conf.locked ? 'locked' : 'open'}`);
+ *   conf.members.forEach(m => {
+ *     console.log(`  ${m.callerIdNumber} muted=${m.muted} deaf=${m.deaf}`);
+ *   });
+ * });
+ * ```
+ */
 export interface Conference {
+    /** Conference room name (e.g. `"conf_<uuid>"` or a custom name). */
     name: string;
+    /** Number of active participants currently in the room. */
     memberCount: number;
+    /** Whether the conference is locked (no new members can join). */
     locked: boolean;
+    /** Human-readable runtime string (e.g. `"0:05:23"` for 5 minutes, 23 seconds). */
     runTime: string;
+    /** List of all active participants with their mute/deaf state. */
     members: ConferenceMember[];
 }
+/**
+ * A member (extension) within a ring group.
+ *
+ * Each member has a priority (for sequential strategy) and a delay before ringing.
+ */
 export interface RingGroupMember {
+    /** Database UUID of this member entry. */
     id: string;
+    /** Extension number (e.g. `"1001"`). */
     extension: string;
+    /** Ring priority for sequential strategy. Lower numbers ring first. `1`-based. */
     priority: number;
+    /** Seconds to wait before ringing this member (applies to sequential strategy). Default: `0`. */
     delay_seconds: number;
 }
+/**
+ * A ring group — rings multiple extensions when a call arrives.
+ *
+ * Strategies:
+ * - `simultaneous`: Ring all members at once. First to answer gets the call.
+ * - `sequential`: Ring members one at a time in priority order. Move to next after `ring_timeout`.
+ * - `random`: Ring a random member.
+ *
+ * If no one answers within `ring_timeout`, execute `no_answer_action` on `no_answer_target`.
+ */
 export interface RingGroup {
+    /** Database UUID of the ring group. */
     id: string;
+    /** Tenant UUID. Present for tenant-scoped queries. */
     tenant_id?: string;
+    /** Human-readable ring group name. Example: `"Sales Team"`. */
     name: string;
+    /** Ring strategy: `'simultaneous'`, `'sequential'`, or `'random'`. */
     strategy: string;
+    /** Total ring time in seconds before executing `no_answer_action`. Example: `30`. */
     ring_timeout: number;
+    /** Action when no one answers: `'voicemail'`, `'ivr'`, `'extension'`, `'hangup'`, `'ai_agent'`. */
     no_answer_action: string;
+    /** Target for `no_answer_action` (extension number, IVR UUID, etc.). `null` when action is `'hangup'`. */
     no_answer_target: string | null;
+    /** Status: `'active'` or `'disabled'`. */
     status: string;
+    /** ISO 8601 timestamp of creation. */
     created_at: string;
+    /** Ordered list of ring group members. */
     members: RingGroupMember[];
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin. */
     tenant?: TenantInfo;
 }
 export interface CreateRingGroupParams {
@@ -1001,33 +1489,75 @@ export interface CreateRingGroupParams {
         delaySeconds?: number;
     }>;
 }
+/**
+ * An agent (extension) assigned to a call queue.
+ *
+ * Agents receive calls distributed by the queue strategy.
+ * Queue managers (ext 6000) can add/remove themselves via `*45`/`*46`.
+ */
 export interface QueueAgent {
+    /** Database UUID of this agent assignment. */
     id: string;
+    /** Extension number assigned to the queue. Example: `"1001"`. */
     extension: string;
+    /** Agent tier/priority. Lower numbers = higher priority (gets calls first). Default: `5`. */
     priority: number;
+    /** Agent penalty (post-call wrap-up delay). Higher = longer delay before next call. Default: `0`. */
     penalty: number;
+    /** Agent status: `'available'`, `'on_call'`, `'paused'`, `'logged_out'`. */
     status: string;
 }
+/**
+ * A call queue — distributes incoming calls among agents based on a strategy.
+ *
+ * Callers hear music-on-hold while waiting for an available agent.
+ * Queue managers can log in/log out, pause, and monitor via FreeSWITCH codes.
+ *
+ * Strategies:
+ * - `round-robin`: Cycle through agents in fixed order.
+ * - `longest-idle`: Agent idle the longest gets the next call.
+ * - `ring-all`: Ring all available agents simultaneously.
+ * - `least-calls`: Agent with fewest calls today gets the next.
+ * - `random`: Pick a random available agent.
+ */
 export interface CallQueue {
+    /** Database UUID of the queue. */
     id: string;
+    /** Tenant UUID. */
     tenant_id?: string;
+    /** Queue name displayed in dashboards and reports. Example: `"Support Queue"`. */
     name: string;
+    /** Distribution strategy: `'round-robin'`, `'longest-idle'`, `'ring-all'`, `'least-calls'`, `'random'`. */
     strategy: string;
+    /** Music-on-hold sound file to play while caller waits. Example: `"default"` or custom audio file name. */
     moh_sound: string;
+    /** Announcement audio played to callers on entry (position in queue, estimated wait). `null` if disabled. */
     announce_sound: string | null;
+    /** How often (seconds) to replay the announcement to waiting callers. Example: `60`. */
     announce_frequency: number;
+    /** Maximum wait time in seconds before caller times out. Example: `300` (5 min). */
     max_wait_time: number;
+    /** Maximum number of simultaneous callers allowed in the queue. Example: `20`. */
     max_callers: number;
+    /** Seconds each agent's phone rings before moving to next agent. Example: `30`. */
     ring_timeout: number;
+    /** Seconds after a call ends before the agent gets the next call (post-call work). Example: `10`. */
     wrap_up_time: number;
+    /** Action when no agents are logged in: `'voicemail'`, `'ivr'`, `'extension'`, `'hangup'`, `'ai_agent'`. */
     no_agent_action: string;
+    /** Target for `no_agent_action`. `null` when action is `'hangup'`. */
     no_agent_target: string | null;
+    /** Action when caller times out (exceeds `max_wait_time`): `'voicemail'`, `'ivr'`, `'extension'`, `'hangup'`, `'ai_agent'`. */
     timeout_action: string;
+    /** Target for `timeout_action`. `null` when action is `'hangup'`. */
     timeout_target: string | null;
+    /** Queue status: `'active'` or `'disabled'`. */
     status: string;
+    /** ISO 8601 timestamp of creation. */
     created_at: string;
+    /** List of agents assigned to this queue. */
     agents: QueueAgent[];
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin. */
     tenant?: TenantInfo;
 }
 export interface CreateQueueParams {
@@ -1050,18 +1580,43 @@ export interface CreateQueueParams {
         penalty?: number;
     }>;
 }
+/**
+ * A webhook subscription that sends call events to an external URL.
+ *
+ * Webhooks fire on call lifecycle events (`call.started`, `call.ended`, etc.),
+ * voicemail events, and extension registration changes.
+ * Each delivery is retried up to `maxRetries` times with exponential backoff.
+ *
+ * @example
+ * ```ts
+ * const { webhooks } = await voip.listWebhooks();
+ * webhooks.forEach(w => {
+ *   console.log(`${w.name} → ${w.url} [${w.events.join(',')}] ${w.active ? 'ACTIVE' : 'PAUSED'}`);
+ * });
+ * ```
+ */
 export interface Webhook {
+    /** Database UUID of the webhook subscription. */
     id: string;
+    /** Human-readable name for this webhook. Example: `"CRM Call Logger"`. */
     name: string;
+    /** Destination URL where HTTP POST requests are sent. Must be HTTPS. Example: `"https://my-crm.example.com/api/webhooks/voip"`. */
     url: string;
+    /** Array of event types this webhook listens to. Example: `["call.started", "call.ended", "call.answered"]`. */
     events: string[];
+    /** Whether this webhook is actively sending events. `false` means paused. */
     active: boolean;
+    /** Whether a signing secret is configured. Always `false` in GET responses — the secret is never returned. */
     hasSecret: boolean;
+    /** Custom HTTP headers included in each delivery. `null` if none. Example: `{"X-Custom-Auth": "token123"}`. */
     headers: Record<string, string> | null;
+    /** Maximum retry attempts for failed deliveries. Default: `3`. After exhausting retries, the delivery is marked as failed. */
     maxRetries?: number;
+    /** Base delay in seconds between retries (exponential backoff). Default: `10`. Delays: 10s, 20s, 40s, ... */
     retryDelaySeconds?: number;
+    /** ISO 8601 timestamp of webhook creation. */
     createdAt: string;
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin. */
     tenant?: TenantInfo;
 }
 export interface WebhookDelivery {
@@ -1075,13 +1630,36 @@ export interface WebhookDelivery {
     error: string | null;
     deliveredAt: string;
 }
+/**
+ * Parameters for creating a new webhook subscription.
+ *
+ * At minimum, provide `name`, `url`, and `events`. The server validates the URL
+ * is HTTPS (non-negotiable for security) and tests connectivity before saving.
+ *
+ * @example
+ * ```ts
+ * await voip.createWebhook({
+ *   name: 'CRM Call Logger',
+ *   url: 'https://my-crm.example.com/api/webhooks/voip',
+ *   events: ['call.started', 'call.answered', 'call.ended', 'voicemail.new'],
+ *   secret: 'whsec_my-signing-secret',
+ * });
+ * ```
+ */
 export interface CreateWebhookParams {
+    /** Human-readable name for this webhook. Example: `"CRM Call Logger"`. */
     name: string;
+    /** Destination HTTPS URL. Must be reachable from the server. Example: `"https://my-crm.example.com/webhook"`. */
     url: string;
+    /** Array of event types to subscribe to. Full list: see `WebhookEventType`. Example: `["call.started", "call.ended"]`. */
     events: string[];
+    /** Signing secret for HMAC payload verification. The server includes `X-Webhook-Signature` header. Optional but recommended. */
     secret?: string;
+    /** Custom HTTP headers to include in each delivery. Example: `{"X-API-Key": "mykey"}`. */
     headers?: Record<string, string>;
+    /** Maximum retry attempts for failed deliveries. Default: `3`. */
     maxRetries?: number;
+    /** Base delay in seconds between retries (exponential: delay * 2^attempt). Default: `10`. */
     retryDelaySeconds?: number;
 }
 /** Supported webhook event names */
@@ -1222,23 +1800,55 @@ export interface VoicemailCallInfo {
     audio_url: string | null;
     started_at: string | null;
 }
+/**
+ * A voicemail message left by a caller.
+ *
+ * Returned by `listVoicemails()`. Each message includes the caller's info,
+ * duration, read/urgent flags, an audio URL, and optionally a linked call record.
+ *
+ * ## Playback
+ *
+ * Use `audio_url` with `voip.buildUrl()` to append the API key for browser playback:
+ * ```html
+ * <audio src={voip.buildUrl(message.audio_url)} controls />
+ * ```
+ *
+ * @example
+ * ```ts
+ * const { messages, unread } = await voip.listVoicemails({ unreadOnly: true });
+ * messages.forEach(msg => {
+ *   console.log(`From ${msg.caller_id}: ${msg.duration_seconds}s ${msg.is_urgent ? 'URGENT' : ''}`);
+ * });
+ * ```
+ */
 export interface VoicemailMessage {
+    /** Database UUID of the voicemail message. */
     id: string;
+    /** Tenant UUID this message belongs to. */
     tenant_id: string;
+    /** Extension number that received the voicemail. Example: `"1001"`. */
     extension: string;
+    /** Caller's phone number. Example: `"+17865551234"`. */
     caller_id: string;
+    /** Caller's display name. `null` if not provided by carrier. Example: `"John Doe"`. */
     caller_name: string | null;
+    /** Duration of the voicemail recording in seconds. Example: `42`. */
     duration_seconds: number;
+    /** Whether the voicemail has been listened to. */
     is_read: boolean;
+    /** Whether this voicemail was marked as urgent by the caller (pressed * during recording). */
     is_urgent: boolean;
+    /** ISO 8601 timestamp when the voicemail was left. Example: `"2025-06-04T15:30:00.000Z"`. */
     created_at: string;
+    /** ISO 8601 timestamp when the voicemail was read. `null` if unread. */
     read_at: string | null;
-    /** Direct URL to stream this voicemail's audio. Append `?apiKey=...` for browser playback. */
+    /** Direct URL to stream this voicemail's audio. Append `?apiKey=...` for browser playback. Example: `"/api/voicemail/abc123/audio"`. */
     audio_url: string;
-    /** Linked call record with status, recording, etc. (null if no matching call found) */
+    /** Linked call record with status, recording, etc. (null if no matching call found). Available since SDK 1.55.4. */
     call: VoicemailCallInfo | null;
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin. Tenant company name. */
     company_name?: string;
+    /** Present when queried as global superadmin. Tenant subdomain. */
     subdomain?: string;
 }
 export interface VoicemailListParams {
@@ -1318,11 +1928,28 @@ export interface PresenceDetail {
     extension?: string;
 }
 export type PresenceDetailMap = Record<string, PresenceDetail>;
+/**
+ * Dashboard summary counters for the current tenant.
+ *
+ * Returned by `getDashboardStats()`. Use for summary cards/badges at the top
+ * of a CRM dashboard showing: total extensions, active DIDs, calls today, and calls this month.
+ *
+ * @example
+ * ```ts
+ * const { dashboard } = await voip.getDashboardStats();
+ * console.log(`Extensions: ${dashboard.extensions}, DIDs: ${dashboard.dids}`);
+ * console.log(`Calls today: ${dashboard.callsToday}, This month: ${dashboard.callsThisMonth}`);
+ * ```
+ */
 export interface DashboardStats {
     dashboard: {
+        /** Total number of extensions configured in this tenant. */
         extensions: number;
+        /** Total number of active DID phone numbers. */
         dids: number;
+        /** Number of calls made/received today (midnight to now). */
         callsToday: number;
+        /** Number of calls made/received this calendar month. */
         callsThisMonth: number;
     };
 }
@@ -1344,19 +1971,46 @@ export interface TopExtension {
 export interface TopExtensionsResponse {
     topExtensions: TopExtension[];
 }
+/**
+ * A blocked phone number in the tenant's blocklist.
+ *
+ * Calls to/from blocked numbers are automatically rejected by FreeSWITCH.
+ * Works for both inbound and outbound directions.
+ */
 export interface BlockedNumber {
+    /** Database UUID of the blocklist entry. */
     id: string;
+    /** Tenant UUID. */
     tenant_id: string;
+    /** Blocked phone number in E.164 format. Example: `"+17865559999"`. */
     number: string;
+    /** Reason for blocking. `null` if no reason was provided. Example: `"Spam caller"`. */
     reason: string | null;
+    /** Direction this block applies to: `'inbound'`, `'outbound'`, `'both'`. `null` = `'both'`. */
     direction: string | null;
+    /** ISO 8601 timestamp when this number was blocked. `null` for legacy entries. */
     created_at: string | null;
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin. */
     tenants?: TenantInfo;
 }
+/**
+ * Parameters for adding a number to the blocklist.
+ *
+ * @example
+ * ```ts
+ * await voip.blockNumber({
+ *   number: '+17865559999',
+ *   reason: 'Repeated spam calls',
+ *   direction: 'inbound',
+ * });
+ * ```
+ */
 export interface CreateBlockedNumberParams {
+    /** E.164 phone number to block. Example: `"+17865559999"`. */
     number: string;
+    /** Optional reason (shown in dashboard). Example: `"Spam caller"`. */
     reason?: string;
+    /** Which direction to block: `'inbound'` (calls FROM this number), `'outbound'` (calls TO this number), `'both'`. Default: `'both'`. */
     direction?: 'inbound' | 'outbound' | 'both';
 }
 export interface BlocklistCheckResponse {
@@ -1373,27 +2027,81 @@ export interface Holiday {
     date: string;
     name?: string;
 }
+/**
+ * A business hours schedule for a tenant.
+ *
+ * Defines which days/times the business is open. When a call arrives outside
+ * business hours, the `after_hours_action` is executed (e.g. send to voicemail).
+ *
+ * Includes weekly `schedules` (day of week + start/end time) and `holidays`
+ * (specific dates when the business is closed regardless of weekly schedule).
+ *
+ * @example
+ * ```ts
+ * const { schedules } = await voip.listSchedules();
+ * schedules.forEach(s => {
+ *   const status = await voip.checkScheduleStatus(s.id);
+ *   console.log(`${s.name}: ${status.isOpen ? 'OPEN' : 'CLOSED'}`);
+ * });
+ * ```
+ */
 export interface BusinessSchedule {
+    /** Database UUID of the schedule. */
     id: string;
+    /** Tenant UUID. */
     tenant_id: string;
+    /** Human-readable schedule name. Example: `"Standard Business Hours"`. */
     name: string;
-    /** Present when queried as global superadmin */
+    /** Present when queried as global superadmin. */
     tenants?: TenantInfo;
+    /** IANA timezone for this schedule. `null` = tenant default. Example: `"America/New_York"`. */
     timezone: string | null;
+    /** Weekly day schedule array. Each entry defines open hours for one day. `null` if not configured. */
     schedules: DaySchedule[] | null;
+    /** Holiday list — specific dates the business is closed. `null` if no holidays configured. */
     holidays: Holiday[] | null;
+    /** Action when a call arrives outside business hours: `'voicemail'`, `'ivr'`, `'extension'`, `'hangup'`, `'external'`, `'ai_agent'`. `null` if not configured. */
     after_hours_action: string | null;
+    /** Target for `after_hours_action`. `null` when action is `'hangup'` or not configured. */
     after_hours_target: string | null;
+    /** Schedule status: `'active'` or `'disabled'`. `null` for legacy entries. */
     status: string | null;
+    /** ISO 8601 timestamp of creation. `null` for legacy entries. */
     created_at: string | null;
+    /** ISO 8601 timestamp of last update. `null` for legacy entries. */
     updated_at: string | null;
 }
+/**
+ * Parameters for creating a business hours schedule.
+ *
+ * @example
+ * ```ts
+ * await voip.createSchedule({
+ *   name: 'Standard Business Hours',
+ *   timezone: 'America/New_York',
+ *   schedules: [
+ *     { day: 'monday', enabled: true, startTime: '09:00', endTime: '17:00' },
+ *     { day: 'tuesday', enabled: true, startTime: '09:00', endTime: '17:00' },
+ *     { day: 'saturday', enabled: false },
+ *     { day: 'sunday', enabled: false },
+ *   ],
+ *   afterHoursAction: 'voicemail',
+ *   afterHoursTarget: '1001',
+ * });
+ * ```
+ */
 export interface CreateScheduleParams {
+    /** Human-readable name. Example: `"Standard Business Hours"`. */
     name: string;
+    /** IANA timezone. Default: tenant's configured timezone or `"America/New_York"`. */
     timezone?: string;
+    /** Weekly day schedule array. Each entry specifies open hours for a single day. Example: `[{ day: 'monday', enabled: true, startTime: '09:00', endTime: '17:00' }]`. */
     schedules?: DaySchedule[];
+    /** Specific dates the business is closed. Example: `[{ date: '2025-12-25', name: 'Christmas' }]`. */
     holidays?: Holiday[];
+    /** Action when a call arrives outside business hours. Defaults to no special handling. */
     afterHoursAction?: 'voicemail' | 'ivr' | 'extension' | 'hangup' | 'external' | 'ai_agent';
+    /** Target for `afterHoursAction` (extension number, IVR UUID, phone number, etc.). */
     afterHoursTarget?: string;
 }
 export interface ScheduleStatusResponse {
@@ -1402,15 +2110,104 @@ export interface ScheduleStatusResponse {
     timezone: string;
     currentTime: string;
 }
+/**
+ * Live gateway status reported by FreeSWITCH for a SIP trunk.
+ *
+ * Included in `SipTrunk` responses when the gateway is registered and available.
+ * Shows the current call count, failures, and uptime.
+ */
 export interface GatewayStatus {
+    /** Gateway state: `'UP'` or `'DOWN'`. */
     state: string;
+    /** Registration status: `'REGED'` (registered), `'UNREG'` (unregistered), `'TRYING'`. */
     status: string;
+    /** Number of active inbound calls on this trunk. */
     callsIn: number;
+    /** Number of active outbound calls on this trunk. */
     callsOut: number;
+    /** Cumulative failed inbound calls. */
     failedIn?: number;
+    /** Cumulative failed outbound calls. */
     failedOut?: number;
+    /** Human-readable uptime string (e.g. `"3d 12h 45m"`). */
     uptime?: string;
 }
+/**
+ * A SIP trunk gateway connecting the platform to an external telephony provider
+ * (Twilio, Telnyx, Vonage, etc.).
+ *
+ * SIP trunks handle PSTN connectivity — outbound calls go through trunks to reach
+ * phone numbers; inbound calls from phone numbers arrive via trunks.
+ *
+ * Global trunks (`tenant_id = null`) are shared across all tenants.
+ * Tenant-specific trunks are only usable by that tenant.
+ */
+export interface SipTrunk {
+    /** Database UUID of the trunk. */
+    id: string;
+    /** NULL for global trunks (shared, not tied to any tenant). */
+    tenant_id: string | null;
+    /** Present when queried as global superadmin. */
+    tenants?: TenantInfo;
+    /** Human-readable trunk name. Example: `"Twilio Primary"`. */
+    name: string;
+    /** Provider name: `'twilio'`, `'telnyx'`, `'vonage'`, etc. `null` for custom/unspecified. */
+    provider: string | null;
+    /** Gateway IP or hostname. Example: `"sip.twilio.com"`. */
+    gateway: string;
+    /** SIP username for registration/auth. `null` for IP-based auth trunks. */
+    username: string | null;
+    /** SIP password (masked in API responses — always `"****"` except on create). `null` for IP-auth. */
+    password: string | null;
+    /** Authentication type: `'ip'`, `'registration'`, `'both'`. `null` for legacy entries. */
+    auth_type: string | null;
+    /** Whether outbound calling is enabled through this trunk. `null` = disabled. */
+    outbound_enabled: boolean | null;
+    /** Whether inbound calling is accepted from this trunk. `null` = disabled. */
+    inbound_enabled: boolean | null;
+    /** Priority for outbound routing. Lower = preferred. Example: `10`. */
+    priority: number | null;
+    /** Maximum simultaneous channels. `null` = unlimited. */
+    max_channels: number | null;
+    /** Trunk status: `'active'` or `'inactive'`. `null` = `'inactive'`. */
+    status: string | null;
+    /** SIP realm for authentication. `null` = auto. */
+    realm: string | null;
+    /** Outbound proxy address. `null` = direct to gateway. */
+    proxy: string | null;
+    /** Whether FreeSWITCH registers with the trunk provider. `null` = false. */
+    register: boolean | null;
+    /** From: username for SIP requests. `null` = use `username`. */
+    from_user: string | null;
+    /** From: domain for SIP requests. `null` = use gateway. */
+    from_domain: string | null;
+    /** SIP transport protocol: `'udp'`, `'tcp'`, `'tls'`. `null` = `'udp'`. */
+    transport: string | null;
+    /** Preferred codec list (comma-separated). `null` = platform default. Example: `"PCMU,PCMA"`. */
+    codec_prefs: string | null;
+    /** Whether to include caller ID in From: header. `null` = true. */
+    caller_id_in_from: boolean | null;
+    /** SIP OPTIONS ping interval in seconds. `null` = no ping. */
+    ping: number | null;
+    /** Seconds between registration retries. `null` = default. */
+    retry_seconds: number | null;
+    /** Registration expiry in seconds. `null` = default (3600). */
+    expire_seconds: number | null;
+    /** Separate proxy for REGISTER requests. `null` = use `proxy` or `gateway`. */
+    register_proxy: string | null;
+    /** Extra SIP contact header parameters. `null` = none. */
+    contact_params: string | null;
+    /** Whether this is a global trunk (usable by all tenants). `null` = false. */
+    is_global: boolean | null;
+    /** FreeSWITCH gateway profile name. `null` = auto-generated from name. */
+    gateway_name: string | null;
+    /** Live gateway status from FreeSWITCH (when available). Shows state, calls, failures, uptime. */
+    gatewayStatus?: GatewayStatus | null;
+    /** ISO 8601 timestamp of creation. `null` for legacy entries. */
+    created_at: string | null;
+    /** ISO 8601 timestamp of last update. `null` for legacy entries. */
+    updated_at: string | null;
+}
 export interface SipTrunk {
     id: string;
     /** NULL for global trunks (shared, not tied to any tenant) */
@@ -1475,21 +2272,48 @@ export interface CreateTrunkParams {
     contactParams?: string;
     isGlobal?: boolean;
 }
+/**
+ * Real-time and today's statistics for a single call queue.
+ *
+ * Returned by `getQueueStats()`. Shows agent availability, today's call metrics,
+ * and service level percentage. Use for queue wallboards and agent dashboards.
+ *
+ * @example
+ * ```ts
+ * const stats = await voip.getQueueStats('queue-uuid');
+ * console.log(`${stats.queueName}: ${stats.today.answered}/${stats.today.totalCalls} answered`);
+ * console.log(`Agents: ${stats.agents.available} available, ${stats.agents.busy} busy`);
+ * ```
+ */
 export interface QueueStats {
+    /** Queue name. Example: `"Support Queue"`. */
     queueName: string;
+    /** Distribution strategy. Example: `"longest-idle"`. */
     strategy: string;
+    /** Agent availability breakdown. */
     agents: {
+        /** Total number of agents assigned to this queue. */
         total: number;
+        /** Agents currently available to take calls. */
         available: number;
+        /** Agents who are paused (taking a break). */
         paused: number;
+        /** Agents currently on a call. */
         busy: number;
+        /** Agents who are logged out. */
         loggedOut: number;
     };
+    /** Today's call statistics (from midnight). */
     today: {
+        /** Total calls offered to the queue today. */
         totalCalls: number;
+        /** Calls successfully answered by an agent today. */
         answered: number;
+        /** Calls abandoned by the caller before reaching an agent. */
         abandoned: number;
+        /** Service level: percentage of calls answered within the SLA (default 20 seconds). Range 0-100. */
         serviceLevel: number;
+        /** Average call duration in seconds for answered calls today. */
         avgDuration: number;
     };
 }
@@ -1499,38 +2323,118 @@ export interface ExportCallsParams {
     direction?: 'inbound' | 'outbound' | 'internal' | 'all';
     limit?: number;
 }
+/**
+ * SIP registration credentials for WebRTC softphone authentication.
+ *
+ * Returned by `getSipCredentials()` when creating an extension or manually.
+ * Pass these to the `WebRTCPhone` constructor for SIP registration.
+ *
+ * @example
+ * ```ts
+ * const creds = await voip.getSipCredentials('1001');
+ * const phone = new WebRTCPhone({
+ *   extension: creds.extension,
+ *   password: creds.password,
+ *   displayName: creds.displayName,
+ *   sipDomain: creds.sipDomain,
+ *   wsUri: creds.wsUri,
+ * });
+ * ```
+ */
 export interface SipCredentials {
+    /** Extension number used as SIP username. Example: `"1001"`. */
     extension: string;
+    /** Display name for caller ID. Example: `"John Smith"`. */
     displayName: string;
+    /** SIP password for registration. */
     password: string;
+    /** SIP domain the phone should register to. Example: `"demo.sip.cemscale.com"`. */
     sipDomain: string;
+    /** WebSocket URI for SIP signaling. Example: `"wss://sip.cemscale.com/ws"`. */
     wsUri: string;
+    /** SIP registrar address (same as sipDomain but explicit for sip.js config). Example: `"sip.cemscale.com"`. */
     registrar: string;
 }
+/**
+ * An API key for authenticating API requests.
+ *
+ * API keys are the recommended way to authenticate SDK requests in production
+ * (server-side integrations, CRMs, automation scripts). They never expire by
+ * default and have role-based scopes.
+ *
+ * **CRITICAL:** The full key is only returned on `createApiKey()` and
+ * `regenerateApiKey()` responses. After that, only `keyPreview` is shown.
+ * Store the full key securely — it cannot be retrieved again.
+ *
+ * @example
+ * ```ts
+ * const { apiKey } = await voip.createApiKey({
+ *   name: 'CRM Integration',
+ *   role: 'admin',
+ * });
+ * console.log(apiKey.key); // "csk_live_abc123def456..." — STORE THIS NOW
+ * console.log(apiKey.keyPreview); // "csk_live_••••••••def456"
+ * ```
+ */
 export interface ApiKey {
+    /** Database UUID of the API key. */
     id: string;
+    /** Human-readable name for this key. Example: `"CRM Integration"`. */
     name: string;
-    /** Full raw key — only present on create and regenerate responses */
+    /** Full raw key — only present on create and regenerate responses. Format: `"csk_live_..."`. **Store securely.** Will be `undefined` in list/get responses. */
     key?: string;
-    /** Masked preview: csk_live_••••••••abcd1234 */
+    /** Masked preview: csk_live_••••••••abcd1234. Safe to display in UI. Always present. */
     keyPreview: string;
+    /** Role determining permissions: `'admin'`, `'readonly'`, `'user'`, `'superadmin'`. */
     role: string;
+    /** API permission scopes. Example: `["read:calls", "write:extensions"]`. */
     scopes: string[];
+    /** ISO 8601 timestamp of last usage. `null` if never used. */
     lastUsedAt: string | null;
+    /** ISO 8601 timestamp when this key expires. `null` if never expires. */
     expiresAt: string | null;
+    /** Key status: `'active'` or `'revoked'`. */
     status: string;
+    /** Who created this key (email or user ID). `null` for legacy keys. */
     createdBy: string | null;
+    /** ISO 8601 timestamp of creation. `null` for legacy keys. */
     createdAt: string | null;
+    /** ISO 8601 timestamp when this key was revoked. `null` if active. */
     revokedAt?: string | null;
 }
+/**
+ * Parameters for creating a new API key.
+ *
+ * At minimum, provide a `name`. The role defaults to `'admin'`.
+ * Use `scopes` for fine-grained permission control.
+ *
+ * Superadmin-only fields (`global`, `tenantId`) allow creating keys
+ * that span tenants or target specific tenants.
+ *
+ * @example
+ * ```ts
+ * // Admin key with full CRUD
+ * const { apiKey } = await voip.createApiKey({ name: 'CRM Admin', role: 'admin' });
+ *
+ * // Read-only key for reporting
+ * const { apiKey } = await voip.createApiKey({ name: 'Reports', role: 'readonly' });
+ *
+ * // Superadmin: create global key for all tenants
+ * const { apiKey } = await voip.createApiKey({ name: 'Global Ops', role: 'superadmin', global: true });
+ * ```
+ */
 export interface CreateApiKeyParams {
+    /** Human-readable name. Example: `"CRM Integration"`. */
     name: string;
+    /** Role for permission level: `'admin'` (full CRUD), `'readonly'` (GET only), `'user'` (limited), `'superadmin'` (full PBX). Default: `'admin'`. */
     role?: 'admin' | 'readonly' | 'user' | 'superadmin';
+    /** API permission scopes for fine-grained control. Example: `["read:calls", "write:extensions", "read:recordings"]`. */
     scopes?: string[];
+    /** ISO 8601 expiration date. `null` (omit) = never expires. Example: `"2026-12-31T23:59:59Z"`. */
     expiresAt?: string;
-    /** Superadmin only: create a global API key with no tenant (full PBX control) */
+    /** Superadmin only: create a global API key with no tenant (full PBX control). */
     global?: boolean;
-    /** Superadmin only: specify which tenant this key belongs to */
+    /** Superadmin only: specify which tenant this key belongs to. */
     tenantId?: string;
 }
 export interface UpdateApiKeyParams {
@@ -1592,17 +2496,201 @@ export interface VoIPClientConfig {
     /** Request timeout in ms (default 15000) */
     timeout?: number;
 }
+/**
+ * A participant in a three-way conference.
+ *
+ * Each participant is identified by their FreeSWITCH channel UUID (`uuid`)
+ * and their conference member ID (`memberId`). Use `memberId` for mute/kick
+ * operations, and `uuid` for swap/merge operations.
+ *
+ * **Status:** `'active'` = in conference and talking. `'held'` = kicked out
+ * of the conference and placed on hold (hears music). Swapping toggles these.
+ */
 export interface ThreeWayParticipant {
-    /** FreeSWITCH channel UUID of this leg */
+    /** FreeSWITCH channel UUID of this leg. Use for swap operations (`keepUuid`/`holdUuid` in `swapParticipant()`). Example: `"a1b2c3d4-..."`. */
     uuid: string;
-    /** FreeSWITCH conference member ID (needed for kick/mute) */
+    /** FreeSWITCH conference member ID (integer). Use for mute/kick operations within the conference. Example: `"1"`. */
     memberId: string;
+    /** Caller ID number of this participant. Example: `"+17865551234"` or `"1002"`. */
     callerIdNumber: string;
+    /** Caller ID name of this participant. Example: `"John Smith"`. */
     callerIdName: string;
+    /** Whether this participant is muted in the conference. */
     muted: boolean;
-    /** 'active' = in conference, 'held' = kicked out and on hold */
+    /** `'active'` = in conference, `'held'` = kicked out and on hold (hears music). */
     status: 'active' | 'held';
 }
+/**
+ * State machine for a three-way call session.
+ *
+ * ## Lifecycle
+ *
+ * ```
+ * [Call A active] → addCallParticipant(...)
+ *   → adding (hold A, dialing B, waiting for answer)
+ *   → [B answers] → mergeCalls(...)
+ *   → active (all three in conference)
+ *     → swapParticipant(keep, hold) → swapping → active
+ *     → kickParticipant(...)
+ *     → [caller hangs up] → conference auto-destroys
+ * ```
+ *
+ * ## Key fields
+ *
+ * - `conferenceName`: The FreeSWITCH conference room name. Needed for swap/kick operations.
+ * - `state`: Current phase of the three-way call.
+ * - `pendingUuid`: UUID of Person B's leg while dialing (before merge). `null` after merge.
+ * - `originalBridgedLeg`: UUID of Person A's PSTN bridge leg. Needed to merge correctly.
+ *
+ * @example
+ * ```ts
+ * // Listen for three-way session state
+ * voip.on('threeWayUpdate', (session: ThreeWaySession) => {
+ *   if (session.state === 'active') {
+ *     console.log('Three-way conference active:', session.conferenceName);
+ *     session.participants.forEach(p => {
+ *       console.log(`  ${p.callerIdNumber} (${p.status}) muted=${p.muted}`);
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export interface ThreeWaySession {
+    /** FreeSWITCH conference room name. Pass to `swapParticipant()`, `kickParticipant()`, `endConference()`. Example: `"conf_abc123"`. */
+    conferenceName: string;
+    /** Current state of the three-way session. Use for UI state: show "Adding participant..." during `'adding'`, show participant list during `'active'`. */
+    state: ThreeWayState;
+    /** List of participants currently in the conference. */
+    participants: ThreeWayParticipant[];
+    /** UUID of the second call leg while dialing (before merge). `null` after successful merge or if no pending dial. */
+    pendingUuid?: string;
+    /** UUID of the bridged PSTN leg of the original call. Required for correct merge — returned by `addCallParticipant()`. `null` if the original call had no bridged PSTN leg. */
+    originalBridgedLeg?: string;
+}
+/**
+ * Parameters for adding a participant to an active call (first step of three-way calling).
+ *
+ * Provide either `toNumber` (external PSTN) or `toExtension` (internal extension),
+ * but not both. The active call is placed on hold while dialing the new party.
+ *
+ * On success, you receive `newCallUuid` (the new leg's UUID) and `originalBridgedLeg`
+ * (the original call's bridged PSTN leg UUID). Pass both to `mergeCalls()`.
+ *
+ * @example
+ * ```ts
+ * // Add external participant
+ * const { newCallUuid, originalBridgedLeg } = await voip.addCallParticipant(callUuid, {
+ *   toNumber: '+17865559999',
+ * });
+ *
+ * // Add internal extension
+ * const { newCallUuid } = await voip.addCallParticipant(callUuid, {
+ *   toExtension: '1002',
+ * });
+ * ```
+ */
+export interface AddParticipantParams {
+    /** PSTN number to call in E.164 format. Example: `"+17865559999"`. */
+    toNumber?: string;
+    /** Internal extension to add. Example: `"1002"`. */
+    toExtension?: string;
+}
+/**
+ * Response from `addCallParticipant()`.
+ *
+ * Use `newCallUuid` and `originalBridgedLeg` in the subsequent `mergeCalls()` call
+ * to join all three parties into a conference.
+ */
+export interface AddParticipantResponse {
+    /** Human-readable message. Example: `"Second call (UUID xxx) established — ready to merge"`. */
+    message: string;
+    /** FreeSWITCH channel UUID of the new call leg (Person B). Pass as `callUuidB` to `mergeCalls()`. */
+    newCallUuid: string;
+    /** FreeSWITCH channel UUID of the original call's bridged PSTN leg. Pass as `bridgedLegA` to `mergeCalls()` for correct merging. */
+    originalBridgedLeg: string;
+}
+/**
+ * Parameters for merging two calls into a three-way conference (second step).
+ *
+ * After `addCallParticipant()` succeeds, call `mergeCalls()` with the UUIDs to
+ * join Person A, Person B, and the original PSTN caller into one conference.
+ *
+ * @example
+ * ```ts
+ * const result = await voip.mergeCalls({
+ *   callUuidA: activeCall.uuid,           // User's WebRTC session
+ *   callUuidB: addResult.newCallUuid,     // New call leg from addCallParticipant
+ *   bridgedLegA: addResult.originalBridgedLeg, // Original PSTN leg
+ * });
+ * console.log('Conference created:', result.conferenceName);
+ * ```
+ */
+export interface MergeCallsParams {
+    /** UUID of the user's WebRTC session (first call). Use `WebRTCCallInfo.fsChannelUuid`. */
+    callUuidA: string;
+    /** UUID returned by addCallParticipant (Person B's direct channel). */
+    callUuidB: string;
+    /**
+     * Person A's PSTN leg UUID — returned as `originalBridgedLeg` by addCallParticipant.
+     * Passing this avoids an extra ESL lookup and ensures the correct leg is used.
+     */
+    bridgedLegA?: string;
+    /** Optional custom conference name — auto-generated if omitted. */
+    conferenceName?: string;
+}
+/**
+ * Response from `mergeCalls()`.
+ *
+ * Contains the conference name (needed for swap/kick/end operations) and the
+ * full participant list with UUIDs, caller IDs, and mute/held status.
+ */
+export interface MergeCallsResponse {
+    /** Human-readable message. Example: `"Calls merged into conference conf_abc123"`. */
+    message: string;
+    /** FreeSWITCH conference room name. Store this for subsequent swap/kick/end operations. */
+    conferenceName: string;
+    /** List of all participants now in the conference. Use for rendering participant cards in the UI. */
+    participants: ThreeWayParticipant[];
+}
+/**
+ * Parameters for directly merging two active WebRTC calls (no PSTN party).
+ *
+ * Use this when the user has two WebRTC calls active simultaneously (e.g.
+ * call on line 1 and line 2) and wants to merge them directly.
+ *
+ * Unlike `addCallParticipant` → `mergeCalls`, this doesn't need a bridged leg UUID
+ * because both calls are WebRTC (no PSTN bridge).
+ *
+ * @example
+ * ```ts
+ * const result = await voip.mergeDirectCalls({
+ *   callUuidA: call1.fsChannelUuid,
+ *   callUuidB: call2.fsChannelUuid,
+ * });
+ * ```
+ */
+export interface MergeDirectParams {
+    /** UUID of the first call (WebRTC leg). Use `WebRTCCallInfo.fsChannelUuid`. */
+    callUuidA: string;
+    /** UUID of the second call to merge (WebRTC leg). Use `WebRTCCallInfo.fsChannelUuid`. */
+    callUuidB: string;
+    /** Optional custom conference name — auto-generated if omitted. */
+    conferenceName?: string;
+}
+/**
+ * Response from `mergeDirectCalls()`.
+ *
+ * Same structure as `MergeCallsResponse`. All participants are now in the
+ * named conference and can be swapped/kicked independently.
+ */
+export interface MergeDirectResponse {
+    /** Human-readable message. Example: `"Calls merged into conference conf_abc123"`. */
+    message: string;
+    /** FreeSWITCH conference room name. Store for subsequent operations. */
+    conferenceName: string;
+    /** List of all participants now in the conference. */
+    participants: ThreeWayParticipant[];
+}
 export type ThreeWayState = 'adding' | 'active' | 'swapping';
 export interface ThreeWaySession {
     conferenceName: string;
@@ -1725,7 +2813,25 @@ export interface AiAgentListResponse {
     agents: AiAgent[];
     total: number;
 }
+/**
+ * Response containing a single AI agent.
+ *
+ * Returned by `createAiAgent()`, `getAiAgent()`, and `updateAiAgent()`.
+ * The `agent` field contains the full agent configuration from the AI Bridge.
+ *
+ * @example
+ * ```ts
+ * const { agent } = await voip.createAiAgent({
+ *   agent_id: 'acme-sales',
+ *   display_name: 'Sofia',
+ *   voice: 'Aoede',
+ *   tools: ['transfer_to_human', 'end_call'],
+ * });
+ * console.log(`Agent "${agent.display_name}" (${agent.agent_id}) created`);
+ * ```
+ */
 export interface AiAgentResponse {
+    /** The full AI agent object from the AI Bridge. */
     agent: AiAgent;
 }
 export interface AiBridgeHealthResponse {
@@ -1905,32 +3011,81 @@ export interface AiCallHistoryResponse {
     calls: AiCallRecord[];
     total: number;
 }
+/**
+ * A paging group for one-way audio broadcast (intercom/PA system).
+ *
+ * When someone dials `extension_code` (e.g. `*801`), all online members auto-answer
+ * and hear the caller through their speaker. This is a one-way broadcast — members
+ * hear the caller but cannot speak back.
+ *
+ * @example
+ * ```ts
+ * const { pagingGroups } = await voip.listPagingGroups();
+ * pagingGroups.forEach(pg => {
+ *   console.log(`${pg.name} (${pg.extension_code}): ${pg.members.length} members`);
+ * });
+ * ```
+ */
 export interface PagingGroup {
+    /** Database UUID of the paging group. */
     id: string;
+    /** Tenant UUID. */
     tenant_id: string;
+    /** Human-readable name. Example: `"All users"`. */
     name: string;
+    /** Optional description. `null` if not set. */
     description: string | null;
+    /** Dial code to trigger paging (e.g. `"*801"`). Must start with `*8`. Unique per tenant. */
     extension_code: string;
+    /** Group status: `'active'` or `'disabled'`. */
     status: string;
+    /** ISO 8601 timestamp of creation. */
     created_at: string;
+    /** ISO 8601 timestamp of last update. */
     updated_at: string;
+    /** List of extension numbers that are members of this paging group. */
     members: PagingGroupMember[];
+    /** Tenant summary — present when queried as global superadmin. */
     tenant?: {
         id: string;
         company_name: string;
         subdomain: string;
     };
 }
+/**
+ * A member extension within a paging group.
+ */
 export interface PagingGroupMember {
+    /** Database UUID of this member entry. */
     id: string;
+    /** Parent paging group UUID. */
     paging_group_id: string;
+    /** Extension number. Example: `"1001"`. */
     extension: string;
+    /** ISO 8601 timestamp when this member was added. */
     created_at: string;
 }
+/**
+ * Parameters for creating a new paging group with members.
+ *
+ * @example
+ * ```ts
+ * await voip.createPagingGroup({
+ *   name: 'Sales Floor',
+ *   description: 'Broadcast to all sales agents',
+ *   extensionCode: '*802',
+ *   members: [{ extension: '1001' }, { extension: '1002' }, { extension: '1005' }],
+ * });
+ * ```
+ */
 export interface CreatePagingGroupParams {
+    /** Human-readable group name. Example: `"Sales Floor"`. Must be unique within the tenant. */
     name: string;
+    /** Optional description of the group's purpose. */
     description?: string;
+    /** Dial code to activate paging (e.g. `"*802"`). Must start with `*8` and be unique within the tenant. */
     extensionCode: string;
+    /** Array of extensions to include as members. Each entry requires `extension` field. */
     members: {
         extension: string;
     }[];