@nomalism-com/api 0.45.63 → 0.45.65

package/dist/index.d.ts

@@ -1,2 +1,4 @@
 import * as Nomalism from './main';
+export { ApiError, isApiError, parseApiError } from './lib/apiError';
+export type { ApiErrorKind, IApiErrorFields } from './lib/apiError';
 export default Nomalism;

package/dist/index.js

@@ -129,9 +129,85 @@ __export(main_exports, {
   Workflow: () => workflow_exports,
   ZipCode: () => zipCode_exports
 });
-import axios, { AxiosHeaders } from "axios";
+import axios2, { AxiosHeaders } from "axios";
 import Nomalism from "@nomalism-com/types";
 
+// src/lib/apiError.ts
+import axios from "axios";
+var RAW_ERROR = /* @__PURE__ */ Symbol("rawError");
+var ApiError = class _ApiError extends Error {
+  constructor(fields, cause) {
+    super(fields.message);
+    this.name = "ApiError";
+    this.kind = fields.kind;
+    this.status = fields.status;
+    this.code = fields.code;
+    this.method = fields.method;
+    this.url = fields.url;
+    this.data = fields.data;
+    Object.defineProperty(this, RAW_ERROR, {
+      value: cause,
+      enumerable: false,
+      writable: false,
+      configurable: true
+    });
+    const captureStackTrace = Error.captureStackTrace;
+    captureStackTrace?.(this, _ApiError);
+  }
+  /**
+   * The original underlying error (e.g. the raw AxiosError) for deep debugging.
+   * Lives on a non-enumerable Symbol slot, so it is never printed by loggers.
+   */
+  get raw() {
+    return this[RAW_ERROR];
+  }
+  /** Controls what `JSON.stringify(err)` and most loggers emit — kept compact. */
+  toJSON() {
+    return {
+      kind: this.kind,
+      message: this.message,
+      status: this.status,
+      code: this.code,
+      method: this.method,
+      url: this.url,
+      data: this.data
+    };
+  }
+};
+function isApiError(error) {
+  return error instanceof ApiError;
+}
+function extractServerMessage(data, fallback) {
+  if (typeof data === "string" && data.trim()) return data;
+  if (data && typeof data === "object") {
+    const record = data;
+    const candidate = record.message ?? record.error ?? record.detail ?? record.title;
+    if (typeof candidate === "string" && candidate.trim()) return candidate;
+  }
+  return fallback;
+}
+function parseApiError(error) {
+  if (error instanceof ApiError) return error;
+  if (!axios.isAxiosError(error)) {
+    const message = error instanceof Error ? error.message : String(error);
+    return new ApiError({ kind: "unknown", message }, error);
+  }
+  const axiosError = error;
+  const method = axiosError.config?.method?.toUpperCase();
+  const url = axiosError.config?.url;
+  const code = axiosError.code;
+  if (axiosError.response) {
+    const { status, data } = axiosError.response;
+    const message = extractServerMessage(data, `Request failed with status ${status}`);
+    return new ApiError({ kind: "response", message, status, code, method, url, data }, error);
+  }
+  if (axiosError.request) {
+    const message = code === "ECONNABORTED" ? `Request timed out${url ? ` (${method} ${url})` : ""}` : `No response received${url ? ` from ${method} ${url}` : ""}`;
+    return new ApiError({ kind: "request", message, code, method, url }, error);
+  }
+  return new ApiError({ kind: "setup", message: axiosError.message, code, method, url }, error);
+}
+
 // src/modules/view/webSocket.ts
 var CLOSE_AUTH_REJECTED = 4401;
 var CLOSE_AUTH_UNAVAILABLE = 4503;
@@ -4453,10 +4529,14 @@ var API = class {
     if (tokenBearer) {
       this.defaultHeaders.setAuthorization(tokenBearer);
     }
-    this.client = axios.create({
+    this.client = axios2.create({
       baseURL: gatewayUrl,
       headers: this.defaultHeaders
     });
+    this.client.interceptors.response.use(
+      (response) => response,
+      (error) => Promise.reject(parseApiError(error))
+    );
     const getServicePath = (service) => {
       const baseUrl = services[service];
       const servicePath = processEnvironment === "localhost" ? "/" : `${service}/`;
@@ -4749,5 +4829,8 @@ var API = class {
 // src/index.ts
 var index_default = main_exports;
 export {
-  index_default as default
+  ApiError,
+  index_default as default,
+  isApiError,
+  parseApiError
 };

package/dist/lib/apiError.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Where the failure happened in the axios lifecycle.
+ *
+ * - `response` — the server replied with a non-2xx status (HTTP / application layer).
+ * - `request`  — the request was sent but no response came back (network, timeout, CORS, offline).
+ * - `setup`    — the request was never sent (bad config, invalid URL, serialization error).
+ * - `unknown`  — the thrown value was not an axios error at all.
+ */
+export type ApiErrorKind = 'response' | 'request' | 'setup' | 'unknown';
+export interface IApiErrorFields {
+    kind: ApiErrorKind;
+    message: string;
+    status?: number;
+    code?: string;
+    method?: string;
+    url?: string;
+    data?: unknown;
+}
+/**
+ * A compact, log-friendly error that replaces axios's huge error object.
+ *
+ * Only small primitives are kept as enumerable fields, so `console.log(err)`,
+ * `JSON.stringify(err)` and `err.stack` stay short. The original axios error is
+ * preserved on a non-enumerable Symbol slot, reachable via `err.raw` for deep
+ * debugging, but never dumped when the error is logged.
+ */
+export declare class ApiError extends Error {
+    readonly kind: ApiErrorKind;
+    /** HTTP status code, when the server responded. */
+    readonly status?: number;
+    /** Axios error code, e.g. 'ECONNABORTED', 'ERR_NETWORK', 'ERR_BAD_REQUEST'. */
+    readonly code?: string;
+    /** HTTP method of the failed request, uppercased. */
+    readonly method?: string;
+    /** Request URL (baseURL + path) of the failed request. */
+    readonly url?: string;
+    /** The server-provided error payload (response body), when present. */
+    readonly data?: unknown;
+    constructor(fields: IApiErrorFields, cause?: unknown);
+    /**
+     * The original underlying error (e.g. the raw AxiosError) for deep debugging.
+     * Lives on a non-enumerable Symbol slot, so it is never printed by loggers.
+     */
+    get raw(): unknown;
+    /** Controls what `JSON.stringify(err)` and most loggers emit — kept compact. */
+    toJSON(): IApiErrorFields;
+}
+/** Type guard for the simplified error. */
+export declare function isApiError(error: unknown): error is ApiError;
+/**
+ * Convert ANY thrown value into a compact {@link ApiError}.
+ *
+ * This is the single, DRY place that understands axios's four failure modes,
+ * so individual modules never have to inspect `error.response` / `error.request`
+ * themselves.
+ */
+export declare function parseApiError(error: unknown): ApiError;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nomalism-com/api",
   "description": "A nomalism API package for performing HTTP requests on API endpoints",
-  "version": "0.45.63",
+  "version": "0.45.65",
   "author": "Nomalism <it.nomalism@gmail.com> (https://https://nomalism.com/)",
   "license": "UNLICENSED",
   "type": "module",
@@ -27,15 +27,15 @@
     "axios": "^1.17.0"
   },
   "devDependencies": {
-    "@swc/core": "^1.15.40",
-    "@types/node": "^24.13.1",
+    "@swc/core": "^1.15.41",
+    "@types/node": "^24.13.2",
     "@typescript-eslint/eslint-plugin": "^8.61.0",
     "@typescript-eslint/parser": "^8.61.0",
     "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-prettier": "^5.5.6",
-    "prettier": "^3.8.3",
+    "prettier": "^3.8.4",
     "tsup": "^8.5.1"
   },
   "repository": {