@saasicat/ui-vue 0.24.2 → 0.26.0

package/src/client/admin-error.ts

@@ -0,0 +1,552 @@
+// One error type for everything that fails on the way to or from the admin
+// API, and one function that turns whatever was caught into it.
+//
+// The problem this solves: the package's HTTP contract (`HttpClient` in
+// `types.ts`) is a bare function type, so an error can arrive in any shape the
+// consumer's client produces — an axios rejection with `err.response.data`, a
+// `fetch` TypeError, a platform `HttpJsonError`, or a plain string. Code that
+// reads exactly one of those shapes works for exactly one kind of consumer and
+// silently shows nothing to the others.
+//
+// Two ideas are deliberately kept apart:
+//
+//   - `message` is the diagnostic. It names the request and what came back,
+//     and it belongs in logs and stack traces. It is never user-facing.
+//   - `detail` is the text the failing side supplied — a response body's
+//     `message`, or the message of a non-HTTP error we wrapped. It is the only
+//     candidate for showing a user, and it is `undefined` when there is none.
+//
+// `adminErrorMessage()` is what turns an error into user-facing text; it is
+// the only place that decides between `detail` and a translated fallback.
+
+import { formatMessage } from './i18n/format.js';
+import type { SaMessages } from './i18n/messages.js';
+
+/**
+ * Brand for cross-copy recognition.
+ *
+ * The package ships `dist/index.*` and `dist/client/index.*` as separate
+ * rollups, so an app that reaches `@saasicat/ui-vue` through both entries can
+ * hold two `AdminError` classes — `instanceof` is then false for an error the
+ * other copy created, and re-wrapping it would drop `status`, `code` and
+ * `body`. A `Symbol.for` key resolves through the process-wide registry, so
+ * every copy agrees on it.
+ */
+const ADMIN_ERROR = Symbol.for('@saasicat/ui-vue/AdminError');
+
+/**
+ * Brand for the error classes this package throws itself.
+ *
+ * `toAdminError` has to answer one question about a caught error: is its
+ * `message` something an operator should read? For a consumer's
+ * `Error('Quota exhausted')` the answer is yes. For
+ * `PlansApiError(403, {}, 'Plans API responded with HTTP 403')` it is no — that
+ * is a diagnostic, and showing it instead of the translated wording is what
+ * this whole separation exists to prevent.
+ *
+ * Shape cannot answer it. Both are `Error`s with a numeric `status`, and two
+ * successive attempts to guess — first from `status === 0`, then from a class
+ * name ending in `ApiError` — each turned out to catch consumer errors as well.
+ * A name suffix is a convention anyone may share; identity is not. `Symbol.for`
+ * because the package ships more than one bundle copy.
+ */
+const PLATFORM_ERROR = Symbol.for('@saasicat/ui-vue/PlatformError');
+
+/**
+ * Marks an error as one this package raised. Called by the package's own error
+ * classes in their constructors; nothing else should call it.
+ */
+export function markPlatformError(error: Error): void {
+    Object.defineProperty(error, PLATFORM_ERROR, { value: true });
+}
+
+/** Whether an error came from this package, across bundle copies. */
+export function isPlatformError(value: unknown): boolean {
+    return typeof value === 'object' && value !== null && PLATFORM_ERROR in value;
+}
+
+/**
+ * Brand for the throw sites where the request completed and only the body was
+ * missing.
+ *
+ * A second brand rather than an inference from the first, because the two
+ * answer different questions about different things. `PLATFORM_ERROR` is a
+ * fact about the *class* — is this `message` a diagnostic, or a consumer's
+ * words? Whether the server answered with an empty body is a fact about the
+ * *throw site*, and one class hosts both: `PlansApiError` is raised for
+ * `Plans API responded with HTTP 403` and for `Create returned no body`.
+ *
+ * Deriving the second from the first (`status === 0 && isPlatformError(err)`)
+ * looked equivalent and was not. `BootLoader.load`, `ManifestLoader` and
+ * `useDiscovery` pass a client-supplied status straight into a branded error
+ * behind a `status !== 200` guard, so an `HttpClient` that reports a transport
+ * failure as `status: 0` instead of rejecting — which XHR and axios do, and
+ * which `HttpClient` explicitly permits — produced a branded status-0 error
+ * for a read-only GET. `adminErrorMessage` then answered "check whether the
+ * change was applied" for a request that never left the machine and could not
+ * have changed anything.
+ *
+ * `Symbol.for` for the same reason as above: the package ships more than one
+ * bundle copy.
+ */
+const EMPTY_RESPONSE = Symbol.for('@saasicat/ui-vue/EmptyResponse');
+
+/**
+ * Marks an error as the empty-body sentinel: the call reached the server, the
+ * server answered, and the body the caller needed was not in it. Returns the
+ * error so a throw site stays one expression.
+ *
+ * Called at those throw sites only — never in a constructor, because the class
+ * is also raised for calls that failed outright.
+ */
+export function markEmptyResponse<E extends Error>(error: E): E {
+    Object.defineProperty(error, EMPTY_RESPONSE, { value: true });
+    return error;
+}
+
+/** Whether an error is that sentinel, across bundle copies. */
+export function isEmptyResponse(value: unknown): boolean {
+    return typeof value === 'object' && value !== null && EMPTY_RESPONSE in value;
+}
+
+/**
+ * Brand for the opposite fact: the request never reached the server.
+ *
+ * The third brand, and for the third time because the shape does not carry the
+ * answer. `err instanceof TypeError` was the guess here, and `TypeError` is
+ * also what a null dereference raises — `rows.map` on a `null` produced "check
+ * your connection" for a bug in the page. A name, a status and a class are all
+ * things two unrelated failures can share; only the seam that made the request
+ * knows whether it left the machine.
+ *
+ * `defaultHttpClient` marks what `fetch` rejects with, which is the one client
+ * this package ships. A consumer's `HttpClient` is welcome to mark its own
+ * rejections — that is why this is exported — and axios is read rather than
+ * branded, because a library cannot be asked to mark itself. What is read of it
+ * is its own statement about the request, not a shape that merely correlates
+ * with one; see `isAxiosNoResponseError`.
+ *
+ * `Symbol.for` for the same reason as above: the package ships more than one
+ * bundle copy.
+ */
+const TRANSPORT_FAILURE = Symbol.for('@saasicat/ui-vue/TransportFailure');
+
+/**
+ * Marks an error as one the request did not survive: no connection, DNS
+ * failure, CORS rejection, abort, or a client that reported the same by
+ * resolving without an HTTP status. Returns the error so a throw site stays one
+ * expression.
+ */
+export function markTransportFailure<E>(error: E): E {
+    if (typeof error === 'object' && error !== null) {
+        try {
+            Object.defineProperty(error, TRANSPORT_FAILURE, { value: true });
+        } catch {
+            // A frozen or sealed error cannot take the brand. Losing it costs
+            // the precise sentence; replacing the error would cost the
+            // diagnostic altogether, so the original is what propagates.
+        }
+    }
+    return error;
+}
+
+/** Whether an error is a declared transport failure, across bundle copies. */
+export function isTransportFailure(value: unknown): boolean {
+    return typeof value === 'object' && value !== null && TRANSPORT_FAILURE in value;
+}
+
+export interface AdminErrorInit {
+    /** HTTP status. `0` means the request never produced one. */
+    status?: number;
+    /** Machine-readable code from the response body (`{ code }`). */
+    code?: string;
+    /** Parsed response body, when there was one. */
+    body?: unknown;
+    /** Requested URL, when known. */
+    url?: string;
+    /** Request method, when known. */
+    method?: string;
+    /**
+     * Text the failing side supplied. Never invent one — its absence is the
+     * signal that only a translated fallback can be shown.
+     */
+    detail?: string;
+    /**
+     * The request completed and the answer was unusable — a 2xx that carried
+     * no body where one was required.
+     *
+     * Its own state because the model could not otherwise tell it from a
+     * transport failure: both have no HTTP status to report, and both were
+     * therefore `status: 0`. They need opposite words. A request that never
+     * left says "check your connection"; one the server accepted and answered
+     * with nothing says "check whether the change was applied", because it may
+     * well have been.
+     */
+    emptyResponse?: boolean;
+    /**
+     * The request never reached the server.
+     *
+     * Its own state for the same reason as `emptyResponse`: neither has an HTTP
+     * status to reason from, so a status of `0` cannot tell them apart — and
+     * neither can it tell either of them from an error that simply carries no
+     * status, such as a bug in page code. Only the seam that made the request
+     * knows, and it says so with `markTransportFailure`.
+     */
+    transportFailure?: boolean;
+    /** Diagnostic message. Derived from the fields above when omitted. */
+    message?: string;
+    /** The error this one was built from. */
+    cause?: unknown;
+}
+
+/**
+ * Builds the diagnostic message. Deliberately shaped like the one
+ * `admin-resource-client.ts` already produces (`GET /url → HTTP 403`), so
+ * logs read the same whichever layer threw.
+ */
+function describe(init: AdminErrorInit): string {
+    const status = init.status ?? 0;
+    const where = [init.method, init.url].filter(Boolean).join(' ');
+    const what = status > 0 ? `HTTP ${status}` : 'request failed';
+    const head = where ? `${where} → ${what}` : what;
+    const code = init.code ? ` (${init.code})` : '';
+    return init.detail ? `${head}${code}: ${init.detail}` : `${head}${code}`;
+}
+
+/** A failed admin API call, in the one shape the package works with. */
+export class AdminError extends Error {
+    /** HTTP status. `0` means the request never produced one. */
+    readonly status: number;
+    /** Machine-readable code from the response body, when it carried one. */
+    readonly code?: string;
+    /** Parsed response body, when there was one. */
+    readonly body?: unknown;
+    /** Requested URL, when known. */
+    readonly url?: string;
+    /** Request method, when known. */
+    readonly method?: string;
+    /**
+     * Text the failing side supplied — the only candidate for user-facing
+     * output. `undefined` when nothing was supplied.
+     */
+    readonly detail?: string;
+    /** The request completed but the answer was unusable. See `AdminErrorInit`. */
+    readonly emptyResponse: boolean;
+    /** The request never reached the server. See `AdminErrorInit`. */
+    readonly transportFailure: boolean;
+
+    constructor(init: AdminErrorInit = {}) {
+        super(init.message ?? describe(init), { cause: init.cause });
+        this.name = 'AdminError';
+        this.status = init.status ?? 0;
+        this.code = init.code;
+        this.body = init.body;
+        this.url = init.url;
+        this.method = init.method;
+        this.detail = init.detail;
+        this.emptyResponse = init.emptyResponse ?? false;
+        this.transportFailure = init.transportFailure ?? false;
+        Object.defineProperty(this, ADMIN_ERROR, { value: true });
+        // `message` here is `describe()`'s diagnostic, or one a throw site
+        // supplied — never text for a screen, which is exactly what the
+        // platform brand states. `toAdminError` returns an `AdminError`
+        // unchanged and so never reads it, but the promise holds for anyone
+        // who does, and it keeps the guard's rule ("every error class this
+        // package declares carries the brand") free of exceptions.
+        markPlatformError(this);
+    }
+}
+
+/** Whether `err` is an `AdminError`, including one from another bundle copy. */
+export function isAdminError(err: unknown): err is AdminError {
+    return typeof err === 'object' && err !== null && ADMIN_ERROR in err;
+}
+
+/** Narrows to an indexable object without asserting anything about its keys. */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+    return typeof value === 'object' && value !== null
+        ? (value as Record<string, unknown>)
+        : undefined;
+}
+
+function asString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+
+/**
+ * Whether an error is axios saying, in its own words, that the request was made
+ * and no response ever arrived.
+ *
+ * This is the one transport failure read rather than branded, because a library
+ * cannot be asked to mark itself. What it reads is axios's own three-way split,
+ * documented under "Handling errors" in its README and visible in the
+ * `AxiosError` constructor: `response` is set only when the server answered,
+ * `request` only once one was actually made, and an error with neither happened
+ * while the request was still being set up.
+ *
+ * Measured against axios 1.18.1 driven at a real `node:http` server, and the
+ * groups came out disjoint:
+ *
+ * | rejection                                       | `isAxiosError` | `request` | `response` |
+ * | ----------------------------------------------- | -------------- | --------- | ---------- |
+ * | connection refused / reset, DNS, timeout, abort  | `true`         | yes       | no         |
+ * | the same, rethrown by a rejection interceptor    | `true`         | yes       | no         |
+ * | a 401 or 500 the server really sent              | `true`         | yes       | yes        |
+ * | interceptor rejects with `new Error(…)`          | absent         | no        | no         |
+ * | …the same, but copying `error.config` across     | absent         | no        | no         |
+ * | …the same, copying `config` and `request`        | absent         | yes       | no         |
+ * | unsupported protocol, signal aborted before call | `true`         | no        | no         |
+ * | request interceptor throws, malformed URL        | absent         | no        | no         |
+ *
+ * Three readings follow from that table, and only the first is free of choice:
+ *
+ * - `response` present means the server answered, whatever else is set.
+ * - `request` present without it is axios's "made, nothing came back". The
+ *   browser and `fetch` adapters attach it too — an `XMLHttpRequest` and a
+ *   `Request` respectively — so the reading is not Node-only.
+ * - Requiring `isAxiosError` on top of that is the decision. It removes the
+ *   ordinary interceptor that copies `config` and `request` onto a hand-built
+ *   `new Error`, which is shape-wise axios's no-response form after the server
+ *   had answered.
+ *
+ * The previous reading was `config` without `response`, which is not axios's
+ * statement about anything: `config` is echoed on every axios error including
+ * the ones carrying a 401, and it is the field an interceptor is most likely to
+ * carry over when it replaces the rejection. It matched three rows above that
+ * mean the opposite of a transport failure.
+ *
+ * ## What this cannot decide, and which way it errs
+ *
+ * This is read *after* the consumer's interceptors have run — after the one
+ * place that can set or delete any field on the rejection. Both readings are
+ * therefore forgeable, in both directions, and each was reproduced:
+ *
+ * - An interceptor that **drops** `request` — `AxiosError.from(err, code,
+ *   config)` without its fourth argument, `err.toJSON()`, or a `delete
+ *   err.request` before logging — leaves a genuine `ECONNREFUSED` unbranded.
+ *   The operator then reads `connect ECONNREFUSED 127.0.0.1:44947` instead of
+ *   the localized sentence.
+ * - An interceptor that **builds** one — `AxiosError.from(msg, code,
+ *   error.config, error.request)` after an answered 401 — is branded. Nothing
+ *   distinguishes it: `AxiosError.from` is public API, so `isAxiosError` is
+ *   available to user code as well.
+ *
+ * Neither is closable by a better predicate; the fields simply do not carry the
+ * fact by then. So the reading errs deliberately toward *not* branding, because
+ * the two mistakes do not cost the same: an unbranded transport failure shows a
+ * true sentence in the wrong register, while a branded application failure tells
+ * the operator to check a connection that is fine. Saying less beats saying
+ * something false.
+ *
+ * An interceptor that rewrites rejections should say what it means with
+ * `markTransportFailure`, which is exported for exactly this. It is checked
+ * first and settles the case.
+ */
+export function isAxiosNoResponseError(value: unknown): boolean {
+    const record = asRecord(value);
+    if (!record) return false;
+    return record.isAxiosError === true && record.request != null && record.response == null;
+}
+
+/**
+ * Reads the human-readable message out of a response body.
+ *
+ * Covers the two shapes the platform and its host produce: a coded platform
+ * error (`{ code, message }`) carries a string, while a NestJS
+ * `ValidationPipe` rejection carries `message: string[]` — one entry per
+ * failed constraint. Joining them is what keeps a validation error readable
+ * instead of rendering as `[object Object]`.
+ *
+ * Exported because every place that builds an `AdminError` from a response
+ * needs the same answer. It had two implementations for one release and they
+ * disagreed: the one in `http-json.ts` accepted only a string, so a validation
+ * rejection arriving through `getJson`/`postJson` lost its constraints
+ * entirely and the operator was shown the generic fallback.
+ */
+export function readErrorDetail(body: unknown): string | undefined {
+    const record = asRecord(body);
+    if (!record) return asString(body);
+    const message = record.message;
+    if (Array.isArray(message)) {
+        const parts = message.filter((part): part is string => typeof part === 'string');
+        return parts.length > 0 ? parts.join(', ') : undefined;
+    }
+    return asString(message) ?? asString(record.error) ?? asString(record.reason);
+}
+
+/** Reads the machine-readable code out of a response body, if it carries one. */
+export function readErrorCode(body: unknown): string | undefined {
+    return asString(asRecord(body)?.code);
+}
+
+/**
+ * Turns anything that was caught into an `AdminError`.
+ *
+ * Recognises, in order: an `AdminError` (from any bundle copy), an axios-style
+ * rejection, an error carrying a numeric `status` — which is every one of the
+ * package's own `*ApiError` classes — and finally any `Error`, string or
+ * unknown value.
+ */
+export function toAdminError(err: unknown): AdminError {
+    if (isAdminError(err)) return err;
+
+    const record = asRecord(err);
+    const response = asRecord(record?.response);
+
+    // Axios rejection: the body sits under `response.data`, the request under
+    // `config`. Both are absent on a network failure, which axios reports as a
+    // rejection with no `response` at all.
+    if (response && typeof response.status === 'number') {
+        const config = asRecord(record?.config);
+        const body = response.data;
+        return new AdminError({
+            status: response.status,
+            code: readErrorCode(body),
+            body,
+            url: asString(config?.url),
+            method: asString(config?.method)?.toUpperCase(),
+            // Only what the response actually said. `err.message` here is
+            // axios's own generated line ("Request failed with status code
+            // 401") — English, untranslated, and about the transport rather
+            // than about what went wrong. Letting it through as `detail` would
+            // make `adminErrorMessage` return it in preference to the
+            // localized wording, which is the whole point of that wording.
+            detail: readErrorDetail(body),
+            cause: err,
+        });
+    }
+
+    // The package's own API errors (`BundlesApiError`, `PlansApiError`, …) all
+    // carry `status` and most carry the parsed `body`.
+    if (record && typeof record.status === 'number') {
+        // Only this package's own classes carry diagnostics in `message`. A
+        // consumer's status-bearing error — `Object.assign(new Error('Quota
+        // exhausted'), { status: 429 })` — says something an operator needs,
+        // and the page-level helper this replaces showed it.
+        const ours = isPlatformError(err);
+        return new AdminError({
+            status: record.status,
+            code: readErrorCode(record.body) ?? asString(record.code),
+            body: record.body,
+            // Same reasoning as above: `BundlesApiError`'s message is
+            // "Bundles API responded with HTTP 403", a diagnostic. It stays on
+            // `message`, where logs read it.
+            detail: readErrorDetail(record.body) ?? (ours ? undefined : asString(record.message)),
+            // Asked of the throw site, not of the class: only the site that
+            // read the response knows whether one arrived. `status === 0 &&
+            // ours` was the same question put to the wrong witness — the
+            // loaders raise branded errors from a status the client chose, so
+            // a client that resolves a transport failure as `0` turned a
+            // failed GET into "the change may have been applied".
+            emptyResponse: isEmptyResponse(err),
+            transportFailure: isTransportFailure(err),
+            message: asString(record.message),
+            cause: err,
+        });
+    }
+
+    if (err instanceof Error) {
+        // A transport failure carries no message from a failing side — only
+        // the client's own diagnostic, generated in English by whichever client
+        // is installed. Leaving `detail` unset is what lets
+        // `adminErrorMessage` reach `msgs.network`, the one sentence that
+        // actually tells the operator what to do.
+        //
+        // Which errors those are is declared, not inferred. `defaultHttpClient`
+        // brands what `fetch` rejects with; a consumer's client may brand its
+        // own. `err instanceof TypeError` used to stand in for it and was
+        // wrong in both directions: it caught every null dereference in page
+        // code ("Cannot read properties of null") and told the operator to
+        // check their connection, and it missed any client that fails with
+        // something else. Axios is the one shape still read rather than
+        // branded, because the package cannot ask a library to mark itself —
+        // but what is read of it is axios's own statement that the request was
+        // made and nothing came back, not the `config` it echoes on every
+        // rejection it produces. See `isAxiosNoResponseError` for the
+        // measurement; the `config` reading it replaces also caught an
+        // interceptor answering a 401 with its own error, which suppressed the
+        // very message the interceptor wrote.
+        //
+        // Anything else keeps its message: an `Error('Plan is locked')` from
+        // app code IS what the failing side said, and it is what the page-level
+        // copies this replaces showed.
+        const transport = isTransportFailure(err) || isAxiosNoResponseError(err);
+        // A `TypeError` nobody declared a transport failure is a JavaScript
+        // fault — `rows.map` on a `null`, or a client that failed in a way it
+        // did not mark. Either way its text is the engine's ("Cannot read
+        // properties of null (reading 'map')"), which belongs in a stack trace
+        // and not on an admin screen, so it stays on `message` and the fallback
+        // in `adminErrorMessage` answers instead.
+        const saidSomethingReadable = !transport && !(err instanceof TypeError);
+        return new AdminError({
+            detail: saidSomethingReadable ? asString(err.message) : undefined,
+            transportFailure: transport,
+            message: err.message,
+            cause: err,
+        });
+    }
+
+    // A rejection that is not an `Error` still says something when it carries a
+    // readable `message`. A client rejecting with `{ code, message }` is an
+    // ordinary shape, and an `Error` built in another realm fails `instanceof`
+    // while being exactly that. The status-bearing branch above already reads
+    // both fields; leaving them unread here treated the same information
+    // differently depending on whether a status happened to travel with it.
+    //
+    // What this cannot separate is a cross-realm `TypeError`, whose message is
+    // the engine's rather than the failing side's — `instanceof` is the only
+    // thing that tells those apart, and it is precisely what has already failed
+    // by the time execution reaches here. So the reading is a decision, not a
+    // measurement: a consumer message shown once too often costs a confusing
+    // sentence, one swallowed costs the only explanation there was.
+    const text = asString(err) ?? asString(record?.message);
+    return new AdminError({
+        code: asString(record?.code),
+        detail: text,
+        message: text,
+        cause: err,
+    });
+}
+
+/**
+ * Maps `status` to the key that describes what happened. `undefined` means the
+ * status has no dedicated wording and falls through to the generic template.
+ */
+function statusKey(status: number): keyof SaMessages['errors'] | undefined {
+    if (status === 400 || status === 422) return 'validation';
+    if (status === 401) return 'unauthorized';
+    if (status === 403) return 'forbidden';
+    if (status === 404) return 'notFound';
+    if (status === 409) return 'conflict';
+    if (status === 429) return 'rateLimited';
+    if (status >= 500) return 'server';
+    return undefined;
+}
+
+/**
+ * Turns anything that was caught into text for a user.
+ *
+ * What the failing side said outranks anything this package could guess, so a
+ * `detail` wins whenever there is one. After that come the two facts a seam
+ * declared about a request with no HTTP status — they need opposite sentences
+ * and no number can tell them apart — and only then the status.
+ *
+ * The last line is the honest one. An error with no status, no text and no
+ * declaration is an error nothing knows anything about; "check your connection"
+ * used to be the answer, and it sent an operator after their router for a null
+ * dereference in a page. Whoever knows better says so with
+ * `markTransportFailure` or `markEmptyResponse`.
+ *
+ * Pages do not call this — `useAsyncAction` and the error banner do.
+ */
+export function adminErrorMessage(err: unknown, msgs: SaMessages['errors']): string {
+    const error = toAdminError(err);
+    if (error.detail) return error.detail;
+    if (error.emptyResponse) return msgs.emptyResponse;
+    if (error.transportFailure) return msgs.network;
+    if (error.status > 0) {
+        const key = statusKey(error.status);
+        return key ? msgs[key] : formatMessage(msgs.httpStatus, { status: error.status });
+    }
+    return msgs.unexpected;
+}

package/src/client/admin-resource-client.ts

@@ -7,6 +7,7 @@ import type {
     AuditEntry,
     PromoCodeRecord,
 } from '@saasicat/types';
+import { filterQueryString } from './resources/list-resource.js';
 import type { HttpClient } from './types.js';
 
 export interface AdminResourceClientOptions {
@@ -57,11 +58,11 @@ export function createAdminResourceClient(options: AdminResourceClientOptions) {
             getJson<AdminTenantDetail>(`${tenantsEndpoint}/${encodeURIComponent(slug)}`),
         loadUsers: (filter: AdminUserListFilter) =>
             getJson<AdminUserListRow[]>(
-                `${base}/users${queryString({ q: filter.q, tenant: filter.tenant })}`,
+                `${base}/users${filterQueryString({ q: filter.q, tenant: filter.tenant })}`,
             ),
         loadAudit: (filter: AdminAuditListFilter) =>
             getJson<AuditEntry[]>(
-                `${base}/audit${queryString({
+                `${base}/audit${filterQueryString({
                     actor: filter.actor,
                     action: filter.action,
                     entity: filter.entity,
@@ -72,7 +73,7 @@ export function createAdminResourceClient(options: AdminResourceClientOptions) {
         loadSubscriptions: () => getJson<AdminSubscriptionListRow[]>(`${base}/subscriptions`),
         loadPromos: (filter: AdminPromoListFilter) =>
             getJson<AdminPromoListRow[]>(
-                `${base}/promo-codes${queryString({
+                `${base}/promo-codes${filterQueryString({
                     search: filter.search,
                     status: filter.status,
                 })}`,
@@ -101,12 +102,8 @@ function assertSuccess(status: number, method: string, url: string): void {
     }
 }
 
-function queryString(params: Record<string, string | number | null | undefined>): string {
-    const search = new URLSearchParams();
-    for (const [key, value] of Object.entries(params)) {
-        if (value === undefined || value === null || value === '') continue;
-        search.set(key, String(value));
-    }
-    const value = search.toString();
-    return value ? `?${value}` : '';
-}
+// The query string these endpoints take is `filterQueryString` — the same
+// omit-the-empties rule the paginated lists apply, minus the pagination these
+// controllers do not offer. It used to be written out again here, which is one
+// decision in two places: the copies agreed by coincidence, and either could
+// have started sending `status=null` on its own.

package/src/client/batch-column-fetcher.ts

@@ -46,7 +46,7 @@ export class BatchColumnDriftError extends Error {
         public readonly column: TenantColumnDef,
         reason: string,
     ) {
-        super(`Spalte "${column.key}": ${reason}`);
+        super(`Column "${column.key}": ${reason}`);
         this.name = 'BatchColumnDriftError';
     }
 }
@@ -91,7 +91,7 @@ export class BatchColumnFetcher {
         const res = await this.http(url, { method: 'GET', headers });
         if (res.status !== 200) {
             throw new Error(
-                `Spalte "${column.key}" — Endpoint ${column.endpoint} antwortete HTTP ${res.status}`,
+                `Column "${column.key}" — endpoint ${column.endpoint} responded with HTTP ${res.status}`,
             );
         }
         const body = (await res.json()) as BatchColumnRow;

package/src/client/boot-loader.ts

@@ -12,6 +12,8 @@
 // Spec: admin-api.openapi.yaml.
 
 import type { PublicBootResponse } from '@saasicat/types';
+import { markPlatformError } from './admin-error.js';
+import { requireServerAnswer } from './http-json.js';
 import { defaultHttpClient, type HttpClient } from './types.js';
 
 export interface BootLoaderOptions {
@@ -31,6 +33,9 @@ export class BootLoadError extends Error {
     ) {
         super(message);
         this.name = 'BootLoadError';
+        // Identity, so `toAdminError` can tell this diagnostic from a
+        // consumer error whose message an operator needs to read.
+        markPlatformError(this);
     }
 }
 
@@ -52,8 +57,14 @@ export class BootLoader {
 
     async load(): Promise<PublicBootResponse> {
         const res = await this.http(this.endpoint);
+        requireServerAnswer(
+            res.status,
+            'GET',
+            this.endpoint,
+            (diagnostic) => new BootLoadError(res.status, diagnostic),
+        );
         if (res.status !== 200) {
-            throw new BootLoadError(res.status, `Boot-Endpunkt antwortete HTTP ${res.status}`);
+            throw new BootLoadError(res.status, `Boot endpoint responded with HTTP ${res.status}`);
         }
         return (await res.json()) as PublicBootResponse;
     }