oneentry 1.0.162 → 1.0.163

package/dist/pages/pagesSchemas.js

@@ -6,6 +6,7 @@ exports.SinglePageSchema = exports.PageSearchResponseSchema = exports.PageSearch
  * @description Zod schemas for validating pages-related API responses
  */
 const zod_1 = require("zod");
+const validation_1 = require("../base/validation");
 /**
  * Page entity schema
  * Includes all fields returned by the API
@@ -21,7 +22,7 @@ exports.PageEntitySchema = zod_1.z.object({
     type: zod_1.z.enum(['catalog_page', 'common_page', 'error_page', 'external_page']),
     templateIdentifier: zod_1.z.string().nullable(),
     attributeSetIdentifier: zod_1.z.string().nullable(),
-    attributeValues: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+    attributeValues: validation_1.AttributeValuesSchema,
     moduleFormConfigs: zod_1.z.array(zod_1.z.any()).optional(),
     rating: zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()).optional(),
     isSync: zod_1.z.boolean(),

package/dist/product-statuses/productStatusesInterfaces.d.ts

@@ -12,7 +12,7 @@ interface IProductStatusesApi {
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      * @description This method searches for all product status objects.
      */
-    getProductStatuses(langCode: string): Promise<IProductStatusEntity[] | IError>;
+    getProductStatuses(langCode?: string): Promise<IProductStatusEntity[] | IError>;
     /**
      * Search for a product status object by its textual identifier (marker).
      * @handleName getProductsByStatusMarker
@@ -22,7 +22,7 @@ interface IProductStatusesApi {
      * @throws {IError} If there is an error during the fetch operation, it will return an error object.
      * @description This method searches for a product status object by its textual identifier (marker).
      */
-    getProductsByStatusMarker(marker: string, langCode: string): Promise<IProductStatusEntity | IError>;
+    getProductsByStatusMarker(marker: string, langCode?: string): Promise<IProductStatusEntity | IError>;
     /**
      * Check the existence of a textual identifier.
      * @handleName validateMarker

package/dist/products/productsSchemas.d.ts

@@ -41,7 +41,7 @@ export declare const ProductEntitySchema: z.ZodObject<{
     }, z.core.$strip>;
     sku: z.ZodNullable<z.ZodString>;
     isSync: z.ZodBoolean;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     categories: z.ZodArray<z.ZodString>;
     isVisible: z.ZodBoolean;
     moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;
@@ -83,7 +83,7 @@ export declare const ProductsResponseSchema: z.ZodObject<{
         }, z.core.$strip>;
         sku: z.ZodNullable<z.ZodString>;
         isSync: z.ZodBoolean;
-        attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+        attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         categories: z.ZodArray<z.ZodString>;
         isVisible: z.ZodBoolean;
         moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;
@@ -127,7 +127,7 @@ export declare const SingleProductSchema: z.ZodObject<{
     }, z.core.$strip>;
     sku: z.ZodNullable<z.ZodString>;
     isSync: z.ZodBoolean;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     categories: z.ZodArray<z.ZodString>;
     isVisible: z.ZodBoolean;
     moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;
@@ -189,7 +189,7 @@ export declare const ProductBlockSchema: z.ZodObject<{
     templateIdentifier: z.ZodNullable<z.ZodString>;
     isVisible: z.ZodBoolean;
     isSync: z.ZodBoolean;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
 /**
  * Related products schema
@@ -210,7 +210,7 @@ export declare const RelatedProductsSchema: z.ZodArray<z.ZodObject<{
     }, z.core.$strip>;
     sku: z.ZodNullable<z.ZodString>;
     isSync: z.ZodBoolean;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     categories: z.ZodArray<z.ZodString>;
     isVisible: z.ZodBoolean;
     moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;

package/dist/products/productsSchemas.js

@@ -6,6 +6,7 @@ exports.RelatedProductsSchema = exports.ProductBlockSchema = exports.ProductsCou
  * @description Zod schemas for validating products-related API responses
  */
 const zod_1 = require("zod");
+const validation_1 = require("../base/validation");
 /**
  * Product price schema
  */
@@ -44,7 +45,7 @@ exports.ProductEntitySchema = zod_1.z.object({
     }),
     sku: zod_1.z.string().nullable(),
     isSync: zod_1.z.boolean(),
-    attributeValues: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+    attributeValues: validation_1.AttributeValuesSchema,
     categories: zod_1.z.array(zod_1.z.string()),
     isVisible: zod_1.z.boolean(),
     moduleFormConfigs: zod_1.z.array(zod_1.z.any()).optional(),
@@ -116,7 +117,7 @@ exports.ProductBlockSchema = zod_1.z.object({
     templateIdentifier: zod_1.z.string().nullable(),
     isVisible: zod_1.z.boolean(),
     isSync: zod_1.z.boolean(),
-    attributeValues: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+    attributeValues: validation_1.AttributeValuesSchema,
 });
 /**
  * Related products schema

package/dist/templates/templatesInterfaces.d.ts

@@ -23,7 +23,7 @@ interface ITemplatesApi {
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      * @description This method gets template objects by type.
      */
-    getTemplateByType(type: BlockType, langCode: string): Promise<ITemplateEntity[] | IError>;
+    getTemplateByType(type: BlockType, langCode?: string): Promise<ITemplateEntity[] | IError>;
     /**
      * Get one template object by id.
      * @handleName getTemplateByMarker

package/dist/templates/templatesSchemas.d.ts

@@ -15,7 +15,7 @@ export declare const TemplateEntitySchema: z.ZodObject<{
     identifier: z.ZodString;
     version: z.ZodNumber;
     generalTypeName: z.ZodString;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     position: z.ZodNumber;
 }, z.core.$strip>;
 /**
@@ -29,7 +29,7 @@ export declare const TemplatesResponseSchema: z.ZodArray<z.ZodObject<{
     identifier: z.ZodString;
     version: z.ZodNumber;
     generalTypeName: z.ZodString;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     position: z.ZodNumber;
 }, z.core.$strip>>;
 /**
@@ -43,6 +43,6 @@ export declare const GroupedTemplatesResponseSchema: z.ZodRecord<z.ZodString, z.
     identifier: z.ZodString;
     version: z.ZodNumber;
     generalTypeName: z.ZodString;
-    attributeValues: z.ZodRecord<z.ZodString, z.ZodAny>;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     position: z.ZodNumber;
 }, z.core.$strip>>>;

package/dist/templates/templatesSchemas.js

@@ -6,6 +6,7 @@ exports.GroupedTemplatesResponseSchema = exports.TemplatesResponseSchema = expor
  * @description Zod schemas for validating templates-related API responses
  */
 const zod_1 = require("zod");
+const validation_1 = require("../base/validation");
 /**
  * Template entity schema
  * Includes all fields returned by the API
@@ -18,7 +19,7 @@ exports.TemplateEntitySchema = zod_1.z.object({
     identifier: zod_1.z.string(),
     version: zod_1.z.number(),
     generalTypeName: zod_1.z.string(),
-    attributeValues: zod_1.z.record(zod_1.z.string(), zod_1.z.any()),
+    attributeValues: validation_1.AttributeValuesSchema,
     position: zod_1.z.number(),
 });
 /**

package/dist/templates-preview/templatesPreviewInterfaces.d.ts

@@ -10,7 +10,7 @@ interface ITemplatesPreviewApi {
      * @returns {ITemplatesPreviewEntity[]} A promise resolving to an array of template preview entities or an error.
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      */
-    getTemplatePreviews(langCode: string): Promise<ITemplatesPreviewEntity[] | IError>;
+    getTemplatePreviews(langCode?: string): Promise<ITemplatesPreviewEntity[] | IError>;
     /**
      * Retrieves a specific template preview object by its marker.
      * @handleName getTemplatePreviewByMarker
@@ -20,7 +20,7 @@ interface ITemplatesPreviewApi {
      * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
      * @description This method retrieves a specific template preview object by its marker.
      */
-    getTemplatePreviewByMarker(marker: string, langCode: string): Promise<ITemplatesPreviewEntity | IError>;
+    getTemplatePreviewByMarker(marker: string, langCode?: string): Promise<ITemplatesPreviewEntity | IError>;
 }
 /**
  * The `ITemplatesPreview` interface defines the structure of template preview entities.

package/esm/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/esm/admins/adminsSchemas.js

@@ -3,18 +3,11 @@
  * @description Zod schemas for validating admins-related API responses
  */
 import { z } from 'zod';
+import { AttributeValuesSchema } from '../base/validation.js';
 /**
  * Admin entity schema
  * Includes all fields returned by the API
  */
-const AttributeValueSchema = z.object({
-    type: z.string(),
-    value: z.unknown(),
-    position: z.number().optional(),
-    additionalFields: z
-        .union([z.record(z.string(), z.unknown()), z.array(z.unknown())])
-        .optional(),
-});
 export const AdminEntitySchema = z.object({
     id: z.number(),
     attributeSetId: z.number().nullable(),
@@ -22,7 +15,7 @@ export const AdminEntitySchema = z.object({
     attributeSetIdentifier: z.string().nullable(),
     position: z.number().nullable(),
     isSync: z.boolean(),
-    attributeValues: z.record(z.string(), z.record(z.string(), AttributeValueSchema)),
+    attributeValues: AttributeValuesSchema,
     moduleFormConfigs: z.array(z.any()).optional(),
     distance: z.number().optional(),
 });

package/esm/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/esm/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/esm/base/attributes.d.ts

@@ -0,0 +1,105 @@
+import type { IAttributeFile, IAttributeValue, IFileAttributeValue, IListAttributeValue, INumberAttributeValue, IStringAttributeValue } from './utils.js';
+/**
+ * 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/esm/base/attributes.js

@@ -0,0 +1,163 @@
+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
+ * }
+ * ```
+ */
+export 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);
+ * ```
+ */
+export 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];
+ * ```
+ */
+export 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).
+ */
+export 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).
+ */
+export 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.
+ */
+export 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;
+ * ```
+ */
+export 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;
+}