bx-rest 1.1.0 → 1.3.0

package/fesm2022/bx-rest.mjs

@@ -587,6 +587,13 @@ class SessionKeyServices {
         }
         return this.getKeyAuth() === 'OAuth2';
     }
+    /**
+     * Статичные заголовки из `BXRestSettings.headers` — копия, чтобы правка
+     * результата не меняла сами настройки.
+     */
+    getHeaders() {
+        return { ...this.BX_REST_SETTINGS.headers };
+    }
     getSessid() {
         const check = this.getSearchParam('sessid');
         if (check) {
@@ -970,21 +977,26 @@ class HttpBXServices extends HttpServices {
      *
      * @param name
      * @param params
+     * @param restApi
+     * @param headers заголовки только для этого запроса, поверх `BXRestSettings.headers`
      */
-    post(name, params = {}, restApi = false) {
+    post(name, params = {}, restApi = false, headers) {
         const method = this.getNameMethod(name);
-        return this.httpPost(restApi ? `api/${method}` : method, params);
+        return this.httpPost(restApi ? `api/${method}` : method, params, undefined, headers);
     }
     /**
      * Второстепенный метод для запросов. По возможности лучше не использовать
      *
      * @param name
      * @param params
+     * @param headers заголовки только для этого запроса, поверх `BXRestSettings.headers`
      */
-    get(name, params = {}) {
-        return this.httpGet(this.getNameMethod(name), params);
+    get(name, params = {}, headers) {
+        return this.httpGet(this.getNameMethod(name), params, undefined, headers);
     }
-    httpPost(url, params = {}) {
+    // settings — только для совместимости сигнатуры с HttpServices: здесь тело
+    // уходит JSON-ом/urlencoded, и пересчёт дат из iHttpParamSettings не нужен.
+    httpPost(url, params = {}, settings, headers) {
         // defer() откладывает всё содержимое (в том числе чтение BXRestSettings
         // через this.session.*) до реальной подписки — иначе даже с "живым"
         // геттером в SessionKeyServices настройки читались бы в момент вызова
@@ -1012,19 +1024,17 @@ class HttpBXServices extends HttpServices {
                     // Преобразуем параметры в формат x-www-form-urlencoded
                     const bodyString = this.serializeBitrixParams(paramsClone);
                     return from(this.axiosInstance.post(fullUrl, bodyString, {
-                        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                        headers: this.buildHeaders(headers, { 'Content-Type': 'application/x-www-form-urlencoded' }),
                     }).then((response) => response.data));
                 }
                 return from(this.axiosInstance.post(fullUrl, paramsClone, {
                     withCredentials: this.session.getWithCredentials(),
-                    headers: {
-                        'Content-Type': 'application/json',
-                    }
+                    headers: this.buildHeaders(headers, { 'Content-Type': 'application/json' }),
                 }).then((response) => response.data));
             }));
         });
     }
-    httpGet(url, params = {}) {
+    httpGet(url, params = {}, settings, headers) {
         // Та же причина, что и у httpPost выше: откладываем чтение BXRestSettings
         // до подписки, чтобы `get()` вёл себя так же "лениво", как и `post()`
         // (симметрия, которой не было до этого — GET резолвил настройки в момент
@@ -1046,10 +1056,21 @@ class HttpBXServices extends HttpServices {
                 const fullUrl = prepareBaseAddress(baseUrl) + url;
                 const queryString = new URLSearchParams(paramsClone).toString();
                 const finalUrl = `${fullUrl}?${queryString}`;
-                return from(this.axiosInstance.get(finalUrl).then((response) => response.data));
+                return from(this.axiosInstance.get(finalUrl, {
+                    headers: this.buildHeaders(headers),
+                }).then((response) => response.data));
             }));
         });
     }
+    /**
+     * Заголовки запроса: `BXRestSettings.headers`, поверх них — заголовки
+     * конкретного запроса, поверх всего — `required`. В `required` идёт
+     * `Content-Type`: от него зависит, как сервер разберёт тело, поэтому
+     * пользовательские заголовки его не перебивают.
+     */
+    buildHeaders(headers, required = {}) {
+        return { ...this.session.getHeaders(), ...headers, ...required };
+    }
     serializeBitrixParams(params) {
         return serializeBitrixParams(params);
     }
@@ -1059,20 +1080,75 @@ class HttpBXServices extends HttpServices {
 }
 
 /**
- * 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.
  */
 class BXRestApiError extends Error {
-    constructor(error, error_description) {
-        super(error_description || error || 'Bitrix API error');
+    constructor(error, error_description, details) {
+        super(error_description || error || 'Bitrix API error', details?.cause !== undefined ? { cause: details.cause } : undefined);
         this.error = error;
         this.error_description = error_description;
         this.name = 'BXRestApiError';
+        this.status = details?.status;
+        this.method = details?.method;
+    }
+}
+/**
+ * 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' }`.
+ */
+function parseBXRestErrorBody(body) {
+    if (!body || typeof body !== 'object' || !('error' in body)) {
+        return undefined;
+    }
+    const { error, error_description } = body;
+    if (typeof error === 'string') {
+        return {
+            error,
+            error_description: typeof error_description === 'string' ? error_description : undefined
+        };
     }
+    if (error && typeof error === 'object' && 'code' in error) {
+        const { code, message } = error;
+        return {
+            error: String(code),
+            error_description: typeof message === 'string' ? message : undefined
+        };
+    }
+    return 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.
+ */
+function bxRestApiErrorFromHttp(err, method) {
+    if (!axios.isAxiosError(err) || !err.response) {
+        return undefined;
+    }
+    const parsed = parseBXRestErrorBody(err.response.data);
+    if (!parsed) {
+        return undefined;
+    }
+    return new BXRestApiError(parsed.error, parsed.error_description, {
+        status: err.response.status,
+        method,
+        cause: err
+    });
 }
 
 class NavvyPagBase {
@@ -1084,8 +1160,21 @@ class NavvyPagBase {
         this.pageSize = 50; // стандартный размер страницы
         this.http = new HttpBXServices();
     }
+    /**
+     * HTTP-заголовки только для этого запроса — поверх `BXRestSettings.headers`
+     * (при совпадении имени побеждает значение отсюда). Повторные вызовы
+     * дополняют уже заданные заголовки. Действует на `.res()`, `.resVanilla()`,
+     * `.mapForVanilla()` и на все batch-запросы `.resAll()`.
+     *
+     * @example
+     * bx.crm.deal.list({ ... }).withHeaders({ 'X-Request-Source': 'report' }).resAll()
+     */
+    withHeaders(headers) {
+        this.requestHeaders = { ...this.requestHeaders, ...headers };
+        return this;
+    }
     resVanilla() {
-        return this.http.post(this.url, this.param, this.restApi);
+        return this.http.post(this.url, this.param, this.restApi, this.requestHeaders);
     }
     mapForVanilla() {
         return this.resVanilla()
@@ -1104,9 +1193,11 @@ class NavvyPagBase {
             : v));
     }
     mapAndError(request, options) {
+        const method = this.http.getNameMethod(this.url);
         return request.pipe(map(v => {
             if (options?.throwOnApiError && v && !instanceOfiBXRestAnswerSuccess(v)) {
-                throw new BXRestApiError(v.error, v.error_description);
+                const parsed = parseBXRestErrorBody(v);
+                throw new BXRestApiError(parsed ? parsed.error : v.error, parsed ? parsed.error_description : v.error_description, { method });
             }
             return BXRestMapResult(v);
         }), catchError((err) => {
@@ -1114,6 +1205,13 @@ class NavvyPagBase {
             if (err instanceof BXRestApiError) {
                 throw err;
             }
+            // Большинство ошибок Bitrix приходит со статусом не 2xx, и axios
+            // отклоняет такой ответ — достаём из него код и описание ошибки,
+            // а не отдаём безликое "AxiosError: Request failed with status code 400".
+            const apiError = bxRestApiErrorFromHttp(err, method);
+            if (apiError) {
+                throw apiError;
+            }
             throw new Error((err.error) ? err.error : err);
         }));
     }
@@ -3042,8 +3140,8 @@ class BXRest {
     profile() {
         return this.http.post(['profile']);
     }
-    batch(param) {
-        return this.http.post(['batch'], param);
+    batch(param, headers) {
+        return this.http.post(['batch'], param, false, headers);
     }
 }
 
@@ -3095,7 +3193,7 @@ class NavvyAlterPagNav extends NavvyPagBase {
                                 return this.http.getNameMethod(this.url)
                                     + '?' + serializeBitrixParams(param);
                             })
-                        });
+                        }, this.requestHeaders);
                     });
                     return from(batchRequests).pipe(concatMap(request => request), // Выполняет запросы по очереди
                     toArray(), // Собирает все результаты в массив
@@ -3151,7 +3249,7 @@ class NavvyPagNavWithUselessKey extends NavvyPagBase {
                                 return this.http.getNameMethod(this.url)
                                     + '?' + serializeBitrixParams(param);
                             })
-                        }).pipe(map(v => {
+                        }, this.requestHeaders).pipe(map(v => {
                             if (v && instanceOfiBXRestAnswerSuccess(v) && v.result && v.result.result && items.result) {
                                 return Object.assign({}, items.result, v.result.result);
                             }
@@ -3237,7 +3335,7 @@ class NavvyPagNavTasks extends NavvyPagBase {
                                 return this.http.getNameMethod(this.url)
                                     + '?' + serializeBitrixParams(param);
                             })
-                        });
+                        }, this.requestHeaders);
                     });
                     return from(batchRequests).pipe(concatMap(request => request), // Выполняет запросы по очереди
                     toArray(), // Собирает все результаты в массив
@@ -3301,7 +3399,7 @@ class NavvyPag extends NavvyPagBase {
                                 return this.http.getNameMethod(this.url)
                                     + '?' + serializeBitrixParams(param);
                             })
-                        }).pipe();
+                        }, this.requestHeaders).pipe();
                     });
                     return from(batchRequests).pipe(concatMap(request => request), // Выполняет запросы по очереди
                     toArray(), // Собирает все результаты в массив
@@ -3371,7 +3469,7 @@ class NavvyPagNavResultKey extends NavvyPagBase {
                                 return this.http.getNameMethod(this.url)
                                     + '?' + serializeBitrixParams(param);
                             })
-                        });
+                        }, this.requestHeaders);
                     });
                     return from(batchRequests).pipe(concatMap(request => request), toArray(), map(results => {
                         const firstPage = items.result?.[this.key];
@@ -3427,7 +3525,7 @@ class NavvyPagNavResultKeyObject extends NavvyPagBase {
                 return bxRest.batch({
                     halt: 1,
                     cmd: [this.http.getNameMethod(this.url) + '?' + serializeBitrixParams(param)]
-                });
+                }, this.requestHeaders);
             });
             return from(commands).pipe(concatMap(request => request), toArray(), mergeMap(results => {
                 const merged = { ...(items.result?.[this.key] ?? {}) };