typedapi-client-helpers 0.3.5 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 A small Fetch runtime and OpenAPI 3 TypeScript generator designed to work with `TypedApi.Swagger` on ASP.NET Core.
 
-## Version 0.3.5 highlights
+## Version 0.4.0 highlights
 
 * Supports `[TypedApiFilterForm]` endpoints through the `x-typedapi-filter-form` OpenAPI extension.
 * Generates grouped filter-form arguments containing normal query values and `FilterFormValues`.
@@ -14,6 +14,8 @@ A small Fetch runtime and OpenAPI 3 TypeScript generator designed to work with `
 * Consumes readable generic schema IDs such as `ApiPaginationResponseOfProjectModel`.
 * Generates method-specific unions from typed `ProblemDetails` error responses.
 * Validates TypedApi OpenAPI contract version 2.
+* Converts HTTP and transport failures into a readable `error: string` for toasts, while preserving the original typed body in `rawError`.
+* Formats ASP.NET Core validation errors, `ProblemDetails`, custom JSON/text errors, and unknown error objects without displaying `[object Object]`.
 
 ## Filter-form endpoints
 
@@ -165,9 +167,9 @@ export type EmailNotificationModel = NotificationModelBase & {
 };
 ```
 
-## Typed errors
+## Typed error contracts
 
-When the OpenAPI operation contains typed error response bodies, generated methods expose the union directly:
+When an OpenAPI operation documents an error body, the generated method keeps its error type (or union) for `rawError`. `error` is always a human-readable `string`, suitable for a toast:
 
 ```ts
 ApiResult<
@@ -176,10 +178,12 @@ ApiResult<
 >
 ```
 
+On failure, access the original documented payload through `result.rawError`; see [Error handling](#error-handling) for examples.
+
 ## Install
 
 ```bash
-npm install typedapi-client-helpers@0.3.5
+npm install typedapi-client-helpers@0.4.0
 ```
 
 The generator expects an OpenAPI 3.x document. Swagger 2.0 documents are rejected with a clear error.
@@ -470,40 +474,71 @@ It does not add:
 * `sortBy`
 * `sortDirection`
 
-## Typed errors
-
-When the OpenAPI document describes error response bodies, generated methods expose their generated type or union.
+## Error handling
 
-When no error schema is documented, the method uses `ApiHttpError` instead of `unknown`:
+Version 0.4.0 separates **display text** from **structured diagnostics** on every failed request:
 
 ```ts
-const result = await cancelOrder({
-  id,
-  reason,
-});
+const result = await cancelOrder({ id, reason });
 
 if (!result.ok) {
-  if (result.error.kind === "http") {
-    console.error(
-      result.error.status,
-      result.error.body,
-    );
-  } else {
-    console.error(result.error);
-  }
+  // Always text: safe to show in a toast, alert, or form message.
+  console.error(result.error);
+
+  // Original error body / transport failure, preserving types and details.
+  console.debug(result.rawError);
+  console.debug(result.status);
 }
 ```
 
-Structured client errors include:
+Use `result.error` (not `result.rawError`) for a toast, e.g. `toast.error(result.error)` if your app uses a toast library. This also applies in `onError` callbacks. Existing success results and `onSuccess` callbacks are unchanged.
 
-* Network errors
-* Aborted requests
-* Timeout errors
-* Malformed response errors
+Typical failure result:
+
+```ts
+{
+  ok: false,
+  status: 400,
+  response: undefined,
+  error: "Setting value validation failed:\n• SettingValues[4].IntValue: 'Card transaction count notification threshold' must be between 1 and 100000 (inclusive).",
+  rawError: {
+    title: "Setting value validation failed",
+    status: 400,
+    errors: {
+      "SettingValues[4].IntValue": [
+        "'Card transaction count notification threshold' must be between 1 and 100000 (inclusive).",
+      ],
+    },
+  },
+}
+```
 
-Malformed JSON is reported as a structured parse error instead of being cast to the expected response type.
+The error message includes **every validation message**, retaining its original field path; the example above is shortened to one field. Messages are deduplicated. Other supported shapes include:
 
-Exceptions thrown by consumer `onSuccess` and `onError` callbacks propagate normally.
+* ASP.NET Core `ValidationProblemDetails` and `HttpValidationProblemDetails`, `ModelState`, and validation arrays.
+* RFC 7807 `ProblemDetails` (`title` and `detail`).
+* JSON with `message`, `error`, `error_description`, or a nested `data` wrapper.
+* Text responses and JSON-encoded strings.
+* Undocumented/unknown JSON objects (formatted JSON rather than `[object Object]`).
+* Empty HTTP error bodies (status-specific messages), binary bodies, network/abort/timeout errors, and malformed JSON.
+
+For an HTTP response **without a documented OpenAPI error schema**, generated methods use `ApiHttpError` as the *typed raw error* instead of `unknown`. `result.rawError` can contain `{ kind: "http", status, body }`. Other client-generated raw errors have `kind: "network"`, `"aborted"`, or `"parse"`.
+
+You can also format a payload outside the API client:
+
+```ts
+import { formatApiError } from "typedapi-client-helpers";
+
+const message = formatApiError(
+  { title: "Validation failed", errors: { Email: ["Email is required"] } },
+  400,
+);
+// "Validation failed:\n• Email: Email is required"
+```
+
+`handleApiResponse` supports a caller-provided `fallbackErrorMessage`, used when no usable error text or HTTP status is available. Unknown nonempty responses retain their content instead of being replaced by that fallback.
+
+Malformed JSON yields a readable parsing error and preserves its raw response body in `rawError`. Exceptions thrown by consumer `onSuccess` or `onError` callbacks still propagate normally. See [`src/utils/README.md`](src/utils/README.md) and [`src/interfaces/README.md`](src/interfaces/README.md) for the full result shape.
 
 ## Runtime configuration
 
@@ -538,13 +573,14 @@ The runtime also exports:
 * `toRequestHeaders`
 * `toCookieHeader`
 * `handleApiResponse`
+* `formatApiError`
 * `buildFilterQuery`
 * `buildQuery`
 * `toFormData`
 
 ## Backend pairing
 
-Use `TypedApi.Swagger` 0.3.2 or newer on the backend for:
+Use `TypedApi.Swagger` 0.3.3 (or a compatible newer release) on the backend for:
 
 * `[TypedApiFilterForm]`
 * Generic reconstruction
@@ -556,3 +592,7 @@ Use `TypedApi.Swagger` 0.3.2 or newer on the backend for:
 The backend package emits `x-typedapi-filter-form` for opted-in filter endpoints.
 
 It also emits `x-typedapi.contractVersion = 2` for contract compatibility. The generator validates the contract version before replacing generated files.
+
+## Tests
+
+For the npm package alone, run `npm run verify` from `npm/typed-api-client` to type-check, build, and run **every** `test/*.test.mjs` file. From the repository root, `npm test` runs the npm suite, test client lint/build, .NET tests, and real HTTP integration tests. See [`../../TESTING.md`](../../TESTING.md) for prerequisites and details.

package/dist/cjs/index.js

@@ -22,6 +22,7 @@ __exportStar(require("./types/ApiMethodTypes"), exports);
 __exportStar(require("./types/ApiCallOptions"), exports);
 __exportStar(require("./types/ApiMethodOptions"), exports);
 __exportStar(require("./utils/buildQuery"), exports);
+__exportStar(require("./utils/formatApiError"), exports);
 __exportStar(require("./utils/handleApiResponse"), exports);
 __exportStar(require("./utils/SortTypeFromSortDirection"), exports);
 __exportStar(require("./utils/toFormData"), exports);

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAE7B,yDAAuC;AACvC,sDAAoC;AACpC,wDAAsC;AAEtC,yDAAuC;AACvC,yDAAuC;AACvC,2DAAyC;AAEzC,qDAAmC;AACnC,4DAA0C;AAC1C,oEAAkD;AAClD,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,+CAA6B;AAE7B,yDAAuC;AACvC,sDAAoC;AACpC,wDAAsC;AAEtC,yDAAuC;AACvC,yDAAuC;AACvC,2DAAyC;AAEzC,qDAAmC;AACnC,yDAAuC;AACvC,4DAA0C;AAC1C,oEAAkD;AAClD,qDAAmC"}

package/dist/cjs/utils/formatApiError.js

@@ -0,0 +1,215 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatApiError = formatApiError;
+/** Format API errors for notifications without discarding the original payload. */
+const defaultErrorMessage = "An unknown error occurred.";
+const statusMessages = {
+    400: "Bad request",
+    401: "Authentication required",
+    403: "Access denied",
+    404: "Resource not found",
+    405: "Method not allowed",
+    408: "Request timed out",
+    409: "Conflict",
+    413: "Request too large",
+    415: "Unsupported media type",
+    422: "Validation failed",
+    429: "Too many requests",
+    500: "Internal server error",
+    502: "Bad gateway",
+    503: "Service unavailable",
+    504: "Gateway timeout",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function property(record, key) {
+    if (Object.prototype.hasOwnProperty.call(record, key))
+        return record[key];
+    const matchingKey = Object.keys(record).find((candidate) => candidate.toLowerCase() === key.toLowerCase());
+    return matchingKey === undefined ? undefined : record[matchingKey];
+}
+function nonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function readableJson(value) {
+    const seen = new WeakSet();
+    try {
+        const json = JSON.stringify(value, (_key, entry) => {
+            if (typeof entry === "bigint")
+                return entry.toString();
+            if (entry instanceof Error)
+                return { name: entry.name, message: entry.message };
+            if (entry && typeof entry === "object") {
+                if (seen.has(entry))
+                    return "[Circular]";
+                seen.add(entry);
+            }
+            return entry;
+        }, 2);
+        if (json && json !== "{}" && json !== "[]")
+            return json;
+    }
+    catch {
+        // Non-serializable input; use a status-based fallback below.
+    }
+    return undefined;
+}
+function parseJsonLikeString(text) {
+    if (!text.startsWith("{") && !text.startsWith("["))
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** ASP.NET ValidationProblemDetails, ModelState and common errors arrays. */
+function validationMessages(value) {
+    const messages = [];
+    const seen = new WeakSet();
+    let visited = 0;
+    function visit(current, field) {
+        if (++visited > 500 || current === null || current === undefined)
+            return;
+        if (typeof current === "string" || typeof current === "number" || typeof current === "boolean") {
+            const message = String(current).trim();
+            if (message)
+                messages.push(field ? `${field}: ${message}` : message);
+            return;
+        }
+        if (typeof current !== "object" || current instanceof Blob || seen.has(current))
+            return;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            for (const item of current)
+                visit(item, field);
+            return;
+        }
+        const record = current;
+        const message = nonEmptyString(property(record, "message"))
+            ?? nonEmptyString(property(record, "errorMessage"))
+            ?? nonEmptyString(property(record, "description"));
+        if (message) {
+            const specificField = nonEmptyString(property(record, "field"))
+                ?? nonEmptyString(property(record, "property"))
+                ?? nonEmptyString(property(record, "propertyName"))
+                ?? field;
+            messages.push(specificField ? `${specificField}: ${message}` : message);
+            return;
+        }
+        for (const [key, child] of Object.entries(record)) {
+            // Preserve the validation property path rather than collapsing all messages into "[object Object]".
+            visit(child, field ? `${field}.${key}` : key);
+        }
+    }
+    visit(value);
+    return [...new Set(messages)];
+}
+function fallback(status, fallbackMessage) {
+    const statusText = status ? statusMessages[status] : undefined;
+    if (statusText)
+        return `${statusText} (HTTP ${status}).`;
+    if (status)
+        return `Request failed (HTTP ${status}).`;
+    return nonEmptyString(fallbackMessage) ?? defaultErrorMessage;
+}
+/**
+ * Produce a readable string for .NET ProblemDetails, validation failures, plain-text
+ * errors, transport errors and unknown response shapes. Unknown payloads are returned
+ * as formatted JSON rather than being converted to "[object Object]".
+ */
+function formatApiError(error, status, fallbackMessage) {
+    const seen = new WeakSet();
+    function format(value, depth, httpStatus) {
+        if (depth > 10 || value === null || value === undefined)
+            return undefined;
+        if (typeof value === "string") {
+            const trimmed = value.trim();
+            if (!trimmed)
+                return undefined;
+            const parsed = parseJsonLikeString(trimmed);
+            return parsed === trimmed ? trimmed : format(parsed, depth + 1, httpStatus) ?? trimmed;
+        }
+        if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+            return String(value);
+        }
+        if (value instanceof Error) {
+            return nonEmptyString(value.message)
+                ? `${value.name && value.name !== "Error" ? `${value.name}: ` : ""}${value.message}`
+                : value.name;
+        }
+        if (value instanceof Blob)
+            return `Server returned a ${value.type || "binary"} error response (${value.size} bytes).`;
+        if (typeof value !== "object" || seen.has(value))
+            return undefined;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            const entries = value.map((item) => format(item, depth + 1, httpStatus)).filter((item) => !!item);
+            if (entries.length)
+                return entries.map((entry) => `• ${entry}`).join("\n");
+            return readableJson(value);
+        }
+        const record = value;
+        const kind = nonEmptyString(property(record, "kind"));
+        if (kind === "http") {
+            const wrappedStatus = property(record, "status");
+            const code = typeof wrappedStatus === "number" ? wrappedStatus : httpStatus;
+            return format(property(record, "body"), depth + 1, code) ?? fallback(code, fallbackMessage);
+        }
+        if (kind === "parse") {
+            const rawBody = nonEmptyString(property(record, "rawBody"));
+            const code = property(record, "status");
+            return `Invalid server response${typeof code === "number" ? ` (HTTP ${code})` : ""}: expected valid JSON${rawBody ? `. Received: ${rawBody}` : "."}`;
+        }
+        if (kind === "aborted")
+            return "Request was cancelled or timed out.";
+        if (kind === "network") {
+            const cause = format(property(record, "cause"), depth + 1, httpStatus);
+            return cause ? `Network error: ${cause}` : "Network error: Could not reach the server.";
+        }
+        const nestedData = property(record, "data");
+        const hasOwnMessage = property(record, "message") !== undefined
+            || property(record, "detail") !== undefined
+            || property(record, "title") !== undefined
+            || property(record, "errors") !== undefined;
+        if (!hasOwnMessage && nestedData !== undefined) {
+            const result = format(nestedData, depth + 1, httpStatus);
+            if (result)
+                return result;
+        }
+        const title = nonEmptyString(property(record, "title"));
+        const detail = nonEmptyString(property(record, "detail"));
+        const message = nonEmptyString(property(record, "message"))
+            ?? nonEmptyString(property(record, "error_description"))
+            ?? nonEmptyString(property(record, "description"));
+        const errors = property(record, "errors") ?? property(record, "modelState");
+        const validation = errors === undefined ? [] : validationMessages(errors);
+        if (validation.length) {
+            const heading = title ?? message ?? detail ?? "Validation failed";
+            return `${heading}:\n${validation.map((entry) => `• ${entry}`).join("\n")}`;
+        }
+        if (detail && title && detail.toLowerCase() !== title.toLowerCase())
+            return `${title}: ${detail}`;
+        if (detail)
+            return detail;
+        if (message)
+            return message;
+        if (title)
+            return title;
+        const nestedError = property(record, "error");
+        if (nestedError !== undefined) {
+            const formatted = format(nestedError, depth + 1, httpStatus);
+            if (formatted)
+                return formatted;
+        }
+        // Do not discard undocumented error objects. Display their original fields.
+        return readableJson(value);
+    }
+    return format(error, 0, status) ?? fallback(status, fallbackMessage);
+}
+//# sourceMappingURL=formatApiError.js.map

package/dist/cjs/utils/formatApiError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatApiError.js","sourceRoot":"","sources":["../../../src/utils/formatApiError.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/handleApiResponse.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createApiHttpError = createApiHttpError;
 exports.handleApiResponse = handleApiResponse;
-const defaultUnknownErrorMessage = "An unknown error occurred.";
+const formatApiError_1 = require("./formatApiError");
 class ResponseParseError extends Error {
     constructor(status, rawBody, parseCause) {
         super(`Could not parse JSON response with status ${status}.`);
@@ -49,7 +49,8 @@ function createApiHttpError(status, body) {
         body: body,
     };
 }
-function clientError(error, fallbackErrorMessage) {
+/** Preserve the transport or parsing failure for callers that need details. */
+function clientError(error) {
     if (error instanceof ResponseParseError) {
         return {
             kind: "parse",
@@ -64,7 +65,17 @@ function clientError(error, fallbackErrorMessage) {
     if (name === "AbortError" || name === "TimeoutError") {
         return { kind: "aborted", cause: error };
     }
-    return fallbackErrorMessage ?? defaultUnknownErrorMessage;
+    return { kind: "network", cause: error };
+}
+/** Return an error as readable text but keep the original typed payload in `rawError`. */
+function failure(status, rawError, fallbackErrorMessage) {
+    return {
+        ok: false,
+        status,
+        response: undefined,
+        error: (0, formatApiError_1.formatApiError)(rawError, status || undefined, fallbackErrorMessage),
+        rawError,
+    };
 }
 async function handleApiResponse(call, options) {
     let result;
@@ -82,12 +93,7 @@ async function handleApiResponse(call, options) {
             };
         }
         catch (error) {
-            result = {
-                ok: false,
-                status: response.status,
-                response: undefined,
-                error: clientError(error, options?.fallbackErrorMessage),
-            };
+            result = failure(response.status, clientError(error), options?.fallbackErrorMessage);
         }
     }
     catch (error) {
@@ -98,31 +104,16 @@ async function handleApiResponse(call, options) {
                     ? options.transformError(rawErrorData, error)
                     : rawErrorData;
                 const errorData = transformedError === undefined
-                    ? options?.fallbackErrorMessage ?? defaultUnknownErrorMessage
+                    ? createApiHttpError(error.status, undefined)
                     : transformedError;
-                result = {
-                    ok: false,
-                    status: error.status,
-                    response: undefined,
-                    error: errorData,
-                };
+                result = failure(error.status, errorData, options?.fallbackErrorMessage);
             }
             catch (parseError) {
-                result = {
-                    ok: false,
-                    status: error.status,
-                    response: undefined,
-                    error: clientError(parseError, options?.fallbackErrorMessage),
-                };
+                result = failure(error.status, clientError(parseError), options?.fallbackErrorMessage);
             }
         }
         else {
-            result = {
-                ok: false,
-                status: 0,
-                response: undefined,
-                error: clientError(error, options?.fallbackErrorMessage),
-            };
+            result = failure(0, clientError(error), options?.fallbackErrorMessage);
         }
     }
     // Consumer callbacks intentionally execute outside the request-catching block.

package/dist/cjs/utils/handleApiResponse.js.map

@@ -1 +1 @@
-{"version":3,"file":"handleApiResponse.js","sourceRoot":"","sources":["../../../src/utils/handleApiResponse.ts"],"names":[],"mappings":";;AAgEA,gDAMC;AAwBD,8CAkEC;AA5JD,MAAM,0BAA0B,GAAG,4BAA4B,CAAC;AAUhE,MAAM,kBAAmB,SAAQ,KAAK;IACpC,YACW,MAAc,EACd,OAAe,EACf,UAAmB;QAE5B,KAAK,CAAC,6CAA6C,MAAM,GAAG,CAAC,CAAC;QAJrD,WAAM,GAAN,MAAM,CAAQ;QACd,YAAO,GAAP,OAAO,CAAQ;QACf,eAAU,GAAV,UAAU,CAAS;QAG5B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED,KAAK,UAAU,gBAAgB,CAC7B,QAAkB;IAElB,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG;QAAE,OAAO,SAAS,CAAC;IAEzE,MAAM,WAAW,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC9E,IACE,WAAW,CAAC,QAAQ,CAAC,0BAA0B,CAAC;QAChD,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC;QAChC,WAAW,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EACvC,CAAC;QACD,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;IACnC,IAAI,CAAC,IAAI;QAAE,OAAO,SAAS,CAAC;IAE5B,IAAI,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAClE,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;QAC/B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,kBAAkB,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACd,QAAQ,IAAI,KAAK;QACjB,IAAI,IAAI,KAAK;QACb,SAAS,IAAI,KAAK;QAClB,OAAQ,KAAkB,CAAC,IAAI,KAAK,UAAU,CAC/C,CAAC;AACJ,CAAC;AAED,SAAgB,kBAAkB,CAAC,MAAc,EAAE,IAAa;IAC9D,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,MAAM;QACN,IAAI,EAAE,IAAwB;KAC/B,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,KAAc,EAAE,oBAA6B;IAChE,IAAI,KAAK,YAAY,kBAAkB,EAAE,CAAC;QACxC,OAAO;YACL,IAAI,EAAE,OAAO;YACb,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,KAAK,EAAE,KAAK,CAAC,UAAU;SACxB,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GACR,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK;QAC5D,CAAC,CAAC,MAAM,CAAE,KAA4B,CAAC,IAAI,CAAC;QAC5C,CAAC,CAAC,EAAE,CAAC;IAET,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;QACrD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED,OAAO,oBAAoB,IAAI,0BAA0B,CAAC;AAC5D,CAAC;AAEM,KAAK,UAAU,iBAAiB,CACrC,IAAoD,EACpD,OAAqD;IAErD,IAAI,MAAoC,CAAC;IAEzC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,gBAAgB,CAAU,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;YAClE,MAAM,IAAI,GAAG,OAAO,EAAE,iBAAiB;gBACrC,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC;gBACpC,CAAC,CAAC,OAAoB,CAAC;YACzB,MAAM,GAAG;gBACP,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,QAAQ,EAAE,IAAI;aACf,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,GAAG;gBACP,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,QAAQ,EAAE,SAAS;gBACnB,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,oBAAoB,CAAC;aACzD,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,MAAM,YAAY,GAAG,MAAM,gBAAgB,CAAU,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;gBACpE,MAAM,gBAAgB,GAAG,OAAO,EAAE,cAAc;oBAC9C,CAAC,CAAC,OAAO,CAAC,cAAc,CAAC,YAAY,EAAE,KAAK,CAAC;oBAC7C,CAAC,CAAC,YAAsB,CAAC;gBAC3B,MAAM,SAAS,GAAG,gBAAgB,KAAK,SAAS;oBAC9C,CAAC,CAAC,OAAO,EAAE,oBAAoB,IAAI,0BAA0B;oBAC7D,CAAC,CAAC,gBAAgB,CAAC;gBACrB,MAAM,GAAG;oBACP,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,QAAQ,EAAE,SAAS;oBACnB,KAAK,EAAE,SAAS;iBACjB,CAAC;YACJ,CAAC;YAAC,OAAO,UAAU,EAAE,CAAC;gBACpB,MAAM,GAAG;oBACP,EAAE,EAAE,KAAK;oBACT,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,QAAQ,EAAE,SAAS;oBACnB,KAAK,EAAE,WAAW,CAAC,UAAU,EAAE,OAAO,EAAE,oBAAoB,CAAC;iBAC9D,CAAC;YACJ,CAAC;QACH,CAAC;aAAM,CAAC;YACN,MAAM,GAAG;gBACP,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,CAAC;gBACT,QAAQ,EAAE,SAAS;gBACnB,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,oBAAoB,CAAC;aACzD,CAAC;QACJ,CAAC;IACH,CAAC;IAED,+EAA+E;IAC/E,uFAAuF;IACvF,IAAI,MAAM,CAAC,EAAE;QAAE,MAAM,OAAO,EAAE,SAAS,EAAE,CAAC,MAAM,CAAC,CAAC;;QAC7C,MAAM,OAAO,EAAE,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IAEtC,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"handleApiResponse.js","sourceRoot":"","sources":["../../../src/utils/handleApiResponse.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -6,6 +6,7 @@ export * from "./types/ApiMethodTypes.js";
 export * from "./types/ApiCallOptions.js";
 export * from "./types/ApiMethodOptions.js";
 export * from "./utils/buildQuery.js";
+export * from "./utils/formatApiError.js";
 export * from "./utils/handleApiResponse.js";
 export * from "./utils/SortTypeFromSortDirection.js";
 export * from "./utils/toFormData.js";

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAE7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAE7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,oBAAoB,CAAC"}

package/dist/esm/utils/formatApiError.js

@@ -0,0 +1,212 @@
+/** Format API errors for notifications without discarding the original payload. */
+const defaultErrorMessage = "An unknown error occurred.";
+const statusMessages = {
+    400: "Bad request",
+    401: "Authentication required",
+    403: "Access denied",
+    404: "Resource not found",
+    405: "Method not allowed",
+    408: "Request timed out",
+    409: "Conflict",
+    413: "Request too large",
+    415: "Unsupported media type",
+    422: "Validation failed",
+    429: "Too many requests",
+    500: "Internal server error",
+    502: "Bad gateway",
+    503: "Service unavailable",
+    504: "Gateway timeout",
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function property(record, key) {
+    if (Object.prototype.hasOwnProperty.call(record, key))
+        return record[key];
+    const matchingKey = Object.keys(record).find((candidate) => candidate.toLowerCase() === key.toLowerCase());
+    return matchingKey === undefined ? undefined : record[matchingKey];
+}
+function nonEmptyString(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function readableJson(value) {
+    const seen = new WeakSet();
+    try {
+        const json = JSON.stringify(value, (_key, entry) => {
+            if (typeof entry === "bigint")
+                return entry.toString();
+            if (entry instanceof Error)
+                return { name: entry.name, message: entry.message };
+            if (entry && typeof entry === "object") {
+                if (seen.has(entry))
+                    return "[Circular]";
+                seen.add(entry);
+            }
+            return entry;
+        }, 2);
+        if (json && json !== "{}" && json !== "[]")
+            return json;
+    }
+    catch {
+        // Non-serializable input; use a status-based fallback below.
+    }
+    return undefined;
+}
+function parseJsonLikeString(text) {
+    if (!text.startsWith("{") && !text.startsWith("["))
+        return text;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** ASP.NET ValidationProblemDetails, ModelState and common errors arrays. */
+function validationMessages(value) {
+    const messages = [];
+    const seen = new WeakSet();
+    let visited = 0;
+    function visit(current, field) {
+        if (++visited > 500 || current === null || current === undefined)
+            return;
+        if (typeof current === "string" || typeof current === "number" || typeof current === "boolean") {
+            const message = String(current).trim();
+            if (message)
+                messages.push(field ? `${field}: ${message}` : message);
+            return;
+        }
+        if (typeof current !== "object" || current instanceof Blob || seen.has(current))
+            return;
+        seen.add(current);
+        if (Array.isArray(current)) {
+            for (const item of current)
+                visit(item, field);
+            return;
+        }
+        const record = current;
+        const message = nonEmptyString(property(record, "message"))
+            ?? nonEmptyString(property(record, "errorMessage"))
+            ?? nonEmptyString(property(record, "description"));
+        if (message) {
+            const specificField = nonEmptyString(property(record, "field"))
+                ?? nonEmptyString(property(record, "property"))
+                ?? nonEmptyString(property(record, "propertyName"))
+                ?? field;
+            messages.push(specificField ? `${specificField}: ${message}` : message);
+            return;
+        }
+        for (const [key, child] of Object.entries(record)) {
+            // Preserve the validation property path rather than collapsing all messages into "[object Object]".
+            visit(child, field ? `${field}.${key}` : key);
+        }
+    }
+    visit(value);
+    return [...new Set(messages)];
+}
+function fallback(status, fallbackMessage) {
+    const statusText = status ? statusMessages[status] : undefined;
+    if (statusText)
+        return `${statusText} (HTTP ${status}).`;
+    if (status)
+        return `Request failed (HTTP ${status}).`;
+    return nonEmptyString(fallbackMessage) ?? defaultErrorMessage;
+}
+/**
+ * Produce a readable string for .NET ProblemDetails, validation failures, plain-text
+ * errors, transport errors and unknown response shapes. Unknown payloads are returned
+ * as formatted JSON rather than being converted to "[object Object]".
+ */
+export function formatApiError(error, status, fallbackMessage) {
+    const seen = new WeakSet();
+    function format(value, depth, httpStatus) {
+        if (depth > 10 || value === null || value === undefined)
+            return undefined;
+        if (typeof value === "string") {
+            const trimmed = value.trim();
+            if (!trimmed)
+                return undefined;
+            const parsed = parseJsonLikeString(trimmed);
+            return parsed === trimmed ? trimmed : format(parsed, depth + 1, httpStatus) ?? trimmed;
+        }
+        if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+            return String(value);
+        }
+        if (value instanceof Error) {
+            return nonEmptyString(value.message)
+                ? `${value.name && value.name !== "Error" ? `${value.name}: ` : ""}${value.message}`
+                : value.name;
+        }
+        if (value instanceof Blob)
+            return `Server returned a ${value.type || "binary"} error response (${value.size} bytes).`;
+        if (typeof value !== "object" || seen.has(value))
+            return undefined;
+        seen.add(value);
+        if (Array.isArray(value)) {
+            const entries = value.map((item) => format(item, depth + 1, httpStatus)).filter((item) => !!item);
+            if (entries.length)
+                return entries.map((entry) => `• ${entry}`).join("\n");
+            return readableJson(value);
+        }
+        const record = value;
+        const kind = nonEmptyString(property(record, "kind"));
+        if (kind === "http") {
+            const wrappedStatus = property(record, "status");
+            const code = typeof wrappedStatus === "number" ? wrappedStatus : httpStatus;
+            return format(property(record, "body"), depth + 1, code) ?? fallback(code, fallbackMessage);
+        }
+        if (kind === "parse") {
+            const rawBody = nonEmptyString(property(record, "rawBody"));
+            const code = property(record, "status");
+            return `Invalid server response${typeof code === "number" ? ` (HTTP ${code})` : ""}: expected valid JSON${rawBody ? `. Received: ${rawBody}` : "."}`;
+        }
+        if (kind === "aborted")
+            return "Request was cancelled or timed out.";
+        if (kind === "network") {
+            const cause = format(property(record, "cause"), depth + 1, httpStatus);
+            return cause ? `Network error: ${cause}` : "Network error: Could not reach the server.";
+        }
+        const nestedData = property(record, "data");
+        const hasOwnMessage = property(record, "message") !== undefined
+            || property(record, "detail") !== undefined
+            || property(record, "title") !== undefined
+            || property(record, "errors") !== undefined;
+        if (!hasOwnMessage && nestedData !== undefined) {
+            const result = format(nestedData, depth + 1, httpStatus);
+            if (result)
+                return result;
+        }
+        const title = nonEmptyString(property(record, "title"));
+        const detail = nonEmptyString(property(record, "detail"));
+        const message = nonEmptyString(property(record, "message"))
+            ?? nonEmptyString(property(record, "error_description"))
+            ?? nonEmptyString(property(record, "description"));
+        const errors = property(record, "errors") ?? property(record, "modelState");
+        const validation = errors === undefined ? [] : validationMessages(errors);
+        if (validation.length) {
+            const heading = title ?? message ?? detail ?? "Validation failed";
+            return `${heading}:\n${validation.map((entry) => `• ${entry}`).join("\n")}`;
+        }
+        if (detail && title && detail.toLowerCase() !== title.toLowerCase())
+            return `${title}: ${detail}`;
+        if (detail)
+            return detail;
+        if (message)
+            return message;
+        if (title)
+            return title;
+        const nestedError = property(record, "error");
+        if (nestedError !== undefined) {
+            const formatted = format(nestedError, depth + 1, httpStatus);
+            if (formatted)
+                return formatted;
+        }
+        // Do not discard undocumented error objects. Display their original fields.
+        return readableJson(value);
+    }
+    return format(error, 0, status) ?? fallback(status, fallbackMessage);
+}
+//# sourceMappingURL=formatApiError.js.map

package/dist/esm/utils/formatApiError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatApiError.js","sourceRoot":"","sources":["../../../src/utils/formatApiError.ts"],"names":[],"mappings":"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"}

package/dist/esm/utils/handleApiResponse.js

@@ -1,4 +1,4 @@
-const defaultUnknownErrorMessage = "An unknown error occurred.";
+import { formatApiError } from "./formatApiError.js";
 class ResponseParseError extends Error {
     constructor(status, rawBody, parseCause) {
         super(`Could not parse JSON response with status ${status}.`);
@@ -45,7 +45,8 @@ export function createApiHttpError(status, body) {
         body: body,
     };
 }
-function clientError(error, fallbackErrorMessage) {
+/** Preserve the transport or parsing failure for callers that need details. */
+function clientError(error) {
     if (error instanceof ResponseParseError) {
         return {
             kind: "parse",
@@ -60,7 +61,17 @@ function clientError(error, fallbackErrorMessage) {
     if (name === "AbortError" || name === "TimeoutError") {
         return { kind: "aborted", cause: error };
     }
-    return fallbackErrorMessage ?? defaultUnknownErrorMessage;
+    return { kind: "network", cause: error };
+}
+/** Return an error as readable text but keep the original typed payload in `rawError`. */
+function failure(status, rawError, fallbackErrorMessage) {
+    return {
+        ok: false,
+        status,
+        response: undefined,
+        error: formatApiError(rawError, status || undefined, fallbackErrorMessage),
+        rawError,
+    };
 }
 export async function handleApiResponse(call, options) {
     let result;
@@ -78,12 +89,7 @@ export async function handleApiResponse(call, options) {
             };
         }
         catch (error) {
-            result = {
-                ok: false,
-                status: response.status,
-                response: undefined,
-                error: clientError(error, options?.fallbackErrorMessage),
-            };
+            result = failure(response.status, clientError(error), options?.fallbackErrorMessage);
         }
     }
     catch (error) {
@@ -94,31 +100,16 @@ export async function handleApiResponse(call, options) {
                     ? options.transformError(rawErrorData, error)
                     : rawErrorData;
                 const errorData = transformedError === undefined
-                    ? options?.fallbackErrorMessage ?? defaultUnknownErrorMessage
+                    ? createApiHttpError(error.status, undefined)
                     : transformedError;
-                result = {
-                    ok: false,
-                    status: error.status,
-                    response: undefined,
-                    error: errorData,
-                };
+                result = failure(error.status, errorData, options?.fallbackErrorMessage);
             }
             catch (parseError) {
-                result = {
-                    ok: false,
-                    status: error.status,
-                    response: undefined,
-                    error: clientError(parseError, options?.fallbackErrorMessage),
-                };
+                result = failure(error.status, clientError(parseError), options?.fallbackErrorMessage);
             }
         }
         else {
-            result = {
-                ok: false,
-                status: 0,
-                response: undefined,
-                error: clientError(error, options?.fallbackErrorMessage),
-            };
+            result = failure(0, clientError(error), options?.fallbackErrorMessage);
         }
     }
     // Consumer callbacks intentionally execute outside the request-catching block.

package/dist/esm/utils/handleApiResponse.js.map

@@ -1 +1 @@
-{"version":3,"file":"handleApiResponse.js","sourceRoot":"","sources":["../../../src/utils/handleApiResponse.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"handleApiResponse.js","sourceRoot":"","sources":["../../../src/utils/handleApiResponse.ts"],"names":[],"mappings":"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"}

package/dist/types/index.d.ts

@@ -6,6 +6,7 @@ export * from "./types/ApiMethodTypes";
 export * from "./types/ApiCallOptions";
 export * from "./types/ApiMethodOptions";
 export * from "./utils/buildQuery";
+export * from "./utils/formatApiError";
 export * from "./utils/handleApiResponse";
 export * from "./utils/SortTypeFromSortDirection";
 export * from "./utils/toFormData";

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAE7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAE7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AAEtC,cAAc,wBAAwB,CAAC;AACvC,cAAc,wBAAwB,CAAC;AACvC,cAAc,0BAA0B,CAAC;AAEzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mCAAmC,CAAC;AAClD,cAAc,oBAAoB,CAAC"}

package/dist/types/interfaces/ApiResult.d.ts

@@ -26,11 +26,15 @@ export type ApiResult<TResponse, TError = unknown> = {
     status: number;
     response: TResponse;
     error?: never;
+    rawError?: never;
 } | {
     ok: false;
     status: number;
     response?: undefined;
-    error: TError | ApiClientError | string;
+    /** Human-readable error text, safe for toast notifications and UI messages. */
+    error: string;
+    /** Original typed error response or client error, without information loss. */
+    rawError: TError | ApiHttpError | ApiClientError | string;
 };
 export type ApiSuccessResult<TResponse, TError = unknown> = Extract<ApiResult<TResponse, TError>, {
     ok: true;

package/dist/types/interfaces/ApiResult.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ApiResult.d.ts","sourceRoot":"","sources":["../../../src/interfaces/ApiResult.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,IAAI,GACJ,SAAS,GACT,gBAAgB,EAAE,GAClB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAExC,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEN,yEAAyE;AACzE,MAAM,MAAM,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAC7C;IACE,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,KAAK,EAAE,MAAM,GAAG,cAAc,GAAG,MAAM,CAAC;CACzC,CAAC;AAEN,MAAM,MAAM,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAAI,OAAO,CACjE,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,EAC5B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CACb,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAAI,OAAO,CAC/D,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,EAC5B;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CACd,CAAC"}
+{"version":3,"file":"ApiResult.d.ts","sourceRoot":"","sources":["../../../src/interfaces/ApiResult.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GACxB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,IAAI,GACJ,SAAS,GACT,gBAAgB,EAAE,GAClB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAAA;CAAE,CAAC;AAExC,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,gBAAgB,CAAC;CACxB,CAAC;AAEF,0FAA0F;AAC1F,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB,CAAC;AAEN,yEAAyE;AACzE,MAAM,MAAM,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAC7C;IACE,EAAE,EAAE,IAAI,CAAC;IACT,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;IACpB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,CAAC;CAClB,GACD;IACE,EAAE,EAAE,KAAK,CAAC;IACV,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,+EAA+E;IAC/E,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,cAAc,GAAG,MAAM,CAAC;CAC3D,CAAC;AAEN,MAAM,MAAM,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAAI,OAAO,CACjE,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,EAC5B;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CACb,CAAC;AAEF,MAAM,MAAM,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAAI,OAAO,CAC/D,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,EAC5B;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CACd,CAAC"}

package/dist/types/utils/formatApiError.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Produce a readable string for .NET ProblemDetails, validation failures, plain-text
+ * errors, transport errors and unknown response shapes. Unknown payloads are returned
+ * as formatted JSON rather than being converted to "[object Object]".
+ */
+export declare function formatApiError(error: unknown, status?: number, fallbackMessage?: string): string;
+//# sourceMappingURL=formatApiError.d.ts.map

package/dist/types/utils/formatApiError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatApiError.d.ts","sourceRoot":"","sources":["../../../src/utils/formatApiError.ts"],"names":[],"mappings":"AAmHA;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAqFhG"}

package/dist/types/utils/handleApiResponse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handleApiResponse.d.ts","sourceRoot":"","sources":["../../../src/utils/handleApiResponse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAoB,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzG,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD,MAAM,MAAM,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAAI;IAClE,SAAS,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC7C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,CAAC;IAClD,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC;IAChE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAoDF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CAM9E;AAwBD,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EACjE,IAAI,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,EACpD,OAAO,CAAC,EAAE,wBAAwB,CAAC,SAAS,EAAE,MAAM,CAAC,GACpD,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CA+DvC"}
+{"version":3,"file":"handleApiResponse.d.ts","sourceRoot":"","sources":["../../../src/utils/handleApiResponse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAoB,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzG,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAClF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAGlD,MAAM,MAAM,wBAAwB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,IAAI;IAClE,SAAS,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAC7C,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,SAAS,CAAC;IAClD,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,KAAK,MAAM,CAAC;IAChE,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B,CAAC;AAkDF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,YAAY,CAM9E;AAuCD,wBAAsB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,EACjE,IAAI,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,EACpD,OAAO,CAAC,EAAE,wBAAwB,CAAC,SAAS,EAAE,MAAM,CAAC,GACpD,OAAO,CAAC,SAAS,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CA0CvC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedapi-client-helpers",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Reusable typed OpenAPI client helpers.",
   "license": "MIT",
   "keywords": [

package/scripts/generate-api-minimal.mjs

@@ -2,7 +2,10 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { generateApi } from "./openapi-generator/index.mjs";
+import {
+  cleanupGenerationArtifacts,
+  generateApi,
+} from "./openapi-generator/index.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -93,6 +96,28 @@ const apiRoot = path.resolve(
   ),
 );
 
+let terminationSignalHandled = false;
+
+function handleTerminationSignal(signal) {
+  if (terminationSignalHandled) return;
+
+  terminationSignalHandled = true;
+
+  try {
+    cleanupGenerationArtifacts(apiRoot);
+  } catch (error) {
+    console.error(
+      `Failed to clean TypedApi temporary files after ${signal}:`,
+      error,
+    );
+  }
+
+  process.exit(signal === "SIGINT" ? 130 : 143);
+}
+
+process.once("SIGINT", () => handleTerminationSignal("SIGINT"));
+process.once("SIGTERM", () => handleTerminationSignal("SIGTERM"));
+
 const methodsDir = path.join(apiRoot, "methods");
 
 const defaultFunctionsPathSetting = getStringSetting(
@@ -222,7 +247,8 @@ function getMethodNameStyle(...values) {
   const normalized = value.replace(/[\s_-]/g, "").toLowerCase();
 
   if (["operationid", "operation"].includes(normalized)) return "operationId";
-  if (["action", "actionname", "controllermethod"].includes(normalized)) return "action";
+  if (["action", "actionname", "controllermethod"].includes(normalized))
+    return "action";
 
   throw new Error(
     `Invalid typedApiMethodNameStyle ${JSON.stringify(value)}. Use "operationId" or "action".`,
@@ -284,7 +310,12 @@ function copySwaggerBackupFromFile(filePath) {
 async function downloadSwaggerBackupFromUrl(url) {
   const controller = new AbortController();
   const timeout = setTimeout(
-    () => controller.abort(new Error(`Swagger download timed out after ${swaggerDownloadTimeoutMs}ms.`)),
+    () =>
+      controller.abort(
+        new Error(
+          `Swagger download timed out after ${swaggerDownloadTimeoutMs}ms.`,
+        ),
+      ),
     swaggerDownloadTimeoutMs,
   );
   let response;
@@ -323,7 +354,9 @@ function useBackupSwaggerInput(reason) {
 async function resolveSwaggerInput() {
   if (offlineMode) {
     if (!fileExists(swaggerBackupPath)) {
-      throw new Error(`Offline mode requires an existing Swagger backup: ${swaggerBackupPath}`);
+      throw new Error(
+        `Offline mode requires an existing Swagger backup: ${swaggerBackupPath}`,
+      );
     }
     return { input: swaggerBackupPath, label: swaggerBackupPath };
   }
@@ -342,7 +375,9 @@ async function resolveSwaggerInput() {
 
     const backupInput = strictMode
       ? undefined
-      : useBackupSwaggerInput(`Swagger file was not found: ${swaggerFilePath}.`);
+      : useBackupSwaggerInput(
+          `Swagger file was not found: ${swaggerFilePath}.`,
+        );
 
     if (backupInput) return backupInput;
 
@@ -452,7 +487,6 @@ export const ${defaultErrorMessageName} = "An unknown error occurred.";
   return resolvedFilePath;
 }
 
-
 function addDefaultErrorMessageIfMissing(filePath) {
   const source = fs.readFileSync(filePath, "utf8");
   if (fileExportsName(source, defaultErrorMessageName)) return;
@@ -527,10 +561,13 @@ function resolveDefaultHandlers() {
     ? defaultFunctionsFilePath
     : `${defaultFunctionsFilePath}.ts`;
   if (checkMode && !fs.existsSync(candidatePath)) {
-    if (verboseMode) console.log("Skipping missing default handler file in check mode.");
+    if (verboseMode)
+      console.log("Skipping missing default handler file in check mode.");
     return undefined;
   }
-  const defaultFunctionsFile = createDefaultFunctionsFileIfMissing(defaultFunctionsFilePath);
+  const defaultFunctionsFile = createDefaultFunctionsFileIfMissing(
+    defaultFunctionsFilePath,
+  );
   const source = fs.readFileSync(defaultFunctionsFile, "utf8");
   const hasSuccessHandler = fileExportsName(source, defaultSuccessHandlerName);
   const hasErrorHandler = fileExportsName(source, defaultErrorHandlerName);
@@ -562,6 +599,8 @@ function resolveDefaultHandlers() {
 }
 
 async function main() {
+  cleanupGenerationArtifacts(apiRoot);
+
   const swaggerInput = await resolveSwaggerInput();
 
   console.log(`Generating API from: ${swaggerInput.label}`);
@@ -588,7 +627,9 @@ async function main() {
     );
   }
 
-  console.log(checkMode ? "Generated API is up to date." : "API generation completed.");
+  console.log(
+    checkMode ? "Generated API is up to date." : "API generation completed.",
+  );
 }
 
 main().catch((error) => {

package/scripts/openapi-generator/index.mjs

@@ -1,7 +1,10 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { collectOperations, validateOpenApiDocument } from "./openapi-utils.mjs";
+import {
+  collectOperations,
+  validateOpenApiDocument,
+} from "./openapi-utils.mjs";
 import { generateDataContracts } from "./schema.mjs";
 import { generateHttpClient } from "./http-client-template.mjs";
 import {
@@ -54,13 +57,18 @@ export async function generateApi(options) {
 
   const controllers = new Map();
   for (const operationInfo of operations) {
-    const controllerName = controllerNameForOperation(operationInfo, normalizedOptions);
+    const controllerName = controllerNameForOperation(
+      operationInfo,
+      normalizedOptions,
+    );
     const controllerOperations = controllers.get(controllerName) ?? [];
     controllerOperations.push(operationInfo);
     controllers.set(controllerName, controllerOperations);
   }
 
-  const controllerNames = [...controllers.keys()].sort((a, b) => a.localeCompare(b));
+  const controllerNames = [...controllers.keys()].sort((a, b) =>
+    a.localeCompare(b),
+  );
   for (const controllerName of controllerNames) {
     files.set(
       `methods/${methodFileNameForController(controllerName)}`,
@@ -73,7 +81,6 @@ export async function generateApi(options) {
     );
   }
 
-
   const changes = compareOutput(output, files);
   if (options.check) {
     if (changes.length > 0) {
@@ -81,7 +88,10 @@ export async function generateApi(options) {
         `Generated API is out of date:\n${changes.map((item) => `- ${item}`).join("\n")}`,
       );
     }
-    return { files: [...files.keys()].map((file) => path.join(output, file)), changed: false };
+    return {
+      files: [...files.keys()].map((file) => path.join(output, file)),
+      changed: false,
+    };
   }
 
   const writeStrategy = writeOutputTransactionally(
@@ -105,7 +115,8 @@ function compareOutput(output, files) {
       changes.push(`${relativePath} is missing`);
       continue;
     }
-    if (fs.readFileSync(target, "utf8") !== expected) changes.push(`${relativePath} differs`);
+    if (fs.readFileSync(target, "utf8") !== expected)
+      changes.push(`${relativePath} differs`);
   }
 
   for (const relativePath of listManagedFiles(output)) {
@@ -123,7 +134,9 @@ function listManagedFiles(output) {
       result.push(topLevel);
       continue;
     }
-    walk(target, (file) => result.push(path.relative(output, file).replaceAll(path.sep, "/")));
+    walk(target, (file) =>
+      result.push(path.relative(output, file).replaceAll(path.sep, "/")),
+    );
   }
   return result;
 }
@@ -142,6 +155,61 @@ function removeManagedOutput(root) {
   }
 }
 
+export function cleanupGenerationArtifacts(output) {
+  const resolvedOutput = path.resolve(output);
+  const parent = path.dirname(resolvedOutput);
+
+  if (!fs.existsSync(parent)) return;
+
+  const outputName = path.basename(resolvedOutput);
+  const stagingPrefix = `.${outputName}.typedapi-staging-`;
+  const backupPrefix = `.${outputName}.typedapi-backup-`;
+  const managedBackupPrefix = `.${outputName}.typedapi-managed-backup-`;
+  const backups = [];
+
+  for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const entryPath = path.join(parent, entry.name);
+
+    if (
+      entry.name.startsWith(stagingPrefix) ||
+      entry.name.startsWith(managedBackupPrefix)
+    ) {
+      removePathWithRetry(entryPath);
+      continue;
+    }
+
+    if (entry.name.startsWith(backupPrefix)) {
+      backups.push(entryPath);
+    }
+  }
+
+  if (backups.length === 0) return;
+
+  if (!fs.existsSync(resolvedOutput)) {
+    backups.sort(
+      (left, right) => fs.statSync(right).mtimeMs - fs.statSync(left).mtimeMs,
+    );
+
+    const [backupToRestore, ...staleBackups] = backups;
+
+    retryFileSystemOperation(() =>
+      fs.renameSync(backupToRestore, resolvedOutput),
+    );
+
+    for (const backup of staleBackups) {
+      removePathWithRetry(backup);
+    }
+
+    return;
+  }
+
+  for (const backup of backups) {
+    removePathWithRetry(backup);
+  }
+}
+
 const RETRYABLE_FS_ERROR_CODES = new Set([
   "EACCES",
   "EBUSY",
@@ -151,14 +219,25 @@ const RETRYABLE_FS_ERROR_CODES = new Set([
   "EPERM",
 ]);
 
-function writeOutputTransactionally(output, files, cleanOutput, forceInPlaceOutput = false) {
+function writeOutputTransactionally(
+  output,
+  files,
+  cleanOutput,
+  forceInPlaceOutput = false,
+) {
   const parent = path.dirname(output);
   fs.mkdirSync(parent, { recursive: true });
-  const staging = fs.mkdtempSync(path.join(parent, `.${path.basename(output)}.typedapi-staging-`));
-  const backup = path.join(parent, `.${path.basename(output)}.typedapi-backup-${process.pid}-${Date.now()}`);
+  const staging = fs.mkdtempSync(
+    path.join(parent, `.${path.basename(output)}.typedapi-staging-`),
+  );
+  const backup = path.join(
+    parent,
+    `.${path.basename(output)}.typedapi-backup-${process.pid}-${Date.now()}`,
+  );
 
   try {
-    if (fs.existsSync(output)) fs.cpSync(output, staging, { recursive: true, force: true });
+    if (fs.existsSync(output))
+      fs.cpSync(output, staging, { recursive: true, force: true });
     if (cleanOutput) removeManagedOutput(staging);
 
     for (const [relativePath, content] of files) {
@@ -212,7 +291,8 @@ function writeOutputTransactionally(output, files, cleanOutput, forceInPlaceOutp
     return "directory-swap";
   } finally {
     removePathWithRetry(staging);
-    if (fs.existsSync(backup) && fs.existsSync(output)) removePathWithRetry(backup);
+    if (fs.existsSync(backup) && fs.existsSync(output))
+      removePathWithRetry(backup);
   }
 }
 
@@ -272,7 +352,8 @@ function syncPath(source, target) {
       syncPath(path.join(source, entry), path.join(target, entry));
     }
     for (const entry of fs.readdirSync(target)) {
-      if (!sourceEntries.has(entry)) removePathWithRetry(path.join(target, entry));
+      if (!sourceEntries.has(entry))
+        removePathWithRetry(path.join(target, entry));
     }
     return;
   }
@@ -312,7 +393,8 @@ function retryFileSystemOperation(operation, attempts = 12) {
       return operation();
     } catch (error) {
       lastError = error;
-      if (!isRetryableFileSystemError(error) || attempt === attempts - 1) throw error;
+      if (!isRetryableFileSystemError(error) || attempt === attempts - 1)
+        throw error;
       sleepSynchronously(Math.min(25 * 2 ** attempt, 250));
     }
   }
@@ -320,7 +402,11 @@ function retryFileSystemOperation(operation, attempts = 12) {
 }
 
 function isRetryableFileSystemError(error) {
-  return Boolean(error && typeof error === "object" && RETRYABLE_FS_ERROR_CODES.has(error.code));
+  return Boolean(
+    error &&
+    typeof error === "object" &&
+    RETRYABLE_FS_ERROR_CODES.has(error.code),
+  );
 }
 
 function sleepSynchronously(milliseconds) {