oneentry 1.0.166 → 1.0.167

package/esm/user-groups/userGroupsApi.d.ts

@@ -0,0 +1,81 @@
+import AsyncModules from '../base/asyncModules.js';
+import type StateModule from '../base/stateModule.js';
+import type { IError } from '../base/utils.js';
+import type { IUserGroupEntity, IUserGroups } from './userGroupsInterfaces.js';
+/**
+ * Controllers for working with user groups
+ * @handle /api/content/user-groups
+ * @class UserGroupsApi
+ * @augments AsyncModules
+ * @implements {IUserGroups}
+ * @description User groups form a tree — a group may have a parent and children. The flat list
+ * comes from `getUserGroups`, the top level from `getRootUserGroups`, and the tree is walked
+ * downwards with `getChildUserGroupsByMarker`.
+ * @example
+ * const { UserGroups } = defineOneEntry('your-url', { token: 'your-app-token' });
+ * const roots = await UserGroups.getRootUserGroups();
+ */
+export default class UserGroupsApi extends AsyncModules implements IUserGroups {
+    protected state: StateModule;
+    protected _url: string;
+    /**
+     * Constructor
+     * @param {StateModule} state - StateModule instance
+     * @description Constructor initializes the UserGroupsApi with a given state.
+     */
+    constructor(state: StateModule);
+    /**
+     * Get all user group objects.
+     * @handleName getUserGroups
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity[] | IError>} Returns an array of user group objects.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Returns every group as a flat array, regardless of nesting.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getUserGroups getUserGroups} documentation.
+     */
+    getUserGroups(langCode?: string): Promise<IUserGroupEntity[] | IError>;
+    /**
+     * Get all top-level user group objects.
+     * @handleName getRootUserGroups
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity[] | IError>} Returns an array of user group objects with `parentId: null`.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Returns the groups of the top level — those without a parent.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getRootUserGroups getRootUserGroups} documentation.
+     */
+    getRootUserGroups(langCode?: string): Promise<IUserGroupEntity[] | IError>;
+    /**
+     * Get a single user group object by its identifier.
+     * @handleName getUserGroupById
+     * @param {number} id - Identifier of the user group. Example: 1.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity | IError>} Returns a single user group object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get a single user group object by its identifier.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getUserGroupById getUserGroupById} documentation.
+     */
+    getUserGroupById(id: number, langCode?: string): Promise<IUserGroupEntity | IError>;
+    /**
+     * Get a single user group object by its marker.
+     * @handleName getUserGroupByMarker
+     * @param {string} marker - Text identifier of the user group. Example: "guest".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity | IError>} Returns a single user group object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get a single user group object by its marker.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getUserGroupByMarker getUserGroupByMarker} documentation.
+     */
+    getUserGroupByMarker(marker: string, langCode?: string): Promise<IUserGroupEntity | IError>;
+    /**
+     * Get the child groups of a user group.
+     * @handleName getChildUserGroupsByMarker
+     * @param {string} marker - Text identifier of the parent user group. Example: "guest".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity[] | IError>} Returns an array of child user group objects, empty when the group has none.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get the child groups of a user group by the parent marker. The nesting is walked
+     * with this method rather than through `parentId`.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getChildUserGroupsByMarker getChildUserGroupsByMarker} documentation.
+     */
+    getChildUserGroupsByMarker(marker: string, langCode?: string): Promise<IUserGroupEntity[] | IError>;
+}

package/esm/user-groups/userGroupsApi.js

@@ -0,0 +1,106 @@
+import AsyncModules from '../base/asyncModules.js';
+import createSchemaLoader from '../base/lazySchema.js';
+const schema = createSchemaLoader(() => import('./userGroupsSchemas.js'));
+/**
+ * Controllers for working with user groups
+ * @handle /api/content/user-groups
+ * @class UserGroupsApi
+ * @augments AsyncModules
+ * @implements {IUserGroups}
+ * @description User groups form a tree — a group may have a parent and children. The flat list
+ * comes from `getUserGroups`, the top level from `getRootUserGroups`, and the tree is walked
+ * downwards with `getChildUserGroupsByMarker`.
+ * @example
+ * const { UserGroups } = defineOneEntry('your-url', { token: 'your-app-token' });
+ * const roots = await UserGroups.getRootUserGroups();
+ */
+export default class UserGroupsApi extends AsyncModules {
+    /**
+     * Constructor
+     * @param {StateModule} state - StateModule instance
+     * @description Constructor initializes the UserGroupsApi with a given state.
+     */
+    constructor(state) {
+        super(state);
+        this._url = state.url + '/api/content/user-groups';
+    }
+    /**
+     * Get all user group objects.
+     * @handleName getUserGroups
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity[] | IError>} Returns an array of user group objects.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Returns every group as a flat array, regardless of nesting.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getUserGroups getUserGroups} documentation.
+     */
+    async getUserGroups(langCode = this.state.lang) {
+        const result = await this._fetchGet(`/?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('UserGroupsResponseSchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Get all top-level user group objects.
+     * @handleName getRootUserGroups
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity[] | IError>} Returns an array of user group objects with `parentId: null`.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Returns the groups of the top level — those without a parent.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getRootUserGroups getRootUserGroups} documentation.
+     */
+    async getRootUserGroups(langCode = this.state.lang) {
+        const result = await this._fetchGet(`/root?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('UserGroupsResponseSchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Get a single user group object by its identifier.
+     * @handleName getUserGroupById
+     * @param {number} id - Identifier of the user group. Example: 1.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity | IError>} Returns a single user group object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get a single user group object by its identifier.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getUserGroupById getUserGroupById} documentation.
+     */
+    async getUserGroupById(id, langCode = this.state.lang) {
+        const result = await this._fetchGet(`/${id}?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('UserGroupEntitySchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Get a single user group object by its marker.
+     * @handleName getUserGroupByMarker
+     * @param {string} marker - Text identifier of the user group. Example: "guest".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity | IError>} Returns a single user group object.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get a single user group object by its marker.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getUserGroupByMarker getUserGroupByMarker} documentation.
+     */
+    async getUserGroupByMarker(marker, langCode = this.state.lang) {
+        const result = await this._fetchGet(`/marker/${marker}?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('UserGroupEntitySchema'));
+        return this._normalizeData(validated, langCode);
+    }
+    /**
+     * Get the child groups of a user group.
+     * @handleName getChildUserGroupsByMarker
+     * @param {string} marker - Text identifier of the parent user group. Example: "guest".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {Promise<IUserGroupEntity[] | IError>} Returns an array of child user group objects, empty when the group has none.
+     * @throws {IError} When isShell=false and an error occurs during the fetch
+     * @description Get the child groups of a user group by the parent marker. The nesting is walked
+     * with this method rather than through `parentId`.
+     * @see {@link https://js-sdk.oneentry.cloud/docs/user-groups/getChildUserGroupsByMarker getChildUserGroupsByMarker} documentation.
+     */
+    async getChildUserGroupsByMarker(marker, langCode = this.state.lang) {
+        const result = await this._fetchGet(`/marker/${marker}/children?langCode=${langCode}`);
+        // Validate response if validation is enabled
+        const validated = await this._validateResponse(result, schema('UserGroupsResponseSchema'));
+        return this._normalizeData(validated, langCode);
+    }
+}

package/esm/user-groups/userGroupsInterfaces.d.ts

@@ -0,0 +1,100 @@
+import type { IAttributeValues, IError, ILocalizeInfo } from '../base/utils.js';
+/**
+ * The `IUserGroups` interface defines methods for reading user groups.
+ * @interface IUserGroups
+ * @description User groups form a tree: a group may have a parent and children, and the tree is
+ * walked through the marker-based methods. Every method requires the project token.
+ */
+interface IUserGroups {
+    /**
+     * Get all user group objects.
+     * @handleName getUserGroups
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {IUserGroupEntity[]} Returns an array of user group objects.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method gets all user group objects, flat, regardless of nesting.
+     */
+    getUserGroups(langCode?: string): Promise<IUserGroupEntity[] | IError>;
+    /**
+     * Get all top-level user group objects.
+     * @handleName getRootUserGroups
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {IUserGroupEntity[]} Returns an array of user group objects with `parentId: null`.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method gets the user groups of the top level — those without a parent.
+     */
+    getRootUserGroups(langCode?: string): Promise<IUserGroupEntity[] | IError>;
+    /**
+     * Get a single user group object by its identifier.
+     * @handleName getUserGroupById
+     * @param {number} id - Identifier of the user group. Example: 1.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {IUserGroupEntity} Returns a single user group object.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method gets a single user group object by its identifier.
+     */
+    getUserGroupById(id: number, langCode?: string): Promise<IUserGroupEntity | IError>;
+    /**
+     * Get a single user group object by its marker.
+     * @handleName getUserGroupByMarker
+     * @param {string} marker - Text identifier of the user group. Example: "guest".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {IUserGroupEntity} Returns a single user group object.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method gets a single user group object by its marker.
+     */
+    getUserGroupByMarker(marker: string, langCode?: string): Promise<IUserGroupEntity | IError>;
+    /**
+     * Get the child groups of a user group.
+     * @handleName getChildUserGroupsByMarker
+     * @param {string} marker - Text identifier of the parent user group. Example: "guest".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {IUserGroupEntity[]} Returns an array of child user group objects, empty when the group has none.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method gets the child groups of a user group by the parent marker.
+     */
+    getChildUserGroupsByMarker(marker: string, langCode?: string): Promise<IUserGroupEntity[] | IError>;
+}
+/**
+ * The `IUserGroupEntity` interface defines the structure of a user group object.
+ * @interface IUserGroupEntity
+ * @property {number} id - Identifier of the user group. Example: 1.
+ * @property {number} depth - Nesting depth relative to the parent. Example: 0.
+ * @property {number | null} parentId - Identifier of the parent group, `null` for a top-level group. Example: null.
+ * @property {ILocalizeInfo} localizeInfos - Title of the group, taking localization into account.
+ * @property {boolean} isVisible - Visibility flag. Example: true.
+ * @property {string} childrenCount - Number of child groups. The API sends it as a **string**, not a number. Example: "0".
+ * @property {string} identifier - Text identifier (marker) of the group. Example: "guest".
+ * @property {boolean} isSync - Synchronization flag. Example: false.
+ * @property {IAttributeValues} attributeValues - Attribute values of the group.
+ * @property {number} [version] - Version of the object. Not present on every stand. Example: 0.
+ * @description Structure of a user group object.
+ * @example
+ * ```json
+ * {
+ *   "id": 1,
+ *   "depth": 0,
+ *   "parentId": null,
+ *   "localizeInfos": { "title": "Guest" },
+ *   "isVisible": true,
+ *   "childrenCount": "0",
+ *   "identifier": "guest",
+ *   "isSync": false,
+ *   "attributeValues": {},
+ *   "version": 0
+ * }
+ * ```
+ */
+interface IUserGroupEntity {
+    id: number;
+    depth: number;
+    parentId: number | null;
+    localizeInfos: ILocalizeInfo;
+    isVisible: boolean;
+    childrenCount: string;
+    identifier: string;
+    isSync: boolean;
+    attributeValues: IAttributeValues;
+    version?: number;
+}
+export type { IUserGroupEntity, IUserGroups };

package/esm/user-groups/userGroupsInterfaces.js

@@ -0,0 +1 @@
+export {};

package/esm/user-groups/userGroupsSchemas.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Validation schemas for UserGroups module
+ * @description Zod schemas for validating user-group API responses
+ */
+import { z } from 'zod';
+/**
+ * User group entity schema.
+ *
+ * `childrenCount` is a **string** here because that is what the API sends
+ * (`"0"`), even though the platform DTO declares it a number. The schema
+ * describes the raw response, so it follows the response.
+ */
+export declare const UserGroupEntitySchema: z.ZodObject<{
+    id: z.ZodNumber;
+    depth: z.ZodNumber;
+    parentId: z.ZodNullable<z.ZodNumber>;
+    localizeInfos: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodObject<{
+        title: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        menuTitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>, z.ZodObject<{
+        title: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        menuTitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+    isVisible: z.ZodBoolean;
+    childrenCount: z.ZodString;
+    identifier: z.ZodString;
+    isSync: z.ZodBoolean;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    version: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * User groups response schema (array of groups)
+ */
+export declare const UserGroupsResponseSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodNumber;
+    depth: z.ZodNumber;
+    parentId: z.ZodNullable<z.ZodNumber>;
+    localizeInfos: z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodObject<{
+        title: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        menuTitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>, z.ZodObject<{
+        title: z.ZodString;
+        content: z.ZodOptional<z.ZodString>;
+        menuTitle: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>;
+    isVisible: z.ZodBoolean;
+    childrenCount: z.ZodString;
+    identifier: z.ZodString;
+    isSync: z.ZodBoolean;
+    attributeValues: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    version: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>>;

package/esm/user-groups/userGroupsSchemas.js

@@ -0,0 +1,32 @@
+/**
+ * Validation schemas for UserGroups module
+ * @description Zod schemas for validating user-group API responses
+ */
+import { z } from 'zod';
+import { AttributeValuesSchema, LocalizeInfoSchema } from '../base/validation.js';
+/**
+ * User group entity schema.
+ *
+ * `childrenCount` is a **string** here because that is what the API sends
+ * (`"0"`), even though the platform DTO declares it a number. The schema
+ * describes the raw response, so it follows the response.
+ */
+export const UserGroupEntitySchema = z.object({
+    id: z.number(),
+    depth: z.number(),
+    parentId: z.number().nullable(),
+    localizeInfos: z.union([
+        z.record(z.string(), LocalizeInfoSchema),
+        LocalizeInfoSchema,
+    ]),
+    isVisible: z.boolean(),
+    childrenCount: z.string(),
+    identifier: z.string(),
+    isSync: z.boolean(),
+    attributeValues: AttributeValuesSchema,
+    version: z.number().optional(),
+});
+/**
+ * User groups response schema (array of groups)
+ */
+export const UserGroupsResponseSchema = z.array(UserGroupEntitySchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oneentry",
-  "version": "1.0.166",
+  "version": "1.0.167",
   "description": "OneEntry NPM package",
   "main": "dist/index.js",
   "module": "esm/index.js",
@@ -48,7 +48,7 @@
   },
   "scripts": {
     "prepublishOnly": "node ../scripts/smoke-pack.js --files-only",
-    "postpublish": "node ../scripts/verify-published.js --named defineOneEntry --expect 1.0.166"
+    "postpublish": "node ../scripts/verify-published.js --named defineOneEntry --expect 1.0.167"
   },
   "sideEffects": false,
   "files": [