1000fetches 0.2.1 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Max Tarsis
+Copyright (c) 2026 Max Tarsis
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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
-- ⚡ **Native streaming** — observe, transform, or pipe data chunks as they flow
-- 🔁 **Retries, timeouts, middleware** — production essentials, zero config
-- 🎯 **Method-based API** — `api.get()` with schema validation `.schema()` and extractor `.data()` for clean and concise code
+- ⚙️ **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 response contracts `.contract()` and extractor `.data()` for clean and concise code
 - 🧠 **Designed for flow** — clear API, predictable behavior, no hidden magic
 
 ---
@@ -55,15 +55,16 @@ const api = createHttpClient({
 // Define schemas for types and safety
 const userSchema = z.object({
   id: z.number(),
-  ...
+  name: z.string(),
+  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
@@ -71,51 +72,42 @@ const user = await api
   .get('/users/:id', {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // user 👉 { id: number, ... }
 ```
 
-**Or use the default client for quick requests:**
-
-```ts
-import http from '1000fetches'
-
-const user = await http
-  .get('/users/:id', {
-    pathParams: { id: '123' },
-  })
-  .schema(userSchema)
-```
+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.
 
 ## ➡️ Key Features
 
 ### ✔️ Type Safety That Actually Works
 
 - **Compile-time path validation** — TypeScript catches missing `:userId` parameters before runtime
+- **Trailing optional path params only** — `'/users/:id?'` supported, `'/users/:id?/cards/:cardId'` rejected
 - **Runtime schema validation** — Schemas verify data at the network boundary
 - **Schema-based type inference** — Types inferred from schemas, no generics needed
 - **Multi-schema support** — [Zod](https://github.com/colinhacks/zod), [Valibot](https://github.com/fabian-hiller/valibot), [ArkType](https://github.com/arktypeio/arktype), or any [Standard Schema](https://github.com/standard-schema/standard-schema)-compatible library
 
 ### ✔️ Production-Ready Quality
 
-- **Smart retry logic** — Exponential backoff with jitter for resilient requests
+- **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
-- **Minimalistic footprint** — Enterprise features without the bloat
+- **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
-- **Real-time streaming** — Access actual data chunks during upload/download
-- **Zero dependencies** — Optional peer dependencies, tree-shakable builds
+- **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
 
-**1000fetches** combines native `fetch` performance with enterprise-grade features and bulletproof type safety.
+**1000fetches** combines native `fetch` performance with production-oriented features and schema-backed type safety.
 
 ## ➡️ Usage Examples
 
@@ -130,44 +122,58 @@ 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 = Math.round((transferredBytes / totalBytes) * 100)
-    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 = Math.round((transferredBytes / totalBytes) * 100)
-    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,
   MiddlewareError,
   PathParameterError,
+  SchemaValidationError,
 } from '1000fetches'
 
 try {
@@ -175,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}`)
@@ -183,10 +189,14 @@ 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) {
     console.log('Path parameter error:', error.message)
+  } else if (error instanceof SchemaValidationError) {
+    console.log('Schema validation error:', error.message)
   }
 }
 ```
@@ -198,24 +208,28 @@ try {
 Creates a new HTTP client with optional configuration.
 
 ```ts
-function createHttpClient(config?: HttpClientConfig): HttpClient
+function createHttpClient(config?: HttpClientConfig)
 ```
 
 **Configuration Options:**
 
-| Option                 | Type                                          | Description                     |
-| ---------------------- | --------------------------------------------- | ------------------------------- |
-| `baseUrl`              | `string`                                      | Base URL for all requests       |
-| `headers`              | `Record<string, string>`                      | Default headers                 |
-| `timeout`              | `number`                                      | Default timeout in milliseconds |
-| `retryOptions`         | `RetryOptions`                                | Default retry configuration     |
-| `onRequestMiddleware`  | `(context: RequestContext) => RequestContext` | Request middleware              |
-| `onResponseMiddleware` | `(response: ResponseType) => 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
@@ -223,15 +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
@@ -239,7 +250,7 @@ const updatedUser = await api
   .put('/users/:id', userData, {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // updatedUser 👉 Fully typed user object
 
@@ -248,7 +259,7 @@ const patchedUser = await api
   .patch('/users/:id', partialData, {
     pathParams: { id: '123' },
   })
-  .schema(userSchema)
+  .contract(userSchema)
   .data()
 // patchedUser 👉 Fully typed user object
 
@@ -260,23 +271,53 @@ await api.delete('/users/:id', {
 
 ### <samp>Request Options</samp>
 
-| Option                | Type                                                       | Description                       |
-| --------------------- | ---------------------------------------------------------- | --------------------------------- |
-| `pathParams`          | `Record<string, string \| number>`                         | Path parameters for URL templates |
-| `params`              | `Record<string, string \| number \| boolean \| undefined>` | Query parameters                  |
-| `headers`             | `Record<string, string>`                                   | Request headers                   |
-| `body`                | `any`                                                      | Request body                      |
-| `timeout`             | `number`                                                   | Request timeout                   |
-| `signal`              | `AbortSignal`                                              | Request cancellation signal       |
-| `validateStatus`      | `(status: number) => boolean`                              | Custom status validation          |
-| `responseType`        | `'text' \| 'blob' \| 'arrayBuffer'`                        | Response type override            |
-| `cache`               | `RequestCache`                                             | Cache mode                        |
-| `credentials`         | `RequestCredentials`                                       | Credentials mode                  |
-| `mode`                | `RequestMode`                                              | Request mode                      |
-| `redirect`            | `RequestRedirect`                                          | Redirect mode                     |
-| `retryOptions`        | `RetryOptions`                                             | 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 `ReadableStream` request bodies.
+
+```ts
+const api = createHttpClient({
+  retry: {
+    maxRetries: 3,
+    retryDelay: 250,
+    jitter: 'full',
+    onRetry: event => {
+      console.log(event.method, event.url, event.nextAttempt)
+    },
+  },
+})
+```
+
+### <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>
 
@@ -287,39 +328,59 @@ interface ResponseType<T> {
   data: T // Parsed response data
   status: number // HTTP status code
   statusText: string // HTTP status text
-  headers: Record<string, string> // Response headers
-  method: HttpMethod // HTTP method used
+  headers: HttpHeaders // Response headers
+  method: HttpMethod
   url: string // Final URL
   raw: Response // Raw fetch Response
 }
 ```
 
-### <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' },
@@ -327,45 +388,43 @@ 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
+
+// Run the request and intentionally ignore response data
+await api.delete('/users/:id', { pathParams: { id: '123' } }).void()
 ```
 
-## ➡️ Feature Comparison
-
-**1000fetches vs Popular Alternatives**
-
-| Feature               | 1000fetches       | Axios           | Better-fetch       | Up-fetch           | Native Fetch       |
-| --------------------- | ----------------- | --------------- | ------------------ | ------------------ | ------------------ |
-| **Bundle Size (gz)**  | ≈4.3 kB           | ≈14.75 kB       | ≈3.07 kB           | ≈1.6 kB            | 0 kB               |
-| **TypeScript**        | ✅ Full inference | ⚠️ Limited      | ⚠️ Limited         | ✅ Good            | ❌ Manual          |
-| **Path Params**       | ✅ Compile-time   | ❌ Manual       | ❌ Manual          | ❌ Manual          | ❌ Manual          |
-| **Schema Validation** | ✅ Multi-library  | ❌ None         | ⚠️ Limited         | ✅ Multi-library   | ❌ None            |
-| **Retry Logic**       | ✅ Built-in       | ✅ Built-in     | ❌ Manual          | ✅ Built-in        | ❌ Manual          |
-| **Error Handling**    | ✅ Structured     | ✅ Good         | ⚠️ Basic           | ✅ Good            | ⚠️ Verbose         |
-| **Middleware**        | ✅ Full support   | ✅ Full support | ⚠️ Limited         | ✅ Lifecycle hooks | ❌ None            |
-| **Streaming**         | ✅ Real chunks    | ❌ None         | ❌ None            | ✅ Real chunks     | ✅ Native          |
-| **API Design**        | ✅ Method-based   | ✅ Method-based | ❌ Single function | ❌ Single function | ❌ Single function |
-| **Tree Shaking**      | ✅ Good           | ⚠️ Partial      | ✅ Good            | ✅ Perfect         | ✅                 |
+## ➡️ Design Trade-Offs
+
+1000fetches is intentionally small, but it is not just a thin `fetch` alias. It focuses on the features that tend to become repetitive in application code:
+
+| Capability            | What 1000fetches Provides                                             |
+| --------------------- | --------------------------------------------------------------------- |
+| **TypeScript**        | Schema-inferred response types and typed path parameters              |
+| **Path Params**       | Compile-time and runtime checks for `:param` placeholders             |
+| **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                    |
+| **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

@@ -0,0 +1,83 @@
+import { SchemaValidator } from './schema';
+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;
+    /** Query parameters */
+    params?: TParams;
+    /** Path parameters for URL template */
+    pathParams?: Record<string, string | number | undefined>;
+    /** Request body */
+    body?: TBody;
+    timeout?: number;
+    signal?: AbortSignal;
+    /** Fetch options */
+    credentials?: RequestCredentials;
+    cache?: RequestCache;
+    mode?: RequestMode;
+    redirect?: RequestRedirect;
+    /** Additional Fetch/Node options passed through to the underlying fetch call */
+    fetchOptions?: FetchOptions;
+    /** Response type override */
+    responseType?: 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData';
+    /** Per-request retry configuration */
+    retry?: RetryOptions | boolean;
+}
+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 */
+    headers?: HttpHeaders;
+    /** Default timeout */
+    timeout?: number;
+    /** Schema validator */
+    schemaValidator?: SchemaValidator;
+    /** Default retry configuration */
+    retry?: RetryOptions | boolean;
+    /** Custom fetch implementation */
+    fetch?: CustomFetch;
+    /** Custom body serializer */
+    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> | 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,
+ * middleware, serialization, defaults, and timeouts.
+ */
+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>>;