@openstage/monadyssey-fetch 3.0.0-beta.8 → 3.0.0-rc.2

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2024 Gabriel Bornea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and
+to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
+THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Inspiration Acknowledgment:
+
+The monadyssey library's development and design approaches draw conceptual inspiration from the Haskell language,
+the Arrow library for Kotlin, and the Cats library for Scala. This acknowledgment is to highlight the influence
+these projects have had on monadyssey's API design and embrace of functional programming paradigms. It is crucial
+to note that this inspiration pertains solely to API design and architecture principles; no direct code from these
+projects has been used in monadyssey. This library stands as an independent work, and this section is included to
+honor the spirit of shared knowledge and to contribute to community growth within the functional programming ecosystem.

package/dist/monadyssey-fetch.d.ts

@@ -1,6 +1,7 @@
 import { IO } from '@openstage/monadyssey-core';
 import { Option as Option_2 } from '@openstage/monadyssey-core';
-import { Pipe } from '@openstage/monadyssey-core';
+import type { Pipe } from '@openstage/monadyssey-core';
+import type { Schedule } from '@openstage/monadyssey-core';
 import { Stream } from '@openstage/monadyssey-core';
 
 /**
@@ -21,24 +22,37 @@ export declare type Credentials = "omit" | "same-origin" | "include";
 export declare const decodeEvents: <E>() => Pipe<E, Uint8Array, ServerSentEvent>;
 
 /**
- * A composable HTTP client that wraps the native `fetch` API, returning `IO` instances instead of Promises.
+ * `T` restricted to the keys of `Shape`: every other key is typed `never`, so an object with an extra
+ * key is rejected even when it is a variable rather than a literal. `send` / `raw` take their options
+ * this way, so a payload passed positionally (`send("POST", url, article)`, where `article` happens to
+ * have a `body` key) does not type-check as the options.
+ */
+declare type Exact<T, Shape> = T & {
+    [K in Exclude<keyof T, keyof Shape>]: never;
+};
+
+/**
+ * A composable HTTP client that wraps the native `fetch` API, returning `IO` instances instead of
+ * Promises. Each instance carries its own configuration (base URL, interceptors, default headers,
+ * timeout, credentials), so different parts of an application can use independently configured
+ * clients.
  *
- * Unlike v1, `HttpClient` is instantiable — each instance carries its own configuration (base URL,
- * interceptors, default headers, timeout, credentials). This allows different parts of an application
- * to use independently configured clients.
+ * Three kinds of call, by what you want back:
+ * - **the decoded body** — `get`, `post`, `put`, `patch`, `delete`, `fetch` return
+ *   `IO<HttpError, A>`. A response with no body (`204`, an empty `200`) fails with
+ *   `kind: "decode"`, since a value was expected; pass `{ empty: "option" }` when absence is
+ *   legitimate, to get `IO<HttpError, Option<A>>`.
+ * - **nothing** — `send(method, uri, { body })` returns `IO<HttpError, void>` for actions whose
+ *   response body you do not read (publish, archive, leave …); any body, or none, is fine.
+ * - **the `Response`** — `raw(method, uri, options?)` returns `IO<HttpError, Response>` for
+ *   status codes, headers or streaming.
  *
- * All HTTP methods return `IO<HttpError, A | null>`, enabling lazy execution, functional composition,
- * and explicit error handling. Cancellation is supported: when an IO is cancelled (via fiber or
- * timeout), the underlying `fetch` call is aborted through `AbortSignal`.
+ * Every non-2xx response fails with `kind: "response"`, whichever you use. Cancellation is
+ * supported: when the IO is cancelled (via a fiber or `timeout`), the underlying `fetch` is
+ * aborted through its `AbortSignal`.
  *
- * **On the `| null` in the return type:** when the server responds with `204 No Content` or
- * `205 Reset Content`, there is no body to parse and the IO succeeds with `null`. This is a
- * protocol-level fact (the HTTP spec says these statuses have no body), distinct from a
- * domain-level optionality. For that reason the methods return `IO<HttpError, A | null>` rather
- * than `IO<HttpError, Option<A>>`. `Option` is the right tool when a value might be absent at
- * the domain level; `| null` is honest when the absence is structural to the protocol. For the
- * 95% case where you control the endpoint and never receive 204, the `| null` is a brief
- * `?? defaultValue` away.
+ * `A` is what you claim the body is; the JSON is not checked unless you pass a `transform` that
+ * validates it (a schema's `parse`, say) — a throw there fails with `kind: "decode"`.
  *
  * **Default credentials:** `same-origin`, matching the platform `fetch` default. Set
  * `credentials: "include"` explicitly per-client or per-request if you need cookies to flow
@@ -48,11 +62,12 @@ export declare const decodeEvents: <E>() => Pipe<E, Uint8Array, ServerSentEvent>
  * const api = new HttpClient({
  *   baseUrl: "https://api.example.com",
  *   interceptors: [authInterceptor],
- *   defaultHeaders: { "Accept": "application/json" },
  *   timeout: 5000,
  * });
  *
- * const users = api.get<User[]>("/users");
+ * const users = api.get<User[]>("/users");                        // IO<HttpError, User[]>
+ * const avatar = api.get<Avatar>("/me/avatar", { empty: "option" }); // IO<HttpError, Option<Avatar>>
+ * const leave = api.send("POST", `/communities/${slug}/leave`);    // IO<HttpError, void>
  */
 export declare class HttpClient {
     private readonly interceptors;
@@ -67,81 +82,105 @@ export declare class HttpClient {
      */
     constructor(config?: HttpClientConfig);
     /**
-     * Performs a GET request.
+     * Performs a GET request and decodes the body.
      *
-     * @template A - The expected type of the response body.
+     * @template A - The type of the decoded body.
      * @param {string} uri - The URL or path to request.
-     * @param {Omit<Options<A>, "body">} [options] - Request options (excluding body).
-     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     * @param {Options<A>} [options] - Request options; `{ empty: "option" }` yields `Option<A>`.
+     * @returns {IO<HttpError, A>} The decoded body.
      */
-    get(uri: string, options: Omit<Options, "body"> & {
-        observe: "response";
-    }): IO<HttpError, Response>;
-    get<A = unknown>(uri: string, options?: Omit<Options<A>, "body">): IO<HttpError, A | null>;
+    get<A = unknown>(uri: string, options: Omit<OptionalBody<A>, "body">): IO<HttpError, Option_2<NonNullable<A>>>;
+    get<A = unknown>(uri: string, options?: Omit<RequiredBody<A>, "body">): IO<HttpError, A>;
     /**
-     * Performs a POST request.
+     * Performs a POST request and decodes the body.
      *
-     * @template A - The expected type of the response body.
+     * @template A - The type of the decoded body.
      * @param {string} uri - The URL or path to request.
      * @param {unknown} [body] - The request payload.
-     * @param {Options<A>} [options] - Request options.
-     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     * @param {Options<A>} [options] - Request options; `{ empty: "option" }` yields `Option<A>`.
+     * @returns {IO<HttpError, A>} The decoded body.
      */
-    post(uri: string, body: unknown, options: Options & {
-        observe: "response";
-    }): IO<HttpError, Response>;
-    post<A = unknown>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;
+    post<A = unknown>(uri: string, body: unknown, options: OptionalBody<A>): IO<HttpError, Option_2<NonNullable<A>>>;
+    post<A = unknown>(uri: string, body?: unknown, options?: RequiredBody<A>): IO<HttpError, A>;
     /**
-     * Performs a PUT request.
+     * Performs a PUT request and decodes the body.
      *
-     * @template A - The expected type of the response body.
+     * @template A - The type of the decoded body.
      * @param {string} uri - The URL or path to request.
      * @param {unknown} [body] - The request payload.
-     * @param {Options<A>} [options] - Request options.
-     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     * @param {Options<A>} [options] - Request options; `{ empty: "option" }` yields `Option<A>`.
+     * @returns {IO<HttpError, A>} The decoded body.
      */
-    put(uri: string, body: unknown, options: Options & {
-        observe: "response";
-    }): IO<HttpError, Response>;
-    put<A = unknown>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;
+    put<A = unknown>(uri: string, body: unknown, options: OptionalBody<A>): IO<HttpError, Option_2<NonNullable<A>>>;
+    put<A = unknown>(uri: string, body?: unknown, options?: RequiredBody<A>): IO<HttpError, A>;
     /**
-     * Performs a PATCH request.
+     * Performs a PATCH request and decodes the body.
      *
-     * @template A - The expected type of the response body.
+     * @template A - The type of the decoded body.
      * @param {string} uri - The URL or path to request.
      * @param {unknown} [body] - The request payload.
-     * @param {Options<A>} [options] - Request options.
-     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     * @param {Options<A>} [options] - Request options; `{ empty: "option" }` yields `Option<A>`.
+     * @returns {IO<HttpError, A>} The decoded body.
      */
-    patch(uri: string, body: unknown, options: Options & {
-        observe: "response";
-    }): IO<HttpError, Response>;
-    patch<A = unknown>(uri: string, body?: unknown, options?: Options<A>): IO<HttpError, A | null>;
+    patch<A = unknown>(uri: string, body: unknown, options: OptionalBody<A>): IO<HttpError, Option_2<NonNullable<A>>>;
+    patch<A = unknown>(uri: string, body?: unknown, options?: RequiredBody<A>): IO<HttpError, A>;
     /**
-     * Performs a DELETE request.
+     * Performs a DELETE request and decodes the body. For a DELETE that answers `204 No Content`,
+     * use `send("DELETE", uri)` instead.
      *
-     * @template A - The expected type of the response body.
+     * @template A - The type of the decoded body.
      * @param {string} uri - The URL or path to request.
-     * @param {Omit<Options<A>, "body">} [options] - Request options (excluding body).
-     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     * @param {Options<A>} [options] - Request options; `{ empty: "option" }` yields `Option<A>`.
+     * @returns {IO<HttpError, A>} The decoded body.
      */
-    delete(uri: string, options: Omit<Options, "body"> & {
-        observe: "response";
-    }): IO<HttpError, Response>;
-    delete<A = unknown>(uri: string, options?: Omit<Options<A>, "body">): IO<HttpError, A | null>;
+    delete<A = unknown>(uri: string, options: Omit<OptionalBody<A>, "body">): IO<HttpError, Option_2<NonNullable<A>>>;
+    delete<A = unknown>(uri: string, options?: Omit<RequiredBody<A>, "body">): IO<HttpError, A>;
     /**
-     * Performs a custom HTTP request with the specified method.
+     * Performs a request with any method and decodes the body.
      *
-     * @template A - The expected type of the response body.
+     * @template A - The type of the decoded body.
      * @param {string} uri - The URL or path to request.
      * @param {Method} method - The HTTP method.
-     * @param {Options<A>} [options] - Request options.
-     * @returns {IO<HttpError, A | null>} An IO representing the result.
+     * @param {Options<A>} [options] - Request options, including `body`; `{ empty: "option" }` yields `Option<A>`.
+     * @returns {IO<HttpError, A>} The decoded body.
+     */
+    fetch<A = unknown>(uri: string, method: Method, options: OptionalBody<A>): IO<HttpError, Option_2<NonNullable<A>>>;
+    fetch<A = unknown>(uri: string, method: Method, options?: RequiredBody<A>): IO<HttpError, A>;
+    /**
+     * Performs a request whose response body you do not need — an action such as publish,
+     * archive or leave. Succeeds with `void` for any 2xx, with or without a body (which is
+     * discarded); a non-2xx response fails with `kind: "response"` and its body.
+     *
+     * @param {Method} method - The HTTP method.
+     * @param {string} uri - The URL or path to request.
+     * @param {SendOptions} [options] - Headers, credentials, timeout and body. Every key must be one of
+     *   `SendOptions`: a payload passed here by mistake (`send("POST", url, article)`) is rejected at
+     *   compile time; it belongs in `{ body: article }`. A `GET` or `HEAD` request with a body throws
+     *   `TypeError` where it is built.
+     * @returns {IO<HttpError, void>}
+     *
+     * @example
+     * client.send("POST", `/api/v1/communities/${slug}/leave`);
+     * client.send("PUT", `/api/v1/articles/${id}`, { body: article });
+     * client.send("DELETE", `/api/v1/passkeys/${id}`, { headers: { "X-Step-Up": token } });
      */
-    fetch(uri: string, method: Method, options: Options & {
-        observe: "response";
-    }): IO<HttpError, Response>;
-    fetch<A = unknown>(uri: string, method: Method, options?: Options<A>): IO<HttpError, A | null>;
+    send<O extends SendOptions>(method: Method, uri: string, options?: Exact<O, SendOptions>): IO<HttpError, void>;
+    /**
+     * Performs a request and yields the `Response` itself, for status codes, headers or streaming.
+     * A non-2xx response still fails with `kind: "response"` (its body read into the error); a 2xx
+     * `Response` is returned unread. When you only need the status or headers, cancel the body
+     * (`response.body?.cancel()`) so the connection is released; `send` does this for you.
+     *
+     * @param {Method} method - The HTTP method.
+     * @param {string} uri - The URL or path to request.
+     * @param {SendOptions} [options] - Headers, credentials, timeout and body; every key must be one of
+     *   `SendOptions`, as for `send`.
+     * @returns {IO<HttpError, Response>}
+     *
+     * @example
+     * client.raw("POST", "/api/v1/communities", { body: input }).map((r) => r.headers.get("Location"));
+     */
+    raw<O extends SendOptions>(method: Method, uri: string, options?: Exact<O, SendOptions>): IO<HttpError, Response>;
     /**
      * Opens a server-sent-events stream and emits each {@link ServerSentEvent} as it arrives.
      *
@@ -158,13 +197,17 @@ export declare class HttpClient {
      * @param {string} uri - The URL or path to connect to.
      * @param {SseOptions} [options] - Headers, credentials, and reconnection settings.
      * @returns {Stream<HttpError, ServerSentEvent>} A stream of parsed events.
+     * @throws {RangeError} If `options.retry` is negative or `NaN`.
      *
      * @example
      * const events = client.sse("/events", { headers: { Authorization: `Bearer ${token}` } });
-     * await events.runForEach((event) => IO.lift(() => handle(event))).unsafeRun();
+     * await events.runForEach((event) => IO.sync(() => handle(event))).unsafeRun();
      */
     sse(uri: string, options?: SseOptions): Stream<HttpError, ServerSentEvent>;
     private resolveUrl;
+    /** Prepares the request, runs it through the interceptors and `fetch`, and yields the `Response`. */
+    private exchange;
+    private withTimeout;
     private request;
 }
 
@@ -172,13 +215,18 @@ export declare class HttpClient {
  * Configuration for creating an HttpClient instance.
  */
 export declare type HttpClientConfig = {
-    /** Base URL prepended to relative paths. */
+    /**
+     * Prepended to relative paths by string concatenation with exactly one `/` between them, so the
+     * base's own path is kept: `baseUrl: "https://h/api"` and `"/v1/x"` give `https://h/api/v1/x`
+     * (`new URL("/v1/x", base)` would drop `/api`). A `uri` with a scheme (`https://…`, `data:`,
+     * `blob:`) is used as is.
+     */
     baseUrl?: string;
     /** Interceptors applied in registration order (first registered = outermost). Immutable after construction. */
     interceptors?: HttpInterceptor[];
     /** Default headers merged into every request. Per-request headers take precedence. */
     defaultHeaders?: Record<string, string>;
-    /** Default timeout in milliseconds for all requests. Can be overridden per-request. */
+    /** Default timeout in milliseconds for all requests; none by default. Can be overridden per-request. */
     timeout?: number;
     /** Default credentials policy. Defaults to `"same-origin"` (matches the platform `fetch` default). */
     credentials?: Credentials;
@@ -193,7 +241,12 @@ export declare type HttpClientConfig = {
  *
  * `kind` tells the two facts apart that `status` alone cannot: "the server said 500" is
  * `kind: "response", status: 500`, while "nothing answered" is `kind: "network", status: 0`.
- * For every kind other than `"response"`, `status` is `0` and `body` is `null`.
+ * For every kind other than `"response"` and `"decode"`, `status` is `0`; `body` is `null` except
+ * for `"response"`.
+ *
+ * `body`, `headers` and `url` hold what the server and the request contained, which may be sensitive
+ * (a token in a query string, an error page echoing input); redact them before logging an error
+ * outside a trusted sink. `Set-Cookie` is never carried.
  *
  * @example
  * client.post("/payments", payment).mapErr((error) =>
@@ -205,7 +258,7 @@ export declare type HttpClientConfig = {
 export declare class HttpError extends Error {
     /** The transport outcome. See {@link HttpErrorKind}. */
     readonly kind: HttpErrorKind;
-    /** The HTTP status code, or `0` when no response arrived (`kind !== "response"`). */
+    /** The HTTP status code (`"response"` and `"decode"`), or `0` when no response arrived. */
     readonly status: number;
     readonly rawMessage: string;
     /** The parsed response body, or `null` when none was parsed. */
@@ -233,6 +286,16 @@ export declare class HttpError extends Error {
      * @param {number} after The timeout in milliseconds.
      */
     static timeout(url: string, after: number): HttpError;
+    /**
+     * An error for a 2xx response whose body could not be used: it failed to parse, a `transform`
+     * threw, or there was no body where one was expected. `status` is the real status, `body` is
+     * `null`, and `cause` carries the underlying error.
+     *
+     * @param {string} url The request URL.
+     * @param {Response} response The response that could not be decoded.
+     * @param {unknown} cause The parse error, the value a `transform` threw, or a description.
+     */
+    static decode(url: string, response: Response, cause: unknown): HttpError;
     /**
      * An error for a request that could not be built, so nothing was sent — typically a body that
      * could not be serialized. `status` is `0` and `body` is `null`.
@@ -269,75 +332,122 @@ export declare class HttpError extends Error {
      *   (e) => `${e.code}: ${e.message}`
      * );
      */
-    bodyAs<T>(guard: (x: unknown) => x is T): Option_2<T>;
+    bodyAs<T>(guard: (x: unknown) => x is T): Option_2<NonNullable<T>>;
 }
 
 /**
  * How a request failed.
  * - `"request"`: the request could not be built — typically the body could not be serialized.
  *   Nothing was sent.
- * - `"response"`: the server answered with a non-2xx status, or a 2xx whose body could not be parsed.
+ * - `"response"`: the server answered with a non-2xx status. `body` carries what it sent.
+ * - `"decode"`: the server answered 2xx, but the body could not be used — it failed to parse, a
+ *   `transform` threw, or there was no body where one was expected (a `204`, say). `status` is the
+ *   real status and `cause` the underlying error.
  * - `"network"`: no response arrived — DNS failure, offline, CORS block, or a rejected interceptor.
  * - `"timeout"`: the client's `timeout` option fired before the response, or its body, completed.
  *   The request may have reached the server.
  * - `"aborted"`: the request was aborted by something other than IO cancellation, such as an
  *   interceptor's own signal (an IO cancelled via `fiber.cancel()` or `IO.timeout` ends as
  *   `Cancelled`, not as an `HttpError`).
+ *
+ * New kinds may be added in a minor release, so give an exhaustive `switch` a `default` branch.
  */
-export declare type HttpErrorKind = "request" | "response" | "network" | "timeout" | "aborted";
+export declare type HttpErrorKind = "request" | "response" | "decode" | "network" | "timeout" | "aborted";
 
 /**
- * An HTTP interceptor that can modify or handle request and response data
- * before and after an outgoing `fetch` call.
+ * An HTTP interceptor that can modify or handle a request before, and its response after, the
+ * outgoing `fetch` call.
  */
 export declare interface HttpInterceptor {
     /**
      * Intercepts an outgoing HTTP request.
      *
-     * Call `next(request)` to continue the chain with the (optionally modified) request.
-     * Return a `Promise<Response>` without calling `next` to short-circuit the request.
+     * Call `next(request)` to continue the chain with the (optionally modified) request — e.g.
+     * `next({ url: request.url, init: { ...request.init, headers } })`. Return a
+     * `Promise<Response>` without calling `next` to short-circuit the request.
      *
-     * @param request - The configuration object for the pending `fetch` call.
+     * Keep `request.init.signal` when building the request you pass on: it is how a timeout or a
+     * cancelled fiber aborts the `fetch`. A request forwarded without it runs to completion in the
+     * background after the IO has already failed or been cancelled.
+     *
+     * @param request - The resolved URL and `fetch` options of the pending request.
      * @param next - Forwards the request to the next interceptor or to `fetch`.
      * @returns A Promise of the resulting `Response`.
      */
-    intercept(request: RequestInit, next: (req: RequestInit) => Promise<Response>): Promise<Response>;
+    intercept(request: InterceptedRequest, next: (request: InterceptedRequest) => Promise<Response>): Promise<Response>;
 }
 
 /**
- * Represents the HTTP method for the request.
+ * A request as seen by an {@link HttpInterceptor}: the resolved URL and the `fetch` options.
+ * `init.headers` is always a `Headers` instance — copy it with `new Headers(request.init.headers)`
+ * (spreading a `Headers` object yields `{}`).
  */
-export declare type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+export declare type InterceptedRequest = {
+    readonly url: string;
+    readonly init: Omit<RequestInit, "headers"> & {
+        readonly headers: Headers;
+    };
+};
 
 /**
- * Specifies how the response should be observed.
- * - `"body"`: Return the response body.
- * - `"response"`: Return the full `Response` object.
+ * Represents the HTTP method for the request. Methods may be added in a minor release, so give an
+ * exhaustive `switch` or a `Record<Method, …>` a fallback.
  */
-export declare type Observe = "body" | "response";
+export declare type Method = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | "HEAD";
+
+/** Options for a request that expects no body back, or `Option` of one. */
+declare type OptionalBody<A> = Options<A> & {
+    empty: "option";
+};
 
 /**
- * Options for configuring an individual HTTP request.
+ * Options for a request whose response body is decoded (`get`, `post`, `put`, `patch`, `delete`,
+ * `fetch`).
  *
- * @template A - The expected type of the response body after transformation.
+ * @template A - The type of the decoded response body.
  */
-export declare type Options<A = unknown> = {
-    /** Custom headers for the request as key-value pairs. */
-    headers?: Record<string, string>;
-    /** The request payload. */
+export declare type Options<A = unknown> = RequestOptions & {
+    /** The request payload (for `fetch`; the other methods take it as an argument). */
     body?: unknown;
-    /** The expected type of the response body. Defaults to `"json"`. */
+    /** How the response body is read. Defaults to `"json"`. */
     responseType?: ResponseType_2;
+    /**
+     * Turns the parsed body into an `A` — a decoder or validator. Called only when there is a body;
+     * a throw fails the request with `kind: "decode"`.
+     */
+    transform?: (data: unknown) => A;
+    /**
+     * What a response without a body means (`204`, `205`, a `HEAD` response, or an empty 2xx under
+     * `responseType: "json"`; under `"text"` an empty body is `""`, not absence):
+     * - `"error"` (default): a value was expected, so it fails with `kind: "decode"`;
+     * - `"option"`: absence is expected, so the request yields `Option<A>` — `None` for no body.
+     *
+     * For requests whose body you never read, use `send()`; to inspect the `Response`, use `raw()`.
+     */
+    empty?: "error" | "option";
+};
+
+/**
+ * Options shared by every request: headers, credentials and timeout.
+ */
+export declare type RequestOptions = {
+    /** Custom headers for the request as key-value pairs. */
+    headers?: Record<string, string>;
     /** The credential policy for the request. Defaults to the client-level setting. */
     credentials?: Credentials;
-    /** Specifies how the response should be observed. Defaults to `"body"`. */
-    observe?: Observe;
-    /** A function to transform the response body into the desired type. */
-    transform?: (data: unknown) => A;
-    /** Per-request timeout in milliseconds. Overrides the client-level timeout. */
+    /**
+     * Per-request timeout in milliseconds. Overrides the client-level timeout. Values above
+     * 2,147,483,647 ms (the `setTimeout` limit), including `Infinity`, are lowered to it; a negative
+     * or `NaN` value throws `RangeError` where the request is built.
+     */
     timeout?: number;
 };
 
+/** Options for a request whose body is required (the default). */
+declare type RequiredBody<A> = Options<A> & {
+    empty?: "error";
+};
+
 /**
  * Specifies the expected response type.
  * - `"json"`: Parse the response as JSON.
@@ -345,14 +455,27 @@ export declare type Options<A = unknown> = {
  * - `"blob"`: Parse the response as a Blob.
  * - `"arrayBuffer"`: Parse the response as an ArrayBuffer.
  * - `"formData"`: Parse the response as FormData.
+ *
+ * Response types may be added in a minor release, so give an exhaustive `switch` or a
+ * `Record<ResponseType, …>` a fallback.
  */
 declare type ResponseType_2 = "json" | "text" | "blob" | "arrayBuffer" | "formData";
 export { ResponseType_2 as ResponseType }
 
+/**
+ * Options for `send` and `raw`: the shared request options plus the payload.
+ */
+export declare type SendOptions = RequestOptions & {
+    /** The request payload. */
+    body?: unknown;
+};
+
 /**
  * A single server-sent event parsed from a text/event-stream response.
  *
- * @property id - The event id, if the server sent an `id:` field. Used to resume a stream.
+ * @property id - The last event id in effect when the event was dispatched — set by the event's
+ *   own `id:` field or by an earlier one, as the spec's `MessageEvent.lastEventId`. Absent until
+ *   the server sends an `id:`; the empty string after the server resets it. Used to resume a stream.
  * @property event - The event type. Defaults to `"message"` when the server sends no `event:` field.
  * @property data - The event payload. Multiple `data:` lines are joined with a newline.
  * @property retry - The reconnection time in milliseconds, if the server sent a `retry:` field.
@@ -377,12 +500,21 @@ export declare type SseOptions = {
      * (network error or a `5xx` status). Terminal `4xx` responses (including auth failures) are not
      * retried. On reconnect the last received event id is sent as `Last-Event-ID`, and the request
      * headers (including `Authorization`) and credentials are re-applied. Defaults to `true`.
+     *
+     * `true` waits `retry` ms (or the server's `retry:` value) before each reconnect, forever. Pass a
+     * `Schedule` for backoff, jitter or a limit on consecutive failed reconnects, e.g.
+     * `Schedule.exponential(1000).maxDelay(30_000).jittered()`; a server `retry:` value still
+     * takes precedence as the delay once received. `maxAttempts` counts connection attempts since the
+     * last delivered event, the connection that delivered it included — `maxAttempts(3)` allows two
+     * reconnects in a row that deliver nothing — and the count resets with every delivered event.
      */
-    reconnect?: boolean;
+    reconnect?: boolean | Schedule;
     /**
      * The delay in milliseconds before reconnecting, used until the server sends a `retry:` value.
      * A server-sent value below 100 ms is raised to 100 ms so a misbehaving server cannot make the
-     * client reconnect in a tight loop. Defaults to `3000`.
+     * client reconnect in a tight loop. Delays above 2,147,483,647 ms (the `setTimeout` limit) are
+     * lowered to it. Must be a non-negative number: `sse()` throws `RangeError` otherwise.
+     * Defaults to `3000`.
      */
     retry?: number;
 };