@bitrix24/b24jssdk 0.1.6 → 0.2.0

package/dist/commonjs/index.d.cts

@@ -383,50 +383,59 @@ declare const Browser: BrowserManager;
 /**
  * Interface defining the structure and methods of a Result object.
  */
-interface IResult {
+interface IResult<T = any> {
     /**
      * Indicates whether the operation resulted in success (no errors).
      */
-    isSuccess: boolean;
+    readonly isSuccess: boolean;
+    /**
+     * Collection of errors
+     */
+    readonly errors: Map<string, Error>;
     /**
      * Sets the data associated with the result.
      *
      * @param data The data to be stored in the result.
      * @returns The current Result object for chaining methods.
      */
-    setData: (data: any) => IResult;
+    setData: (data: T) => IResult<T>;
     /**
      * Retrieves the data associated with the result.
      *
      * @returns The data stored in the result, if any.
      */
-    getData: () => any;
+    getData: () => T | null;
     /**
      * Adds an error message or Error object to the result.
-     *
      * @param error The error message or Error object to be added.
-     * @returns The current Result object for chaining methods.
+     * @param key Error key. You can leave it blank. Then it will be generated automatically.
+     * @returns {IResult} The current Result object for chaining methods.
      */
-    addError: (error: Error | string) => IResult;
+    addError: (error: Error | string, key?: string) => IResult;
     /**
      * Adds multiple errors to the result in a single call.
      *
      * @param errors An array of errors or strings that will be converted to errors.
-     * @returns The current Result object for chaining methods.
+     * @returns {IResult} The current Result object for chaining methods.
      */
     addErrors: (errors: (Error | string)[]) => IResult;
     /**
      * Retrieves an iterator for the errors collected in the result.
      *
-     * @returns An iterator over the stored Error objects.
+     * @returns {IterableIterator<Error>} An iterator over the stored Error objects.
      */
     getErrors: () => IterableIterator<Error>;
     /**
      * Retrieves an array of error messages from the collected errors.
      *
-     * @returns An array of strings representing the error messages.
+     * @returns {string[]} An array of strings representing the error messages.
      */
     getErrorMessages: () => string[];
+    /**
+     * Checks for an error in a collection by key
+     * @param key - Error key
+     */
+    hasError(key: string): boolean;
     /**
      * Converts the Result object to a string.
      *
@@ -439,49 +448,18 @@ interface IResult {
  * Similar to \Bitrix\Main\Result from Bitrix Framework.
  * @link https://dev.1c-bitrix.ru/api_d7/bitrix/main/result/index.php
  */
-declare class Result implements IResult {
-    private _errorCollection;
-    protected _data: any;
-    constructor();
-    /**
-     * Getter for the `isSuccess` property.
-     * Checks if the `_errorCollection` is empty to determine success.
-     *
-     * @returns Whether the operation resulted in success (no errors).
-     */
+declare class Result<T = any> implements IResult<T> {
+    protected _errors: Map<string, Error>;
+    protected _data: T | null;
+    constructor(data?: T);
     get isSuccess(): boolean;
-    /**
-     * Sets the data associated with the result.
-     *
-     * @param data The data to be stored in the result.
-     * @returns The current Result object for chaining methods.
-     */
-    setData(data: any): Result;
-    /**
-     * Retrieves the data associated with the result.
-     *
-     * @returns The data stored in the result, if any.
-     */
-    getData(): any;
-    /**
-     * Adds an error message or Error object to the result.
-     *
-     * @param error The error message or Error object to be added.
-     * @returns The current Result object for chaining methods.
-     */
-    addError(error: Error | string): Result;
-    /**
-     * Adds multiple errors to the result in a single call.
-     *
-     * @param errors An array of errors or strings that will be converted to errors.
-     * @returns The current Result object for chaining methods.
-     */
-    addErrors(errors: (Error | string)[]): Result;
-    /**
-     * Retrieves an iterator for the errors collected in the result.
-     * @returns An iterator over the stored Error objects.
-     */
+    get errors(): Map<string, Error>;
+    setData(data: T | null): Result<T>;
+    getData(): T | null;
+    addError(error: Error | string, key?: string): Result<T>;
+    addErrors(errors: (Error | string)[]): Result<T>;
     getErrors(): IterableIterator<Error>;
+    hasError(key: string): boolean;
     /**
      * Retrieves an array of error messages from the collected errors.
      *
@@ -495,6 +473,10 @@ declare class Result implements IResult {
      * @returns {string} Returns a string representation of the result operation
      */
     toString(): string;
+    private safeStringify;
+    private replacer;
+    static ok<U>(data?: U): Result<U>;
+    static fail<U>(error: Error | string, key?: string): Result<U>;
 }
 
 type PayloadTime = {
@@ -538,36 +520,52 @@ type BatchPayload<C> = {
 };
 type Payload<P> = GetPayload<P> | ListPayload<P> | BatchPayload<P>;
 
-type AjaxQuery = {
+type AjaxQuery = Readonly<{
     method: string;
-    params: object;
+    params: Readonly<object>;
     start: number;
-};
-type AjaxResultParams = {
+}>;
+type AjaxResultParams<T = unknown> = Readonly<{
     error?: string | {
         error: string;
-        error_description: string;
+        error_description?: string;
     };
     error_description?: string;
-    result: any;
+    result: T;
     next?: NumberString;
     total?: NumberString;
-};
+    time: PayloadTime;
+}>;
+type AjaxResultOptions<T> = Readonly<{
+    answer: AjaxResultParams<T>;
+    query: AjaxQuery;
+    status: number;
+}>;
 /**
  * Result of request to Rest Api
  */
-declare class AjaxResult extends Result implements IResult {
+declare class AjaxResult<T = unknown> extends Result<Payload<T>> implements IResult<Payload<T>> {
+    #private;
     private readonly _status;
     private readonly _query;
-    protected _data: AjaxResultParams;
-    constructor(answer: AjaxResultParams, query: AjaxQuery, status: number);
-    setData(data: any): Result;
-    getData(): Payload<unknown>;
+    protected _data: AjaxResultParams<T>;
+    constructor(options: AjaxResultOptions<T>);
+    getData(): Payload<T>;
+    /**
+     * Alias for isMore
+     */
+    hasMore(): boolean;
     isMore(): boolean;
     getTotal(): number;
     getStatus(): number;
-    getQuery(): AjaxQuery;
-    getNext(http: TypeHttp): Promise<false | AjaxResult>;
+    getQuery(): Readonly<AjaxQuery>;
+    /**
+     * Alias for getNext
+     * @param http
+     */
+    fetchNext(http: TypeHttp): Promise<AjaxResult<T> | null>;
+    getNext(http: TypeHttp): Promise<AjaxResult<T> | false>;
+    setData(): never;
 }
 
 type TypeHttp = {
@@ -1360,18 +1358,81 @@ type AjaxErrorParams = {
     answerError: AnswerError;
     cause?: Error;
 };
+type ErrorDetails = {
+    code: string;
+    description?: string;
+    status: number;
+    requestInfo?: {
+        method?: string;
+        url?: string;
+        params?: Record<string, unknown> | unknown;
+    };
+    originalError?: unknown;
+};
 /**
  * Error requesting RestApi
  */
 declare class AjaxError extends Error {
-    cause: null | Error;
+    readonly code: string;
     private _status;
-    private _answerError;
-    constructor(params: AjaxErrorParams);
+    readonly requestInfo?: ErrorDetails['requestInfo'];
+    readonly timestamp: Date;
+    readonly originalError?: unknown;
+    constructor(details: ErrorDetails);
+    /**
+     * @deprecated
+     */
     get answerError(): AnswerError;
     get status(): number;
+    /**
+     * @deprecated
+     */
     set status(status: number);
+    /**
+     * Creates AjaxError from HTTP response
+     */
+    static fromResponse(response: {
+        status: number;
+        data?: {
+            error?: string;
+            error_description?: string;
+        };
+        config?: {
+            method?: string;
+            url?: string;
+            params?: unknown;
+        };
+    }): AjaxError;
+    /**
+     * Creates AjaxError from exception
+     */
+    static fromException(error: unknown, context?: {
+        code?: string;
+        status?: number;
+        requestInfo?: ErrorDetails['requestInfo'];
+    }): AjaxError;
+    /**
+     * Serializes error for logging and debugging
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        status: number;
+        timestamp: string;
+        requestInfo: {
+            method?: string;
+            url?: string;
+            params?: Record<string, unknown> | unknown;
+        } | undefined;
+        stack: string | undefined;
+    };
+    /**
+     * Formats error information for human-readable output
+     */
     toString(): string;
+    private static formatErrorMessage;
+    private cleanErrorStack;
 }
 
 declare abstract class AbstractB24 implements TypeB24 {
@@ -1683,7 +1744,9 @@ declare enum MessageCommands {
     selectUser = "selectUser",
     selectAccess = "selectAccess",
     selectCRM = "selectCRM",
-    showAppForm = "showAppForm"
+    showAppForm = "showAppForm",
+    getInterface = "getInterface",
+    placementBindEvent = "placementBindEvent"
 }
 
 /**
@@ -2139,7 +2202,7 @@ declare class SliderManager {
  */
 declare class PlacementManager {
     #private;
-    constructor();
+    constructor(messageManager: MessageManager);
     /**
      * Initializes the data received from the parent window message.
      * @param data
@@ -2149,6 +2212,31 @@ declare class PlacementManager {
     get isDefault(): boolean;
     get options(): any;
     get isSliderMode(): boolean;
+    /**
+     * Get Information About the JS Interface of the Current Embedding Location
+     *
+     * @return {Promise<any>}
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-get-interface.html
+     */
+    getInterface(): Promise<any>;
+    /**
+     * Set Up the Interface Event Handler
+     * @param {string} eventName
+     * @return {Promise<any>}
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-bind-event.html
+     */
+    bindEvent(eventName: string): Promise<any>;
+    /**
+     * Call the Registered Interface Command
+     * @param {string} command
+     * @param {Record<string, any>} parameters
+     * @return {Promise<any>}
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-call.html
+     */
+    call(command: string, parameters?: Record<string, any>): Promise<any>;
 }
 
 /**

package/dist/commonjs/index.d.mts

@@ -383,50 +383,59 @@ declare const Browser: BrowserManager;
 /**
  * Interface defining the structure and methods of a Result object.
  */
-interface IResult {
+interface IResult<T = any> {
     /**
      * Indicates whether the operation resulted in success (no errors).
      */
-    isSuccess: boolean;
+    readonly isSuccess: boolean;
+    /**
+     * Collection of errors
+     */
+    readonly errors: Map<string, Error>;
     /**
      * Sets the data associated with the result.
      *
      * @param data The data to be stored in the result.
      * @returns The current Result object for chaining methods.
      */
-    setData: (data: any) => IResult;
+    setData: (data: T) => IResult<T>;
     /**
      * Retrieves the data associated with the result.
      *
      * @returns The data stored in the result, if any.
      */
-    getData: () => any;
+    getData: () => T | null;
     /**
      * Adds an error message or Error object to the result.
-     *
      * @param error The error message or Error object to be added.
-     * @returns The current Result object for chaining methods.
+     * @param key Error key. You can leave it blank. Then it will be generated automatically.
+     * @returns {IResult} The current Result object for chaining methods.
      */
-    addError: (error: Error | string) => IResult;
+    addError: (error: Error | string, key?: string) => IResult;
     /**
      * Adds multiple errors to the result in a single call.
      *
      * @param errors An array of errors or strings that will be converted to errors.
-     * @returns The current Result object for chaining methods.
+     * @returns {IResult} The current Result object for chaining methods.
      */
     addErrors: (errors: (Error | string)[]) => IResult;
     /**
      * Retrieves an iterator for the errors collected in the result.
      *
-     * @returns An iterator over the stored Error objects.
+     * @returns {IterableIterator<Error>} An iterator over the stored Error objects.
      */
     getErrors: () => IterableIterator<Error>;
     /**
      * Retrieves an array of error messages from the collected errors.
      *
-     * @returns An array of strings representing the error messages.
+     * @returns {string[]} An array of strings representing the error messages.
      */
     getErrorMessages: () => string[];
+    /**
+     * Checks for an error in a collection by key
+     * @param key - Error key
+     */
+    hasError(key: string): boolean;
     /**
      * Converts the Result object to a string.
      *
@@ -439,49 +448,18 @@ interface IResult {
  * Similar to \Bitrix\Main\Result from Bitrix Framework.
  * @link https://dev.1c-bitrix.ru/api_d7/bitrix/main/result/index.php
  */
-declare class Result implements IResult {
-    private _errorCollection;
-    protected _data: any;
-    constructor();
-    /**
-     * Getter for the `isSuccess` property.
-     * Checks if the `_errorCollection` is empty to determine success.
-     *
-     * @returns Whether the operation resulted in success (no errors).
-     */
+declare class Result<T = any> implements IResult<T> {
+    protected _errors: Map<string, Error>;
+    protected _data: T | null;
+    constructor(data?: T);
     get isSuccess(): boolean;
-    /**
-     * Sets the data associated with the result.
-     *
-     * @param data The data to be stored in the result.
-     * @returns The current Result object for chaining methods.
-     */
-    setData(data: any): Result;
-    /**
-     * Retrieves the data associated with the result.
-     *
-     * @returns The data stored in the result, if any.
-     */
-    getData(): any;
-    /**
-     * Adds an error message or Error object to the result.
-     *
-     * @param error The error message or Error object to be added.
-     * @returns The current Result object for chaining methods.
-     */
-    addError(error: Error | string): Result;
-    /**
-     * Adds multiple errors to the result in a single call.
-     *
-     * @param errors An array of errors or strings that will be converted to errors.
-     * @returns The current Result object for chaining methods.
-     */
-    addErrors(errors: (Error | string)[]): Result;
-    /**
-     * Retrieves an iterator for the errors collected in the result.
-     * @returns An iterator over the stored Error objects.
-     */
+    get errors(): Map<string, Error>;
+    setData(data: T | null): Result<T>;
+    getData(): T | null;
+    addError(error: Error | string, key?: string): Result<T>;
+    addErrors(errors: (Error | string)[]): Result<T>;
     getErrors(): IterableIterator<Error>;
+    hasError(key: string): boolean;
     /**
      * Retrieves an array of error messages from the collected errors.
      *
@@ -495,6 +473,10 @@ declare class Result implements IResult {
      * @returns {string} Returns a string representation of the result operation
      */
     toString(): string;
+    private safeStringify;
+    private replacer;
+    static ok<U>(data?: U): Result<U>;
+    static fail<U>(error: Error | string, key?: string): Result<U>;
 }
 
 type PayloadTime = {
@@ -538,36 +520,52 @@ type BatchPayload<C> = {
 };
 type Payload<P> = GetPayload<P> | ListPayload<P> | BatchPayload<P>;
 
-type AjaxQuery = {
+type AjaxQuery = Readonly<{
     method: string;
-    params: object;
+    params: Readonly<object>;
     start: number;
-};
-type AjaxResultParams = {
+}>;
+type AjaxResultParams<T = unknown> = Readonly<{
     error?: string | {
         error: string;
-        error_description: string;
+        error_description?: string;
     };
     error_description?: string;
-    result: any;
+    result: T;
     next?: NumberString;
     total?: NumberString;
-};
+    time: PayloadTime;
+}>;
+type AjaxResultOptions<T> = Readonly<{
+    answer: AjaxResultParams<T>;
+    query: AjaxQuery;
+    status: number;
+}>;
 /**
  * Result of request to Rest Api
  */
-declare class AjaxResult extends Result implements IResult {
+declare class AjaxResult<T = unknown> extends Result<Payload<T>> implements IResult<Payload<T>> {
+    #private;
     private readonly _status;
     private readonly _query;
-    protected _data: AjaxResultParams;
-    constructor(answer: AjaxResultParams, query: AjaxQuery, status: number);
-    setData(data: any): Result;
-    getData(): Payload<unknown>;
+    protected _data: AjaxResultParams<T>;
+    constructor(options: AjaxResultOptions<T>);
+    getData(): Payload<T>;
+    /**
+     * Alias for isMore
+     */
+    hasMore(): boolean;
     isMore(): boolean;
     getTotal(): number;
     getStatus(): number;
-    getQuery(): AjaxQuery;
-    getNext(http: TypeHttp): Promise<false | AjaxResult>;
+    getQuery(): Readonly<AjaxQuery>;
+    /**
+     * Alias for getNext
+     * @param http
+     */
+    fetchNext(http: TypeHttp): Promise<AjaxResult<T> | null>;
+    getNext(http: TypeHttp): Promise<AjaxResult<T> | false>;
+    setData(): never;
 }
 
 type TypeHttp = {
@@ -1360,18 +1358,81 @@ type AjaxErrorParams = {
     answerError: AnswerError;
     cause?: Error;
 };
+type ErrorDetails = {
+    code: string;
+    description?: string;
+    status: number;
+    requestInfo?: {
+        method?: string;
+        url?: string;
+        params?: Record<string, unknown> | unknown;
+    };
+    originalError?: unknown;
+};
 /**
  * Error requesting RestApi
  */
 declare class AjaxError extends Error {
-    cause: null | Error;
+    readonly code: string;
     private _status;
-    private _answerError;
-    constructor(params: AjaxErrorParams);
+    readonly requestInfo?: ErrorDetails['requestInfo'];
+    readonly timestamp: Date;
+    readonly originalError?: unknown;
+    constructor(details: ErrorDetails);
+    /**
+     * @deprecated
+     */
     get answerError(): AnswerError;
     get status(): number;
+    /**
+     * @deprecated
+     */
     set status(status: number);
+    /**
+     * Creates AjaxError from HTTP response
+     */
+    static fromResponse(response: {
+        status: number;
+        data?: {
+            error?: string;
+            error_description?: string;
+        };
+        config?: {
+            method?: string;
+            url?: string;
+            params?: unknown;
+        };
+    }): AjaxError;
+    /**
+     * Creates AjaxError from exception
+     */
+    static fromException(error: unknown, context?: {
+        code?: string;
+        status?: number;
+        requestInfo?: ErrorDetails['requestInfo'];
+    }): AjaxError;
+    /**
+     * Serializes error for logging and debugging
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        status: number;
+        timestamp: string;
+        requestInfo: {
+            method?: string;
+            url?: string;
+            params?: Record<string, unknown> | unknown;
+        } | undefined;
+        stack: string | undefined;
+    };
+    /**
+     * Formats error information for human-readable output
+     */
     toString(): string;
+    private static formatErrorMessage;
+    private cleanErrorStack;
 }
 
 declare abstract class AbstractB24 implements TypeB24 {
@@ -1683,7 +1744,9 @@ declare enum MessageCommands {
     selectUser = "selectUser",
     selectAccess = "selectAccess",
     selectCRM = "selectCRM",
-    showAppForm = "showAppForm"
+    showAppForm = "showAppForm",
+    getInterface = "getInterface",
+    placementBindEvent = "placementBindEvent"
 }
 
 /**
@@ -2139,7 +2202,7 @@ declare class SliderManager {
  */
 declare class PlacementManager {
     #private;
-    constructor();
+    constructor(messageManager: MessageManager);
     /**
      * Initializes the data received from the parent window message.
      * @param data
@@ -2149,6 +2212,31 @@ declare class PlacementManager {
     get isDefault(): boolean;
     get options(): any;
     get isSliderMode(): boolean;
+    /**
+     * Get Information About the JS Interface of the Current Embedding Location
+     *
+     * @return {Promise<any>}
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-get-interface.html
+     */
+    getInterface(): Promise<any>;
+    /**
+     * Set Up the Interface Event Handler
+     * @param {string} eventName
+     * @return {Promise<any>}
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-bind-event.html
+     */
+    bindEvent(eventName: string): Promise<any>;
+    /**
+     * Call the Registered Interface Command
+     * @param {string} command
+     * @param {Record<string, any>} parameters
+     * @return {Promise<any>}
+     *
+     * @link https://apidocs.bitrix24.com/api-reference/widgets/ui-interaction/bx24-placement-call.html
+     */
+    call(command: string, parameters?: Record<string, any>): Promise<any>;
 }
 
 /**