bx-rest 1.0.0 → 1.2.0

package/functions/errors.d.ts

@@ -1,13 +1,53 @@
+export interface BXRestApiErrorDetails {
+    /**
+     * HTTP status of the portal response. `undefined` when the error came in
+     * the body of a successful (2xx) response.
+     */
+    status?: number;
+    /** REST method that failed, e.g. `crm.deal.get`. */
+    method?: string;
+    /**
+     * The original error, e.g. the `AxiosError` — its `response.data` holds
+     * the full response body (including REST v3 `validation`).
+     */
+    cause?: unknown;
+}
 /**
- * Thrown by `.res()` when called with `{ throwOnApiError: true }` and the
- * Bitrix REST call resolves as a Bitrix-level API error, e.g.
- * `INSUFFICIENT_SCOPE` or `expired_token`.
+ * A Bitrix-level API error, e.g. `INSUFFICIENT_SCOPE` or `expired_token`.
  *
- * By default `.res()` resolves such responses as `undefined` instead of
- * throwing — see the "Error handling" section of the README.
+ * `.res()` fails with it whenever the portal answers with a Bitrix error and
+ * a non-2xx HTTP status — which is how Bitrix sends most of its errors. When
+ * the error comes in the body of a 2xx response, `.res()` resolves as
+ * `undefined` by default and fails with it only with
+ * `{ throwOnApiError: true }` — see the "Error handling" section of the README.
  */
 export declare class BXRestApiError extends Error {
     error: string | undefined;
     error_description: string | undefined;
-    constructor(error: string | undefined, error_description: string | undefined);
+    readonly status: number | undefined;
+    readonly method: string | undefined;
+    constructor(error: string | undefined, error_description: string | undefined, details?: BXRestApiErrorDetails);
 }
+/**
+ * Recognises a Bitrix error body: REST v2 `{ error, error_description }` and
+ * REST v3 `{ error: { code, message } }`. Returns `undefined` for anything
+ * else — a success payload, an HTML page from a proxy, an empty body.
+ *
+ * An empty `error` still counts: Bitrix answers e.g. `crm.deal.get` for a
+ * missing ID with `{ error: '', error_description: 'Not found' }`.
+ */
+export declare function parseBXRestErrorBody(body: unknown): {
+    error: string;
+    error_description: string | undefined;
+} | undefined;
+/**
+ * Turns an HTTP failure into a `BXRestApiError` when the portal answered with
+ * a Bitrix error body. Bitrix sends most errors with a non-2xx status
+ * (401 `expired_token`, 404 `ERROR_METHOD_NOT_FOUND`, 503
+ * `QUERY_LIMIT_EXCEEDED`, 400 "Not found" from `crm.*.get`, ...), and axios
+ * rejects on those.
+ *
+ * Returns `undefined` for network errors and for responses that are not a
+ * Bitrix error body, so the caller can keep its own handling for them.
+ */
+export declare function bxRestApiErrorFromHttp(err: unknown, method: string): BXRestApiError | undefined;

package/map/tasks/task.d.ts

@@ -6,9 +6,7 @@ import { iBXRestHttpTask, iBXRestTask } from '../../typification/rest/tasks/task
 import { iBXRestTaskFieldsName } from '../../typification/rest/tasks/base/fields-name';
 export declare class BXRestMapTasksTask {
     readonly result: typeof BXRestMapTasksTaskResult;
-    static getAccess(v: iBXRestTaskGetAccess | undefined): {
-        [key: number]: import("../../typification/rest/task/access/getaccess").iBXRestTaskGetAccessItem;
-    } | undefined;
+    static getAccess(v: iBXRestTaskGetAccess | undefined): Record<number, import("../../typification/rest/task/access/getaccess").iBXRestTaskGetAccessItem> | undefined;
     static add(item: {
         task: iBXRestTasksTaskGetHttpDefault;
     } | undefined): iBXRestTask | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bx-rest",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Bitrix24 REST API client and TypeScript SDK for Angular, Vue and browser apps",
   "keywords": [
     "bitrix",
@@ -48,6 +48,7 @@
     "README.md",
     "README.en.md",
     "LICENSE",
+    "CHANGELOG.md",
     "*.d.ts",
     "consts",
     "esm2022",

package/services/http/HttpBX.d.ts

@@ -4,7 +4,7 @@ import { iBatchRequestAnswer, iBatchRequestParam, iBatchRequestParamArr, iBatchR
 import { iBXRestAnswer } from '../../typification/rest/base/answer';
 export declare class HttpBXServices extends HttpServices {
     /**
-     * Это пиздец а не метод
+     * Не считайте этот метод образцом/финальным API.
      * TODO: Удалить данный метод после реализации его в разделе Navvy
      * @param param
      */
@@ -27,6 +27,7 @@ export declare class HttpBXServices extends HttpServices {
      */
     get<T>(name: string[], params?: any): Observable<iBXRestAnswer<T> | undefined>;
     httpPost<T>(url: string, params?: any): Observable<T | undefined>;
+    httpGet<T>(url: string, params?: any): Observable<T | undefined>;
     serializeBitrixParams(params: unknown): string;
     getNameMethod(arr: string[]): string;
 }

package/services/navvy/extends/navvy-pag-base.d.ts

@@ -4,10 +4,13 @@ import { HttpBXServices } from '../../http/HttpBX';
 import { ReturnTypeNavvy } from '../navvy-support';
 export interface BXRestResOptions {
     /**
-     * When `true`, a Bitrix-level API error (`{ error, error_description }`,
-     * e.g. `INSUFFICIENT_SCOPE`, `expired_token`) makes the `Observable`
-     * returned by `.res()` error out with a `BXRestApiError` instead of
-     * resolving with `undefined`.
+     * When `true`, a Bitrix-level API error that comes in the body of a 2xx
+     * response makes the `Observable` returned by `.res()` error out with a
+     * `BXRestApiError` instead of resolving with `undefined`.
+     *
+     * Errors that Bitrix sends with a non-2xx HTTP status (most of them, e.g.
+     * `expired_token`, `INSUFFICIENT_SCOPE`) fail with `BXRestApiError`
+     * regardless of this option.
      *
      * Default: `false` (preserves the historical `.res()` behaviour).
      */

package/settings.d.ts

@@ -1,6 +1,13 @@
 import { iBXRestSettings } from './typification/settings';
 export declare const DEFAULT_BX_REST_SETTINGS: iBXRestSettings;
 export declare const BXRestSettings: {
+    value: iBXRestSettings;
+    /**
+     * @deprecated Переименовано в `BXRestSettings.value` — имя `date` не
+     * отражало содержимое (настройки auth/urls, а не дату) и сбивало с толку
+     * в публичном API. Геттер/сеттер оставлен только для обратной совместимости
+     * с кодом, написанным против API до 1.0.
+     */
     date: iBXRestSettings;
     update(newSettings: Partial<iBXRestSettings>): void;
 };

package/typification/rest/batch/batchRequestParam.d.ts

@@ -4,12 +4,6 @@ export interface iBatchRequestParam<T> {
     name: string;
     param: T;
 }
-export type iBatchRequestParamHttp = {
-    [key: keyBatch]: string;
-};
-export type iBatchRequestParamArr<T> = {
-    [key: keyBatch]: iBatchRequestParam<T>;
-};
-export type iBatchRequestAnswer<T> = iBXRestAnswer<iBXRestAnswer<{
-    [key: keyBatch]: T;
-}>>;
+export type iBatchRequestParamHttp = Record<keyBatch, string>;
+export type iBatchRequestParamArr<T> = Record<keyBatch, iBatchRequestParam<T>>;
+export type iBatchRequestAnswer<T> = iBXRestAnswer<iBXRestAnswer<Record<keyBatch, T>>>;

package/typification/rest/support/param.d.ts

@@ -1,5 +1,3 @@
 export interface iBXRestBaseParam {
     start?: number;
 }
-export interface iBXRestBaseParamFactor<T extends iBXRestBaseParam> {
-}

package/typification/rest/task/access/getaccess.d.ts

@@ -6,9 +6,7 @@ export interface iBXRestParamTaskGetAccess {
     users?: number[];
 }
 export interface iBXRestTaskGetAccess {
-    allowedActions: {
-        [key: number]: iBXRestTaskGetAccessItem;
-    };
+    allowedActions: Record<number, iBXRestTaskGetAccessItem>;
 }
 export interface iBXRestTaskGetAccessItem {
     ACCEPT: boolean;

package/typification/rest/task/commentitem/commentitem.d.ts

@@ -5,9 +5,7 @@ export interface iBXRestTaskComment extends iBXRestTaskCommentBase {
     POST_DATE: Date;
 }
 export interface iBXRestTaskCommentHtml extends iBXRestTaskCommentBase {
-    ATTACHED_OBJECTS?: {
-        [key: number]: iCommentTaskFileHtml;
-    };
+    ATTACHED_OBJECTS?: Record<number, iCommentTaskFileHtml>;
     AUTHOR_ID: string;
     ID: string;
     POST_DATE: string;

package/typification/rest/tasks/task.d.ts

@@ -68,9 +68,7 @@ export interface iBXRestHttpTask extends iBXRestBaseTask {
     additionalData: any[];
     creator: iBXRestHttpTaskPeople;
     responsible: iBXRestHttpTaskPeople;
-    accomplicesData: {
-        [key: number]: iBXRestHttpTaskPeople;
-    };
+    accomplicesData: Record<number, iBXRestHttpTaskPeople>;
     allowTimeTracking: iBXRestYesNo;
     tags: iBXRestTaskHttpTag;
 }
@@ -78,12 +76,10 @@ export interface iBXRestTaskTag {
     id: number;
     title: string;
 }
-export interface iBXRestTaskHttpTag {
-    [key: string]: {
-        id: string;
-        title: string;
-    };
-}
+export type iBXRestTaskHttpTag = Record<string, {
+    id: string;
+    title: string;
+}>;
 export interface iBXRestHttpTaskGroupHttp {
     id: string;
     name: string;