oneentry 1.0.154 → 1.0.156

package/README.md

@@ -90,6 +90,8 @@ The second parameter of the constructor takes the 'config'. It contains the foll
 
 - 'guestId' - Optional guest identifier sent as the "x-guest-id" header on unauthenticated requests. It enables guest cart / wishlist / activity flows. In the browser, if you omit it, the SDK generates a stable id and persists it in localStorage. On the server you must pass a per-visitor "guestId" (or call "setGuestId"): the SDK never auto-generates a server id, to avoid sharing one guest across visitors. The header is omitted once a user is authenticated.
 
+- 'deviceMetadata' - Optional device-metadata string sent as the "x-device-metadata" header instead of the fingerprint the SDK computes from the current environment. The API binds refresh tokens to this header, so a server that issues tokens on behalf of a browser (for example, an OAuth code exchange keeping the client secret server-side) must pass the browser's string here — otherwise the issued refresh token is bound to the server's fingerprint and cannot be refreshed from the browser. Obtain the string in the browser via "getDeviceMetadata()" and set/clear it at runtime via "setDeviceMetadata".
+
 - 'traficLimit' - Some methods use more than one request to the CMS so that the data you receive is complete and easy to work with. Pass the value "true" for this parameter to save traffic and decide for yourself what data you need. The default value "false".
 
 - 'auth' - An object with authorization settings. By default, the SDK is configured to work with tokens inside the user's session and does not require any additional work from you. At the same time, the SDK does not store the session state between sessions. If you are satisfied with such settings, do not pass the variable 'auth' at all.
@@ -179,6 +181,25 @@ const api = defineOneEntry('your-url', {
 
 OneEntry SDK supports optional validation of API responses using Zod. This feature is disabled by default and can be enabled for development or critical operations.
 
+### Time Intervals
+
+Attributes of type `timeInterval` return a compact recurrence rule (an anchor date, daily time ranges and repeat flags), not a ready list of slots. The SDK does not expand it eagerly — a single attribute can materialize into megabytes of slots — so resolve it on demand with `expandAttributeTimeIntervals`, passing the window you actually render:
+
+```js
+import { defineOneEntry, expandAttributeTimeIntervals } from 'oneentry'
+
+const { Pages } = defineOneEntry('your-url', { token: 'your-app-token' })
+const page = await Pages.getPageByUrl('booking')
+
+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'], …]
+```
+
+Also exported: `expandTimeIntervals(schedule, window)` for a single schedule (e.g. a form's `localizeInfos.intervals`), and the `isTimeIntervalAttribute` type guard.
+
 ### Errors
 
 If you want to escape errors inside the sc, leave the "errors" property by default.

package/changelog.md

@@ -1,5 +1,90 @@
 # SDK Change Log
 
+## v.1.0.156
+
+### What's New
+
+- `expandAttributeTimeIntervals(attr, { from, to })` — new top-level export that resolves a whole `timeInterval` attribute into concrete `[start, end]` ISO pairs for a window you choose. This is the one-call replacement for the removed `timeIntervals` field: it walks the attribute's groups and schedules and merges the results (merging matters — deduplication and ordering only hold within a single schedule). Anything that is not a `timeInterval` attribute yields an empty array, so it is safe to call without checking `type` first.
+
+  ```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'], …]
+  ```
+
+- `expandTimeIntervals(schedule, { from, to })` — new top-level export that resolves a single schedule. Accepts both shapes the API returns: entity schedules (`attributeValues[marker].value[].values[]` on pages, products, blocks and attribute sets) and form schedules (`attributes[].localizeInfos.intervals[]`). Use it when you already hold one schedule — most notably on forms, whose schedules are already typed:
+
+  ```ts
+  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' }),
+  );
+  ```
+
+  Both functions are pure — they do not mutate their input and perform no requests.
+
+- `isTimeIntervalAttribute(attr)` — new exported type guard narrowing an `IAttributeValue` to `ITimeIntervalAttributeValue`. `IAttributeValue.value` is `unknown` because its shape depends on `type`; this guard is what lets you reach the schedules without a cast:
+
+  ```ts
+  const attr = page.attributeValues.interval;
+  if (isTimeIntervalAttribute(attr)) {
+    attr.value[0].values[0].dates; // fully typed
+  }
+  ```
+
+- `ITimeIntervalAttributeValue`, `ITimeIntervalGroup`, `ITimeIntervalEntitySchedule`, `ITimeIntervalWindow` and `TimeIntervalPair` — new exported types covering the whole `timeInterval` payload: the attribute, its groups, an entity schedule, the expansion window and a resolved slot. `ITimeIntervalSchedule` and `IAttributeValue` are now exported for the same reason. The payload previously had no typed representation at all.
+
+### What's Changed
+
+- `ITimeIntervalSchedule` — `range` is typed `string[]` instead of `unknown[]` (it is a pair of ISO dates), and the optional `inEveryWeek` flag is documented; the SDK always read it, but the interface omitted it.
+
+### Bug Fixes
+
+These affect `expandTimeIntervals`, which replaces the removed built-in expansion:
+
+- The expansion horizon is no longer hardcoded. Monthly recurrence stopped exactly 12 months after the anchor and weekly recurrence stopped at the end of the anchor's month, so slots beyond that could not be obtained at all. The window is now the horizon.
+- A schedule with no recurrence flags (`inEveryWeek: false, inEveryMonth: false`) produced no intervals at all — `_processScheduleDates` had no branch for that case. A plain date range now yields slots for every day in it.
+- Weekly recurrence combined with monthly no longer emits dates **before** the schedule's start date. The old branch walked from the 1st of the anchor's month, so a schedule starting Monday 2025-04-14 also emitted 2025-04-07.
+- Weekly recurrence was host-timezone dependent: it computed its end-of-month bound with `getFullYear`/`getMonth` (local time) while every other date operation used UTC, so the result shifted with the machine's timezone. All arithmetic is now UTC.
+- Weekly+monthly recurrence silently dropped months: it advanced the month before pinning the day to the 1st, so an anchor on the 31st overflowed short months and lost 5 of 12 months.
+- Identical intervals are now actually deduplicated. The old code collected into a `Set` of array references, which compares by identity, so duplicates always survived despite the intent.
+- A range with a non-positive `period` no longer hangs. The slot loop never advanced its cursor and spun forever; such ranges are now skipped.
+- Malformed input no longer throws. `_addTimeIntervalsToFormSchedules` dereferenced its argument unguarded (`TypeError` on `undefined`), and both expanders read `dates[0]` / `range[0]` without checking the array existed. `expandTimeIntervals` returns an empty array instead.
+
+### What's Deleted
+
+- **Breaking** — the computed `timeIntervals` field is no longer added to `timeInterval` attribute values. It was injected into every response carrying a `timeInterval` attribute (pages, products, blocks, attribute sets and forms) and materialized a full year of slots regardless of what the caller needed: a single attribute with hourly slots expanded to roughly 2,000 lines of JSON, and finer slot periods reached megabytes — enough to blow past framework data-cache limits. The field was never declared in any interface or Zod schema, so TypeScript consumers could only reach it through a cast.
+
+  Migrate by calling `expandAttributeTimeIntervals(attr, window)` with the window you actually render. The source data it expands (`dates`/`range`, `times`/`intervals`, `inEveryWeek`, `inEveryMonth`) is unchanged and still on every schedule, so nothing is lost — it is now resolved on demand instead of eagerly, and the compact rule is what gets cached.
+
+- `_addTimeIntervalsToSchedules` and `_addTimeIntervalsToFormSchedules` — removed from every module. Despite the `_` prefix these were public and callable (e.g. `Pages._addTimeIntervalsToSchedules`). Use `expandTimeIntervals`.
+
+## v.1.0.155
+
+### What's New
+
+- Config > `deviceMetadata` — new optional config parameter that overrides the `x-device-metadata` header (sent on POST requests and token refresh) instead of the fingerprint computed from the current environment. The API binds refresh tokens to this header, so a server issuing tokens on behalf of a browser (e.g. an OAuth code exchange that keeps the client secret server-side) can now stamp the browser's fingerprint and the issued refresh token stays refreshable from that browser. Previously this required bypassing the SDK with a raw `fetch`.
+- `setDeviceMetadata(deviceMetadata)` — new public method on every module: sets the `x-device-metadata` override at runtime (empty string clears it and falls back to the computed fingerprint).
+- `getDeviceMetadata()` — new public method on every module: returns the `x-device-metadata` string the SDK sends (the override when set, otherwise the environment-derived fingerprint). Use it in the browser to obtain the value that a server-side token-issuing flow must forward; previously this required reaching into the protected `_getDeviceMetadata`.
+
+### Bug Fixes
+
+- `Blocks.getBlocks` — error responses no longer crash block enrichment. On an API error (e.g. `403` without list permission, or `422`) the normalized value is an `IError` without an `items` array; the method previously called `.items.map(...)` unconditionally and threw a `TypeError`. Enrichment now runs only when `items` is an array, and the error response is returned as-is.
+
+- `Pages.getRootPages`, `getPages`, `getChildPagesByParentUrl`, `searchPage` — error responses no longer crash template enrichment. The shared `addTemplateToPages` helper called `.filter(...)` / `.map(...)` on its input; on an API error (e.g. `403` / `422`) that input is an `IError` object, not an array, which threw a `TypeError`. The helper now returns the error response as-is when the input is not an array.
+
+- `Blocks.getProductsByBlockMarker` (used internally by block enrichment) — on an API error the method read `result.items` (which is `undefined` for an `IError`) and returned `undefined` instead of the error. It now returns the normalized error response when there is no `items` array.
+
+### What's Deleted
+
+- AttributesSets > `IAttributeSetsEntity.typeId` and `IAttributeSetsEntity.properties` — removed: the API no longer returns these fields for `getAttributes` / `getAttributeSetByMarker`. The attribute set type is available via the `type` object (`type.id`, `type.type`). The Zod schema (`AttributeSetEntitySchema`) is updated accordingly. The `typeId` **query parameter** of `getAttributes` is unaffected.
+- TemplatePreviews > `ITemplatesPreviewEntity.attributeValues` — removed: the API no longer returns this field for `getTemplatePreviews` / `getTemplatePreviewByMarker` (it was always an empty object). The Zod schema (`TemplatePreviewEntitySchema`) is updated accordingly.
+
 ## v.1.0.154
 
 ### What's New
@@ -226,7 +311,7 @@
 
 - Discounts > `getAllDiscounts` — removed `'PERSONAL_BONUS'` from type filter parameter.
 
-- Forms > `IFormsEntity` — type narrowed to `'order' | 'sing_in_up' | 'collection' | 'data' | 'rating'`, removed `moduleFormConfigs` field.
+- Forms > `IFormsEntity` — type narrowed to `'order' | 'sign_in_up' | 'collection' | 'data' | 'rating'`, removed `moduleFormConfigs` field.
 
 - Products > `getProductsEmptyPage` — changed from GET to POST, added `body` parameter, return type changed to `IAggregatedProductGroup[]`.
 

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

@@ -206,7 +206,6 @@ interface IAttributeValidators {
  * @property {string} updatedDate - The date when the attribute set was last updated. Example: "2023-10-01T12:00:00Z".
  * @property {number} version - The version number of the attribute set, used for tracking changes or updates. Example: 1.
  * @property {string} identifier - A string that uniquely identifies the attribute set. Example: "attributeSet1".
- * @property {number} typeId - The numerical identifier representing the type of the attribute set. Example: 1.
  * @property {string} title - The title or name of the attribute set. Example: "Product Attributes".
  * @property {Record<string, IAttributeSchemaItem>} schema - Schema fields keyed by marker.
  * @example
@@ -223,12 +222,6 @@ interface IAttributeValidators {
      }
    }
  * @property {boolean} isVisible - Indicates whether the attribute set is visible or not. Example: true.
- * @property {Record<string, unknown>} properties - Additional properties associated with the attribute set; empty object when none.
- * @example
-   {
-     "color": "red",
-     "size": "M"
-   }
  * @property {string} type - The type of the attribute set, which could be a specific classification or category. Example: "product", "user", "etc".
  * @property {number} position - The position number for sorting the attribute set. Example: 1.
  * @description This interface defines the structure of an attribute set entity.
@@ -239,11 +232,9 @@ interface IAttributeSetsEntity {
     updatedDate: string;
     version: number;
     identifier: string;
-    typeId: number;
     title: string;
     schema: Record<string, IAttributeSchemaItem>;
     isVisible: boolean;
-    properties: Record<string, unknown>;
     type: IAttributeSetTypeRef;
     position: number;
 }

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

@@ -38,11 +38,9 @@ export declare const AttributeSetEntitySchema: z.ZodObject<{
     updatedDate: z.ZodString;
     version: z.ZodNumber;
     identifier: z.ZodString;
-    typeId: z.ZodNumber;
     title: z.ZodString;
     schema: z.ZodObject<{}, z.core.$loose>;
     isVisible: z.ZodBoolean;
-    properties: z.ZodObject<{}, z.core.$loose>;
     type: z.ZodObject<{
         id: z.ZodNumber;
         type: z.ZodString;
@@ -60,11 +58,9 @@ export declare const AttributeSetsResponseSchema: z.ZodObject<{
         updatedDate: z.ZodString;
         version: z.ZodNumber;
         identifier: z.ZodString;
-        typeId: z.ZodNumber;
         title: z.ZodString;
         schema: z.ZodObject<{}, z.core.$loose>;
         isVisible: z.ZodBoolean;
-        properties: z.ZodObject<{}, z.core.$loose>;
         type: z.ZodObject<{
             id: z.ZodNumber;
             type: z.ZodString;

package/dist/attribute-sets/attributeSetsSchemas.js

@@ -47,11 +47,9 @@ exports.AttributeSetEntitySchema = zod_1.z.object({
     updatedDate: zod_1.z.string(),
     version: zod_1.z.number(),
     identifier: zod_1.z.string(),
-    typeId: zod_1.z.number(),
     title: zod_1.z.string(),
     schema: zod_1.z.object({}).passthrough(),
     isVisible: zod_1.z.boolean(),
-    properties: zod_1.z.object({}).passthrough(),
     type: zod_1.z.object({
         id: zod_1.z.number(),
         type: zod_1.z.string(),

package/dist/base/stateModule.d.ts

@@ -10,6 +10,7 @@ export default class StateModule {
     lang: string | undefined;
     token: string | undefined;
     guestId: string | undefined;
+    deviceMetadata: string | undefined;
     accessToken: string | undefined;
     traficLimit: boolean;
     refreshToken: string | undefined;

package/dist/base/stateModule.js

@@ -27,6 +27,9 @@ class StateModule {
         // Normalize empty string to undefined: an explicit '' must not masquerade
         // as a set guest id (it would otherwise suppress id resolution).
         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;

package/dist/base/syncModules.d.ts

@@ -111,113 +111,6 @@ export default abstract class SyncModules {
      * @returns {any} Sorted attributes.
      */
     protected _sortAttributes: (data: any) => any;
-    /**
-     * Adds a specified number of days to a date.
-     * @param {Date} date - The initial date.
-     * @param {number} days - The number of days to add.
-     * @returns {any} The new date with added days.
-     */
-    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 {(currentDate: Date) => void} processDate - Callback function to process each date.
-     */
-    protected _processScheduleDates(date: Date, config: {
-        inEveryWeek: boolean;
-        inEveryMonth: boolean;
-    }, 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.
-     * @param {any[]} schedule.times - The times for each interval.
-     * @param {boolean} schedule.inEveryMonth - The month intervals for each interval.
-     * @param {Set<Array<string>>} utcIntervals - A set to store unique intervals.
-     */
-    protected _generateIntervalsForDate(date: Date, schedule: {
-        inEveryWeek: boolean;
-        times: any[];
-        inEveryMonth: boolean;
-    }, 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.
-     * @param {boolean} interval.inEveryMonth - Indicates whether the schedule is monthly.
-     * @param {any[]} timeIntervals - The time intervals to process.
-     * @param {Set<Array<string>>} utcIntervals - A set to store unique intervals.
-     */
-    protected _generateIntervalsForFormDate(date: Date, interval: {
-        inEveryWeek: boolean;
-        inEveryMonth: boolean;
-    }, 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.
      *
@@ -238,16 +131,20 @@ export default abstract class SyncModules {
      * 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,
+     * Same `additionalFields` 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.
      *
+     * `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.
@@ -287,6 +184,30 @@ export default abstract class SyncModules {
      * @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
      *
@@ -313,6 +234,10 @@ export default abstract class SyncModules {
      * 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;