@qikdev/sdk 1.0.10 → 1.0.13

package/src/api/qik.socket.js

@@ -3,12 +3,37 @@ import { EventDispatcher } from './qik.utils.js';
 ///////////////////////////////////////////////////
 
 /**
- * Creates a new instance of QikSocket a module of the SDK
- * that contains all helper functions to do with realtime sockets
+ * Realtime updates over a WebSocket. Subscribe to a channel to be told when something changes, then
+ * re-read what you need with sdk.content.get / list: content messages say THAT a record changed, not what it
+ * now contains (the read applies the viewer's field permissions). Needs a signed-in user or application
+ * token; the socket connects on first use, reconnects automatically with back-off, resubscribes its channels
+ * after reconnecting, and reconnects when the user switches organisation. Changes made from this same
+ * browser window are not echoed back to it. Subscriptions are permission-checked by the server: a channel
+ * you may not use is simply never delivered.
+ * Channels (use these names; don't invent others):
+ * '<recordID>:edit' and '<recordID>:delete' — that record saved or deleted (needs view access to it);
+ * '<type or definition key>:create' / ':edit' / ':delete' — any record of that type, e.g. 'profile:edit' (needs viewany or editany on it);
+ * '<recordID>:restore' and '<type or definition key>:restore' — restored from the trash;
+ * '<eventID>:checkins', '<profileID>:checkins', '<eventID>:assignments' — check-ins and roster assignments;
+ * '<recordID>:comment' — comments posted on a record (the full comment);
+ * '<type or definition key>:definition' — that type's fields changed;
+ * 'notifications:<your persona, profile or user id>' and 'presence:<your organisation id>'.
+ * Each message is { channel, message }. For create and edit, message is
+ * { user: { name, _id, persona }, item: { _id, meta: { type, definition, uhash, updated, deleted } }, truncated: true }:
+ * compare item.meta.uhash with your copy and refetch when it differs. For delete and restore, message.item is just the id.
+ * Connection events: sdk.socket.addEventListener('connected' | 'disconnected' | 'error' | 'message', handler);
+ * 'message' receives every incoming message on every channel.
  * @name socket
  * @constructor
  * @hideconstructor
  * @param {QikAPI} qik A reference to the parent instance of the QikCore module. This module is usually created by a QikCore instance that passes itself in as the first argument.
+ * @example
+ * const channel = await sdk.socket.channel(`${recordID}:edit`);
+ * channel.addEventListener('message', async ({ message }) => {
+ *     record = await sdk.content.get(recordID);
+ * });
+ * // when finished
+ * channel.destroy();
  */
 
 const QikSocket = function(qik, mode) {
@@ -34,9 +59,19 @@ const QikSocket = function(qik, mode) {
 
     let socket;
     let timer;
+    let connecting;
+    let reconnectTimer;
+    let reconnectAttempts = 0;
+    let pendingSubscribes = [];
+    let flushScheduled = false;
     let buckets = {};
     const channels = {};
 
+    // Reconnect backoff: 1s, 2s, 4s ... capped, with jitter so a fleet of tabs
+    // that lost the socket together doesn't return in lockstep.
+    const RECONNECT_BASE_MS = 1000;
+    const RECONNECT_MAX_MS = 30000;
+
 
 
     //Create a new dispatcher
@@ -53,19 +88,27 @@ const QikSocket = function(qik, mode) {
 
 
     /**
-     * @description Create an event dispatcher instance and subscribe to a new socket channel.
-     * This can then be used to receive socket events for this channel
+     * @description Subscribes to a channel and returns a listener object for it, connecting first if needed.
+     * This is the easiest way to use the socket. Calling channel() again with the same key returns the same
+     * object, so it is shared by everything on the page that uses that key.
+     * The returned object has addEventListener('message', handler), removeEventListener('message', handler),
+     * removeAllListeners() and destroy(). Handlers receive { channel, message }. destroy() unsubscribes the
+     * channel and removes every handler on it — including other components' — so when the key may be shared,
+     * remove just your own handler instead.
      * @alias socket.channel
-     * @param  {String} key The key or name of the channel to subscribe to
+     * @param {String} key The channel name, e.g. `${recordID}:edit` or 'profile:create' (see the channel list above).
+     * @returns {Promise<Object>} The channel's listener object. If nobody is signed in the socket can't connect, and the returned object never receives messages.
      * @example
-     * const socketChannel = await sdk.socket.channel('awesome:notifications')
-     * socketChannel.addEventListener('message', function(message) {
-     *    console.log('Received a new message from the socket')
-     * })
+     * const channel = await sdk.socket.channel('profile:create');
+     * async function onCreated({ message }) {
+     *     const profile = await sdk.content.get(message.item._id);
+     * }
+     * channel.addEventListener('message', onCreated);
      *
-     * // Disconnect from this channel and remove all listeners
-     * socketChannel.destroy();
-     * 
+     * // Later: stop listening (keeps the channel for anyone else using it)
+     * channel.removeEventListener('message', onCreated);
+     * // Or: unsubscribe and remove all listeners on this channel
+     * channel.destroy();
      */
     service.channel = async function(key) {
         if (buckets[key]) {
@@ -138,17 +181,14 @@ const QikSocket = function(qik, mode) {
     function socketOpened(event) {
         service.debug ? console.log("[socket] Connection open", event) : null;
         service.connected = true;
+        reconnectAttempts = 0;
 
         dispatcher.dispatch('connected', event);
 
         // Replay every recorded subscription — frames broadcast before the
         // connection opened were dropped, and reconnects need them resent.
-        Object.keys(channels).forEach(function(channel) {
-            broadcast({
-                action: 'subscribe',
-                channel,
-            });
-        });
+        // One batched frame: the server writes them in a single update.
+        queueSubscribe(Object.keys(channels));
 
         // startHeartbeat();
     }
@@ -167,12 +207,28 @@ const QikSocket = function(qik, mode) {
         socket = null;
 
         if(service.autoreconnect) {
-            service.reconnect();
+            scheduleReconnect();
+        }
+    }
+
+    function scheduleReconnect() {
+        if (reconnectTimer) {
+            return;
         }
+
+        const delay = Math.min(RECONNECT_MAX_MS, RECONNECT_BASE_MS * Math.pow(2, reconnectAttempts));
+        const jittered = Math.round(delay * (0.5 + Math.random() / 2));
+        reconnectAttempts++;
+
+        service.debug ? console.log(`[socket] reconnecting in ${jittered}ms`) : null;
+        reconnectTimer = setTimeout(function() {
+            reconnectTimer = null;
+            service.reconnect();
+        }, jittered);
     }
 
     function socketError(error) {
-        console.log('[event] socketError', event);
+        console.log('[event] socketError', error);
         service.debug ? console.log("[socket] Error", error) : null;
         dispatcher.dispatch('error', error);
     }
@@ -187,6 +243,14 @@ const QikSocket = function(qik, mode) {
         if (eventData.channel) {
             dispatcher.dispatch(eventData.channel, eventData);
         }
+
+        // The server says this person's access changed (a role or access pass
+        // they hold was edited). Reload the session so what they can see
+        // follows; a failed reload keeps them signed in as they were.
+        const message = eventData.message;
+        if (message && message.type === 'session' && message.action === 'changed') {
+            Promise.resolve(qik.auth.sync({ keepOnError: true })).catch(function() {});
+        }
     }
 
     async function broadcast(data) {
@@ -203,28 +267,34 @@ const QikSocket = function(qik, mode) {
 
     ///////////////////////////////////////////////////
 
+    // Resolves once the socket is open. Waits on the 'connected' event rather
+    // than polling: a polling timer kept running forever if the socket was
+    // closed before it opened, and added up to a second to every connect.
     function wait() {
-        return new Promise(function(resolve) {
-            function check() {
-                if (service.connected) {
-                    return resolve(socket);
-                }
+        if (service.connected) {
+            return Promise.resolve(socket);
+        }
 
-                setTimeout(check, 1000);
+        return new Promise(function(resolve) {
+            function opened() {
+                service.removeEventListener('connected', opened);
+                resolve(socket);
             }
 
-            check();
+            service.addEventListener('connected', opened);
         })
     }
 
     ///////////////////////////////////////////////////
 
     /**
-     * @description Connect to the socket service
+     * @description Opens the socket connection, first refreshing the access token if it has expired. Resolves once
+     * connected. Calls made while a connection is being opened share it. channel() connects for you, so this is
+     * rarely needed. Resolves with nothing (and doesn't connect) when there's no access token.
      * @alias socket.connect
+     * @returns {Promise<WebSocket|undefined>} The underlying WebSocket once open, or undefined without a token.
      * @example
-     * const connected = await sdk.socket.connect()
-     * 
+     * await sdk.socket.connect();
      */
     service.connect = async function() {
         if (socket) {
@@ -237,6 +307,31 @@ const QikSocket = function(qik, mode) {
             return socket;
         }
 
+        // Callers arriving while we refresh the token share this attempt
+        // instead of each opening their own socket.
+        if (connecting) {
+            return connecting;
+        }
+
+        connecting = openSocket();
+        try {
+            return await connecting;
+        } finally {
+            connecting = null;
+        }
+    }
+
+    async function openSocket() {
+        // The socket authenticates once, with the token in its URL. Tokens
+        // expire (3 h), and a reconnect after the connection went idle would
+        // otherwise present a stale one: the server refuses to register it
+        // and the socket silently receives nothing. Refresh first if needed.
+        try {
+            await qik.auth.ensureValidToken();
+        } catch (err) {
+            service.debug ? console.log('[socket] - could not refresh token before connecting', err) : null;
+        }
+
         const accessToken = qik.auth.getCurrentToken();
 
         if (!accessToken) {
@@ -256,11 +351,12 @@ const QikSocket = function(qik, mode) {
 
 
     /**
-     * @description Reconnect to the socket service
+     * @description Connects again after the connection was lost or closed; does nothing if already connected.
+     * Channels that were subscribed are subscribed again once the connection opens.
      * @alias socket.reconnect
+     * @returns {Promise<WebSocket|undefined>} As for connect(); undefined when already connected.
      * @example
-     * const connected = await sdk.socket.reconnect()
-     * 
+     * await sdk.socket.reconnect();
      */
     service.reconnect = async function() {
         if(service.connected) {
@@ -278,11 +374,12 @@ const QikSocket = function(qik, mode) {
     ///////////////////////////////////////////////////
 
     /**
-     * @description Close the connection to the socket service
+     * @description Closes the connection without reconnecting automatically. Channel subscriptions are
+     * remembered and resent by a later connect() or reconnect(). Also available as sdk.socket.disconnect().
      * @alias socket.close
+     * @returns {Promise<undefined>}
      * @example
-     * const closed = await sdk.socket.close()
-     * 
+     * await sdk.socket.close();
      */
     service.close = async function() {
         if (!socket) {
@@ -290,6 +387,11 @@ const QikSocket = function(qik, mode) {
             return;
         }
 
+        if (reconnectTimer) {
+            clearTimeout(reconnectTimer);
+            reconnectTimer = null;
+        }
+
         const previousSetting = service.autoreconnect;
         service.autoreconnect = false;
         socket.close();
@@ -302,17 +404,68 @@ const QikSocket = function(qik, mode) {
         service.autoreconnect = previousSetting;
     }
 
+    /**
+     * @description Same as close(): closes the connection without reconnecting automatically.
+     * @alias socket.disconnect
+     * @returns {Promise<undefined>}
+     * @example
+     * await sdk.socket.disconnect();
+     */
     service.disconnect = service.close;
 
     ///////////////////////////////////////////////////
 
+    // Subscribes requested in the same tick go out as one frame. A page opening
+    // several channels at once used to send one frame each; the server then
+    // updated the same connection row from several places at the same moment
+    // and those requests queued behind each other for seconds.
+    function queueSubscribe(list) {
+        list.forEach(function(channel) {
+            if (!pendingSubscribes.includes(channel)) {
+                pendingSubscribes.push(channel);
+            }
+        });
+
+        if (flushScheduled) {
+            return;
+        }
+
+        flushScheduled = true;
+        setTimeout(flushSubscribes, 0);
+    }
+
+    function flushSubscribes() {
+        flushScheduled = false;
+        const list = pendingSubscribes.filter(function(channel) {
+            return channels[channel];
+        });
+        pendingSubscribes = [];
+
+        if (!list.length) {
+            return;
+        }
+
+        if (list.length === 1) {
+            broadcast({ action: 'subscribe', channel: list[0] });
+        } else {
+            broadcast({ action: 'subscribe', channels: list });
+        }
+    }
+
+    ///////////////////////////////////////////////////
+
     /**
-     * @description Subscribe to a socket channel
+     * @description Asks the server to send this channel's messages to this connection. Takes no callback: listen with
+     * sdk.socket.addEventListener(channel, handler), which receives { channel, message }. Only works while the
+     * socket is connected (otherwise it logs and does nothing) — channel() handles connecting, subscribing and
+     * listening in one step and is usually the better choice. Subscriptions made in the same moment are sent together.
      * @alias socket.subscribe
-     * @param  {String} key The name of the channel to subscribe to
+     * @param {String} channel The channel name.
+     * @returns {Promise<undefined>}
      * @example
-     * const subscribed = await sdk.socket.subscribe('some:cool:alert')
-     * 
+     * await sdk.socket.connect();
+     * sdk.socket.subscribe(`${eventID}:checkins`);
+     * sdk.socket.addEventListener(`${eventID}:checkins`, ({ message }) => refresh());
      */
     service.subscribe = async function(channel) {
         if (!socket) {
@@ -320,12 +473,8 @@ const QikSocket = function(qik, mode) {
             return;
         }
 
-        broadcast({
-            action: 'subscribe',
-            channel,
-        })
-
         channels[channel] = true;
+        queueSubscribe([channel]);
 
         dispatcher.dispatch('subscribe', channel)
         service.debug ? console.log(`[socket] - subscribed to ${channel}`) : null;
@@ -334,12 +483,13 @@ const QikSocket = function(qik, mode) {
     ///////////////////////////////////////////////////
 
     /**
-     * @description Unsubscribe from a socket channel
+     * @description Tells the server to stop sending this channel's messages. Listeners added with addEventListener
+     * stay attached (remove them yourself). Only works while connected.
      * @alias socket.unsubscribe
-     * @param  {String} key The name of the channel to unsubscribe from
+     * @param {String} channel The channel name.
+     * @returns {Promise<undefined>}
      * @example
-     * const unsubscribed = await sdk.socket.unsubscribe('some:cool:alert')
-     * 
+     * sdk.socket.unsubscribe(`${eventID}:checkins`);
      */
     service.unsubscribe = async function(channel) {
         if (!socket) {
@@ -360,31 +510,47 @@ const QikSocket = function(qik, mode) {
 
     ///////////////////////////////////////////////////
 
-    // Reconnect the socket whenever the authenticated organisation changes.
-    // The WebSocket authenticates with an access token at connect time, so the
-    // connection stays bound to whichever organisation was active when it
-    // opened. Switching organisations issues a new token but leaves the socket
-    // untouched, so without this it keeps streaming the previous
-    // organisation's events. Reconnecting re-authenticates with the new token.
-    let currentOrganisationID = qik.utils.id(qik.auth.getCurrentUser()?.organisation);
+    // Reconnect the socket whenever who is signed in changes: signing in,
+    // signing out, switching organisation or switching person. The WebSocket
+    // authenticates with an access token at connect time, so the connection
+    // stays bound to whoever was signed in when it opened — channels opened
+    // before sign-in stay refused, and an organisation switch keeps streaming
+    // the previous organisation's events. Reconnecting re-authenticates with
+    // the new token and replays every channel.
+    //
+    // The stored user is { session, token }; who someone is lives on the
+    // session. Only these ids are read — sessions and tokens are untouched.
+    function identityOf(user) {
+        const session = user && user.session;
+        if (!session) {
+            return '';
+        }
+        return [
+            qik.utils.id(session.organisation),
+            qik.utils.id(session.persona),
+            qik.utils.id(session._id),
+        ].join('|');
+    }
+
+    let currentIdentity = identityOf(qik.auth.getCurrentUser());
 
     qik.auth.addEventListener('change', async function(user) {
-        const organisationID = qik.utils.id(user?.organisation);
+        const identity = identityOf(user);
 
-        // Ignore auth changes that don't change the organisation (e.g. routine
-        // access token refreshes) so we don't churn the connection needlessly.
-        if (organisationID === currentOrganisationID) {
+        // Ignore auth changes that leave the same person signed in (e.g.
+        // routine access token refreshes) so we don't churn the connection.
+        if (identity === currentIdentity) {
             return;
         }
 
-        currentOrganisationID = organisationID;
+        currentIdentity = identity;
 
         // Nothing to reconnect if the socket was never opened.
         if (!socket) {
             return;
         }
 
-        service.debug ? console.log('[socket] - organisation changed, reconnecting') : null;
+        service.debug ? console.log('[socket] - signed-in identity changed, reconnecting') : null;
         await service.close();
         await service.reconnect();
     });

package/src/api/qik.storage.js

@@ -1,5 +1,9 @@
 /**
- * Storage abstraction layer for handling both localStorage and httpOnly cookie storage
+ * Where the SDK keeps the signed-in session. Not a namespace of its own: sdk.auth creates one adapter,
+ * available as sdk.auth.storageAdapter, and uses it for getCurrentUser, set and logout.
+ * LocalStorageAdapter (the default, despite its name) keeps the session in memory only, so it is lost on page
+ * reload unless your app saves and restores it with sdk.auth.set. CookieStorageAdapter (useHttpOnlyCookies)
+ * keeps the session details in memory and leaves the tokens to httpOnly cookies set by the server.
  * @module QikStorage
  */
 
@@ -70,7 +74,7 @@ class StorageAdapter {
 }
 
 /**
- * localStorage-based storage adapter (current behavior)
+ * The default adapter. Despite the name it does not use window.localStorage: the session is held in memory.
  */
 class LocalStorageAdapter extends StorageAdapter {
     constructor() {
@@ -111,7 +115,8 @@ class LocalStorageAdapter extends StorageAdapter {
 }
 
 /**
- * Cookie-based storage adapter for httpOnly cookies
+ * Adapter used with useHttpOnlyCookies: session details in memory, tokens in httpOnly cookies the server sets
+ * (so getAccessToken, getRefreshToken and getTokenExpiry always return null).
  */
 class CookieStorageAdapter extends StorageAdapter {
     constructor(options = {}) {
@@ -281,11 +286,15 @@ class CookieStorageAdapter extends StorageAdapter {
 }
 
 /**
- * Factory function to create appropriate storage adapter
- * @param {Object} options Configuration options
- * @param {Boolean} options.useHttpOnlyCookies Whether to use cookie storage
- * @param {Object} options.cookieConfig Cookie configuration options
- * @returns {StorageAdapter} Storage adapter instance
+ * Creates the adapter sdk.auth uses: a CookieStorageAdapter when useHttpOnlyCookies is set and the browser
+ * accepts cookies, otherwise a LocalStorageAdapter (in memory).
+ * @param {Object} [options] Configuration.
+ * @param {Boolean} [options.useHttpOnlyCookies] Use cookie mode.
+ * @param {Object} [options.cookieConfig] Cookie settings: { domain, secure, sameSite }.
+ * @returns {StorageAdapter} The adapter.
+ * @example
+ * const adapter = createStorageAdapter({ useHttpOnlyCookies: false });
+ * adapter.setUser(session);
  */
 export function createStorageAdapter(options = {}) {
     if (options.useHttpOnlyCookies) {

package/src/api/qik.system.js

@@ -1,8 +1,7 @@
 ///////////////////////////////////////////////////
 
 /**
- * Creates a new QikSystem instance.
- * This module provides a number of helper functions for the system
+ * Platform reference data that isn't specific to an organisation.
  * @alias system
  * @constructor
  * @hideconstructor
@@ -21,10 +20,12 @@ export default function(qik) {
 
     /**
      * @alias system.countries
-     * @description Helper function for retrieving a full list of all countries, their ISO codes
-     * and phone number prefixes. Helpful for populating dropdown lists.
+     * @description Retrieves every country (GET /system/countries) with its ISO codes, name, phone calling
+     * codes and currencies, e.g. to fill a country picker. Loaded once and shared by later calls.
+     * @returns {Promise<Array<Object>>} Countries, each with alpha2 (e.g. 'AU'), alpha3, name, countryCallingCodes (e.g. ['+61']) and currencies.
      * @example
-     * const countries = await sdk.system.countries()
+     * const countries = await sdk.system.countries();
+     * const options = countries.map((country) => ({ title: country.name, value: country.alpha2 }));
      */
     service.countries = async function() {