oneentry 1.0.159 → 1.0.161

package/esm/base/syncModules.js

@@ -0,0 +1,555 @@
+// localStorage keys for the persistent browser-side identifiers.
+const _DEVICE_ID_STORAGE_KEY = 'oneentry_device_id';
+const _GUEST_ID_STORAGE_KEY = 'oneentry_guest_id';
+// Module-level cache of persistent IDs keyed by storage key — survives class
+// re-instantiation, but resets on page reload if localStorage is unavailable.
+const _persistentIds = {};
+/**
+ * Generates a new opaque identifier.
+ *
+ * Prefers a cryptographically secure source (Web Crypto, exposed as
+ * `globalThis.crypto` in browsers and Node.js >= 18): `randomUUID()` when
+ * available, otherwise random bytes rendered as a base-36 string. Falls back to
+ * a timestamp + `Math.random()` only when no CSPRNG exists (e.g. very old Node).
+ *
+ * The result contains no special characters, so it is safe to use both in
+ * localStorage and in HTTP headers.
+ * @returns {string} A freshly generated identifier.
+ */
+function _generateId() {
+    const cryptoObj = typeof globalThis !== 'undefined' ? globalThis.crypto : undefined;
+    if (cryptoObj === null || cryptoObj === void 0 ? void 0 : cryptoObj.randomUUID) {
+        return cryptoObj.randomUUID();
+    }
+    if (cryptoObj === null || cryptoObj === void 0 ? void 0 : cryptoObj.getRandomValues) {
+        const bytes = cryptoObj.getRandomValues(new Uint8Array(18));
+        let result = '';
+        for (let i = 0; i < bytes.length; i++) {
+            result += bytes[i].toString(36).padStart(2, '0');
+        }
+        return result;
+    }
+    // Last-resort fallback for environments without Web Crypto.
+    // Non-cryptographic, but adequate when nothing better is available.
+    return (Date.now().toString(36) +
+        Math.random().toString(36).substring(2, 15) +
+        Math.random().toString(36).substring(2, 15));
+}
+/**
+ * Returns a stable identifier for the browser environment, persisted in localStorage.
+ *
+ * Algorithm (per `storageKey`):
+ * 1. If the module-level cache is already populated — return it (fastest path).
+ * 2. Otherwise try reading the ID from localStorage under `storageKey`.
+ * This ensures the same browser gets the same ID across sessions and tabs.
+ * 3. If localStorage has nothing — generate a new ID, persist it to localStorage
+ * and cache it in the module variable.
+ * 4. If localStorage is unavailable (SSR, private mode, iframe sandbox) —
+ * return null; the caller falls back to a per-instance Node id.
+ * @param {string} storageKey - localStorage key under which the ID is stored.
+ * @returns {string | null} The identifier or null if localStorage is unavailable.
+ */
+function _getPersistentBrowserId(storageKey) {
+    const win = typeof globalThis !== 'undefined' ? globalThis.window : undefined;
+    if (!(win === null || win === void 0 ? void 0 : win.localStorage))
+        return null;
+    if (_persistentIds[storageKey])
+        return _persistentIds[storageKey];
+    try {
+        const stored = win.localStorage.getItem(storageKey);
+        if (stored) {
+            _persistentIds[storageKey] = stored;
+            return _persistentIds[storageKey];
+        }
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    }
+    catch (_e) {
+        // ignore
+    }
+    const id = _generateId();
+    _persistentIds[storageKey] = id;
+    try {
+        win.localStorage.setItem(storageKey, id);
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    }
+    catch (_e) {
+        // ignore
+    }
+    return _persistentIds[storageKey];
+}
+/**
+ * Abstract class representing synchronization modules.
+ */
+export default class SyncModules {
+    /**
+     * Constructor to initialize state and URL.
+     * @param {StateModule} state - StateModule instance.
+     */
+    constructor(state) {
+        /**
+         * 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.
+         */
+        this._sortAttributes = (data) => Array.isArray(data)
+            ? [...data].sort((a, b) => a.position - b.position)
+            : Object.fromEntries(Object.entries(data).sort(([, a], [, b]) => a.position - b.position));
+        this.state = state;
+        this._url = state.url;
+        this._nodeDeviceId = _generateId();
+    }
+    /**
+     * 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.
+     */
+    _getGuestId() {
+        if (this.state.guestId)
+            return this.state.guestId;
+        // Browser only: a localStorage-backed id is safe to cache into shared state,
+        // because a single browser maps to a single guest.
+        const browserId = _getPersistentBrowserId(_GUEST_ID_STORAGE_KEY);
+        if (browserId) {
+            this.state.guestId = browserId;
+            return browserId;
+        }
+        // No localStorage and no explicit id (e.g. Node/SSR) — do not invent one.
+        return 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.
+     */
+    _getFullPath(path) {
+        return this._url + path;
+    }
+    /**
+     * 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.
+     */
+    _queryParamsToString(query) {
+        // Skip null/undefined to avoid sending empty parameters.
+        // 0, false and '' are kept — they are semantically meaningful.
+        return Object.keys(query)
+            .filter((key) => query[key] !== null && query[key] !== undefined)
+            .map((key) => `${key}=${encodeURIComponent(query[key])}`)
+            .join('&');
+    }
+    /**
+     * 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.
+     */
+    _normalizeData(data, langCode = this.state.lang) {
+        if (Array.isArray(data)) {
+            return this._normalizeAttr(data.map((item) => this._normalizeData(item, langCode)));
+        }
+        else if (typeof data === 'object' && data) {
+            const normalizeData = {};
+            Object.keys(data).forEach((key) => {
+                if (Array.isArray(data[key])) {
+                    normalizeData[key] = this._normalizeData(data[key], langCode);
+                }
+                else if (!data[key] || typeof data[key] !== 'object') {
+                    normalizeData[key] = data[key];
+                }
+                else if (langCode in data[key]) {
+                    // Field contains a translation map — pick the requested locale.
+                    normalizeData[key] = data[key][langCode];
+                }
+                else {
+                    normalizeData[key] = this._normalizeData(data[key], langCode);
+                }
+            });
+            return this._normalizeAttr(normalizeData);
+        }
+        else {
+            return data;
+        }
+    }
+    /**
+     * 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.
+     */
+    _normalizePostBody(body, langCode = this.state.lang) {
+        // API does not accept phoneSMS = '' — delete the field if empty.
+        if (body.notificationData && body.notificationData.phoneSMS === '') {
+            delete body.notificationData.phoneSMS;
+        }
+        // If formData is not provided — no further normalization needed.
+        if (!body.formData)
+            return body;
+        // Wrap form fields in an object keyed by locale:
+        // [{ marker, value }]  →  { "en_US": [{ marker, value }] }
+        const formData = {};
+        formData[langCode] = Array.isArray(body.formData)
+            ? body.formData
+            : [body.formData];
+        body.formData = formData;
+        return body;
+    }
+    /**
+     * 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.
+     */
+    _normalizeAttrValue(attr) {
+        if ((attr.type === 'image' || attr.type === 'file') &&
+            Array.isArray(attr.value) &&
+            attr.value.length === 1) {
+            attr.value = attr.value[0];
+        }
+        // An attribute with no value arrives as an empty localization map.
+        if (attr.value &&
+            typeof attr.value === 'object' &&
+            !Array.isArray(attr.value) &&
+            Object.keys(attr.value).length === 0) {
+            attr.value = null;
+        }
+        if (attr.type === 'integer' ||
+            attr.type === 'float' ||
+            attr.type === 'real') {
+            // Number(null) is 0 and Number('') is 0 — an empty value must stay empty.
+            const isEmpty = attr.value === null || attr.value === undefined || attr.value === '';
+            const numValue = isEmpty ? NaN : Number(attr.value);
+            attr.value = isNaN(numValue) ? null : numValue;
+        }
+    }
+    /**
+     * 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.
+     */
+    _normalizeAdditionalFields(attr) {
+        if (!this.state.rawData && Array.isArray(attr.additionalFields)) {
+            attr.additionalFields = Object.fromEntries(attr.additionalFields.map((field) => [field.marker, field]));
+        }
+    }
+    /**
+     * 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.
+     */
+    _normalizeAttr(data) {
+        // For regular attributes collections - pages, products, etc.
+        if ('attributeValues' in data) {
+            Object.keys(data.attributeValues).forEach((attr) => {
+                const d = data.attributeValues[attr];
+                this._normalizeAdditionalFields(d);
+                this._normalizeAttrValue(d);
+            });
+            return {
+                ...data,
+                attributeValues: this._sortAttributes(data.attributeValues),
+            };
+        }
+        const booleanFields = [
+            'isLogin',
+            'isSignUp',
+            'isNotificationEmail',
+            'isNotificationPhonePush',
+            'isNotificationPhoneSMS',
+        ];
+        // for forms attributes - forms attributes collections
+        if ('attributes' in data) {
+            const d = data.attributes;
+            // A form with no attributes arrives as an empty object `{}` — normalize
+            // it to an empty array, the container every non-empty form uses.
+            if (d &&
+                typeof d === 'object' &&
+                !Array.isArray(d) &&
+                Object.keys(d).length === 0) {
+                return { ...data, attributes: [] };
+            }
+            Object.keys(d).forEach((attr) => {
+                this._normalizeAdditionalFields(d[attr]);
+                this._normalizeAttrValue(d[attr]);
+                for (const field of booleanFields) {
+                    if (field in d[attr] && d[attr][field] === null) {
+                        d[attr][field] = false;
+                    }
+                }
+            });
+            return { ...data, attributes: this._sortAttributes(d) };
+        }
+        //  For single attribute - for attribute sets
+        if ('type' in data) {
+            this._normalizeAdditionalFields(data);
+            this._normalizeAttrValue(data);
+            for (const field of booleanFields) {
+                if (field in data && data[field] === null) {
+                    data[field] = false;
+                }
+            }
+        }
+        return data;
+    }
+    /**
+     * 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) {
+        this.state.accessToken = accessToken;
+        return this;
+    }
+    /**
+     * 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) {
+        this.state.refreshToken = refreshToken;
+        return this;
+    }
+    /**
+     * 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) {
+        this.state.guestId = guestId || undefined;
+        return this;
+    }
+    /**
+     * 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) {
+        this.state.deviceMetadata = deviceMetadata || undefined;
+        return this;
+    }
+    /**
+     * 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() {
+        return this._getDeviceMetadata();
+    }
+    /**
+     * 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.
+     */
+    _getDeviceMetadata() {
+        var _a;
+        // Explicit override wins: the API binds refresh tokens to this header, so
+        // server-side token issuance must be able to stamp the browser's string.
+        if (this.state.deviceMetadata)
+            return this.state.deviceMetadata;
+        // Check if we're in a browser environment
+        if (typeof globalThis === 'undefined') {
+            return '';
+        }
+        // Access navigator through globalThis.window object to avoid direct reference
+        const win = globalThis.window;
+        const instanceId = (_a = _getPersistentBrowserId(_DEVICE_ID_STORAGE_KEY)) !== null && _a !== void 0 ? _a : this._nodeDeviceId;
+        // Node.js environment
+        if (!win) {
+            return JSON.stringify({
+                fingerprint: `UQ_${instanceId}`,
+                deviceInfo: {
+                    os: 'Node.js',
+                    browser: `Node.js/${instanceId.substring(0, 10)}`,
+                    location: 'en-US',
+                },
+            });
+        }
+        const nav = win.navigator || {};
+        const platform = nav.platform || 'Win32';
+        const userAgent = nav.userAgent || 'Node.js/22';
+        const language = nav.language || 'en-US';
+        // Get screen information if available
+        const screen = win.screen || {};
+        const screenWidth = screen.width || 0;
+        const screenHeight = screen.height || 0;
+        const colorDepth = screen.colorDepth || 0;
+        // Get timezone
+        let timezone = 'UTC';
+        try {
+            timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        }
+        catch (e) {
+            // Ignore error, fallback to UTC
+        }
+        // Detect private browsing mode
+        let isPrivateBrowsing = false;
+        try {
+            // Simple localStorage test to detect private browsing
+            if (win.localStorage) {
+                const testKey = 'test_private_browsing';
+                win.localStorage.setItem(testKey, '1');
+                win.localStorage.removeItem(testKey);
+            }
+            else {
+                isPrivateBrowsing = true; // If localStorage is not available, likely private browsing
+            }
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        }
+        catch (e) {
+            isPrivateBrowsing = true; // Error during localStorage access indicates private browsing
+        }
+        // Create a stable fingerprint string using stable device/browser characteristics
+        const fingerprintString = `${platform}|${userAgent}|${language}|${screenWidth}|${screenHeight}|${colorDepth}|${timezone}|${isPrivateBrowsing ? 'private' : 'normal'}|${instanceId}`;
+        // Simple but stable hash function
+        let hash = 0;
+        for (let i = 0; i < fingerprintString.length; i++) {
+            const char = fingerprintString.charCodeAt(i);
+            hash = (hash << 5) - hash + char;
+            hash = hash & hash; // Convert to 32-bit integer
+        }
+        const deviceMetadata = {
+            fingerprint: `UQ_${Math.abs(hash).toString(36)}_${instanceId.substring(0, 12)}`,
+            deviceInfo: {
+                os: platform.replace(/ /g, '_'),
+                browser: userAgent.replace(/ /g, '_'),
+                location: language,
+            },
+        };
+        return JSON.stringify(deviceMetadata);
+    }
+}

package/esm/base/timeIntervals.d.ts

@@ -0,0 +1,95 @@
+import type { IAttributeValue, ITimeIntervalAttributeValue, ITimeIntervalEntitySchedule, ITimeIntervalSchedule, ITimeIntervalWindow, TimeIntervalPair } from './utils.js';
+/**
+ * Expands a `timeInterval` schedule into concrete UTC slots for a given window.
+ *
+ * A schedule as returned by the API is a compact **recurrence rule** — an
+ * anchor date plus daily time ranges plus repeat flags — not a list of slots.
+ * Materializing it wholesale is what makes `timeInterval` attributes expensive
+ * (a year of half-hour slots runs to megabytes), so expansion is on demand and
+ * the window is required: only the caller knows how far it needs to resolve.
+ *
+ * Both schedule shapes the API returns are accepted:
+ * - **entity** — `attributeValues[marker].value[].values[]` on pages, products,
+ * blocks and attribute sets: a `dates` range with `times` pairs;
+ * - **form** — `attributes[marker].localizeInfos.intervals[]`: a `range` with
+ * `intervals` that carry a slot `period` in minutes.
+ *
+ * Semantics:
+ * - `dates[0]` / `range[0]` is both the recurrence phase and the first valid
+ * day — nothing earlier is emitted, however wide the window;
+ * - `dates[1]` / `range[1]` ends validity; when it does not extend past the
+ * start, the schedule is anchored to that day — with a recurrence flag set,
+ * recurrence is then open-ended and the window alone bounds the result;
+ * - `inEveryWeek` repeats every 7 days from the anchor; `inEveryMonth` repeats
+ * on the same day-of-month, skipping months that are too short; with both set
+ * the weekly rule applies, which is what it has always meant in practice;
+ * - with neither flag the schedule is a plain date range — every day of it;
+ * - the result is deduplicated and sorted by start, then end.
+ * @param {ITimeIntervalEntitySchedule | ITimeIntervalSchedule} schedule - A single schedule entry from a `timeInterval` attribute.
+ * @param {ITimeIntervalWindow} window - Inclusive `{ from, to }` range to resolve, compared at UTC day granularity.
+ * @returns {TimeIntervalPair[]} Sorted, deduplicated `[start, end]` ISO pairs; empty when the schedule is malformed or does not overlap the window.
+ * To expand a whole attribute at once, prefer {@link expandAttributeTimeIntervals}
+ * — it walks the groups and merges the results for you. Reach for this function
+ * directly when you already hold a single schedule, e.g. a form's
+ * `localizeInfos.intervals[]`.
+ * @example
+ * ```ts
+ * import { expandTimeIntervals } from 'oneentry';
+ *
+ * // Form attributes are an array keyed by `marker`, and carry their schedules
+ * // already typed on `localizeInfos.intervals`.
+ * const field = form.attributes.find((a) => a.marker === 'booking');
+ *
+ * const slots = (field?.localizeInfos.intervals ?? []).flatMap((schedule) =>
+ *     expandTimeIntervals(schedule, { from: '2025-05-01', to: '2025-05-31' }),
+ * );
+ * // [['2025-05-07T09:00:00.000Z', '2025-05-07T10:00:00.000Z'], …]
+ * ```
+ */
+export declare function expandTimeIntervals(schedule: ITimeIntervalEntitySchedule | ITimeIntervalSchedule, window: ITimeIntervalWindow): TimeIntervalPair[];
+/**
+ * Narrows an attribute value to a `timeInterval` attribute.
+ *
+ * `IAttributeValue.value` is `unknown` — its shape depends on `type` — so this
+ * guard is what lets you reach the schedules without a cast.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is a `timeInterval` carrying an array of groups.
+ * @example
+ * ```ts
+ * const attr = page.attributeValues.interval;
+ * if (isTimeIntervalAttribute(attr)) {
+ *     attr.value[0].values[0].dates; // fully typed, no cast
+ * }
+ * ```
+ */
+export declare function isTimeIntervalAttribute(attr: IAttributeValue | undefined): attr is ITimeIntervalAttributeValue;
+/**
+ * Expands a whole `timeInterval` attribute into concrete UTC slots for a window.
+ *
+ * The one-call path for the common case: it walks the attribute's groups and
+ * their schedules, expands each with {@link expandTimeIntervals}, and merges the
+ * results. Merging matters — deduplication and ordering only hold within a
+ * single schedule, so combining groups by hand can yield duplicate or unsorted
+ * slots.
+ *
+ * Anything that is not a `timeInterval` attribute yields an empty array, so this
+ * is safe to call on an arbitrary attribute without checking `type` first.
+ *
+ * For **form** attributes the schedules are already typed at
+ * `localizeInfos.intervals`, so no equivalent helper is needed — map over them
+ * and call {@link expandTimeIntervals} directly.
+ * @param {IAttributeValue | undefined} attr - A `timeInterval` attribute value, e.g. `page.attributeValues.interval`.
+ * @param {ITimeIntervalWindow} window - Inclusive `{ from, to }` range to resolve, compared at UTC day granularity.
+ * @returns {TimeIntervalPair[]} Sorted, deduplicated `[start, end]` ISO pairs across every group; empty when the attribute is not a `timeInterval`.
+ * @example
+ * ```ts
+ * import { expandAttributeTimeIntervals } from 'oneentry';
+ *
+ * const slots = expandAttributeTimeIntervals(page.attributeValues.interval, {
+ *     from: '2025-04-01',
+ *     to: '2025-04-30',
+ * });
+ * // [['2025-04-14T09:00:00.000Z', '2025-04-14T10:00:00.000Z'], …]
+ * ```
+ */
+export declare function expandAttributeTimeIntervals(attr: IAttributeValue | undefined, window: ITimeIntervalWindow): TimeIntervalPair[];