oneentry 1.0.159 → 1.0.161

package/esm/base/syncModules.d.ts

@@ -0,0 +1,245 @@
+import type { IUploadingQuery } from '../file-uploading/fileUploadingInterfaces.js';
+import type { IProductsQuery } from '../products/productsInterfaces.js';
+import type StateModule from './stateModule.js';
+/**
+ * Abstract class representing synchronization modules.
+ */
+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.
+     */
+    protected constructor(state: StateModule);
+    /**
+     * Resolves the guest identifier for the current request, or `undefined`.
+     *
+     * Resolution order:
+     * 1. An explicitly configured `state.guestId` (from config or `setGuestId`) — wins.
+     * 2. A persistent browser ID stored in localStorage (key `oneentry_guest_id`),
+     * stable across sessions and tabs — mirrors the device-metadata strategy.
+     * Once resolved it is cached into `state.guestId` (safe: one browser = one user).
+     * 3. Otherwise `undefined` — the `x-guest-id` header is simply omitted.
+     *
+     * IMPORTANT (server-side): the SDK never invents a guest id on the server.
+     * `defineOneEntry` is typically created once and shared across many visitors,
+     * so a silently-generated server id would be cached into the shared state and
+     * leak one guest cart/wishlist across all anonymous visitors. On the server
+     * you must pass a per-visitor `guestId` (config or `setGuestId`) yourself.
+     * @returns {string | undefined} The guest identifier, or undefined when none is available.
+     */
+    protected _getGuestId(): string | undefined;
+    /**
+     * Constructs the full URL path by appending the given path to the base URL.
+     * @param {string} path - The path to append to the base URL.
+     * @returns {string} The full URL as a string.
+     */
+    protected _getFullPath(path: string): string;
+    /**
+     * Converts query parameters into a query string.
+     *
+     * Values are percent-encoded so free-text and special characters (spaces,
+     * `&`, `=`, non-ASCII) cannot corrupt the query string. Keys are known,
+     * machine-safe field names and are left as-is.
+     * @param {IProductsQuery | IUploadingQuery | any} query - The query object containing key-value pairs.
+     * @returns {string} A string representation of the query parameters.
+     */
+    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.
+     */
+    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.
+     */
+    protected _normalizePostBody(body: any, langCode?: string): any;
+    /**
+     * Normalizes the value of a single attribute in place.
+     *
+     * Applies the three type-driven fixes the API response needs, so that an
+     * attribute of a given type always reaches the consumer in the same shape,
+     * no matter which collection it arrived in:
+     *
+     * 1. **Single-file values** (`image`, `file`) — the API always sends an array,
+     * even for one file: `[img]` → `img`. Multi-file values and `groupOfImages`
+     * (a collection by definition) stay an array.
+     * 2. **Empty values** — an attribute with no value comes back as an empty
+     * localization map `{}`; it is replaced with `null`, the same marker the
+     * 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`.
+     * @param {any} attr - The attribute object to normalize in place.
+     */
+    private _normalizeAttrValue;
+    /**
+     * Sorts attributes by their positions.
+     *
+     * Each attribute has a `position` field, and the API returns them in no
+     * particular order. The method rebuilds the collection sorted by ascending
+     * `position`, so the display order matches the order defined in the CMS.
+     * Both container shapes the API uses are handled: an object keyed by marker
+     * (`attributeValues`) and an array (form `attributes`).
+     * @param {any} data - The attributes collection to sort.
+     * @returns {any} Sorted attributes, in the same container shape.
+     */
+    protected _sortAttributes: (data: any) => any;
+    /**
+     * Transforms additionalFields from array to object keyed by marker.
+     *
+     * 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:
+     *
+     * All three go through the same steps, so an attribute of a given type looks
+     * the same whichever collection it arrived in:
+     * - `_normalizeAdditionalFields` turns nested fields into a marker map;
+     * - `_normalizeAttrValue` unwraps single-file values, empties to `null` and
+     * casts numbers;
+     * - the collection is re-sorted by `position`.
+     *
+     * **1. `attributeValues`** — attributes of pages, products and other entities,
+     * an object `{ marker: AttrObject }`.
+     *
+     * **2. `attributes`** — form attributes, an array (or a marker map on some
+     * endpoints); form-only boolean flags (`isLogin`, `isSignUp`, notifications)
+     * are additionally coerced from `null` to `false`. A form with no attributes
+     * arrives as an empty object `{}` — it is normalized to an empty array.
+     *
+     * **3. `type`** — a standalone attribute: an attribute-set entry, a form-data
+     * field or a nested `additionalFields` entry. Same transformations, but there
+     * is no collection to sort.
+     *
+     * `timeInterval` attributes are left exactly as the API returned them — a
+     * compact recurrence rule. Resolving one into concrete slots is the caller's
+     * job, via `expandTimeIntervals`: the rule is open-ended, so only the caller
+     * knows how wide a window it needs.
+     *
+     * 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;
+    /**
+     * Sets the access token in the state.
+     * @param {string} accessToken - The access token to set.
+     * @returns {any} The instance of SyncModules for chaining.
+     */
+    setAccessToken(accessToken: string): any;
+    /**
+     * Sets the refresh token in the state.
+     * @param {string} refreshToken - The refresh token to set.
+     * @returns {any} The instance of SyncModules for chaining.
+     */
+    setRefreshToken(refreshToken: string): any;
+    /**
+     * Sets the guest identifier in the state.
+     *
+     * Once set, it is sent as the `x-guest-id` header on unauthenticated requests,
+     * enabling guest cart/wishlist/activity flows. Pass an empty string to clear it
+     * (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.
+     */
+    setGuestId(guestId: string): any;
+    /**
+     * Sets the device-metadata override in the state.
+     *
+     * Once set, the string is sent as the `x-device-metadata` header on POST
+     * requests and token refresh instead of the environment-derived fingerprint.
+     * The API binds refresh tokens to this header, so server-side flows that issue
+     * tokens on behalf of a browser (e.g. an OAuth code exchange) must set the
+     * 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.
+     */
+    setDeviceMetadata(deviceMetadata: string): any;
+    /**
+     * Returns the device-metadata string the SDK sends as the `x-device-metadata` header.
+     *
+     * Public counterpart of `_getDeviceMetadata`: an explicit override (config or
+     * `setDeviceMetadata`) wins, otherwise the environment-derived fingerprint is
+     * computed. Use it in the browser to obtain the string that a server-side
+     * token-issuing flow (OAuth code exchange) must forward, so the issued refresh
+     * token stays refreshable from this browser.
+     * @returns {string} The metadata string sent with requests from this instance.
+     */
+    getDeviceMetadata(): string;
+    /**
+     * 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: `_getPersistentBrowserId('oneentry_device_id')` — 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.
+     *
+     * An explicitly provided string (`deviceMetadata` in config or `setDeviceMetadata`)
+     * takes precedence over the environment-derived fingerprint — this lets a server
+     * issue tokens bound to the browser's fingerprint (see `IConfig.deviceMetadata`).
+     * @returns {string} - Returns an object containing device metadata.
+     */
+    protected _getDeviceMetadata(): string;
+}