bx-rest 1.1.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/package.json

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

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).
      */