@expandai/sdk 0.19.0 → 0.20.0

package/src/HttpClientHelpers.ts

@@ -1,5 +1,19 @@
 import { HttpClientError, HttpClientRequest, HttpClientResponse } from '@effect/platform'
 import { Effect, Schema } from 'effect'
+import { ExpandSdkError } from './Error.js'
+
+// Preserve transport status across Effect's tracing proxies without changing
+// the enumerable error body. A wire tag can occur at more than one status.
+const DECODED_ERROR_STATUS = Symbol('DecodedErrorStatus')
+
+export function decodedErrorStatus(error: unknown): number | undefined {
+	return typeof error === 'object' &&
+		error !== null &&
+		DECODED_ERROR_STATUS in error &&
+		typeof error[DECODED_ERROR_STATUS] === 'number'
+		? error[DECODED_ERROR_STATUS]
+		: undefined
+}
 
 export function unexpectedStatus(
 	request: HttpClientRequest.HttpClientRequest,
@@ -20,5 +34,38 @@ export function unexpectedStatus(
 }
 
 export function decodeError<A, I, R>(response: HttpClientResponse.HttpClientResponse, schema: Schema.Schema<A, I, R>) {
-	return Effect.flatMap(HttpClientResponse.schemaBodyJson(schema)(response), Effect.fail)
+	const decoded = HttpClientResponse.schemaBodyJson(schema)(response)
+	// Terminal statuses stay terminal even when a gateway sends an unfamiliar
+	// JSON body. Preserve the old unexpected-status path instead of retrying a ParseError.
+	const body =
+		response.status === 404 || response.status === 410
+			? decoded.pipe(Effect.catchTag('ParseError', () => unexpectedStatus(response.request, response)))
+			: decoded
+	return Effect.flatMap(body, (error) => {
+		if (typeof error === 'object' && error !== null)
+			Object.defineProperty(error, DECODED_ERROR_STATUS, { value: response.status })
+		return Effect.fail(error)
+	})
+}
+
+/**
+ * Decode a *success* body, turning a decode failure into a non-retryable `ExpandSdkError`.
+ *
+ * The distinction from a bare `ParseError` matters to the retry policy: an error-path decode
+ * failure may be an old server's body missing a new field, so `isRetryable` treats raw
+ * `ParseError`s as retryable and recovers the verdict from the rejected input. A 2xx body that
+ * fails its schema is the opposite case — the server said the capture *succeeded* and this SDK
+ * cannot read the answer, which is deterministic client/server skew — and retrying it re-runs a
+ * full capture per attempt for the same undecodable result.
+ */
+export function decodeSuccess<A, I, R>(
+	response: HttpClientResponse.HttpClientResponse,
+	schema: Schema.Schema<A, I, R>,
+) {
+	return HttpClientResponse.schemaBodyJson(schema)(response).pipe(
+		Effect.catchTag(
+			'ParseError',
+			(error) => new ExpandSdkError({ message: 'Failed to decode the API response', cause: error }),
+		),
+	)
 }

package/src/Internal.ts

@@ -1,14 +1,18 @@
 import { HttpClientError } from '@effect/platform'
-import { Cause, Effect, HashSet, Layer, Match, Option, ParseResult } from 'effect'
+import { Cause, Effect, HashSet, Layer, Match, Option, ParseResult, Predicate } from 'effect'
 import {
 	ExpandApiError,
+	ExpandClientApiError,
+	ExpandClientConnectionError,
 	ExpandClientError,
+	ExpandClientTimeoutError,
 	ExpandConnectionError,
 	type ExpandError,
 	ExpandSdkError,
 	ExpandTimeoutError,
 } from './Error.js'
-import * as Generated from './Generated.js'
+import { decodedErrorStatus } from './HttpClientHelpers.js'
+import { errorField, parseErrorBody } from './ParseErrorBody.js'
 import {
 	type BatchedParams,
 	type BatchedRequestOptions,
@@ -20,21 +24,69 @@ import {
 	type FetchJsonResponse,
 	type FetchParams,
 	type FetchResponse,
-	type FetchSearchParams,
-	type FetchSearchResponse,
 	type GetBatchedParams,
 	type GetBatchedResponse,
 	type RequestOptions,
+	type SnapshotCatalog,
+	type SnapshotGetParams,
+	type SnapshotHighlightsResponse,
 } from './Service.js'
 
 const RETRYABLE_STATUS_CODES = HashSet.make(408, 409, 429, 500, 502, 503, 504, 529)
 
-interface TaggedApiError {
-	readonly _tag: string
+// Status for each tagged error the API can return. Decoded error bodies always
+// carry their `_tag`, so this table classifies them without an arm apiece.
+const STATUS_BY_ERROR_TAG = new Map<string, number>([
+	['HttpApiDecodeError', 400],
+	['BadRequest', 400],
+	['BatchedIncludeUnsupported', 400],
+	['AuthFailed', 401],
+	['AccessBlocked', 403],
+	['FetchBlocked', 403],
+	['FetchSnapshotHighlightsNotFound', 404],
+	['SnapshotNotFound', 404],
+	['BatchedIdempotencyConflict', 409],
+	['BatchedCancellationConflict', 409],
+	['PayloadTooLarge', 413],
+	['FetchPageTooLarge', 413],
+	['FetchUnsupportedContentType', 415],
+	['FetchVideoUnavailable', 422],
+	['TooManyRequests', 429],
+	['FetchConcurrencyLimitExceeded', 429],
+	['InternalError', 500],
+	['FetchNavigationFailed', 502],
+	['FetchCaptureFailed', 502],
+	['FetchOriginHttpError', 502],
+	['ServiceUnavailable', 503],
+	['FetchDocumentProcessingUnavailable', 503],
+	['FetchCaptureTimeout', 504],
+	['FetchCapacityTimeout', 529],
+])
+
+function statusForErrorTag(error: unknown): Option.Option<number> {
+	if (typeof error !== 'object' || error === null || !('_tag' in error) || typeof error._tag !== 'string') {
+		return Option.none()
+	}
+	const transportStatus = decodedErrorStatus(error)
+	if (transportStatus !== undefined) return Option.some(transportStatus)
+	if (
+		error._tag === 'FetchOriginHttpError' &&
+		'statusCode' in error &&
+		(error.statusCode === 404 || error.statusCode === 410)
+	) {
+		return Option.some(error.statusCode)
+	}
+	return Option.fromNullable(STATUS_BY_ERROR_TAG.get(error._tag))
 }
 
-function hasApiErrorTag(error: unknown, tag: string): error is TaggedApiError {
-	return typeof error === 'object' && error !== null && '_tag' in error && error._tag === tag
+/**
+ * The `_tag` of the body a decode failed on, so a terminal error is not retried merely because this
+ * client could not decode the envelope it arrived in. See {@link parseErrorBody}.
+ */
+function parseErrorBodyTag(error: unknown): Option.Option<string> {
+	return Option.flatMap(parseErrorBody(error), (body) =>
+		Predicate.hasProperty(body, '_tag') && typeof body._tag === 'string' ? Option.some(body._tag) : Option.none(),
+	)
 }
 
 function apiError(status: number, error: unknown): ExpandApiError {
@@ -57,9 +109,22 @@ function apiError(status: number, error: unknown): ExpandApiError {
  * its public error channel.
  */
 export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
-	// Split across two `pipe` calls: the arm list is longer than `pipe`'s 20-argument overloads.
-	// Arms are evaluated top to bottom across both halves, so the ordering is unaffected.
-	const transportAndClientErrors = Match.value(error).pipe(
+	// Already-typed failures (including the promise-side `ExpandClient*` classes that the Crawl
+	// helpers throw) pass through so wrapping never turns a 429 into a bare SDK error.
+	if (
+		error instanceof ExpandApiError ||
+		error instanceof ExpandConnectionError ||
+		error instanceof ExpandTimeoutError ||
+		error instanceof ExpandSdkError
+	)
+		return error
+	if (error instanceof ExpandClientApiError)
+		return new ExpandApiError({ message: error.message, status: error.status, body: error.body, cause: error })
+	if (error instanceof ExpandClientTimeoutError)
+		return new ExpandTimeoutError({ message: error.message, timeoutMs: error.timeoutMs, cause: error })
+	if (error instanceof ExpandClientConnectionError)
+		return new ExpandConnectionError({ message: error.message, cause: error })
+	return Match.value(error).pipe(
 		Match.when(
 			(error: unknown) => error instanceof Cause.TimeoutException,
 			(error) => new ExpandTimeoutError({ message: `Request timed out after ${timeoutMs}ms`, timeoutMs, cause: error }),
@@ -79,84 +144,20 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 				}),
 		),
 		Match.when(
-			(error: unknown) => error instanceof Generated.AuthFailed,
-			(error) => new ExpandApiError({ message: 'AuthFailed', status: 401, body: error, cause: error }),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'AuthFailed'),
-			(error) => apiError(401, error),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'AccessBlocked'),
-			(error) => apiError(403, error),
-		),
-		Match.when(
-			(error: unknown) =>
-				hasApiErrorTag(error, 'BatchedIdempotencyConflict') || hasApiErrorTag(error, 'BatchedCancellationConflict'),
-			(error) => apiError(409, error),
-		),
-		Match.when(
-			(error: unknown) => error instanceof Generated.PayloadTooLarge,
-			(error) => new ExpandApiError({ message: 'PayloadTooLarge', status: 413, body: error, cause: error }),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'PayloadTooLarge'),
-			(error) => apiError(413, error),
-		),
-		Match.when(
-			(error: unknown) => error instanceof Generated.TooManyRequests,
-			(error) => new ExpandApiError({ message: 'TooManyRequests', status: 429, body: error, cause: error }),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'TooManyRequests'),
-			(error) => apiError(429, error),
-		),
-	)
-	return transportAndClientErrors.pipe(
-		Match.when(
-			(error: unknown) => error instanceof Generated.InternalError,
-			(error) => new ExpandApiError({ message: 'InternalError', status: 500, body: error, cause: error }),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'InternalError'),
-			(error) => apiError(500, error),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'FetchNavigationFailed'),
-			(error) => apiError(502, error),
-		),
-		// No `instanceof Generated.ServiceUnavailable` arm: decoded instances carry `_tag`, so the
-		// tag predicate already matches them and both would produce the same `apiError(503, ...)`.
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'ServiceUnavailable'),
-			(error) => apiError(503, error),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'FetchCaptureTimeout'),
-			(error) => apiError(504, error),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'FetchCapacityTimeout'),
-			(error) => apiError(529, error),
-		),
-		Match.when(
-			(error: unknown) => error instanceof Generated.HttpApiDecodeError,
-			(error) => new ExpandApiError({ message: 'HttpApiDecodeError', status: 400, body: error, cause: error }),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'HttpApiDecodeError') || hasApiErrorTag(error, 'BadRequest'),
-			(error) => apiError(400, error),
-		),
-		Match.when(
-			(error: unknown) => hasApiErrorTag(error, 'FetchSnapshotSearchNotFound'),
-			(error) => apiError(404, error),
+			(error: unknown) => Option.isSome(statusForErrorTag(error)),
+			(error) => apiError(Option.getOrThrow(statusForErrorTag(error)), error),
 		),
 		// A response we couldn't decode (e.g. a 5xx whose body is empty or doesn't match the declared
 		// error schema) arrives as a bare ParseError with no status. Surface a clear SDK error instead
-		// of dumping the raw schema-mismatch tree as the message.
+		// of dumping the raw schema-mismatch tree as the message — unless the body named an error class
+		// we recognize, in which case the caller gets its status rather than paying for our skew.
 		Match.when(
 			(error: unknown) => ParseResult.isParseError(error),
-			(error) => new ExpandSdkError({ message: 'Failed to decode the API response', cause: error }),
+			(error) =>
+				Option.getOrElse(
+					recoverUndecodedApiError(error, timeoutMs),
+					() => new ExpandSdkError({ message: 'Failed to decode the API response', cause: error }),
+				),
 		),
 		Match.orElse(
 			(error) => new ExpandSdkError({ message: error instanceof Error ? error.message : String(error), cause: error }),
@@ -165,24 +166,81 @@ export function toExpandError(error: unknown, timeoutMs: number): ExpandError {
 }
 
 /**
- * Decide whether a failure should trigger a retry. Timeouts and connection errors are always
- * retryable; API errors are retryable only for the standard transient status codes (408/409/429/5xx).
+ * The typed error an undecodable body still identifies itself as.
+ *
+ * A replica that predates a required field sends a body this client rejects wholesale, so a caller
+ * would see `ExpandSdkError` with no status where the previous release gave them
+ * `ExpandApiError(429)`. The tag survives on the rejected input, and every arm above keys off the
+ * tag rather than the class, so running them against it recovers the status. The `ParseError` stays
+ * as the cause: the response really was undecodable and that is what makes the skew visible.
+ *
+ * Terminates: the recursive call is given a plain object, which cannot itself be a `ParseError`.
+ */
+function recoverUndecodedApiError(error: ParseResult.ParseError, timeoutMs: number): Option.Option<ExpandApiError> {
+	if (Option.isNone(parseErrorBodyTag(error))) return Option.none()
+	return Option.flatMap(parseErrorBody(error), (body) => {
+		const recovered = toExpandError(body, timeoutMs)
+		return recovered instanceof ExpandApiError
+			? Option.some(new ExpandApiError({ message: recovered.message, status: recovered.status, body, cause: error }))
+			: Option.none()
+	})
+}
+
+/**
+ * The server's own verdict, for the error classes that carry one. Statuses whose retryability is
+ * ambiguous — 429, 500, 502, 503, 504, 529 — state it outright in the body, so no client-side rule has to
+ * guess and a newly-terminal class needs no SDK release.
+ *
+ * Read through {@link errorField} so the verdict still counts when the body did not decode. That is
+ * the case the whole mechanism exists for: an error class this SDK has never heard of is exactly
+ * the one no client-side rule can classify, and it is also the one guaranteed to fail the decode.
+ * Without the fallback, an unknown `{ retryable: false }` is retried — the precise outcome the
+ * field was added to prevent.
+ */
+function declaredRetryable(error: unknown): Option.Option<boolean> {
+	return errorField(error, 'retryable', (value): value is boolean => typeof value === 'boolean')
+}
+
+/**
+ * Decide whether a failure should trigger a retry. The body's `retryable` field decides when the
+ * server sent one. Everything below it is the fallback for servers that predate the field and for
+ * responses that never decoded: timeouts and connection errors are always retryable; API errors are
+ * retryable only for the standard transient status codes (408/409/429/5xx).
  */
 export function isRetryable(error: unknown, timeoutMs: number): boolean {
-	if (hasApiErrorTag(error, 'BatchedIdempotencyConflict') || hasApiErrorTag(error, 'BatchedCancellationConflict')) {
-		return false
-	}
-	// A 502 FetchNavigationFailed is a deterministic verdict about the target page (the browser
-	// committed an internal error document), not a transient gateway failure — retrying re-runs a
-	// full capture for the same outcome.
-	if (hasApiErrorTag(error, 'FetchNavigationFailed')) {
-		return false
-	}
-	// A typed 504 FetchCaptureTimeout is the conservative fallback when no result was publishable by
-	// the request deadline and queue-only expiry was not proven. Automatic retry remains disabled so
-	// ambiguous timeouts do not amplify a control-plane incident. A deliberate retry may still be
-	// appropriate; a bare intermediary 504 stays on the normal retryable-status path.
-	if (hasApiErrorTag(error, 'FetchCaptureTimeout')) {
+	return Option.match(declaredRetryable(error), {
+		onSome: (retryable) => retryable,
+		onNone: () => isRetryableWithoutServerVerdict(error, timeoutMs),
+	})
+}
+
+/**
+ * Tags that are terminal on their own, for servers that do not yet say so in the body. Everything
+ * here is a verdict rather than a condition: repeating the request reaches the same answer.
+ */
+const TERMINAL_TAGS = new Set([
+	'BatchedIdempotencyConflict',
+	'BatchedCancellationConflict',
+	'FetchNavigationFailed',
+	'FetchCaptureFailed',
+	// A 504 that is ours says `retryable: false` in the body and never reaches this set. This is the
+	// fallback for a server that predates the field: the timeout is the conservative verdict when no
+	// result was publishable by the deadline and queue-only expiry was not proven, so retrying it
+	// automatically would amplify a control-plane incident. A bare intermediary 504 carries no `_tag`
+	// and stays on the normal retryable-status path.
+	'FetchCaptureTimeout',
+])
+
+function isRetryableWithoutServerVerdict(error: unknown, timeoutMs: number): boolean {
+	// Both 502 classes are deterministic verdicts about the target page — the browser committed an
+	// internal error document, or the page could not be captured after the retry ladder was spent —
+	// not transient gateway failures, so retrying re-runs a full capture for the same outcome.
+	// Current servers say so in the body and never reach this line; it stays for the ones that don't
+	// yet, whose bodies reach it as a failed decode rather than a value.
+	const tag = Option.getOrElse(parseErrorBodyTag(error), () =>
+		typeof error === 'object' && error !== null && '_tag' in error && typeof error._tag === 'string' ? error._tag : '',
+	)
+	if (TERMINAL_TAGS.has(tag)) {
 		return false
 	}
 	// An undecodable response (a transient 5xx with an empty/garbled body, a proxy error page, etc.)
@@ -234,11 +292,11 @@ export class InternalClient extends Effect.Service<InternalClient>()('@expandai/
 		): Effect.Effect<FetchJsonResponse, ExpandClientError> =>
 			service.fetchJson(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
 
-		const fetchSearch = (
-			params: FetchSearchParams,
+		const getSnapshot = (
+			params: SnapshotGetParams,
 			options: RequestOptions = {},
-		): Effect.Effect<FetchSearchResponse, ExpandClientError> =>
-			service.fetchSearch(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
+		): Effect.Effect<SnapshotCatalog | SnapshotHighlightsResponse, ExpandClientError> =>
+			service.snapshots.get(params, options).pipe(Effect.mapError((error) => error.toPublicError()))
 
 		const batched = (
 			params: BatchedParams,
@@ -258,7 +316,7 @@ export class InternalClient extends Effect.Service<InternalClient>()('@expandai/
 		): Effect.Effect<CancelBatchedResponse, ExpandClientError> =>
 			service.cancelBatched(id, options).pipe(Effect.mapError((error) => error.toPublicError()))
 
-		return { fetch, fetchJson, fetchSearch, batched, getBatched, cancelBatched } as const
+		return { fetch, fetchJson, getSnapshot, batched, getBatched, cancelBatched } as const
 	}),
 }) {
 	/**

package/src/ParseErrorBody.ts

@@ -0,0 +1,42 @@
+import { Option, ParseResult, Predicate } from 'effect'
+import { ExpandApiError, ExpandClientApiError } from './Error.js'
+
+/**
+ * The response body a decode failed on.
+ *
+ * A body that does not satisfy the declared schema arrives as a `ParseError`, which carries none of
+ * the body's own fields — not its `_tag`, not its `retryable` verdict, not its `retryAfterSeconds`.
+ * Read naively, every one of those looks absent, and absent means "fall back to a client-side
+ * guess" at three separate call sites.
+ *
+ * That is not a hypothetical. This client requires `retryable` on the classes that carry it, so
+ * every body from a replica that predates the field fails to decode, and a rolling update runs
+ * mixed versions on every deploy. The rejected input survives on the issue, so the fields the
+ * server did send are still readable even though the body as a whole was refused.
+ *
+ * This is deliberately the single place that reaches into a `ParseError` for the body. Each caller
+ * that grew its own copy of the check ended up covering a different subset of the fields.
+ */
+export function parseErrorBody(error: unknown): Option.Option<object> {
+	if (!ParseResult.isParseError(error)) return Option.none()
+	const actual = error.issue.actual
+	return typeof actual === 'object' && actual !== null ? Option.some(actual) : Option.none()
+}
+
+/**
+ * A field read off either a decoded error or the raw body of an undecodable one.
+ *
+ * The decoded case is just the property; the fallback is what keeps a server's own answer
+ * authoritative when this client rejected the envelope around it.
+ */
+export function errorField<A>(error: unknown, key: string, refine: Predicate.Refinement<unknown, A>): Option.Option<A> {
+	const read = (source: unknown): Option.Option<A> =>
+		Predicate.hasProperty(source, key) && refine(source[key]) ? Option.some(source[key]) : Option.none()
+	return Option.orElse(read(error), () => {
+		if (error instanceof ExpandApiError || error instanceof ExpandClientApiError) {
+			const body: unknown = error.body
+			return Predicate.hasProperty(body, 'error') ? read(body.error) : read(body)
+		}
+		return Option.flatMap(parseErrorBody(error), read)
+	})
+}

package/src/Playground.ts

@@ -43,6 +43,54 @@ export function playgroundBase(snapshotId: string, host: string = DEFAULT_PLAYGR
 	return `${normalizeHost(host)}/s/${encodeURIComponent(snapshotId)}`
 }
 
+/** Appendix-only Markdown: `${host}/s/${snapshotId}/appendix` (public, `text/markdown`). */
+export function playgroundAppendixUrl(snapshotId: string, host: string = DEFAULT_PLAYGROUND_HOST): string {
+	return `${playgroundBase(snapshotId, host)}/appendix`
+}
+
+/**
+ * One block as Markdown by evidence id: `${host}/s/${snapshotId}/content?id=N`
+ * (public, request with `Accept: text/markdown`). Without an id, the whole
+ * public Markdown document.
+ */
+export function playgroundContentUrl(
+	snapshotId: string,
+	evidenceId?: number,
+	host: string = DEFAULT_PLAYGROUND_HOST,
+): string {
+	const base = `${playgroundBase(snapshotId, host)}/content`
+	const id = publicEvidenceId(evidenceId)
+	return id === undefined ? base : `${base}?id=${id}`
+}
+
+export interface SnapshotHandle {
+	readonly snapshotId: string
+	/** Origin of the playground URL the handle came from, when it was a URL. */
+	readonly host?: string
+}
+
+const SNAPSHOT_ID_PATTERN = /^[A-Za-z0-9._~-]+$/u
+
+/**
+ * Accept either a bare snapshot id or any playground URL for the snapshot
+ * (`https://expand.land/s/<id>`, `/s/<id>/appendix`, `/s/<id>?id=612`) and
+ * return the id plus the host it was served from. Text-mode fetch output
+ * has no `meta.snapshotId`; the `playground:` front-matter line is the handle.
+ */
+export function parseSnapshotHandle(handle: string): SnapshotHandle | undefined {
+	const trimmed = handle.trim()
+	if (trimmed.length === 0) return undefined
+	if (SNAPSHOT_ID_PATTERN.test(trimmed)) return { snapshotId: trimmed }
+	try {
+		const url = new URL(trimmed)
+		const match = /^\/s\/([^/]+)/u.exec(url.pathname)
+		if (!match?.[1]) return undefined
+		return { snapshotId: decodeURIComponent(match[1]), host: url.origin }
+	} catch {
+		return undefined
+	}
+}
+
 /** Origin of a server-provided `meta.playground` URL, for reuse as the host (staging-safe). */
 export function playgroundOrigin(metaPlayground: string): string {
 	return new URL(metaPlayground).origin

package/src/RetryAfter.ts

@@ -0,0 +1,138 @@
+import { Headers, HttpClient } from '@effect/platform'
+import { Duration, Effect, FiberRef, Option, Random } from 'effect'
+import { errorField } from './ParseErrorBody.js'
+
+const RETRY_AFTER_HEADER = 'retry-after'
+
+/**
+ * Upper bound on any single wait between attempts, server-requested or our own. `Retry-After` is a
+ * hint from a remote we do not control, and honouring an arbitrarily large one would park a
+ * caller's request far past its own timeout budget; the same bound applies to the exponential
+ * backoff, which a large `maxRetries` would otherwise grow past it. Two minutes is well above the
+ * largest value the API sends and well below any plausible caller patience.
+ */
+export const MAX_RETRY_AFTER = Duration.minutes(2)
+
+/**
+ * `Retry-After` from the most recent response received on this fiber, or `None` if that response
+ * carried no usable value.
+ *
+ * The header cannot travel on the error: `HttpApiClient`-style decoding fails with the schema
+ * instance parsed from the body, and the `HttpClientResponse` — the only thing that has headers —
+ * is gone by the time a retry schedule runs. Recording it here keeps the signal reachable without
+ * threading a response through every call site. Every response overwrites it, so a value can never
+ * outlive the attempt that produced it, and a fiber only ever observes its own requests.
+ */
+const currentRetryAfter = FiberRef.unsafeMake(Option.none<Duration.Duration>())
+
+/**
+ * Rounded to whole milliseconds rather than kept as fractional seconds.
+ *
+ * `Duration.seconds(1.001)` is representable only in nanoseconds, so Effect backs it with a
+ * `bigint`, and arithmetic on a `bigint` duration rejects a fractional operand outright —
+ * `Duration.times(d, 1.125)` throws `RangeError: The number 1.125 cannot be converted to a BigInt`.
+ * Both callers can produce a fraction: an HTTP-date differs from now by an arbitrary sub-second
+ * amount, and `retryAfterSeconds` is a JSON number. Normalizing here keeps every downstream
+ * duration millisecond-backed, so the jitter below is plain number arithmetic. Sub-millisecond
+ * precision is meaningless for a retry wait.
+ */
+const positiveSeconds = (seconds: number): Option.Option<Duration.Duration> =>
+	Number.isFinite(seconds) && seconds > 0
+		? Option.some(Duration.min(Duration.millis(Math.round(seconds * 1_000)), MAX_RETRY_AFTER))
+		: Option.none()
+
+/** Parses both `Retry-After` forms: delta-seconds and an HTTP-date. */
+const parseRetryAfter = (value: string): Option.Option<Duration.Duration> => {
+	const trimmed = value.trim()
+	if (/^\d+$/.test(trimmed)) return positiveSeconds(Number(trimmed))
+	const retryAt = Date.parse(trimmed)
+	return Number.isNaN(retryAt) ? Option.none() : positiveSeconds((retryAt - Date.now()) / 1_000)
+}
+
+/**
+ * Records the `Retry-After` of every response the client receives, so {@link retryAfterDelay} can
+ * read it back when a failure is about to be retried.
+ */
+export const recordRetryAfter = <E, R>(client: HttpClient.HttpClient.With<E, R>): HttpClient.HttpClient.With<E, R> =>
+	HttpClient.tap(
+		// Cleared before the request, not just overwritten after it. An attempt that fails at the
+		// transport level never produces a response to overwrite the previous one, so without this the
+		// next attempt would sleep on a wait some earlier response asked for — a connection reset would
+		// inherit a saturated gate's 20s.
+		HttpClient.tapRequest(client, () => FiberRef.set(currentRetryAfter, Option.none())),
+		(response) =>
+			FiberRef.set(
+				currentRetryAfter,
+				Option.flatMap(Headers.get(response.headers, RETRY_AFTER_HEADER), parseRetryAfter),
+			),
+	)
+
+/**
+ * Reads `retryAfterSeconds` off a decoded error body. Errors that can name their own recovery time
+ * say so in the body as well as the header; the body wins because it survives proxies that strip
+ * headers, and because it is the value the server actually chose for this error rather than for
+ * this status.
+ */
+const bodyRetryAfter = (error: unknown): Option.Option<Duration.Duration> =>
+	Option.flatMap(
+		// Through `errorField` rather than off the error directly, so a body this client could not
+		// decode still gets to name its own wait. An unknown error class is both the one whose delay
+		// no client-side default can guess and the one certain to fail the decode.
+		errorField(error, 'retryAfterSeconds', (value): value is number => typeof value === 'number'),
+		positiveSeconds,
+	)
+
+/**
+ * Widest multiple of a server-requested wait this will actually sleep. Jitter only ever runs the
+ * wait *longer*: the server named the earliest moment worth trying again, so spreading below it
+ * would retry sooner than asked, which is the thing the header exists to prevent.
+ */
+const RETRY_AFTER_JITTER = 1.25
+
+/**
+ * Spreads a server-requested wait across a window so a whole rejected population does not wake at
+ * once. The value is a policy constant chosen per status rather than per caller, so every client
+ * refused in the same burst is handed the identical number; sleeping it raw would reconverge them
+ * on one instant and march them into the same saturated gate together, which is the behaviour the
+ * wait was supposed to break up.
+ */
+export const spreadRetryAfter = (retryAfter: Duration.Duration): Effect.Effect<Duration.Duration> =>
+	Effect.map(Random.next, (factor) =>
+		// Scaled as milliseconds rather than with `Duration.times`, which throws on a fractional
+		// factor whenever the duration happens to be nanosecond-backed. `positiveSeconds` already
+		// keeps our own values millisecond-backed; doing the arithmetic in numbers means an
+		// unrounded duration arriving from anywhere else cannot reintroduce that crash.
+		Duration.min(
+			Duration.millis(Math.round(Duration.toMillis(retryAfter) * (1 + factor * (RETRY_AFTER_JITTER - 1)))),
+			MAX_RETRY_AFTER,
+		),
+	)
+
+/**
+ * How long the server asked us to wait before retrying this failure — `Duration.zero` when it asked
+ * for nothing, which leaves the caller's own backoff untouched.
+ */
+export const retryAfterDelay = (error: unknown): Effect.Effect<Duration.Duration> =>
+	Effect.map(FiberRef.get(currentRetryAfter), (fromHeader) =>
+		bodyRetryAfter(error).pipe(
+			Option.orElse(() => fromHeader),
+			Option.getOrElse(() => Duration.zero),
+		),
+	)
+
+/**
+ * The wait before the next attempt, given the failure and the backoff the schedule computed.
+ *
+ * A server that asked for a wait gets at least that wait: retrying sooner than it asked only
+ * spends the caller's timeout budget on a refusal it already predicted. The floor is re-jittered
+ * ({@link spreadRetryAfter}) because the server hands every client refused in the same burst the
+ * identical constant. Backoff wins when it is the longer of the two, but never past
+ * {@link MAX_RETRY_AFTER} — a large `maxRetries` must not grow the exponential past what we would
+ * accept from the server.
+ */
+export const nextRetryDelay = (error: unknown, backoff: Duration.Duration): Effect.Effect<Duration.Duration> =>
+	Effect.flatMap(retryAfterDelay(error), (retryAfter) =>
+		Duration.greaterThan(retryAfter, backoff)
+			? spreadRetryAfter(retryAfter)
+			: Effect.succeed(Duration.min(backoff, MAX_RETRY_AFTER)),
+	)