@zerotal/client 1.8.1 → 1.10.0

package/CHANGELOG.md

@@ -8,6 +8,16 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.9.0] — 2026-08-29
+
+### Documented
+
+- **Every promised export is documented.** The `docs-coverage` gate reads `maturity: stable` as a
+  promise about a package's exports, and measures how much of that promise is written down. It
+  was 798 gaps across the suite; it is now zero. This package's share is covered on its own
+  pages — types named, options shapes described, and the decisions behind them recorded where
+  somebody looking for them will find them.
+
 ## [1.7.2] — 2026-08-18
 
 ### Fixed

package/api-surface.md

@@ -127,64 +127,64 @@ function ClientConfig = (options?: Partial<ClientConfigShape>) => Partial<Client
 function createApiClient = <Routes extends ApiRouteMap>(config?: ApiClientConfig) => ApiClient<Routes>
 
 interface ApiClientConfig = {
-  baseUrl?: string
-  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions
-  csrf?: boolean | {    cookie?: string;    header?: string;}
-  headers?: Record<string, string>
-  onError?: (error: ApiClientError) => void | Promise<void>
-  onForbidden?: (error: ApiClientError) => void | Promise<void>
-  onRequest?: RequestInterceptor | RequestInterceptor[]
-  onResponse?: ResponseInterceptor | ResponseInterceptor[]
-  onUnauthorized?: (error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void
-  retry?: number | RetryOptions
-  timeout?: number
-  token?: TokenSource
-  withCredentials?: boolean
+  baseUrl?: string | undefined
+  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions | undefined
+  csrf?: boolean | {    cookie?: string;    header?: string;} | undefined
+  headers?: Record<string, string> | undefined
+  onError?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onForbidden?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onRequest?: RequestInterceptor | RequestInterceptor[] | undefined
+  onResponse?: ResponseInterceptor | ResponseInterceptor[] | undefined
+  onUnauthorized?: ((error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void) | undefined
+  retry?: number | RetryOptions | undefined
+  timeout?: number | undefined
+  token?: TokenSource | undefined
+  withCredentials?: boolean | undefined
 }
 
 interface CircuitBreakerOptions = {
-  isFailure?: (error: unknown) => boolean
-  resetTimeout?: number
-  threshold?: number
+  isFailure?: ((error: unknown) => boolean) | undefined
+  resetTimeout?: number | undefined
+  threshold?: number | undefined
 }
 
 interface ClientConfigShape = {
-  baseUrl?: string
-  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions
-  csrf?: boolean | {    cookie?: string;    header?: string;}
-  headers?: Record<string, string>
-  onError?: (error: ApiClientError) => void | Promise<void>
-  onForbidden?: (error: ApiClientError) => void | Promise<void>
-  onRequest?: RequestInterceptor | RequestInterceptor[]
-  onResponse?: ResponseInterceptor | ResponseInterceptor[]
-  onUnauthorized?: (error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void
-  retry?: number | RetryOptions
-  timeout?: number
-  token?: TokenSource
-  withCredentials?: boolean
+  baseUrl?: string | undefined
+  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions | undefined
+  csrf?: boolean | {    cookie?: string;    header?: string;} | undefined
+  headers?: Record<string, string> | undefined
+  onError?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onForbidden?: ((error: ApiClientError) => void | Promise<void>) | undefined
+  onRequest?: RequestInterceptor | RequestInterceptor[] | undefined
+  onResponse?: ResponseInterceptor | ResponseInterceptor[] | undefined
+  onUnauthorized?: ((error: ApiClientError, retry: (headerOverrides?: Record<string, string>) => Promise<unknown>) => Promise<unknown> | void) | undefined
+  retry?: number | RetryOptions | undefined
+  timeout?: number | undefined
+  token?: TokenSource | undefined
+  withCredentials?: boolean | undefined
 }
 
 interface GetOptions = {
-  headers?: Record<string, string>
-  init?: Omit<RequestInit, 'method' | 'headers' | 'body'>
-  meta?: (meta: ResponseMeta) => void
-  query?: Q
-  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer'
-  retry?: number | false | RetryOptions
-  signal?: AbortSignal
-  timeout?: number
+  headers?: Record<string, string> | undefined
+  init?: Omit<RequestInit, 'method' | 'headers' | 'body'> | undefined
+  meta?: ((meta: ResponseMeta) => void) | undefined
+  query?: Q | undefined
+  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer' | undefined
+  retry?: number | false | RetryOptions | undefined
+  signal?: AbortSignal | undefined
+  timeout?: number | undefined
 }
 
 interface MutationOptions = {
-  headers?: Record<string, string>
-  init?: Omit<RequestInit, 'method' | 'headers' | 'body'>
-  meta?: (meta: ResponseMeta) => void
-  params?: Record<string, string | number>
-  query?: Q
-  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer'
-  retry?: number | false | RetryOptions
-  signal?: AbortSignal
-  timeout?: number
+  headers?: Record<string, string> | undefined
+  init?: Omit<RequestInit, 'method' | 'headers' | 'body'> | undefined
+  meta?: ((meta: ResponseMeta) => void) | undefined
+  params?: Record<string, string | number> | undefined
+  query?: Q | undefined
+  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer' | undefined
+  retry?: number | false | RetryOptions | undefined
+  signal?: AbortSignal | undefined
+  timeout?: number | undefined
 }
 
 interface PresenceMember = {
@@ -200,13 +200,13 @@ interface RequestConfig = {
 }
 
 interface RequestOptions = {
-  headers?: Record<string, string>
-  init?: Omit<RequestInit, 'method' | 'headers' | 'body'>
-  meta?: (meta: ResponseMeta) => void
-  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer'
-  retry?: number | false | RetryOptions
-  signal?: AbortSignal
-  timeout?: number
+  headers?: Record<string, string> | undefined
+  init?: Omit<RequestInit, 'method' | 'headers' | 'body'> | undefined
+  meta?: ((meta: ResponseMeta) => void) | undefined
+  responseType?: 'text' | 'json' | 'auto' | 'blob' | 'arrayBuffer' | undefined
+  retry?: number | false | RetryOptions | undefined
+  signal?: AbortSignal | undefined
+  timeout?: number | undefined
 }
 
 interface ResponseContext = {
@@ -222,11 +222,11 @@ interface ResponseMeta = {
 }
 
 interface RetryOptions = {
-  attempts?: number
-  backoff?: (attempt: number, retryAfterMs: number | null) => number
-  methods?: string[]
-  respectRetryAfter?: boolean
-  statuses?: number[]
+  attempts?: number | undefined
+  backoff?: ((attempt: number, retryAfterMs: number | null) => number) | undefined
+  methods?: string[] | undefined
+  respectRetryAfter?: boolean | undefined
+  statuses?: number[] | undefined
 }
 
 interface RouteShape = {
@@ -247,20 +247,20 @@ interface SocketLike = {
 }
 
 interface SocketOptions = {
-  WebSocket?: new (url: string) => SocketLike
-  auth?: {    params?: Record<string, string>;    headers?: Record<string, string>;}
-  authEndpoint?: string | false
-  autoConnect?: boolean
-  fetch?: typeof fetch
-  host?: string
-  maxReconnectDelay?: number
-  path?: string
-  pingInterval?: number
-  port?: string | number
-  reconnect?: boolean
-  reconnectDelay?: number
-  scheme?: 'ws' | 'wss'
-  url?: string
+  WebSocket?: (new (url: string) => SocketLike) | undefined
+  auth?: {    params?: Record<string, string>;    headers?: Record<string, string>;} | undefined
+  authEndpoint?: string | false | undefined
+  autoConnect?: boolean | undefined
+  fetch?: typeof fetch | undefined
+  host?: string | undefined
+  maxReconnectDelay?: number | undefined
+  path?: string | undefined
+  pingInterval?: number | undefined
+  port?: string | number | undefined
+  reconnect?: boolean | undefined
+  reconnectDelay?: number | undefined
+  scheme?: 'ws' | 'wss' | undefined
+  url?: string | undefined
 }
 
 type ApiRouteMap = {    [x: `GET ${string}`]: RouteShape | undefined;    [x: `POST ${string}`]: RouteShape | undefined;    [x: `PUT ${string}`]: RouteShape | undefined;    [x: `PATCH ${string}`]: RouteShape | undefined;    [x: `DELETE ${string}`]: RouteShape | undefined;}
@@ -373,20 +373,20 @@ interface SocketLike = {
 }
 
 interface SocketOptions = {
-  WebSocket?: new (url: string) => SocketLike
-  auth?: {    params?: Record<string, string>;    headers?: Record<string, string>;}
-  authEndpoint?: string | false
-  autoConnect?: boolean
-  fetch?: typeof fetch
-  host?: string
-  maxReconnectDelay?: number
-  path?: string
-  pingInterval?: number
-  port?: string | number
-  reconnect?: boolean
-  reconnectDelay?: number
-  scheme?: 'ws' | 'wss'
-  url?: string
+  WebSocket?: (new (url: string) => SocketLike) | undefined
+  auth?: {    params?: Record<string, string>;    headers?: Record<string, string>;} | undefined
+  authEndpoint?: string | false | undefined
+  autoConnect?: boolean | undefined
+  fetch?: typeof fetch | undefined
+  host?: string | undefined
+  maxReconnectDelay?: number | undefined
+  path?: string | undefined
+  pingInterval?: number | undefined
+  port?: string | number | undefined
+  reconnect?: boolean | undefined
+  reconnectDelay?: number | undefined
+  scheme?: 'ws' | 'wss' | undefined
+  url?: string | undefined
 }
 
 type SocketState = 'connecting' | 'connected' | 'disconnected' | 'reconnecting' | 'error'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/client",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,7 +35,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1"
+    "@zerotal/core": "1.10.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/ApiClient.ts

@@ -73,31 +73,31 @@ export interface ResponseMeta {
 
 export interface RequestOptions {
   /** Extra headers merged on top of the client's default headers. */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
   /** Additional `RequestInit` fields (e.g. `credentials`, `mode`, `cache`). */
-  init?: Omit<RequestInit, "method" | "headers" | "body">;
+  init?: Omit<RequestInit, "method" | "headers" | "body"> | undefined;
   /** Abort signal for cancellation (combined with any `timeout`). */
-  signal?: AbortSignal;
+  signal?: AbortSignal | undefined;
   /** Per-request timeout in ms (overrides the client default; `0` disables). */
-  timeout?: number;
+  timeout?: number | undefined;
   /** Per-request retry policy (overrides the client default; `false` disables). */
-  retry?: number | RetryOptions | false;
+  retry?: number | RetryOptions | false | undefined;
   /** How to read the response body. Default `"auto"` (JSON with text fallback). */
-  responseType?: "auto" | "json" | "text" | "blob" | "arrayBuffer";
+  responseType?: "auto" | "json" | "text" | "blob" | "arrayBuffer" | undefined;
   /** Read response metadata (status, headers) without a global interceptor. */
-  meta?: (meta: ResponseMeta) => void;
+  meta?: ((meta: ResponseMeta) => void) | undefined;
 }
 
 export interface GetOptions<Q> extends RequestOptions {
   /** Query-string parameters (nested arrays/objects are serialized with bracket notation). */
-  query?: Q;
+  query?: Q | undefined;
 }
 
 export interface MutationOptions<Q> extends RequestOptions {
   /** URL path parameters for routes like `/api/users/{id}/action`. */
-  params?: Record<string, string | number>;
+  params?: Record<string, string | number> | undefined;
   /** Query-string parameters. */
-  query?: Q;
+  query?: Q | undefined;
 }
 
 // ── Client config ─────────────────────────────────────────────────────────────
@@ -108,39 +108,39 @@ export type TokenSource =
 
 export interface ApiClientConfig {
   /** Base URL prepended to every request path, e.g. `'https://api.example.com'`. */
-  baseUrl?: string;
+  baseUrl?: string | undefined;
   /** Default headers sent with every request (e.g. `Authorization`). */
-  headers?: Record<string, string>;
+  headers?: Record<string, string> | undefined;
   /**
    * Bearer token attached as `Authorization: Bearer <token>` when no `Authorization` header is
    * already present. May be a string or a (possibly async) resolver. Update at runtime with
    * {@link ApiClient.setToken}.
    */
-  token?: TokenSource;
+  token?: TokenSource | undefined;
   /** Send credentials (cookies) with every request — sets `credentials: 'include'`. */
-  withCredentials?: boolean;
+  withCredentials?: boolean | undefined;
   /**
    * Attach the CSRF/XSRF token to mutating requests: reads the `XSRF-TOKEN` cookie and sends it as
    * `X-XSRF-TOKEN` (the SPA/session flow). Defaults to `true` when `withCredentials` is set.
    * Customize the cookie/header names with an object.
    */
-  csrf?: boolean | { cookie?: string; header?: string };
+  csrf?: boolean | { cookie?: string; header?: string } | undefined;
   /** Default per-request timeout in ms (`0`/omitted = no timeout). */
-  timeout?: number;
+  timeout?: number | undefined;
   /**
    * Default retry policy. `2` retries idempotent requests on network errors / 5xx / 429 with
    * exponential backoff (honoring `Retry-After`); pass {@link RetryOptions} to tune, or omit to
    * disable. Per-request `retry` overrides this.
    */
-  retry?: number | RetryOptions;
+  retry?: number | RetryOptions | undefined;
   /** Called for every non-2xx response before the error is thrown. */
-  onError?: (error: ApiClientError) => void | Promise<void>;
+  onError?: ((error: ApiClientError) => void | Promise<void>) | undefined;
   /** Called when a request receives `403 Forbidden`. */
-  onForbidden?: (error: ApiClientError) => void | Promise<void>;
+  onForbidden?: ((error: ApiClientError) => void | Promise<void>) | undefined;
   /** One or more request interceptors executed in order before every fetch. */
-  onRequest?: RequestInterceptor | RequestInterceptor[];
+  onRequest?: RequestInterceptor | RequestInterceptor[] | undefined;
   /** One or more response interceptors executed in order after every successful (2xx) response. */
-  onResponse?: ResponseInterceptor | ResponseInterceptor[];
+  onResponse?: ResponseInterceptor | ResponseInterceptor[] | undefined;
   /**
    * Called when a request receives `401 Unauthorized`. Receives the error and a `retry` function
    * (optionally with header overrides) to re-execute the request once.
@@ -148,12 +148,14 @@ export interface ApiClientConfig {
    * @example
    * onUnauthorized: async (err, retry) => retry({ Authorization: `Bearer ${await refresh()}` }),
    */
-  onUnauthorized?: (
-    error: ApiClientError,
-    retry: (headerOverrides?: Record<string, string>) => Promise<unknown>,
-  ) => Promise<unknown> | void;
+  onUnauthorized?:
+    | ((
+        error: ApiClientError,
+        retry: (headerOverrides?: Record<string, string>) => Promise<unknown>,
+      ) => Promise<unknown> | void)
+    | undefined;
   /** Attach a circuit breaker (instance to share, or options to create a dedicated one). */
-  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions;
+  circuitBreaker?: CircuitBreaker | CircuitBreakerOptions | undefined;
 }
 
 // ── ApiClient<Routes> ───────────────────────────────────────────────────────────

package/src/CircuitBreaker.ts

@@ -10,19 +10,19 @@ export interface CircuitBreakerOptions {
    * Number of consecutive failures required to open the circuit.
    * Default: `5`.
    */
-  threshold?: number;
+  threshold?: number | undefined;
   /**
    * Milliseconds to wait in the open state before allowing a single probe
    * request through (transition to half-open). Default: `30_000` (30 s).
    */
-  resetTimeout?: number;
+  resetTimeout?: number | undefined;
   /**
    * Predicate that decides whether a thrown error counts as a failure.
    * By default, network errors and `ApiClientError` responses with status ≥ 500
    * are failures; 4xx errors are not (they indicate client mistakes, not
    * upstream outages).
    */
-  isFailure?: (error: unknown) => boolean;
+  isFailure?: ((error: unknown) => boolean) | undefined;
 }
 
 // ── Error thrown when the circuit is open ─────────────────────────────────────

package/src/Socket.ts

@@ -50,42 +50,42 @@ export interface SocketOptions {
    * Full WebSocket URL. When omitted it's derived from the page location (browser) as
    * `ws(s)://<host>:<port><path>`. Required in non-browser environments.
    */
-  url?: string;
+  url?: string | undefined;
   /** WebSocket upgrade path. Defaults to `/app/ws` (matches the broadcasting config default). */
-  path?: string;
+  path?: string | undefined;
   /** Host override (defaults to `location.hostname`). */
-  host?: string;
+  host?: string | undefined;
   /** Port override (defaults to `location.port`). */
-  port?: string | number;
+  port?: string | number | undefined;
   /** Force a scheme. Defaults to `wss` on https pages, `ws` otherwise. */
-  scheme?: "ws" | "wss";
+  scheme?: "ws" | "wss" | undefined;
   /**
    * Authentication for the connection and for private/presence channels:
    *  - `params`  — query params appended to the WS URL (browsers can't set WS headers), read
    *                by the server on upgrade.
    *  - `headers` — sent on the `POST /broadcasting/auth` request (e.g. a CSRF token).
    */
-  auth?: { params?: Record<string, string>; headers?: Record<string, string> };
+  auth?: { params?: Record<string, string>; headers?: Record<string, string> } | undefined;
   /**
    * Endpoint that signs a private/presence subscription (Pusher-style). Defaults to
    * `/broadcasting/auth`. Set to `false` to skip the signature fetch and rely on
    * connection-level authorization instead.
    */
-  authEndpoint?: string | false;
+  authEndpoint?: string | false | undefined;
   /** Inject a `fetch` implementation for the auth request (tests / non-DOM runtimes). */
-  fetch?: typeof fetch;
+  fetch?: typeof fetch | undefined;
   /** Connect immediately on construction. Default: true. */
-  autoConnect?: boolean;
+  autoConnect?: boolean | undefined;
   /** Reconnect automatically after an unexpected close. Default: true. */
-  reconnect?: boolean;
+  reconnect?: boolean | undefined;
   /** Initial reconnect delay in ms (doubles each attempt up to `maxReconnectDelay`). Default: 1000. */
-  reconnectDelay?: number;
+  reconnectDelay?: number | undefined;
   /** Cap on the reconnect backoff in ms. Default: 30000. */
-  maxReconnectDelay?: number;
+  maxReconnectDelay?: number | undefined;
   /** Heartbeat ping interval in ms (0 disables). Default: 30000. */
-  pingInterval?: number;
+  pingInterval?: number | undefined;
   /** Inject a WebSocket constructor (tests / non-DOM runtimes). Defaults to the global. */
-  WebSocket?: new (url: string) => SocketLike;
+  WebSocket?: (new (url: string) => SocketLike) | undefined;
 }
 
 type Listener = (payload: unknown) => void;
@@ -217,6 +217,16 @@ export class PresenceChannel extends Channel {
   }
 }
 
+/** The options {@link Socket}'s constructor always fills in. */
+type GuaranteedOption =
+  | "path"
+  | "autoConnect"
+  | "reconnect"
+  | "reconnectDelay"
+  | "maxReconnectDelay"
+  | "pingInterval"
+  | "authEndpoint";
+
 /**
  * Realtime client for Zerotal broadcasting (native `ws` / `redis` drivers). Exposes a
  * familiar realtime-client API over the native protocol — see the module header for usage.
@@ -231,19 +241,17 @@ export class Socket {
   private _reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   private _pingTimer: ReturnType<typeof setInterval> | null = null;
   private _closedByUser = false;
-  private readonly _opts: Required<
-    Pick<
-      SocketOptions,
-      | "path"
-      | "autoConnect"
-      | "reconnect"
-      | "reconnectDelay"
-      | "maxReconnectDelay"
-      | "pingInterval"
-      | "authEndpoint"
-    >
-  > &
-    SocketOptions;
+  /**
+   * The seven fields the constructor guarantees, plus whatever else was passed.
+   *
+   * `Omit` rather than `& SocketOptions`: intersecting with the whole shape puts the
+   * optional declaration of each guaranteed field back alongside the required one, so
+   * `pingInterval` read as possibly `undefined` in the very code that had just given
+   * it a default.
+   */
+  private readonly _opts: {
+    [K in GuaranteedOption]-?: Exclude<SocketOptions[K], undefined>;
+  } & Omit<SocketOptions, GuaranteedOption>;
 
   constructor(options: SocketOptions = {}) {
     // The caller's options go FIRST, then the defaults fill the gaps.

package/src/config.ts

@@ -2,7 +2,7 @@ import { deepMerge } from "@zerotal/core/helpers";
 import type { ApiClientConfig } from "./ApiClient.ts";
 
 export interface ClientConfigShape extends ApiClientConfig {
-  baseUrl?: string;
+  baseUrl?: string | undefined;
 }
 
 // The client carries no framework-level defaults of its own — `ApiClient` applies

package/src/http.ts

@@ -1,3 +1,4 @@
+import { definedOnly, type Resolved } from "@zerotal/core/helpers";
 import { ApiClientError } from "./errors.ts";
 import { CircuitBreakerOpenError } from "./CircuitBreaker.ts";
 
@@ -109,18 +110,18 @@ export function readCookie(name: string): string | undefined {
 
 export interface RetryOptions {
   /** Max retry attempts after the first try. Default: 2. */
-  attempts?: number;
+  attempts?: number | undefined;
   /** HTTP methods eligible for retry. Default: idempotent verbs (GET/PUT/DELETE/HEAD/OPTIONS). */
-  methods?: string[];
+  methods?: string[] | undefined;
   /** HTTP statuses that should be retried. Default: 408, 425, 429, 500, 502, 503, 504. */
-  statuses?: number[];
+  statuses?: number[] | undefined;
   /** Honor a `Retry-After` header when present. Default: true. */
-  respectRetryAfter?: boolean;
+  respectRetryAfter?: boolean | undefined;
   /** Compute the delay (ms) before attempt N. Default: exponential backoff + jitter. */
-  backoff?: (attempt: number, retryAfterMs: number | null) => number;
+  backoff?: ((attempt: number, retryAfterMs: number | null) => number) | undefined;
 }
 
-const DEFAULT_RETRY: Required<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff"> = {
+const DEFAULT_RETRY: Resolved<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff"> = {
   attempts: 2,
   methods: ["GET", "PUT", "DELETE", "HEAD", "OPTIONS"],
   statuses: [408, 425, 429, 500, 502, 503, 504],
@@ -131,12 +132,15 @@ const DEFAULT_RETRY: Required<Omit<RetryOptions, "backoff">> & Pick<RetryOptions
 export function resolveRetry(
   retry: number | RetryOptions | false | undefined,
   method: string,
-): Required<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff"> {
+): Resolved<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff"> {
   if (retry === undefined || retry === false || retry === 0) {
     return { ...DEFAULT_RETRY, attempts: 0 };
   }
   const opts = typeof retry === "number" ? { attempts: retry } : retry;
-  const merged = { ...DEFAULT_RETRY, ...opts };
+  // `definedOnly`, not a bare spread: these options accept an explicit `undefined`
+  // so that `{ attempts: cfg.attempts }` compiles, and a bare spread would then let
+  // that `undefined` overwrite the default rather than leave it standing.
+  const merged = { ...DEFAULT_RETRY, ...definedOnly(opts) };
   // Methods are matched case-insensitively.
   if (!merged.methods.some((m) => m.toUpperCase() === method.toUpperCase())) {
     return { ...merged, attempts: 0 };
@@ -173,7 +177,7 @@ function _isRetryable(
 /** Run `fn`, retrying transient failures per `policy`. */
 export async function withRetry<T>(
   fn: () => Promise<T>,
-  policy: Required<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff">,
+  policy: Resolved<Omit<RetryOptions, "backoff">> & Pick<RetryOptions, "backoff">,
 ): Promise<T> {
   const backoff = policy.backoff ?? _defaultBackoff;
   let attempt = 0;