oneentry 1.0.159 → 1.0.161

package/esm/users/usersInterfaces.d.ts

@@ -0,0 +1,419 @@
+import type { IAuthData, IAuthFormData, INotificationData } from '../auth-provider/authProvidersInterfaces.js';
+import type { IError, IRating } from '../base/utils.js';
+import type { IFormConfig } from '../forms/formsInterfaces.js';
+import type { FormDataType } from '../forms-data/formsDataInterfaces.js';
+/**
+ * Interface representing user-related operations.
+ * @interface IUsersApi
+ * @description This interface defines methods for managing user data and handling Firebase Cloud Messaging tokens.
+ */
+interface IUsersApi {
+    /**
+     * Retrieves the data of an authorized user.
+     * @handleName getUser
+     * @param {string} [langCode] - Optional language code for localization. Default: "en_US".
+     * @returns {IUserEntity} A promise resolving to the user entity or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    getUser(langCode?: string): Promise<IUserEntity | IError>;
+    /**
+     * Updating a single user object.
+     * @handleName updateUser
+     * @param {IUserBody} body - Request body.
+     * @example
+        {
+          "formIdentifier": "reg",
+          "authData": [
+            {
+              "marker": "email_reg",
+              "value": "your-email@oneentery.cloud"
+            },
+            {
+              "marker": "password_reg",
+              "value": "12345"
+            }
+          ],
+          "formData": [
+            {
+              "marker": "last_name",
+              "type": "string",
+              "value": "Username"
+            }
+          ],
+          "notificationData": {
+            "email": "example@oneentry.cloud",
+            "phonePush": ["+99999999999"],
+            "phoneSMS": "+99999999999"
+          },
+          "state": {}
+        }
+     * @param {string} body.formIdentifier - Identifies the registration form being used. Example: "reg_form".
+     * @param {string} body.authData - Contains authentication credentials for the user. Example:
+     * @example
+        [
+          {
+            "marker": "email_reg",
+            "value": "example@oneentry.cloud"
+          },
+          {
+            "marker": "password_reg",
+            "value": "password"
+          }
+        ]
+     * @param {string} body.authData[index].marker - Identifies the field being used. Example: "email_reg".
+     * @param {string} body.authData[index].value - Contains the value of the field. Example: "example@oneentry.cloud".
+     * @param {string} body.formData - Contains additional data for the user.
+     * @example
+        [
+          {
+            "marker": "last_name",
+            "type": "string",
+            "value": "Username"
+          }
+        ]
+     * @param {string} body.formData[index].marker - The marker of the field. Example: "last_name".
+     * @param {string} body.formData[index].type - The type of the field. Example: "string".
+     * @param {string} body.formData[index].value - The value of the field. Example: "Username".
+     * @param {string} body.notificationData - The notification data.
+     * @example
+        {
+          "email": "example@oneentry.cloud",
+          "phonePush": ["+99999999999"],
+          "phoneSMS": "+99999999999"
+        }
+     * @param {string} body.notificationData.email - The email address of the user. Example: "example@oneentry.cloud".
+     * @param {string} body.notificationData.phonePush - An array of phone numbers for push notifications. Example: ["+99999999999"].
+     * @param {string} body.notificationData.phoneSMS - The phone number for SMS notifications. Example: "+99999999999".
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @returns {boolean} Returns `true` if the user object was successfully updated; otherwise, returns an error object.
+     * @throws {IError} If there is an error during the fetch operation, it will return an error object.
+     * @description This method updates the user's data. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     * @see For more information about {@link https://doc.oneentry.cloud/docs/forms/create-form registration forms}, see the documentation in the  {@link https://doc.oneentry.cloud/docs/forms/create-form forms configuration section}.
+     */
+    updateUser(body: IUserBody, langCode?: string): Promise<boolean | IError>;
+    /**
+     * Archiving one user object (marked for deletion).
+     * @handleName archiveUser
+     * @returns {boolean} A promise resolving to true if successful, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method archives a user object (marks it for deletion). This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    archiveUser(): Promise<boolean | IError>;
+    /**
+     * Deletes the user from the system.
+     * @handleName deleteUser
+     * @returns {boolean} A promise resolving to true if successful, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method deletes the user from the system. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    deleteUser(): Promise<boolean | IError>;
+    /**
+     * Adds an FCM token for sending push notifications.
+     * @handleName addFCMToken
+     * @param {string} token - The FCM token to be added. Example: "fcm_token_1234567890abcdefg".
+     * @returns {boolean} A promise resolving to true if successful, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method adds an FCM token for sending push notifications. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    addFCMToken(token: string): Promise<boolean | IError>;
+    /**
+     * Deletes an existing FCM token.
+     * @handleName deleteFCMToken
+     * @param {string} token - The FCM token to be deleted. Example: "fcm_token_1234567890abcdefg".
+     * @returns {boolean} A promise resolving to true if successful, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method deletes an existing FCM token. This method requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    deleteFCMToken(token: string): Promise<boolean | IError>;
+    /**
+     * Get the current user's or guest's cart.
+     * @handleName getCart
+     * @returns {Promise<ICartResponse | IError>} A promise resolving to the cart with its items and total, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    getCart(): Promise<ICartResponse | IError>;
+    /**
+     * Replace the current user's or guest's cart.
+     * @handleName setCart
+     * @param {ICartSet} body - New cart contents. Example: `{ items: [{ productId: 1, qty: 2 }] }`.
+     * @returns {Promise<ICartResponse | IError>} A promise resolving to the updated cart, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    setCart(body: ICartSet): Promise<ICartResponse | IError>;
+    /**
+     * Add an item to the cart (or update qty of an existing one).
+     * @handleName addCartItem
+     * @param {ICartAddItem} body - Item to add. Example: `{ productId: 1, qty: 2 }`.
+     * @returns {Promise<ICartResponse | IError>} A promise resolving to the updated cart, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    addCartItem(body: ICartAddItem): Promise<ICartResponse | IError>;
+    /**
+     * Remove an item from the cart.
+     * @handleName removeCartItem
+     * @param {number} productId - Product identifier. Example: 12345.
+     * @returns {Promise<ICartResponse | IError>} A promise resolving to the updated cart, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    removeCartItem(productId: number): Promise<ICartResponse | IError>;
+    /**
+     * Get the current user's or guest's wishlist.
+     * @handleName getWishlist
+     * @returns {Promise<IWishlistResponse | IError>} A promise resolving to the wishlist with its items and total, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    getWishlist(): Promise<IWishlistResponse | IError>;
+    /**
+     * Replace the current user's or guest's wishlist.
+     * @handleName setWishlist
+     * @param {IWishlistSet} body - New wishlist contents. Example: `{ items: [{ productId: 1 }] }`.
+     * @returns {Promise<IWishlistResponse | IError>} A promise resolving to the updated wishlist, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    setWishlist(body: IWishlistSet): Promise<IWishlistResponse | IError>;
+    /**
+     * Add an item to the wishlist.
+     * @handleName addWishlistItem
+     * @param {IWishlistAddItem} body - Item to add. Example: `{ productId: 1 }`.
+     * @returns {Promise<IWishlistResponse | IError>} A promise resolving to the updated wishlist, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    addWishlistItem(body: IWishlistAddItem): Promise<IWishlistResponse | IError>;
+    /**
+     * Remove an item from the wishlist.
+     * @handleName removeWishlistItem
+     * @param {number} productId - Product identifier. Example: 12345.
+     * @returns {Promise<IWishlistResponse | IError>} A promise resolving to the updated wishlist, or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method requires user authorization (or a guest context).
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    removeWishlistItem(productId: number): Promise<IWishlistResponse | IError>;
+    /**
+     * Semantic (vector) search for users.
+     * @handleName getUsersByVectorSearch
+     * @param {IUsersVectorSearch} body - Vector search body. Example: `{ queryText: "john" }`.
+     * @param {string} [langCode] - Language code. Default: "en_US".
+     * @param {number} [offset] - Parameter for pagination. Default: 0.
+     * @param {number} [limit] - Parameter for pagination. Default: 30.
+     * @returns {Promise<IUsersResponse | IError>} A promise resolving to a users response (items + total), or an error.
+     * @throws {IError} - If there is an error during the fetch operation, it will return an error object.
+     * @description This method performs a semantic (vector) search for users. It requires user authorization.
+     * @see For more information about configuring the {@link https://js-sdk.oneentry.cloud/docs/category/authprovider authorization module}, see the documentation in the  {@link https://js-sdk.oneentry.cloud/docs/category/authprovider configuration settings section of the SDK}.
+     */
+    getUsersByVectorSearch(body: IUsersVectorSearch, langCode?: string, offset?: number, limit?: number): Promise<IUsersResponse | IError>;
+}
+/**
+ * Body for semantic (vector) user search.
+ * @interface IUsersVectorSearch
+ * @property {string} queryText - Natural-language search query. Example: "john".
+ * @property {number} [vectorDistanceThreshold] - Override of the cosine distance threshold (0..2). Example: 0.3.
+ * @property {number} [maxHits] - Top-K candidates fetched before pagination. Default: 100. Max: 500. Example: 10.
+ * @property {boolean} [debug] - When true, each returned item gets a `distance` field. Example: false.
+ * @description Body for the users vector/search endpoint.
+ */
+interface IUsersVectorSearch {
+    queryText: string;
+    vectorDistanceThreshold?: number;
+    maxHits?: number;
+    debug?: boolean;
+}
+/**
+ * @interface IUsersResponse
+ * @property {IUserEntity[]} items - Array of found user objects.
+ * @property {number} total - Total number of found records. Example: 100.
+ * @description This interface defines the structure of a response containing multiple user entities, including the total count and an array of user items.
+ */
+interface IUsersResponse {
+    items: IUserEntity[];
+    total: number;
+}
+/**
+ * @interface IUserEntity
+ * @property {number} id - Object identifier. Example: 12345.
+ * @property {string} identifier - Text identifier for record field. Example: "user_12345".
+ * @property {string} authProviderIdentifier - Text identifier of the authentication provider. Example: "auth_provider_12345".
+ * @property {FormDataType[]} formData - Array of data form objects with the following values.
+ * @example
+    [
+      {
+        "marker": "last_name",
+        "type": "string",
+        "value": "Username"
+      }
+    ]
+ * @property {string} formIdentifier - Text identifier of the form. Example: "form_12345".
+ * @property {string} total - Total value. Example: "0".
+ * @property {Array<string | number>} groups - Array of user groups.
+ * @example
+    [
+      "group_1",
+      "group_2"
+    ]
+ * @property {object} state - Object containing additional user state information.
+ * @example
+    {
+      "key": "value"
+    }
+ * @property {Array<IFormConfig>} [moduleFormConfigs] - Optional array of form configuration objects associated with the user.
+ * @property {IRating} [rating] - Rating data.
+ * @description Represents a user entity with various properties, including identifiers, form data, and user groups.
+ */
+interface IUserEntity {
+    id: number;
+    identifier: string;
+    authProviderIdentifier: string;
+    formData: FormDataType[];
+    formIdentifier: string;
+    total: string;
+    groups: Array<string | number>;
+    state: Record<string, unknown>;
+    moduleFormConfigs?: Array<IFormConfig>;
+    rating?: IRating;
+}
+/**
+ * @interface IUserBody
+ * @property {string} formIdentifier - Text identifier of the form. Example: "form_12345".
+ * @property {string} [langCode] - Language code for localization. Default: "en_US".
+ * @property {IAuthData[]} [authData] - Array of authentication data objects with markers and values.
+ * @example
+    [
+      {
+        "marker": "password",
+        "value": "12345"
+      }
+    ]
+ * @property {IAuthFormData | IAuthFormData[]} [formData] - Form data object or array of form data objects.
+ * @example
+    [
+      {
+        "marker": "first_name",
+        "type": "string",
+        "value": "John"
+      },
+      {
+        "marker": "last_name",
+        "type": "string",
+        "value": "Doe"
+      }
+    ]
+ * @property {object} [notificationData] - Object containing notification data, including email and phone information.
+ * @example
+    {
+      "email": "example@oneentry.cloud",
+      "phonePush": ["+99999999999"],
+      "phoneSMS": "+99999999999"
+    }
+ * @property {object} [state] - Object containing additional state information.
+ * @example
+    {
+      "key": "value"
+    }
+ * @description Represents the body of a user request, including form identifiers, authentication data, form data, notification data, and state information.
+ */
+interface IUserBody {
+    formIdentifier: string;
+    langCode?: string;
+    authData?: IAuthData[];
+    formData?: IAuthFormData | IAuthFormData[];
+    notificationData?: INotificationData;
+    state?: Record<string, unknown>;
+}
+/**
+ * @interface ICartItem
+ * @property {number} productId - Product identifier. Example: 1.
+ * @property {number} qty - Quantity of the product in the cart. Example: 2.
+ * @property {string} [addedAt] - ISO date when the item was added. Example: "2026-05-30T10:00:00.000Z".
+ * @description A single cart item.
+ */
+interface ICartItem {
+    productId: number;
+    qty: number;
+    addedAt?: string;
+}
+/**
+ * @interface ICartResponse
+ * @property {ICartItem[]} items - Cart items.
+ * @property {number} total - Total number of items in the cart. Example: 3.
+ * @description The user's or guest's cart.
+ */
+interface ICartResponse {
+    items: ICartItem[];
+    total: number;
+}
+/**
+ * @interface ICartSet
+ * @property {ICartItem[]} items - New cart items. Example: `[{ productId: 1, qty: 2 }]`.
+ * @description Body for replacing the whole cart.
+ */
+interface ICartSet {
+    items: ICartItem[];
+}
+/**
+ * @interface ICartAddItem
+ * @property {number} productId - Product identifier. Example: 1.
+ * @property {number} qty - Quantity to add. Example: 2.
+ * @description Body for adding a single item to the cart.
+ */
+interface ICartAddItem {
+    productId: number;
+    qty: number;
+}
+/**
+ * @interface IWishlistItem
+ * @property {number} productId - Product identifier. Example: 1.
+ * @property {string} [addedAt] - ISO date when the item was added. Example: "2026-05-30T10:00:00.000Z".
+ * @description A single wishlist item.
+ */
+interface IWishlistItem {
+    productId: number;
+    addedAt?: string;
+}
+/**
+ * @interface IWishlistResponse
+ * @property {IWishlistItem[]} items - Wishlist items.
+ * @property {number} total - Total number of items in the wishlist. Example: 3.
+ * @description The user's or guest's wishlist.
+ */
+interface IWishlistResponse {
+    items: IWishlistItem[];
+    total: number;
+}
+/**
+ * @interface IWishlistSet
+ * @property {IWishlistItem[]} items - New wishlist items. Example: `[{ productId: 1 }]`.
+ * @description Body for replacing the whole wishlist.
+ */
+interface IWishlistSet {
+    items: IWishlistItem[];
+}
+/**
+ * @interface IWishlistAddItem
+ * @property {number} productId - Product identifier. Example: 1.
+ * @description Body for adding a single item to the wishlist.
+ */
+interface IWishlistAddItem {
+    productId: number;
+}
+export type { ICartAddItem, ICartItem, ICartResponse, ICartSet, IUserBody, IUserEntity, IUsersApi, IUsersResponse, IUsersVectorSearch, IWishlistAddItem, IWishlistItem, IWishlistResponse, IWishlistSet, };

package/esm/users/usersInterfaces.js

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

package/esm/users/usersSchemas.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Validation schemas for Users module
+ * @description Zod schemas for validating users-related API responses
+ */
+import { z } from 'zod';
+/**
+ * User response schema (extends base UserEntitySchema)
+ * formData can be array or object (inherited from UserEntitySchema)
+ */
+export declare const UserResponseSchema: z.ZodObject<{
+    id: z.ZodNumber;
+    identifier: z.ZodString;
+    authProviderIdentifier: z.ZodString;
+    formData: z.ZodUnion<readonly [z.ZodArray<z.ZodAny>, z.ZodRecord<z.ZodString, z.ZodAny>]>;
+    formIdentifier: z.ZodString;
+    total: z.ZodString;
+    groups: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    state: z.ZodRecord<z.ZodString, z.ZodAny>;
+    moduleFormConfigs: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+    rating: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+/**
+ * Update user response schema (returns true on success)
+ */
+export declare const UpdateUserResponseSchema: z.ZodBoolean;
+/**
+ * Delete user response schema
+ */
+export declare const DeleteUserResponseSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    message: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Cart item schema
+ * @description Schema for a single cart item
+ */
+export declare const CartItemSchema: z.ZodObject<{
+    productId: z.ZodNumber;
+    qty: z.ZodNumber;
+    addedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Cart response schema
+ * @description Schema for the user's or guest's cart
+ */
+export declare const CartResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        productId: z.ZodNumber;
+        qty: z.ZodNumber;
+        addedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+}, z.core.$strip>;
+/**
+ * Wishlist item schema
+ * @description Schema for a single wishlist item
+ */
+export declare const WishlistItemSchema: z.ZodObject<{
+    productId: z.ZodNumber;
+    addedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Wishlist response schema
+ * @description Schema for the user's or guest's wishlist
+ */
+export declare const WishlistResponseSchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        productId: z.ZodNumber;
+        addedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    total: z.ZodNumber;
+}, z.core.$strip>;

package/esm/users/usersSchemas.js

@@ -0,0 +1,55 @@
+/**
+ * Validation schemas for Users module
+ * @description Zod schemas for validating users-related API responses
+ */
+import { z } from 'zod';
+import { UserEntitySchema } from '../base/validation.js';
+/**
+ * User response schema (extends base UserEntitySchema)
+ * formData can be array or object (inherited from UserEntitySchema)
+ */
+export const UserResponseSchema = UserEntitySchema;
+/**
+ * Update user response schema (returns true on success)
+ */
+export const UpdateUserResponseSchema = z.boolean();
+/**
+ * Delete user response schema
+ */
+export const DeleteUserResponseSchema = z.object({
+    success: z.boolean(),
+    message: z.string().optional(),
+});
+/**
+ * Cart item schema
+ * @description Schema for a single cart item
+ */
+export const CartItemSchema = z.object({
+    productId: z.number(),
+    qty: z.number(),
+    addedAt: z.string().optional(),
+});
+/**
+ * Cart response schema
+ * @description Schema for the user's or guest's cart
+ */
+export const CartResponseSchema = z.object({
+    items: z.array(CartItemSchema),
+    total: z.number(),
+});
+/**
+ * Wishlist item schema
+ * @description Schema for a single wishlist item
+ */
+export const WishlistItemSchema = z.object({
+    productId: z.number(),
+    addedAt: z.string().optional(),
+});
+/**
+ * Wishlist response schema
+ * @description Schema for the user's or guest's wishlist
+ */
+export const WishlistResponseSchema = z.object({
+    items: z.array(WishlistItemSchema),
+    total: z.number(),
+});

package/esm/web-socket/lazySocket.d.ts

@@ -0,0 +1,18 @@
+import type { Socket } from 'socket.io-client';
+/**
+ * Wraps a not-yet-loaded Socket.io socket in a synchronous stand-in.
+ *
+ * `WS.connect()` is synchronous and returns a `Socket`, so `socket.io-client` would have to
+ * be imported statically — putting ~41 kB into every bundle, including those that never open
+ * a socket. This keeps the signature by returning a proxy immediately: calls made on it are
+ * queued and replayed onto the real socket as soon as the chunk resolves, and every later
+ * call passes straight through.
+ * @param {() => Promise<Socket>} createSocket - Loads Socket.io and creates the socket.
+ * @returns {Socket} Stand-in usable exactly like the socket it will become.
+ * @description Listener registration is what matters for ordering, and it is safe: the queue is
+ * replayed in the same tick the socket is created, before the connection can deliver anything.
+ * The one visible difference is that methods returning a value (e.g. `listeners()`) cannot answer
+ * before the chunk arrives — they return the proxy instead. Reading state (`id`, `connected`, …)
+ * is accurate, and awaiting `socket.io` or other nested objects is only possible once loaded.
+ */
+export default function createLazySocket(createSocket: () => Promise<Socket>): Socket;

package/esm/web-socket/lazySocket.js

@@ -0,0 +1,67 @@
+/**
+ * Properties readable before the real socket exists.
+ * @description Their values match what Socket.io itself reports for a socket that
+ * has been created but has not connected yet, so reading them early is not a lie.
+ */
+const PENDING_STATE = {
+    id: undefined,
+    connected: false,
+    disconnected: true,
+    active: false,
+    recovered: false,
+};
+/**
+ * Wraps a not-yet-loaded Socket.io socket in a synchronous stand-in.
+ *
+ * `WS.connect()` is synchronous and returns a `Socket`, so `socket.io-client` would have to
+ * be imported statically — putting ~41 kB into every bundle, including those that never open
+ * a socket. This keeps the signature by returning a proxy immediately: calls made on it are
+ * queued and replayed onto the real socket as soon as the chunk resolves, and every later
+ * call passes straight through.
+ * @param {() => Promise<Socket>} createSocket - Loads Socket.io and creates the socket.
+ * @returns {Socket} Stand-in usable exactly like the socket it will become.
+ * @description Listener registration is what matters for ordering, and it is safe: the queue is
+ * replayed in the same tick the socket is created, before the connection can deliver anything.
+ * The one visible difference is that methods returning a value (e.g. `listeners()`) cannot answer
+ * before the chunk arrives — they return the proxy instead. Reading state (`id`, `connected`, …)
+ * is accurate, and awaiting `socket.io` or other nested objects is only possible once loaded.
+ */
+export default function createLazySocket(createSocket) {
+    let socket;
+    const queued = [];
+    const loading = createSocket().then((created) => {
+        // Replay before returning: the connection cannot emit anything until this tick ends,
+        // so no event registered through the proxy can be missed.
+        for (const { method, args } of queued) {
+            created[method](...args);
+        }
+        queued.length = 0;
+        socket = created;
+        return created;
+    });
+    // A failed chunk load must not surface as an unhandled rejection
+    loading.catch((error) => {
+        // eslint-disable-next-line no-undef, no-console
+        console.error('OneEntry SDK: failed to load socket.io-client', error);
+    });
+    const proxy = new Proxy({}, {
+        get(_target, property) {
+            if (socket) {
+                const value = socket[property];
+                return typeof value === 'function' ? value.bind(socket) : value;
+            }
+            // Never look thenable: returning a function for `then` would make `await socket` hang
+            if (property === 'then' || typeof property === 'symbol') {
+                return undefined;
+            }
+            if (property in PENDING_STATE) {
+                return PENDING_STATE[property];
+            }
+            return (...args) => {
+                queued.push({ method: property, args });
+                return proxy;
+            };
+        },
+    });
+    return proxy;
+}

package/esm/web-socket/wsApi.d.ts

@@ -0,0 +1,27 @@
+import type { Socket } from 'socket.io-client';
+import AsyncModules from '../base/asyncModules.js';
+import type StateModule from '../base/stateModule.js';
+import type { IWS } from './wsInterfaces.js';
+/**
+ * Controllers for working with users
+ * @handle /api/content/ws
+ */
+export default class WsApi extends AsyncModules implements IWS {
+    protected state: StateModule;
+    protected _url: string;
+    /**
+     * Constructor
+     * @param {StateModule} state - StateModule
+     */
+    constructor(state: StateModule);
+    /**
+     * Creates an instance of an object Socket.io with a connection.
+     * @handleName connect
+     * @returns {Socket} Returns a Socket instance.
+     * @description Creates an instance of an object Socket.io with a connection. This method requires user authorization.
+     * Socket.io is imported on demand, so projects that never open a socket do not bundle it; the returned
+     * value is usable immediately either way (see `createLazySocket`).
+     * @see {@link https://js-sdk.oneentry.cloud/docs/web-socket/connect connect} documentation.
+     */
+    connect(): Socket;
+}