oneentry 1.0.176 → 1.0.178

package/dist/base/asyncModules.js

@@ -37,6 +37,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const syncModules_1 = __importDefault(require("./syncModules"));
+/**
+ * A refresh that does not answer within this time (ms) counts as failed.
+ */
+const REFRESH_TIMEOUT_MS = 30000;
 /**
  * Abstract class AsyncModules extends SyncModules to provide asynchronous HTTP request functionalities.
  * @description Abstract class AsyncModules extends SyncModules to provide asynchronous HTTP request functionalities.
@@ -49,6 +53,14 @@ class AsyncModules extends syncModules_1.default {
      */
     constructor(state) {
         super(state);
+        /**
+         * Set on the view `_asSignIn` returns: the request is a sign-in or sign-up.
+         */
+        this._signIn = false;
+        /**
+         * Set on the view `_asSubRequest` returns.
+         */
+        this._subRequest = false;
         this.state = state;
         this._url = this.state.url;
     }
@@ -59,7 +71,7 @@ class AsyncModules extends syncModules_1.default {
      * body — and a caught exception — instead of throwing, so a failed request
      * is indistinguishable from a successful one by control flow alone.
      * @param {unknown} value - Value returned by a request.
-     * @returns {boolean} True when the value is an API error (statusCode >= 400) or a thrown error object.
+     * @returns {boolean} True when the value is an API error (statusCode >= 400), the shell error of a request that got no answer (statusCode 0) or a thrown error object.
      * @description Recognizes both the OneEntry error body and errors caught by browserResponse (e.g. a network failure).
      */
     _isErrorResponse(value) {
@@ -70,7 +82,10 @@ class AsyncModules extends syncModules_1.default {
             typeof value === 'object' &&
             'statusCode' in value &&
             typeof value.statusCode === 'number' &&
-            value.statusCode >= 400);
+            // `0` is the shell error of a request that never got an answer (`_toShellError`):
+            // a dropped connection used to make `_fetchBoolean` report success
+            (value.statusCode >= 400 ||
+                (value.statusCode === 0 && 'pageData' in value)));
     }
     /**
      * Validates API response against a Zod schema (optional)
@@ -110,13 +125,82 @@ class AsyncModules extends syncModules_1.default {
                     validationErrors: result.error.issues,
                 };
             }
-            return result.data;
+            // Return the original data: the parsed copy lacks keys the schema does not describe
+            return data;
         }
         else {
             // Non-strict mode: log errors but return original data
             return validateResponseSafe(schema, data, this.state.validationLogErrors);
         }
     }
+    /**
+     * A view of this module for sign-in and sign-up requests.
+     * @returns {this} An object that shares the module's state but sends the request without the current session.
+     * @description A sign-in with a wrong password answers `401`, the status of an expired token:
+     * with a session open the SDK used to refresh that session and send the same wrong password
+     * again — two failed attempts for one, and a rotated refresh token. Such a request carries
+     * no `Authorization` header and never triggers a token refresh.
+     */
+    _asSignIn() {
+        const view = Object.create(this);
+        view._signIn = true;
+        return view;
+    }
+    /**
+     * A view of this module for requests the SDK makes on its own behalf.
+     * @returns {this} An object that shares the module's state but does not call `errors.customErrors`.
+     * @description The products of page blocks and the templates of pages are loaded by the SDK
+     * itself, and a failure there leaves an empty value. A `customErrors` handler (a Next.js
+     * `notFound()`) used to fire for them as if the page itself had failed.
+     */
+    _asSubRequest() {
+        const view = Object.create(this);
+        view._subRequest = true;
+        return view;
+    }
+    /**
+     * `_asSubRequest` for another module the SDK calls on its own behalf.
+     * @param {T} module - A module created by the SDK for a nested request.
+     * @returns {T} Its view that does not call `errors.customErrors`.
+     */
+    static _subRequestOf(module) {
+        return module._asSubRequest();
+    }
+    /**
+     * Reads the answer of a call that returns `true` on success.
+     * @param {T} result - What the request returned.
+     * @returns {T | true} `true` for an empty 2xx body (read as `{}`), the value otherwise.
+     */
+    _asBoolean(result) {
+        return result &&
+            typeof result === 'object' &&
+            !this._isErrorResponse(result) &&
+            Object.keys(result).length === 0
+            ? true
+            : result;
+    }
+    /**
+     * Whether a refresh may be attempted now.
+     * @returns {boolean} False while the device metadata is the one the platform rejected as malformed.
+     */
+    _canRefresh() {
+        return (!!this.state.refreshToken &&
+            this.state._rejectedMetadata !== this._getDeviceMetadata());
+    }
+    /**
+     * A view of this module whose requests go to another base URL.
+     * @param {string} url - The base URL for the view's requests.
+     * @returns {this} An object that shares the module's state and methods but has its own `_url`.
+     * @description For the few endpoints that live outside the module's base path. The base URL
+     * used to be swapped on the module itself for the duration of the call; two calls in flight
+     * at once (`Promise.all`) then sent one of them to the other base path, and the second
+     * `finally` restored the swapped URL — every later call of the instance went there too.
+     */
+    _withBaseUrl(url) {
+        const view = Object.create(this);
+        view._url = url;
+        return view;
+    }
     /**
      * Prepares a caller value (a marker) to be one segment of a request path.
      * @param {string} value - The value to put into the path.
@@ -131,6 +215,20 @@ class AsyncModules extends syncModules_1.default {
         const encoded = encodeURIComponent(value);
         return /^\.{1,2}$/.test(value) ? encoded.replace(/\./g, '%252E') : encoded;
     }
+    /**
+     * Prepares a caller path (a page URL) for a request path, keeping its `/`.
+     * @param {string} value - The path to put into the request path.
+     * @returns {string} Each `/`-separated part encoded by `_pathSegment`.
+     * @description A page URL may hold `/`, so it cannot be one segment; each part is
+     * encoded instead. `getProductsByPageUrl('../../all')` resolved to
+     * `POST /products/all` — the whole catalogue instead of one page.
+     */
+    _pathSegments(value) {
+        return String(value)
+            .split('/')
+            .map((part) => this._pathSegment(part))
+            .join('/');
+    }
     /**
      * Performs an HTTP GET request.
      * @param {string} path - The path to append to the base URL.
@@ -233,6 +331,7 @@ class AsyncModules extends syncModules_1.default {
      * @description Sends POST /users/refresh and, on success, stores the rotated access/refresh tokens and calls saveFunction.
      */
     async _performRefresh() {
+        var _a, _b;
         const url = this.state.url +
             `/api/content/users-auth-providers/marker/` +
             this.state.providerMarker +
@@ -245,20 +344,45 @@ class AsyncModules extends syncModules_1.default {
          * @param {object} options.headers - Set the necessary headers for the request
          * @param {object} options.body - Send the current refresh token in the request body as a JSON string
          */
-        const response = await fetch(url, {
-            method: 'POST',
-            headers: {
-                // Indicate that the request body is in JSON format
-                'Content-Type': 'application/json',
-                // Include the application token from the state
-                'x-app-token': this.state.token,
-                // Include the device fingerprint
-                'x-device-metadata': this._getDeviceMetadata(),
-                // x-guest-id is intentionally omitted: refresh is an auth-only call
-                // (a pure guest has no refresh token), so guest scoping does not apply.
-            },
-            body: JSON.stringify({ refreshToken: this.state.refreshToken }),
-        });
+        // `AbortSignal.timeout` is missing in older runtimes (Safari < 16, Node < 17.3)
+        let signal;
+        if (typeof AbortSignal !== 'undefined' &&
+            typeof AbortSignal.timeout === 'function') {
+            signal = AbortSignal.timeout(REFRESH_TIMEOUT_MS);
+        }
+        else if (typeof AbortController !== 'undefined') {
+            const controller = new AbortController();
+            // eslint-disable-next-line no-undef
+            const timer = setTimeout(() => controller.abort(), REFRESH_TIMEOUT_MS);
+            // Not cleared when the headers arrive: the body is read under the same signal.
+            // Must not keep a Node process alive for the timeout.
+            (_a = timer === null || timer === void 0 ? void 0 : timer.unref) === null || _a === void 0 ? void 0 : _a.call(timer);
+            signal = controller.signal;
+        }
+        let response;
+        try {
+            response = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    // Indicate that the request body is in JSON format
+                    'Content-Type': 'application/json',
+                    // Include the application token from the state
+                    'x-app-token': this.state.token,
+                    // Include the device fingerprint
+                    'x-device-metadata': this._getDeviceMetadata(),
+                    // x-guest-id is intentionally omitted: refresh is an auth-only call
+                    // (a pure guest has no refresh token), so guest scoping does not apply.
+                },
+                body: JSON.stringify({ refreshToken: this.state.refreshToken }),
+                // Every request of the client waits on this one refresh (`_refreshPromise`):
+                // a refresh that never answered froze the whole client
+                ...(signal ? { signal } : {}),
+            });
+        }
+        catch {
+            // No answer (network, timeout): the token may still be valid, keep it
+            return false;
+        }
         // Check if the response status is OK (status code 200-299)
         if (response.ok) {
             // Parsed through the shared helper rather than `response.json()`: a `200` whose body is
@@ -270,6 +394,7 @@ class AsyncModules extends syncModules_1.default {
                 return false;
             }
             // Update the state's refreshToken and accessToken with the new tokens from the response
+            this.state._rejectedMetadata = undefined;
             this.state.refreshToken = result.refreshToken;
             this.state.accessToken = result.accessToken;
             // If a save function is defined in the state, call it with the new refresh token
@@ -280,6 +405,21 @@ class AsyncModules extends syncModules_1.default {
             return true;
         }
         else {
+            // The platform rejected the token itself (`400 Provided token is incorrect`: expired,
+            // revoked, another device): drop it from this client, or every following request fired
+            // the same doomed refresh first. A 400 about the request (`Invalid x-device-metadata
+            // format`, `Missing x-device-metadata header`) says nothing about the token — keep it.
+            // `saveFunction` is not called: on another device the stored token is still valid.
+            if (response.status === 400) {
+                const body = await this._parseJson(response);
+                if (!/x-device-metadata/i.test(String((_b = body === null || body === void 0 ? void 0 : body.message) !== null && _b !== void 0 ? _b : ''))) {
+                    this.state.refreshToken = undefined;
+                }
+                else {
+                    // Kept, but not retried with the same metadata before every request
+                    this.state._rejectedMetadata = this._getDeviceMetadata();
+                }
+            }
             // Return false to indicate that the token refresh failed
             return false;
         }
@@ -317,7 +457,10 @@ class AsyncModules extends syncModules_1.default {
             };
         }
         // Check if 'data' is an instance of FormData or Blob
-        if (data instanceof FormData || data instanceof Blob) {
+        // Runtimes without FormData/Blob (older Node, some workers): `instanceof` on an
+        // undefined global threw on every request, a GET included
+        if ((typeof FormData !== 'undefined' && data instanceof FormData) ||
+            (typeof Blob !== 'undefined' && data instanceof Blob)) {
             // Remove the 'Content-Type' header from options.headers
             delete options.headers['Content-Type'];
             // Set the 'accept' header to 'application/json', while preserving existing headers
@@ -334,7 +477,7 @@ class AsyncModules extends syncModules_1.default {
             options.body = JSON.stringify(data);
         }
         // Check if there is an access token available in the state
-        if (this.state.accessToken) {
+        if (this.state.accessToken && !this._signIn) {
             // Add an 'Authorization' header with the Bearer token to options.headers
             options.headers['Authorization'] = 'Bearer ' + this.state.accessToken;
         }
@@ -381,10 +524,13 @@ class AsyncModules extends syncModules_1.default {
      * @description Define an asynchronous method 'browserResponse' that takes a path and options as parameters
      */
     async browserResponse(path, options) {
+        var _a;
         // Set when a proactive refresh ran and failed (dead/expired refresh token):
         // used below to skip the reactive refresh so we don't fire a second,
         // equally-doomed refresh on the 401 that the request is about to return.
         let proactiveRefreshFailed = false;
+        let status = 0;
+        let failure;
         try {
             // Proactive (eager) refresh: a session restored from storage has a refresh
             // token but no access token yet. Sending the first authenticated request
@@ -394,8 +540,9 @@ class AsyncModules extends syncModules_1.default {
             // Fires at most once per session (skipped once accessToken is set), and is
             // off for custom-auth callers who manage tokens themselves.
             if (!this.state.accessToken &&
-                this.state.refreshToken &&
-                !this.state.customAuth) {
+                this._canRefresh() &&
+                !this.state.customAuth &&
+                !this._signIn) {
                 const refreshed = await this.refreshToken();
                 if (refreshed) {
                     // Authenticated now — attach the bearer and drop the guest scoping
@@ -418,7 +565,11 @@ class AsyncModules extends syncModules_1.default {
             if (!response.ok &&
                 response.status === 401 &&
                 !this.state.customAuth &&
-                !proactiveRefreshFailed) {
+                !proactiveRefreshFailed &&
+                !this._signIn &&
+                // Without a refresh token there is nothing to refresh: the call went out
+                // as `{}` and every 401 of a guest or a wrong app token cost two requests
+                this._canRefresh()) {
                 const refresh = await this.refreshToken();
                 if (refresh) {
                     // Update the Authorization header with the new access token and retry.
@@ -443,19 +594,33 @@ class AsyncModules extends syncModules_1.default {
                 }
             }
             // Handle non-OK responses (applies to the first response and to a failed retry).
-            const status = response.status;
-            const res = await this._parseJson(response);
-            const statusKey = status;
-            if (this.state.errorsFunctions && this.state.errorsFunctions[statusKey]) {
-                this.state.errorsFunctions[statusKey](res);
-            }
-            // Determine whether to return or throw the response based on 'isShell' state
-            if (this.state.isShell) {
-                return res;
-            }
-            else {
-                throw res;
-            }
+            status = response.status;
+            const body = await this._parseJson(response);
+            // A failing answer whose body is not the platform's error (`{"error":…}`, `[]`,
+            // `null` from a gateway) used to be returned as data — `_fetchBoolean` read a 503 as `true`
+            const hasMessage = (value) => typeof (value === null || value === void 0 ? void 0 : value.message) === 'string' && value.message.trim() !== '';
+            failure =
+                body &&
+                    typeof body === 'object' &&
+                    typeof body.statusCode === 'number'
+                    ? // The platform's own error: keep it, with a message to show
+                        hasMessage(body)
+                            ? body
+                            : { ...body, message: `HTTP ${status}` }
+                    : {
+                        ...(body && typeof body === 'object' && !Array.isArray(body)
+                            ? body
+                            : {}),
+                        statusCode: status,
+                        // The text the server sent wins over the bare status
+                        message: typeof body === 'string' && body
+                            ? body
+                            : hasMessage(body)
+                                ? body.message
+                                : `HTTP ${status}`,
+                        pageData: null,
+                        timestamp: new Date().toISOString(),
+                    };
         }
         catch (e) {
             // Handle any errors that occur during the fetch process
@@ -463,10 +628,27 @@ class AsyncModules extends syncModules_1.default {
             if (this.state.isShell) {
                 return this._toShellError(e);
             }
-            else {
-                throw e;
+            // `@throws {IError}`: a dropped connection used to escape as a raw TypeError
+            const error = this._toShellError(e);
+            if (error !== e) {
+                error.cause = e;
             }
+            throw error;
+        }
+        // Called outside the try block: an exception from the handler (Next.js `redirect()`,
+        // `notFound()`) has to reach the caller, not turn into a `statusCode: 0` error
+        const statusKey = status;
+        const handler = this._subRequest
+            ? undefined
+            : (_a = this.state.errorsFunctions) === null || _a === void 0 ? void 0 : _a[statusKey];
+        if (handler) {
+            await handler(failure);
+        }
+        // Determine whether to return or throw the response based on 'isShell' state
+        if (this.state.isShell) {
+            return failure;
         }
+        throw failure;
     }
     /**
      * Describes a response whose body is not the JSON the API is supposed to send.

package/dist/base/stateModule.d.ts

@@ -11,10 +11,12 @@ export default class StateModule {
     token: string | undefined;
     guestId: string | undefined;
     deviceMetadata: string | undefined;
+    nodeDeviceId: string | undefined;
     accessToken: string | undefined;
     traficLimit: boolean;
     refreshToken: string | undefined;
     _refreshPromise: Promise<boolean> | null;
+    _rejectedMetadata: string | undefined;
     providerMarker: string;
     customAuth: boolean;
     isShell: boolean;

package/dist/base/stateModule.js

@@ -1,5 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const syncModules_1 = require("./syncModules");
 // HTTP status codes for which a custom error handler may be configured.
 const ERROR_STATUS_CODES = [
     400, 401, 403, 404, 429, 500, 502, 503, 504,
@@ -16,32 +18,40 @@ class StateModule {
      * @description Constructor for StateModule.
      */
     constructor(url, config) {
-        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t;
         // In-flight token refresh, shared across all module instances (they share this
         // state object). De-duplicates concurrent refreshes so the single-use refresh
         // token is not burned by parallel requests. Null when no refresh is running.
         this._refreshPromise = null;
         this.url = url;
-        this.lang = (_a = config.langCode) !== null && _a !== void 0 ? _a : 'en_US';
+        // `''` is not a language: it went out as `?langCode=` and every call answered 400
+        this.lang =
+            (typeof config.langCode === 'string' && config.langCode.trim()) ||
+                'en_US';
         this.token = config.token;
         // Normalize empty string to undefined: an explicit '' must not masquerade
         // as a set guest id (it would otherwise suppress id resolution).
+        (0, syncModules_1._warnGuestId)(config.guestId);
         this.guestId = config.guestId || undefined;
         // Same normalization as guestId: an explicit '' must not suppress the
         // environment-derived fingerprint.
         this.deviceMetadata = config.deviceMetadata || undefined;
         this.traficLimit = config.traficLimit || false;
-        this.validationEnabled = (_c = (_b = config.validation) === null || _b === void 0 ? void 0 : _b.enabled) !== null && _c !== void 0 ? _c : false;
-        this.validationStrictMode = (_e = (_d = config.validation) === null || _d === void 0 ? void 0 : _d.strictMode) !== null && _e !== void 0 ? _e : false;
-        this.validationLogErrors = (_g = (_f = config.validation) === null || _f === void 0 ? void 0 : _f.logErrors) !== null && _g !== void 0 ? _g : true;
-        this.rawData = (_h = config.rawData) !== null && _h !== void 0 ? _h : false;
-        this.refreshToken = (_k = (_j = config.auth) === null || _j === void 0 ? void 0 : _j.refreshToken) !== null && _k !== void 0 ? _k : undefined;
-        this.providerMarker = (_m = (_l = config.auth) === null || _l === void 0 ? void 0 : _l.providerMarker) !== null && _m !== void 0 ? _m : 'email';
-        this.customAuth = (_p = (_o = config.auth) === null || _o === void 0 ? void 0 : _o.customAuth) !== null && _p !== void 0 ? _p : false;
+        this.validationEnabled = (_b = (_a = config.validation) === null || _a === void 0 ? void 0 : _a.enabled) !== null && _b !== void 0 ? _b : false;
+        this.validationStrictMode = (_d = (_c = config.validation) === null || _c === void 0 ? void 0 : _c.strictMode) !== null && _d !== void 0 ? _d : false;
+        this.validationLogErrors = (_f = (_e = config.validation) === null || _e === void 0 ? void 0 : _e.logErrors) !== null && _f !== void 0 ? _f : true;
+        if (this.validationStrictMode && !this.validationEnabled) {
+            // eslint-disable-next-line no-undef, no-console
+            console.warn('OneEntry SDK: validation.strictMode has no effect without validation.enabled: true');
+        }
+        this.rawData = (_g = config.rawData) !== null && _g !== void 0 ? _g : false;
+        this.refreshToken = (_j = (_h = config.auth) === null || _h === void 0 ? void 0 : _h.refreshToken) !== null && _j !== void 0 ? _j : undefined;
+        this.providerMarker = (_l = (_k = config.auth) === null || _k === void 0 ? void 0 : _k.providerMarker) !== null && _l !== void 0 ? _l : 'email';
+        this.customAuth = (_o = (_m = config.auth) === null || _m === void 0 ? void 0 : _m.customAuth) !== null && _o !== void 0 ? _o : false;
         this.errorsFunctions = {};
-        this.saveFunction = (_r = (_q = config.auth) === null || _q === void 0 ? void 0 : _q.saveFunction) !== null && _r !== void 0 ? _r : null;
-        this.isShell = (_t = (_s = config.errors) === null || _s === void 0 ? void 0 : _s.isShell) !== null && _t !== void 0 ? _t : true;
-        const customErrors = (_u = config.errors) === null || _u === void 0 ? void 0 : _u.customErrors;
+        this.saveFunction = (_q = (_p = config.auth) === null || _p === void 0 ? void 0 : _p.saveFunction) !== null && _q !== void 0 ? _q : null;
+        this.isShell = (_s = (_r = config.errors) === null || _r === void 0 ? void 0 : _r.isShell) !== null && _s !== void 0 ? _s : true;
+        const customErrors = (_t = config.errors) === null || _t === void 0 ? void 0 : _t.customErrors;
         if (customErrors) {
             for (const code of ERROR_STATUS_CODES) {
                 if (customErrors[code]) {

package/dist/base/syncModules.d.ts

@@ -1,6 +1,11 @@
 import type { IUploadingQuery } from '../file-uploading/fileUploadingInterfaces';
 import type { IProductsQuery } from '../products/productsInterfaces';
 import type StateModule from './stateModule';
+/**
+ * Warns about a caller's guest id the platform will not keep.
+ * @param {string | undefined} guestId - The id passed in config or to `setGuestId`.
+ */
+export declare function _warnGuestId(guestId: string | undefined): void;
 /**
  * Abstract class representing synchronization modules.
  */
@@ -8,7 +13,6 @@ export default abstract class SyncModules {
     /** Protected properties for state and URL */
     protected state: StateModule;
     protected _url: string;
-    private readonly _nodeDeviceId;
     /**
      * Constructor to initialize state and URL.
      * @param {StateModule} state - StateModule instance.
@@ -109,7 +113,11 @@ export default abstract class SyncModules {
      * numeric branch already produced.
      * 3. **Numbers** (`integer`, `float`, `real`) — cast to a JS number; anything
      * that is not a number (including an empty value) becomes `null`.
+     * 4. **Empty strings** of non-text types (`image`, `groupOfImages`, `file`,
+     * `timeInterval`, `date`, `dateTime`, `time`) — the API sends an unset value as
+     * `""`; it is replaced with `null`. For text types `""` is a real value and stays.
      * @param {any} attr - The attribute object to normalize in place.
+     * @param {boolean} [isEntityValue] - The attribute is a value of an entity (`attributeValues`): one without a `value` key is unset and gets `null`. Form fields and attribute-set schemas describe a field and get no key.
      */
     private _normalizeAttrValue;
     /**
@@ -172,15 +180,15 @@ export default abstract class SyncModules {
     /**
      * Sets the access token in the state.
      * @param {string} accessToken - The access token to set.
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
-    setAccessToken(accessToken: string): any;
+    setAccessToken(accessToken: string): this;
     /**
      * Sets the refresh token in the state.
      * @param {string} refreshToken - The refresh token to set.
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
-    setRefreshToken(refreshToken: string): any;
+    setRefreshToken(refreshToken: string): this;
     /**
      * Sets the guest identifier in the state.
      *
@@ -189,9 +197,9 @@ export default abstract class SyncModules {
      * (the SDK then falls back to the localStorage-backed id in the browser, or to
      * no guest id at all on the server).
      * @param {string} guestId - The guest identifier to set (empty string clears it).
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
-    setGuestId(guestId: string): any;
+    setGuestId(guestId: string): this;
     /**
      * Sets the device-metadata override in the state.
      *
@@ -202,9 +210,9 @@ export default abstract class SyncModules {
      * browser's string (obtained there via `getDeviceMetadata`). Pass an empty
      * string to clear the override and fall back to the computed fingerprint.
      * @param {string} deviceMetadata - The metadata string to send (empty string clears the override).
-     * @returns {any} The instance of SyncModules for chaining.
+     * @returns {this} The same module, for chaining.
      */
-    setDeviceMetadata(deviceMetadata: string): any;
+    setDeviceMetadata(deviceMetadata: string): this;
     /**
      * Returns the device-metadata string the SDK sends as the `x-device-metadata` header.
      *
@@ -238,7 +246,7 @@ export default abstract class SyncModules {
      *
      * **instanceId strategy:**
      * - Browser: `_getPersistentBrowserId('oneentry_device_id')` — read from localStorage, stable across sessions.
-     * - Node.js / no localStorage: `_nodeDeviceId` — generated at instance creation,
+     * - Node.js / no localStorage: `state.nodeDeviceId` — generated once per client (shared by its modules),
      * lives until the process restarts.
      *
      * In a Node.js environment (no `window`) returns a simplified object without screen/navigator.