oneentry 1.0.141 → 1.0.143

package/configure.js

@@ -4,11 +4,13 @@
  * OneEntry SDK Configuration Tool
  *
  * Interactive CLI tool for initial SDK setup. Prompts the user for:
+ * - Project type (Node.js or Next.js)
  * - Project URL (must include https://)
  * - Authentication token
  *
- * Generates an example.ts file with a TypeScript interface template
- * containing the provided configuration values.
+ * Node.js: Generates an example.mjs file with a ready-to-use SDK setup.
+ * Next.js: Initializes a new Next.js project via create-next-app and adds
+ *          oneentry configuration in lib/oneentry.ts and .env.local.
  *
  * Usage:
  *   npx oneentry
@@ -22,6 +24,7 @@
 /* eslint-disable @typescript-eslint/no-require-imports */
 
 const fs = require('fs');
+const path = require('path');
 const readline = require('readline');
 const { spawn } = require('child_process');
 
@@ -30,26 +33,41 @@ const rl = readline.createInterface({
   output: process.stdout,
 });
 
-rl.question('Enter project name with https://... : ', (url) => {
-  rl.question('Enter token: ', (token) => {
-    rl.question('Run example after creating? (y/n): ', (answer) => {
-      rl.close();
-      createInterface(url, token, answer.trim().toLowerCase() === 'y');
+console.log('\nOneEntry SDK setup\n');
+console.log('1) Node.js');
+console.log('2) Next.js\n');
+
+rl.question('Choose project type (1/2): ', (type) => {
+  const isNext = type.trim() === '2';
+
+  if (isNext) {
+    rl.question('Enter Next.js project name: ', (projectName) => {
+      rl.question('Enter project URL with https://... : ', (url) => {
+        rl.question('Enter token: ', (token) => {
+          rl.close();
+          initNextProject(projectName.trim(), url.trim(), token.trim());
+        });
+      });
     });
-  });
+  } else {
+    rl.question('Enter project URL with https://... : ', (url) => {
+      rl.question('Enter token: ', (token) => {
+        rl.question('Run example after creating? (y/n): ', (answer) => {
+          rl.close();
+          createNodeExample(url.trim(), token.trim(), answer.trim().toLowerCase() === 'y');
+        });
+      });
+    });
+  }
 });
 
 /**
  * Creates an example JavaScript file with SDK initialization and sample requests
- *
- * Generates an example.mjs file with a ready-to-use defineOneEntry call
- * that fetches admins, pages and products and prints them to the console.
- * Run with: node example.mjs
- * @param {string} url - Project URL with https:// (e.g., "https://example.oneentry.cloud")
- * @param {string} token - Authentication token for API access
+ * @param {string} url - Project URL with https://
+ * @param {string} token - Authentication token
  * @param {boolean} run - Whether to run the generated file immediately
  */
-function createInterface(url, token, run) {
+function createNodeExample(url, token, run) {
   const filePath = 'example.mjs';
   const tokenLine = token ? `\n  token: '${token}',` : '';
   fs.writeFile(
@@ -88,3 +106,77 @@ console.log('Products:', JSON.stringify(products, null, 2));
     },
   );
 }
+
+/**
+ * Initializes a Next.js project and adds OneEntry SDK configuration
+ * @param {string} projectName - Directory name for the new Next.js project
+ * @param {string} url - Project URL with https://
+ * @param {string} token - Authentication token
+ */
+function initNextProject(projectName, url, token) {
+  console.log(`\nRunning create-next-app for "${projectName}"...\n`);
+
+  const child = spawn(
+    'npx',
+    ['create-next-app@latest', projectName, '--ts', '--app', '--eslint', '--no-tailwind', '--src-dir', '--import-alias', '@/*'],
+    { stdio: 'inherit', shell: true },
+  );
+
+  child.on('error', (e) => {
+    console.error('Failed to run create-next-app:', e.message);
+  });
+
+  child.on('close', (code) => {
+    if (code !== 0) {
+      console.error(`create-next-app exited with code ${code}`);
+      return;
+    }
+    addOneEntryConfig(projectName, url, token);
+  });
+}
+
+/**
+ * Writes oneentry config files into the newly created Next.js project
+ * @param {string} projectName - Project directory name
+ * @param {string} url - Project URL with https://
+ * @param {string} token - Authentication token
+ */
+function addOneEntryConfig(projectName, url, token) {
+  const libDir = path.join(projectName, 'src', 'lib');
+  fs.mkdirSync(libDir, { recursive: true });
+
+  const tokenLine = token ? `\n  token: process.env.ONEENTRY_TOKEN,` : '';
+  const libContent = `import { defineOneEntry } from 'oneentry';
+
+const { Admins, Pages, Products } = defineOneEntry(
+  process.env.NEXT_PUBLIC_ONEENTRY_URL ?? '',
+  {${tokenLine}
+    langCode: 'en_US',
+  },
+);
+
+export { Admins, Pages, Products };
+`;
+
+  const envContent = `NEXT_PUBLIC_ONEENTRY_URL=${url}\n${token ? `ONEENTRY_TOKEN=${token}\n` : ''}`;
+
+  fs.writeFile(path.join(libDir, 'oneentry.ts'), libContent, (err) => {
+    if (err) {
+      console.error('Failed to create lib/oneentry.ts:', err.message);
+      return;
+    }
+    console.log(`Created ${projectName}/src/lib/oneentry.ts`);
+  });
+
+  fs.writeFile(path.join(projectName, '.env.local'), envContent, (err) => {
+    if (err) {
+      console.error('Failed to create .env.local:', err.message);
+      return;
+    }
+    console.log(`Created ${projectName}/.env.local`);
+    console.log(`\nNext steps:`);
+    console.log(`  cd ${projectName}`);
+    console.log(`  npm install oneentry`);
+    console.log(`  npm run dev`);
+  });
+}

package/dist/admins/adminsInterfaces.d.ts

@@ -1,7 +1,6 @@
 import type { AttributeType, IAttributeValues, IError } from '../base/utils';
 /**
  * @interface IAdmins
- * @property {Function} getAdminsInfo - Method to retrieve all admin user objects.
  * @description This interface defines the contract for any class that implements it
  */
 interface IAdmins {
@@ -81,7 +80,7 @@ interface IAdminEntity {
     position: number | null;
     isSync: boolean;
     attributeValues: IAttributeValues;
-    [key: string]: any;
+    [key: string]: unknown;
 }
 /**
  * Interface representing a query for fetching admin data.

package/dist/attribute-sets/attributeSetsInterfaces.d.ts

@@ -2,8 +2,6 @@ import type { IError, ILocalizeInfo } from '../base/utils';
 /**
  * Interface for retrieving attributes based on markers and language codes.
  * @interface IAttributesSets
- * @property {Function} getAttributesByMarker - Get all attributes with data from the attribute sets.
- * @property {Function} getSingleAttributeByMarkerSet - Get a single attribute with data from the attribute sets.
  * @description This interface defines methods for retrieving attributes based on markers and language codes.
  */
 interface IAttributesSets {
@@ -54,16 +52,16 @@ interface IListTitle {
  * @type {AttributeType}
  * @description This type defines the possible values for attribute types used in the system.
  */
-type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' | 'float' | 'dateTime' | 'date' | 'time' | 'file' | 'image' | 'groupOfImages' | 'radioButton' | 'list' | 'button';
+type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' | 'float' | 'dateTime' | 'date' | 'time' | 'file' | 'image' | 'groupOfImages' | 'radioButton' | 'list' | 'button' | 'entity' | 'timeInterval';
 /**
  * Represents an attribute set entity.
  * @interface IAttributesSetsEntity
  * @property {AttributeType} type - Attribute type. Example: "string", "text", "integer", "etc".
- * @property {any} [value] - Value of the attribute, which can be of any type.
- * @property {any} initialValue - Initial value of the attribute.
+ * @property {unknown} [value] - Value of the attribute, which can be of any type.
+ * @property {unknown} initialValue - Initial value of the attribute.
  * @property {string} marker - Textual identifier of the attribute (marker). Example: "color", "size", "etc".
  * @property {number} position - Position number for sorting. Example: 1.
- * @property {IListTitle[] | Record<string, any>} [listTitles] - Array of values (with extended data) for list and radioButton attributes.
+ * @property {IListTitle[] | Record<string, unknown>} [listTitles] - Array of values (with extended data) for list and radioButton attributes.
  * @example
     [
       {
@@ -81,7 +79,7 @@ type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' |
         "extendedValueType": null
       }
     ]
- * @property {Record<string, any>} [validators] - Set of validators for validation.
+ * @property {Record<string, unknown>} [validators] - Set of validators for validation.
  * @example
     {
       "requiredValidator": {
@@ -96,19 +94,19 @@ type AttributeType = 'string' | 'text' | 'textWithHeader' | 'integer' | 'real' |
    {
      "title": "My attribute"
    }
- * @property {Record<string, any>} [additionalFields] - Additional fields for the attribute (optional).
+ * @property {Record<string, unknown>} [additionalFields] - Additional fields for the attribute (optional).
  * @description This interface defines the structure of an attribute set entity, including its type, marker, position, validators, localization information, list titles, additional fields, and settings.
  */
 interface IAttributesSetsEntity {
     type: AttributeType;
-    value?: any;
-    initialValue: any;
+    value?: unknown;
+    initialValue: unknown;
     marker: string;
     position: number;
-    listTitles?: IListTitle[] | Record<string, any>;
-    validators?: Record<string, any>;
+    listTitles?: IListTitle[] | Record<string, unknown>;
+    validators?: Record<string, unknown>;
     localizeInfos: ILocalizeInfo;
-    additionalFields?: Record<string, any>;
+    additionalFields?: Record<string, unknown>;
 }
 /**
  * Represents an attribute set entity.

package/dist/auth-provider/authProviderApi.d.ts

@@ -14,7 +14,7 @@ export default class AuthProviderApi extends AsyncModules implements IAuthProvid
     protected state: StateModule;
     protected _url: string;
     /**
-     *
+     * constructor
      */
     constructor(state: StateModule);
     /**

package/dist/auth-provider/authProviderApi.js

@@ -16,7 +16,7 @@ const authProviderSchemas_1 = require("./authProviderSchemas");
  */
 class AuthProviderApi extends asyncModules_1.default {
     /**
-     *
+     * constructor
      */
     constructor(state) {
         super(state);
@@ -187,11 +187,12 @@ class AuthProviderApi extends asyncModules_1.default {
         const result = await this._fetchPost(`/marker/${marker}/users/auth`, body);
         // Validate response if validation is enabled
         const validated = this._validateResponse(result, authProviderSchemas_1.AuthResponseSchema);
-        this.state.accessToken = validated.accessToken;
-        this.state.refreshToken = validated.refreshToken;
-        // console.log(validated);
-        if (this.state.saveFunction && validated.refreshToken) {
-            this.state.saveFunction(validated.refreshToken);
+        if (!('statusCode' in validated)) {
+            this.state.accessToken = validated.accessToken;
+            this.state.refreshToken = validated.refreshToken;
+            if (this.state.saveFunction && validated.refreshToken) {
+                this.state.saveFunction(validated.refreshToken);
+            }
         }
         return validated;
     }
@@ -207,10 +208,12 @@ class AuthProviderApi extends asyncModules_1.default {
     async refresh(marker, token) {
         const data = { refreshToken: token };
         const result = await this._fetchPost(`/marker/${marker}/users/refresh`, data);
-        this.state.accessToken = result.accessToken;
-        this.state.refreshToken = result.refreshToken;
-        if (this.state.saveFunction) {
-            this.state.saveFunction(result.refreshToken);
+        if (!('statusCode' in result)) {
+            this.state.accessToken = result.accessToken;
+            this.state.refreshToken = result.refreshToken;
+            if (this.state.saveFunction) {
+                this.state.saveFunction(result.refreshToken);
+            }
         }
         return result;
     }

package/dist/auth-provider/authProvidersInterfaces.d.ts

@@ -1,19 +1,6 @@
 import type { IError, ILocalizeInfo } from '../base/utils';
 /**
  * @interface IAuthProvider
- * @property {Function} signUp - User registration.
- * @property {Function} generateCode - Getting a user activation code.
- * @property {Function} checkCode - User activation code verification.
- * @property {Function} activateUser - User activate.
- * @property {Function} auth - User authorization.
- * @property {Function} refresh - Refresh token.
- * @property {Function} logout - User logout.
- * @property {Function} logoutAll - User logout.
- * @property {Function} changePassword - Change password.
- * @property {Function} getAuthProviders - Get all auth providers objects.
- * @property {Function} getAuthProviderByMarker - Get one auth provider object by marker.
- * @property {Function} getActiveSessionsByMarker - Get one auth provider object by marker.
- * @property {Function} oauth - User registration (authorization) via OAUTH.
  * @description This interface defines methods for user authentication and registration through various auth providers.
  */
 interface IAuthProvider {
@@ -167,11 +154,11 @@ interface IAuthProvider {
      * Retrieves active user sessions data object.
      * @handleName getActiveSessionsByMarker
      * @param {string} marker - The marker identifying the auth provider. Example: "email".
-     * @returns {any} A promise that resolves to active user sessions data object.
+     * @returns {Promise<IActiveSession[] | IError>} A promise that resolves to active user sessions data object.
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      * @description This method retrieves active user sessions data object.
      */
-    getActiveSessionsByMarker(marker: string): Promise<any | IError>;
+    getActiveSessionsByMarker(marker: string): Promise<IActiveSession[] | IError>;
     /**
      * User registration (authorization) via OAUTH.
      * @handleName oauthSignUp
@@ -226,7 +213,7 @@ interface ISignUpData {
     notificationData: {
         email: string;
         phonePush: Array<string>;
-        phoneSMS: string;
+        phoneSMS?: string;
     };
 }
 /**
@@ -289,7 +276,7 @@ interface ISignUpEntity {
     notificationData: {
         email: string;
         phonePush: Array<string>;
-        phoneSMS: string;
+        phoneSMS?: string;
     };
     locale?: string;
 }

package/dist/base/asyncModules.js

@@ -38,6 +38,14 @@ class AsyncModules extends syncModules_1.default {
         if (!this.state.validationEnabled || !schema) {
             return data;
         }
+        // Skip validation for error responses (statusCode indicates API error)
+        if (data !== null &&
+            typeof data === 'object' &&
+            'statusCode' in data &&
+            typeof data.statusCode === 'number' &&
+            data.statusCode >= 400) {
+            return data;
+        }
         // Use strict or safe validation based on config
         if (this.state.validationStrictMode) {
             const result = (0, validation_1.validateResponse)(schema, data, {

package/dist/base/stateModule.js

@@ -93,7 +93,7 @@ class StateModule {
             }
         }
         else {
-            this.isShell = false;
+            this.isShell = true;
         }
         try {
             if (typeof process === 'object' &&

package/dist/base/syncModules.d.ts

@@ -28,6 +28,20 @@ export default abstract class SyncModules {
     protected _queryParamsToString(query: IProductsQuery | IUploadingQuery | any): string;
     /**
      * Normalizes data based on language code.
+     *
+     * Recursively traverses the API response and unwraps localized fields.
+     * The API stores translations as objects like
+     * `{ "en_US": "Hello", "ru_RU": "Hello" }`. The method replaces such an object
+     * with the value for the requested `langCode` when that key is present.
+     *
+     * Traversal order:
+     * 1. Array → recursively normalize each element, then `_normalizeAttr`.
+     * 2. Object → for each key:
+     * - value is an array: recurse;
+     * - value is a non-object (primitive) or falsy: copy as-is;
+     * - object has key `langCode`: take only the needed translation;
+     * - otherwise: recurse deeper.
+     * 3. Primitive → return as-is.
      * @param {any} data - The data to normalize.
      * @param {string} langCode - The language code for normalization.
      * @returns {any} Normalized data.
@@ -35,6 +49,17 @@ export default abstract class SyncModules {
     protected _normalizeData(data: any, langCode?: string): any;
     /**
      * Normalizes the body of a POST request.
+     *
+     * Performs two transformations before sending to the API:
+     *
+     * 1. **phoneSMS cleanup**: the API rejects an empty string as a field value,
+     * so if `notificationData.phoneSMS === ''` the key is deleted entirely.
+     * A missing key is treated by the API as "not provided"; an empty string is not.
+     *
+     * 2. **formData localization**: the API expects formData as
+     * `{ "<langCode>": [...fields] }`, but callers pass a flat array or a single object.
+     * The method wraps the data into the required structure.
+     * If `formData` is absent from the body — return the body as-is (only phoneSMS cleanup applied).
      * @param {any} body - The body to normalize.
      * @param {string} [langCode] - The language code for normalization.
      * @returns {any} Normalized body.
@@ -42,12 +67,24 @@ export default abstract class SyncModules {
     protected _normalizePostBody(body: any, langCode?: string): any;
     /**
      * Clears arrays within the data structure.
+     *
+     * Traverses the data and fixes a specific edge case with image attributes:
+     * when an `image` attribute has a single-element array in `value`,
+     * the API returns an array but consumers expect a plain object.
+     * In that case `value` is unwrapped: `[img]` → `img`.
+     *
+     * For all other keys the method recursively copies the structure unchanged.
      * @param {Record<string, any>} data - The data to clear.
      * @returns {any} Cleared data.
      */
     protected _clearArray(data: Record<string, any>): any;
     /**
      * Sorts attributes by their positions.
+     *
+     * The API returns attributes as an object `{ marker: AttrObject }`.
+     * Each attribute has a `position` field. The method rebuilds the object
+     * with keys sorted by ascending `position` so that the display order
+     * matches the order defined in the CMS.
      * @param {any} data - The data containing attributes.
      * @returns {any} Sorted attributes.
      */
@@ -61,11 +98,26 @@ export default abstract class SyncModules {
     protected _addDays(date: Date, days: number): any;
     /**
      * Common logic for processing schedule dates (weekly, monthly, or both).
+     *
+     * Abstracts date iteration for three scheduling modes:
+     *
+     * - **`inEveryWeek` only**: starting from the start date, generates dates
+     * with a 7-day step until the end of the current month.
+     *
+     * - **`inEveryMonth` only**: pins the day-of-month from the start date
+     * and repeats it for each of the next 12 months. If the month does not
+     * have that day (e.g. Feb 31), the iteration is skipped.
+     *
+     * - **`inEveryWeek` + `inEveryMonth`**: for each of the next 12 months finds
+     * the first occurrence of the target weekday (from the start date), then
+     * iterates all occurrences of that weekday in the month with a 7-day step.
+     *
+     * `processDate(currentDate)` is called for every resolved date.
      * @param {Date} date - The date for which to process intervals.
      * @param {object} config - Configuration for schedule repetition.
      * @param {boolean} config.inEveryWeek - Whether to repeat weekly.
      * @param {boolean} config.inEveryMonth - Whether to repeat monthly.
-     * @param {Function} processDate - Callback function to process each date.
+     * @param {(currentDate: Date) => void} processDate - Callback function to process each date.
      */
     protected _processScheduleDates(date: Date, config: {
         inEveryWeek: boolean;
@@ -73,6 +125,12 @@ export default abstract class SyncModules {
     }, processDate: (currentDate: Date) => void): void;
     /**
      * Generates intervals for a specific date based on a schedule.
+     *
+     * For each date resolved by `_processScheduleDates`, iterates over
+     * the `schedule.times` array of time ranges. Each range is a pair
+     * `[startTime, endTime]` with `{ hours, minutes }` fields.
+     * Creates an ISO interval `[start.toISOString(), end.toISOString()]`
+     * and adds it to `utcIntervals` (Set deduplicates automatically).
      * @param {Date} date - The date for which to generate intervals.
      * @param {object} schedule - The schedule defining the intervals.
      * @param {boolean} schedule.inEveryWeek  - The number of weeks between intervals.
@@ -87,12 +145,32 @@ export default abstract class SyncModules {
     }, utcIntervals: Set<Array<string>>): void;
     /**
      * Adds time intervals to schedules.
+     *
+     * Accepts an array of schedule groups (structure of `timeInterval` attributes
+     * for pages/products). For each group iterates over `values` — the set of
+     * concrete schedules. Each schedule contains a date range `dates[0..1]`.
+     *
+     * If both boundaries are equal (`isSameDay`), intervals are generated only
+     * for that single date. Otherwise — for every day in the range inclusive.
+     *
+     * The result (`schedule.timeIntervals`) is a sorted array of ISO pairs,
+     * ready to pass to UI components.
      * @param {any[]} schedules - The schedules to process.
      * @returns {any} Schedules with added time intervals.
      */
     _addTimeIntervalsToSchedules(schedules: any[]): any;
     /**
      * Generates intervals for a specific date for form schedules.
+     *
+     * Unlike `_generateIntervalsForDate`, time ranges here have a different shape:
+     * each `timeInterval` contains `start`, `end` and `period`
+     * (slot length in minutes). The method slices the [start, end) window into
+     * fixed-length slots of `period` minutes:
+     *
+     * start=09:00, end=12:00, period=30 → [09:00–09:30], [09:30–10:00], …, [11:30–12:00]
+     *
+     * Generation stops if the next slot would exceed `end`.
+     * Each slot is added to `utcIntervals` (Set deduplicates automatically).
      * @param {Date} date - The date for which to generate intervals.
      * @param {object} interval - The interval configuration.
      * @param {boolean} interval.inEveryWeek - Indicates whether the schedule is weekly.
@@ -106,24 +184,59 @@ export default abstract class SyncModules {
     }, timeIntervals: any[], utcIntervals: Set<Array<string>>): void;
     /**
      * Adds time intervals to form schedules (different structure).
+     *
+     * Same as `_addTimeIntervalsToSchedules` but for `timeInterval` attributes
+     * in **forms** (different API data structure):
+     * - `interval.range[0..1]` instead of `schedule.dates[0..1]`
+     * - `interval.intervals` — array of time ranges with slots (`period`)
+     * instead of `[startTime, endTime]` pairs
+     *
+     * Result is written to `interval.timeIntervals`.
      * @param {any[]} intervals - The intervals to process.
      * @returns {any} Intervals with added time intervals.
      */
     _addTimeIntervalsToFormSchedules(intervals: any[]): any;
     /**
      * Transforms additionalFields from array to object keyed by marker.
-     * Skipped when rawData is enabled in config.
+     *
+     * The API returns `additionalFields` as an array: `[{ marker, ... }, ...]`.
+     * For convenient key-based access (`attr.additionalFields['fieldName']`)
+     * the method converts it to an object `{ marker: { marker, ... } }`.
+     * Transformation is skipped when `rawData` mode is enabled in config
+     * (the consumer wants the data as-is, without transformations).
      * @param {any} attr - The attribute object that may contain additionalFields.
      */
     private _normalizeAdditionalFields;
     /**
      * Normalizes attributes within the data.
+     *
+     * Handles three different attribute formats returned by the API:
+     *
+     * **1. `attributeValues`** — attributes of pages, products and other entities.
+     * Contains an object `{ marker: AttrObject }`. For each attribute:
+     * - `_normalizeAdditionalFields` is called;
+     * - numeric types (`integer`, `float`) are cast to a JS number (or `null`);
+     * - `timeInterval` attributes are enriched with computed `timeIntervals`;
+     * - the whole object is re-sorted by `position`.
+     *
+     * **2. `attributes`** — form attributes (different API structure).
+     * Same `additionalFields` and `timeInterval` processing,
+     * but numbers are not normalized here (commented out — logic differs).
+     *
+     * **3. `type`** — a single attribute from an attribute set.
+     * Same transformations as in case 1, but without sorting.
+     *
+     * If none of the keys are found — data is returned unchanged.
      * @param {any} data - The data to normalize.
      * @returns {any} Normalized attributes.
      */
     protected _normalizeAttr(data: any): any;
     /**
      * Processes data after fetching or receiving it.
+     *
+     * Final post-processing of the API response: first unwraps localized fields
+     * (`_normalizeData`), then fixes single-element image attributes
+     * (`_clearArray`). Called at the end of every fetch method.
      * @param {any} data - The data to process.
      * @param {any} [langCode] - The language code for processing.
      * @returns {any} Processed data.
@@ -143,6 +256,30 @@ export default abstract class SyncModules {
     setRefreshToken(refreshToken: string): any;
     /**
      * Get deviceMetadata
+     *
+     * Builds a device metadata object to be sent in request headers.
+     * Used for analytics and anti-fraud on the API side.
+     *
+     * Returned JSON structure:
+     * ```json
+     * {
+     *   "fingerprint": "UQ_<hash>_<instanceId>",
+     *   "deviceInfo": { "os": "...", "browser": "...", "location": "en-US" }
+     * }
+     * ```
+     *
+     * **Fingerprint algorithm:**
+     * 1. Builds a string from stable characteristics: platform, userAgent, language,
+     * screen resolution, colorDepth, timezone, private-browsing mode, instanceId.
+     * 2. Runs it through a simple 32-bit hash (djb2-like).
+     * 3. Concatenates the hash and the first 12 characters of instanceId.
+     *
+     * **instanceId strategy:**
+     * - Browser: `_getBrowserDeviceId()` — read from localStorage, stable across sessions.
+     * - Node.js / no localStorage: `_nodeDeviceId` — generated at instance creation,
+     * lives until the process restarts.
+     *
+     * In a Node.js environment (no `window`) returns a simplified object without screen/navigator.
      * @returns {string} - Returns an object containing device metadata.
      */
     protected _getDeviceMetadata(): string;