@owlmeans/api 0.1.18-rc.4 → 0.1.18-rc.40

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;AAM1C,OAAO,EAAE,cAAc,EAAuD,MAAM,cAAc,CAAA;AAIlG,eAAO,MAAM,eAAe,aAAc,aAAa,SAAS,gBAAgB,CAAC,GAAG,CAAC,SAoBpF,CAAA;AAkCD;;;;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, DENIAL_KIND_HEADER, ACCESS_DENIED_KIND, 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,66 @@ 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);
+    const denialKind = response.status === FORBIDDEN_ERROR
+        && headerOf(response.headers, DENIAL_KIND_HEADER) === ACCESS_DENIED_KIND
+        ? ACCESS_DENIED_KIND : 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, denialKind,
+            });
+            return error;
+        }
+        catch {
+            console.error(`Server returned an unrecognizable text error: ${response.status} ${response.data}`);
+        }
+    }
+    return Object.assign(statusError(response.status, incidentId), { denialKind });
+};
+/**
+ * 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.4",
+  "version": "0.1.18-rc.40",
   "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.4",
-    "@owlmeans/client-config": "^0.1.18-rc.4",
-    "@owlmeans/client-route": "^0.1.18-rc.4",
-    "@owlmeans/config": "^0.1.18-rc.4",
-    "@owlmeans/context": "^0.1.18-rc.4",
-    "@owlmeans/error": "^0.1.18-rc.4",
-    "@owlmeans/entrypoint": "^0.1.18-rc.4",
-    "@owlmeans/route": "^0.1.18-rc.4",
+    "@owlmeans/auth-common": "^0.1.18-rc.40",
+    "@owlmeans/client-config": "^0.1.18-rc.38",
+    "@owlmeans/client-route": "^0.1.18-rc.41",
+    "@owlmeans/config": "^0.1.18-rc.38",
+    "@owlmeans/context": "^0.1.18-rc.32",
+    "@owlmeans/error": "^0.1.18-rc.36",
+    "@owlmeans/entrypoint": "^0.1.18-rc.37",
+    "@owlmeans/route": "^0.1.18-rc.33",
     "axios": "^1.7.7",
     "qs": "^6.13.0"
   },

package/src/consts.ts

@@ -13,6 +13,14 @@ 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 DENIAL_KIND_HEADER = 'X-OwlMeans-Denial'
+export const ACCESS_DENIED_KIND = 'access-denied'
+
 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/service.ts

@@ -5,15 +5,21 @@ import type { ApiClient } from './types.js'
 import axios, { AxiosHeaders } from 'axios'
 import type { AxiosRequestTransformer } from 'axios'
 import type { CommonEntrypoint } from '@owlmeans/entrypoint'
-import { DEFAULT_ALIAS } from './consts.js'
+import { DEFAULT_ALIAS, UNAUTHORIZED_ERROR } from './consts.js'
 import { processResponse } from './utils/handler.js'
 import { BasicClientConfig } from '@owlmeans/client-config'
 import qs from 'qs'
 import { makeSecurityHelper } from '@owlmeans/config'
 import { RouteMethod } from '@owlmeans/route'
-import { DEF_AUTH_SRV, TOKEN_UPDATE } from '@owlmeans/auth-common'
+import { AUTH_HEADER, DEF_AUTH_SRV, TOKEN_UPDATE } from '@owlmeans/auth-common'
 import type { AuthService } from '@owlmeans/auth-common'
 
+/** Whether a request carried an authentication header of its own. */
+const presented = (headers?: Record<string, unknown>): boolean =>
+  headers != null && Object.entries(headers).some(
+    ([key, value]) => key.toLowerCase() === AUTH_HEADER && value != null && value !== ''
+  )
+
 type Config = BasicClientConfig
 
 interface Context<C extends Config = Config> extends BasicContext<C> {
@@ -28,9 +34,8 @@ export const createApiService = (alias: string = DEFAULT_ALIAS): ApiClient => {
       }
       const context = assertContext<Config, Context>(client.ctx, location)
       const module = context.entrypoint<CommonEntrypoint>(request.alias)
-      await module.resolve()
       const route = module.route.route
-      let path = module.getPath()
+      let path = module.path()
       const params = extractParams(path)
       path = params.reduce((path, param) => {
         type Key = keyof typeof request.params
@@ -39,13 +44,15 @@ export const createApiService = (alias: string = DEFAULT_ALIAS): ApiClient => {
         }
         return path.replace(`:${param}`, `${request.params[param as Key]}`)
       }, path)
-      if (route.host == null && request.host == null) {
-        throw new SyntaxError(`No host provided in ${module.alias} route`)
-      }
 
       const helper = makeSecurityHelper(context)
 
-      const url = helper.makeUrl(route, path, { host: request.host, base: request.base, forceUnsecure: request.unsecure })
+      // The entrypoint answers where it lives — host, port, base, protocol and whether the hop is
+      // TLS — from its declaration and the service it names. A per-request host still overrides it.
+      const url = helper.makeUrl(
+        module.address(), path,
+        { host: request.host, base: request.base, forceUnsecure: request.unsecure }
+      )
 
       let transformer: AxiosRequestTransformer | undefined = undefined
 
@@ -84,6 +91,24 @@ export const createApiService = (alias: string = DEFAULT_ALIAS): ApiClient => {
         const auth = context.service<AuthService>(DEF_AUTH_SRV)
         const update = headers.get(TOKEN_UPDATE) as string
         await auth.update(update == null || update === '' ? undefined : update)
+      } else if (
+        response.status === UNAUTHORIZED_ERROR
+        && presented(request.headers)
+        && context.hasService(DEF_AUTH_SRV)
+      ) {
+        /**
+         * A session the server has refused is not a session, and keeping it is worse than having
+         * none: the application goes on rendering its signed-in tree over a credential that fails
+         * every call it makes, and nothing on the client ever asks again — `authenticated()` reads
+         * storage and decodes an envelope, it does not consult the server. What that leaves is an
+         * app that looks signed in, works at nothing, and offers "Log out" where the control that
+         * would fix it should be.
+         *
+         * Narrow on purpose. Only a request that actually PRESENTED this context's bearer counts,
+         * so a 401 from an authentication attempt — bad code, wrong password, an expired challenge
+         * — never clears the session of whoever is already signed in.
+         */
+        await context.service<AuthService>(DEF_AUTH_SRV).update(undefined)
       }
 
       processResponse(response, reply)

package/src/status/index.ts

@@ -0,0 +1,85 @@
+import { ResilientError } from '@owlmeans/error'
+import { ApiClientError } from '../errors.js'
+import { parseClientMarker } from './marker.js'
+
+export { INCIDENT_ID_HEADER } from '../consts.js'
+export { DENIAL_KIND_HEADER, ACCESS_DENIED_KIND } from '../consts.js'
+import { ACCESS_DENIED_KIND } 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
+  denialKind?: string
+}
+
+/** True only for a server-labelled auth/IAM refusal, never an unrelated 403. */
+export const isAccessDenied = (error: unknown): boolean =>
+  httpStatusOf(error) === 403
+  && typeof error === 'object' && error != null
+  && (error as ResponseStatusCarrier).denialKind === ACCESS_DENIED_KIND
+
+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,
+  }
+}