bx-rest 1.1.0 → 1.3.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bx-rest",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Bitrix24 REST API client and TypeScript SDK for Angular, Vue and browser apps",
   "keywords": [
     "bitrix",

package/rest/base.d.ts

@@ -29,5 +29,5 @@ export declare class BXRest {
     readonly socialNetWork: BXRestSocialNetWork;
     readonly pull: BXRestPull;
     profile(): import("rxjs").Observable<import("../typification/rest/base").iBXRestAnswer<iBXRestProfileHttp> | undefined>;
-    batch<T>(param: iBXRestParamBatch): import("rxjs").Observable<import("../typification/rest/base").iBXRestAnswer<iBXRestBatch<T>> | undefined>;
+    batch<T>(param: iBXRestParamBatch, headers?: Record<string, string>): import("rxjs").Observable<import("../typification/rest/base").iBXRestAnswer<iBXRestBatch<T>> | undefined>;
 }

package/services/http/HttpBX.d.ts

@@ -2,6 +2,7 @@ import { Observable } from 'rxjs';
 import { HttpServices } from './http';
 import { iBatchRequestAnswer, iBatchRequestParam, iBatchRequestParamArr, iBatchRequestParamHttp, keyBatch } from '../../typification/rest/batch/batchRequestParam';
 import { iBXRestAnswer } from '../../typification/rest/base/answer';
+import { iHttpParamSettings } from '../../typification/rest/settings';
 export declare class HttpBXServices extends HttpServices {
     /**
      * Не считайте этот метод образцом/финальным API.
@@ -17,17 +18,27 @@ export declare class HttpBXServices extends HttpServices {
      *
      * @param name
      * @param params
+     * @param restApi
+     * @param headers заголовки только для этого запроса, поверх `BXRestSettings.headers`
      */
-    post<T>(name: string[], params?: any, restApi?: boolean): Observable<iBXRestAnswer<T> | undefined>;
+    post<T>(name: string[], params?: any, restApi?: boolean, headers?: Record<string, string>): Observable<iBXRestAnswer<T> | undefined>;
     /**
      * Второстепенный метод для запросов. По возможности лучше не использовать
      *
      * @param name
      * @param params
+     * @param headers заголовки только для этого запроса, поверх `BXRestSettings.headers`
      */
-    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>;
+    get<T>(name: string[], params?: any, headers?: Record<string, string>): Observable<iBXRestAnswer<T> | undefined>;
+    httpPost<T>(url: string, params?: any, settings?: iHttpParamSettings, headers?: Record<string, string>): Observable<T | undefined>;
+    httpGet<T>(url: string, params?: any, settings?: iHttpParamSettings, headers?: Record<string, string>): Observable<T | undefined>;
+    /**
+     * Заголовки запроса: `BXRestSettings.headers`, поверх них — заголовки
+     * конкретного запроса, поверх всего — `required`. В `required` идёт
+     * `Content-Type`: от него зависит, как сервер разберёт тело, поэтому
+     * пользовательские заголовки его не перебивают.
+     */
+    private buildHeaders;
     serializeBitrixParams(params: unknown): string;
     getNameMethod(arr: string[]): string;
 }

package/services/http/sessionKey.d.ts

@@ -21,6 +21,11 @@ export declare class SessionKeyServices {
      * сохраняется историческое поведение: включаем только для `auth.key === 'OAuth2'`.
      */
     getWithCredentials(): boolean;
+    /**
+     * Статичные заголовки из `BXRestSettings.headers` — копия, чтобы правка
+     * результата не меняла сами настройки.
+     */
+    getHeaders(): Record<string, string>;
     getSessid(): string;
     getAuthParams(): string | undefined;
     getCheckAuthParamsIsOn(): boolean;

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).
      */
@@ -19,8 +22,19 @@ export declare abstract class NavvyPagBase<T, R, P> {
     protected map: ((param: T | undefined) => R | undefined) | undefined;
     protected restApi: boolean;
     protected readonly http: HttpBXServices;
+    protected requestHeaders?: Record<string, string>;
     pageSize: number;
     constructor(url: string[], param: P, map?: ((param: T | undefined) => R | undefined) | undefined, restApi?: boolean);
+    /**
+     * HTTP-заголовки только для этого запроса — поверх `BXRestSettings.headers`
+     * (при совпадении имени побеждает значение отсюда). Повторные вызовы
+     * дополняют уже заданные заголовки. Действует на `.res()`, `.resVanilla()`,
+     * `.mapForVanilla()` и на все batch-запросы `.resAll()`.
+     *
+     * @example
+     * bx.crm.deal.list({ ... }).withHeaders({ 'X-Request-Source': 'report' }).resAll()
+     */
+    withHeaders(headers: Record<string, string>): this;
     resVanilla(): Observable<iBXRestAnswer<T> | undefined>;
     mapForVanilla(): Observable<iBXRestAnswer<ReturnTypeNavvy<T, R>> | undefined>;
     res(options?: BXRestResOptions): Observable<ReturnTypeNavvy<T, R> | undefined>;

package/typification/settings.d.ts

@@ -17,4 +17,11 @@ export interface iBXRestSettings {
      * а браузер должен приложить cookie сессии этого прокси (не Bitrix24).
      */
     withCredentials?: boolean;
+    /**
+     * Статичные HTTP-заголовки, которые прикладываются к каждому запросу,
+     * например `{ 'X-Bitrix-App': 'smart-process-pro' }`. Для одного запроса
+     * их можно дополнить или перебить через `.withHeaders()`. `Content-Type`
+     * библиотека всегда выставляет сама — от него зависит формат тела запроса.
+     */
+    headers?: Record<string, string>;
 }