voxnix 1.0.11 → 1.0.13

package/README.md

@@ -1,14 +1,22 @@
 # Voxnix
 
-Universal Voice Widget SDK. Works in React, Vue, Angular, plain HTML — any stack.
+Universal Voice Widget SDK — SIP-based floating phone widget. Works in React, Vue, Angular, plain HTML, or any stack.
+
+**Current version: `1.0.12`**
+
+---
 
 ## What it does
 
 - Floating phone button (fixed position, configurable placement)
 - Auto-connects to your SIP/PABX server on init
 - Shows dialer numpad immediately after registration
-- Full call UI: incoming call, outgoing dialing, in-call controls (mute, hold, DTMF)
-- Fires callbacks for all call events so your app can react
+- Full call UI: incoming call, outgoing dialing, in-call controls (mute, hold, DTMF keypad)
+- **Agent status bar** — Ready / Not Ready / AUX with optional custom AUX codes
+- Fires callbacks for all call and agent-status events so your app can react
+- Keyboard shortcuts: digits to dial, `Enter` to call, `Backspace` to delete, `0–9`/`*`/`#` for DTMF during a call
+
+---
 
 ## Installation
 
@@ -18,28 +26,41 @@ npm install voxnix
 yarn add voxnix
 ```
 
+---
+
 ## Quick start (any framework)
 
 ```js
 import { OmnixWidget } from 'voxnix';
 
 const widget = OmnixWidget.init({
-  platform: 'sipjs',
   auth: {
-    username: '1001',
-    pwd_pbx:  'secret',
+    username:  '1001',
+    pwd_pbx:   'secret',
     pabx_host: 'sip.example.com',
-    port: 8089,
+    port:       8089,          // optional, default 8089
   },
-  placement: 'bottom-left',  // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
 
+  // Required for agent status API (Ready / AUX / Not Ready)
+  'X-CPAAS-Key-Fingerprint': 'your-cpaas-key-fingerprint-here',
+
+  placement: 'bottom-left',   // 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right'
+
+  // Agent status options (optional)
+  autoReady:     true,         // auto-set agent to Ready after SIP register (default: true)
+  showAuxButton: false,        // show AUX button in status bar (default: false)
+  auxOptions:    [],           // array of { code, label } — custom AUX codes
+
+  // Callbacks
   onRegisterStatus: (status) => {
-    console.log('SIP status:', status); // 'REGISTERED' | 'FAILED'
+    // status: 'REGISTERED' | { status: 'FAILED', reason: string }
+    console.log('SIP status:', status);
   },
-  onIncomingCall:  (data) => console.log('Incoming:', data),
-  onCallAnswered:  (data) => console.log('Answered:', data),
-  onCallEnded:     (data) => console.log('Ended:', data),
-  onCallUnanswered: ()   => console.log('Missed call'),
+  onAgentStatus:    (status) => console.log('Agent:', status),  // 'READY' | 'NOT_READY' | 'AUX'
+  onIncomingCall:   (data)   => console.log('Incoming:', data),
+  onCallAnswered:   (data)   => console.log('Answered:', data),
+  onCallEnded:      (data)   => console.log('Ended:', data),
+  onCallUnanswered: ()       => console.log('Missed call'),
 });
 
 // Imperative controls (optional — widget has its own UI)
@@ -54,17 +75,155 @@ widget.dial('1002');  // programmatic dial
 widget.destroy();     // unmount widget
 ```
 
-### Custom container or offset
+---
+
+## Config reference
+
+### Top-level options
+
+| Option                      | Type                                                               | Default         | Description                                                       |
+|-----------------------------|--------------------------------------------------------------------|-----------------|-----------------------------------------------------------------|
+| `auth`                      | `object`                                                           | —               | SIP credentials (see [auth object](#auth-object))                 |
+| `pabxConfig`                | `{ auth: object }`                                                 | —               | Alternative config shape — use `pabxConfig.auth` instead of `auth` |
+| `X-CPAAS-Key-Fingerprint`  | `string`                                                           | —               | **Required** for agent status API calls. See [section below](#x-cpaas-key-fingerprint) |
+| `fingerprint`               | `string`                                                           | —               | Alias for `X-CPAAS-Key-Fingerprint`                              |
+| `cpaasKeyFingerprint`       | `string`                                                           | —               | Alias for `X-CPAAS-Key-Fingerprint`                              |
+| `placement`                 | `'bottom-left'` \| `'bottom-right'` \| `'top-left'` \| `'top-right'` | `'bottom-left'` | Fixed position of the floating widget                             |
+| `offset`                    | `{ bottom?, top?, left?, right? }`                                 | —               | CSS pixel coords — overrides `placement`                          |
+| `container`                 | `string` \| `HTMLElement`                                          | —               | Mount target. Auto-creates `<div id="omnix-widget-root">` if omitted |
+| `autoReady`                 | `boolean`                                                          | `true`          | Auto-call the Ready API right after SIP registration              |
+| `showAuxButton`             | `boolean`                                                          | `false`         | Show the AUX menu in the agent status bar                         |
+| `auxOptions`                | `Array<{ code: string, label: string }>`                           | `[]`            | Custom AUX reason codes shown in the status dropdown              |
+| `onRegisterStatus`          | `(status) => void`                                                 | —               | `'REGISTERED'` or `{ status: 'FAILED', reason: string }`         |
+| `onAgentStatus`             | `(status: string) => void`                                         | —               | `'READY'` \| `'NOT_READY'` \| `'AUX'`                            |
+| `onIncomingCall`            | `(data) => void`                                                   | —               | Fired on incoming SIP INVITE                                      |
+| `onCallAnswered`            | `(data) => void`                                                   | —               | Fired when call is established                                    |
+| `onCallEnded`               | `(data) => void`                                                   | —               | Fired on BYE / hangup                                             |
+| `onCallUnanswered`          | `() => void`                                                       | —               | Fired when incoming call is not answered (missed)                 |
+
+### `auth` object
+
+| Field       | Type     | Description                              |
+|-------------|----------|------------------------------------------|
+| `username`  | `string` | SIP username / extension number          |
+| `user_pbx`  | `string` | Alias for `username`                     |
+| `pwd_pbx`   | `string` | SIP password                             |
+| `secret`    | `string` | Alias for `pwd_pbx`                      |
+| `pabx_host` | `string` | SIP domain / WSS host (strips `http(s)://`) |
+| `pbxurl`    | `string` | Alias for `pabx_host`                    |
+| `port`      | `number` | WSS port (default `8089`)                |
+
+---
+
+## `X-CPAAS-Key-Fingerprint`
+
+This key is the **API authentication credential** used when the widget calls the CPaaS extension status endpoint:
+
+```
+POST https://api-cpaas.omnix.co.id/voice/extensions/status
+Header: X-CPAAS-Key-Fingerprint: <your-fingerprint>
+```
+
+The endpoint is hit automatically whenever the agent status changes (Ready / AUX / Not Ready). Without this key, status updates will silently fail and — if `autoReady: true` (default) — the widget will report `FAILED` registration even if the SIP connection itself succeeded.
+
+### Accepted config locations
+
+The widget looks for the fingerprint in the following order, using the first match:
+
+| Priority | Config key | Example |
+|----------|------------|---------|
+| 1 | `'X-CPAAS-Key-Fingerprint'` (top-level) | `{ 'X-CPAAS-Key-Fingerprint': 'abc123', auth: { ... } }` |
+| 2 | `fingerprint` (top-level) | `{ fingerprint: 'abc123', auth: { ... } }` |
+| 3 | `cpaasKeyFingerprint` (top-level) | `{ cpaasKeyFingerprint: 'abc123', auth: { ... } }` |
+| 4 | `env.fingerprint` | `{ env: { fingerprint: 'abc123' }, auth: { ... } }` |
+| 5 | `env.X_CPAAS_Key_Fingerprint` | `{ env: { X_CPAAS_Key_Fingerprint: 'abc123' }, auth: { ... } }` |
+| 6 | `pabxConfig['X-CPAAS-Key-Fingerprint']` | `{ pabxConfig: { 'X-CPAAS-Key-Fingerprint': 'abc123', auth: { ... } } }` |
+
+### Recommended usage
+
+```js
+// Option A — top-level key (simplest)
+OmnixWidget.init({
+  'X-CPAAS-Key-Fingerprint': 'your-fingerprint-here',
+  auth: { username: '1001', pwd_pbx: 'secret', pabx_host: 'sip.example.com' },
+  autoReady: true,
+});
+
+// Option B — inside pabxConfig (if your backend returns this shape)
+OmnixWidget.init({
+  pabxConfig: {
+    'X-CPAAS-Key-Fingerprint': 'your-fingerprint-here',
+    auth: { username: '1001', pwd_pbx: 'secret', pabx_host: 'sip.example.com' },
+  },
+});
+
+// Option C — via env object
+OmnixWidget.init({
+  env: { fingerprint: 'your-fingerprint-here' },
+  auth: { username: '1001', pwd_pbx: 'secret', pabx_host: 'sip.example.com' },
+});
+```
+
+> **Important:** If the fingerprint is missing and `autoReady: true` (default), the widget will emit `{ status: 'FAILED', reason: 'Failed to hit extension ready API' }` via `onRegisterStatus` even though the SIP connection itself was successful. Set `autoReady: false` if you do not have a fingerprint yet.
+
+### Custom container / offset
 
 ```js
 OmnixWidget.init({
   container: '#my-widget-slot',   // CSS selector or DOM element
-  // or use offset to position precisely (bypasses placement classes)
-  offset: { bottom: 80, left: 10 },
+  // — or —
+  offset: { bottom: 80, left: 10 }, // exact pixel position (bypasses placement)
   // ... rest of config
 });
 ```
 
+---
+
+## Instance API
+
+`OmnixWidget.init()` returns an instance with these methods:
+
+| Method         | Description                                                |
+|----------------|------------------------------------------------------------|
+| `answer()`     | Answer the current incoming call                           |
+| `hangup()`     | End the active / outgoing call                             |
+| `reject()`     | Reject the current incoming call                           |
+| `mute(bool)`   | `true` = mute microphone, `false` = unmute                 |
+| `hold(bool)`   | `true` = put call on hold, `false` = resume                |
+| `dial(number)` | Programmatically dial a number string                      |
+| `destroy()`    | Unmount the widget and clean up the DOM container          |
+
+---
+
+## Agent status bar
+
+When `autoReady: false` or `showAuxButton: true` a status bar appears at the bottom of the dialer.
+
+> **Note:** The agent status bar calls the CPaaS extension status API. You **must** provide `X-CPAAS-Key-Fingerprint` (or one of its aliases) for these calls to succeed.
+
+```js
+OmnixWidget.init({
+  auth: { ... },
+  'X-CPAAS-Key-Fingerprint': 'your-fingerprint-here',
+  autoReady:     false,          // agent starts as NOT_READY; must go Ready manually
+  showAuxButton: true,           // show AUX dropdown
+  auxOptions: [
+    { code: 'BRK', label: 'Break' },
+    { code: 'LCH', label: 'Lunch' },
+    { code: 'TRN', label: 'Training' },
+  ],
+  onAgentStatus: (status) => console.log('Agent status changed:', status),
+});
+```
+
+| Status      | Badge colour | Meaning                              |
+|-------------|--------------|--------------------------------------|
+| `READY`     | 🟢 Green     | Agent is available for calls         |
+| `NOT_READY` | ⚪ Gray      | Agent is unavailable                 |
+| `AUX`       | 🟡 Amber     | Agent is on a break / custom reason  |
+
+---
+
 ## React integration
 
 ```jsx
@@ -76,13 +235,22 @@ function App() {
 
   useEffect(() => {
     widgetRef.current = OmnixWidget.init({
-      platform: 'sipjs',
-      auth: { username: '1001', pwd_pbx: 'secret', pabx_host: 'sip.example.com' },
-      placement: 'bottom-right',
-      onIncomingCall: (data) => { /* navigate, show notification, etc. */ },
-      onCallAnswered: (data) => { /* routing logic */ },
-      onCallEnded:    ()     => { /* cleanup */ },
-      onRegisterStatus: (s)  => { /* update UI */ },
+      auth: {
+        username:  '1001',
+        pwd_pbx:   'secret',
+        pabx_host: 'sip.example.com',
+      },
+      'X-CPAAS-Key-Fingerprint': 'your-fingerprint-here',
+      placement:    'bottom-right',
+      autoReady:    true,
+      showAuxButton: true,
+      auxOptions:   [{ code: 'BRK', label: 'Break' }],
+
+      onIncomingCall:   (data) => { /* navigate, show notification, etc. */ },
+      onCallAnswered:   (data) => { /* routing logic */ },
+      onCallEnded:      ()     => { /* cleanup */ },
+      onRegisterStatus: (s)    => { /* update UI */ },
+      onAgentStatus:    (s)    => { /* s: 'READY' | 'NOT_READY' | 'AUX' */ },
     });
 
     return () => widgetRef.current?.destroy();
@@ -92,96 +260,114 @@ function App() {
 }
 ```
 
+---
+
 ## Vue integration
 
 ```js
-// composable or mounted()
 import { OmnixWidget } from 'voxnix';
 
+// inside setup() or options API
 onMounted(() => {
-  const widget = OmnixWidget.init({ ... });
+  const widget = OmnixWidget.init({
+    auth: { username: '1001', pwd_pbx: 'secret', pabx_host: 'sip.example.com' },
+    'X-CPAAS-Key-Fingerprint': 'your-fingerprint-here',
+    autoReady: false,
+    showAuxButton: true,
+    auxOptions: [{ code: 'BRK', label: 'Break' }],
+  });
   onUnmounted(() => widget.destroy());
 });
 ```
 
+---
+
 ## Via CDN (plain HTML, no bundler)
 
 ```html
-<!-- Include React CDN first -->
-<script src="https://unpkg.com/react@18/umd/react.production.min.js"></script>
-<script src="https://unpkg.com/react-dom@18/umd/react-dom.production.min.js"></script>
-
-<!-- Or use the self-contained IIFE build (includes React) -->
-<script src="./dist/voxnix.iife.js"></script>
+<!-- Self-contained IIFE build (bundles React) -->
+<script src="https://unpkg.com/voxnix/dist/voxnix.iife.js"></script>
 <script>
   OmnixWidget.init({
-    platform: 'sipjs',
     auth: {
-      username: '1001',
-      pwd_pbx:  'secret',
+      username:  '1001',
+      pwd_pbx:   'secret',
       pabx_host: 'sip.example.com',
     },
-    placement: 'bottom-right',
+    'X-CPAAS-Key-Fingerprint': 'your-fingerprint-here',
+    placement:     'bottom-right',
+    autoReady:     true,
+    showAuxButton: true,
+    auxOptions: [
+      { code: 'BRK', label: 'Break' },
+      { code: 'LCH', label: 'Lunch' },
+    ],
     onRegisterStatus: (s) => console.log('SIP:', s),
     onIncomingCall:   (d) => console.log('Incoming:', d),
+    onAgentStatus:    (s) => console.log('Agent:', s),
   });
 </script>
 ```
 
-## Config reference
+> If you need to use your own React instance, include `react@18` and `react-dom@18` UMD builds **before** the script tag and use `dist/voxnix.js` (ESM) or `dist/voxnix.umd.cjs` (CJS) instead.
 
-| Option              | Type                                           | Default         | Description                                      |
-|---------------------|------------------------------------------------|-----------------|--------------------------------------------------|
-| `platform`          | `string`                                       | `'sipjs'`       | Voice platform. Currently: `'sipjs'`             |
-| `auth`              | `object`                                       | —               | SIP credentials (see below)                      |
-| `placement`         | `'bottom-left'│'bottom-right'│'top-left'│'top-right'` | `'bottom-left'` | Fixed position of the floating widget    |
-| `offset`            | `{ bottom?, top?, left?, right? }`             | `undefined`     | CSS pixel coords — overrides `placement`         |
-| `container`         | `string │ HTMLElement`                         | `undefined`     | Mount target. Auto-creates `div` if omitted      |
-| `onIncomingCall`    | `(data) => void`                               | —               | Fired on incoming SIP INVITE                     |
-| `onCallAnswered`    | `(data) => void`                               | —               | Fired when call is established                   |
-| `onCallEnded`       | `(data) => void`                               | —               | Fired on BYE / hangup                            |
-| `onCallUnanswered`  | `() => void`                                   | —               | Fired when incoming call is not answered         |
-| `onRegisterStatus`  | `(status: string) => void`                     | —               | `'REGISTERED'` or `'FAILED'`                     |
+---
 
-### `auth` object
+## Keyboard shortcuts
 
-| Field         | Description                     |
-|---------------|---------------------------------|
-| `username`    | SIP username / extension        |
-| `pwd_pbx`     | SIP password                    |
-| `pabx_host`   | SIP domain / WSS host           |
-| `port`        | WSS port (default `8089`)       |
+These shortcuts are active whenever the dialer widget is open:
 
-## Instance API
+| Key              | State   | Action                        |
+|------------------|---------|-------------------------------|
+| `0–9`, `*`, `#`  | Idle    | Append digit to dial input    |
+| `Backspace`      | Idle    | Delete last digit             |
+| `Enter`          | Idle    | Dial the current number       |
+| `0–9`, `*`, `#`  | In-call | Send DTMF tone                |
 
-`OmnixWidget.init()` returns an instance with these methods:
-
-| Method          | Description                        |
-|-----------------|------------------------------------|
-| `answer()`      | Answer incoming call               |
-| `hangup()`      | End active call                    |
-| `reject()`      | Reject incoming call               |
-| `mute(bool)`    | Mute / unmute microphone           |
-| `hold(bool)`    | Hold / resume call                 |
-| `dial(number)`  | Programmatically dial a number     |
-| `destroy()`     | Unmount widget and clean up        |
+---
 
 ## Build
 
 ```bash
-# ESM + UMD (peer React, for npm consumers)
+# ESM + UMD (peer React — for npm consumers)
 yarn build:lib
 
-# Self-contained IIFE (bundles React, for CDN/script tag)
+# Self-contained IIFE (bundles React — for CDN / script tag)
 yarn build:iife
 
-# Both
+# Both outputs
 yarn build
 ```
 
+Output files in `dist/`:
+
+| File               | Format | React    | Use case              |
+|--------------------|--------|----------|-----------------------|
+| `voxnix.js`        | ESM    | peer dep | `import` / bundlers   |
+| `voxnix.umd.cjs`   | UMD    | peer dep | CommonJS / `require`  |
+| `voxnix.iife.js`   | IIFE   | bundled  | `<script>` / CDN      |
+
+---
+
 ## Development
 
 ```bash
 yarn install
-yarn dev
+yarn dev       # Vite dev server with hot reload
+yarn watch     # Vite library watch mode
 ```
+
+---
+
+## Changelog
+
+### v1.0.12
+- Rollback DevToast / console interceptor feature
+
+### v1.0.11 and earlier
+- Agent status bar (Ready / Not Ready / AUX) with configurable `auxOptions`
+- `onAgentStatus` callback
+- `autoReady` and `showAuxButton` config options
+- Keyboard shortcut support for dialer and DTMF
+- React 17 / 18 compatibility layer
+- Dual-SIP auth shape support (`auth` and `pabxConfig.auth`)