1000fetches 0.2.2 → 0.3.0

package/README.md

@@ -22,7 +22,7 @@ or heavy Axios-style clients that add weight without type guarantees.
 
 ### The idea
 
-A type-first HTTP client that unifies validation, retries, streaming, and middleware on top of native `fetch`.
+A type-first HTTP client that unifies validation, dynamic defaults, retries, and middleware on top of native `fetch`.
 
 ---
 
@@ -30,9 +30,9 @@ A type-first HTTP client that unifies validation, retries, streaming, and middle
 
 - 🧭 **Compile-time path safety** — `:pathParam` can't slip through undefined
 - 🧩 **Schema-driven validation** — infer types at build time, verify data at runtime
-- ⚡ **Streaming telemetry** — observe upload/download chunks and progress as data flows
+- ⚙️ **Dynamic defaults** — resolve auth, params, timeouts, and fetch options per request
 - 🔁 **Retries, timeouts, middleware** — production essentials with opt-ins
-- 🎯 **Method-based API** — `api.get()` with schema validation `.schema()` and extractor `.data()` for clean and concise code
+- 🎯 **Method-based API** — `api.get()` with response contracts `.contract()` and extractor `.data()` for clean and concise code
 - 🧠 **Designed for flow** — clear API, predictable behavior, no hidden magic
 
 ---
@@ -59,12 +59,12 @@ const userSchema = z.object({
   email: z.email(),
 })
 
-// Request data with schema validation
+// Request data with a response contract
 const userResponse = await api
   .get('/users/:id', {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
 // userResponse.data 👉 { id: number, ... }
 
 // Clean data extraction with full type safety
@@ -72,28 +72,13 @@ const user = await api
   .get('/users/:id', {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // user 👉 { id: number, ... }
 ```
 
-**Or use the shortcut client for quick requests with absolute URLs:**
-
-```ts
-import http from '1000fetches/http'
-
-const user = await http
-  .get('https://api.example.com/users/:id', {
-    pathParams: { id: '123' },
-  })
-  .schema(userSchema)
-  .data()
-```
-
 With native Node `fetch`, requests must resolve to absolute URLs. Use an absolute `baseUrl` in Node, or provide a custom `fetch` implementation that supports relative URLs.
 
-The `1000fetches/http` subpath intentionally exports only this default client. Use `1000fetches` when you need named exports like `createHttpClient` or error classes.
-
 ## ➡️ Key Features
 
 ### ✔️ Type Safety That Actually Works
@@ -109,16 +94,16 @@ The `1000fetches/http` subpath intentionally exports only this default client. U
 - **Smart retry logic** — Opt-in exponential backoff for resilient requests
 - **Timeout and cancellation support** — Built-in `AbortController` integration
 - **Structured error handling** — `HttpError`, `NetworkError`, `TimeoutError` with full context
-- **Request/Response middleware** — Authentication, logging, transformations
+- **Dynamic defaults and middleware** — Authentication, logging, transformations
 - **Minimalistic footprint** — Production features without the bloat
 
 ### ✔️ Engineer-Friendly DX
 
 - **Method-based API** — `api.get()`, `api.post()`, `api.put()`, `api.patch()`, `api.delete()`, and generic `api.request()` with full type safety
-- **Schema-first validation** — Chain `.schema()` for runtime validation and automatic type inference
+- **Contract-first validation** — Chain `.contract()` for runtime validation and automatic type inference
 - **Smart data extraction** — Chain `.data()` for direct value access without `.data` property
 - **Automatic response parsing** — JSON/text responses parsed automatically
-- **Chunk telemetry** — Observe upload/download chunks and byte progress
+- **Per-request defaults** — Resolve auth, params, timeouts, retry settings, and fetch options from request context
 - **Tiny runtime footprint** — one tiny Standard Schema type dependency, tree-shakable builds
 - **TypeScript-first** — Full type inference and `IntelliSense` support
 
@@ -137,43 +122,52 @@ const api = createHttpClient({
 // Or dynamic auth
 const api = createHttpClient({
   baseUrl: 'https://api.example.com',
-  onRequestMiddleware: async context => {
+  defaults: async () => {
     const token = await getToken()
-    context.headers.set('Authorization', `Bearer ${token}`)
-    return context
+    return {
+      headers: { Authorization: `Bearer ${token}` },
+    }
   },
 })
 ```
 
-### Streaming
+### Dynamic Defaults
 
 ```ts
-// Upload progress with actual data chunks
-await api.post('/api/files', fileData, {
-  onUploadStreaming: ({ chunk, transferredBytes, totalBytes }) => {
-    const progress = totalBytes
-      ? `${Math.round((transferredBytes / totalBytes) * 100)}%`
-      : `${transferredBytes} bytes`
-    console.log(`Uploading: ${progress} - chunk size: ${chunk.length} bytes`)
-  },
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  defaults: ({ resolvedPath, method }) => ({
+    headers: { 'X-Client': 'dashboard' },
+    timeout: resolvedPath.startsWith('/reports') ? 60_000 : 10_000,
+    retry: method === 'GET',
+    params: { locale: 'en-US' },
+  }),
 })
+```
 
-// Download progress
-await api.get('/api/files/:id', {
-  pathParams: { id: '123' },
-  onDownloadStreaming: ({ chunk, transferredBytes, totalBytes }) => {
-    const progress = totalBytes
-      ? `${Math.round((transferredBytes / totalBytes) * 100)}%`
-      : `${transferredBytes} bytes`
-    console.log(`Downloading: ${progress} - chunk size: ${chunk.length} bytes`)
+### Middleware
+
+```ts
+const api = createHttpClient({
+  baseUrl: 'https://api.example.com',
+  onRequestMiddleware: context => {
+    console.log(`→ ${context.method} ${context.url}`)
+    return context
+  },
+  onResponseMiddleware: response => {
+    console.log(`← ${response.status} ${response.method} ${response.url}`)
+    return response
   },
 })
 ```
 
+Middleware can observe requests and responses, but it can also mutate them. Keep middleware side-effect-light; use mutation only when dynamic defaults are not enough.
+
 ### Error Handling
 
 ```ts
 import {
+  AbortError,
   HttpError,
   NetworkError,
   TimeoutError,
@@ -187,7 +181,7 @@ try {
     .get('/users/:id', {
       pathParams: { id: '123' },
     })
-    .schema(userSchema)
+    .contract(userSchema)
 } catch (error) {
   if (error instanceof HttpError) {
     console.log(`HTTP ${error.status}: ${error.statusText}`)
@@ -195,6 +189,8 @@ try {
     console.log('Network error:', error.message)
   } else if (error instanceof TimeoutError) {
     console.log('Request timed out')
+  } else if (error instanceof AbortError) {
+    console.log('Request was cancelled')
   } else if (error instanceof MiddlewareError) {
     console.log('Middleware error:', error.message)
   } else if (error instanceof PathParameterError) {
@@ -217,19 +213,23 @@ function createHttpClient(config?: HttpClientConfig)
 
 **Configuration Options:**
 
-| Option                 | Type                                                                     | Description                        |
-| ---------------------- | ------------------------------------------------------------------------ | ---------------------------------- |
-| `baseUrl`              | `string`                                                                 | Absolute or root-relative base URL |
-| `headers`              | `Record<string, string>`                                                 | Default headers                    |
-| `timeout`              | `number`                                                                 | Default timeout in milliseconds    |
-| `retry`                | `RetryOptions \| boolean`                                                | Opt-in retry configuration         |
-| `onRequestMiddleware`  | `(context: RequestContext) => RequestContext \| Promise<RequestContext>` | Request middleware                 |
-| `onResponseMiddleware` | `(response: ResponseType) => ResponseType \| Promise<ResponseType>`      | Response middleware                |
-| `schemaValidator`      | `SchemaValidator`                                                        | Custom schema validator            |
+| Option                 | Type                                                                                     | Description                        |
+| ---------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------- |
+| `baseUrl`              | `string`                                                                                 | Absolute or root-relative base URL |
+| `headers`              | `Record<string, string>`                                                                 | Default headers                    |
+| `timeout`              | `number`                                                                                 | Default timeout in milliseconds    |
+| `retry`                | `RetryOptions \| boolean`                                                                | Opt-in retry configuration         |
+| `fetch`                | `typeof fetch`                                                                           | Custom fetch-compatible transport  |
+| `serializeBody`        | `(body: TBody) => BodyInit \| null \| undefined`                                         | Custom request body serializer     |
+| `serializeParams`      | `(params) => string`                                                                     | Custom query parameter serializer  |
+| `defaults`             | `(context) => RequestDefaults \| void \| Promise<RequestDefaults \| void>`               | Dynamic request defaults           |
+| `onRequestMiddleware`  | `(context: RequestContext) => RequestContext \| void \| Promise<RequestContext \| void>` | Request middleware                 |
+| `onResponseMiddleware` | `(response: ResponseType) => ResponseType \| Promise<ResponseType>`                      | Response middleware                |
+| `schemaValidator`      | `SchemaValidator`                                                                        | Custom schema validator            |
 
 ### <samp>HTTP Methods</samp>
 
-All HTTP methods support schema validation and data extraction:
+All HTTP methods support response contracts and data extraction:
 
 ```ts
 // GET
@@ -237,12 +237,12 @@ const user = await api
   .get('/users/:id', {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // user 👉 Fully typed user object
 
 // POST
-const newUser = await api.post('/users', userData).schema(userSchema).data()
+const newUser = await api.post('/users', userData).contract(userSchema).data()
 // newUser 👉 Fully typed user object
 
 // PUT
@@ -250,7 +250,7 @@ const updatedUser = await api
   .put('/users/:id', userData, {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // updatedUser 👉 Fully typed user object
 
@@ -259,7 +259,7 @@ const patchedUser = await api
   .patch('/users/:id', partialData, {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // patchedUser 👉 Fully typed user object
 
@@ -271,27 +271,25 @@ await api.delete('/users/:id', {
 
 ### <samp>Request Options</samp>
 
-| Option                | Type                                                        | Description                       |
-| --------------------- | ----------------------------------------------------------- | --------------------------------- |
-| `pathParams`          | `Record<string, string \| number \| undefined>`             | Path parameters for URL templates |
-| `params`              | `RequestParamsType`                                         | Query parameters                  |
-| `headers`             | `Record<string, string>`                                    | Request headers                   |
-| `body`                | `TBody`                                                     | Request body                      |
-| `timeout`             | `number`                                                    | Request timeout                   |
-| `signal`              | `AbortSignal`                                               | Request cancellation signal       |
-| `responseType`        | `'json' \| 'text' \| 'blob' \| 'arrayBuffer' \| 'formData'` | Response type override            |
-| `cache`               | `RequestCache`                                              | Cache mode                        |
-| `credentials`         | `RequestCredentials`                                        | Credentials mode                  |
-| `mode`                | `RequestMode`                                               | Request mode                      |
-| `redirect`            | `RequestRedirect`                                           | Redirect mode                     |
-| `fetchOptions`        | `FetchOptions`                                              | Native Fetch/Node passthrough     |
-| `retry`               | `RetryOptions \| boolean`                                   | Retry configuration               |
-| `onUploadStreaming`   | `(event: UploadStreamingEvent) => void`                     | Upload streaming callback         |
-| `onDownloadStreaming` | `(event: DownloadStreamingEvent) => void`                   | Download streaming callback       |
+| Option         | Type                                                        | Description                       |
+| -------------- | ----------------------------------------------------------- | --------------------------------- |
+| `pathParams`   | `Record<string, string \| number \| undefined>`             | Path parameters for URL templates |
+| `params`       | `RequestParamsType`                                         | Query parameters                  |
+| `headers`      | `Record<string, string>`                                    | Request headers                   |
+| `body`         | `TBody`                                                     | Request body                      |
+| `timeout`      | `number`                                                    | Request timeout                   |
+| `signal`       | `AbortSignal`                                               | Request cancellation signal       |
+| `responseType` | `'json' \| 'text' \| 'blob' \| 'arrayBuffer' \| 'formData'` | Response type override            |
+| `cache`        | `RequestCache`                                              | Cache mode                        |
+| `credentials`  | `RequestCredentials`                                        | Credentials mode                  |
+| `mode`         | `RequestMode`                                               | Request mode                      |
+| `redirect`     | `RequestRedirect`                                           | Redirect mode                     |
+| `fetchOptions` | `FetchOptions`                                              | Native Fetch/Node passthrough     |
+| `retry`        | `RetryOptions \| boolean`                                   | Retry configuration               |
 
 ### <samp>Retry Options</samp>
 
-Retries are disabled unless you set client `retry`, request `retry: true`, or request retry settings. The built-in policy retries idempotent methods by default (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`), honors `Retry-After`, supports jitter, and never retries one-shot request streams.
+Retries are disabled unless you set client `retry`, request `retry: true`, or request retry settings. The built-in policy retries idempotent methods by default (`GET`, `HEAD`, `OPTIONS`, `PUT`, `DELETE`), honors `Retry-After`, supports jitter, and never retries one-shot `ReadableStream` request bodies.
 
 ```ts
 const api = createHttpClient({
@@ -306,6 +304,21 @@ const api = createHttpClient({
 })
 ```
 
+### <samp>Status and Empty Responses</samp>
+
+By default, 1000fetches treats any 2xx response as successful. Declare valid non-2xx protocol flows, such as `304 Not Modified`, in response contracts.
+
+Responses that cannot carry a body (`204`, `205`, `304`, and `HEAD`) resolve with `data: undefined` without attempting JSON parsing.
+
+```ts
+const response = await api.get('/cached-resource').contract({
+  success: {
+    default: CachedResourceSchema,
+    304: z.undefined(),
+  },
+})
+```
+
 ### <samp>Response Object</samp>
 
 All requests return a `ResponseType<T>` object:
@@ -322,32 +335,52 @@ interface ResponseType<T> {
 }
 ```
 
-### <samp>Schema Validation</samp>
+### <samp>Response Contracts</samp>
 
-The library provides a chainable API for schema validation:
+The library provides a chainable API for response contracts:
 
 ```ts
-// Without schema
+// Without contract
 const response = await api.get('/users/:id', {
   pathParams: { id: '123' },
 })
 // response 👉 ResponseType<unknown>
 
-// With schema
+// With a schema contract
 const response = await api
   .get('/users/:id', {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
 // response 👉 ResponseType<User>
 ```
 
+Contracts can also describe success and error bodies by status:
+
+```ts
+await api.post('/transactions', transactionInput).contract({
+  success: {
+    default: CreatedTransactionSchema,
+    201: EmptyResponseSchema,
+  },
+  error: {
+    default: ErrorSchema,
+    400: BadTransactionResponseSchema,
+    409: AlreadyCreatedTransactionResponseSchema,
+  },
+})
+```
+
+Success status maps accept only `2xx` and `3xx` status keys. Error status maps accept only `4xx` and `5xx` status keys. Success map status keys control which non-2xx responses resolve; error contracts validate failed responses before `HttpError` is thrown.
+
+Error branches validate failed HTTP responses before throwing `HttpError` with the validated error data. If an error response fails its own contract, 1000fetches throws `ContractValidationError` with the status, method, URL, response, schema, and original data.
+
 ### <samp>Data Extraction</samp>
 
 The method-based API provides clean data extraction with full type safety:
 
 ```ts
-// Extract untyped data (without schema)
+// Extract untyped data (without contract)
 const data = await api
   .get('/users/:id', {
     pathParams: { id: '123' },
@@ -355,22 +388,22 @@ const data = await api
   .data()
 // data 👉 unknown
 
-// Direct typed data extraction (with schema)
+// Direct typed data extraction (with contract)
 const user = await api
   .get('/users/:id', {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // user 👉 { id: number, ... }
 
 // Works with all HTTP methods
-const newUser = await api.post('/users', userData).schema(userSchema).data()
+const newUser = await api.post('/users', userData).contract(userSchema).data()
 // newUser 👉 Fully typed user object
 
 const updatedUser = await api
   .put('/users/:id', userData, { pathParams: { id: '123' } })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // updatedUser 👉 Fully typed user object
 
@@ -389,9 +422,9 @@ await api.delete('/users/:id', { pathParams: { id: '123' } }).void()
 | **Schema Validation** | Standard Schema support for Zod, Valibot, ArkType, and more           |
 | **Retry Logic**       | Opt-in retry policy with backoff, jitter, and `Retry-After`           |
 | **Error Handling**    | Structured errors for HTTP, network, timeout, and validation failures |
+| **Dynamic Defaults**  | Per-request headers, params, timeout, retry, and fetch options        |
 | **Middleware**        | Request and response middleware with typed context                    |
-| **Streaming**         | Upload/download chunk telemetry through callback hooks                |
-| **Tree Shaking**      | Side-effect-free ESM/CJS builds with a default-only `./http` shortcut |
+| **Tree Shaking**      | Side-effect-free ESM/CJS builds                                       |
 
 ---
 

package/dist/client/index.d.ts

@@ -0,0 +1,23 @@
+import { HttpClientConfig, HttpRequestOptions } from '../core';
+import { ContractableResponse, EnforcedPathParamsOptions, RequestParamsType } from '../types';
+import { AssertSupportedPath, HasRequiredParams, RequirePathParams } from '../utils';
+type PathOptionsArgs<Path extends string, TOptions> = [
+    AssertSupportedPath<Path>
+] extends [never] ? [options: never] : HasRequiredParams<AssertSupportedPath<Path>> extends true ? [options: TOptions] : [options?: TOptions];
+type EnforcedHttpRequestOptions<TBody, TParams extends RequestParamsType, Path extends string> = RequirePathParams<AssertSupportedPath<Path>, string extends Path ? HttpRequestOptions<TBody, TParams> : Omit<HttpRequestOptions<TBody, TParams>, 'pathParams'>>;
+/**
+ * Creates a complete HTTP client with method builders
+ */
+export declare function createHttpClient<TSerializedBody = unknown>(config?: HttpClientConfig<TSerializedBody>): {
+    get: <Path extends string = string, TParams extends RequestParamsType = RequestParamsType>(url: Path, ...args: PathOptionsArgs<Path, EnforcedPathParamsOptions<never, TParams, Path>>) => ContractableResponse<unknown>;
+    post: <Path extends string = string, TBody extends TSerializedBody = TSerializedBody, TParams extends RequestParamsType = RequestParamsType>(url: Path, body?: TBody, ...args: PathOptionsArgs<Path, EnforcedPathParamsOptions<TBody, TParams, Path>>) => ContractableResponse<unknown>;
+    put: <Path extends string = string, TBody extends TSerializedBody = TSerializedBody, TParams extends RequestParamsType = RequestParamsType>(url: Path, body?: TBody, ...args: PathOptionsArgs<Path, EnforcedPathParamsOptions<TBody, TParams, Path>>) => ContractableResponse<unknown>;
+    patch: <Path extends string = string, TBody extends TSerializedBody = TSerializedBody, TParams extends RequestParamsType = RequestParamsType>(url: Path, body?: TBody, ...args: PathOptionsArgs<Path, EnforcedPathParamsOptions<TBody, TParams, Path>>) => ContractableResponse<unknown>;
+    delete: <Path extends string = string, TParams extends RequestParamsType = RequestParamsType>(url: Path, ...args: PathOptionsArgs<Path, EnforcedPathParamsOptions<never, TParams, Path>>) => ContractableResponse<unknown>;
+    /**
+     * Generic request method for custom HTTP methods and full control
+     */
+    request: <Path extends string = string, TBody extends TSerializedBody = TSerializedBody, TParams extends RequestParamsType = RequestParamsType>(url: Path, ...args: PathOptionsArgs<Path, EnforcedHttpRequestOptions<TBody, TParams, Path>>) => ContractableResponse<unknown>;
+};
+export type HttpClient = ReturnType<typeof createHttpClient>;
+export {};

package/dist/contract/index.d.ts

@@ -0,0 +1,6 @@
+import { HttpRequestOptions } from '../core';
+import { SchemaValidator } from '../schema';
+import { InferContractSuccess, RequestParamsType, ResponseContract, ResponseType } from '../types';
+export declare function validateResponseContractShape(contract: ResponseContract): void;
+export declare function createContractRequestOptions<TBody, TParams extends RequestParamsType>(options: HttpRequestOptions<TBody, TParams>, contract: ResponseContract): HttpRequestOptions<TBody, TParams>;
+export declare function validateResponsePromiseWithContract<C extends ResponseContract>(contract: C, responsePromise: Promise<ResponseType<unknown>>, schemaValidator: SchemaValidator): Promise<ResponseType<InferContractSuccess<C>>>;

package/dist/core.d.ts

@@ -1,5 +1,5 @@
 import { SchemaValidator } from './schema';
-import { CustomFetch, DownloadStreamingEvent, FetchOptions, HttpHeaders, HttpMethod, RequestContext, RequestParamsType, ResponseType, RetryOptions, SerializeBody, SerializeParams, UploadStreamingEvent } from './types';
+import { CustomFetch, FetchOptions, HttpHeaders, HttpMethod, RequestContext, RequestParamsType, ResponseType, RetryOptions, SerializeBody, SerializeParams } from './types';
 export interface HttpRequestOptions<TBody = unknown, TParams extends RequestParamsType = RequestParamsType> {
     method?: HttpMethod;
     headers?: HttpHeaders;
@@ -18,16 +18,40 @@ export interface HttpRequestOptions<TBody = unknown, TParams extends RequestPara
     redirect?: RequestRedirect;
     /** Additional Fetch/Node options passed through to the underlying fetch call */
     fetchOptions?: FetchOptions;
-    /** Upload streaming tracking for this specific request */
-    onUploadStreaming?: (event: UploadStreamingEvent) => void;
-    /** Download streaming tracking for this specific request */
-    onDownloadStreaming?: (event: DownloadStreamingEvent) => void;
     /** Response type override */
     responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData';
     /** Per-request retry configuration */
     retry?: RetryOptions | boolean;
 }
-export interface HttpClientConfig {
+export interface RequestDefaults {
+    headers?: HttpHeaders;
+    params?: RequestParamsType;
+    timeout?: number;
+    credentials?: RequestCredentials;
+    cache?: RequestCache;
+    mode?: RequestMode;
+    redirect?: RequestRedirect;
+    fetchOptions?: FetchOptions;
+    responseType?: HttpRequestOptions['responseType'];
+    retry?: RetryOptions | boolean;
+}
+export interface RequestDefaultsContext<TBody = unknown, TParams extends RequestParamsType = RequestParamsType, Path extends string = string> {
+    /** Raw path or URL passed by the caller before path parameter generation */
+    path: Path;
+    /** Path after template parameter generation, before baseUrl and query params */
+    resolvedPath: string;
+    method: HttpMethod;
+    params?: TParams;
+    pathParams?: Record<string, string | number | undefined>;
+    body?: TBody;
+    hasBody: boolean;
+    requestOptions: Readonly<HttpRequestOptions<TBody, TParams>>;
+    baseUrl: string;
+    headers: HttpHeaders;
+    timeout: number;
+    retry?: RetryOptions | boolean;
+}
+export interface HttpClientConfig<TSerializedBody = unknown> {
     /** Base URL for all requests */
     baseUrl?: string;
     /** Default headers */
@@ -41,17 +65,19 @@ export interface HttpClientConfig {
     /** Custom fetch implementation */
     fetch?: CustomFetch;
     /** Custom body serializer */
-    serializeBody?: SerializeBody;
+    serializeBody?: SerializeBody<TSerializedBody>;
     /** Custom params serializer */
     serializeParams?: SerializeParams;
+    /** Per-request defaults resolved before request options and middleware */
+    defaults?: <TBody extends TSerializedBody = TSerializedBody, TParams extends RequestParamsType = RequestParamsType, Path extends string = string>(context: RequestDefaultsContext<TBody, TParams, Path>) => RequestDefaults | void | Promise<RequestDefaults | void>;
     /** Request middleware - can modify request before sending */
-    onRequestMiddleware?: <TBody = unknown>(context: RequestContext<TBody>) => RequestContext<TBody> | Promise<RequestContext<TBody>>;
+    onRequestMiddleware?: <TBody = unknown>(context: RequestContext<TBody>) => RequestContext<TBody> | void | Promise<RequestContext<TBody> | void>;
     /** Response middleware - can modify response after receiving */
     onResponseMiddleware?: (response: ResponseType<unknown>) => ResponseType<unknown> | Promise<ResponseType<unknown>>;
 }
 /**
  * Creates an HTTP request handler with the given configuration.
  * This is the core function that handles all HTTP requests with retry logic,
- * interceptors, and streaming.
+ * middleware, serialization, defaults, and timeouts.
  */
-export declare function createHttpRequest(config?: HttpClientConfig): <Path extends string = string, TResponse = unknown, TBody = unknown, TParams extends RequestParamsType = RequestParamsType>(url: Path, options?: HttpRequestOptions<TBody, TParams>) => Promise<ResponseType<TResponse>>;
+export declare function createHttpRequest<TSerializedBody = unknown>(config?: HttpClientConfig<TSerializedBody>): <Path extends string = string, TResponse = unknown, TBody extends TSerializedBody = TSerializedBody, TParams extends RequestParamsType = RequestParamsType>(url: Path, options?: HttpRequestOptions<TBody, TParams>) => Promise<ResponseType<TResponse>>;

package/dist/{errors.d.ts → errors/errors.d.ts}

@@ -22,18 +22,53 @@ export declare class NetworkError extends Error implements HttpClientError {
     constructor(message: string, cause?: Error);
 }
 export declare class SchemaValidationError extends Error implements HttpClientError {
-    readonly name = "SchemaValidationError";
+    readonly name: string;
     readonly schema: unknown;
     readonly data: unknown;
     readonly issues?: ReadonlyArray<StandardSchemaV1.Issue>;
     readonly cause?: Error;
     constructor(message: string, schema: unknown, data: unknown, cause?: Error, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
 }
+export declare class ContractValidationError extends SchemaValidationError {
+    readonly name = "ContractValidationError";
+    readonly branch: 'success' | 'error';
+    readonly status: number;
+    readonly statusText: string;
+    readonly response: Response;
+    readonly url: string;
+    readonly method: string;
+    constructor(message: string, schema: unknown, data: unknown, response: {
+        status: number;
+        statusText: string;
+        raw: Response;
+        url: string;
+        method: string;
+    }, branch: 'success' | 'error', cause?: Error, issues?: ReadonlyArray<StandardSchemaV1.Issue>);
+}
+export declare class InvalidContractError extends Error implements HttpClientError {
+    readonly name = "InvalidContractError";
+    readonly contract: unknown;
+    readonly status?: number;
+    readonly branch?: 'success' | 'error';
+    readonly cause?: Error;
+    constructor(message: string, contract: unknown, status?: number, branch?: 'success' | 'error', cause?: Error);
+}
 export declare class TimeoutError extends Error implements HttpClientError {
     readonly name = "TimeoutError";
     readonly cause?: Error;
     constructor(message: string, cause?: Error);
 }
+/**
+ * Thrown when a request is cancelled by a caller-provided AbortSignal.
+ *
+ * Timeouts are reported as TimeoutError; this class represents explicit
+ * cancellation only.
+ */
+export declare class AbortError extends Error implements HttpClientError {
+    readonly name = "AbortError";
+    readonly cause?: Error;
+    constructor(message?: string, cause?: Error);
+}
 export declare class PathParameterError extends Error implements HttpClientError {
     readonly name = "PathParameterError";
     readonly url: string;
@@ -55,17 +90,17 @@ export declare class SerializationError extends Error implements HttpClientError
     readonly cause?: Error;
     constructor(message: string, cause?: Error);
 }
-export declare class InvalidSchemaError extends Error implements HttpClientError {
-    readonly name = "InvalidSchemaError";
+declare abstract class SchemaDefinitionError extends Error implements HttpClientError {
+    abstract readonly name: string;
     readonly schema: unknown;
     readonly cause?: Error;
     constructor(message: string, schema: unknown, cause?: Error);
 }
-export declare class AsyncSchemaValidationError extends Error implements HttpClientError {
+export declare class InvalidSchemaError extends SchemaDefinitionError {
+    readonly name = "InvalidSchemaError";
+}
+export declare class AsyncSchemaValidationError extends SchemaDefinitionError {
     readonly name = "AsyncSchemaValidationError";
-    readonly schema: unknown;
-    readonly cause?: Error;
-    constructor(message: string, schema: unknown, cause?: Error);
 }
 export declare class InvalidBaseUrlError extends Error implements HttpClientError {
     readonly name = "InvalidBaseUrlError";

package/dist/errors/handling.d.ts

@@ -0,0 +1,2 @@
+export declare function createErrorMessage(context: string, error: unknown): string;
+export declare function createStandardizedError(error: unknown, context: string): Error;

package/dist/errors/index.d.ts

@@ -0,0 +1 @@
+export { AbortError, AsyncSchemaValidationError, ContractValidationError, HttpError, InvalidBaseUrlError, InvalidContractError, InvalidSchemaError, MiddlewareError, NetworkError, PathParameterError, SchemaValidationError, SerializationError, TimeoutError, } from './errors';