@owlmeans/api 0.1.18-rc.35 → 0.1.18-rc.37

package/README.md

@@ -12,7 +12,7 @@ HTTP API client service for OwlMeans client contexts — carries entrypoint call
 ## Installation
 
 ```bash
-bun add @owlmeans/api@^0.1.18-rc.35
+bun add @owlmeans/api@^0.1.18-rc.37
 ```
 
 ## Usage
@@ -65,7 +65,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.35
+npx @owlmeans/agent-skills@^0.1.18-rc.38
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/api",
-  "version": "0.1.18-rc.35",
-  "generatedAt": "2026-09-22T21:57:18.841Z",
+  "version": "0.1.18-rc.37",
+  "generatedAt": "2026-09-23T19:57:40.715Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api
-description: How to use @owlmeans/api — the axios-based HTTP client service that carries entrypoint calls between services, its status-to-outcome mapping, typed transport errors and per-request timeout/abort. Auto-invoked when importing the API client, or when ctx.entrypoint(...).call() under the hood is involved.
+description: How to use @owlmeans/api — the axios-based HTTP client service that carries entrypoint calls between services, its status-to-outcome mapping, typed transport errors that keep the HTTP status and incident id (the ./status subpath), and per-request timeout/abort. Auto-invoked when importing the API client, reading a failed call's status, or when ctx.entrypoint(...).call() under the hood is involved.
 user-invocable: false
 ---
 <!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
@@ -8,7 +8,7 @@ user-invocable: false
 # @owlmeans/api
 
 **Layer:** Core
-**Install:** `"@owlmeans/api": "^0.1.18-rc.35"` in `dependencies`
+**Install:** `"@owlmeans/api": "^0.1.18-rc.37"` in `dependencies`
 
 ## Key Exports
 
@@ -17,8 +17,13 @@ user-invocable: false
 | `createApiService(alias?)` | Factory for the HTTP client service (axios) |
 | `appendApiClient(ctx, alias?)` | Register it and make it the context's default `webService` when none is set |
 | `ApiClient` | Service interface — a single `handler(req, reply)` |
-| `ApiError`, `ApiClientError`, `ServerCrashedError`, `ServerAuthError` | Typed transport errors |
-| Constants | Status codes (`OK`, `CREATED`, `ACCEPTED`, `FINISHED`, `UNAUTHORIZED_ERROR`, `FORBIDDEN_ERROR`, `SERVER_ERROR`), `DEFAULT_ALIAS` (`web-client`) |
+| `ApiError`, `ApiClientError`, `ServerCrashedError`, `ServerAuthError`, `ApiStatusError` | Typed transport errors; an `ApiClientError` carries the answered `status` and the server's `incidentId` |
+| `httpStatusOf`, `incidentIdOf`, `isIncidentBody`, `parseClientMarker`, `API_CLIENT_MARKER`, `API_STATUS_MARKER` | Read a failure's HTTP status and incident id (also the `./status` subpath) |
+| Constants | Status codes (`OK`, `CREATED`, `ACCEPTED`, `FINISHED`, `UNAUTHORIZED_ERROR`, `FORBIDDEN_ERROR`, `SERVER_ERROR`), `INCIDENT_ID_HEADER` (`X-Incident-ID`), `DEFAULT_ALIAS` (`web-client`) |
+
+Subpath `./status` — `httpStatusOf`, `incidentIdOf`, `isIncidentBody`, `parseClientMarker`, the
+markers and `INCIDENT_ID_HEADER`, importing only `@owlmeans/error`: a browser package reads a
+status without pulling axios in.
 
 ## How a call is carried
 
@@ -56,10 +61,25 @@ included, comes back and is mapped here.
 | 201 / 204 | Resolves with the body, or with the response headers when the body is empty |
 | any other | Rejects |
 
-A rejection prefers the server's own error: a text body is rehydrated into the original
-`ResilientError`, so a `handleError` reply on the far side arrives as the same class it was thrown
-as. Failing that it becomes `ServerCrashedError` (500), `ServerAuthError` (401) or `ApiClientError`
-(403 and the rest).
+Every rejection keeps the HTTP status and, when the server sent one, its incident id (the
+`X-Incident-ID` header, read from `AxiosHeaders` or a plain object, else a bare UUID body — a
+browser reads that header cross-origin only when the server exposes it, the body covers the rest):
+
+| Body | Rejects with |
+|---|---|
+| Development — the marshaled `ResilientError` (carries the separator) | The original class, rebuilt through the registry, stamped `responseStatus` and `incidentId` |
+| Production — a bare incident UUID; also proxy HTML, framework JSON, anything else | `ServerCrashedError` `api:client:crashed:<id>` (500) · `ServerAuthError` `api:client:auth:<id>` (401) · `ApiClientError` `api:client:forbidden[:<id>]` (403) · `ApiStatusError` `api:client:status:<n>[:<id>]` (every other status) |
+
+An `@owlmeans/server-api` boundary in production exposure sends ONLY the incident id, so a typed
+refusal's class never reaches the browser — its status does. Read it with `httpStatusOf(e)`: the
+stamped `responseStatus`, else an `ApiClientError`'s parsed `status`, else a class's declared
+`httpStatus` (a 4xx; a 5xx only with `allowServerErrorStatus`, exactly what the server answers),
+else an `api:client:*` marker in the message or type; `null` when nothing states one. A consumer
+that acts on a refusal checks the class/marker AND the status (`consentRefusalOf(e) ||
+httpStatusOf(e) === 428`). Markers without an id stay as they were (`api:client:crashed:error`,
+`api:client:forbidden`). The status and id are rebuilt from the marker in `finalizeUnmarshal()`,
+so they survive a marshal. No class of this family declares a static `httpStatus`: a server that
+rethrows one still answers 500.
 
 **A failure with no answer at all is a different family.** Suppressing status errors does not wrap
 the call: an expired `timeout` (`ECONNABORTED`), an aborted `signal` (`CanceledError` /

package/build/consts.d.ts

@@ -5,6 +5,11 @@ export declare const OK = 200;
 export declare const CREATED = 201;
 export declare const ACCEPTED = 202;
 export declare const FINISHED = 204;
+/**
+ * The response header an `@owlmeans/server-api` boundary puts its incident id in — the key to the
+ * server log entry that owns a failure's full detail.
+ */
+export declare const INCIDENT_ID_HEADER = "X-Incident-ID";
 export declare const DEFAULT_ALIAS = "web-client";
 export declare const protocols: string[];
 //# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,MAAM,CAAA;AAE/B,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC,eAAO,MAAM,eAAe,MAAM,CAAA;AAElC,eAAO,MAAM,EAAE,MAAM,CAAA;AAErB,eAAO,MAAM,OAAO,MAAM,CAAA;AAE1B,eAAO,MAAM,QAAQ,MAAM,CAAA;AAE3B,eAAO,MAAM,QAAQ,MAAM,CAAA;AAE3B,eAAO,MAAM,aAAa,eAAe,CAAA;AAEzC,eAAO,MAAM,SAAS,UAAiC,CAAA"}
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,YAAY,MAAM,CAAA;AAE/B,eAAO,MAAM,kBAAkB,MAAM,CAAA;AAErC,eAAO,MAAM,eAAe,MAAM,CAAA;AAElC,eAAO,MAAM,EAAE,MAAM,CAAA;AAErB,eAAO,MAAM,OAAO,MAAM,CAAA;AAE1B,eAAO,MAAM,QAAQ,MAAM,CAAA;AAE3B,eAAO,MAAM,QAAQ,MAAM,CAAA;AAE3B;;;GAGG;AACH,eAAO,MAAM,kBAAkB,kBAAkB,CAAA;AAEjD,eAAO,MAAM,aAAa,eAAe,CAAA;AAEzC,eAAO,MAAM,SAAS,UAAiC,CAAA"}

package/build/consts.js

@@ -5,6 +5,11 @@ export const OK = 200;
 export const CREATED = 201;
 export const ACCEPTED = 202;
 export const FINISHED = 204;
+/**
+ * The response header an `@owlmeans/server-api` boundary puts its incident id in — the key to the
+ * server log entry that owns a failure's full detail.
+ */
+export const INCIDENT_ID_HEADER = 'X-Incident-ID';
 export const DEFAULT_ALIAS = 'web-client';
 export const protocols = ['http', 'https', 'wss', 'ws'];
 //# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -1 +1 @@
-{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAA;AAE/B,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAErC,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAA;AAElC,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,CAAA;AAErB,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAA;AAE1B,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAA;AAE3B,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAA;AAE3B,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA"}
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAA;AAE/B,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAA;AAErC,MAAM,CAAC,MAAM,eAAe,GAAG,GAAG,CAAA;AAElC,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,CAAA;AAErB,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAA;AAE1B,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAA;AAE3B,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAG,CAAA;AAE3B;;;GAGG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,eAAe,CAAA;AAEjD,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAA"}

package/build/errors.d.ts

@@ -3,16 +3,44 @@ export declare class ApiError extends ResilientError {
     static typeName: string;
     constructor(message?: string);
 }
+/**
+ * A request the peer answered with a failure.
+ *
+ * `status` is the HTTP status the marker in the message states (`api:client:crashed:<id>` is 500,
+ * `api:client:auth:<id>` 401, `api:client:forbidden[:<id>]` 403, `api:client:status:<n>[:<id>]`
+ * any other); `incidentId` is the server's correlation id when the marker carries one. Only
+ * `type` and `message` survive a marshal, so both are rebuilt from the message in
+ * `finalizeUnmarshal()`. No class of this family declares a static `httpStatus`: a server that
+ * rethrows one answers 500, as before.
+ */
 export declare class ApiClientError extends ApiError {
     static typeName: string;
+    /** The HTTP status the peer answered with, when the message states one. */
+    status?: number;
     constructor(message?: string);
+    protected applyStatus(): void;
+    finalizeUnmarshal(): void;
 }
+/** The peer answered 500. Marker `api:client:crashed:<incident id | error>`. */
 export declare class ServerCrashedError extends ApiClientError {
     static typeName: string;
-    constructor(message?: string);
+    constructor(incidentId?: string);
 }
+/** The peer answered 401. Marker `api:client:auth:<incident id | error>`. */
 export declare class ServerAuthError extends ApiClientError {
     static typeName: string;
-    constructor(message?: string);
+    constructor(incidentId?: string);
+}
+/**
+ * The peer answered any other non-2xx status with no typed error in the body — a production
+ * incident id, a proxy's HTML page, a framework's JSON. Marker `api:client:status:<n>[:<id>]`.
+ */
+export declare class ApiStatusError extends ApiClientError {
+    static typeName: string;
+    /** The marker body: `<status>[:<incident id>]`. */
+    static encode(status: number, incidentId?: string): string;
+    constructor(status: number, incidentId?: string);
+    /** A marker body (`ApiStatusError.encode`) or a marshaled message — the error registry's path. */
+    constructor(message: string);
 }
 //# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAa;IAE5C,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF;AAED,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAmB;IAElD,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,OAAuB,QAAQ,SAA4C;IAE3E,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF;AAED,qBAAa,eAAgB,SAAQ,cAAc;IACjD,OAAuB,QAAQ,SAAyC;IAExE,YAAY,OAAO,GAAE,MAAgB,EAGpC;CACF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAGhD,qBAAa,QAAS,SAAQ,cAAc;IAC1C,OAAuB,QAAQ,SAAa;IAE5C,YAAY,OAAO,GAAE,MAAgB,EAEpC;CACF;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C,OAAuB,QAAQ,SAAmB;IAElD,2EAA2E;IACpE,MAAM,CAAC,EAAE,MAAM,CAAA;IAEtB,YAAY,OAAO,GAAE,MAAgB,EAIpC;IAED,SAAS,CAAC,WAAW,IAAI,IAAI,CAM5B;IAEQ,iBAAiB,IAAI,IAAI,CAEjC;CACF;AAED,gFAAgF;AAChF,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,OAAuB,QAAQ,SAA4C;IAE3E,YAAY,UAAU,CAAC,EAAE,MAAM,EAG9B;CACF;AAED,6EAA6E;AAC7E,qBAAa,eAAgB,SAAQ,cAAc;IACjD,OAAuB,QAAQ,SAAyC;IAExE,YAAY,UAAU,CAAC,EAAE,MAAM,EAG9B;CACF;AAED;;;GAGG;AACH,qBAAa,cAAe,SAAQ,cAAc;IAChD,OAAuB,QAAQ,SAAqC;IAEpE,mDAAmD;IACnD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD;IAED,YAAY,MAAM,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAC;IAChD,kGAAkG;IAClG,YAAY,OAAO,EAAE,MAAM,EAAC;CAK7B"}

package/build/errors.js

@@ -1,33 +1,75 @@
 import { ResilientError } from '@owlmeans/error';
+import { parseClientMarker } from './status/marker.js';
 export class ApiError extends ResilientError {
     static typeName = 'ApiError';
     constructor(message = 'error') {
         super(ApiError.typeName, `api:${message}`);
     }
 }
+/**
+ * A request the peer answered with a failure.
+ *
+ * `status` is the HTTP status the marker in the message states (`api:client:crashed:<id>` is 500,
+ * `api:client:auth:<id>` 401, `api:client:forbidden[:<id>]` 403, `api:client:status:<n>[:<id>]`
+ * any other); `incidentId` is the server's correlation id when the marker carries one. Only
+ * `type` and `message` survive a marshal, so both are rebuilt from the message in
+ * `finalizeUnmarshal()`. No class of this family declares a static `httpStatus`: a server that
+ * rethrows one answers 500, as before.
+ */
 export class ApiClientError extends ApiError {
     static typeName = 'ApiClientError';
+    /** The HTTP status the peer answered with, when the message states one. */
+    status;
     constructor(message = 'error') {
         super(`client:${message}`);
         this.type = ApiClientError.typeName;
+        this.applyStatus();
+    }
+    applyStatus() {
+        const marker = parseClientMarker(this.message);
+        this.status = marker?.status;
+        if (marker?.incidentId != null) {
+            this.incidentId ??= marker.incidentId;
+        }
+    }
+    finalizeUnmarshal() {
+        this.applyStatus();
     }
 }
+/** The peer answered 500. Marker `api:client:crashed:<incident id | error>`. */
 export class ServerCrashedError extends ApiClientError {
     static typeName = `${ApiClientError.typeName}ServerCrashed`;
-    constructor(message = 'error') {
-        super(`crashed:${message}`);
+    constructor(incidentId) {
+        super(`crashed:${incidentId ?? 'error'}`);
         this.type = ServerCrashedError.typeName;
     }
 }
+/** The peer answered 401. Marker `api:client:auth:<incident id | error>`. */
 export class ServerAuthError extends ApiClientError {
     static typeName = `${ApiClientError.typeName}ServerAuth`;
-    constructor(message = 'error') {
-        super(`auth:${message}`);
+    constructor(incidentId) {
+        super(`auth:${incidentId ?? 'error'}`);
         this.type = ServerAuthError.typeName;
     }
 }
+/**
+ * The peer answered any other non-2xx status with no typed error in the body — a production
+ * incident id, a proxy's HTML page, a framework's JSON. Marker `api:client:status:<n>[:<id>]`.
+ */
+export class ApiStatusError extends ApiClientError {
+    static typeName = `${ApiClientError.typeName}Status`;
+    /** The marker body: `<status>[:<incident id>]`. */
+    static encode(status, incidentId) {
+        return incidentId != null && incidentId !== '' ? `${status}:${incidentId}` : `${status}`;
+    }
+    constructor(status = 'error', incidentId) {
+        super(`status:${typeof status === 'number' ? ApiStatusError.encode(status, incidentId) : status}`);
+        this.type = ApiStatusError.typeName;
+    }
+}
 ResilientError.registerErrorClass(ApiError);
 ResilientError.registerErrorClass(ApiClientError);
 ResilientError.registerErrorClass(ServerCrashedError);
 ResilientError.registerErrorClass(ServerAuthError);
+ResilientError.registerErrorClass(ApiStatusError);
 //# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAEhD,MAAM,OAAO,QAAS,SAAQ,cAAc;IACnC,MAAM,CAAU,QAAQ,GAAG,UAAU,CAAA;IAE5C,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,OAAO,EAAE,CAAC,CAAA;IAC5C,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACnC,MAAM,CAAU,QAAQ,GAAG,gBAAgB,CAAA;IAElD,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,UAAU,OAAO,EAAE,CAAC,CAAA;QAC1B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC,QAAQ,CAAA;IACrC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,cAAc;IAC7C,MAAM,CAAU,QAAQ,GAAG,GAAG,cAAc,CAAC,QAAQ,eAAe,CAAA;IAE3E,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,WAAW,OAAO,EAAE,CAAC,CAAA;QAC3B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC,QAAQ,CAAA;IACzC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,cAAc;IAC1C,MAAM,CAAU,QAAQ,GAAG,GAAG,cAAc,CAAC,QAAQ,YAAY,CAAA;IAExE,YAAY,OAAO,GAAW,OAAO;QACnC,KAAK,CAAC,QAAQ,OAAO,EAAE,CAAC,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAA;IACtC,CAAC;CACF;AAED,cAAc,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAA;AAC3C,cAAc,CAAC,kBAAkB,CAAC,cAAc,CAAC,CAAA;AACjD,cAAc,CAAC,kBAAkB,CAAC,kBAAkB,CAAC,CAAA;AACrD,cAAc,CAAC,kBAAkB,CAAC,eAAe,CAAC,CAAA"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/build/index.d.ts

@@ -2,4 +2,6 @@ export * from './errors.js';
 export * from './consts.js';
 export * from './service.js';
 export type * from './types.js';
+export { httpStatusOf, incidentIdOf, isIncidentBody, parseClientMarker, API_CLIENT_MARKER, API_STATUS_MARKER, } from './status/index.js';
+export type { ClientMarker, ResponseStatusCarrier } from './status/index.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,mBAAmB,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,mBAAmB,YAAY,CAAA;AAC/B,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,GACpG,MAAM,mBAAmB,CAAA;AAC1B,YAAY,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}

package/build/index.js

@@ -1,4 +1,5 @@
 export * from './errors.js';
 export * from './consts.js';
 export * from './service.js';
+export { httpStatusOf, incidentIdOf, isIncidentBody, parseClientMarker, API_CLIENT_MARKER, API_STATUS_MARKER, } from './status/index.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAE5B,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,GACpG,MAAM,mBAAmB,CAAA"}

package/build/status/index.d.ts

@@ -0,0 +1,27 @@
+export { INCIDENT_ID_HEADER } from '../consts.js';
+export { API_CLIENT_MARKER, API_STATUS_MARKER, parseClientMarker } from './marker.js';
+export type { ClientMarker } from './marker.js';
+/** The HTTP status the API client stamps on an error it rebuilt from a response body. */
+export interface ResponseStatusCarrier {
+    responseStatus?: number;
+}
+/**
+ * The HTTP status an error answers to, or `null` when nothing states one.
+ *
+ * Read in order: the status the API client stamped on the error it rebuilt from a response
+ * (`responseStatus`); the status an `ApiClientError` parsed from its marker; the `httpStatus` its
+ * class declares — a 4xx always, a 5xx only with `allowServerErrorStatus`, exactly what an
+ * `@owlmeans/server-api` boundary answers with; finally an `api:client:*` marker in the message or
+ * the type of anything else. This is what lets a browser recognise a refusal from its status
+ * alone when a production body carries nothing but an incident id.
+ */
+export declare const httpStatusOf: (error: unknown) => number | null;
+/** The server's incident id carried by an error — its own field, else its marker — or `null`. */
+export declare const incidentIdOf: (error: unknown) => string | null;
+/**
+ * Whether a response body is a production incident body — the bare incident UUID an
+ * `@owlmeans/server-api` boundary sends instead of the marshaled error. A development body
+ * carries the `ResilientError` separator and is never one.
+ */
+export declare const isIncidentBody: (data: unknown) => data is string;
+//# sourceMappingURL=index.d.ts.map

package/build/status/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/status/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACrF,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE/C,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACpC,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAaD;;;;;;;;;GASG;AACH,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,MAAM,GAAG,IAkBtD,CAAA;AAED,iGAAiG;AACjG,eAAO,MAAM,YAAY,UAAW,OAAO,KAAG,MAAM,GAAG,IAUtD,CAAA;AAID;;;;GAIG;AACH,eAAO,MAAM,cAAc,SAAU,OAAO,KAAG,IAAI,IAAI,MACyC,CAAA"}

package/build/status/index.js

@@ -0,0 +1,59 @@
+import { ResilientError } from '@owlmeans/error';
+import { ApiClientError } from '../errors.js';
+import { parseClientMarker } from './marker.js';
+export { INCIDENT_ID_HEADER } from '../consts.js';
+export { API_CLIENT_MARKER, API_STATUS_MARKER, parseClientMarker } from './marker.js';
+const httpStatus = (value) => typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599 ? value : null;
+/** The first `api:client:*` marker in an error's `message`, else in its `type`. */
+const markerOf = (error) => {
+    const { message, type } = error;
+    return (typeof message === 'string' ? parseClientMarker(message) : null)
+        ?? (typeof type === 'string' ? parseClientMarker(type) : null);
+};
+/**
+ * The HTTP status an error answers to, or `null` when nothing states one.
+ *
+ * Read in order: the status the API client stamped on the error it rebuilt from a response
+ * (`responseStatus`); the status an `ApiClientError` parsed from its marker; the `httpStatus` its
+ * class declares — a 4xx always, a 5xx only with `allowServerErrorStatus`, exactly what an
+ * `@owlmeans/server-api` boundary answers with; finally an `api:client:*` marker in the message or
+ * the type of anything else. This is what lets a browser recognise a refusal from its status
+ * alone when a production body carries nothing but an incident id.
+ */
+export const httpStatusOf = (error) => {
+    if (error == null || typeof error !== 'object') {
+        return null;
+    }
+    const stamped = httpStatus(error.responseStatus);
+    if (stamped != null) {
+        return stamped;
+    }
+    if (error instanceof ApiClientError && httpStatus(error.status) != null) {
+        return error.status;
+    }
+    const declaration = error.constructor;
+    const declared = httpStatus(declaration?.httpStatus);
+    if (declared != null && (declared < 500 || declaration?.allowServerErrorStatus === true)) {
+        return declared;
+    }
+    return markerOf(error)?.status ?? null;
+};
+/** The server's incident id carried by an error — its own field, else its marker — or `null`. */
+export const incidentIdOf = (error) => {
+    if (error == null || typeof error !== 'object') {
+        return null;
+    }
+    const own = error.incidentId;
+    if (typeof own === 'string' && own !== '') {
+        return own;
+    }
+    return markerOf(error)?.incidentId ?? null;
+};
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Whether a response body is a production incident body — the bare incident UUID an
+ * `@owlmeans/server-api` boundary sends instead of the marshaled error. A development body
+ * carries the `ResilientError` separator and is never one.
+ */
+export const isIncidentBody = (data) => typeof data === 'string' && !data.includes(ResilientError.separator) && UUID.test(data.trim());
+//# sourceMappingURL=index.js.map

package/build/status/index.js.map

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

package/build/status/marker.d.ts

@@ -0,0 +1,12 @@
+/** The prefix every `ApiClientError` message carries. */
+export declare const API_CLIENT_MARKER = "api:client:";
+/** The marker of an `ApiStatusError`: `api:client:status:<n>[:<incident id>]`. */
+export declare const API_STATUS_MARKER = "api:client:status:";
+/** What an `api:client:*` marker states. */
+export interface ClientMarker {
+    status?: number;
+    incidentId?: string;
+}
+/** Read the first `api:client:*` marker in a text, or `null` when it carries none. */
+export declare const parseClientMarker: (text: string) => ClientMarker | null;
+//# sourceMappingURL=marker.d.ts.map

package/build/status/marker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.d.ts","sourceRoot":"","sources":["../../src/status/marker.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,eAAO,MAAM,iBAAiB,gBAAgB,CAAA;AAE9C,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,uBAAgC,CAAA;AAY9D,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,sFAAsF;AACtF,eAAO,MAAM,iBAAiB,SAAU,MAAM,KAAG,YAAY,GAAG,IAa/D,CAAA"}

package/build/status/marker.js

@@ -0,0 +1,27 @@
+/** The prefix every `ApiClientError` message carries. */
+export const API_CLIENT_MARKER = 'api:client:';
+/** The marker of an `ApiStatusError`: `api:client:status:<n>[:<incident id>]`. */
+export const API_STATUS_MARKER = `${API_CLIENT_MARKER}status:`;
+/**
+ * `crashed` / `auth` / `forbidden` / `status:<n>` / the legacy bare `<n>`, then an optional
+ * `:<incident id>`. The look-ahead refuses a match that runs on into more marker text, so a
+ * doubled prefix (a subclass constructor handed a whole marshaled message) resolves to the inner,
+ * complete marker.
+ */
+const MARKER = /api:client:(?:(crashed|auth|forbidden)|status:(\d{3})|(\d{3}))(?::([\w.-]{1,128}))?(?![\w.:-])/;
+const NAMED_STATUS = { crashed: 500, auth: 401, forbidden: 403 };
+/** Read the first `api:client:*` marker in a text, or `null` when it carries none. */
+export const parseClientMarker = (text) => {
+    const match = MARKER.exec(text);
+    if (match == null) {
+        return null;
+    }
+    const [, named, coded, legacy, id] = match;
+    const code = named != null ? NAMED_STATUS[named] : Number(coded ?? legacy);
+    return {
+        status: code >= 100 && code <= 599 ? code : undefined,
+        // `error` is the placeholder a marker gets when no incident id was known.
+        incidentId: id != null && id !== 'error' ? id : undefined,
+    };
+};
+//# sourceMappingURL=marker.js.map

package/build/status/marker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"marker.js","sourceRoot":"","sources":["../../src/status/marker.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,CAAC,MAAM,iBAAiB,GAAG,aAAa,CAAA;AAE9C,kFAAkF;AAClF,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAG,iBAAiB,SAAS,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,GAAG,gGAAgG,CAAA;AAE/G,MAAM,YAAY,GAA2B,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;AAQxF,sFAAsF;AACtF,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAY,EAAuB,EAAE;IACrE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/B,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,IAAI,CAAA;IACb,CAAC;IACD,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,GAAG,KAAK,CAAA;IAC1C,MAAM,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,CAAA;IAE1E,OAAO;QACL,MAAM,EAAE,IAAI,IAAI,GAAG,IAAI,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS;QACrD,0EAA0E;QAC1E,UAAU,EAAE,EAAE,IAAI,IAAI,IAAI,EAAE,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS;KAC1D,CAAA;AACH,CAAC,CAAA"}

package/build/utils/handler.d.ts

@@ -1,4 +1,11 @@
 import type { AbstractResponse } from '@owlmeans/entrypoint';
 import type { AxiosResponse } from 'axios';
+import { ApiClientError } from '../errors.js';
 export declare const processResponse: (response: AxiosResponse, reply: AbstractResponse<any>) => void;
+/**
+ * The typed error of a bare status: `ServerCrashedError` (500), `ServerAuthError` (401),
+ * `ApiClientError('forbidden[:<id>]')` (403), `ApiStatusError` (`api:client:status:<n>[:<id>]`)
+ * for every other one.
+ */
+export declare const statusError: (status: number, incidentId?: string) => ApiClientError;
 //# sourceMappingURL=handler.d.ts.map

package/build/utils/handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/utils/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAK1C,eAAO,MAAM,eAAe,aAAc,aAAa,SAAS,gBAAgB,CAAC,GAAG,CAAC,SAyCpF,CAAA"}
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/utils/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAA;AAK1C,OAAO,EAAE,cAAc,EAAuD,MAAM,cAAc,CAAA;AAIlG,eAAO,MAAM,eAAe,aAAc,aAAa,SAAS,gBAAgB,CAAC,GAAG,CAAC,SAoBpF,CAAA;AA6BD;;;;GAIG;AACH,eAAO,MAAM,WAAW,WAAY,MAAM,eAAe,MAAM,KAAG,cAUjE,CAAA"}

package/build/utils/handler.js

@@ -1,7 +1,8 @@
 import { EntrypointOutcome } from '@owlmeans/entrypoint';
-import { ACCEPTED, CREATED, FINISHED, FORBIDDEN_ERROR, OK, SERVER_ERROR, UNAUTHORIZED_ERROR } from '../consts.js';
+import { ACCEPTED, CREATED, FINISHED, FORBIDDEN_ERROR, INCIDENT_ID_HEADER, OK, SERVER_ERROR, UNAUTHORIZED_ERROR, } from '../consts.js';
 import { ResilientError } from '@owlmeans/error';
-import { ApiClientError, ServerAuthError, ServerCrashedError } from '../errors.js';
+import { ApiClientError, ApiStatusError, ServerAuthError, ServerCrashedError } from '../errors.js';
+import { isIncidentBody } from '../status/index.js';
 export const processResponse = (response, reply) => {
     switch (response.status) {
         case OK:
@@ -16,33 +17,61 @@ export const processResponse = (response, reply) => {
             return processEmptyResponse(response, reply, EntrypointOutcome.Finished);
         default:
             console.error(response.status, response.statusText);
-            console.error(response.config.url, response.headers);
+            console.error(response.config?.url, response.headers);
             console.error(response.data);
-            try {
-                if (typeof response.data === 'string') {
-                    reply.reject(ResilientError.ensure(response.data, true));
-                    return;
-                }
-            }
-            catch {
-                console.error(`Server returned an unrecognizable text error: ${response.status} ${response.data}`);
-            }
-            switch (response.status) {
-                case SERVER_ERROR:
-                    reply.reject(new ServerCrashedError());
-                    return;
-                case UNAUTHORIZED_ERROR:
-                    reply.reject(new ServerAuthError());
-                    return;
-                case FORBIDDEN_ERROR:
-                    reply.reject(new ApiClientError('forbidden'));
-                    return;
-                default:
-                    reply.reject(new ApiClientError(`${response.status}`));
-                    return;
-            }
+            reply.reject(failureOf(response));
     }
 };
+/**
+ * The error a non-2xx answer rejects with — always carrying the HTTP status and, when the server
+ * sent one, its incident id.
+ *
+ * A development body is the marshaled `ResilientError`: it is rebuilt into its own class and
+ * stamped with `responseStatus`. Anything else — the bare incident id of a production body, a
+ * proxy's HTML, a framework's JSON — becomes the status error of {@link statusError}.
+ */
+const failureOf = (response) => {
+    const incidentId = headerOf(response.headers, INCIDENT_ID_HEADER)
+        ?? (isIncidentBody(response.data) ? response.data.trim() : undefined);
+    if (typeof response.data === 'string' && response.data.includes(ResilientError.separator)) {
+        try {
+            const error = ResilientError.ensure(response.data, true);
+            error.incidentId ??= incidentId;
+            Object.assign(error, { responseStatus: response.status });
+            return error;
+        }
+        catch {
+            console.error(`Server returned an unrecognizable text error: ${response.status} ${response.data}`);
+        }
+    }
+    return statusError(response.status, incidentId);
+};
+/**
+ * The typed error of a bare status: `ServerCrashedError` (500), `ServerAuthError` (401),
+ * `ApiClientError('forbidden[:<id>]')` (403), `ApiStatusError` (`api:client:status:<n>[:<id>]`)
+ * for every other one.
+ */
+export const statusError = (status, incidentId) => {
+    const error = status === SERVER_ERROR ? new ServerCrashedError(incidentId)
+        : status === UNAUTHORIZED_ERROR ? new ServerAuthError(incidentId)
+            : status === FORBIDDEN_ERROR ? new ApiClientError(incidentId != null ? `forbidden:${incidentId}` : 'forbidden')
+                : new ApiStatusError(status, incidentId);
+    if (incidentId != null) {
+        error.incidentId = incidentId;
+    }
+    return Object.assign(error, { responseStatus: status });
+};
+/** One response header, from an `AxiosHeaders` instance or a plain header object alike. */
+const headerOf = (headers, name) => {
+    if (headers == null || typeof headers !== 'object') {
+        return undefined;
+    }
+    const get = headers.get;
+    const viaGet = typeof get === 'function' ? get.call(headers, name) : undefined;
+    const value = viaGet ?? Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
+    const first = Array.isArray(value) ? value[0] : value;
+    return typeof first === 'string' && first.trim() !== '' ? first.trim() : undefined;
+};
 const processEmptyResponse = (response, reply, outcome) => {
     if (response.data != null && response.data != '') {
         reply.resolve(response.data, outcome);

package/build/utils/handler.js.map

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

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/api",
-  "version": "0.1.18-rc.35",
+  "version": "0.1.18-rc.37",
   "license": "MIT",
   "type": "module",
   "scripts": {
     "build": "tsc -b",
     "dev": "sleep 0 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
-    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
   },
   "main": "build/index.js",
   "module": "build/index.js",
@@ -18,17 +19,24 @@
       "default": "./build/index.js",
       "module": "./build/index.js",
       "types": "./build/index.d.ts"
+    },
+    "./status": {
+      "import": "./build/status/index.js",
+      "require": "./build/status/index.js",
+      "default": "./build/status/index.js",
+      "module": "./build/status/index.js",
+      "types": "./build/status/index.d.ts"
     }
   },
   "dependencies": {
-    "@owlmeans/auth-common": "^0.1.18-rc.35",
-    "@owlmeans/client-config": "^0.1.18-rc.35",
-    "@owlmeans/client-route": "^0.1.18-rc.36",
-    "@owlmeans/config": "^0.1.18-rc.35",
-    "@owlmeans/context": "^0.1.18-rc.31",
-    "@owlmeans/error": "^0.1.18-rc.33",
-    "@owlmeans/entrypoint": "^0.1.18-rc.34",
-    "@owlmeans/route": "^0.1.18-rc.32",
+    "@owlmeans/auth-common": "^0.1.18-rc.37",
+    "@owlmeans/client-config": "^0.1.18-rc.37",
+    "@owlmeans/client-route": "^0.1.18-rc.38",
+    "@owlmeans/config": "^0.1.18-rc.37",
+    "@owlmeans/context": "^0.1.18-rc.32",
+    "@owlmeans/error": "^0.1.18-rc.35",
+    "@owlmeans/entrypoint": "^0.1.18-rc.36",
+    "@owlmeans/route": "^0.1.18-rc.33",
     "axios": "^1.7.7",
     "qs": "^6.13.0"
   },

package/src/consts.ts

@@ -13,6 +13,12 @@ export const ACCEPTED = 202
 
 export const FINISHED = 204
 
+/**
+ * The response header an `@owlmeans/server-api` boundary puts its incident id in — the key to the
+ * server log entry that owns a failure's full detail.
+ */
+export const INCIDENT_ID_HEADER = 'X-Incident-ID'
+
 export const DEFAULT_ALIAS = 'web-client'
 
 export const protocols = ['http', 'https', 'wss', 'ws']

package/src/errors.ts

@@ -1,4 +1,5 @@
 import { ResilientError } from '@owlmeans/error'
+import { parseClientMarker } from './status/marker.js'
 
 export class ApiError extends ResilientError {
   public static override typeName = 'ApiError'
@@ -8,34 +9,84 @@ export class ApiError extends ResilientError {
   }
 }
 
+/**
+ * A request the peer answered with a failure.
+ *
+ * `status` is the HTTP status the marker in the message states (`api:client:crashed:<id>` is 500,
+ * `api:client:auth:<id>` 401, `api:client:forbidden[:<id>]` 403, `api:client:status:<n>[:<id>]`
+ * any other); `incidentId` is the server's correlation id when the marker carries one. Only
+ * `type` and `message` survive a marshal, so both are rebuilt from the message in
+ * `finalizeUnmarshal()`. No class of this family declares a static `httpStatus`: a server that
+ * rethrows one answers 500, as before.
+ */
 export class ApiClientError extends ApiError {
   public static override typeName = 'ApiClientError'
 
+  /** The HTTP status the peer answered with, when the message states one. */
+  public status?: number
+
   constructor(message: string = 'error') {
     super(`client:${message}`)
     this.type = ApiClientError.typeName
+    this.applyStatus()
+  }
+
+  protected applyStatus(): void {
+    const marker = parseClientMarker(this.message)
+    this.status = marker?.status
+    if (marker?.incidentId != null) {
+      this.incidentId ??= marker.incidentId
+    }
+  }
+
+  override finalizeUnmarshal(): void {
+    this.applyStatus()
   }
 }
 
+/** The peer answered 500. Marker `api:client:crashed:<incident id | error>`. */
 export class ServerCrashedError extends ApiClientError {
   public static override typeName = `${ApiClientError.typeName}ServerCrashed`
 
-  constructor(message: string = 'error') {
-    super(`crashed:${message}`)
+  constructor(incidentId?: string) {
+    super(`crashed:${incidentId ?? 'error'}`)
     this.type = ServerCrashedError.typeName
   }
 }
 
+/** The peer answered 401. Marker `api:client:auth:<incident id | error>`. */
 export class ServerAuthError extends ApiClientError {
   public static override typeName = `${ApiClientError.typeName}ServerAuth`
 
-  constructor(message: string = 'error') {
-    super(`auth:${message}`)
+  constructor(incidentId?: string) {
+    super(`auth:${incidentId ?? 'error'}`)
     this.type = ServerAuthError.typeName
   }
 }
 
+/**
+ * The peer answered any other non-2xx status with no typed error in the body — a production
+ * incident id, a proxy's HTML page, a framework's JSON. Marker `api:client:status:<n>[:<id>]`.
+ */
+export class ApiStatusError extends ApiClientError {
+  public static override typeName = `${ApiClientError.typeName}Status`
+
+  /** The marker body: `<status>[:<incident id>]`. */
+  static encode(status: number, incidentId?: string): string {
+    return incidentId != null && incidentId !== '' ? `${status}:${incidentId}` : `${status}`
+  }
+
+  constructor(status: number, incidentId?: string)
+  /** A marker body (`ApiStatusError.encode`) or a marshaled message — the error registry's path. */
+  constructor(message: string)
+  constructor(status: number | string = 'error', incidentId?: string) {
+    super(`status:${typeof status === 'number' ? ApiStatusError.encode(status, incidentId) : status}`)
+    this.type = ApiStatusError.typeName
+  }
+}
+
 ResilientError.registerErrorClass(ApiError)
 ResilientError.registerErrorClass(ApiClientError)
 ResilientError.registerErrorClass(ServerCrashedError)
 ResilientError.registerErrorClass(ServerAuthError)
+ResilientError.registerErrorClass(ApiStatusError)

package/src/index.ts

@@ -1,5 +1,8 @@
-
 export * from './errors.js'
 export * from './consts.js'
 export * from './service.js'
 export type * from './types.js'
+export {
+  httpStatusOf, incidentIdOf, isIncidentBody, parseClientMarker, API_CLIENT_MARKER, API_STATUS_MARKER,
+} from './status/index.js'
+export type { ClientMarker, ResponseStatusCarrier } from './status/index.js'

package/src/status/index.ts

@@ -0,0 +1,76 @@
+import { ResilientError } from '@owlmeans/error'
+import { ApiClientError } from '../errors.js'
+import { parseClientMarker } from './marker.js'
+
+export { INCIDENT_ID_HEADER } from '../consts.js'
+export { API_CLIENT_MARKER, API_STATUS_MARKER, parseClientMarker } from './marker.js'
+export type { ClientMarker } from './marker.js'
+
+/** The HTTP status the API client stamps on an error it rebuilt from a response body. */
+export interface ResponseStatusCarrier {
+  responseStatus?: number
+}
+
+const httpStatus = (value: unknown): number | null =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 100 && value <= 599 ? value : null
+
+/** The first `api:client:*` marker in an error's `message`, else in its `type`. */
+const markerOf = (error: object) => {
+  const { message, type } = error as { message?: unknown, type?: unknown }
+
+  return (typeof message === 'string' ? parseClientMarker(message) : null)
+    ?? (typeof type === 'string' ? parseClientMarker(type) : null)
+}
+
+/**
+ * The HTTP status an error answers to, or `null` when nothing states one.
+ *
+ * Read in order: the status the API client stamped on the error it rebuilt from a response
+ * (`responseStatus`); the status an `ApiClientError` parsed from its marker; the `httpStatus` its
+ * class declares — a 4xx always, a 5xx only with `allowServerErrorStatus`, exactly what an
+ * `@owlmeans/server-api` boundary answers with; finally an `api:client:*` marker in the message or
+ * the type of anything else. This is what lets a browser recognise a refusal from its status
+ * alone when a production body carries nothing but an incident id.
+ */
+export const httpStatusOf = (error: unknown): number | null => {
+  if (error == null || typeof error !== 'object') {
+    return null
+  }
+  const stamped = httpStatus((error as ResponseStatusCarrier).responseStatus)
+  if (stamped != null) {
+    return stamped
+  }
+  if (error instanceof ApiClientError && httpStatus(error.status) != null) {
+    return error.status!
+  }
+  const declaration = error.constructor as { httpStatus?: unknown, allowServerErrorStatus?: unknown } | undefined
+  const declared = httpStatus(declaration?.httpStatus)
+  if (declared != null && (declared < 500 || declaration?.allowServerErrorStatus === true)) {
+    return declared
+  }
+
+  return markerOf(error)?.status ?? null
+}
+
+/** The server's incident id carried by an error — its own field, else its marker — or `null`. */
+export const incidentIdOf = (error: unknown): string | null => {
+  if (error == null || typeof error !== 'object') {
+    return null
+  }
+  const own = (error as { incidentId?: unknown }).incidentId
+  if (typeof own === 'string' && own !== '') {
+    return own
+  }
+
+  return markerOf(error)?.incidentId ?? null
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * Whether a response body is a production incident body — the bare incident UUID an
+ * `@owlmeans/server-api` boundary sends instead of the marshaled error. A development body
+ * carries the `ResilientError` separator and is never one.
+ */
+export const isIncidentBody = (data: unknown): data is string =>
+  typeof data === 'string' && !data.includes(ResilientError.separator) && UUID.test(data.trim())

package/src/status/marker.ts

@@ -0,0 +1,37 @@
+/** The prefix every `ApiClientError` message carries. */
+export const API_CLIENT_MARKER = 'api:client:'
+
+/** The marker of an `ApiStatusError`: `api:client:status:<n>[:<incident id>]`. */
+export const API_STATUS_MARKER = `${API_CLIENT_MARKER}status:`
+
+/**
+ * `crashed` / `auth` / `forbidden` / `status:<n>` / the legacy bare `<n>`, then an optional
+ * `:<incident id>`. The look-ahead refuses a match that runs on into more marker text, so a
+ * doubled prefix (a subclass constructor handed a whole marshaled message) resolves to the inner,
+ * complete marker.
+ */
+const MARKER = /api:client:(?:(crashed|auth|forbidden)|status:(\d{3})|(\d{3}))(?::([\w.-]{1,128}))?(?![\w.:-])/
+
+const NAMED_STATUS: Record<string, number> = { crashed: 500, auth: 401, forbidden: 403 }
+
+/** What an `api:client:*` marker states. */
+export interface ClientMarker {
+  status?: number
+  incidentId?: string
+}
+
+/** Read the first `api:client:*` marker in a text, or `null` when it carries none. */
+export const parseClientMarker = (text: string): ClientMarker | null => {
+  const match = MARKER.exec(text)
+  if (match == null) {
+    return null
+  }
+  const [, named, coded, legacy, id] = match
+  const code = named != null ? NAMED_STATUS[named] : Number(coded ?? legacy)
+
+  return {
+    status: code >= 100 && code <= 599 ? code : undefined,
+    // `error` is the placeholder a marker gets when no incident id was known.
+    incidentId: id != null && id !== 'error' ? id : undefined,
+  }
+}

package/src/utils/handler.ts

@@ -1,9 +1,13 @@
 import type { AbstractResponse } from '@owlmeans/entrypoint'
 import { EntrypointOutcome } from '@owlmeans/entrypoint'
 import type { AxiosResponse } from 'axios'
-import { ACCEPTED, CREATED, FINISHED, FORBIDDEN_ERROR, OK, SERVER_ERROR, UNAUTHORIZED_ERROR } from '../consts.js'
+import {
+  ACCEPTED, CREATED, FINISHED, FORBIDDEN_ERROR, INCIDENT_ID_HEADER, OK, SERVER_ERROR, UNAUTHORIZED_ERROR,
+} from '../consts.js'
 import { ResilientError } from '@owlmeans/error'
-import { ApiClientError, ServerAuthError, ServerCrashedError } from '../errors.js'
+import { ApiClientError, ApiStatusError, ServerAuthError, ServerCrashedError } from '../errors.js'
+import { isIncidentBody } from '../status/index.js'
+import type { ResponseStatusCarrier } from '../status/index.js'
 
 export const processResponse = (response: AxiosResponse, reply: AbstractResponse<any>) => {
   switch (response.status) {
@@ -20,34 +24,70 @@ export const processResponse = (response: AxiosResponse, reply: AbstractResponse
     default:
 
       console.error(response.status, response.statusText)
-      console.error(response.config.url, response.headers)
+      console.error(response.config?.url, response.headers)
       console.error(response.data)
 
-      try {
-        if (typeof response.data === 'string') {
-          reply.reject(ResilientError.ensure(response.data, true))
-          return
-        }
-      } catch {
-        console.error(`Server returned an unrecognizable text error: ${response.status} ${response.data}`)
-      }
-      switch (response.status) {
-        case SERVER_ERROR:
-          reply.reject(new ServerCrashedError())
-          return
-        case UNAUTHORIZED_ERROR:
-          reply.reject(new ServerAuthError())
-          return
-        case FORBIDDEN_ERROR:
-          reply.reject(new ApiClientError('forbidden'))
-          return
-        default:
-          reply.reject(new ApiClientError(`${response.status}`))
-          return
-      }
+      reply.reject(failureOf(response))
   }
 }
 
+/**
+ * The error a non-2xx answer rejects with — always carrying the HTTP status and, when the server
+ * sent one, its incident id.
+ *
+ * A development body is the marshaled `ResilientError`: it is rebuilt into its own class and
+ * stamped with `responseStatus`. Anything else — the bare incident id of a production body, a
+ * proxy's HTML, a framework's JSON — becomes the status error of {@link statusError}.
+ */
+const failureOf = (response: AxiosResponse): Error => {
+  const incidentId = headerOf(response.headers, INCIDENT_ID_HEADER)
+    ?? (isIncidentBody(response.data) ? response.data.trim() : undefined)
+
+  if (typeof response.data === 'string' && response.data.includes(ResilientError.separator)) {
+    try {
+      const error = ResilientError.ensure(response.data, true)
+      error.incidentId ??= incidentId
+      Object.assign(error, { responseStatus: response.status } satisfies ResponseStatusCarrier)
+
+      return error
+    } catch {
+      console.error(`Server returned an unrecognizable text error: ${response.status} ${response.data}`)
+    }
+  }
+
+  return statusError(response.status, incidentId)
+}
+
+/**
+ * The typed error of a bare status: `ServerCrashedError` (500), `ServerAuthError` (401),
+ * `ApiClientError('forbidden[:<id>]')` (403), `ApiStatusError` (`api:client:status:<n>[:<id>]`)
+ * for every other one.
+ */
+export const statusError = (status: number, incidentId?: string): ApiClientError => {
+  const error = status === SERVER_ERROR ? new ServerCrashedError(incidentId)
+    : status === UNAUTHORIZED_ERROR ? new ServerAuthError(incidentId)
+      : status === FORBIDDEN_ERROR ? new ApiClientError(incidentId != null ? `forbidden:${incidentId}` : 'forbidden')
+        : new ApiStatusError(status, incidentId)
+  if (incidentId != null) {
+    error.incidentId = incidentId
+  }
+
+  return Object.assign(error, { responseStatus: status } satisfies ResponseStatusCarrier)
+}
+
+/** One response header, from an `AxiosHeaders` instance or a plain header object alike. */
+const headerOf = (headers: unknown, name: string): string | undefined => {
+  if (headers == null || typeof headers !== 'object') {
+    return undefined
+  }
+  const get = (headers as { get?: unknown }).get
+  const viaGet = typeof get === 'function' ? get.call(headers, name) : undefined
+  const value = viaGet ?? Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1]
+  const first = Array.isArray(value) ? value[0] : value
+
+  return typeof first === 'string' && first.trim() !== '' ? first.trim() : undefined
+}
+
 const processEmptyResponse = (response: AxiosResponse, reply: AbstractResponse<any>, outcome: EntrypointOutcome) => {
   if (response.data != null && response.data != '') {
     reply.resolve(response.data, outcome)

package/tests/handler.spec.ts

@@ -0,0 +1,186 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test'
+import { AxiosHeaders } from 'axios'
+import type { AxiosResponse } from 'axios'
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import { EntrypointOutcome } from '@owlmeans/entrypoint'
+import { ResilientError } from '@owlmeans/error'
+import {
+  ApiClientError, ApiStatusError, ServerAuthError, ServerCrashedError, httpStatusOf, incidentIdOf,
+  INCIDENT_ID_HEADER,
+} from '../src/index.js'
+import { processResponse, statusError } from '../src/utils/handler.js'
+import * as status from '../src/status/index.js'
+
+const INCIDENT = '6f1c1a52-8a0e-4f5e-9a7c-1f2d3e4c5b6a'
+
+class ConsentRequired extends ResilientError {
+  public static override typeName = 'ApiSpecConsentRequired'
+  public static httpStatus = 428
+
+  constructor(message: string = 'error') {
+    super(ConsentRequired.typeName, `spec:consent-required:${message}`)
+  }
+}
+ResilientError.registerErrorClass(ConsentRequired)
+
+class Unavailable extends ResilientError {
+  public static override typeName = 'ApiSpecUnavailable'
+  public static httpStatus = 503
+
+  constructor(message: string = 'error') {
+    super(Unavailable.typeName, message)
+  }
+}
+
+const respond = (
+  statusCode: number, data: unknown, headers: Record<string, string> | AxiosHeaders = {}
+): AbstractResponse<unknown> => {
+  const reply: AbstractResponse<unknown> = {
+    resolve: (value, outcome) => { reply.value = value; reply.outcome = outcome },
+    reject: error => { reply.error = error },
+  }
+  processResponse({
+    status: statusCode, statusText: '', data, headers, config: { url: '/spec' },
+  } as unknown as AxiosResponse, reply)
+
+  return reply
+}
+
+const quiet = console.error
+beforeAll(() => { console.error = () => {} })
+afterAll(() => { console.error = quiet })
+
+describe('2xx', () => {
+  test('resolve exactly as before', () => {
+    expect(respond(200, { ok: true })).toMatchObject({ value: { ok: true }, outcome: EntrypointOutcome.Ok })
+    expect(respond(202, 'queued')).toMatchObject({ value: 'queued', outcome: EntrypointOutcome.Accepted })
+    expect(respond(204, '', { 'x-a': '1' })).toMatchObject({ value: { 'x-a': '1' }, outcome: EntrypointOutcome.Finished })
+  })
+})
+
+describe('a production incident body keeps its status and incident id', () => {
+  test('428 with the header becomes ApiStatusError', () => {
+    const { error } = respond(428, INCIDENT, { [INCIDENT_ID_HEADER.toLowerCase()]: INCIDENT })
+    expect(error).toBeInstanceOf(ApiStatusError)
+    expect(error!.message).toBe(`api:client:status:428:${INCIDENT}`)
+    expect(httpStatusOf(error)).toBe(428)
+    expect(incidentIdOf(error)).toBe(INCIDENT)
+    expect((error as ApiStatusError).status).toBe(428)
+  })
+
+  test('the header is read from AxiosHeaders too, and the body alone suffices', () => {
+    const headers = new AxiosHeaders({ [INCIDENT_ID_HEADER]: INCIDENT })
+    expect(incidentIdOf(respond(409, 'x', headers).error)).toBe(INCIDENT)
+    expect(incidentIdOf(respond(402, INCIDENT).error)).toBe(INCIDENT)
+    expect(httpStatusOf(respond(402, INCIDENT).error)).toBe(402)
+  })
+
+  test('500, 401 and 403 keep their classes and markers', () => {
+    const crashed = respond(500, INCIDENT).error
+    expect(crashed).toBeInstanceOf(ServerCrashedError)
+    expect(crashed!.message).toBe(`api:client:crashed:${INCIDENT}`)
+    expect(httpStatusOf(crashed)).toBe(500)
+
+    const auth = respond(401, INCIDENT).error
+    expect(auth).toBeInstanceOf(ServerAuthError)
+    expect(auth!.message).toBe(`api:client:auth:${INCIDENT}`)
+    expect(httpStatusOf(auth)).toBe(401)
+
+    const forbidden = respond(403, INCIDENT).error
+    expect(forbidden).toBeInstanceOf(ApiClientError)
+    expect(forbidden).not.toBeInstanceOf(ApiStatusError)
+    expect(forbidden!.message).toBe(`api:client:forbidden:${INCIDENT}`)
+    expect(httpStatusOf(forbidden)).toBe(403)
+  })
+
+  test('without an incident id the markers stay as before', () => {
+    expect(statusError(500).message).toBe('api:client:crashed:error')
+    expect(statusError(403).message).toBe('api:client:forbidden')
+    expect(incidentIdOf(statusError(500))).toBeNull()
+    expect(statusError(418).message).toBe('api:client:status:418')
+  })
+
+  test('a proxy HTML page or framework JSON becomes a status error', () => {
+    const html = respond(502, '<html><body>Bad Gateway</body></html>').error
+    expect(html).toBeInstanceOf(ApiStatusError)
+    expect(httpStatusOf(html)).toBe(502)
+    expect(incidentIdOf(html)).toBeNull()
+
+    const json = respond(400, { statusCode: 400, error: 'Bad Request', message: 'body/x' }).error
+    expect(json).toBeInstanceOf(ApiStatusError)
+    expect(httpStatusOf(json)).toBe(400)
+  })
+
+  test('no class declares a static httpStatus, so a rethrow upstream stays 500', () => {
+    for (const error of [statusError(428), statusError(500), statusError(401), statusError(403)]) {
+      expect((error.constructor as { httpStatus?: unknown }).httpStatus).toBeUndefined()
+    }
+  })
+})
+
+describe('a development body stays its typed class', () => {
+  test('rebuilt with responseStatus and incident id', () => {
+    const body = ResilientError.marshal(new ConsentRequired('2'), { includeStack: true, incidentId: INCIDENT }).message
+    const { error } = respond(428, body, { [INCIDENT_ID_HEADER]: INCIDENT })
+    expect(error).toBeInstanceOf(ConsentRequired)
+    expect(error!.message).toBe('spec:consent-required:2')
+    expect((error as { responseStatus?: number }).responseStatus).toBe(428)
+    expect(httpStatusOf(error)).toBe(428)
+    expect(incidentIdOf(error)).toBe(INCIDENT)
+  })
+
+  test('a typed api error keeps its marker fields', () => {
+    const body = ResilientError.marshal(new ApiStatusError(409, INCIDENT)).message
+    const error = respond(409, body).error as ApiStatusError
+    expect(error).toBeInstanceOf(ApiStatusError)
+    expect(error.status).toBe(409)
+    expect(error.incidentId).toBe(INCIDENT)
+  })
+})
+
+describe('marshal round trips', () => {
+  const roundTrip = (error: Error): ResilientError => ResilientError.ensure(ResilientError.marshal(error))
+
+  test('keep status and incident id of every client error', () => {
+    const cases: Array<[ApiClientError, number]> = [
+      [new ApiStatusError(428, INCIDENT), 428],
+      [new ServerCrashedError(INCIDENT), 500],
+      [new ServerAuthError(INCIDENT), 401],
+      [new ApiClientError(`forbidden:${INCIDENT}`), 403],
+    ]
+    for (const [error, code] of cases) {
+      const back = roundTrip(error)
+      expect(back.constructor).toBe(error.constructor)
+      expect((back as ApiClientError).status).toBe(code)
+      expect(httpStatusOf(back)).toBe(code)
+      expect(incidentIdOf(back)).toBe(INCIDENT)
+    }
+  })
+
+  test('a legacy bare-status marker still reads', () => {
+    expect(httpStatusOf(new ApiClientError('404'))).toBe(404)
+  })
+})
+
+describe('./status', () => {
+  test('a declared static 428 answers without any marker; an undeclared 5xx does not', () => {
+    expect(status.httpStatusOf(new ConsentRequired())).toBe(428)
+    expect(status.httpStatusOf(new Unavailable())).toBeNull()
+    expect(status.httpStatusOf(new Error('plain'))).toBeNull()
+    expect(status.httpStatusOf(null)).toBeNull()
+  })
+
+  test('reads a marker from a plain error message or a type', () => {
+    expect(status.httpStatusOf(new Error(`${status.API_STATUS_MARKER}428:${INCIDENT}`))).toBe(428)
+    expect(status.httpStatusOf({ type: 'api:client:auth:error' })).toBe(401)
+    expect(status.incidentIdOf(new Error(`api:client:crashed:${INCIDENT}`))).toBe(INCIDENT)
+  })
+
+  test('isIncidentBody accepts a bare incident UUID only', () => {
+    expect(status.isIncidentBody(INCIDENT)).toBe(true)
+    expect(status.isIncidentBody(`${INCIDENT}\n`)).toBe(true)
+    expect(status.isIncidentBody('Unauthorized')).toBe(false)
+    expect(status.isIncidentBody(`ApiError|||api:x|||${INCIDENT}`)).toBe(false)
+    expect(status.isIncidentBody({ id: INCIDENT })).toBe(false)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tsconfig.json

@@ -6,5 +6,5 @@
     "rootDir": "./src/",
     "outDir": "./build/"
   },
-  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts"]
+  "exclude": ["./dist/**/*", "./build/**/*", "./*.ts", "./tests/**/*"]
 }