@owlmeans/api 0.1.18-rc.5 → 0.1.18-rc.50

package/build/utils/response.js

@@ -0,0 +1,99 @@
+import { EntrypointOutcome } from '@owlmeans/entrypoint';
+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, ApiStatusError, ServerAuthError, ServerCrashedError } from '../errors.js';
+import { apiStatusHelper } from '../status/helper.js';
+import { logger } from '@owlmeans/log';
+export const createResponseUtils = () => {
+    const log = logger('api');
+    const processResponse = (response, reply) => {
+        switch (response.status) {
+            case OK:
+                reply.resolve(response.data, EntrypointOutcome.Ok);
+                return;
+            case ACCEPTED:
+                reply.resolve(response.data, EntrypointOutcome.Accepted);
+                return;
+            case CREATED:
+                return processEmptyResponse(response, reply, EntrypointOutcome.Created);
+            case FINISHED:
+                return processEmptyResponse(response, reply, EntrypointOutcome.Finished);
+            default:
+                // A refusal is ordinary traffic (401, 403, 409, 428): debug, and never the headers.
+                log.debug('Request answered with a failure', {
+                    status: response.status, statusText: response.statusText, url: response.config?.url,
+                    incidentId: headerOf(response.headers, INCIDENT_ID_HEADER),
+                });
+                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)
+            ?? (apiStatusHelper.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 {
+                log.warn('Server returned an unrecognizable text error', { status: response.status, body: 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.
+     */
+    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);
+            return;
+        }
+        if (response.headers.toJSON != null && typeof response.headers.toJSON === 'function') {
+            reply.resolve(response.headers.toJSON(), outcome);
+            return;
+        }
+        reply.resolve(response.headers, outcome);
+    };
+    return { processResponse, statusError };
+};
+export const responseUtils = createResponseUtils();
+//# sourceMappingURL=response.js.map

package/build/utils/response.js.map

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

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@owlmeans/api",
-  "version": "0.1.18-rc.5",
+  "version": "0.1.18-rc.50",
   "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,23 +19,32 @@
       "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.5",
-    "@owlmeans/client-config": "^0.1.18-rc.5",
-    "@owlmeans/client-route": "^0.1.18-rc.5",
-    "@owlmeans/config": "^0.1.18-rc.5",
-    "@owlmeans/context": "^0.1.18-rc.5",
-    "@owlmeans/error": "^0.1.18-rc.5",
-    "@owlmeans/entrypoint": "^0.1.18-rc.5",
-    "@owlmeans/route": "^0.1.18-rc.5",
-    "axios": "^1.7.7",
-    "qs": "^6.13.0"
+    "@owlmeans/auth-common": "^0.1.18-rc.50",
+    "@owlmeans/client-config": "^0.1.18-rc.45",
+    "@owlmeans/client-route": "^0.1.18-rc.51",
+    "@owlmeans/config": "^0.1.18-rc.44",
+    "@owlmeans/context": "^0.1.18-rc.34",
+    "@owlmeans/entrypoint": "^0.1.18-rc.41",
+    "@owlmeans/error": "^0.1.18-rc.38",
+    "@owlmeans/log": "^0.1.18-rc.3",
+    "@owlmeans/route": "^0.1.18-rc.35",
+    "axios": "^1.20.0",
+    "qs": "^6.16.0"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",
-    "@types/qs": "^6.9.16",
+    "@owlmeans/resource": "^0.1.18-rc.40",
+    "@types/qs": "^6.15.1",
     "nodemon": "^3.1.14",
     "typescript": "^7.0.2"
   },

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,9 @@
-
 export * from './errors.js'
 export * from './consts.js'
 export * from './service.js'
 export type * from './types.js'
+export {
+  httpStatusOf, apiStatusHelper, createApiStatusHelper, parseClientMarker, API_CLIENT_MARKER, API_STATUS_MARKER,
+} from './status/index.js'
+export type { ClientMarker, ApiStatusHelper } from './status/index.js'
+export type { ResponseStatusCarrier } from './status/types.js'

package/src/service.ts

@@ -1,23 +1,21 @@
 import { assertContext, createService } from '@owlmeans/context'
-import type { BasicContext } from '@owlmeans/context'
-import { extractParams } from '@owlmeans/client-route'
+import { clientRouteHelper } from '@owlmeans/client-route'
 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 { processResponse } from './utils/handler.js'
-import { BasicClientConfig } from '@owlmeans/client-config'
-import qs from 'qs'
+import { DEFAULT_ALIAS, UNAUTHORIZED_ERROR } from './consts.js'
+import { responseUtils } from './utils/response.js'
 import { makeSecurityHelper } from '@owlmeans/config'
-import { RouteMethod } from '@owlmeans/route'
-import { DEF_AUTH_SRV, TOKEN_UPDATE } from '@owlmeans/auth-common'
-import type { AuthService } from '@owlmeans/auth-common'
+import { AUTH_HEADER, DEF_AUTH_SRV, TOKEN_UPDATE, type AuthService } from '@owlmeans/auth-common'
+import type { Config, Context } from './types.local.js'
+import { bodyUtils } from './utils/body.js'
 
-type Config = BasicClientConfig
-
-interface Context<C extends Config = Config> extends BasicContext<C> {
-}
+/** 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 !== ''
+  )
 
 export const createApiService = (alias: string = DEFAULT_ALIAS): ApiClient => {
   const location = `api.service:${alias}`
@@ -28,10 +26,9 @@ 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()
-      const params = extractParams(path)
+      let path = module.path()
+      const params = clientRouteHelper.extractParams(path)
       path = params.reduce((path, param) => {
         type Key = keyof typeof request.params
         if (request.params[param as Key] == null) {
@@ -39,36 +36,29 @@ 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 })
-
-      let transformer: AxiosRequestTransformer | undefined = undefined
-
-      let body = request.body != null && Object.entries((request.headers ?? {})).find(
-        ([key, value]) =>
-          key.toLowerCase() === 'content-type' && value?.includes('application/x-www-form-urlencoded')
-      ) ? qs.stringify(request.body) : request.body
-
-      // @TODO Probably this hack needs to be made a little bit less dirty
-      if (typeof body === 'string' && route.method === RouteMethod.POST) {
-        if (Object.keys(request.headers).every(key => key.toLowerCase() !== 'content-type')) {
-          request.headers['content-type'] = 'application/json'
-          // It fixes the case when final rest api under application/json can't
-          // properly accept canonized jsoned string value (put into quotes)
-          transformer = data => data
-        }
-      }
+      // 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 }
+      )
+
+      // A scalar JSON body (a string, a number, a boolean) is serialized here, so the server parses
+      // back the value the caller sent; objects and arrays are left to axios.
+      const body = bodyUtils.requestBodyOf(request.body, request.headers, route.method, module.filter?.body)
+      const transformer: AxiosRequestTransformer | undefined = body.verbatim ? data => data : undefined
+      const requestHeaders = body.contentType != null
+        ? { ...request.headers, 'content-type': body.contentType }
+        : request.headers
 
       const response = await axios.request({
         url, method: route.method,
         params: request.query,
-        data: body,
-        headers: request.headers,
+        data: body.data,
+        headers: requestHeaders,
         transformRequest: transformer,
         validateStatus: () => true,
         // Per-request timeout (ms); axios aborts the request and rejects on expiry.
@@ -84,9 +74,27 @@ 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)
+      responseUtils.processResponse(response, reply)
 
       return [reply.error ?? reply.value, reply.outcome] as any
     }

package/src/status/consts.local.ts

@@ -0,0 +1,11 @@
+export const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/**
+ * `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.
+ */
+export const MARKER = /api:client:(?:(crashed|auth|forbidden)|status:(\d{3})|(\d{3}))(?::([\w.-]{1,128}))?(?![\w.:-])/
+
+export const NAMED_STATUS: Record<string, number> = { crashed: 500, auth: 401, forbidden: 403 }

package/src/status/consts.ts

@@ -0,0 +1,5 @@
+/** 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:`

package/src/status/helper.ts

@@ -0,0 +1,63 @@
+import { ResilientError } from '@owlmeans/error'
+import { ApiClientError } from '../errors.js'
+import { parseClientMarker } from './marker.js'
+import { ACCESS_DENIED_KIND } from '../consts.js'
+import { UUID } from './consts.local.js'
+import type { ApiStatusHelper, ClientMarker, ResponseStatusCarrier } from './types.js'
+
+export const createApiStatusHelper = (): ApiStatusHelper => {
+  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): ClientMarker | null => {
+    const { message, type } = error as { message?: unknown, type?: unknown }
+
+    return (typeof message === 'string' ? parseClientMarker(message) : null)
+      ?? (typeof type === 'string' ? parseClientMarker(type) : null)
+  }
+
+  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
+  }
+
+  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 isIncidentBody = (data: unknown): data is string =>
+    typeof data === 'string' && !data.includes(ResilientError.separator) && UUID.test(data.trim())
+
+  return { isAccessDenied, httpStatusOf, incidentIdOf, isIncidentBody }
+}
+
+export const apiStatusHelper = createApiStatusHelper()

package/src/status/index.ts

@@ -0,0 +1,11 @@
+import { apiStatusHelper } from './helper.js'
+
+export { INCIDENT_ID_HEADER } from '../consts.js'
+export { DENIAL_KIND_HEADER, ACCESS_DENIED_KIND } from '../consts.js'
+export { parseClientMarker } from './marker.js'
+export { API_CLIENT_MARKER, API_STATUS_MARKER } from './consts.js'
+export type { ClientMarker, ResponseStatusCarrier, ApiStatusHelper } from './types.js'
+export { apiStatusHelper, createApiStatusHelper } from './helper.js'
+
+/** @deprecated compat:factory-refactor — use `apiStatusHelper.httpStatusOf(…)` */
+export const httpStatusOf = (error: unknown): number | null => apiStatusHelper.httpStatusOf(error)

package/src/status/marker.ts

@@ -0,0 +1,19 @@
+
+/** Read the first `api:client:*` marker in a text, or `null` when it carries none. */
+import { MARKER, NAMED_STATUS } from './consts.local.js'
+import type { ClientMarker } from './types.js'
+
+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/status/types.ts

@@ -0,0 +1,36 @@
+/** The HTTP status the API client stamps on an error it rebuilt from a response body. */
+export interface ResponseStatusCarrier {
+  responseStatus?: number
+  denialKind?: string
+}
+
+/** What an `api:client:*` marker states. */
+export interface ClientMarker {
+  status?: number
+  incidentId?: string
+}
+
+/** Reads the HTTP status, the incident id and the denial kind a failed call carries. */
+export interface ApiStatusHelper {
+  /** True only for a server-labelled auth/IAM refusal, never an unrelated 403. */
+  isAccessDenied: (error: unknown) => boolean
+  /**
+   * 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.
+   */
+  httpStatusOf: (error: unknown) => number | null
+  /** The server's incident id carried by an error — its own field, else its marker — or `null`. */
+  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.
+   */
+  isIncidentBody: (data: unknown) => data is string
+}

package/src/types.local.ts

@@ -0,0 +1,7 @@
+import { BasicClientConfig } from '@owlmeans/client-config'
+import type { BasicContext } from '@owlmeans/context'
+
+export type Config = BasicClientConfig
+
+export interface Context<C extends Config = Config> extends BasicContext<C> {
+}

package/src/utils/body/types.ts

@@ -0,0 +1,37 @@
+import type { RouteMethod } from '@owlmeans/route'
+
+export interface RequestBody {
+  /** What axios is handed as `data`. */
+  data: unknown
+  /** A `content-type` the request lacked and must carry. */
+  contentType?: string
+  /** `data` is final text — axios must not transform it again. */
+  verbatim: boolean
+}
+
+/** How a request's body travels: its content type and the text a scalar body becomes. */
+export interface BodyUtils {
+  /** The request's own `content-type`, whatever case its key is written in. */
+  contentTypeOf: (headers?: Record<string, unknown>) => string | undefined
+  /** `application/json` or a `+json` suffix type, with or without parameters. */
+  isJsonContentType: (type?: string) => boolean
+  /**
+   * The JSON text a scalar body travels as, so the server parses it back to the same value.
+   *
+   * A number or a boolean is `JSON.stringify`'d. A string is a value unless it is already JSON text:
+   * one that does not parse is quoted; one that parses is sent as it is (the caller serialized it
+   * itself) — except under a body schema of `type: 'string'`, where only a JSON string literal
+   * counts as serialized and `123`, `true` or `{…}` are the text the caller means.
+   */
+  jsonScalarBody: (body: string | number | boolean, schema?: object) => string
+  /**
+   * What a request's body becomes on the wire.
+   *
+   * - A `x-www-form-urlencoded` request: the body through `qs`.
+   * - A string, number or boolean under a JSON `content-type` — the caller's, or `application/json`
+   *   supplied for a `POST` that names none — becomes JSON text ({@link BodyUtils.jsonScalarBody}).
+   * - Anything else — objects, arrays, a scalar under another content type — goes to axios as it is,
+   *   which serializes an object or an array as JSON.
+   */
+  requestBodyOf: (body: unknown, headers: Record<string, unknown> | undefined, method?: RouteMethod, schema?: object) => RequestBody
+}