oneentry 1.0.162 → 1.0.163

package/README.md

@@ -202,6 +202,24 @@ Zod and the response schemas are loaded on demand, the first time a response act
 
 Together that means a project calling a single SDK method loads about **43 kB minified (9.7 kB gzip)** instead of 536 kB, with Zod, the schemas and Socket.io landing in chunks that are never requested. The SDK is published as both CommonJS and ESM (`sideEffects: false`), so bundlers can tree-shake the rest.
 
+### Attribute Values
+
+`IAttributeValue.value` is typed `unknown` — its shape is decided by `type` at runtime. The trap is files: an `image`/`file` attribute holding **one** file has its value unwrapped to the file object itself, while several files and every `groupOfImages` stay an array. Reading the wrong shape is not a compile error, it is a silently missing image. Read files through the helpers instead:
+
+```js
+import { defineOneEntry, getAttributeFile, getAttributeFiles } from 'oneentry'
+
+const { Pages } = defineOneEntry('your-url', { token: 'your-app-token' })
+const page = await Pages.getPageByUrl('catalog')
+
+// Same call whether the attribute holds one file or a gallery.
+const images = getAttributeFiles(page.attributeValues.gallery) // IAttributeFile[]
+const cover = getAttributeFile(page.attributeValues.cover) // IAttributeFile | null
+const blurDataURL = cover?.previewLink?.default?.[0]
+```
+
+Also exported: `getAdditionalFields(attr)` for an attribute's nested fields as a marker map, the type guards `isFileAttribute`, `isStringAttribute`, `isNumberAttribute`, `isListAttribute`, the file type `IAttributeFile`, and `ITypedAttributeValue` — `IAttributeValue` as a discriminated union over `type`, to annotate with where you want the compiler to enforce the shape.
+
 ### 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:

package/changelog.md

@@ -1,5 +1,64 @@
 # SDK Change Log
 
+## v.1.0.163
+
+### What's Fixed
+
+- **FormData > `getFormsDataByMarker` — the filter body is typed.** It was `body?: object`, so nothing about it was checked or suggested. That is worse than merely inconvenient: the API **ignores** a field it does not recognize, so `statuses: ['approved']` (note the "s") returned every record — unmoderated ones included — while the code looked correct. The new `IFormsDataFilter` declares the fields the endpoint actually applies, each verified against a live project:
+
+  ```ts
+  await FormData.getFormsDataByMarker('review', 12, {
+      entityIdentifier: 'blog',
+      parentId: 10,
+      userIdentifier: '',
+      status: ['approved'],
+      dateFrom: '2025-01-01',
+      dateTo: '',
+  })
+  ```
+
+  Note `entityparentIdentifier` from the old JSDoc example is **not** among them: the API ignores it (filtering by it changes nothing), so it is not declared. Use `parentId` to fetch replies to a submission. Also exported: `FormDataStatus`.
+
+- **FormData > the JSDoc example used a status that does not exist.** It showed `"status": ["new", "approved"]`; copied as-is it answers `400 each value in status must be a valid enum value`, without naming the valid ones. The set is `sent`, `moderation`, `approved`, `banned`, `deleted` — now spelled out next to `status` in the JSDoc, and enforced by `FormDataStatus`. `status` must also be an array; a bare string is a `400`.
+
+- **FormData > the locale unwrapping of `formData` is now documented.** The API returns `formData: { "en_US": [ … ] }`, the SDK normalizes it and hands over the array for the requested `langCode`. Nothing said so, so code written against the raw API response — the one you see first, through curl or the panel — read `formData[langCode]`, got `undefined`, and rendered an empty list with no error anywhere. It is now stated in the method's JSDoc and on `formData` in `IFormByMarkerDataEntity` / `IFormDataEntity`. Behaviour is unchanged.
+
+- **FormData > `IBodyTypeImageGroupOfImages.type` had a typo: `'groupOfImage'`**, a value the API rejects (`400 formData's marker '…' type must be one of […]`). Worse than a plain typo — the editor autocompleted it. It is now `'groupOfImages'`, matching the attribute type and the SDK's own upload branch, which has always checked for the plural.
+
+- **FormData > `postFormsData` JSDoc now points at `IImageValue` / `IFileValue`** — the shape an attached file must take, which is *not* what `FileUploading.upload` returns (that one carries `contentType`, which form data rejects; the SDK strips it for you when it uploads the file itself). These interfaces were the only place that shape was written down, and nothing linked to them.
+
+- **AttributesSets > `getSingleAttributeByMarkerSet` — the interface declared its arguments in the reverse order of the implementation.** `IAttributesSets` (and its JSDoc) said `(attributeMarker, setMarker, langCode)`, while `AttributesSetsApi` — and the request path `/{setMarker}/attributes/{attributeMarker}` — take `(setMarker, attributeMarker, langCode)`. Both parameters are `string`, so `implements` did not catch it and neither did any caller's compiler: a call written from the interface built `/icon/attributes/page_content` and the API answered `404 Attribute not found`, which reads like a missing attribute rather than a wrong call. The interface now matches the implementation; no runtime behaviour changed.
+
+- **15 module interfaces declared `langCode` as required** while the implementing method defaults it — Blocks > `getBlockByMarker`, Discounts > `getDiscountByMarker`, IntegrationCollections > `getICollections` / `getICollectionById` / `getICollectionRowsById` / `getICollectionRowByMarkerAndId` / `createICollectionRow` / `updateICollectionRow`, Menus > `getMenusByMarker`, Orders > `getAllStatusesByStorageMarker`, ProductStatuses > `getProductStatuses` / `getProductsByStatusMarker`, Templates > `getTemplateByType`, TemplatePreviews > `getTemplatePreviews` / `getTemplatePreviewByMarker`. All are now optional, as the JSDoc already stated.
+
+- **Two parameters were named differently in the interface than in the implementation**: AuthProvider > `signUp` / `auth` took `data` (now `body`), and FormData > `getFormsDataByMarker` took `isNested`, documented as "hierarchical data", while the method sends `isExtended` — a flag for additional fields. Names and docs now follow the implementation.
+
+- **A test now guards this whole class of defect.** `src/base/tests/signatures.spec.ts` parses the sources with the TypeScript compiler API and compares every `*Api` class against the interface it `implements` — parameter names, order and optionality. The compiler cannot do this: it matches parameters positionally by type, so a swapped pair of `string`s is a valid implementation to it.
+
+### What's New
+
+- **Typed access to attribute values.** `IAttributeValue.value` is `unknown` — its shape is decided by `type` at runtime — and the rule for that shape lived only in a JSDoc comment, so breaking it cost nothing at compile time. The classic case: an `image` attribute holding **one** file has its `value` unwrapped to the file object itself, so a helper written as `Array.isArray(v) ? v[0] : undefined` returns `undefined` for every single-image attribute, builds cleanly, and shows an empty page. The SDK now ships the missing pieces:
+
+  ```ts
+  import { getAttributeFiles, getAttributeFile } from 'oneentry'
+
+  // Same call for one image and for a gallery — no branching on the shape.
+  const images = getAttributeFiles(page.attributeValues.cover)
+  const cover = getAttributeFile(product.attributeValues.img)
+  const blurDataURL = cover?.previewLink?.default?.[0]
+  ```
+
+  - `getAttributeFiles(attr)` → `IAttributeFile[]` — every file of an `image`, `file` or `groupOfImages` attribute, collapsing the single-file and array shapes to one list; empty for anything else.
+  - `getAttributeFile(attr)` → `IAttributeFile | null` — the first file, for covers and previews.
+  - `getAdditionalFields(attr)` → `Record<string, IAttributeValue>` — nested fields as a marker map. `additionalFields` is typed `Record<string, IAttributeValue> | unknown[]` because the API returns an empty **array** when there are none, and that union makes every field read a type error; the helper collapses it (and converts the `rawData: true` array by `marker`).
+  - Type guards `isFileAttribute`, `isStringAttribute`, `isNumberAttribute`, `isListAttribute` — alongside the existing `isTimeIntervalAttribute`.
+
+- **`IAttributeFile`** — the file object of an attribute value is now an exported type: `filename`, `downloadLink`, `size`, `contentType`, plus the optional `previewLink` (previews keyed by template, each a `[base64 placeholder, url]` pair — the placeholder is what a `blurDataURL` needs) and `defaultPreview`. It had to be re-declared by hand in every project until now.
+
+- **Attribute values are now validated.** Every schema carrying `attributeValues` used `z.record(z.string(), z.any())` — the whole attribute payload passed validation unconditionally, so a change in the API's file shape reached consumers as an empty gallery, not as an error. The shared `AttributeValuesSchema` (`base/validation.ts`) replaces it in the admins, blocks, menus, pages, products and templates schemas. It stays open where the data is open — what `value` holds is defined by the project's own attribute set — and checks the one part the API fixes and the SDK's helpers depend on: the files of `image` / `file` / `groupOfImages` attributes, nested `additionalFields` included. A renamed or dropped `downloadLink` is reported as a validation issue naming the marker and index; unknown new fields on a file are accepted. Exported alongside it: `AttributeFileSchema`.
+
+- **`ITypedAttributeValue`** — `IAttributeValue` as a discriminated union over `type` (`IFileAttributeValue`, `IStringAttributeValue`, `INumberAttributeValue`, `IListAttributeValue`, `ITimeIntervalAttributeValue`), so `switch (attr.type)` narrows `value` for you. The union is closed on purpose: a loose member (`type: string`) would match every case and collapse the narrowing back to `unknown`; types the SDK does not model (`entity`, `date`, custom ones) stay on `IAttributeValue`. Opt-in — `IAttributeValues` keeps the loose `IAttributeValue`, so nothing existing changes.
+
 ## v.1.0.162
 
 ### What's New

package/dist/admins/adminsSchemas.d.ts

@@ -3,6 +3,10 @@
  * @description Zod schemas for validating admins-related API responses
  */
 import { z } from 'zod';
+/**
+ * Admin entity schema
+ * Includes all fields returned by the API
+ */
 export declare const AdminEntitySchema: z.ZodObject<{
     id: z.ZodNumber;
     attributeSetId: z.ZodNullable<z.ZodNumber>;
@@ -10,17 +14,7 @@ export declare const AdminEntitySchema: z.ZodObject<{
     attributeSetIdentifier: z.ZodNullable<z.ZodString>;
     position: z.ZodNullable<z.ZodNumber>;
     isSync: z.ZodBoolean;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<{
-        type: string;
-        value: unknown;
-        position?: number;
-        additionalFields?: Record<string, unknown> | unknown[];
-    }, unknown, z.core.$ZodTypeInternals<{
-        type: string;
-        value: unknown;
-        position?: number;
-        additionalFields?: Record<string, unknown> | unknown[];
-    }, unknown>>>>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;
     distance: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
@@ -34,17 +28,7 @@ export declare const AdminsResponseSchema: z.ZodArray<z.ZodObject<{
     attributeSetIdentifier: z.ZodNullable<z.ZodString>;
     position: z.ZodNullable<z.ZodNumber>;
     isSync: z.ZodBoolean;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodType<{
-        type: string;
-        value: unknown;
-        position?: number;
-        additionalFields?: Record<string, unknown> | unknown[];
-    }, unknown, z.core.$ZodTypeInternals<{
-        type: string;
-        value: unknown;
-        position?: number;
-        additionalFields?: Record<string, unknown> | unknown[];
-    }, unknown>>>>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;
     distance: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>>;

package/dist/admins/adminsSchemas.js

@@ -6,18 +6,11 @@ exports.AdminsResponseSchema = exports.AdminEntitySchema = void 0;
  * @description Zod schemas for validating admins-related API responses
  */
 const zod_1 = require("zod");
+const validation_1 = require("../base/validation");
 /**
  * Admin entity schema
  * Includes all fields returned by the API
  */
-const AttributeValueSchema = zod_1.z.object({
-    type: zod_1.z.string(),
-    value: zod_1.z.unknown(),
-    position: zod_1.z.number().optional(),
-    additionalFields: zod_1.z
-        .union([zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()), zod_1.z.array(zod_1.z.unknown())])
-        .optional(),
-});
 exports.AdminEntitySchema = zod_1.z.object({
     id: zod_1.z.number(),
     attributeSetId: zod_1.z.number().nullable(),
@@ -25,7 +18,7 @@ exports.AdminEntitySchema = zod_1.z.object({
     attributeSetIdentifier: zod_1.z.string().nullable(),
     position: zod_1.z.number().nullable(),
     isSync: zod_1.z.boolean(),
-    attributeValues: zod_1.z.record(zod_1.z.string(), zod_1.z.record(zod_1.z.string(), AttributeValueSchema)),
+    attributeValues: validation_1.AttributeValuesSchema,
     moduleFormConfigs: zod_1.z.array(zod_1.z.any()).optional(),
     distance: zod_1.z.number().optional(),
 });

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

@@ -14,18 +14,18 @@ interface IAttributesSets {
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      * @description This method fetches attributes by a specific marker.
      */
-    getAttributesByMarker(marker: string, langCode: string): Promise<IAttributesSetsEntity[] | IError>;
+    getAttributesByMarker(marker: string, langCode?: string): Promise<IAttributesSetsEntity[] | IError>;
     /**
-     * Fetches a single attribute by its marker and the set marker.
+     * Fetches a single attribute by the set marker and the attribute marker.
      * @handleName getSingleAttributeByMarkerSet
-     * @param {string} attributeMarker - The marker identifying the attribute. Example: "color".
-     * @param {string} setMarker - The marker identifying the attribute set. Example: "productAttributes".
+     * @param {string} setMarker - The marker identifying the attribute set — the first path segment. Example: "productAttributes".
+     * @param {string} attributeMarker - The marker identifying the attribute inside that set. Example: "color".
      * @param {string} [langCode] - The language code for localization purposes. Default: "en_US".
      * @returns {IAttributesSetsEntity} A promise that resolves to an attribute set entity or an error.
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
-     * @description This method fetches a single attribute by its marker and the set marker.
+     * @description This method fetches a single attribute of an attribute set. The order matches the request path `/{setMarker}/attributes/{attributeMarker}`: the set comes first. Both parameters are strings, so swapping them type-checks and answers `404 Attribute not found`.
      */
-    getSingleAttributeByMarkerSet(attributeMarker: string, setMarker: string, langCode: string): Promise<IAttributesSetsEntity | IError>;
+    getSingleAttributeByMarkerSet(setMarker: string, attributeMarker: string, langCode?: string): Promise<IAttributesSetsEntity | IError>;
 }
 /**
  * Represents the structure of a list item.

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

@@ -8,7 +8,7 @@ interface IAuthProvider {
      * Registers a new user.
      * @handleName signUp
      * @param {string} marker - The marker identifying the auth provider. Example: "email".
-     * @param {ISignUpData} data - The data required for user registration.
+     * @param {ISignUpData} body - The data required for user registration.
      * @example
         {
           "formIdentifier": "reg",
@@ -40,7 +40,7 @@ interface IAuthProvider {
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      * @description This method registers a new user.
      */
-    signUp(marker: string, data: ISignUpData, langCode?: string): Promise<ISignUpEntity | IError>;
+    signUp(marker: string, body: ISignUpData, langCode?: string): Promise<ISignUpEntity | IError>;
     /**
      * Generates an activation code for a user.
      * @handleName generateCode
@@ -79,12 +79,12 @@ interface IAuthProvider {
      * Authorizes a user.
      * @handleName auth
      * @param {string} marker - The marker identifying the auth provider. Example: "email".
-     * @param {IAuthPostBody} data - The data required for user authorization. Example: .
+     * @param {IAuthPostBody} body - The data required for user authorization. Example: .
      * @returns {IAuthEntity} A promise that resolves to an auth entity or an error.
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      * @description This method authorizes a user.
      */
-    auth(marker: string, data: IAuthPostBody): Promise<IAuthEntity | IError>;
+    auth(marker: string, body: IAuthPostBody): Promise<IAuthEntity | IError>;
     /**
      * Refreshes a user's access token.
      * @handleName refresh

package/dist/base/attributes.d.ts

@@ -0,0 +1,105 @@
+import type { IAttributeFile, IAttributeValue, IFileAttributeValue, IListAttributeValue, INumberAttributeValue, IStringAttributeValue } from './utils';
+/**
+ * Narrows an attribute value to a file-bearing attribute.
+ *
+ * `IAttributeValue.value` is `unknown` — its shape depends on `type` — so this
+ * guard is what lets you reach the files without a cast. It accepts both shapes
+ * the SDK produces: a single file object for an `image`/`file` attribute holding
+ * exactly one file, an array for several and for every `groupOfImages`.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is an `image`, `file` or `groupOfImages` carrying files (or nothing).
+ * @example
+ * ```ts
+ * const attr = page.attributeValues.cover;
+ * if (isFileAttribute(attr)) {
+ *     // attr.value is IAttributeFile | IAttributeFile[] | null — no cast
+ * }
+ * ```
+ */
+export declare function isFileAttribute(attr: IAttributeValue | undefined): attr is IFileAttributeValue;
+/**
+ * Reads every file of an attribute as an array.
+ *
+ * The one-call path for the common case. An `image`/`file` attribute holding a
+ * single file has it unwrapped to the object itself, while several files and
+ * every `groupOfImages` stay an array — a rule that is easy to get wrong in a
+ * way the compiler cannot catch, since `value` is `unknown`: reading `value[0]`
+ * off a single file yields `undefined` and nothing anywhere reports an error.
+ * This helper collapses both shapes to a list.
+ *
+ * Anything that is not a file-bearing attribute yields an empty array, so it is
+ * safe to call on an arbitrary attribute without checking `type` first.
+ * @param {IAttributeValue | undefined} attr - An attribute value, e.g. `page.attributeValues.cover`.
+ * @returns {IAttributeFile[]} The files, in the order the API returned them; empty when the attribute holds none or is not file-bearing.
+ * @example
+ * ```ts
+ * import { getAttributeFiles } from 'oneentry';
+ *
+ * // Works the same for one image and for a gallery.
+ * const images = getAttributeFiles(page.attributeValues.cover);
+ * images.map((file) => file.downloadLink);
+ * ```
+ */
+export declare function getAttributeFiles(attr: IAttributeValue | undefined): IAttributeFile[];
+/**
+ * Reads the first file of an attribute.
+ *
+ * The single-image counterpart of {@link getAttributeFiles} — same shape
+ * handling, but returns the file itself instead of a list. For a gallery it
+ * returns the first entry, which is what a preview or a cover usually needs.
+ * @param {IAttributeValue | undefined} attr - An attribute value, e.g. `product.attributeValues.img`.
+ * @returns {IAttributeFile | null} The first file, or null when the attribute holds none.
+ * @example
+ * ```ts
+ * import { getAttributeFile } from 'oneentry';
+ *
+ * const cover = getAttributeFile(product.attributeValues.img);
+ * const blurDataURL = cover?.previewLink?.default?.[0];
+ * ```
+ */
+export declare function getAttributeFile(attr: IAttributeValue | undefined): IAttributeFile | null;
+/**
+ * Narrows an attribute value to a text attribute.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is a `string`, `text` or `textEditor` carrying a string (or nothing).
+ */
+export declare function isStringAttribute(attr: IAttributeValue | undefined): attr is IStringAttributeValue;
+/**
+ * Narrows an attribute value to a numeric attribute.
+ *
+ * The SDK casts `integer`, `float` and `real` values to a JS number, so the
+ * guard checks for one — a value that failed to cast is `null`.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is an `integer`, `float` or `real` carrying a number (or nothing).
+ */
+export declare function isNumberAttribute(attr: IAttributeValue | undefined): attr is INumberAttributeValue;
+/**
+ * Narrows an attribute value to a `list` attribute.
+ *
+ * The option shape is defined by the attribute set, so the entries stay
+ * `unknown` — the guard only promises the array container.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is a `list` carrying an array.
+ */
+export declare function isListAttribute(attr: IAttributeValue | undefined): attr is IListAttributeValue;
+/**
+ * Reads the nested fields of an attribute as a marker map.
+ *
+ * `additionalFields` is typed `Record<string, IAttributeValue> | unknown[]`
+ * because the API returns an empty **array** when an attribute has no nested
+ * fields — the union makes every read of a field a type error. This helper
+ * collapses that case to an empty map, so the result is always keyed by marker.
+ *
+ * With `rawData: true` in the config the SDK keeps the API's original array of
+ * fields; it is converted here by `marker` as well, so the helper returns the
+ * same map in both modes.
+ * @param {IAttributeValue | undefined} attr - An attribute value whose nested fields to read.
+ * @returns {Record<string, IAttributeValue>} Nested attribute values keyed by marker; empty when there are none.
+ * @example
+ * ```ts
+ * import { getAdditionalFields } from 'oneentry';
+ *
+ * const alt = getAdditionalFields(page.attributeValues.cover).alt?.value;
+ * ```
+ */
+export declare function getAdditionalFields(attr: IAttributeValue | undefined): Record<string, IAttributeValue>;

package/dist/base/attributes.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFileAttribute = isFileAttribute;
+exports.getAttributeFiles = getAttributeFiles;
+exports.getAttributeFile = getAttributeFile;
+exports.isStringAttribute = isStringAttribute;
+exports.isNumberAttribute = isNumberAttribute;
+exports.isListAttribute = isListAttribute;
+exports.getAdditionalFields = getAdditionalFields;
+const _FILE_TYPES = ['image', 'file', 'groupOfImages'];
+/**
+ * Tests whether a value looks like a file object of an attribute.
+ *
+ * A file is identified by `downloadLink`: it is the one field every file of
+ * every attribute carries, while previews are only generated for images.
+ * @param {unknown} value - The value to test.
+ * @returns {boolean} True when the value is a file object.
+ */
+function _isFile(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof value.downloadLink === 'string');
+}
+/**
+ * Narrows an attribute value to a file-bearing attribute.
+ *
+ * `IAttributeValue.value` is `unknown` — its shape depends on `type` — so this
+ * guard is what lets you reach the files without a cast. It accepts both shapes
+ * the SDK produces: a single file object for an `image`/`file` attribute holding
+ * exactly one file, an array for several and for every `groupOfImages`.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is an `image`, `file` or `groupOfImages` carrying files (or nothing).
+ * @example
+ * ```ts
+ * const attr = page.attributeValues.cover;
+ * if (isFileAttribute(attr)) {
+ *     // attr.value is IAttributeFile | IAttributeFile[] | null — no cast
+ * }
+ * ```
+ */
+function isFileAttribute(attr) {
+    if (!attr || !_FILE_TYPES.includes(attr.type))
+        return false;
+    if (attr.value === null || attr.value === undefined)
+        return true;
+    return Array.isArray(attr.value)
+        ? attr.value.every((item) => _isFile(item))
+        : _isFile(attr.value);
+}
+/**
+ * Reads every file of an attribute as an array.
+ *
+ * The one-call path for the common case. An `image`/`file` attribute holding a
+ * single file has it unwrapped to the object itself, while several files and
+ * every `groupOfImages` stay an array — a rule that is easy to get wrong in a
+ * way the compiler cannot catch, since `value` is `unknown`: reading `value[0]`
+ * off a single file yields `undefined` and nothing anywhere reports an error.
+ * This helper collapses both shapes to a list.
+ *
+ * Anything that is not a file-bearing attribute yields an empty array, so it is
+ * safe to call on an arbitrary attribute without checking `type` first.
+ * @param {IAttributeValue | undefined} attr - An attribute value, e.g. `page.attributeValues.cover`.
+ * @returns {IAttributeFile[]} The files, in the order the API returned them; empty when the attribute holds none or is not file-bearing.
+ * @example
+ * ```ts
+ * import { getAttributeFiles } from 'oneentry';
+ *
+ * // Works the same for one image and for a gallery.
+ * const images = getAttributeFiles(page.attributeValues.cover);
+ * images.map((file) => file.downloadLink);
+ * ```
+ */
+function getAttributeFiles(attr) {
+    if (!attr)
+        return [];
+    const value = attr.value;
+    if (Array.isArray(value))
+        return value.filter((item) => _isFile(item));
+    return _isFile(value) ? [value] : [];
+}
+/**
+ * Reads the first file of an attribute.
+ *
+ * The single-image counterpart of {@link getAttributeFiles} — same shape
+ * handling, but returns the file itself instead of a list. For a gallery it
+ * returns the first entry, which is what a preview or a cover usually needs.
+ * @param {IAttributeValue | undefined} attr - An attribute value, e.g. `product.attributeValues.img`.
+ * @returns {IAttributeFile | null} The first file, or null when the attribute holds none.
+ * @example
+ * ```ts
+ * import { getAttributeFile } from 'oneentry';
+ *
+ * const cover = getAttributeFile(product.attributeValues.img);
+ * const blurDataURL = cover?.previewLink?.default?.[0];
+ * ```
+ */
+function getAttributeFile(attr) {
+    var _a;
+    return (_a = getAttributeFiles(attr)[0]) !== null && _a !== void 0 ? _a : null;
+}
+/**
+ * Narrows an attribute value to a text attribute.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is a `string`, `text` or `textEditor` carrying a string (or nothing).
+ */
+function isStringAttribute(attr) {
+    return (!!attr &&
+        (attr.type === 'string' ||
+            attr.type === 'text' ||
+            attr.type === 'textEditor') &&
+        (attr.value === null || typeof attr.value === 'string'));
+}
+/**
+ * Narrows an attribute value to a numeric attribute.
+ *
+ * The SDK casts `integer`, `float` and `real` values to a JS number, so the
+ * guard checks for one — a value that failed to cast is `null`.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is an `integer`, `float` or `real` carrying a number (or nothing).
+ */
+function isNumberAttribute(attr) {
+    return (!!attr &&
+        (attr.type === 'integer' ||
+            attr.type === 'float' ||
+            attr.type === 'real') &&
+        (attr.value === null || typeof attr.value === 'number'));
+}
+/**
+ * Narrows an attribute value to a `list` attribute.
+ *
+ * The option shape is defined by the attribute set, so the entries stay
+ * `unknown` — the guard only promises the array container.
+ * @param {IAttributeValue | undefined} attr - The attribute value to test.
+ * @returns {boolean} True when the attribute is a `list` carrying an array.
+ */
+function isListAttribute(attr) {
+    return !!attr && attr.type === 'list' && Array.isArray(attr.value);
+}
+/**
+ * Reads the nested fields of an attribute as a marker map.
+ *
+ * `additionalFields` is typed `Record<string, IAttributeValue> | unknown[]`
+ * because the API returns an empty **array** when an attribute has no nested
+ * fields — the union makes every read of a field a type error. This helper
+ * collapses that case to an empty map, so the result is always keyed by marker.
+ *
+ * With `rawData: true` in the config the SDK keeps the API's original array of
+ * fields; it is converted here by `marker` as well, so the helper returns the
+ * same map in both modes.
+ * @param {IAttributeValue | undefined} attr - An attribute value whose nested fields to read.
+ * @returns {Record<string, IAttributeValue>} Nested attribute values keyed by marker; empty when there are none.
+ * @example
+ * ```ts
+ * import { getAdditionalFields } from 'oneentry';
+ *
+ * const alt = getAdditionalFields(page.attributeValues.cover).alt?.value;
+ * ```
+ */
+function getAdditionalFields(attr) {
+    const fields = attr === null || attr === void 0 ? void 0 : attr.additionalFields;
+    if (!fields || typeof fields !== 'object')
+        return {};
+    if (Array.isArray(fields)) {
+        // rawData mode: the API's own array of fields, each carrying its marker.
+        return Object.fromEntries(fields
+            .filter((field) => !!field &&
+            typeof field === 'object' &&
+            typeof field.marker === 'string')
+            .map((field) => [field.marker, field]));
+    }
+    return fields;
+}

package/dist/base/utils.d.ts

@@ -266,10 +266,19 @@ interface ITimeIntervalRange {
  * @property {string} type - Attribute data type (e.g. "string", "integer", "list", "file", "image").
  * @property {unknown} value - Attribute value — actual TS type depends on `type`, and the SDK normalizes it to the same shape in every module: `string` for "string"/"text"; `number | null` for "integer"/"float"/"real"; the file object itself for a single-file "image"/"file" and an array of them for several; an array for "list" and "groupOfImages". An attribute with no value is always `null`. Example: "Admins text".
  * @property {number} [position] - Sort position of the value inside its set; the containing collection is returned sorted by it. Example: 0.
- * @property {Record<string, IAttributeValue> | unknown[]} [additionalFields] - Nested attribute values keyed by marker; the API may also return an empty array when none are configured. Optional.
+ * @property {Record<string, IAttributeValue> | unknown[]} [additionalFields] - Nested attribute values keyed by marker; the API may also return an empty array when none are configured. Read it through `getAdditionalFields`, which collapses that array to an empty map. Optional.
  * @property {boolean} [isIcon] - Block/preview attribute flag — whether the field is treated as an icon. Optional.
  * @property {boolean} [isProductPreview] - Block/preview attribute flag — whether the field is shown in product preview. Optional.
  * @description A single attribute value attached to an entity (admin, user, page, product, …).
+ *
+ * `value` is `unknown` because its shape is decided by `type` at runtime, which
+ * a single interface cannot express. Do not read it by assumption — the type
+ * checker cannot catch a wrong guess (an array read on a single file yields
+ * `undefined`, silently, with no error anywhere). Reach it through the guards
+ * and helpers instead: `isFileAttribute` / `getAttributeFiles`,
+ * `isStringAttribute`, `isNumberAttribute`, `isListAttribute`,
+ * `isTimeIntervalAttribute`; or annotate with {@link ITypedAttributeValue} to
+ * have the compiler enforce the rule.
  */
 interface IAttributeValue {
     type: string;
@@ -286,6 +295,90 @@ interface IAttributeValue {
 interface IAttributeValues {
     [key: string]: IAttributeValue;
 }
+/**
+ * @interface IAttributeFile
+ * @property {string} filename - Storage-relative path of the file. Example: "files/project/product/2954/image/48853cbf-4462-42c6-8b99-d14f721c21a2.jpeg".
+ * @property {string} downloadLink - Public URL of the original file. Example: "https://my-project.oneentry.cloud/cloud-static/files/project/product/2954/image/48853cbf.jpeg".
+ * @property {number} size - File size in bytes. Example: 742690.
+ * @property {string} contentType - MIME type of the file. Example: "image/jpeg".
+ * @property {Record<string, string[]>} [previewLink] - Generated previews keyed by preview template. Each entry is a `[placeholder, url]` pair: the first item is an inline base64 thumbnail (usable as a `blurDataURL`), the second the preview URL. Optional — previews are generated for images; a non-image `file` may arrive without them. Example: { "default": ["data:image/webp;base64,UklGRmwA…", "https://…48853cbf.preview.default.jpeg"] }.
+ * @property {string} [defaultPreview] - Key of `previewLink` to use by default. Optional — present alongside `previewLink`. Example: "default".
+ * @description One file of an `image`, `file` or `groupOfImages` attribute value. Reach it through {@link IFileAttributeValue} — or, without caring whether the attribute holds one file or many, through `getAttributeFiles`.
+ */
+interface IAttributeFile {
+    filename: string;
+    downloadLink: string;
+    size: number;
+    contentType: string;
+    previewLink?: Record<string, string[]>;
+    defaultPreview?: string;
+}
+/**
+ * @interface IFileAttributeValue
+ * @property {'image' | 'file' | 'groupOfImages'} type - Discriminant identifying the attribute as file-bearing.
+ * @property {IAttributeFile | IAttributeFile[] | null} value - The file itself when an `image`/`file` attribute holds exactly one, an array when it holds several, always an array for `groupOfImages`, `null` when nothing is set.
+ * @description {@link IAttributeValue} narrowed to attributes that carry files, whose generic `value: unknown` resolves to {@link IAttributeFile}. The single/array split is what the SDK's normalization produces, so it has to be handled: narrow with `isFileAttribute`, or skip the branch entirely with `getAttributeFiles` / `getAttributeFile`.
+ */
+interface IFileAttributeValue extends IAttributeValue {
+    type: 'image' | 'file' | 'groupOfImages';
+    value: IAttributeFile | IAttributeFile[] | null;
+}
+/**
+ * @interface IStringAttributeValue
+ * @property {'string' | 'text' | 'textEditor'} type - Discriminant identifying the attribute as text-bearing.
+ * @property {string | null} value - The text; `null` when no value is set.
+ * @description {@link IAttributeValue} narrowed to text attributes. Narrow to it with `isStringAttribute`.
+ */
+interface IStringAttributeValue extends IAttributeValue {
+    type: 'string' | 'text' | 'textEditor';
+    value: string | null;
+}
+/**
+ * @interface INumberAttributeValue
+ * @property {'integer' | 'float' | 'real'} type - Discriminant identifying the attribute as numeric.
+ * @property {number | null} value - The number, cast by the SDK from the API's string form; `null` when no value is set.
+ * @description {@link IAttributeValue} narrowed to numeric attributes. Narrow to it with `isNumberAttribute`.
+ */
+interface INumberAttributeValue extends IAttributeValue {
+    type: 'integer' | 'float' | 'real';
+    value: number | null;
+}
+/**
+ * @interface IListAttributeValue
+ * @property {'list'} type - Discriminant identifying the attribute as a list.
+ * @property {unknown[]} value - The selected options. The option shape is defined by the attribute set, so the entries stay `unknown` — only the array container is guaranteed.
+ * @description {@link IAttributeValue} narrowed to `list` attributes. Narrow to it with `isListAttribute`.
+ */
+interface IListAttributeValue extends IAttributeValue {
+    type: 'list';
+    value: unknown[];
+}
+/**
+ * ITypedAttributeValue — {@link IAttributeValue} as a discriminated union over `type`.
+ *
+ * Opt-in, and deliberately closed: it lists only the types whose `value` shape
+ * the SDK guarantees, so `switch (attr.type)` narrows `value` for you. A loose
+ * member (`type: string`) would be assignable to every case and collapse the
+ * narrowing back to `unknown`, which is exactly what this type exists to avoid.
+ *
+ * `IAttributeValues` keeps the loose `IAttributeValue`, so nothing existing
+ * changes: narrow into this union with the guards (`isFileAttribute` and the
+ * rest), or annotate a value you control. Attribute types the SDK does not
+ * model (`entity`, `date`, custom ones) stay on `IAttributeValue`.
+ * @example
+ * ```ts
+ * function render(attr: ITypedAttributeValue) {
+ *     switch (attr.type) {
+ *         case 'image':
+ *         case 'file':
+ *             return attr.value; // IAttributeFile | IAttributeFile[] | null
+ *         case 'integer':
+ *             return attr.value; // number | null
+ *     }
+ * }
+ * ```
+ */
+type ITypedAttributeValue = IFileAttributeValue | IStringAttributeValue | INumberAttributeValue | IListAttributeValue | ITimeIntervalAttributeValue;
 /**
  * @interface IRating
  * @property {number} [value] - Average rating value. Example: 4.5.
@@ -351,4 +444,4 @@ type LangType = string | Array<string>;
  * LocalizeType
  */
 type LocalizeType = ILocalizeInfo;
-export type { IAttributeLocalizeInfo, IAttributes, IAttributeValue, IAttributeValues, IConfig, IError, IHttpHeaders, IHttpOptions, ILocalizeInfo, IRating, ITimeIntervalAttributeValue, ITimeIntervalEntitySchedule, ITimeIntervalGroup, ITimeIntervalPoint, ITimeIntervalRange, ITimeIntervalSchedule, ITimeIntervalWindow, LangType, LocalizeType, TimeIntervalPair, };
+export type { IAttributeFile, IAttributeLocalizeInfo, IAttributes, IAttributeValue, IAttributeValues, IConfig, IError, IFileAttributeValue, IHttpHeaders, IHttpOptions, IListAttributeValue, ILocalizeInfo, INumberAttributeValue, IRating, IStringAttributeValue, ITimeIntervalAttributeValue, ITimeIntervalEntitySchedule, ITimeIntervalGroup, ITimeIntervalPoint, ITimeIntervalRange, ITimeIntervalSchedule, ITimeIntervalWindow, ITypedAttributeValue, LangType, LocalizeType, TimeIntervalPair, };