@visns-studio/visns-components 6.6.3 → 6.15.0

package/src/components/sms/smsLiveState.js

@@ -0,0 +1,132 @@
+/**
+ * The bookkeeping behind "is this inbox actually live?".
+ *
+ * Split out of `useSmsLive` so it can be tested without React, and because the
+ * question is subtler than it looks. Calling `echo.private(name)` returns a
+ * channel object immediately — before `/broadcasting/auth` has been asked, let
+ * alone answered. A 403 or a 419 there, or a websocket that never connects at
+ * all, leaves the consumer holding a channel that will never deliver an event.
+ * If that counts as "live" the polling fallback switches itself off and the
+ * page stops refreshing entirely, which is precisely the failure we saw in the
+ * field: an open inbox and not one occupied channel on Pusher.
+ *
+ * So live means *confirmed*: at least one channel has reported
+ * `pusher:subscription_succeeded`, and the connection underneath it has not
+ * since gone away.
+ */
+
+/**
+ * Connection states in which nothing can arrive, whatever the channels think.
+ *
+ * pusher-js resubscribes by itself once it reconnects, so these are not
+ * terminal — they just mean "poll in the meantime".
+ */
+export const DEAD_CONNECTION_STATES = ['unavailable', 'failed', 'disconnected'];
+
+/**
+ * Live iff a channel has confirmed and the socket is not known to be down.
+ *
+ * @param {Set<string>|Array<string>|number|null} succeeded Confirmed channels.
+ * @param {string|null} [connectionState] Latest pusher connection state.
+ *
+ * @returns {boolean}
+ */
+export const deriveLiveState = (succeeded, connectionState = null) => {
+    let count = 0;
+
+    if (typeof succeeded === 'number') count = succeeded;
+    else if (succeeded instanceof Set) count = succeeded.size;
+    else if (Array.isArray(succeeded)) count = succeeded.length;
+
+    if (count <= 0) return false;
+
+    return !DEAD_CONNECTION_STATES.includes(connectionState);
+};
+
+/** Whether a connection state means "nothing will arrive right now". */
+export const isDeadConnectionState = (state) => DEAD_CONNECTION_STATES.includes(state);
+
+/**
+ * Watch one subscription for its authorisation result.
+ *
+ * Echo's `PusherPrivateChannel` exposes `.subscribed(cb)` and `.error(cb)`;
+ * older versions, and anything hand-rolled, only expose the raw pusher-js
+ * channel at `.subscription`, which we bind the same two events on directly.
+ * Either way the caller learns whether the channel is real.
+ *
+ * Everything is guarded: a channel object that is missing one of these must
+ * cost us the confirmation, not the other channels or the render.
+ *
+ * @param {object} subscription Echo channel (or a stand-in in tests).
+ * @param {object} handlers
+ * @param {Function} [handlers.onSuccess] Called on subscription_succeeded.
+ * @param {Function} [handlers.onError]   Called on subscription_error.
+ *
+ * @returns {Function} Unbinds whatever was bound. Always safe to call.
+ */
+export const subscriptionMonitor = (subscription, { onSuccess, onError } = {}) => {
+    if (!subscription) return () => {};
+
+    const success = () => {
+        try {
+            onSuccess?.();
+        } catch (error) {
+            // A consumer's setState must not break the pusher callback chain.
+        }
+    };
+
+    const failure = (payload) => {
+        try {
+            onError?.(payload);
+        } catch (error) {
+            // Same.
+        }
+    };
+
+    // Preferred path: Echo's own callbacks.
+    if (typeof subscription.subscribed === 'function') {
+        let bound = false;
+
+        try {
+            subscription.subscribed(success);
+            bound = true;
+        } catch (error) {
+            // Fall through to the raw channel below.
+        }
+
+        if (bound) {
+            try {
+                if (typeof subscription.error === 'function') subscription.error(failure);
+            } catch (error) {
+                // An unwatchable error channel is not worth failing over.
+            }
+
+            // Echo gives no way to unbind these individually; leaving the
+            // channel (which the hook does on cleanup) drops them with it.
+            return () => {};
+        }
+    }
+
+    // Fallback: the raw pusher-js channel.
+    const raw = subscription.subscription;
+
+    if (!raw || typeof raw.bind !== 'function') return () => {};
+
+    try {
+        raw.bind('pusher:subscription_succeeded', success);
+        raw.bind('pusher:subscription_error', failure);
+    } catch (error) {
+        return () => {};
+    }
+
+    return () => {
+        try {
+            raw.unbind?.('pusher:subscription_succeeded', success);
+            raw.unbind?.('pusher:subscription_error', failure);
+        } catch (error) {
+            // Already gone.
+        }
+    };
+};
+
+export default deriveLiveState;

package/src/components/sms/useSmsLive.js

@@ -0,0 +1,307 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import CustomFetch from '../Fetch';
+import { resolveSmsEndpoints } from './smsEndpoints';
+import { deriveLiveState, isDeadConnectionState, subscriptionMonitor } from './smsLiveState';
+
+/** The two events the backend broadcasts on a line's channel. */
+export const EVENT_RECEIVED = '.sms.received';
+export const EVENT_UPDATED = '.sms.updated';
+
+/** The channel a line broadcasts on, when the consumer does not name one. */
+export const defaultChannelFor = (lineId) => `sms-line.${lineId}`;
+
+/**
+ * Live messaging: Pusher when it is wired up, polling when it is not.
+ *
+ * Both halves matter. The CRM has Echo, so the inbox updates the moment a
+ * reply lands. The fixture, a tab with a dead websocket, and any deployment
+ * where broadcasting is not configured have no Echo at all — and a messaging
+ * inbox that silently stops updating is worse than one that was never live,
+ * because nothing on screen says so. So the fallback is not an error state,
+ * it is a slower version of the same behaviour: `/unread` every thirty
+ * seconds, plus whatever the mounted surface wants to re-fetch alongside it.
+ *
+ * What "live" means here is deliberately strict. `instance.private(name)`
+ * hands back a channel object straight away, long before
+ * `/broadcasting/auth` has approved it — so treating that as live is how an
+ * inbox ends up subscribed to nothing, polling nothing, and showing a
+ * conversation that stopped updating an hour ago. Live therefore waits for
+ * `pusher:subscription_succeeded` on at least one channel, and drops again if
+ * the connection goes `unavailable`/`failed`/`disconnected`. A subscription
+ * whose auth fails must never be allowed to silence the poller.
+ *
+ * Even once live, a slow safety-net poll keeps running (`livePollInterval`,
+ * a minute by default) so a single dropped event costs a minute of staleness
+ * rather than the rest of the session. It skips the immediate first tick —
+ * the subscription is already delivering.
+ *
+ * The `echo` prop is an instance OR a factory, matching CallQueuePop: a
+ * factory is called inside the effect rather than at mount, so a user without
+ * the permission never opens a Pusher connection at all.
+ *
+ * @param {object}   options
+ * @param {object|Function|null} options.echo        Echo instance, or `() => echo`.
+ * @param {Array}    options.lines                   `[{id}]` — the lines to listen on.
+ * @param {Function} [options.channelFor]            `(lineId) => 'sms-line.7.dev'`.
+ * @param {object}   [options.endpoints]             Partial endpoints override.
+ * @param {boolean}  [options.enabled]               Off entirely when false.
+ * @param {Function} [options.onReceived]            `({thread, message}) => void`.
+ * @param {Function} [options.onUpdated]             `({thread, message}) => void`.
+ * @param {Function} [options.onUnread]              `({total, by_line, by_thread}) => void`.
+ * @param {Function} [options.onPoll]                Ticks on every poll, live or not.
+ * @param {number}   [options.pollInterval]          Fallback poll; default 30s.
+ * @param {number}   [options.livePollInterval]      Safety net while live; default 60s, 0 off.
+ *
+ * @returns {{live: boolean, refreshUnread: Function, subscribed: number}}
+ */
+const useSmsLive = ({
+    echo = null,
+    lines = [],
+    channelFor = defaultChannelFor,
+    endpoints,
+    enabled = true,
+    onReceived,
+    onUpdated,
+    onUnread,
+    onPoll,
+    pollInterval = 30_000,
+    livePollInterval = 60_000,
+} = {}) => {
+    const [live, setLive] = useState(false);
+    const [subscribed, setSubscribed] = useState(0);
+
+    // Everything below is read through a ref so that a consumer passing an
+    // inline arrow — `onReceived={(e) => ...}`, `echo={() => getEcho()}`,
+    // which is the normal way to write both — does not tear the subscription
+    // down and rebuild it on every render. Only the channel names do that.
+    const echoRef = useRef(echo);
+    echoRef.current = echo;
+
+    const channelForRef = useRef(channelFor);
+    channelForRef.current = channelFor;
+
+    const receivedRef = useRef(onReceived);
+    receivedRef.current = onReceived;
+
+    const updatedRef = useRef(onUpdated);
+    updatedRef.current = onUpdated;
+
+    const unreadRef = useRef(onUnread);
+    unreadRef.current = onUnread;
+
+    const pollRef = useRef(onPoll);
+    pollRef.current = onPoll;
+
+    const mountedRef = useRef(true);
+
+    // The channels that have actually been confirmed, and the last connection
+    // state we heard about — the two inputs `live` is derived from.
+    const succeededRef = useRef(new Set());
+    const connectionStateRef = useRef(null);
+
+    useEffect(
+        () => () => {
+            mountedRef.current = false;
+        },
+        []
+    );
+
+    const routes = resolveSmsEndpoints(endpoints);
+    const unreadUrl = routes.unread;
+
+    /** Pull the unread counts once. Safe to call from anywhere. */
+    const refreshUnread = useCallback(() => {
+        CustomFetch(
+            unreadUrl,
+            'GET',
+            null,
+            (result) => {
+                if (!mountedRef.current) return;
+
+                unreadRef.current?.(result || {});
+            },
+            // Silent: a background count that fails must not toast at someone
+            // in the middle of typing.
+            () => {}
+        ).catch(() => {});
+    }, [unreadUrl]);
+
+    /** Re-read the two inputs and publish the answer. */
+    const syncLive = useCallback(() => {
+        if (!mountedRef.current) return;
+
+        const count = succeededRef.current.size;
+
+        setSubscribed(count);
+        setLive(deriveLiveState(count, connectionStateRef.current));
+    }, []);
+
+    // The channel names, as one stable string, so the effect below re-runs
+    // when the set of lines actually changes and not when the array identity
+    // does — `lines` is rebuilt by every fetch.
+    const channelKey = (Array.isArray(lines) ? lines : [])
+        .map((line) => (line && line.id !== undefined ? line.id : line))
+        .filter((id) => id !== undefined && id !== null)
+        .map((id) => channelForRef.current(id))
+        .join('|');
+
+    useEffect(() => {
+        succeededRef.current = new Set();
+        connectionStateRef.current = null;
+
+        if (!enabled || channelKey === '' || typeof window === 'undefined') {
+            syncLive();
+
+            return undefined;
+        }
+
+        const source = echoRef.current;
+        const instance = typeof source === 'function' ? source() : source;
+
+        if (!instance) {
+            syncLive();
+
+            return undefined;
+        }
+
+        const names = channelKey.split('|');
+        const subscriptions = [];
+        const monitors = [];
+
+        names.forEach((name) => {
+            try {
+                // Until /broadcasting/auth knows the channel the subscription
+                // just fails auth — pusher-js logs a warning, nothing of ours
+                // throws — so a line the user cannot see is harmless here. It
+                // simply never joins the confirmed set below.
+                const subscription = instance.private(name);
+
+                subscription.listen(EVENT_RECEIVED, (event) => {
+                    receivedRef.current?.(event || {});
+                });
+
+                subscription.listen(EVENT_UPDATED, (event) => {
+                    updatedRef.current?.(event || {});
+                });
+
+                monitors.push(
+                    subscriptionMonitor(subscription, {
+                        onSuccess: () => {
+                            succeededRef.current.add(name);
+                            syncLive();
+                        },
+                        onError: () => {
+                            succeededRef.current.delete(name);
+                            syncLive();
+                        },
+                    })
+                );
+
+                subscriptions.push({ name, subscription });
+            } catch (error) {
+                // One bad channel must not cost the others their subscription.
+            }
+        });
+
+        // Not live yet — that waits for a subscribed callback. The poller
+        // covers the grace window in between, including its immediate tick.
+        syncLive();
+
+        // The socket underneath. When it goes, every channel goes with it,
+        // whatever the confirmed set still says; pusher-js resubscribes on
+        // its own once it comes back, so we clear the set and let the
+        // subscribed callbacks re-fill it.
+        let unbindState = () => {};
+
+        try {
+            const connection = instance.connector?.pusher?.connection;
+
+            if (connection && typeof connection.bind === 'function') {
+                const onStateChange = (states) => {
+                    const current = states?.current ?? states;
+
+                    connectionStateRef.current = current;
+
+                    if (isDeadConnectionState(current)) succeededRef.current = new Set();
+
+                    syncLive();
+                };
+
+                connection.bind('state_change', onStateChange);
+                connectionStateRef.current = connection.state ?? null;
+
+                unbindState = () => {
+                    try {
+                        connection.unbind?.('state_change', onStateChange);
+                    } catch (error) {
+                        // Already gone.
+                    }
+                };
+            }
+        } catch (error) {
+            // No reachable connection object: channel confirmations alone
+            // decide, which is the same answer we gave before.
+        }
+
+        return () => {
+            unbindState();
+            monitors.forEach((unbind) => {
+                try {
+                    unbind();
+                } catch (error) {
+                    // Already gone.
+                }
+            });
+
+            subscriptions.forEach(({ name, subscription }) => {
+                try {
+                    subscription.stopListening(EVENT_RECEIVED);
+                    subscription.stopListening(EVENT_UPDATED);
+                    instance.leave(name);
+                } catch (error) {
+                    // Nothing to clean up.
+                }
+            });
+
+            succeededRef.current = new Set();
+            connectionStateRef.current = null;
+        };
+    }, [enabled, channelKey, syncLive]);
+
+    /**
+     * The fallback, and the safety net.
+     *
+     * With nothing confirmed live this is the only thing keeping the page
+     * fresh, so it starts immediately and runs at `pollInterval`. Once a
+     * channel confirms it drops back to `livePollInterval` — slow enough to
+     * be free, quick enough that a dropped event is invisible — and skips the
+     * immediate tick, because the subscription is already delivering.
+     *
+     * `onPoll` is what a mounted inbox hangs its thread-list refresh on, so
+     * the page makes one decision about how often to talk to the server
+     * rather than two.
+     */
+    useEffect(() => {
+        if (!enabled) return undefined;
+
+        const interval = live ? livePollInterval : pollInterval;
+
+        if (!(interval > 0)) return undefined;
+
+        const tick = () => {
+            refreshUnread();
+            pollRef.current?.();
+        };
+
+        if (!live) tick();
+
+        const timer = setInterval(tick, interval);
+
+        return () => clearInterval(timer);
+    }, [enabled, live, pollInterval, livePollInterval, refreshUnread]);
+
+    return { live, refreshUnread, subscribed };
+};
+
+export default useSmsLive;