oneentry 1.0.176 → 1.0.177

package/esm/web-socket/lazySocket.d.ts

@@ -8,11 +8,12 @@ import type { Socket } from 'socket.io-client';
  * queued and replayed onto the real socket as soon as the chunk resolves, and every later
  * call passes straight through.
  * @param {() => Promise<Socket>} createSocket - Loads Socket.io and creates the socket.
- * @returns {Socket} Stand-in usable exactly like the socket it will become.
+ * @returns {Socket} Stand-in usable like the socket it will become.
  * @description Listener registration is what matters for ordering, and it is safe: the queue is
  * replayed in the same tick the socket is created, before the connection can deliver anything.
- * The one visible difference is that methods returning a value (e.g. `listeners()`) cannot answer
- * before the chunk arrives — they return the proxy instead. Reading state (`id`, `connected`, …)
- * is accurate, and awaiting `socket.io` or other nested objects is only possible once loaded.
+ * Before the chunk arrives: `emitWithAck` returns a Promise settled by the real socket,
+ * `hasListeners`/`listeners` answer from the queued listeners, `socket.io.on(…)` and `volatile` are
+ * queued, assignments (e.g. `socket.auth = …`) are applied to the real socket, and other properties
+ * read `undefined`. A failed chunk load is reported to the `connect_error` listeners.
  */
-export default function createLazySocket(createSocket: () => Promise<Socket>): Socket;
+export default function createLazySocket<S extends Socket = Socket>(createSocket: () => Promise<S>): S;

package/esm/web-socket/lazySocket.js

@@ -7,9 +7,41 @@ const PENDING_STATE = {
     id: undefined,
     connected: false,
     disconnected: true,
-    active: false,
+    // A socket created with `autoConnect` is active from the start
+    active: true,
     recovered: false,
 };
+/**
+ * Socket methods that may be called before the real socket exists: they are queued and replayed.
+ * @description Any other property read early answers `undefined`. Queuing every name used to put
+ * `toJSON` (read by `JSON.stringify`) into the queue, and its replay threw and lost every listener.
+ */
+const QUEUEABLE = new Set([
+    'on',
+    'once',
+    'off',
+    'addListener',
+    'removeListener',
+    'removeAllListeners',
+    'onAny',
+    'prependAny',
+    'offAny',
+    'onAnyOutgoing',
+    'prependAnyOutgoing',
+    'offAnyOutgoing',
+    'emit',
+    'send',
+    'connect',
+    'open',
+    'disconnect',
+    'close',
+    'compress',
+    'timeout',
+]);
+/**
+ * Methods of `socket.io` (the Manager) that may be called before the real socket exists.
+ */
+const IO_QUEUEABLE = new Set(['on', 'once', 'off', 'reconnection']);
 /**
  * Wraps a not-yet-loaded Socket.io socket in a synchronous stand-in.
  *
@@ -19,30 +51,108 @@ const PENDING_STATE = {
  * queued and replayed onto the real socket as soon as the chunk resolves, and every later
  * call passes straight through.
  * @param {() => Promise<Socket>} createSocket - Loads Socket.io and creates the socket.
- * @returns {Socket} Stand-in usable exactly like the socket it will become.
+ * @returns {Socket} Stand-in usable like the socket it will become.
  * @description Listener registration is what matters for ordering, and it is safe: the queue is
  * replayed in the same tick the socket is created, before the connection can deliver anything.
- * The one visible difference is that methods returning a value (e.g. `listeners()`) cannot answer
- * before the chunk arrives — they return the proxy instead. Reading state (`id`, `connected`, …)
- * is accurate, and awaiting `socket.io` or other nested objects is only possible once loaded.
+ * Before the chunk arrives: `emitWithAck` returns a Promise settled by the real socket,
+ * `hasListeners`/`listeners` answer from the queued listeners, `socket.io.on(…)` and `volatile` are
+ * queued, assignments (e.g. `socket.auth = …`) are applied to the real socket, and other properties
+ * read `undefined`. A failed chunk load is reported to the `connect_error` listeners.
  */
 export default function createLazySocket(createSocket) {
     let socket;
+    let loadError;
     const queued = [];
+    const pendingProps = new Map();
+    // The listeners the queue leaves registered, `off`/`removeAllListeners` applied in order
+    const queuedListeners = (event) => {
+        let listeners = [];
+        for (const { target, method, args } of queued) {
+            if (target !== 'socket')
+                continue;
+            if (method === 'on' || method === 'once' || method === 'addListener') {
+                listeners.push({
+                    event: args[0],
+                    fn: args[1],
+                });
+            }
+            else if (method === 'off' || method === 'removeListener') {
+                // `off()` without arguments removes every listener, as in Socket.io
+                listeners = listeners.filter((l) => (args.length > 0 && l.event !== args[0]) ||
+                    (args.length > 1 && l.fn !== args[1]));
+            }
+            else if (method === 'removeAllListeners') {
+                listeners = listeners.filter((l) => args.length > 0 && l.event !== args[0]);
+            }
+        }
+        return listeners
+            .filter((l) => event === undefined || l.event === event)
+            .map((l) => l.fn);
+    };
     const loading = createSocket().then((created) => {
+        // Assigned first: a listener running during the replay already reaches the real socket
+        socket = created;
+        for (const [property, value] of pendingProps) {
+            created[property] = value;
+        }
+        pendingProps.clear();
         // Replay before returning: the connection cannot emit anything until this tick ends,
-        // so no event registered through the proxy can be missed.
-        for (const { method, args } of queued) {
-            created[method](...args);
+        // so no event registered through the proxy can be missed. One failing call must not
+        // drop the rest of the queue.
+        for (const { target, method, args } of queued) {
+            try {
+                const owner = target === 'io' ? created.io : created;
+                if (method === 'volatile') {
+                    void owner.volatile;
+                }
+                else if (method === 'emitWithAck') {
+                    // Replayed in its place in the queue: a `timeout()` queued before it is its own flag
+                    const { resolve, reject } = args.pop();
+                    owner.emitWithAck(...args).then(resolve, reject);
+                }
+                else {
+                    owner[method](...args);
+                }
+            }
+            catch (error) {
+                // eslint-disable-next-line no-undef, no-console
+                console.error(`OneEntry SDK: socket.${method}() failed`, error);
+            }
         }
         queued.length = 0;
-        socket = created;
         return created;
     });
-    // A failed chunk load must not surface as an unhandled rejection
+    // A failed chunk load must not surface as an unhandled rejection: it goes to the
+    // `connect_error` listeners, the place Socket.io reports a connection that cannot open
     loading.catch((error) => {
-        // eslint-disable-next-line no-undef, no-console
-        console.error('OneEntry SDK: failed to load socket.io-client', error);
+        loadError = error;
+        const listeners = queuedListeners('connect_error');
+        for (const { method, args } of queued) {
+            if (method === 'emitWithAck') {
+                args[args.length - 1].reject(error);
+            }
+        }
+        queued.length = 0;
+        if (listeners.length === 0) {
+            // eslint-disable-next-line no-undef, no-console
+            console.error('OneEntry SDK: could not create the socket', error);
+        }
+        for (const listener of listeners) {
+            listener(error);
+        }
+    });
+    const ioProxy = new Proxy({}, {
+        get(_target, property) {
+            if (typeof property === 'string' && IO_QUEUEABLE.has(property)) {
+                return (...args) => {
+                    if (!loadError) {
+                        queued.push({ target: 'io', method: property, args });
+                    }
+                    return ioProxy;
+                };
+            }
+            return undefined;
+        },
     });
     const proxy = new Proxy({}, {
         get(_target, property) {
@@ -54,13 +164,100 @@ export default function createLazySocket(createSocket) {
             if (property === 'then' || typeof property === 'symbol') {
                 return undefined;
             }
+            if (pendingProps.has(property)) {
+                return pendingProps.get(property);
+            }
+            if (property === 'active') {
+                // Active until a queued disconnect or a failed load, as the real socket would be
+                // The last queued connect/disconnect decides, as on the real socket
+                const last = [...queued]
+                    .reverse()
+                    .find(({ target, method }) => target === 'socket' &&
+                    ['disconnect', 'close', 'connect', 'open'].includes(method));
+                return (!loadError &&
+                    !(last && (last.method === 'disconnect' || last.method === 'close')));
+            }
             if (property in PENDING_STATE) {
                 return PENDING_STATE[property];
             }
-            return (...args) => {
-                queued.push({ method: property, args });
+            if (property === 'io') {
+                return ioProxy;
+            }
+            if (property === 'volatile') {
+                if (!loadError) {
+                    queued.push({ target: 'socket', method: 'volatile', args: [] });
+                }
                 return proxy;
-            };
+            }
+            if (property === 'emitWithAck') {
+                return (...args) => loadError
+                    ? Promise.reject(loadError)
+                    : new Promise((resolve, reject) => {
+                        queued.push({
+                            target: 'socket',
+                            method: 'emitWithAck',
+                            args: [...args, { resolve, reject }],
+                        });
+                    });
+            }
+            if (property === 'hasListeners') {
+                return (event) => queuedListeners(event).length > 0;
+            }
+            if (property === 'listeners') {
+                return (event) => queuedListeners(event);
+            }
+            if (typeof property === 'string' && QUEUEABLE.has(property)) {
+                return (...args) => {
+                    if (loadError &&
+                        (property === 'on' || property === 'once') &&
+                        args[0] === 'connect_error') {
+                        // Registered after the load already failed: report it straight away
+                        args[1](loadError);
+                    }
+                    else if (!loadError) {
+                        queued.push({ target: 'socket', method: property, args });
+                    }
+                    return proxy;
+                };
+            }
+            return undefined;
+        },
+        set(_target, property, value) {
+            if (socket) {
+                return Reflect.set(socket, property, value);
+            }
+            pendingProps.set(property, value);
+            return true;
+        },
+        has(_target, property) {
+            if (socket) {
+                return property in socket;
+            }
+            return (typeof property === 'string' &&
+                (property in PENDING_STATE ||
+                    QUEUEABLE.has(property) ||
+                    [
+                        'io',
+                        'volatile',
+                        'emitWithAck',
+                        'hasListeners',
+                        'listeners',
+                    ].includes(property) ||
+                    pendingProps.has(property)));
+        },
+        ownKeys() {
+            return socket ? Reflect.ownKeys(socket) : [];
+        },
+        getOwnPropertyDescriptor(_target, property) {
+            if (!socket) {
+                return undefined;
+            }
+            const descriptor = Reflect.getOwnPropertyDescriptor(socket, property);
+            // The proxy target holds none of these keys, so they must be reported configurable
+            return descriptor ? { ...descriptor, configurable: true } : undefined;
+        },
+        getPrototypeOf() {
+            return socket ? Reflect.getPrototypeOf(socket) : Object.prototype;
         },
     });
     return proxy;

package/esm/web-socket/wsApi.d.ts

@@ -1,7 +1,7 @@
 import type { Socket } from 'socket.io-client';
 import AsyncModules from '../base/asyncModules.js';
 import type StateModule from '../base/stateModule.js';
-import type { IWS } from './wsInterfaces.js';
+import type { IWS, IWsServerEvents } from './wsInterfaces.js';
 /**
  * Controllers for working with users
  * @handle /api/content/ws
@@ -17,11 +17,14 @@ export default class WsApi extends AsyncModules implements IWS {
     /**
      * Creates an instance of an object Socket.io with a connection.
      * @handleName connect
-     * @returns {Socket} Returns a Socket instance.
-     * @description Creates an instance of an object Socket.io with a connection. This method requires user authorization.
+     * @returns {Socket<IWsServerEvents>} Returns a Socket instance.
+     * @description Opens a Socket.io connection. Without a signed-in user the socket is a guest and
+     * receives only notifications sent to everyone; personal ones need `AuthProvider.auth` first.
+     * The current access token is sent on every (re)connection, so a refreshed token is picked up.
+     * Every call opens a separate connection.
      * Socket.io is imported on demand, so projects that never open a socket do not bundle it; the returned
      * value is usable immediately either way (see `createLazySocket`).
      * @see {@link https://js-sdk.oneentry.cloud/docs/web-socket/connect connect} documentation.
      */
-    connect(): Socket;
+    connect(): Socket<IWsServerEvents>;
 }

package/esm/web-socket/wsApi.js

@@ -16,28 +16,65 @@ export default class WsApi extends AsyncModules {
     /**
      * Creates an instance of an object Socket.io with a connection.
      * @handleName connect
-     * @returns {Socket} Returns a Socket instance.
-     * @description Creates an instance of an object Socket.io with a connection. This method requires user authorization.
+     * @returns {Socket<IWsServerEvents>} Returns a Socket instance.
+     * @description Opens a Socket.io connection. Without a signed-in user the socket is a guest and
+     * receives only notifications sent to everyone; personal ones need `AuthProvider.auth` first.
+     * The current access token is sent on every (re)connection, so a refreshed token is picked up.
+     * Every call opens a separate connection.
      * Socket.io is imported on demand, so projects that never open a socket do not bundle it; the returned
      * value is usable immediately either way (see `createLazySocket`).
      * @see {@link https://js-sdk.oneentry.cloud/docs/web-socket/connect connect} documentation.
      */
     connect() {
-        if (!this.state.accessToken) {
-            // eslint-disable-next-line no-undef, no-console
-            console.error('User is unauthorized');
-        }
         return createLazySocket(async () => {
+            var _a;
             const { io } = await import('socket.io-client');
-            return io(this.state.url, {
+            // A session restored from a refresh token has no access token until its first
+            // request: the socket went out as a guest. Obtain it first, as REST calls do.
+            if (!this.state.accessToken &&
+                this._canRefresh() &&
+                !this.state.customAuth) {
+                await this.refreshToken();
+            }
+            // A path in the project URL (a reverse proxy prefix) belongs to the socket path:
+            // passed in the URL, Socket.io read it as a namespace and answered "Invalid namespace"
+            // A proxy path (`/oneentry`) resolves against the page
+            // `''` (the site root proxy) must not resolve to the current page's path
+            const base = new URL(this.state.url || '/', (_a = globalThis.location) === null || _a === void 0 ? void 0 : _a.href);
+            const path = base.pathname.replace(/\/+$/, '') + '/api/content/ws';
+            // The platform registers a user only with both the bearer and `x-device-metadata`;
+            // without the latter every SDK socket was a guest. Read on each (re)connection so a
+            // refreshed token is used, and no `Bearer undefined` for a guest.
+            const headers = () => ({
+                ...(this.state.accessToken
+                    ? { Authorization: 'Bearer ' + this.state.accessToken }
+                    : {}),
+                'x-app-token': this.state.token,
+                'x-device-metadata': this._getDeviceMetadata(),
+            });
+            const socket = io(base.origin, {
                 autoConnect: true,
-                path: '/api/content/ws',
+                path,
                 transports: ['websocket'],
-                extraHeaders: {
-                    Authorization: 'Bearer ' + this.state.accessToken,
-                    'x-app-token': this.state.token,
-                },
+                // Browsers drop `extraHeaders` on a WebSocket: the same data goes in the
+                // handshake `auth` payload as well
+                extraHeaders: headers(),
+                auth: (cb) => cb({
+                    token: this.state.accessToken,
+                    appToken: this.state.token,
+                    deviceMetadata: this._getDeviceMetadata(),
+                }),
             });
+            // Every connection — automatic reconnection or a manual `socket.connect()` after
+            // `disconnect()` — goes through `Manager.open`, which builds the transport from
+            // `opts`: refresh the headers there, or a sign-in after the first connect never reached it
+            const manager = socket.io;
+            const open = manager.open.bind(manager);
+            manager.open = (...args) => {
+                manager.opts.extraHeaders = headers();
+                return open(...args);
+            };
+            return socket;
         });
     }
 }

package/esm/web-socket/wsInterfaces.d.ts

@@ -1,4 +1,39 @@
 import type { Socket } from 'socket.io-client';
+/**
+ * @interface IWsNotificationAttribute
+ * @property {string} identifier - Attribute marker. Example: "title".
+ * @property {string} type - Attribute type. Example: "string".
+ * @property {unknown} value - Attribute value as the platform sent it.
+ * @description An attribute carried by a notification.
+ */
+interface IWsNotificationAttribute {
+    identifier: string;
+    type: string;
+    value: unknown;
+}
+/**
+ * @interface IWsNotification
+ * @property {string} message - Notification text; an empty string when the event has none.
+ * @property {string} [type] - What the notification is about. Example: "product", "order", "user", "form", "refund".
+ * @property {IWsNotificationAttribute[]} [attributes] - Attributes selected for the notification in the event settings.
+ * @description Payload of the `notification` event. Fields beyond `message` depend on the event
+ * (`product`, `order`, `user`, `formData`, …) and are typed `unknown` until checked.
+ */
+interface IWsNotification {
+    message: string;
+    type?: string;
+    attributes?: IWsNotificationAttribute[];
+    [key: string]: unknown;
+}
+/**
+ * @interface IWsServerEvents
+ * @property {function(IWsNotification): void} notification - Event notification sent by the platform.
+ * @description Events the platform sends over the socket. Other event names stay untyped.
+ */
+interface IWsServerEvents {
+    notification: (payload: IWsNotification) => void;
+    [event: string]: (...args: any[]) => void;
+}
 /**
  * @interface IWS
  * @description This interface defines a method for establishing a WebSocket connection.
@@ -7,10 +42,12 @@ interface IWS {
     /**
      * Creates an instance of an object Socket.io with a connection.
      * @handleName connect
-     * @returns {Socket} Returns a Socket instance.
-     * @description Creates an instance of an object Socket.io with a connection. This method requires user authorization.
+     * @returns {Socket<IWsServerEvents>} Returns a Socket instance.
+     * @description Opens a Socket.io connection. Without a signed-in user the socket is a guest and
+     * receives only notifications sent to everyone; personal ones need `AuthProvider.auth` first.
+     * Every call opens a separate connection.
      * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
      */
-    connect(): Socket;
+    connect(): Socket<IWsServerEvents>;
 }
-export type { IWS };
+export type { IWS, IWsNotification, IWsNotificationAttribute, IWsServerEvents };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oneentry",
-  "version": "1.0.176",
+  "version": "1.0.177",
   "description": "OneEntry NPM package",
   "main": "dist/index.js",
   "module": "esm/index.js",
@@ -48,7 +48,7 @@
   },
   "scripts": {
     "prepublishOnly": "node ../scripts/smoke-pack.js --files-only",
-    "postpublish": "node ../scripts/verify-published.js --named defineOneEntry --expect 1.0.176"
+    "postpublish": "node ../scripts/verify-published.js --named defineOneEntry --expect 1.0.177"
   },
   "sideEffects": false,
   "files": [