API Client

Requirements

• Export createApiClient(baseUrl, options = {}) as a named and default function. baseUrl is an absolute HTTP(S) URL with an optional path prefix. options accepts headers (a Record<string, string>) and fetcher (a fetch-compatible function); use global fetch when fetcher is omitted.
• The client exposes get(path), post(path), put(path), and delete(path). Each returns a builder with query(params), headers(values), body(value), signal(abortSignal), and send(). A builder method returns a new independent builder, preserving the original; no builder method performs a request.
• Join the base URL and relative path with one slash while preserving the base path prefix. A leading slash on path does not discard that prefix. Existing query parameters in path must be preserved unless query(params) replaces the same name.
• query accepts own enumerable string keys with string, number, boolean, null, or undefined values. Convert defined values to strings and encode them with URLSearchParams. Null and undefined are omitted. Repeated query calls merge values; later defined values replace earlier values. Arrays and nested query values are outside scope.
• Merge shared and request headers case-insensitively, with the latest value winning. Snapshot configuration and builder inputs when their method is called so later caller mutation cannot alter a request. Send headers using the Headers API or an equivalent case-insensitive representation.
• body(value) serializes a JSON-serializable value immediately with JSON.stringify. Reject body() on GET with TypeError. When a body is present, add Content-Type: application/json only if no content type was already specified. DELETE bodies are allowed.
• signal(signal) forwards the same AbortSignal in RequestInit. send() calls the selected fetcher once with the URL string and request options. Each send is independent; a builder can be sent more than once without losing its configuration.
• On an ok response, return parsed response.json(), except status 204 which resolves to undefined without parsing. On a non-ok response, reject with an Error named ApiError carrying the numeric status. Network, abort, and JSON parsing errors propagate unchanged.
• In TypeScript define typed client and builder interfaces. send<T = unknown>() returns Promise<T | undefined>. Do not falsely infer a response shape from the URL. Retry logic, auth refresh, timeouts, non-JSON bodies, streaming, and caching are outside scope.

Examples

Input: createApiClient("https://api.example.test/v1").get("/users").query({ page: 2 }).send()
Output: Fetches https://api.example.test/v1/users?page=2 with method GET.

Input: client.post("users").body({ name: "Ada" }).send()
Output: Sends serialized JSON with a default JSON content type and returns parsed response JSON.

Input: const base = client.get("users"); const page2 = base.query({ page: 2 })
Output: base stays unchanged; page2 is independently configured.