@xemahq/biome-host-internal-api-client 0.3.1 → 0.3.3

package/dist/custom-fetch.d.ts

@@ -1,24 +1,36 @@
 /**
  * Configurable fetch wrapper for Orval-generated clients.
  *
+ * GENERATED by `@xemahq/api-client-generator` — do not edit. Every client in
+ * the fleet ships this file byte-for-byte; a local edit is erased by the next
+ * `pnpm refresh` and, until then, makes this one client speak to the platform
+ * differently from all of its siblings. Change the template instead:
+ * `api-client-generator/src/lib/custom-fetch-template.ts`.
+ *
  * Consumers must call `configureClient()` before using any endpoint function.
  * The baseUrl is prepended to the relative paths generated by Orval.
  *
- * Features:
- *   - Automatic bearer-token injection via `getAuthToken` callback
- *   - Per-request header injection via `getHeaders` callback
- *   - Automatic 401 handling via `onUnauthorized` callback (single retry)
- *   - Exponential-backoff retry for transient failures (429, 502, 503, 504)
- *   - Typed `ClientError` for non-2xx responses
- *   - Per-call header overrides (take precedence over global headers)
- *
- * @example
- *   configureClient({
- *     baseUrl: 'http://governance-api:3400',
- *     getAuthToken: () => identityBootstrapService.getAccessToken(),
- *     getHeaders: () => ({ 'X-Xema-Org-Id': orgId, 'X-Correlation-Id': crypto.randomUUID() }),
- *   });
+ * By default this transport issues exactly ONE request and adds no delay of its
+ * own, so a slow call is a slow server. Retrying is opt-in, and opting in
+ * requires supplying an observer — see `maxRetries` / `onRetry` below.
  */
+/** What {@link ClientConfig.onRetry} is told before each re-attempt. */
+export interface RetryNotice {
+    /** 1-based index of the re-attempt about to be made. */
+    attempt: number;
+    /** The configured budget this re-attempt is spending from. */
+    maxRetries: number;
+    /** The response status that made the previous attempt retryable. */
+    status: number;
+    /** Delay before the re-attempt, in ms — from `Retry-After` when the server sent one. */
+    waitMs: number;
+    /** Whether {@link waitMs} came from the server's `Retry-After` header. */
+    retryAfterHonoured: boolean;
+    /** Absolute URL being re-requested. */
+    url: string;
+    /** HTTP method being re-requested. */
+    method: string;
+}
 export interface ClientConfig {
     /**
      * Static base URL (e.g. 'http://localhost:3140') — no trailing slash.
@@ -35,10 +47,28 @@ export interface ClientConfig {
     getAuthToken?: () => Promise<string>;
     /** Optional callback returning headers to inject on every request. Per-call headers take precedence. */
     getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    /** Optional callback invoked on 401 before a single retry (e.g. force-refresh auth token). */
+    /**
+     * Optional callback invoked on a 401 before ONE re-attempt. Supplying it is
+     * what opts this client into that re-attempt; without it a 401 comes back to
+     * the caller as a `ClientError` like any other 4xx.
+     */
     onUnauthorized?: () => Promise<void>;
-    /** Maximum retry attempts for transient failures (default: 3). Set to 0 to disable retries. */
+    /**
+     * Re-attempts for a retryable status. **Defaults to 0 — no retry.**
+     *
+     * Setting it above 0 REQUIRES `onRetry`; `configureClient` throws otherwise.
+     * See the block above `customFetch` for why the budget is opt-in and why an
+     * observer is mandatory rather than advisory.
+     */
     maxRetries?: number;
+    /**
+     * Called immediately before every re-attempt, with the reason and the delay.
+     *
+     * Mandatory whenever `maxRetries` is above 0. It is the difference between a
+     * retry and a hidden degradation path: without it a caller cannot tell a slow
+     * server from this transport sleeping between attempts.
+     */
+    onRetry?: (notice: RetryNotice) => void;
 }
 export declare class ClientError extends Error {
     readonly status: number;

package/dist/custom-fetch.js

@@ -2,23 +2,18 @@
 /**
  * Configurable fetch wrapper for Orval-generated clients.
  *
+ * GENERATED by `@xemahq/api-client-generator` — do not edit. Every client in
+ * the fleet ships this file byte-for-byte; a local edit is erased by the next
+ * `pnpm refresh` and, until then, makes this one client speak to the platform
+ * differently from all of its siblings. Change the template instead:
+ * `api-client-generator/src/lib/custom-fetch-template.ts`.
+ *
  * Consumers must call `configureClient()` before using any endpoint function.
  * The baseUrl is prepended to the relative paths generated by Orval.
  *
- * Features:
- *   - Automatic bearer-token injection via `getAuthToken` callback
- *   - Per-request header injection via `getHeaders` callback
- *   - Automatic 401 handling via `onUnauthorized` callback (single retry)
- *   - Exponential-backoff retry for transient failures (429, 502, 503, 504)
- *   - Typed `ClientError` for non-2xx responses
- *   - Per-call header overrides (take precedence over global headers)
- *
- * @example
- *   configureClient({
- *     baseUrl: 'http://governance-api:3400',
- *     getAuthToken: () => identityBootstrapService.getAccessToken(),
- *     getHeaders: () => ({ 'X-Xema-Org-Id': orgId, 'X-Correlation-Id': crypto.randomUUID() }),
- *   });
+ * By default this transport issues exactly ONE request and adds no delay of its
+ * own, so a slow call is a slow server. Retrying is opt-in, and opting in
+ * requires supplying an observer — see `maxRetries` / `onRetry` below.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.customFetch = exports.ClientError = void 0;
@@ -39,6 +34,14 @@ class ClientError extends Error {
 exports.ClientError = ClientError;
 let clientConfig = null;
 function configureClient(config) {
+    // Fail at WIRING time, not on the request that happens to be retried. A
+    // client configured to retry without an observer is the exact defect this
+    // transport was rebuilt to remove, so it must not be constructible.
+    if ((config.maxRetries ?? 0) > 0 && !config.onRetry) {
+        throw new Error('configureClient: maxRetries above 0 requires onRetry. A retry nothing ' +
+            'reports is indistinguishable from a slow server, which is how two ' +
+            'silent re-attempts were read as a 3,312ms call.');
+    }
     clientConfig = config;
 }
 function getClientConfig() {
@@ -47,7 +50,49 @@ function getClientConfig() {
     }
     return clientConfig;
 }
-const RETRYABLE_STATUSES = [429, 502, 503, 504];
+/*
+ * RETRYING IS OPT-IN, OBSERVED, AND NARROW. Do not widen any of the three.
+ *
+ * This transport used to retry up to `maxRetries` (defaulting to THREE) over
+ * 429/502/503/504 AND over any thrown network error, backing off from 1000ms,
+ * with no log line anywhere. Three properties were wrong:
+ *
+ *   1. The DEFAULT was on. ~99% of the fleet's client configurations never
+ *      mention `maxRetries`, so two re-attempts could add ~3s to any call with
+ *      nothing to distinguish that from a slow peer. Every caller that DID set
+ *      it set it LOWER — canopy's control plane to 1, "so a hard outage
+ *      surfaces inside the turn's latency budget rather than after three
+ *      backoffs"; two llm-registry callers to 1; a test to 0. Nobody ever
+ *      raised it. A default three separate call sites work around is not a
+ *      default, and `configureOrvalClientResolved` cannot express the field at
+ *      all, so most callers could not have opted out if they had wanted to.
+ *   2. It retried AMBIGUOUS failures. 502 and 504 mean a gateway did not get a
+ *      timely answer from upstream — the upstream may well have APPLIED the
+ *      request. So did a thrown network error mid-flight. Re-sending a POST in
+ *      either case is a duplicate write, and no amount of logging makes that
+ *      safe. Only 429 and 503 state positively that the request was NOT
+ *      processed, so only those are retried; everything else surfaces at once.
+ *   3. Nothing reported it. Now `onRetry` is mandatory whenever the budget is
+ *      above 0, enforced in `configureClient`.
+ *
+ * Also note `baseUrlResolver` is awaited ONCE, above the loop: a re-attempt
+ * returns to the same resolved instance. In a registry-resolved fleet the cure
+ * for an unhealthy peer is re-resolution, which lives above this file — which
+ * is a further reason not to lean on retrying here.
+ *
+ * Retry policy a caller genuinely wants belongs in `@xemahq/managed-fetch`,
+ * which has backoff, a circuit breaker, a token bucket and health reporting,
+ * and reports what it did.
+ *
+ * Enforced fleet-wide by `check-client-transport-envelope`, which compares
+ * every client's transport to this template.
+ */
+/** The only statuses that state the request was NOT processed. See above. */
+const RETRYABLE_STATUSES = [429, 503];
+/** Backoff floor, doubling per attempt up to {@link MAX_BACKOFF_MS}. */
+const BASE_BACKOFF_MS = 1000;
+/** Ceiling on a single backoff, however many attempts have elapsed. */
+const MAX_BACKOFF_MS = 30_000;
 async function buildHeaders(config, callerHeaders) {
     const headers = new Headers(callerHeaders);
     // Global headers from config (caller-provided headers take precedence)
@@ -66,6 +111,29 @@ async function buildHeaders(config, callerHeaders) {
     }
     return headers;
 }
+/*
+ * THE TRANSPORT RETURNS THE BODY UNCHANGED. Do not reintroduce an unwrap here.
+ *
+ * Xema services wrap every 2xx payload in a { data: T } envelope via the global
+ * ResponseEnvelopeInterceptor (platform-common), and the generator emits types
+ * that describe THAT ENVELOPE — every endpoint returns Promise<XDataEnvelope>
+ * or Promise<XPaginatedEnvelope>, never a bare inner T. Consumers read the data
+ * property themselves.
+ *
+ * This template used to peel data, justified by a comment claiming generated
+ * types describe the inner T. That stopped being true when the generator moved
+ * to envelope-typed returns, and the comment outlived the fact — so the peel
+ * then contradicted every type in every package it seeded. Four clients shipped
+ * that way (resource-governance x3, workload-runtime-api): declared
+ * *DataEnvelope, returned the already-peeled inner object, so .data read
+ * undefined at runtime on every non-paginated endpoint. Paginated calls hid it,
+ * because the old peel deliberately preserved an envelope carrying pagination.
+ *
+ * Four MORE shipped it in repositories the gate could not see — license-api and
+ * license-internal-api in xema-operator, plus their host-web mirrors — because
+ * the gate ran in xema-base only. That is why it now runs in every repository
+ * that ships a client, and why this file is generator-owned rather than seeded.
+ */
 const customFetch = async (url, options) => {
     const config = getClientConfig();
     const base = config.baseUrlResolver
@@ -75,51 +143,57 @@ const customFetch = async (url, options) => {
         throw new Error('Client not configured: set baseUrl or baseUrlResolver via configureClient().');
     }
     const fullUrl = `${base}${url}`;
-    const maxRetries = config.maxRetries ?? 3;
+    const maxRetries = config.maxRetries ?? 0;
+    // A caller that supplied its own Authorization header owns that credential.
+    // `buildHeaders` lets it win, so refreshing the CLIENT-WIDE token and
+    // re-sending would replay the identical failing request with the identical
+    // credential: one wasted round trip, plus a global refresh nobody asked for.
+    const callerSuppliedAuth = new Headers(options.headers).has('Authorization');
     const headers = await buildHeaders(config, options.headers);
     const requestInit = { ...options, headers };
-    let delay = 1000;
-    let lastError;
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-        try {
-            const response = await fetch(fullUrl, requestInit);
-            // 401 — invoke onUnauthorized and retry once (outside the transient retry loop)
-            if (response.status === 401 && config.onUnauthorized && attempt === 0) {
-                await config.onUnauthorized();
-                const refreshedHeaders = await buildHeaders(config, options.headers);
-                const retryResponse = await fetch(fullUrl, { ...options, headers: refreshedHeaders });
-                const retryBody = await parseBody(retryResponse);
-                if (retryResponse.status >= 400) {
-                    throw new ClientError(retryResponse.status, fullUrl, retryBody);
-                }
-                return retryBody;
-            }
-            // Non-retryable status — return or throw
-            if (!RETRYABLE_STATUSES.includes(response.status) || attempt >= maxRetries) {
-                const body = await parseBody(response);
-                if (response.status >= 400) {
-                    throw new ClientError(response.status, fullUrl, body);
-                }
-                return body;
+    let delay = BASE_BACKOFF_MS;
+    for (let attempt = 0;; attempt++) {
+        const response = await fetch(fullUrl, requestInit);
+        if (response.status === 401 &&
+            config.onUnauthorized &&
+            !callerSuppliedAuth &&
+            attempt === 0) {
+            await config.onUnauthorized();
+            const refreshedHeaders = await buildHeaders(config, options.headers);
+            const retryResponse = await fetch(fullUrl, {
+                ...options,
+                headers: refreshedHeaders,
+            });
+            const retryBody = await parseBody(retryResponse);
+            if (retryResponse.status >= 400) {
+                throw new ClientError(retryResponse.status, fullUrl, retryBody);
             }
-            // Retryable — wait and retry
-            const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
-            const waitMs = retryAfter ?? addJitter(delay);
-            await sleep(waitMs);
-            delay = Math.min(delay * 2, 30_000);
+            return retryBody;
         }
-        catch (error) {
-            if (error instanceof ClientError)
-                throw error; // Don't retry client errors
-            lastError = error instanceof Error ? error : new Error(String(error));
-            if (attempt >= maxRetries)
-                throw lastError;
-            const waitMs = addJitter(delay);
-            await sleep(waitMs);
-            delay = Math.min(delay * 2, 30_000);
+        if (!RETRYABLE_STATUSES.includes(response.status) ||
+            attempt >= maxRetries) {
+            const body = await parseBody(response);
+            if (response.status >= 400) {
+                throw new ClientError(response.status, fullUrl, body);
+            }
+            return body;
         }
+        const retryAfter = parseRetryAfter(response.headers.get('Retry-After'));
+        const waitMs = retryAfter ?? addJitter(delay);
+        // Non-null: `configureClient` refuses a budget above 0 without an observer,
+        // and this line is unreachable unless `maxRetries` is above 0.
+        config.onRetry({
+            attempt: attempt + 1,
+            maxRetries,
+            status: response.status,
+            waitMs,
+            retryAfterHonoured: retryAfter !== undefined,
+            url: fullUrl,
+            method: options.method ?? 'GET',
+        });
+        await sleep(waitMs);
+        delay = Math.min(delay * 2, MAX_BACKOFF_MS);
     }
-    throw lastError ?? new Error(`All retries exhausted for ${fullUrl}`);
 };
 exports.customFetch = customFetch;
 async function parseBody(response) {
@@ -147,6 +221,6 @@ function addJitter(delay) {
     return delay + (Math.random() * 2 - 1) * delay * 0.25;
 }
 function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+    return new Promise((resolve) => setTimeout(resolve, ms));
 }
 exports.default = exports.customFetch;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { configureClient, getClientConfig, ClientError, customFetch, type ClientConfig } from './custom-fetch';
+export { configureClient, getClientConfig, ClientError, customFetch, type ClientConfig, type RetryNotice } from './custom-fetch';
 export * from './models';
 export * from './endpoints/describe-objects/describe-objects';
 export * from './endpoints/runtime-authority-internal/runtime-authority-internal';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xemahq/biome-host-internal-api-client",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/xema-dev/xema-base.git",
@@ -25,7 +25,7 @@
     "service": "biome-host-api",
     "biome": "biome-host",
     "target": "server",
-    "generator": "@xemahq/api-client-generator@0.5.0",
+    "generator": "@xemahq/api-client-generator@0.12.0",
     "source": "openapi.internal.json"
   },
   "scripts": {