@visns-studio/visns-components 6.24.4 → 6.26.0

package/src/components/callQueue/callPopStatus.js

@@ -0,0 +1,236 @@
+/**
+ * Call pop status store.
+ * -----------------------------------------------------------------------
+ * A tiny module-level record of what the call pop's plumbing is actually
+ * doing right now: was an Echo instance handed over, did the private channel
+ * authorise, what state is the socket in, when did the last `.queue.*` event
+ * land, how many cards are on screen.
+ *
+ * It exists because "the pop only shows up some of the time" is unanswerable
+ * from the pop itself — a failed `/broadcasting/auth` is invisible, a dropped
+ * socket is invisible, and a webhook that never arrived looks exactly like a
+ * browser that never subscribed. Every one of those now leaves a trace here.
+ *
+ * Deliberately dependency-free and framework-free:
+ *   - `getCallPopStatus()` returns a plain snapshot (safe to JSON.stringify),
+ *   - `updateCallPopStatus(patch)` merges, stamps `updatedAt` and fires the
+ *     `callpop:status` window event so a panel can re-render,
+ *   - `appendCallPopLog(message, level, patch)` does the same and pushes one
+ *     line onto a 50-entry ring buffer.
+ *
+ * Module-level state is the point: the pop mounts once at the app root and the
+ * diagnostics panel mounts somewhere else entirely (Settings -> Call Queues),
+ * with no shared React tree between them. The window event is the bridge.
+ *
+ * Nothing here throws. A store that breaks the pop it is meant to explain
+ * would be worse than no store at all.
+ */
+
+/** The window event dispatched on every change. */
+export const CALL_POP_STATUS_EVENT = 'callpop:status';
+
+/** How many log lines are kept. Oldest are dropped first. */
+export const CALL_POP_LOG_LIMIT = 50;
+
+/**
+ * The empty record. Every field is present from the first read, so a panel
+ * rendering before the pop has mounted shows "unknown", not `undefined`.
+ */
+export const emptyCallPopStatus = () => ({
+    /** Did the `echo` prop/factory yield an instance? null = not asked yet. */
+    echoAvailable: null,
+    /** Does this user hold the monitor permission? */
+    canMonitor: null,
+    /** The private channel the pop subscribed (or tried) to. */
+    channel: null,
+    /** pusher-js connection state: connected/connecting/unavailable/… */
+    connectionState: null,
+    connectionChangedAt: null,
+    /** Has the channel reported pusher:subscription_succeeded? */
+    subscribed: false,
+    subscribedAt: null,
+    /** `{status, message}` from pusher:subscription_error, else null. */
+    subscriptionError: null,
+    /** The one-shot `/ajax/call-queue/live` snapshot. */
+    snapshotAt: null,
+    snapshotError: null,
+    snapshotCalls: 0,
+    /** Broadcast events received since the page loaded. */
+    eventsReceived: 0,
+    lastEventName: null,
+    lastEventAt: null,
+    /** `{nonce, receivedAt}` of the last diagnostic ping delivered here. */
+    lastPing: null,
+    /** Cards currently on screen. */
+    visibleCalls: 0,
+    /** Times the socket has left `connected`. */
+    disconnects: 0,
+    /** When any of the above last changed. */
+    updatedAt: null,
+    /** Ring buffer of `{at, level, message}`, newest last. */
+    log: [],
+});
+
+let status = emptyCallPopStatus();
+
+/** Timestamps are ISO strings so they survive JSON round trips unchanged. */
+const now = () => new Date().toISOString();
+
+/**
+ * A defensive copy: callers (a React state setter, a "Copy status" button)
+ * must never be able to mutate the store by holding on to what they read.
+ */
+const snapshot = () => ({ ...status, log: status.log.slice() });
+
+/** Read the current status. */
+export const getCallPopStatus = () => snapshot();
+
+/** Drop everything back to the empty record. Used by tests. */
+export const resetCallPopStatus = () => {
+    status = emptyCallPopStatus();
+
+    return snapshot();
+};
+
+/** Fire the window event, if there is a window and it will have it. */
+const broadcast = (detail) => {
+    if (typeof window === 'undefined') {
+        return;
+    }
+
+    try {
+        const CustomEventCtor =
+            typeof window.CustomEvent === 'function'
+                ? window.CustomEvent
+                : typeof CustomEvent === 'function'
+                  ? CustomEvent
+                  : null;
+
+        if (!CustomEventCtor || typeof window.dispatchEvent !== 'function') {
+            return;
+        }
+
+        window.dispatchEvent(
+            new CustomEventCtor(CALL_POP_STATUS_EVENT, { detail })
+        );
+    } catch (error) {
+        // A listener that throws, or an environment with no CustomEvent, must
+        // not take the pop down with it.
+    }
+};
+
+/**
+ * Merge a patch into the status, stamp `updatedAt` and notify listeners.
+ *
+ * `patch.log`, when an array, replaces the buffer (trimmed to the limit);
+ * appending one line is `appendCallPopLog` below.
+ *
+ * @param {object} patch
+ * @returns {object} The new snapshot.
+ */
+export const updateCallPopStatus = (patch = {}) => {
+    if (!patch || typeof patch !== 'object') {
+        return snapshot();
+    }
+
+    const next = { ...status, ...patch, updatedAt: now() };
+
+    next.log = Array.isArray(patch.log)
+        ? patch.log.slice(-CALL_POP_LOG_LIMIT)
+        : status.log;
+
+    status = next;
+
+    const detail = snapshot();
+
+    broadcast(detail);
+
+    return detail;
+};
+
+/**
+ * Append one line to the log (and optionally merge a patch alongside it, so a
+ * state change and its explanation are one update and one event).
+ *
+ * @param {string} message
+ * @param {string} [level] 'info' | 'warn' | 'error'
+ * @param {object} [patch] Merged in the same update.
+ *
+ * @returns {object} The new snapshot.
+ */
+export const appendCallPopLog = (message, level = 'info', patch = {}) => {
+    const entry = {
+        at: now(),
+        level: typeof level === 'string' && level !== '' ? level : 'info',
+        message: String(message ?? ''),
+    };
+
+    return updateCallPopStatus({
+        ...patch,
+        log: [...status.log, entry].slice(-CALL_POP_LOG_LIMIT),
+    });
+};
+
+/**
+ * Record one received broadcast event: bumps the counter and remembers which
+ * event it was and when.
+ *
+ * @param {string} name  Event name, e.g. '.queue.ringing'.
+ * @param {object} [patch] Anything else worth storing with it.
+ */
+export const noteCallPopEvent = (name, patch = {}) =>
+    updateCallPopStatus({
+        ...patch,
+        eventsReceived: status.eventsReceived + 1,
+        lastEventName: name,
+        lastEventAt: now(),
+    });
+
+/**
+ * Record a pusher connection state change, counting every departure from
+ * `connected` as a disconnect — that count is the single most useful number
+ * on the panel when staff say the pop "works for a while and then stops".
+ *
+ * @param {string} state Next connection state.
+ */
+export const noteCallPopConnectionState = (state) => {
+    const wasConnected = status.connectionState === 'connected';
+    const isConnected = state === 'connected';
+
+    return updateCallPopStatus({
+        connectionState: state ?? null,
+        connectionChangedAt: now(),
+        disconnects:
+            wasConnected && !isConnected
+                ? status.disconnects + 1
+                : status.disconnects,
+    });
+};
+
+/**
+ * Expose the reader on `window` next to the demo hooks, so support can run
+ * `callPopStatus()` in a staff member's console without a build of anything.
+ *
+ * @returns {Function} Removes the hook again. Always safe to call.
+ */
+export const installCallPopStatusHook = () => {
+    if (typeof window === 'undefined') {
+        return () => {};
+    }
+
+    try {
+        window.callPopStatus = getCallPopStatus;
+    } catch (error) {
+        return () => {};
+    }
+
+    return () => {
+        try {
+            delete window.callPopStatus;
+        } catch (error) {
+            // A sealed window: nothing to undo.
+        }
+    };
+};
+
+export default getCallPopStatus;

package/src/components/callQueue/callQueueHelpers.js

@@ -12,6 +12,32 @@ export const MONITOR_PERMISSION = 'Call Queue Monitor';
 /** Badge text for a queue Zoom sent without a name. */
 export const FALLBACK_QUEUE_NAME = 'Call Queue';
 
+/**
+ * What rang. A 'queue' call arrived on one of the account's call queues; a
+ * 'direct' call rang a staff member's own extension (their DID, or a transfer
+ * to it) and has no queue at all — `queueId` is null on those.
+ */
+export const KIND_QUEUE = 'queue';
+export const KIND_DIRECT = 'direct';
+
+/**
+ * Pickup codes are keyed by `pickupKey`, not by queue id: a direct call is
+ * intercepted through Zoom's call PICKUP GROUP, which is one code for the whole
+ * group rather than a per-queue one, and the snapshot files it under this
+ * literal key.
+ */
+export const DIRECT_PICKUP_KEY = 'direct';
+
+/** Badge text for a direct call, whatever the server called its "queue". */
+export const DIRECT_BADGE_TEXT = 'Direct';
+
+/**
+ * How old a card has to be before a snapshot that no longer lists it is taken
+ * as proof the call is over. Anything younger is left alone: a `.queue.ringing`
+ * that beat its own snapshot to the browser must not be reconciled away.
+ */
+export const SNAPSHOT_MIN_AGE_MS = 30000;
+
 /**
  * Does this user hold the monitor permission?
  *
@@ -19,15 +45,30 @@ export const FALLBACK_QUEUE_NAME = 'Call Queue';
  * the Spatie shape `roles[].permissions[].name`. Direct (non-role) permissions
  * are checked too, since Spatie allows assigning a permission straight to a
  * user.
+ *
+ * NO PERMISSION CONFIGURED = EVERY SIGNED-IN USER MAY MONITOR. Passing `null`
+ * (or '') as `permission` switches the gate off rather than failing closed: a
+ * deployment that wants the whole practice to see the pop says so by naming no
+ * permission, in the component prop and in the server's channel authorisation
+ * alike. Only a truthy permission name is ever looked for on the profile, and
+ * only a signed-in user (a profile object) is ever let through.
+ *
+ * Omitting the argument entirely is NOT the same thing: the default parameter
+ * still asks for `MONITOR_PERMISSION`, which is what every existing caller of
+ * the one-argument form relies on.
  */
 export const hasMonitorPermission = (
     userProfile,
     permission = MONITOR_PERMISSION
 ) => {
-    if (!userProfile) {
+    if (!userProfile || typeof userProfile !== 'object') {
         return false;
     }
 
+    if (permission === null || permission === '') {
+        return true;
+    }
+
     const roles = Array.isArray(userProfile.roles) ? userProfile.roles : [];
 
     const viaRole = roles.some((role) =>
@@ -236,13 +277,55 @@ export const normaliseCall = (raw) => {
             ? null
             : String(rawQueueId);
 
+    // 'direct' or 'queue'. Anything the server does not label is a queue call,
+    // which is what every payload was before direct calls existed.
+    const kind =
+        String(raw.kind ?? '')
+            .trim()
+            .toLowerCase() === KIND_DIRECT
+            ? KIND_DIRECT
+            : KIND_QUEUE;
+
     const rawQueueName = raw.queueName ?? raw.queue_name ?? '';
-    const queueName = String(rawQueueName).trim() || FALLBACK_QUEUE_NAME;
+    const queueName =
+        String(rawQueueName).trim() ||
+        (kind === KIND_DIRECT ? DIRECT_BADGE_TEXT : FALLBACK_QUEUE_NAME);
+
+    // Which entry of `pickup_codes` this call's Pick up button reads. Defaults
+    // to the queue id, so a server that does not send the key behaves exactly
+    // as it did before; a direct call with no key falls back to the literal
+    // 'direct', which is where its group code is filed.
+    const rawPickupKey = raw.pickupKey ?? raw.pickup_key ?? null;
+    const suppliedPickupKey =
+        rawPickupKey === null || rawPickupKey === undefined
+            ? ''
+            : String(rawPickupKey).trim();
+    const pickupKey =
+        suppliedPickupKey !== ''
+            ? suppliedPickupKey
+            : kind === KIND_DIRECT
+              ? DIRECT_PICKUP_KEY
+              : queueId;
+
+    const text = (...values) => {
+        const found = values.find(
+            (value) => value !== null && value !== undefined
+        );
+
+        return found === undefined ? '' : String(found).trim();
+    };
 
     return {
         callId: String(callId),
+        kind,
         queueId,
         queueName,
+        pickupKey,
+        // Who the call is actually ringing. Only direct calls carry these; a
+        // queue call rings a queue, not a person, and leaves them ''.
+        calleeName: text(raw.calleeName, raw.callee_name),
+        calleeExtension: text(raw.calleeExtension, raw.callee_extension),
+        forwardedByName: text(raw.forwardedByName, raw.forwarded_by_name),
         callerNumber: raw.callerNumber ?? raw.caller_number ?? raw.from ?? '',
         callerName: raw.callerName ?? raw.caller_name ?? '',
         client: raw.client ?? null,
@@ -250,12 +333,211 @@ export const normaliseCall = (raw) => {
         // leaves it null and the expansion fetches the drill-down endpoint.
         tasks: Array.isArray(raw.tasks) ? raw.tasks : null,
         startedAt: raw.startedAt ?? raw.started_at ?? new Date().toISOString(),
+        // When THIS browser first saw the call, which is not when it started
+        // ringing: the snapshot reconcile ages cards by their arrival here.
+        receivedAt:
+            typeof raw.receivedAt === 'number' ? raw.receivedAt : Date.now(),
         status: 'ringing',
+        // Set when a `.queue.missed` says one ringing leg was declined or timed
+        // out. The call may still be ringing elsewhere, so this only starts a
+        // grace timer — it never removes the card by itself.
+        missedAt: typeof raw.missedAt === 'number' ? raw.missedAt : null,
         isDemo: raw.isDemo === true || raw.is_demo === true,
         leaving: false,
     };
 };
 
+/** The badge's text: a direct call says so, a queue call names its queue. */
+export const callBadgeLabel = (call) =>
+    call?.kind === KIND_DIRECT
+        ? DIRECT_BADGE_TEXT
+        : call?.queueName || FALLBACK_QUEUE_NAME;
+
+/**
+ * Who a direct call is ringing, by name if Zoom knew one and by extension if it
+ * did not. '' when neither is known — the card then just says "Direct".
+ */
+export const calleeLabel = (call) => {
+    const name = String(call?.calleeName ?? '').trim();
+
+    if (name !== '') {
+        return name;
+    }
+
+    const extension = String(call?.calleeExtension ?? '').trim();
+
+    return extension === '' ? '' : `ext ${extension}`;
+};
+
+/**
+ * The direct card's one extra line: "Ringing Jane Smith", plus who transferred
+ * it when the call reached that extension via someone else. '' for a queue
+ * call, or a direct call with no callee at all.
+ */
+export const directRingingLine = (call) => {
+    if (call?.kind !== KIND_DIRECT) {
+        return '';
+    }
+
+    const who = calleeLabel(call);
+
+    if (who === '') {
+        return '';
+    }
+
+    const forwardedBy = String(call?.forwardedByName ?? '').trim();
+
+    return forwardedBy === ''
+        ? `Ringing ${who}`
+        : `Ringing ${who} · transferred by ${forwardedBy}`;
+};
+
+/** The `pickup_codes` key for a call, tolerating a payload from an older server. */
+export const pickupKeyFor = (call) => {
+    const key = call?.pickupKey;
+
+    if (key !== null && key !== undefined && String(key).trim() !== '') {
+        return String(key).trim();
+    }
+
+    if (call?.kind === KIND_DIRECT) {
+        return DIRECT_PICKUP_KEY;
+    }
+
+    return call?.queueId ?? null;
+};
+
+/** A call's dial string, or '' when nothing is configured for its key. */
+export const resolvePickupCode = (call, codes) => {
+    const key = pickupKeyFor(call);
+
+    if (key === null || !codes || typeof codes !== 'object') {
+        return '';
+    }
+
+    const code = codes[key];
+
+    return typeof code === 'string' && code.trim() !== '' ? code.trim() : '';
+};
+
+/**
+ * Mark one call as having had a leg declined. Idempotent: a second `.missed`
+ * for the same call leaves the ORIGINAL stamp in place, so the grace period is
+ * measured from the first decline rather than being extended by every later
+ * one. Returns the same array when nothing changed, so React can skip a render.
+ */
+export const applyMissed = (calls, callId, now = Date.now()) => {
+    const list = Array.isArray(calls) ? calls : [];
+    const id = String(callId ?? '');
+
+    if (id === '') {
+        return list;
+    }
+
+    let changed = false;
+
+    const next = list.map((call) => {
+        if (call.callId !== id || call.leaving || call.missedAt) {
+            return call;
+        }
+
+        changed = true;
+
+        return { ...call, missedAt: now };
+    });
+
+    return changed ? next : list;
+};
+
+/**
+ * Ingest a ringing call: append it when it is new, and clear any missed mark
+ * when it is one already on screen — a fresh `.queue.ringing` for a call whose
+ * first leg was declined proves the call is still live, so its grace period is
+ * cancelled rather than allowed to expire.
+ *
+ * A card already animating out is left alone: its exit timer will drop it, and
+ * un-setting `leaving` here would leave a card that can never be removed.
+ */
+export const applyRinging = (calls, call) => {
+    const list = Array.isArray(calls) ? calls : [];
+
+    if (!call) {
+        return list;
+    }
+
+    const existing = list.find((item) => item.callId === call.callId);
+
+    if (!existing) {
+        return [...list, call];
+    }
+
+    if (!existing.missedAt) {
+        return list;
+    }
+
+    return list.map((item) =>
+        item.callId === call.callId ? { ...item, missedAt: null } : item
+    );
+};
+
+/**
+ * Work out what a fresh `/ajax/call-queue/live` snapshot means for the cards
+ * already on screen. The server's liveness rule is authoritative, with one
+ * deliberate exception in each direction:
+ *
+ *   - a call the snapshot lists and the screen does not is ADDED, unless the
+ *     user has already dismissed it here (`skipIds`) — a dismiss is local, so
+ *     the server keeps listing the call and a refresh would otherwise put the
+ *     card straight back;
+ *   - a card the snapshot does not list is REMOVED only once it is older than
+ *     `minAgeMs` (30s), and never when it is a demo card or already leaving.
+ *     Anything younger is presumed to be a ringing event that overtook the
+ *     snapshot request rather than a call that has ended.
+ *
+ * Pure: it decides, and the caller applies the decision through the same
+ * add/remove paths every other code path uses (so removals still animate).
+ *
+ * @param {Array}  current  Cards on screen (normalised calls).
+ * @param {Array}  snapshot Normalised calls from the snapshot.
+ * @param {number} now
+ * @param {object} [options] `{ minAgeMs, skipIds }`.
+ *
+ * @returns {{add: Array, remove: Array}} Calls to add, callIds to remove.
+ */
+export const reconcileSnapshot = (
+    current,
+    snapshot,
+    now = Date.now(),
+    options = {}
+) => {
+    const live = Array.isArray(current) ? current : [];
+    const incoming = (Array.isArray(snapshot) ? snapshot : []).filter(Boolean);
+    const minAgeMs = options.minAgeMs ?? SNAPSHOT_MIN_AGE_MS;
+    const skipIds =
+        options.skipIds instanceof Set
+            ? options.skipIds
+            : new Set(options.skipIds ?? []);
+
+    const onScreen = new Set(live.map((call) => call.callId));
+    const listed = new Set(incoming.map((call) => call.callId));
+
+    const add = incoming.filter(
+        (call) => !onScreen.has(call.callId) && !skipIds.has(call.callId)
+    );
+
+    const remove = live
+        .filter(
+            (call) =>
+                !call.leaving &&
+                !call.isDemo &&
+                !listed.has(call.callId) &&
+                now - (call.receivedAt ?? 0) > minAgeMs
+        )
+        .map((call) => call.callId);
+
+    return { add, remove };
+};
+
 /**
  * Coerce the snapshot's `pickup_codes` block into a plain `{ queueId: code }`
  * map, dropping anything that is not a non-empty string on both sides. A queue

package/src/components/columns/ColumnRenderers.jsx

@@ -15,6 +15,9 @@ import {
 } from '../../utils/relationshipSortingUtils';
 import { formatCellContent } from '../generic/shared/formatters';
 import { arrayCountFrom } from '../utils/displayValue';
+// One Australian numbering table, shared with the card row — see
+// `utils/contactChannels.js` for why it is not defined here any more.
+import { formatPhoneNumber } from '../utils/contactChannels';
 
 // Stage Toggle Utility Functions
 const buildToggleUrl = (urlTemplate, stageItem, rowData) => {
@@ -3170,52 +3173,6 @@ export const renderTotalColumn = () => {
     };
 };
 
-// Phone Number formatter
-const formatPhoneNumber = (phoneNumber) => {
-    if (!phoneNumber) return '';
-    
-    // Remove all non-digit characters
-    let cleanNumber = phoneNumber.replace(/\D/g, '');
-
-    // +61 spellings collapse to the local form so every branch below applies.
-    if (cleanNumber.match(/^61[2-9]\d{8}$/)) {
-        cleanNumber = '0' + cleanNumber.slice(2);
-    }
-    
-    // Check if it's an Australian mobile number (starts with 04 and has 10 digits)
-    if (cleanNumber.match(/^04\d{8}$/)) {
-        // Mobile format: 0400 000 000
-        return cleanNumber.replace(/(\d{4})(\d{3})(\d{3})/, '$1 $2 $3');
-    }
-    
-    // Check if it's a 1300/1800 number (10 digits starting with 1300 or 1800)
-    if (cleanNumber.match(/^1[38]00\d{6}$/)) {
-        // 1300/1800 format: 1300 000 000
-        return cleanNumber.replace(/(\d{4})(\d{3})(\d{3})/, '$1 $2 $3');
-    }
-    
-    // Check if it's an Australian landline number (8 digits with area code, or 10 digits total)
-    if (cleanNumber.match(/^0[2-9]\d{8}$/)) {
-        // Landline format: (02) 0000 0000
-        return cleanNumber.replace(/(\d{2})(\d{4})(\d{4})/, '($1) $2 $3');
-    }
-    
-    // If it doesn't match standard Australian patterns, return as is with some basic formatting
-    if (cleanNumber.length >= 8) {
-        // Generic formatting for longer numbers
-        if (cleanNumber.length === 8) {
-            return cleanNumber.replace(/(\d{4})(\d{4})/, '$1 $2');
-        } else if (cleanNumber.length === 9) {
-            return cleanNumber.replace(/(\d{1})(\d{4})(\d{4})/, '$1 $2 $3');
-        } else if (cleanNumber.length === 10) {
-            return cleanNumber.replace(/(\d{2})(\d{4})(\d{4})/, '($1) $2 $3');
-        }
-    }
-    
-    // Return original if no formatting pattern matches
-    return phoneNumber;
-};
-
 // ABN formatter
 const formatABN = (abn) => {
     if (!abn) return '';