create-request 1.6.1 → 2.0.0-next.0

package/dist/index.d.cts

@@ -0,0 +1,851 @@
+//#region src/schema.d.ts
+/**
+ * The Standard Schema interface (https://standardschema.dev), version 1.
+ *
+ * Any schema library that implements it — zod (≥ 3.24), valibot (≥ 1.0), arktype (≥ 2.0),
+ * effect/Schema and others — can be passed to `getJson(schema)`, `getData(schema)` and
+ * `getResult(schema)` to validate (and type) the response body without adding a dependency
+ * on any particular library.
+ */
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  /** The Standard Schema properties. */
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  /** The Standard Schema properties interface. */
+  interface Props<Input = unknown, Output = Input> {
+    /** The version number of the standard. */
+    readonly version: 1;
+    /** The vendor name of the schema library. */
+    readonly vendor: string;
+    /** Validates unknown input values. */
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+    /** Inferred types associated with the schema. */
+    readonly types?: Types<Input, Output> | undefined;
+  }
+  /** The result interface of the validate function. */
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  /** The result interface if validation succeeds. */
+  interface SuccessResult<Output> {
+    /** The typed output value. */
+    readonly value: Output;
+    /** The non-existent issues. */
+    readonly issues?: undefined;
+  }
+  /** The result interface if validation fails. */
+  interface FailureResult {
+    /** The issues of failed validation. */
+    readonly issues: readonly Issue[];
+  }
+  /** The issue interface of the failure output. */
+  interface Issue {
+    /** The error message of the issue. */
+    readonly message: string;
+    /** The path of the issue, if any. */
+    readonly path?: readonly (PropertyKey | PathSegment)[] | undefined;
+  }
+  /** The path segment interface of the issue. */
+  interface PathSegment {
+    /** The key representing a path segment. */
+    readonly key: PropertyKey;
+  }
+  /** The Standard Schema types interface. */
+  interface Types<Input = unknown, Output = Input> {
+    /** The input type of the schema. */
+    readonly input: Input;
+    /** The output type of the schema. */
+    readonly output: Output;
+  }
+  /** Infers the input type of a Standard Schema. */
+  type InferInput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+  /** Infers the output type of a Standard Schema. */
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+//#endregion
+//#region src/error.d.ts
+/** Everything a {@link RequestError} can carry besides its message. */
+interface RequestErrorOptions {
+  /** What kind of failure this is — see {@link RequestErrorCode}. */
+  code: RequestErrorCode;
+  /** The URL that was requested (with query string). */
+  url: string;
+  /** The HTTP method that was used. */
+  method: Method;
+  /** HTTP status, when a response was received. */
+  status?: number | undefined;
+  /** The raw `Response`, when one was received. Its body has been read into `body` (unless it was larger than 1 MB). */
+  response?: Response | undefined;
+  /** The response body as text, when one was received and could be read (at most 1 MB). */
+  body?: string | undefined;
+  /** Schema issues, for `"VALIDATION"` errors coming from `getJson(schema)` and friends. */
+  issues?: readonly StandardSchemaV1.Issue[] | undefined;
+  /** The underlying error (what `fetch`, an interceptor or `JSON.parse` threw). */
+  cause?: unknown;
+}
+/**
+ * The single error type thrown by this library. Every rejection from `getResponse()`, `getJson()`, …
+ * is a `RequestError`, so one `instanceof` (or {@link isRequestError}) check is enough, and `code`
+ * tells you what happened.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await api.get("/users/42").getJson<User>();
+ * } catch (error) {
+ *   if (!isRequestError(error)) throw error;
+ *   switch (error.code) {
+ *     case "HTTP":    console.log(error.status, error.data);   break;  // parsed error body
+ *     case "TIMEOUT": console.log("try again later");          break;
+ *     case "ABORTED": break;                                     // the user navigated away
+ *     default:        console.error(error.message, error.cause);
+ *   }
+ * }
+ * ```
+ */
+export declare class RequestError<TData = unknown> extends Error {
+  readonly name = "RequestError";
+  /** What kind of failure this is — see {@link RequestErrorCode}. */
+  readonly code: RequestErrorCode;
+  /** The URL that was requested (with query string). */
+  readonly url: string;
+  /** The HTTP method that was used. */
+  readonly method: Method;
+  /** HTTP status, when a response was received. */
+  readonly status?: number | undefined;
+  /** The raw `Response`, when one was received. Its body has been read into `body` (unless it was larger than 1 MB). */
+  readonly response?: Response | undefined;
+  /** The response body as text, when one was received and could be read (at most 1 MB). */
+  readonly body?: string | undefined;
+  /** Schema issues, for `"VALIDATION"` errors coming from `getJson(schema)` and friends. */
+  readonly issues?: readonly StandardSchemaV1.Issue[] | undefined;
+  private _data?;
+  constructor(message: string, options: RequestErrorOptions);
+  /**
+   * `body` parsed as JSON — the shape most APIs use for error details.
+   * `undefined` when there is no body or it is not valid JSON; never throws.
+   *
+   * @example
+   * ```typescript
+   * catch (error) {
+   *   if (isRequestError(error)) console.log(error.data?.message ?? error.message);
+   * }
+   * ```
+   */
+  get data(): TData | undefined;
+  /** Shorthand for `code === "TIMEOUT"`. */
+  get isTimeout(): boolean;
+  /** Shorthand for `code === "ABORTED"`. */
+  get isAborted(): boolean;
+}
+/** Type guard for {@link RequestError} — handy in `catch (error: unknown)` blocks. */
+export declare const isRequestError: (error: unknown) => error is RequestError;
+//#endregion
+//#region src/types.d.ts
+/** The HTTP methods a request can be created with. */
+type Method = "GET" | "HEAD" | "OPTIONS" | "DELETE" | "POST" | "PUT" | "PATCH";
+/** The HTTP methods that may carry a request body (`withBody` / `withGraphQL` are only available on these). */
+type BodyMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+/** What `fetch` accepts as a body. */
+type FetchBody = NonNullable<RequestInit["body"]>;
+/** `"include"`, `"omit"` or `"same-origin"`. */
+type CredentialsMode = NonNullable<RequestInit["credentials"]>;
+/** `"cors"`, `"no-cors"`, `"same-origin"` or `"navigate"`. */
+type CorsMode = NonNullable<RequestInit["mode"]>;
+/** `"follow"`, `"error"` or `"manual"`. */
+type RedirectMode = NonNullable<RequestInit["redirect"]>;
+/** A referrer policy name (`"no-referrer"`, `"strict-origin-when-cross-origin"`, …). */
+type ReferrerPolicyName = NonNullable<RequestInit["referrerPolicy"]>;
+/** How the HTTP cache is used. */
+type CacheMode = "default" | "force-cache" | "no-cache" | "no-store" | "only-if-cached" | "reload";
+/** A fetch priority hint. */
+type PriorityHint = "auto" | "high" | "low";
+/**
+ * Anything `withBody()` accepts.
+ *
+ * - `string` → sent as-is (`Content-Type: text/plain` unless you set one)
+ * - `Blob` / `File`, `FormData`, `URLSearchParams` → sent as-is, `fetch` sets the matching `Content-Type`
+ * - `ArrayBuffer`, typed arrays, `ReadableStream` → sent as-is, no `Content-Type` unless you set one
+ * - any other JSON-serialisable object or array → `JSON.stringify`-ed (`Content-Type: application/json` unless you set one)
+ *
+ * @example
+ * ```typescript
+ * request.withBody({ name: "Ada" });          // JSON
+ * request.withBody(new FormData(form));       // multipart
+ * request.withBody("id=1&name=Ada");          // text/plain — set withContentType() for form-urlencoded
+ * ```
+ */
+type Body = FetchBody | object;
+/** A single query-string value. Arrays produce repeated keys (`?tag=a&tag=b`); `null`/`undefined` remove the key. */
+type QueryValue = string | number | boolean | Date | null | undefined | readonly (string | number | boolean | Date)[];
+/** Query parameters as a plain object (`{ page: 1, tags: ["a", "b"] }`) or as `URLSearchParams`. */
+type QueryParams = Record<string, QueryValue> | URLSearchParams;
+/** Headers as a plain object. `null`/`undefined` unsets the header (useful to drop an api-level default). */
+type HeadersRecord = Record<string, string | number | null | undefined>;
+/** Cookies as a plain object of `name → value`. Values are sent verbatim (no encoding). */
+type CookiesRecord = Record<string, string>;
+/** A fetch-compatible function: receives the final URL and `RequestInit` and returns a `Response`. */
+type FetchFunction = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * Discriminates the kind of failure a {@link RequestError} represents.
+ *
+ * - `"HTTP"` — the server answered with a non-2xx status (`status`, `response`, `body`, `data` are set)
+ * - `"NETWORK"` — `fetch` itself rejected: DNS, connection refused, CORS, offline, a relative URL in Node.js
+ *   (`cause` is the original error)
+ * - `"TIMEOUT"` — the `withTimeout()` deadline passed, or a signal aborted with a `TimeoutError` (`AbortSignal.timeout()`)
+ * - `"ABORTED"` — a signal passed with `withSignal()` / `withAbortController()` was aborted
+ * - `"PARSE"` — the body could not be read or parsed (invalid JSON, body already consumed, selector threw)
+ * - `"VALIDATION"` — the response did not match the schema passed to `getJson(schema)` (`issues` is set),
+ *   or the request could not be built: an empty or unparsable absolute URL, an invalid header, timeout,
+ *   retries or body (those last three are thrown synchronously by the `with*` method)
+ * - `"INTERCEPTOR"` — an interceptor or callback (retry, CSRF token) threw (`cause` is what it threw)
+ * - `"GRAPHQL"` — the GraphQL response contained `errors` and `throwOnError` was enabled
+ */
+type RequestErrorCode = "HTTP" | "NETWORK" | "TIMEOUT" | "ABORTED" | "PARSE" | "VALIDATION" | "INTERCEPTOR" | "GRAPHQL";
+/** What a retry decision or delay function receives. */
+interface RetryContext {
+  /** The retry about to happen, starting at 1 (so `attempt === 1` follows the first failure). */
+  attempt: number;
+  /** The error that triggered this retry. */
+  error: RequestError;
+}
+/**
+ * Configuration for automatic retries — see `withRetries()`.
+ *
+ * By default a request is retried after a network error, a timeout, or a response with status
+ * 408, 425, 429, 500, 502, 503 or 504, with exponential backoff (300 ms, 600 ms, 1.2 s, … plus
+ * up to 100 ms of jitter, capped at `maxDelay`). A `Retry-After` header is honoured when present.
+ * Aborted requests and requests with a `ReadableStream` body are never retried, whatever the policy.
+ *
+ * @example
+ * ```typescript
+ * request.withRetries(3);                                        // 3 retries, default policy
+ * request.withRetries({ attempts: 3, delay: 1000 });             // fixed 1 s delay
+ * request.withRetries({ attempts: 5, methods: ["GET", "HEAD"] });  // idempotent methods only
+ * request.withRetries({
+ *   attempts: 3,
+ *   delay: ({ attempt }) => attempt * 500,
+ *   shouldRetry: ({ error }) => error.code === "HTTP" && error.status === 503,
+ *   onRetry: ({ attempt, delay }) => console.log(`retry #${attempt} in ${delay}ms`),
+ * });
+ * ```
+ */
+interface RetryConfig {
+  /** Number of retries after the first attempt (`3` means up to 4 requests in total). */
+  attempts: number;
+  /**
+   * Delay before each retry, in milliseconds, or a function computing it.
+   * When set, it takes precedence over a `Retry-After` header. Default: exponential backoff.
+   */
+  delay?: number | ((context: RetryContext) => number) | undefined;
+  /** Statuses that are retried. Default: `[408, 425, 429, 500, 502, 503, 504]`. Network errors and timeouts are retried by default. */
+  statuses?: readonly number[] | undefined;
+  /** Methods that are retried. Default: all. Use `["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]` to retry idempotent requests only. */
+  methods?: readonly Method[] | undefined;
+  /**
+   * Upper bound, in milliseconds, for the default backoff. A `Retry-After` header longer than this
+   * cancels the retry so you can react to it yourself. Default: `30000`.
+   */
+  maxDelay?: number | undefined;
+  /** Full override of the retry decision (`statuses` and `methods` are ignored). Aborts and stream bodies still never retry. */
+  shouldRetry?: ((context: RetryContext) => boolean | Promise<boolean>) | undefined;
+  /** Called before every retry, after the delay has been computed. Awaited if it returns a promise. */
+  onRetry?: ((context: RetryContext & {
+    delay: number;
+  }) => void | Promise<void>) | undefined;
+}
+/**
+ * The request as it is about to be sent, handed to request interceptors.
+ *
+ * `headers` keys are lower-case; `body` is already serialised (JSON bodies are strings);
+ * `signal` combines the signals passed with `withSignal()` (the timeout is added after interceptors ran).
+ * Mutate it in place or return a new object; return a `Response` to skip the network entirely.
+ */
+interface RequestConfig extends Omit<RequestInit, "headers" | "body" | "method" | "signal" | "window"> {
+  /** The final URL, with the query string and, for api requests, the base URL applied. */
+  url: string;
+  /** The HTTP method. */
+  method: Method;
+  /** The headers to send, with lower-case names. The CSRF header (`withCsrf()`) is added after interceptors ran. */
+  headers: Record<string, string>;
+  /** The serialised body: JSON bodies are already strings. */
+  body?: FetchBody | null | undefined;
+  /** The signals passed with `withSignal()` / `withAbortController()`, combined. The timeout is added after interceptors ran. */
+  signal?: AbortSignal | undefined;
+  /** Required by browsers and Node for `ReadableStream` bodies; set automatically. */
+  duplex?: "half";
+}
+/**
+ * Runs before the request is sent. Return nothing to keep your in-place changes, a new
+ * {@link RequestConfig} to replace it, or a `Response` to short-circuit the request
+ * (it is then treated like a fetched response: status is checked, response interceptors run —
+ * but `withTimeout()` does not apply to it, since nothing was fetched).
+ *
+ * @example
+ * ```typescript
+ * const withTraceId: RequestInterceptor = config => {
+ *   config.headers["x-trace-id"] = crypto.randomUUID();
+ * };
+ * ```
+ */
+type RequestInterceptor = (config: RequestConfig) => RequestConfig | Response | void | Promise<RequestConfig | Response | void>;
+/**
+ * Runs after a successful response (before the body is read), with the request that produced it.
+ * Return nothing to keep the response or another {@link ResponseWrapper} to replace it.
+ *
+ * @example
+ * ```typescript
+ * const logStatus: ResponseInterceptor = (response, request) => {
+ *   console.log(request.method, response.url, response.status);
+ * };
+ * ```
+ */
+type ResponseInterceptor = (response: ResponseWrapper, request: HttpRequest) => ResponseWrapper | void | Promise<ResponseWrapper | void>;
+/**
+ * Runs once when the request has failed for good (after all retries), with the request that failed.
+ * Return nothing to keep the error, another {@link RequestError} to replace it, or a
+ * {@link ResponseWrapper} to recover — typically by replaying `request.clone()`. Throwing replaces the error as well.
+ *
+ * @example
+ * ```typescript
+ * const replayed = new WeakSet<HttpRequest>();
+ * const refreshOn401: ErrorInterceptor = async (error, request) => {
+ *   if (error.status !== 401 || replayed.has(request)) return;
+ *   token = await refreshToken();          // the request interceptor that adds the token reads it
+ *   const retry = request.clone();
+ *   replayed.add(retry);                   // never loop on a persistent 401
+ *   return retry.getResponse();
+ * };
+ * ```
+ */
+type ErrorInterceptor = (error: RequestError, request: HttpRequest) => RequestError | ResponseWrapper | void | Promise<RequestError | ResponseWrapper | void>;
+/** Options for `withGraphQL()`. */
+interface GraphQLOptions {
+  /** Throw a `RequestError` with code `"GRAPHQL"` when the response contains a non-empty `errors` array. Default: `false`. */
+  throwOnError?: boolean | undefined;
+}
+/**
+ * Options for `withCsrf()`.
+ *
+ * The token is attached only to same-origin requests (evaluated against the final URL, after
+ * interceptors, before any redirect) unless `crossOrigin` is set. Outside a browser there is no
+ * page origin and every request counts as same-origin.
+ */
+interface CsrfOptions {
+  /** Cookie to read the token from (browser only). Default: `"XSRF-TOKEN"`. Ignored when `token` is set. */
+  cookie?: string | undefined;
+  /** Header the token is sent in. Default: `"X-XSRF-TOKEN"` when read from a cookie, `"X-CSRF-Token"` when `token` is set. */
+  header?: string | undefined;
+  /** A token, or a function returning one per request (return `null`/`undefined` to send nothing). */
+  token?: string | (() => string | null | undefined) | undefined;
+  /** Also attach the token to cross-origin URLs. Default: `false`. */
+  crossOrigin?: boolean | undefined;
+}
+/** What `getResult()` resolves to: `error` is `null` on success and the {@link RequestError} otherwise (then `data` is `null`). */
+type RequestResult<T> = {
+  data: T;
+  error: null;
+} | {
+  data: null;
+  error: RequestError;
+};
+//#endregion
+//#region src/response.d.ts
+/**
+ * A successful response. Exposes the status line and headers, and reads the body in the format you
+ * ask for. The body is buffered once, so you can call several readers, in any order and concurrently
+ * (`getJson()` after `getText()`, `Promise.all([res.getJson(), res.getBlob()])`, …) — except
+ * `getBody()`, which hands you the live stream and therefore excludes the others.
+ *
+ * `T` is the JSON type declared at the request (`api.get<User>()`) and is the default for `getJson()` / `getData()`.
+ *
+ * @example
+ * ```typescript
+ * const res = await api.get<User>("/me").getResponse();
+ * console.log(res.status, res.headers.get("etag"));
+ * const user = await res.getJson();   // User
+ * ```
+ */
+export declare class ResponseWrapper<T = unknown> {
+  /** The underlying `Response`. Read its body through this wrapper's methods, or take it over with `getBody()`. */
+  readonly raw: Response;
+  /** The URL that was requested, including the query string (after interceptors). */
+  readonly url: string;
+  /** The HTTP method that was used. */
+  readonly method: Method;
+  private _bin?;
+  private _text?;
+  private _json?;
+  /** Wraps a `Response` — useful to hand a synthetic response to an error interceptor. */
+  constructor(
+  /** The underlying `Response`. Read its body through this wrapper's methods, or take it over with `getBody()`. */
+  raw: Response,
+  /** The URL that was requested, including the query string (after interceptors). */
+  url?: string,
+  /** The HTTP method that was used. */
+  method?: Method);
+  /** HTTP status code (`200`, `404`, …). */
+  get status(): number;
+  /** HTTP status text (`"OK"`, `"Not Found"`, …); empty over HTTP/2. */
+  get statusText(): string;
+  /** Whether the status is in the 200–299 range. */
+  get ok(): boolean;
+  /** Response headers. */
+  get headers(): Headers;
+  private _err;
+  /** The error for a body that cannot be read: TIMEOUT / ABORTED when the deadline or a signal fired, otherwise PARSE with `fallback`. */
+  private _unreadable;
+  private _buffer;
+  private _validate;
+  /** The body as an `ArrayBuffer`. */
+  getArrayBuffer(): Promise<ArrayBuffer>;
+  /** The body as a `Blob`, typed with the response's `Content-Type`. */
+  getBlob(): Promise<Blob>;
+  /** The body decoded as UTF-8 text (`""` for an empty body). */
+  getText(): Promise<string>;
+  /** The body parsed as `multipart/form-data` or `application/x-www-form-urlencoded`. */
+  getFormData(): Promise<FormData>;
+  /**
+   * The raw body stream, for streaming consumption (downloads with progress, SSE/NDJSON, LLM output…).
+   * Unlike the other readers it is not buffered: the body can be read once, and only if no other reader ran.
+   * Taking the stream also ends the request's `withTimeout()` deadline — from here on the stream is yours.
+   *
+   * @example
+   * ```typescript
+   * const reader = (await request.getBody())!.pipeThrough(new TextDecoderStream()).getReader();
+   * for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) process(chunk.value);
+   * ```
+   */
+  getBody(): ReadableStream<Uint8Array> | null;
+  /**
+   * The body parsed as JSON. An empty body (`204`, `Content-Length: 0`, whitespace) yields `null` —
+   * declare it in the type (`getJson<User | null>()`) for endpoints that may return nothing.
+   *
+   * Pass a [Standard Schema](https://standardschema.dev) (zod, valibot, arktype, …) to validate the body
+   * and infer its type; a mismatch rejects with a `RequestError` whose `code` is `"VALIDATION"` and
+   * whose `issues` lists what went wrong.
+   *
+   * @example
+   * ```typescript
+   * const user = await res.getJson<User>();
+   * const user = await res.getJson(UserSchema);   // typed from the schema, validated at runtime
+   * ```
+   */
+  getJson<U = T>(): Promise<U>;
+  getJson<S extends StandardSchemaV1>(schema: S): Promise<StandardSchemaV1.InferOutput<S>>;
+  /**
+   * `getJson()` followed by a selector, so you can pick the part you need in one call. The selector
+   * receives `T` (declare it on the request: `api.get<Page>()`), or pass both type arguments explicitly.
+   * Errors thrown by the selector are reported as a `RequestError` with code `"PARSE"`. A schema can be validated first.
+   *
+   * @example
+   * ```typescript
+   * const names = await res.getData(page => page.users.map(u => u.name));      // res: ResponseWrapper<Page>
+   * const names = await res.getData<Page, string[]>(page => page.users.map(u => u.name));
+   * const names = await res.getData(PageSchema, page => page.users.map(u => u.name));
+   * ```
+   */
+  getData<U = T>(): Promise<U>;
+  getData<S extends StandardSchemaV1>(schema: S): Promise<StandardSchemaV1.InferOutput<S>>;
+  getData<S extends StandardSchemaV1, R>(schema: S, selector: (data: StandardSchemaV1.InferOutput<S>) => R): Promise<R>;
+  getData<R>(selector: (data: T) => R): Promise<R>;
+  getData<U, R>(selector: (data: U) => R): Promise<R>;
+}
+//#endregion
+//#region src/request.d.ts
+/**
+ * A request under construction. Configure it with the `with*` methods (each returns the same request,
+ * so calls chain), then execute it with one of the `get*` methods. Nothing is sent until you execute.
+ *
+ * `M` is the HTTP method — `withBody()` and `withGraphQL()` only exist for methods that carry a body —
+ * and `T` is the JSON type the response is expected to have (`api.get<User>("/me")`), used as the
+ * default for `getJson()` / `getData()` / `getResult()`.
+ *
+ * Create requests with `create.get(url)`, `create.post(url)`, … or through an api instance; the class
+ * is exported for type annotations and `instanceof` checks.
+ *
+ * @example
+ * ```typescript
+ * const user = await create
+ *   .post("https://api.example.com/users")
+ *   .withBearerToken(token)
+ *   .withBody({ name: "Ada" })
+ *   .withTimeout(5000)
+ *   .withRetries(2)
+ *   .getJson<User>();
+ * ```
+ */
+export declare class HttpRequest<M extends Method = Method, T = unknown> {
+  /** The HTTP method. */
+  readonly method: M;
+  private readonly _url;
+  /** Prefer `create.get(url)`, `create.post(url)`, … or an api instance to construct requests. */
+  constructor(
+  /** The HTTP method. */
+  method: M, url: string);
+  /** The URL this request will be sent to, including the query string. */
+  get url(): string;
+  private _fail;
+  private _set;
+  /**
+   * Sets several headers at once. Names are case-insensitive (stored lower-case); a `null` or `undefined`
+   * value removes the header, which is how a request drops a default set on its api.
+   *
+   * @example
+   * ```typescript
+   * request.withHeaders({ Accept: "application/json", "X-Request-Id": id });
+   * api.get("/public").withHeaders({ Authorization: null });   // send this one unauthenticated
+   * ```
+   */
+  withHeaders<H extends { [K in keyof H]: string | number | null | undefined; }>(headers: H): this;
+  /** Sets one header — see {@link withHeaders}. */
+  withHeader(name: string, value: string | number | null | undefined): this;
+  /**
+   * Sets the `Content-Type` header. Rarely needed: JSON and text bodies set it automatically and
+   * `FormData` / `Blob` bodies must leave it to `fetch` (it adds the multipart boundary).
+   */
+  withContentType(contentType: string): this;
+  /** Sets the `Authorization` header verbatim (`"Bearer …"`, `"Basic …"`, a custom scheme). */
+  withAuthorization(value: string): this;
+  /** Sets `Authorization: Bearer <token>`. */
+  withBearerToken(token: string): this;
+  /** Sets `Authorization: Basic <base64(username:password)>` (UTF-8 safe). */
+  withBasicAuth(username: string, password: string): this;
+  /**
+   * Adds cookies to the `Cookie` header. Names and values are sent verbatim — encode them yourself if
+   * needed, and never pass untrusted values (a `;` would smuggle in another cookie). **Node.js /
+   * server-side only**: browsers ignore a `Cookie` header on `fetch` and send their own cookies
+   * instead — use `withCredentials("include")` there.
+   */
+  withCookies<C extends { [K in keyof C]: string; }>(cookies: C): this;
+  /** Adds one cookie — see {@link withCookies}. */
+  withCookie(name: string, value: string): this;
+  /**
+   * Enables CSRF protection: a token is attached to requests whose URL (final, after interceptors) is
+   * same-origin with the page, so it is not sent to third-party hosts. By default the token is read
+   * from the `XSRF-TOKEN` cookie and sent as `X-XSRF-TOKEN` — the convention of Angular, Laravel and
+   * Spring. See {@link CsrfOptions} for other setups.
+   *
+   * Two limits of that guarantee: the check happens before `fetch` runs, so a same-origin URL that
+   * *redirects* to another origin still carries the header (`fetch` only strips `Authorization` on
+   * cross-origin redirects) — use `withRedirect("error")` for endpoints that may redirect elsewhere;
+   * and outside a browser there is no page origin, so every URL counts as same-origin.
+   *
+   * @example
+   * ```typescript
+   * api.withCsrf();                                                     // XSRF-TOKEN cookie → X-XSRF-TOKEN
+   * api.withCsrf({ cookie: "csrftoken", header: "X-CSRFToken" });       // Django
+   * api.withCsrf({ token: () => document.querySelector("meta[name=csrf-token]")?.getAttribute("content") }); // Rails
+   * ```
+   */
+  withCsrf(options?: CsrfOptions): this;
+  /**
+   * Sends a CSRF token you already hold in the given header (default `X-CSRF-Token`) — with every request,
+   * whatever its origin. It is a plain header; prefer {@link withCsrf} (`{ token }`) to keep the same-origin check.
+   */
+  withCsrfToken(token: string, header?: string): this;
+  /**
+   * Sets query parameters. A key that is already present is replaced (so a request can override an
+   * api-level default); arrays produce repeated keys, `Date`s are sent as ISO strings, and
+   * `null` / `undefined` remove the key. Accepts a `URLSearchParams` too.
+   *
+   * @example
+   * ```typescript
+   * request.withQueryParams({ page: 2, tags: ["a", "b"], since: new Date() });
+   * // ?page=2&tags=a&tags=b&since=2026-01-01T00%3A00%3A00.000Z
+   * ```
+   */
+  withQueryParams<P extends { [K in keyof P]: QueryValue; }>(params: P | URLSearchParams): this;
+  /** Sets one query parameter — see {@link withQueryParams}. */
+  withQueryParam(key: string, value: QueryValue): this;
+  /**
+   * Fails the request with code `"TIMEOUT"` if it has not completed — response received *and* body read —
+   * within `ms` milliseconds. The clock starts after request interceptors ran and applies to each attempt
+   * when retries are enabled; `getBody()` ends the deadline and hands you the stream. It does not cover
+   * a `Response` returned by a request interceptor (nothing was fetched).
+   * `0`, `Infinity` or anything above 2^31 − 1 ms (≈ 24.8 days, the limit of `setTimeout`) remove a
+   * timeout set earlier (for instance by an api instance).
+   */
+  withTimeout(ms: number): this;
+  /**
+   * Retries failed requests. Pass a number of retries for the default policy (network errors, timeouts,
+   * 408/425/429/500/502/503/504, exponential backoff, `Retry-After` honoured) or a {@link RetryConfig}
+   * to tune it. Calling it again merges with the previous configuration.
+   */
+  withRetries(retries: number | RetryConfig): this;
+  /** Called before every retry — shorthand for `withRetries({ onRetry })`. It does not enable retries by itself. */
+  onRetry(callback: RetryConfig["onRetry"]): this;
+  /**
+   * Cancels the request when `signal` aborts (error code `"ABORTED"`). Call it several times to
+   * combine signals — for instance the one your data-fetching library hands you and your own.
+   *
+   * @example
+   * ```typescript
+   * useQuery({ queryKey: ["user", id], queryFn: ({ signal }) => api.get(`/users/${id}`).withSignal(signal).getJson<User>() });
+   * ```
+   */
+  withSignal(signal: AbortSignal): this;
+  /** Cancels the request when `controller.abort()` is called — shorthand for `withSignal(controller.signal)`. */
+  withAbortController(controller: AbortController): this;
+  /**
+   * Uses `fetchFn` instead of the global `fetch`: inject a stub in tests, an undici `Agent` or proxy in
+   * Node.js, or a framework's patched fetch (Next.js caching options). It receives the final URL and
+   * `RequestInit` and must honour `init.signal` for timeouts and cancellation to work.
+   *
+   * @example
+   * ```typescript
+   * request.withFetch(async () => new Response('{"ok":true}'));                       // test stub
+   * request.withFetch((url, init) => undiciFetch(url, { ...init, dispatcher: agent })); // undici agent
+   * request.withFetch((url, init) => fetch(url, { ...init, next: { revalidate: 60 } })); // Next.js
+   * ```
+   */
+  withFetch(fetchFn: FetchFunction): this;
+  /** Whether cookies and auth headers are sent cross-origin: `"include"`, `"omit"` or `"same-origin"` (browser default). */
+  withCredentials(credentials: CredentialsMode): this;
+  /** CORS mode: `"cors"` (default), `"no-cors"` (opaque response, status 0 — not treated as an error) or `"same-origin"`. */
+  withMode(mode: CorsMode): this;
+  /**
+   * Redirect handling: `"follow"` (default), `"error"` (rejects with a network error) or `"manual"`, which
+   * resolves with the redirect itself — an opaque response (status 0) in browsers, the actual 3xx in Node.js.
+   */
+  withRedirect(redirect: RedirectMode): this;
+  /** The `Referer` to send (browser): a URL, `""` to send none, or `"about:client"` for the default. */
+  withReferrer(referrer: string): this;
+  /** How much referrer information the browser includes (`"no-referrer"`, `"strict-origin-when-cross-origin"`, …). */
+  withReferrerPolicy(policy: ReferrerPolicyName): this;
+  /** Priority hint for the browser's scheduler: `"high"`, `"low"` or `"auto"`. */
+  withPriority(priority: PriorityHint): this;
+  /** Lets the request outlive the page (analytics beacons, ≤ 64 KB body). */
+  withKeepAlive(keepalive?: boolean): this;
+  /** Subresource-integrity hash the response must match, e.g. `"sha256-…"`. */
+  withIntegrity(integrity: string): this;
+  /** How the browser's HTTP cache is used: `"default"`, `"no-store"`, `"reload"`, `"no-cache"`, `"force-cache"` or `"only-if-cached"`. */
+  withCache(cache: CacheMode): this;
+  /** Adds a {@link RequestInterceptor}. Api-level interceptors run first, then request-level ones, in registration order. */
+  withRequestInterceptor(interceptor: RequestInterceptor): this;
+  /** Adds a {@link ResponseInterceptor}, run after every successful response in registration order (it also receives the request). */
+  withResponseInterceptor(interceptor: ResponseInterceptor): this;
+  /** Adds an {@link ErrorInterceptor}, run once after the request has failed for good (after retries); it also receives the request, so it can replay it. */
+  withErrorInterceptor(interceptor: ErrorInterceptor): this;
+  /**
+   * Sets the request body (POST, PUT, PATCH and DELETE only — a compile error elsewhere). Objects and
+   * arrays are JSON-encoded; strings, `Blob`, `FormData`, `URLSearchParams`, `ArrayBuffer`, typed arrays
+   * and `ReadableStream` are sent as-is. `Content-Type` is set to `application/json` / `text/plain`
+   * unless already present, and removed for `FormData` (fetch must add the multipart boundary itself).
+   * Stream bodies are sent with `duplex: "half"` (Chromium and Node.js only) and are never retried.
+   *
+   * @example
+   * ```typescript
+   * create.post(url).withBody({ name: "Ada" });
+   * create.put(url).withBody(new FormData(form));
+   * ```
+   */
+  withBody(this: HttpRequest<BodyMethod, T>, body: Body): this;
+  /**
+   * Sends a GraphQL operation as a JSON body (`{ query, variables }`). With `throwOnError`, a response
+   * whose `errors` array is non-empty rejects `getJson()` with a `RequestError` of code `"GRAPHQL"`.
+   *
+   * @example
+   * ```typescript
+   * const { user } = await create
+   *   .post<{ data: { user: User } }>("/graphql")
+   *   .withGraphQL("query ($id: ID!) { user(id: $id) { name } }", { id }, { throwOnError: true })
+   *   .getData(r => r.data);
+   * ```
+   */
+  withGraphQL(this: HttpRequest<BodyMethod, T>, query: string, variables?: object, options?: GraphQLOptions): this;
+  /**
+   * An independent copy of this request, so a configured request can serve as a template.
+   * Interceptors, signals and body objects are shared by reference (a `ReadableStream` body can only be sent once).
+   *
+   * @example
+   * ```typescript
+   * const search = api.get("/search").withTimeout(2000);
+   * const page1 = search.clone().withQueryParam("page", 1).getJson();
+   * const page2 = search.clone().withQueryParam("page", 2).getJson();
+   * ```
+   */
+  clone(): HttpRequest<M, T>;
+  /**
+   * Sends the request (with retries, if configured) and resolves with the {@link ResponseWrapper} of a
+   * successful (2xx or opaque) response. Any failure — non-2xx status, network error, timeout, abort,
+   * interceptor error — rejects with a {@link RequestError}; use `getResult()` for a non-throwing variant.
+   */
+  getResponse(): Promise<ResponseWrapper<T>>;
+  private _retriable;
+  private _attempt;
+  /** Attaches the CSRF token (see {@link withCsrf}) to `config.headers` when the final URL qualifies. */
+  private _csrf;
+  /**
+   * Sends the request and parses the body as JSON — see {@link ResponseWrapper.getJson} for the empty-body
+   * rule and schema validation.
+   *
+   * @example
+   * ```typescript
+   * const users = await api.get("/users").getJson<User[]>();
+   * const user = await api.get("/me").getJson(UserSchema);   // validated + typed by the schema
+   * ```
+   */
+  getJson<U = T>(): Promise<U>;
+  getJson<S extends StandardSchemaV1>(schema: S): Promise<StandardSchemaV1.InferOutput<S>>;
+  /** Sends the request and returns the body as text. */
+  getText(): Promise<string>;
+  /** Sends the request and returns the body as a `Blob` (downloads, images). */
+  getBlob(): Promise<Blob>;
+  /** Sends the request and returns the body as an `ArrayBuffer`. */
+  getArrayBuffer(): Promise<ArrayBuffer>;
+  /** Sends the request and parses the body as `FormData`. */
+  getFormData(): Promise<FormData>;
+  /** Sends the request and returns the raw body stream — see {@link ResponseWrapper.getBody}. */
+  getBody(): Promise<ReadableStream<Uint8Array> | null>;
+  /**
+   * Sends the request, parses JSON and applies a selector — see {@link ResponseWrapper.getData}.
+   *
+   * @example
+   * ```typescript
+   * const names = await api.get<Page<User>>("/users").getData(page => page.items.map(u => u.name));
+   * ```
+   */
+  getData<U = T>(): Promise<U>;
+  getData<S extends StandardSchemaV1>(schema: S): Promise<StandardSchemaV1.InferOutput<S>>;
+  getData<S extends StandardSchemaV1, R>(schema: S, selector: (data: StandardSchemaV1.InferOutput<S>) => R): Promise<R>;
+  getData<R>(selector: (data: T) => R): Promise<R>;
+  getData<U, R>(selector: (data: U) => R): Promise<R>;
+  /**
+   * Sends the request and resolves with `{ data, error }` instead of throwing — for code that prefers
+   * errors as values. `error` is the same {@link RequestError} `getJson()` would have thrown.
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await api.get("/me").getResult<User>();
+   * if (error) return showError(error.message);
+   * render(data);
+   * ```
+   */
+  getResult<U = T>(): Promise<RequestResult<U>>;
+  getResult<S extends StandardSchemaV1>(schema: S): Promise<RequestResult<StandardSchemaV1.InferOutput<S>>>;
+}
+//#endregion
+//#region src/api.d.ts
+/** Chainable `HttpRequest` methods that make sense as api-wide defaults (everything but body, signal and clone). */
+type ApiKeys = Exclude<{ [K in keyof HttpRequest]: K extends `with${string}` | "onRetry" ? K : never; }[keyof HttpRequest], "withBody" | "withGraphQL" | "withSignal" | "withAbortController">;
+type ApiChainables = { [K in keyof HttpRequest as K extends ApiKeys ? K : never]: HttpRequest[K] extends ((...args: infer A) => unknown) ? (...args: A) => ApiBuilder : never; };
+/**
+ * A set of defaults for the requests it creates: base URL, headers, auth, timeout, retries, interceptors —
+ * every `with*` method of {@link HttpRequest} except the body and signal ones, with the same signatures.
+ *
+ * Api instances are **immutable**: each `with*` call returns a new instance and leaves the original
+ * untouched, so an api can be specialised safely (`const admin = api.withHeader("X-Role", "admin")`).
+ * Requests created from it can still override any default. Arguments are applied to every request the
+ * api creates (an object passed to `withHeaders` is read each time, so treat it as frozen).
+ *
+ * @example
+ * ```typescript
+ * export const api = createApi()
+ *   .withBaseURL("https://api.example.com")
+ *   .withBearerToken(token)
+ *   .withTimeout(5000)
+ *   .withRetries(2);
+ *
+ * const users = await api.get("/users").getJson<User[]>();
+ * const user = await api.post("/users").withBody({ name: "Ada" }).getJson<User>();
+ * ```
+ */
+interface ApiBuilder extends ApiChainables {
+  withHeaders<H extends { [K in keyof H]: string | number | null | undefined; }>(headers: H): ApiBuilder;
+  withCookies<C extends { [K in keyof C]: string; }>(cookies: C): ApiBuilder;
+  withQueryParams<P extends { [K in keyof P]: QueryValue; }>(params: P | URLSearchParams): ApiBuilder;
+  /**
+   * Prefixes relative paths with `baseURL`. Paths are *joined*, not resolved: `/v1` + `/users` → `/v1/users`,
+   * `./users` and `users` work the same, and absolute URLs (`https://…`, `//…`) are used as-is.
+   */
+  withBaseURL(baseURL: string): ApiBuilder;
+  /** Creates a GET request. `T` declares the JSON type the response is expected to have. */
+  get<T = unknown>(path?: string): HttpRequest<"GET", T>;
+  /** Creates a HEAD request. */
+  head<T = unknown>(path?: string): HttpRequest<"HEAD", T>;
+  /** Creates an OPTIONS request. */
+  options<T = unknown>(path?: string): HttpRequest<"OPTIONS", T>;
+  /** Creates a POST request. */
+  post<T = unknown>(path?: string): HttpRequest<"POST", T>;
+  /** Creates a PUT request. */
+  put<T = unknown>(path?: string): HttpRequest<"PUT", T>;
+  /** Creates a PATCH request. */
+  patch<T = unknown>(path?: string): HttpRequest<"PATCH", T>;
+  /** Creates a DELETE request (`del` is an alias). */
+  delete<T = unknown>(path?: string): HttpRequest<"DELETE", T>;
+  /** Alias of `delete`. */
+  del<T = unknown>(path?: string): HttpRequest<"DELETE", T>;
+}
+/**
+ * Creates an empty {@link ApiBuilder}. Configure it once, export it, and create every request through it.
+ * (`create.api()` is the same function.)
+ */
+export declare function createApi(): ApiBuilder;
+//#endregion
+//#region src/index.d.ts
+/** A GET request. */
+export type GetRequest<T = unknown> = HttpRequest<"GET", T>;
+/** A HEAD request. */
+export type HeadRequest<T = unknown> = HttpRequest<"HEAD", T>;
+/** An OPTIONS request. */
+export type OptionsRequest<T = unknown> = HttpRequest<"OPTIONS", T>;
+/** A POST request. */
+export type PostRequest<T = unknown> = HttpRequest<"POST", T>;
+/** A PUT request. */
+export type PutRequest<T = unknown> = HttpRequest<"PUT", T>;
+/** A PATCH request. */
+export type PatchRequest<T = unknown> = HttpRequest<"PATCH", T>;
+/** A DELETE request. */
+export type DeleteRequest<T = unknown> = HttpRequest<"DELETE", T>;
+/** Any request — the v1 name for {@link HttpRequest}. */
+export type BaseRequest<T = unknown> = HttpRequest<Method, T>;
+/** Any request that may carry a body — the v1 name for `HttpRequest<"POST" | "PUT" | "PATCH" | "DELETE">`. */
+export type BodyRequest<T = unknown> = HttpRequest<BodyMethod, T>;
+/** Creates a GET request. `T` declares the JSON type the response is expected to have. */
+export declare const createGet: <T = unknown>(url: string) => GetRequest<T>;
+/** Creates a HEAD request. */
+export declare const createHead: <T = unknown>(url: string) => HeadRequest<T>;
+/** Creates an OPTIONS request. */
+export declare const createOptions: <T = unknown>(url: string) => OptionsRequest<T>;
+/** Creates a POST request. */
+export declare const createPost: <T = unknown>(url: string) => PostRequest<T>;
+/** Creates a PUT request. */
+export declare const createPut: <T = unknown>(url: string) => PutRequest<T>;
+/** Creates a PATCH request. */
+export declare const createPatch: <T = unknown>(url: string) => PatchRequest<T>;
+/** Creates a DELETE request. */
+export declare const createDelete: <T = unknown>(url: string) => DeleteRequest<T>;
+/**
+ * The entry point: one factory per HTTP method plus `api()` for configured instances.
+ *
+ * @example
+ * ```typescript
+ * import create from "create-request";
+ *
+ * const users = await create.get("https://api.example.com/users").getJson<User[]>();
+ * const api = create.api().withBaseURL("https://api.example.com").withBearerToken(token);
+ * const me = await api.get("/me").getJson<User>();
+ * ```
+ */
+declare const create: {
+  /** Creates a GET request. `T` declares the JSON type the response is expected to have. */
+  readonly get: <T = unknown>(url: string) => GetRequest<T>;
+  /** Creates a HEAD request. */
+  readonly head: <T = unknown>(url: string) => HeadRequest<T>;
+  /** Creates an OPTIONS request. */
+  readonly options: <T = unknown>(url: string) => OptionsRequest<T>;
+  /** Creates a POST request. */
+  readonly post: <T = unknown>(url: string) => PostRequest<T>;
+  /** Creates a PUT request. */
+  readonly put: <T = unknown>(url: string) => PutRequest<T>;
+  /** Creates a PATCH request. */
+  readonly patch: <T = unknown>(url: string) => PatchRequest<T>;
+  /** Creates a DELETE request. */
+  readonly delete: <T = unknown>(url: string) => DeleteRequest<T>;
+  /** Alias of `delete`. */
+  readonly del: <T = unknown>(url: string) => DeleteRequest<T>;
+  /** Creates an api instance — see {@link createApi}. */
+  readonly api: typeof createApi;
+};
+//#endregion
+export { type ApiBuilder, type Body, type BodyMethod, type CookiesRecord, type CsrfOptions, type ErrorInterceptor, type FetchFunction, type GraphQLOptions, type HeadersRecord, type Method, type QueryParams, type QueryValue, type RequestConfig, type RequestErrorCode, type RequestErrorOptions, type RequestInterceptor, type RequestResult, type ResponseInterceptor, type RetryConfig, type RetryContext, type StandardSchemaV1, create as default };