voxnix 2.0.0 → 2.1.0

package/README.md

@@ -5,7 +5,7 @@ SIP/WebSocket, manages the agent status (Ready / Not Ready / AUX)
 through the CPaaS API, and gives you **functions + events** to build your own calling UI in any stack:
 React, Vue, Angular, or plain HTML.
 
-**Current version: `2.0.0`**. Voxnix ships no UI. Upgrading from 1.x? See [Migrating from 1.x](#migrating-from-1x).
+**Current version: `2.1.0`**. Voxnix ships no UI. Upgrading from 1.x? See [Migrating from 1.x](#migrating-from-1x).
 
 ---
 
@@ -231,6 +231,7 @@ All callbacks are optional. Payloads are described in [Events & callbacks](#even
 | `mute(muted = true)` | — | `true` mutes the microphone, `false` unmutes it. Only during a connected call |
 | `hold(onHold = true)` | — | `true` holds the call, `false` resumes it. Only during a connected call |
 | `sendDtmf(tones)` | — | Send DTMF during a connected call. Accepts one tone or a string: `'5'`, `'123#'` |
+| `transfer(target, { attended = false })` | `Promise<boolean>` | *(2.1+)* Transfer the connected call to `target`. Blind: REFER straight away. Attended: hold the caller, call `target`, and REFER (Replaces) once it answers. On success our leg is hung up (`onCallEnded` fires) |
 | `setReady()` | `Promise<boolean>` | Agent → Ready. Emits `'REGISTERED'` + `'READY'` on success |
 | `setNotReady()` | `Promise<boolean>` | Agent → Not Ready (CPaaS `Logout`). Emits `'SIP_CONNECTED'` + `'NOT_READY'` |
 | `setAux(code = 'AUX', label = code)` | `Promise<boolean>` | Agent → AUX. `code` is sent to CPaaS as the reason; `label` is for your UI |
@@ -255,7 +256,7 @@ The call controls are safe to call at any time. Outside a valid state they do no
   callDuration:   '01:23',        // 'MM:SS' or 'HH:MM:SS'
   isMuted:        false,
   isOnHold:       false,
-  remote:         { number: '1002', name: 'Jane', direction: 'outgoing' }, // null when Idle
+  remote:         { number: '1002', name: 'Jane', direction: 'outgoing', headers: {} }, // null when Idle
 }
 ```
 
@@ -274,14 +275,15 @@ Subscribe with `voice.on(event, cb)`. Events that have a callback option fire th
 | `call_status`          | `'Idle'` \| `'Calling...'` \| `'Ringing'` \| `'InCall'` | `onCallStatus` |
 | `call_duration`        | `'00:42'`, every second while connected, `'00:00'` on end | — |
 | `call_failed`          | `cause` string, e.g. `'Busy'`, `'Rejected'`, `'Unavailable'` | `onCallFailed` |
-| `incoming_call`        | `{ number, name, direction: 'incoming' }` | `onIncomingCall` |
-| `sync_call_answered`   | `{ number, name, direction }` | `onCallAnswered` |
-| `sync_call_ended`      | `{ number, name, direction, cause, originator }` | `onCallEnded` |
-| `sync_call_unanswered` | `{ number, name, direction, cause, originator }` | `onCallUnanswered` |
+| `incoming_call`        | `{ number, name, direction: 'incoming', headers }` | `onIncomingCall` |
+| `sync_call_answered`   | `{ number, name, direction, headers }` | `onCallAnswered` |
+| `sync_call_ended`      | `{ number, name, direction, headers, cause, originator }` | `onCallEnded` |
+| `sync_call_unanswered` | `{ number, name, direction, headers, cause, originator }` | `onCallUnanswered` |
 | `mute_status`          | `boolean` | — |
 | `hold_status`          | `boolean` | — |
 
 - `direction`: `'incoming'` or `'outgoing'`.
+- `headers` *(2.1+)*: custom `X-*` headers of an incoming INVITE, e.g. `{ 'X-Call-Uuid': '…', 'X-Source-Type': 'whatsapp-call', 'X-Queue-Name': '…' }`. Always `{}` for outgoing calls. These values come from the caller side, so treat them as untrusted.
 - `originator`: who ended the call. `'local'` means you, `'remote'` means the other side, `'system'` means a network or SIP error.
 - `cause`: the end reason, such as `'Terminated'`, `'Canceled'`, `'Rejected'`, `'Busy'` or `'No Answer'`.
 
@@ -442,6 +444,8 @@ npm run watch        # rebuild ESM + UMD on change
 - **New SIP engine.** Call callbacks now receive `{ number, name, direction, ... }` instead of a raw SIP session object.
 - `hold(true)` now holds and `hold(false)` resumes (1.x had them reversed).
 - `onCallEnded` fires once per call. Before, it could fire twice for incoming calls.
+- Call payloads include `headers` (2.1+), the `X-*` headers of an incoming INVITE. Use it instead of reading headers from the raw SIP session.
+- Call transfer is `transfer(target, { attended })` (2.1+) instead of `refer()` on the raw session.
 - New in 2.0: `sendDtmf`, `setReady`, `setNotReady`, `setAux`, `getState`, `on`, plus the options `onCallStatus`, `onCallFailed`, `ringtone` and `contacts`.
 - `contacts` has no built-in demo entries any more. Pass your own map.
 
@@ -449,13 +453,18 @@ npm run watch        # rebuild ESM + UMD on change
 
 ## Changelog
 
+### v2.1.0
+- `transfer(target, { attended })`: blind transfer (REFER), or attended (hold caller, consult call, REFER with Replaces)
+- Call payloads and `getState().remote` include `headers`: the `X-*` headers of an incoming INVITE (`X-Call-Uuid`, `X-Source-Type`, `X-Queue-Name`, …)
+- Build runs on `prepack`, so `npm pack` / `npm publish` always ship a fresh `dist`
+
 ### v2.0.0
 - Removed the built-in React UI; Voxnix is now a headless SDK (no React / Tailwind dependencies)
 - New internal SIP engine
 - New API: `sendDtmf`, `setReady`, `setNotReady`, `setAux`, `getState`, `on`; options `onCallStatus`, `onCallFailed`, `ringtone`, `contacts`
 - Configurable `cpaas_base_url`, `pbx_url` (SIP domain), `sip_url` (WSS host)
 - Re-REGISTER + CPaaS poll when the extension reports `is_register = 0`
-- Security: credentials and API responses are no longer logged (1.0.23–1.0.24 logged the full config); HTTPS-only CPaaS URL; `dial()` input validation; `prepublishOnly` build
+- Security: credentials and API responses are no longer logged (1.0.23–1.0.24 logged the full config); HTTPS-only CPaaS URL; `dial()` input validation; build before publish
 - Fixes: cancel while dialing, double `onCallEnded`, inverted `hold()`, outgoing call duration and callbacks, busy second incoming call, `destroy()` not stopping SIP, IIFE global `OmnixWidget.init`
 
 ### v1.0.12