@softure-ai/core 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,23 @@ Newest first. Each version lists what changed for an app that uses `@softure-ai/
 production, the version gets a line `verified in: <app>@<commit>` ([docs/05](../../docs/05-adoption-playbook.md),
 "Definition of done"). Versions before the first one below are described in their GitHub Releases (`core@x.y.z`).
 
+## 0.2.3
+
+- `requestJson` reads response headers (#652), with no breaking change to calls that do not use the new option.
+  - `readHeaders: readonly string[]`: response headers to return, by name (any letter case), an explicit allow-list.
+    With it the value is `{ body, headers }` (each requested name a key, `null` when absent) and a failure that had a
+    response carries `headers`. A name that is not a valid header name throws a `RangeError` before the request.
+  - `retryAfterSeconds: number | null` on every `core.http_rate_limited` and `core.http_unavailable` failure, parsed
+    from `Retry-After` (seconds, or an HTTP date measured against the new `clock` option), 0 to 86 400.
+    `HttpJsonFailure` is now a union narrowed by `error`, and a rate limited or unavailable failure's `status` is a
+    `number`.
+  - `parseLinkHeader(value)` returns the `next`, `prev`, `first` and `last` URLs of a `Link` header.
+  - New types `HttpJsonAnswer`, `HttpJsonResponseHeaders`, `HttpJsonRetryableCode`, `LinkHeaderLinks`,
+    `RequestJsonReadHeadersOptions`.
+  - Migrate: nothing is required. A test that deep-compares a 429 or 5xx failure adds `retryAfterSeconds: null` (or
+    the parsed value). An app that dropped to raw `fetch` for `Retry-After`, a `Link` header or rate-limit headers
+    goes back to `requestJson` with `readHeaders`, and passes `retryAfterSeconds` to `retryJobLater`.
+
 ## 0.2.2
 
 - `requestJson` writes (#635): `method` (`"GET"` by default, `"POST" | "PUT" | "PATCH" | "DELETE"`), `body` sent as

package/README.md

@@ -305,7 +305,7 @@ if (plan.endedAt !== null) throw new PublicError("This plan has ended; pick anot
 `isPublicError` recognises one from another copy of core too (a registry symbol, not `instanceof`).
 `safeError` itself still answers `core.unexpected` for it, since callers switch on its two codes.
 
-**External JSON APIs.** `requestJson({ url, method?, body?, idempotencyKey?, fetch?, headers?, timeoutMs?, schema? })`
+**External JSON APIs.** `requestJson({ url, method?, body?, idempotencyKey?, fetch?, headers?, timeoutMs?, schema?, readHeaders?, clock? })`
 calls a third-party JSON API (a GET by default) and returns `Ok<value>` or an `HttpJsonFailure` (`{ ok: false, error, status }`). It sets the details a hand-written
 helper tends to miss:
 
@@ -351,6 +351,35 @@ throws before anything is sent. `idempotencyKey` is sent as `Idempotency-Key`. A
 (a 204, or a 200 with nothing) is `ok(undefined)`, schema or not, so a write's value is `T | undefined`; a non-empty
 answer still goes through the schema. A GET carries no body, and an empty answer to it stays an unexpected answer.
 
+**Response headers.** A failure with `core.http_rate_limited` (429) or `core.http_unavailable` (5xx) always carries
+`retryAfterSeconds`: the `Retry-After` header as seconds (delay-seconds, or an HTTP date measured against `clock`,
+default `systemClock`, rounded up), between 0 and 86 400, or `null` when the header is missing or malformed. It goes
+straight into `retryJobLater` of `@softure-ai/jobs`. Narrowing on `error` types it; other failures do not carry it.
+
+Any other header is read only when named in `readHeaders` (any letter case; an explicit allow-list, so nothing secret
+leaves by accident). The value then becomes `{ body, headers }`, with each requested name as a key and `null` for a
+header the answer lacks; a failure that had a response carries the same `headers`. Without `readHeaders` the value is
+the body, as before. A name that is not a valid header name throws a `RangeError` before anything is sent.
+`parseLinkHeader(value)` reads a `Link` header (RFC 8288) into `{ next?, prev?, first?, last? }`, the URLs as
+written (`previous` counts as `prev`; the first link of a relation wins; `null` or garbage gives `{}`):
+
+```ts
+import { parseLinkHeader, requestJson } from "@softure-ai/core";
+
+const page = await requestJson({
+  url,
+  headers: { Authorization: `Bearer ${env.REPORTS_API_KEY}` },
+  schema: z.array(rowSchema),
+  readHeaders: ["link", "x-ratelimit-remaining"],
+});
+if (!page.ok) {
+  if (page.error === "core.http_rate_limited") return retryJobLater("app.reports_busy", page.retryAfterSeconds ?? 60);
+  return page;
+}
+const { next } = parseLinkHeader(page.value.headers.link);
+// page.value.body: the rows; next: the URL of the next page, or undefined on the last one
+```
+
 ```ts
 const saved = await requestJson({
   url: `https://api.example.com/tasks/${task.id}`,

package/dist/http-json.d.ts

@@ -1,9 +1,28 @@
 import type { z } from "zod";
+import { type Clock } from "./clock.js";
 import { type Err, type Ok } from "./result.js";
 export type HttpJsonFailureCode = "core.http_unreachable" | "core.http_refused" | "core.http_rate_limited" | "core.http_unavailable" | "core.http_conflict" | "core.http_unexpected_answer";
-/** A failed `requestJson`: the code and the HTTP status (`null` when no response arrived). Nothing else. */
-export type HttpJsonFailure = Err<HttpJsonFailureCode> & {
+/** The failure codes whose answer may say when to try again (`Retry-After`). */
+export type HttpJsonRetryableCode = "core.http_rate_limited" | "core.http_unavailable";
+/** The headers named in `readHeaders`, keyed as the caller wrote them; `null` when the answer does not carry one. */
+export type HttpJsonResponseHeaders<H extends string = string> = Readonly<Record<H, string | null>>;
+/**
+ * A failed `requestJson`: the code and the HTTP status (`null` when no response arrived). A rate limited or
+ * unavailable answer adds `retryAfterSeconds`, and a response read with `readHeaders` adds `headers`. Nothing else.
+ */
+export type HttpJsonFailure = (Err<Exclude<HttpJsonFailureCode, HttpJsonRetryableCode>> & {
     readonly status: number | null;
+    readonly headers?: HttpJsonResponseHeaders;
+}) | (Err<HttpJsonRetryableCode> & {
+    readonly status: number;
+    /** Parsed from `Retry-After` (seconds or an HTTP date), 0 to 86 400; `null` when missing or malformed. */
+    readonly retryAfterSeconds: number | null;
+    readonly headers?: HttpJsonResponseHeaders;
+});
+/** The value of a call made with `readHeaders`: the body as without it, and the requested headers. */
+export type HttpJsonAnswer<T, H extends string> = {
+    readonly body: T;
+    readonly headers: HttpJsonResponseHeaders<H>;
 };
 export type HttpJsonWriteMethod = "POST" | "PUT" | "PATCH" | "DELETE";
 export type HttpJsonMethod = "GET" | HttpJsonWriteMethod;
@@ -15,6 +34,16 @@ export interface RequestJsonOptions {
     readonly headers?: HeadersInit;
     /** Milliseconds before the request (body included) gives up. Defaults to 10 000. */
     readonly timeoutMs?: number;
+    /** Measures a `Retry-After` HTTP date. Defaults to `systemClock`. */
+    readonly clock?: Clock;
+}
+/** Response headers to return, by name (any letter case). Only these are read. */
+export interface RequestJsonReadHeadersOptions<H extends string> {
+    readonly readHeaders: readonly H[];
+}
+/** The calls without `readHeaders`, whose value is the body itself. */
+interface WithoutReadHeaders {
+    readonly readHeaders?: undefined;
 }
 export interface RequestJsonSchemaOptions<S extends z.ZodType> extends RequestJsonOptions {
     readonly schema: S;
@@ -38,13 +67,31 @@ export interface RequestJsonWriteOptions extends RequestJsonOptions {
  * for the caller to narrow; with one it is the schema's output. A write answered with an empty body (a 204) is
  * `ok(undefined)`, schema or not. 3xx, 401 and 403 are refused, 409 and 412 a conflict, 429 rate limited, 5xx
  * unavailable, and any other non-2xx status or a body that is not JSON or fails the schema an unexpected answer.
+ * With `readHeaders` the value is `{ body, headers }`, and a failure that had a response carries `headers` too.
+ */
+export declare function requestJson<S extends z.ZodType, const H extends string>(options: RequestJsonSchemaOptions<S> & RequestJsonReadOptions & RequestJsonReadHeadersOptions<H>): Promise<Ok<HttpJsonAnswer<z.output<S>, H>> | HttpJsonFailure>;
+export declare function requestJson<S extends z.ZodType, const H extends string>(options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions & RequestJsonReadHeadersOptions<H>): Promise<Ok<HttpJsonAnswer<z.output<S> | undefined, H>> | HttpJsonFailure>;
+export declare function requestJson<const H extends string>(options: (RequestJsonReadOptions | RequestJsonWriteOptions) & RequestJsonReadHeadersOptions<H>): Promise<Ok<HttpJsonAnswer<unknown, H>> | HttpJsonFailure>;
+export declare function requestJson<S extends z.ZodType>(options: RequestJsonSchemaOptions<S> & RequestJsonReadOptions & WithoutReadHeaders): Promise<Ok<z.output<S>> | HttpJsonFailure>;
+export declare function requestJson<S extends z.ZodType>(options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions & WithoutReadHeaders): Promise<Ok<z.output<S> | undefined> | HttpJsonFailure>;
+export declare function requestJson(options: (RequestJsonReadOptions | RequestJsonWriteOptions) & WithoutReadHeaders): Promise<Ok<unknown> | HttpJsonFailure>;
+/** The URLs of the pagination relations in a `Link` header (RFC 8288), as written; missing ones are left out. */
+export interface LinkHeaderLinks {
+    readonly next?: string;
+    readonly prev?: string;
+    readonly first?: string;
+    readonly last?: string;
+}
+/**
+ * Read `next`, `prev` (or `previous`), `first` and `last` from a `Link` header such as
+ * `<https://api.example.com/items?page=2>; rel="next"`. The first link of a relation wins; `null`, an empty value or
+ * one that cannot be read gives `{}`.
  */
-export declare function requestJson<S extends z.ZodType>(options: RequestJsonSchemaOptions<S> & RequestJsonReadOptions): Promise<Ok<z.output<S>> | HttpJsonFailure>;
-export declare function requestJson<S extends z.ZodType>(options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions): Promise<Ok<z.output<S> | undefined> | HttpJsonFailure>;
-export declare function requestJson(options: RequestJsonReadOptions | RequestJsonWriteOptions): Promise<Ok<unknown> | HttpJsonFailure>;
+export declare function parseLinkHeader(value: string | null | undefined): LinkHeaderLinks;
 /**
  * The query part of a URL (without `?`) from a flat record, in insertion order. `null` and `undefined` are left
  * out, so optional parameters can be passed as they are.
  */
 export declare function toQueryString(params: Readonly<Record<string, string | number | boolean | null | undefined>>): string;
+export {};
 //# sourceMappingURL=http-json.d.ts.map

package/dist/http-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http-json.d.ts","sourceRoot":"","sources":["../src/http-json.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,EAAW,KAAK,GAAG,EAAE,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAEzD,MAAM,MAAM,mBAAmB,GAC3B,uBAAuB,GACvB,mBAAmB,GACnB,wBAAwB,GACxB,uBAAuB,GACvB,oBAAoB,GACpB,6BAA6B,CAAC;AAElC,4GAA4G;AAC5G,MAAM,MAAM,eAAe,GAAG,GAAG,CAAC,mBAAmB,CAAC,GAAG;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAE5F,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;AACtE,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,mBAAmB,CAAC;AAEzD,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE1F,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IAC3B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,CAAE,SAAQ,kBAAkB;IACvF,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;CACpB;AAED,wEAAwE;AACxE,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC;CACjC;AAED,wFAAwF;AACxF,MAAM,WAAW,uBAAwB,SAAQ,kBAAkB;IACjE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,yGAAyG;IACzG,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,sFAAsF;IACtF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAID;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC7C,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,sBAAsB,GAC5D,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,eAAe,CAAC,CAAC;AAC9C,wBAAgB,WAAW,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC7C,OAAO,EAAE,wBAAwB,CAAC,CAAC,CAAC,GAAG,uBAAuB,GAC7D,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,GAAG,eAAe,CAAC,CAAC;AAC1D,wBAAgB,WAAW,CACzB,OAAO,EAAE,sBAAsB,GAAG,uBAAuB,GACxD,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,eAAe,CAAC,CAAC;AAsE1C;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,GAAG,MAAM,CAQpH"}
+{"version":3,"file":"http-json.d.ts","sourceRoot":"","sources":["../src/http-json.ts"],"names":[],"mappings":"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"}

package/dist/http-json.js

@@ -1,6 +1,12 @@
+import { systemClock } from "./clock.js";
 import { err, ok } from "./result.js";
 const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_RETRY_AFTER_SECONDS = 86_400;
+// An RFC 9110 token: what a header name may be made of.
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 export async function requestJson(options) {
+    // Before anything is sent: a write must not go out when its answer cannot be read.
+    assertHeaderNames(options.readHeaders);
     const fetchFunction = options.fetch ?? globalThis.fetch;
     const method = options.method ?? "GET";
     const isWrite = method !== "GET";
@@ -31,11 +37,14 @@ export async function requestJson(options) {
         // Network error or timeout. The error's text can quote the URL, so it is dropped on purpose.
         return httpFailure("core.http_unreachable", null);
     }
-    const statusFailure = getStatusFailure(response);
-    if (statusFailure !== null) {
+    const headers = options.readHeaders === undefined ? undefined : readResponseHeaders(response, options.readHeaders);
+    const fail = (code) => withHeaders(responseFailure(code, response, options.clock ?? systemClock), headers);
+    const succeed = (body) => ok(headers === undefined ? body : { body, headers });
+    const statusFailureCode = getStatusFailureCode(response);
+    if (statusFailureCode !== null) {
         // Release the connection; a body that cannot be cancelled changes nothing for the caller.
         await response.body?.cancel().catch(() => undefined);
-        return statusFailure;
+        return fail(statusFailureCode);
     }
     let text;
     try {
@@ -43,25 +52,69 @@ export async function requestJson(options) {
     }
     catch {
         // The body broke off, usually the timeout firing mid-body.
-        return httpFailure("core.http_unreachable", response.status);
+        return fail("core.http_unreachable");
     }
     if (isWrite && text.trim() === "") {
         // A 204, or a write that answers 200 with nothing: the write succeeded and there is nothing to read.
-        return ok(undefined);
+        return succeed(undefined);
     }
     let answer;
     try {
         answer = JSON.parse(text);
     }
     catch {
-        return httpFailure("core.http_unexpected_answer", response.status);
+        return fail("core.http_unexpected_answer");
     }
     if (options.schema === undefined) {
-        return ok(answer);
+        return succeed(answer);
     }
     // The schema's issues can quote the body's values, so only the code leaves.
     const parsed = options.schema.safeParse(answer);
-    return parsed.success ? ok(parsed.data) : httpFailure("core.http_unexpected_answer", response.status);
+    return parsed.success ? succeed(parsed.data) : fail("core.http_unexpected_answer");
+}
+const REL_PATTERN = /(?:^|;)\s*rel\s*=\s*(?:"([^"]*)"|([^\s;,"]+))/i;
+const LINK_RELATIONS = {
+    next: "next",
+    prev: "prev",
+    previous: "prev",
+    first: "first",
+    last: "last",
+};
+/**
+ * Read `next`, `prev` (or `previous`), `first` and `last` from a `Link` header such as
+ * `<https://api.example.com/items?page=2>; rel="next"`. The first link of a relation wins; `null`, an empty value or
+ * one that cannot be read gives `{}`.
+ */
+export function parseLinkHeader(value) {
+    const links = {};
+    if (value === null || value === undefined) {
+        return links;
+    }
+    // One link: the URL in angle brackets and its parameters up to the next `<`. Splitting by commas would break a URL
+    // that contains one, and a regular expression would rescan the rest of a hostile value from every `<`.
+    let position = 0;
+    while (position < value.length) {
+        const open = value.indexOf("<", position);
+        const close = open === -1 ? -1 : value.indexOf(">", open + 1);
+        if (close === -1) {
+            break;
+        }
+        const nextOpen = value.indexOf("<", close + 1);
+        position = nextOpen === -1 ? value.length : nextOpen;
+        const url = value.slice(open + 1, close).trim();
+        const rel = REL_PATTERN.exec(value.slice(close + 1, position));
+        const relationTypes = rel?.[1] ?? rel?.[2];
+        if (url === "" || relationTypes === undefined) {
+            continue;
+        }
+        for (const relationType of relationTypes.trim().toLowerCase().split(/\s+/)) {
+            const relation = LINK_RELATIONS[relationType];
+            if (relation !== undefined && links[relation] === undefined) {
+                links[relation] = url;
+            }
+        }
+    }
+    return links;
 }
 /**
  * The query part of a URL (without `?`) from a flat record, in insertion order. `null` and `undefined` are left
@@ -76,26 +129,67 @@ export function toQueryString(params) {
     }
     return search.toString();
 }
-function getStatusFailure(response) {
+function getStatusFailureCode(response) {
     const { status } = response;
     if (response.type === "opaqueredirect" || (status >= 300 && status < 400) || status === 401 || status === 403) {
-        return httpFailure("core.http_refused", status);
+        return "core.http_refused";
     }
     if (status === 409 || status === 412) {
-        return httpFailure("core.http_conflict", status);
+        return "core.http_conflict";
     }
     if (status === 429) {
-        return httpFailure("core.http_rate_limited", status);
+        return "core.http_rate_limited";
     }
     if (status >= 500) {
-        return httpFailure("core.http_unavailable", status);
+        return "core.http_unavailable";
     }
     if (status < 200 || status >= 300) {
-        return httpFailure("core.http_unexpected_answer", status);
+        return "core.http_unexpected_answer";
     }
     return null;
 }
 function httpFailure(code, status) {
     return { ...err(code), status };
 }
+function responseFailure(code, response, clock) {
+    if (code === "core.http_rate_limited" || code === "core.http_unavailable") {
+        const retryAfterSeconds = getRetryAfterSeconds(response.headers.get("retry-after"), clock.now());
+        return { ...err(code), status: response.status, retryAfterSeconds };
+    }
+    return httpFailure(code, response.status);
+}
+function withHeaders(failure, headers) {
+    return headers === undefined ? failure : { ...failure, headers };
+}
+function assertHeaderNames(names) {
+    for (const name of names ?? []) {
+        if (!HEADER_NAME_PATTERN.test(name)) {
+            throw new RangeError(`requestJson: readHeaders holds an invalid header name ${JSON.stringify(name)}`);
+        }
+    }
+}
+function readResponseHeaders(response, names) {
+    return Object.fromEntries(names.map((name) => [name, response.headers.get(name)]));
+}
+/**
+ * Seconds to wait from a `Retry-After` value (RFC 9110): delay-seconds, or an HTTP date measured against `now` and
+ * rounded up. A date in the past is 0, anything above a day is a day, and a malformed value is `null`.
+ */
+function getRetryAfterSeconds(value, now) {
+    const trimmed = value?.trim() ?? "";
+    if (/^\d+$/.test(trimmed)) {
+        return Math.min(Number(trimmed), MAX_RETRY_AFTER_SECONDS);
+    }
+    // Every HTTP date names its day and month; without a letter the value is no date (and `Date.parse` guesses).
+    if (!/^[A-Za-z]/.test(trimmed)) {
+        return null;
+    }
+    // HTTP dates are GMT; the obsolete asctime form says so nowhere, and `Date.parse` would read it as local time.
+    const at = Date.parse(/(GMT|UTC)$/i.test(trimmed) ? trimmed : `${trimmed} GMT`);
+    if (Number.isNaN(at)) {
+        return null;
+    }
+    const seconds = Math.ceil((at - now.getTime()) / 1000);
+    return Math.min(Math.max(seconds, 0), MAX_RETRY_AFTER_SECONDS);
+}
 //# sourceMappingURL=http-json.js.map

package/dist/http-json.js.map

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

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { calendarPeriodSchema, countPeriodDays, doPeriodsOverlap, isDayInPeriod,
 export { getLocalDay, isLocalDateTime, localDateTimeSchema, type LocalDateTime } from "./local-date-time.js";
 export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
 export { DEFAULT_DURATION_MESSAGES, formatCalendarDay, formatCalendarMonth, formatDuration, formatMoney, formatPercent, isCalendarMonth, type CalendarDayStyle, type CalendarMonthStyle, type DurationMessages, type FormatDurationOptions, type FormatMoneyOptions, type FormatPercentOptions, } from "./format.js";
-export { requestJson, toQueryString, type FetchFunction, type HttpJsonFailure, type HttpJsonFailureCode, type HttpJsonMethod, type HttpJsonWriteMethod, type RequestJsonOptions, type RequestJsonReadOptions, type RequestJsonSchemaOptions, type RequestJsonWriteOptions, } from "./http-json.js";
+export { parseLinkHeader, requestJson, toQueryString, type FetchFunction, type HttpJsonAnswer, type HttpJsonFailure, type HttpJsonFailureCode, type HttpJsonMethod, type HttpJsonResponseHeaders, type HttpJsonRetryableCode, type HttpJsonWriteMethod, type LinkHeaderLinks, type RequestJsonOptions, type RequestJsonReadHeadersOptions, type RequestJsonReadOptions, type RequestJsonSchemaOptions, type RequestJsonWriteOptions, } from "./http-json.js";
 export { memoizeByContent, type MemoizeByContentOptions, type MemoizedFunction } from "./memoize.js";
 export { createTestClock, systemClock, type Clock, type TestClock } from "./clock.js";
 export { formatMessage, getMessage, DEFAULT_LOCALE, isLocale, mergeMessages, pickLocalizedText, selectMessages, selectPlural, type DeepPartial, type Dictionaries, type Locale, type LocalizedText, type MessageOverrides, type MessageTree, type PluralForms, } from "./i18n.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,KAAK,UAAU,GAChB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,KAAK,cAAc,GACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC7G,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,WAAW,EACX,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,6BAA6B,EAClC,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,KAAK,uBAAuB,EAAE,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,MAAM,EACX,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,GAAG,EAAE,KAAK,SAAS,EAAE,KAAK,EAAE,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,EACzB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,0BAA0B,EAC/B,KAAK,cAAc,EACnB,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,EACZ,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,KAAK,eAAe,EAAE,KAAK,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -5,7 +5,7 @@ export { calendarPeriodSchema, countPeriodDays, doPeriodsOverlap, isDayInPeriod,
 export { getLocalDay, isLocalDateTime, localDateTimeSchema } from "./local-date-time.js";
 export { CURRENCY_MINOR_UNIT_DIGITS } from "./currency-digits.js";
 export { DEFAULT_DURATION_MESSAGES, formatCalendarDay, formatCalendarMonth, formatDuration, formatMoney, formatPercent, isCalendarMonth, } from "./format.js";
-export { requestJson, toQueryString, } from "./http-json.js";
+export { parseLinkHeader, requestJson, toQueryString, } from "./http-json.js";
 export { memoizeByContent } from "./memoize.js";
 export { createTestClock, systemClock } from "./clock.js";
 export { formatMessage, getMessage, DEFAULT_LOCALE, isLocale, mergeMessages, pickLocalizedText, selectMessages, selectPlural, } from "./i18n.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mGAAmG;AACnG,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,GAEnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAC;AAC7G,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAOhB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,WAAW,EACX,aAAa,GAUd,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAuD,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,WAAW,EAA8B,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,GAQb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAkD,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,GAQ1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,GAUb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAyC,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAmC,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,mGAAmG;AACnG,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,aAAa,EACb,kBAAkB,GAEnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,aAAa,GAEd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,mBAAmB,EAAsB,MAAM,sBAAsB,CAAC;AAC7G,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EACL,yBAAyB,EACzB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,aAAa,EACb,eAAe,GAOhB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,eAAe,EACf,WAAW,EACX,aAAa,GAed,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAuD,MAAM,cAAc,CAAC;AACrG,OAAO,EAAE,eAAe,EAAE,WAAW,EAA8B,MAAM,YAAY,CAAC;AACtF,OAAO,EACL,aAAa,EACb,UAAU,EACV,cAAc,EACd,QAAQ,EACR,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,GAQb,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAqB,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,GAAG,EAAE,EAAE,EAAkD,MAAM,aAAa,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAsB,MAAM,iBAAiB,CAAC;AAC7H,OAAO,EACL,mBAAmB,EACnB,SAAS,EACT,yBAAyB,GAQ1B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,YAAY,EACZ,oBAAoB,EACpB,YAAY,GAUb,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,iBAAiB,EACjB,gBAAgB,GAIjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAuC,MAAM,gBAAgB,CAAC;AACvG,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAyC,MAAM,eAAe,CAAC;AACpG,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAmC,MAAM,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softure-ai/core",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "The SOFTURE AI module contract: app config, module definitions, Result, Clock and messages.",
   "license": "MIT",
   "type": "module",

package/src/http-json.ts

@@ -1,8 +1,10 @@
 // A JSON call to a third-party API (a GET, or a write with a JSON body), with the details every app's own copy has to
 // get right: a timeout, no redirect followed (a key in a header or the URL never reaches another host), and every
 // failure returned as a code. A caught error's message is never read, since it can quote the URL and some APIs put
-// the key there. The body stays `unknown` unless a zod schema narrows it.
+// the key there. The body stays `unknown` unless a zod schema narrows it. Response headers are read only by name from
+// the caller's allow-list, so nothing secret is surfaced by accident.
 import type { z } from "zod";
+import { systemClock, type Clock } from "./clock.js";
 import { err, ok, type Err, type Ok } from "./result.js";
 
 export type HttpJsonFailureCode =
@@ -13,8 +15,30 @@ export type HttpJsonFailureCode =
   | "core.http_conflict"
   | "core.http_unexpected_answer";
 
-/** A failed `requestJson`: the code and the HTTP status (`null` when no response arrived). Nothing else. */
-export type HttpJsonFailure = Err<HttpJsonFailureCode> & { readonly status: number | null };
+/** The failure codes whose answer may say when to try again (`Retry-After`). */
+export type HttpJsonRetryableCode = "core.http_rate_limited" | "core.http_unavailable";
+
+/** The headers named in `readHeaders`, keyed as the caller wrote them; `null` when the answer does not carry one. */
+export type HttpJsonResponseHeaders<H extends string = string> = Readonly<Record<H, string | null>>;
+
+/**
+ * A failed `requestJson`: the code and the HTTP status (`null` when no response arrived). A rate limited or
+ * unavailable answer adds `retryAfterSeconds`, and a response read with `readHeaders` adds `headers`. Nothing else.
+ */
+export type HttpJsonFailure =
+  | (Err<Exclude<HttpJsonFailureCode, HttpJsonRetryableCode>> & {
+      readonly status: number | null;
+      readonly headers?: HttpJsonResponseHeaders;
+    })
+  | (Err<HttpJsonRetryableCode> & {
+      readonly status: number;
+      /** Parsed from `Retry-After` (seconds or an HTTP date), 0 to 86 400; `null` when missing or malformed. */
+      readonly retryAfterSeconds: number | null;
+      readonly headers?: HttpJsonResponseHeaders;
+    });
+
+/** The value of a call made with `readHeaders`: the body as without it, and the requested headers. */
+export type HttpJsonAnswer<T, H extends string> = { readonly body: T; readonly headers: HttpJsonResponseHeaders<H> };
 
 export type HttpJsonWriteMethod = "POST" | "PUT" | "PATCH" | "DELETE";
 export type HttpJsonMethod = "GET" | HttpJsonWriteMethod;
@@ -28,6 +52,18 @@ export interface RequestJsonOptions {
   readonly headers?: HeadersInit;
   /** Milliseconds before the request (body included) gives up. Defaults to 10 000. */
   readonly timeoutMs?: number;
+  /** Measures a `Retry-After` HTTP date. Defaults to `systemClock`. */
+  readonly clock?: Clock;
+}
+
+/** Response headers to return, by name (any letter case). Only these are read. */
+export interface RequestJsonReadHeadersOptions<H extends string> {
+  readonly readHeaders: readonly H[];
+}
+
+/** The calls without `readHeaders`, whose value is the body itself. */
+interface WithoutReadHeaders {
+  readonly readHeaders?: undefined;
 }
 
 export interface RequestJsonSchemaOptions<S extends z.ZodType> extends RequestJsonOptions {
@@ -51,25 +87,43 @@ export interface RequestJsonWriteOptions extends RequestJsonOptions {
 }
 
 const DEFAULT_TIMEOUT_MS = 10_000;
+const MAX_RETRY_AFTER_SECONDS = 86_400;
+// An RFC 9110 token: what a header name may be made of.
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 
 /**
  * Call `url` (a GET unless `method` says otherwise) and read its JSON body. Without a schema the value is `unknown`,
  * for the caller to narrow; with one it is the schema's output. A write answered with an empty body (a 204) is
  * `ok(undefined)`, schema or not. 3xx, 401 and 403 are refused, 409 and 412 a conflict, 429 rate limited, 5xx
  * unavailable, and any other non-2xx status or a body that is not JSON or fails the schema an unexpected answer.
+ * With `readHeaders` the value is `{ body, headers }`, and a failure that had a response carries `headers` too.
  */
+export function requestJson<S extends z.ZodType, const H extends string>(
+  options: RequestJsonSchemaOptions<S> & RequestJsonReadOptions & RequestJsonReadHeadersOptions<H>,
+): Promise<Ok<HttpJsonAnswer<z.output<S>, H>> | HttpJsonFailure>;
+export function requestJson<S extends z.ZodType, const H extends string>(
+  options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions & RequestJsonReadHeadersOptions<H>,
+): Promise<Ok<HttpJsonAnswer<z.output<S> | undefined, H>> | HttpJsonFailure>;
+export function requestJson<const H extends string>(
+  options: (RequestJsonReadOptions | RequestJsonWriteOptions) & RequestJsonReadHeadersOptions<H>,
+): Promise<Ok<HttpJsonAnswer<unknown, H>> | HttpJsonFailure>;
 export function requestJson<S extends z.ZodType>(
-  options: RequestJsonSchemaOptions<S> & RequestJsonReadOptions,
+  options: RequestJsonSchemaOptions<S> & RequestJsonReadOptions & WithoutReadHeaders,
 ): Promise<Ok<z.output<S>> | HttpJsonFailure>;
 export function requestJson<S extends z.ZodType>(
-  options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions,
+  options: RequestJsonSchemaOptions<S> & RequestJsonWriteOptions & WithoutReadHeaders,
 ): Promise<Ok<z.output<S> | undefined> | HttpJsonFailure>;
 export function requestJson(
-  options: RequestJsonReadOptions | RequestJsonWriteOptions,
+  options: (RequestJsonReadOptions | RequestJsonWriteOptions) & WithoutReadHeaders,
 ): Promise<Ok<unknown> | HttpJsonFailure>;
 export async function requestJson(
-  options: (RequestJsonReadOptions | RequestJsonWriteOptions) & { readonly schema?: z.ZodType },
+  options: (RequestJsonReadOptions | RequestJsonWriteOptions) & {
+    readonly schema?: z.ZodType;
+    readonly readHeaders?: readonly string[];
+  },
 ): Promise<Ok<unknown> | HttpJsonFailure> {
+  // Before anything is sent: a write must not go out when its answer cannot be read.
+  assertHeaderNames(options.readHeaders);
   const fetchFunction = options.fetch ?? globalThis.fetch;
   const method = options.method ?? "GET";
   const isWrite = method !== "GET";
@@ -101,11 +155,16 @@ export async function requestJson(
     return httpFailure("core.http_unreachable", null);
   }
 
-  const statusFailure = getStatusFailure(response);
-  if (statusFailure !== null) {
+  const headers = options.readHeaders === undefined ? undefined : readResponseHeaders(response, options.readHeaders);
+  const fail = (code: HttpJsonFailureCode): HttpJsonFailure =>
+    withHeaders(responseFailure(code, response, options.clock ?? systemClock), headers);
+  const succeed = (body: unknown): Ok<unknown> => ok(headers === undefined ? body : { body, headers });
+
+  const statusFailureCode = getStatusFailureCode(response);
+  if (statusFailureCode !== null) {
     // Release the connection; a body that cannot be cancelled changes nothing for the caller.
     await response.body?.cancel().catch(() => undefined);
-    return statusFailure;
+    return fail(statusFailureCode);
   }
 
   let text: string;
@@ -113,27 +172,83 @@ export async function requestJson(
     text = await response.text();
   } catch {
     // The body broke off, usually the timeout firing mid-body.
-    return httpFailure("core.http_unreachable", response.status);
+    return fail("core.http_unreachable");
   }
 
   if (isWrite && text.trim() === "") {
     // A 204, or a write that answers 200 with nothing: the write succeeded and there is nothing to read.
-    return ok(undefined);
+    return succeed(undefined);
   }
 
   let answer: unknown;
   try {
     answer = JSON.parse(text);
   } catch {
-    return httpFailure("core.http_unexpected_answer", response.status);
+    return fail("core.http_unexpected_answer");
   }
 
   if (options.schema === undefined) {
-    return ok(answer);
+    return succeed(answer);
   }
   // The schema's issues can quote the body's values, so only the code leaves.
   const parsed = options.schema.safeParse(answer);
-  return parsed.success ? ok(parsed.data) : httpFailure("core.http_unexpected_answer", response.status);
+  return parsed.success ? succeed(parsed.data) : fail("core.http_unexpected_answer");
+}
+
+/** The URLs of the pagination relations in a `Link` header (RFC 8288), as written; missing ones are left out. */
+export interface LinkHeaderLinks {
+  readonly next?: string;
+  readonly prev?: string;
+  readonly first?: string;
+  readonly last?: string;
+}
+
+type LinkRelation = keyof LinkHeaderLinks;
+
+const REL_PATTERN = /(?:^|;)\s*rel\s*=\s*(?:"([^"]*)"|([^\s;,"]+))/i;
+const LINK_RELATIONS: Readonly<Record<string, LinkRelation>> = {
+  next: "next",
+  prev: "prev",
+  previous: "prev",
+  first: "first",
+  last: "last",
+};
+
+/**
+ * Read `next`, `prev` (or `previous`), `first` and `last` from a `Link` header such as
+ * `<https://api.example.com/items?page=2>; rel="next"`. The first link of a relation wins; `null`, an empty value or
+ * one that cannot be read gives `{}`.
+ */
+export function parseLinkHeader(value: string | null | undefined): LinkHeaderLinks {
+  const links: Partial<Record<LinkRelation, string>> = {};
+  if (value === null || value === undefined) {
+    return links;
+  }
+  // One link: the URL in angle brackets and its parameters up to the next `<`. Splitting by commas would break a URL
+  // that contains one, and a regular expression would rescan the rest of a hostile value from every `<`.
+  let position = 0;
+  while (position < value.length) {
+    const open = value.indexOf("<", position);
+    const close = open === -1 ? -1 : value.indexOf(">", open + 1);
+    if (close === -1) {
+      break;
+    }
+    const nextOpen = value.indexOf("<", close + 1);
+    position = nextOpen === -1 ? value.length : nextOpen;
+    const url = value.slice(open + 1, close).trim();
+    const rel = REL_PATTERN.exec(value.slice(close + 1, position));
+    const relationTypes = rel?.[1] ?? rel?.[2];
+    if (url === "" || relationTypes === undefined) {
+      continue;
+    }
+    for (const relationType of relationTypes.trim().toLowerCase().split(/\s+/)) {
+      const relation = LINK_RELATIONS[relationType];
+      if (relation !== undefined && links[relation] === undefined) {
+        links[relation] = url;
+      }
+    }
+  }
+  return links;
 }
 
 /**
@@ -150,26 +265,72 @@ export function toQueryString(params: Readonly<Record<string, string | number |
   return search.toString();
 }
 
-function getStatusFailure(response: Response): HttpJsonFailure | null {
+function getStatusFailureCode(response: Response): HttpJsonFailureCode | null {
   const { status } = response;
   if (response.type === "opaqueredirect" || (status >= 300 && status < 400) || status === 401 || status === 403) {
-    return httpFailure("core.http_refused", status);
+    return "core.http_refused";
   }
   if (status === 409 || status === 412) {
-    return httpFailure("core.http_conflict", status);
+    return "core.http_conflict";
   }
   if (status === 429) {
-    return httpFailure("core.http_rate_limited", status);
+    return "core.http_rate_limited";
   }
   if (status >= 500) {
-    return httpFailure("core.http_unavailable", status);
+    return "core.http_unavailable";
   }
   if (status < 200 || status >= 300) {
-    return httpFailure("core.http_unexpected_answer", status);
+    return "core.http_unexpected_answer";
   }
   return null;
 }
 
-function httpFailure(code: HttpJsonFailureCode, status: number | null): HttpJsonFailure {
+function httpFailure(code: Exclude<HttpJsonFailureCode, HttpJsonRetryableCode>, status: number | null): HttpJsonFailure {
   return { ...err(code), status };
 }
+
+function responseFailure(code: HttpJsonFailureCode, response: Response, clock: Clock): HttpJsonFailure {
+  if (code === "core.http_rate_limited" || code === "core.http_unavailable") {
+    const retryAfterSeconds = getRetryAfterSeconds(response.headers.get("retry-after"), clock.now());
+    return { ...err(code), status: response.status, retryAfterSeconds };
+  }
+  return httpFailure(code, response.status);
+}
+
+function withHeaders(failure: HttpJsonFailure, headers: HttpJsonResponseHeaders | undefined): HttpJsonFailure {
+  return headers === undefined ? failure : { ...failure, headers };
+}
+
+function assertHeaderNames(names: readonly string[] | undefined): void {
+  for (const name of names ?? []) {
+    if (!HEADER_NAME_PATTERN.test(name)) {
+      throw new RangeError(`requestJson: readHeaders holds an invalid header name ${JSON.stringify(name)}`);
+    }
+  }
+}
+
+function readResponseHeaders(response: Response, names: readonly string[]): HttpJsonResponseHeaders {
+  return Object.fromEntries(names.map((name) => [name, response.headers.get(name)]));
+}
+
+/**
+ * Seconds to wait from a `Retry-After` value (RFC 9110): delay-seconds, or an HTTP date measured against `now` and
+ * rounded up. A date in the past is 0, anything above a day is a day, and a malformed value is `null`.
+ */
+function getRetryAfterSeconds(value: string | null, now: Date): number | null {
+  const trimmed = value?.trim() ?? "";
+  if (/^\d+$/.test(trimmed)) {
+    return Math.min(Number(trimmed), MAX_RETRY_AFTER_SECONDS);
+  }
+  // Every HTTP date names its day and month; without a letter the value is no date (and `Date.parse` guesses).
+  if (!/^[A-Za-z]/.test(trimmed)) {
+    return null;
+  }
+  // HTTP dates are GMT; the obsolete asctime form says so nowhere, and `Date.parse` would read it as local time.
+  const at = Date.parse(/(GMT|UTC)$/i.test(trimmed) ? trimmed : `${trimmed} GMT`);
+  if (Number.isNaN(at)) {
+    return null;
+  }
+  const seconds = Math.ceil((at - now.getTime()) / 1000);
+  return Math.min(Math.max(seconds, 0), MAX_RETRY_AFTER_SECONDS);
+}

package/src/index.ts

@@ -36,14 +36,20 @@ export {
   type FormatPercentOptions,
 } from "./format.js";
 export {
+  parseLinkHeader,
   requestJson,
   toQueryString,
   type FetchFunction,
+  type HttpJsonAnswer,
   type HttpJsonFailure,
   type HttpJsonFailureCode,
   type HttpJsonMethod,
+  type HttpJsonResponseHeaders,
+  type HttpJsonRetryableCode,
   type HttpJsonWriteMethod,
+  type LinkHeaderLinks,
   type RequestJsonOptions,
+  type RequestJsonReadHeadersOptions,
   type RequestJsonReadOptions,
   type RequestJsonSchemaOptions,
   type RequestJsonWriteOptions,