create-request 1.4.3-rc.4 → 1.5.1

package/dist/library/apiBuilder.d.ts

@@ -1,180 +1,541 @@
-import type { CookiesRecord, CookieOptions, RetryConfig, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from "./types.js";
-import type { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods.js";
-interface ApiBuilderRequestMethods {
-    withoutCsrfProtection(): ApiBuilder & ApiBuilderRequestMethods;
-    withAntiCsrfHeaders(): ApiBuilder & ApiBuilderRequestMethods;
-    withTimeout(timeout: number): ApiBuilder & ApiBuilderRequestMethods;
-    withReferrer(referrer: string): ApiBuilder & ApiBuilderRequestMethods;
-    withKeepAlive(keepalive: boolean): ApiBuilder & ApiBuilderRequestMethods;
-    withIntegrity(integrity: string): ApiBuilder & ApiBuilderRequestMethods;
-    withHeader(key: string, value: string): ApiBuilder & ApiBuilderRequestMethods;
-    withHeaders(headers: Record<string, string>): ApiBuilder & ApiBuilderRequestMethods;
-    withRetries(retries: number | RetryConfig): ApiBuilder & ApiBuilderRequestMethods;
-    withBearerToken(token: string): ApiBuilder & ApiBuilderRequestMethods;
-    withCookies(cookies: CookiesRecord): ApiBuilder & ApiBuilderRequestMethods;
-    withContentType(contentType: string): ApiBuilder & ApiBuilderRequestMethods;
-    withAuthorization(authValue: string): ApiBuilder & ApiBuilderRequestMethods;
-    withBasicAuth(username: string, password: string): ApiBuilder & ApiBuilderRequestMethods;
-    withCsrfToken(token: string, headerName?: string): ApiBuilder & ApiBuilderRequestMethods;
-    withErrorInterceptor(interceptor: ErrorInterceptor): ApiBuilder & ApiBuilderRequestMethods;
-    withCookie(name: string, value: string | CookieOptions): ApiBuilder & ApiBuilderRequestMethods;
-    withRequestInterceptor(interceptor: RequestInterceptor): ApiBuilder & ApiBuilderRequestMethods;
-    withResponseInterceptor(interceptor: ResponseInterceptor): ApiBuilder & ApiBuilderRequestMethods;
-}
+import { GetRequest, PostRequest, PutRequest, DeleteRequest, PatchRequest, HeadRequest, OptionsRequest } from "./requestMethods.js";
+import type { RetryConfig, RetryCallback, CookiesRecord, CookieOptions, RequestInterceptor, ResponseInterceptor, ErrorInterceptor } from "./types.js";
+import type { CredentialsPolicy, RedirectMode, RequestPriority, ReferrerPolicy, RequestMode } from "./enums.js";
 /**
- * API builder for creating configured API instances with default settings.
- * Allows you to set default headers, timeouts, authentication, and other options
- * that will be applied to all requests created through this builder.
- *
- * @example
- * ```typescript
- * const api = create.api()
- *   .withBaseURL("https://api.example.com")
- *   .withBearerToken("token123")
- *   .withTimeout(5000);
- *
- * // All requests will use the base URL, bearer token, and timeout
- * await api.get("/users").getJson();
- * await api.post("/posts").withBody({ title: "Hello" }).getJson();
- * ```
+ * API Builder for creating configured API instances with reusable default settings.
  */
-export declare class ApiBuilder {
-    private baseURL?;
-    private modifiers?;
+type ApiBuilder = {
+    withBaseURL(baseURL: string): ApiBuilder;
+    get(path?: string): GetRequest;
+    post(path?: string): PostRequest;
+    put(path?: string): PutRequest;
+    del(path?: string): DeleteRequest;
+    patch(path?: string): PatchRequest;
+    head(path?: string): HeadRequest;
+    options(path?: string): OptionsRequest;
+    /**
+     * Add multiple HTTP headers to the request.
+     * Null and undefined header values are ignored.
+     *
+     * @param headers - An object containing key-value pairs of headers
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withHeaders({
+     *   'Content-Type': 'application/json',
+     *   'Authorization': 'Bearer token123'
+     * });
+     * ```
+     */
+    withHeaders(headers: Record<string, string>): ApiBuilder;
+    /**
+     * Add a single HTTP header to the request.
+     *
+     * @param name - The header name
+     * @param value - The header value
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withHeader('Content-Type', 'application/json');
+     * ```
+     */
+    withHeader(name: string, value: string): ApiBuilder;
+    /**
+     * Set a timeout for the request.
+     * If the request takes longer than the specified time, it will be aborted and a RequestError will be thrown.
+     *
+     * @param timeout - The timeout in milliseconds (must be a positive finite number)
+     * @returns The API builder instance for chaining
+     * @throws {RequestError} If timeout is not a positive finite number
+     *
+     * @example
+     * ```typescript
+     * api.withTimeout(5000); // 5 second timeout
+     * ```
+     */
+    withTimeout(timeout: number): ApiBuilder;
+    /**
+     * Configure automatic retry behavior for failed requests.
+     * By default, retries only network errors. For more control, pass a RetryConfig object.
+     *
+     * @param retries - Either:
+     *   - A number: number of retry attempts (fixed delay of 1000ms between retries)
+     *   - A RetryConfig object with optional properties:
+     *     - maxRetries: number of retry attempts
+     *     - delay: a function (attempt, error?) => number that returns delay in ms
+     *     - retryOn: array of status codes to retry on (in addition to network errors)
+     *     - shouldRetry: custom function to decide if a retry should happen
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple retry with fixed delay
+     * api.withRetries(3);
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Exponential backoff
+     * api.withRetries({
+     *   maxRetries: 3,
+     *   delay: (attempt) => Math.pow(2, attempt) * 1000
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Retry specific status codes
+     * api.withRetries({
+     *   maxRetries: 2,
+     *   retryOn: [408, 429, 500, 502, 503, 504]
+     * });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Custom retry logic with error-aware delay
+     * api.withRetries({
+     *   maxRetries: 3,
+     *   delay: (attempt, error) => {
+     *     if (error?.status === 429) return 5000; // Rate limited
+     *     return attempt * 1000; // Linear backoff
+     *   },
+     *   shouldRetry: (error) => error.status === 429 || error.status >= 500
+     * });
+     * ```
+     */
+    withRetries(retries: number | RetryConfig): ApiBuilder;
     /**
-     * Sets the base URL for all requests created through this API builder.
-     * Relative URLs will be resolved against this base URL.
+     * Register a callback to be invoked before each retry attempt.
+     * The callback receives the attempt number (1-indexed), the error that caused the retry,
+     * and the delay before the next retry.
+     *
+     * @param callback - A function that receives (attempt: number, error: RequestError, delay: number)
+     * @returns The API builder instance for chaining
      *
-     * @param baseURL - The base URL to use for all requests
-     * @returns The API builder instance for method chaining
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * await api.get("/users").getJson(); // Requests https://api.example.com/users
+     * api.onRetry((attempt, error, delay) => {
+     *   console.log(`Retry attempt ${attempt} after ${delay}ms due to:`, error.message);
+     * });
      * ```
      */
-    withBaseURL(baseURL: string): ApiBuilder & ApiBuilderRequestMethods;
+    onRetry(callback: RetryCallback): ApiBuilder;
     /**
-     * Adds a modifier function that will be applied to all requests created through this builder.
+     * Set the credentials policy for the request.
+     * Controls whether cookies and HTTP authentication are sent with cross-origin requests.
+     *
+     * - `include`: Send credentials with both same-origin and cross-origin requests
+     * - `omit`: Never send credentials
+     * - `same-origin` (default): Only send credentials with same-origin requests
+     *
+     * Note: Use direct call pattern. Fluent API (e.g., `.withCredentials.INCLUDE()`) is not supported in ApiBuilder.
      *
-     * @private
-     * @param modifier - A function that modifies a request and returns it
-     * @returns The API builder instance for method chaining
+     * @param credentials - The credentials policy
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withCredentials('include'); // Send cookies with cross-origin requests
+     * api.withCredentials(CredentialsPolicy.INCLUDE);
+     * ```
      */
-    private addModifier;
+    withCredentials(credentials: CredentialsPolicy): ApiBuilder;
     /**
-     * Creates a GET request with the configured default settings.
+     * Set the referrer URL for the request.
+     * This specifies the referrer to send in the Referer header.
+     *
+     * @param referrer - The referrer URL
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withReferrer('https://example.com/page');
+     * ```
+     */
+    withReferrer(referrer: string): ApiBuilder;
+    /**
+     * Set the referrer policy for the request.
+     * Controls how much referrer information is included with requests.
+     *
+     * Available policies:
+     * - `no-referrer`: Never send referrer
+     * - `no-referrer-when-downgrade` (default): Send referrer except when going from HTTPS to HTTP
+     * - `origin`: Send only the origin (scheme, host, port)
+     * - `origin-when-cross-origin`: Full URL for same-origin, only origin for cross-origin
+     * - `same-origin`: Send referrer only for same-origin requests
+     * - `strict-origin`: Send origin, but not when going from HTTPS to HTTP
+     * - `strict-origin-when-cross-origin`: Full URL for same-origin, origin for cross-origin HTTPS, nothing for HTTP
+     * - `unsafe-url`: Always send full URL (may leak sensitive information)
+     *
+     * @param policy - The referrer policy
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withReferrerPolicy('no-referrer');
+     * api.withReferrerPolicy(ReferrerPolicy.NO_REFERRER); // Using enum
+     * ```
+     */
+    withReferrerPolicy(policy: ReferrerPolicy): ApiBuilder;
+    /**
+     * Set the redirect behavior for the request.
+     *
+     * - `follow` (default): Automatically follow redirects
+     * - `error`: Treat redirects as errors
+     * - `manual`: Handle redirects manually (response will have type 'opaqueredirect')
+     *
+     * @param redirect - The redirect mode
+     * @returns The API builder instance for chaining
      *
-     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
-     * @returns A GetRequest instance ready to be executed
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * await api.get("/users").getJson();
-     * await api.get("https://other.com/data").getJson(); // Absolute URL overrides base
+     * api.withRedirect('error'); // Throw an error on redirect
+     * api.withRedirect(RedirectMode.ERROR); // Using enum
      * ```
      */
-    get: (url?: string) => GetRequest;
+    withRedirect(redirect: RedirectMode): ApiBuilder;
     /**
-     * Creates a POST request with the configured default settings.
+     * Enable or disable HTTP keep-alive for the request.
+     * When enabled, the connection can be reused for multiple requests.
+     *
+     * @param keepalive - Whether to use keep-alive (default is false)
+     * @returns The API builder instance for chaining
      *
-     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
-     * @returns A PostRequest instance ready to be executed
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * await api.post("/users").withBody({ name: "John" }).getJson();
+     * api.withKeepAlive(true);
      * ```
      */
-    post: (url?: string) => PostRequest;
+    withKeepAlive(keepalive: boolean): ApiBuilder;
     /**
-     * Creates a PUT request with the configured default settings.
+     * Set the priority hint for the request.
+     * This provides a hint to the browser about the relative priority of this request.
+     *
+     * - `high`: High priority (e.g., critical resources)
+     * - `low`: Low priority (e.g., prefetch, background tasks)
+     * - `auto` (default): Browser decides the priority
+     *
+     * @param priority - The request priority
+     * @returns The API builder instance for chaining
      *
-     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
-     * @returns A PutRequest instance ready to be executed
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * await api.put("/users/123").withBody({ name: "Jane" }).getJson();
+     * api.withPriority('high'); // Mark as high priority
+     * api.withPriority(RequestPriority.HIGH); // Using enum
      * ```
      */
-    put: (url?: string) => PutRequest;
+    withPriority(priority: RequestPriority): ApiBuilder;
     /**
-     * Creates a DELETE request with the configured default settings.
+     * Set the Subresource Integrity (SRI) value for the request.
+     * Used to verify that a fetched resource hasn't been tampered with.
+     *
+     * @param integrity - The integrity hash (e.g., 'sha384-...')
+     * @returns The API builder instance for chaining
      *
-     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
-     * @returns A DeleteRequest instance ready to be executed
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * await api.del("/users/123").getResponse();
+     * api.withIntegrity('sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC');
      * ```
      */
-    del: (url?: string) => DeleteRequest;
+    withIntegrity(integrity: string): ApiBuilder;
     /**
-     * Creates a PATCH request with the configured default settings.
+     * Set the cache mode for the request.
+     * Controls how the request interacts with the browser's HTTP cache.
+     *
+     * Cache modes:
+     * - `default`: Use the standard HTTP cache behavior (check freshness, use cached response if valid)
+     * - `no-store`: Bypass cache completely, don't store the response
+     * - `reload`: Bypass cache for this request, but store the response
+     * - `no-cache`: Use cached response only after revalidation with the server
+     * - `force-cache`: Use cached response even if stale, only fetch if not cached
+     * - `only-if-cached`: Use cached response or fail (must use with same-origin mode)
+     *
+     * @param cache - The cache mode
+     * @returns The API builder instance for chaining
      *
-     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
-     * @returns A PatchRequest instance ready to be executed
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * await api.patch("/users/123").withBody({ name: "Updated" }).getJson();
+     * api.withCache('no-store'); // Don't cache this request
+     * api.withCache('force-cache'); // Use cache even if stale
      * ```
      */
-    patch: (url?: string) => PatchRequest;
+    withCache(cache: RequestCache): ApiBuilder;
     /**
-     * Creates a HEAD request with the configured default settings.
+     * Set the request mode.
+     * Controls CORS behavior and what types of responses are allowed.
+     *
+     * Request modes:
+     * - `cors` (default): Allow cross-origin requests, follow CORS protocol
+     * - `no-cors`: Make cross-origin request without CORS headers (limited response access)
+     * - `same-origin`: Only allow same-origin requests, reject cross-origin
+     * - `navigate`: Used for navigation requests (usually not needed for fetch)
+     *
+     * @param mode - The request mode
+     * @returns The API builder instance for chaining
      *
-     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
-     * @returns A HeadRequest instance ready to be executed
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * const response = await api.head("/users").getResponse();
+     * api.withMode('same-origin'); // Only allow same-origin requests
+     * api.withMode(RequestMode.SAME_ORIGIN); // Using enum
      * ```
      */
-    head: (url?: string) => HeadRequest;
+    withMode(mode: RequestMode): ApiBuilder;
     /**
-     * Creates an OPTIONS request with the configured default settings.
+     * Sets the Content-Type header for the request.
+     * Shorthand for `withHeader('Content-Type', contentType)`.
+     *
+     * @param contentType - The MIME type (e.g., 'application/json', 'text/plain', 'application/xml')
+     * @returns The API builder instance for chaining
      *
-     * @param url - Optional URL path. If not provided, uses the base URL. If relative, resolves against base URL.
-     * @returns An OptionsRequest instance ready to be executed
      * @example
      * ```typescript
-     * const api = create.api().withBaseURL("https://api.example.com");
-     * await api.options("/users").getResponse();
+     * api.withContentType('application/json');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * api.withContentType('application/xml');
      * ```
      */
-    options: (url?: string) => OptionsRequest;
+    withContentType(contentType: string): ApiBuilder;
     /**
-     * Creates a new ApiBuilder instance with a Proxy that enables dynamic method forwarding.
-     * The Proxy allows calling any `with*` method from BaseRequest on the API builder,
-     * which will apply that configuration to all requests created through this builder.
+     * Sets the Authorization header for the request.
+     * Shorthand for `withHeader('Authorization', authValue)`.
+     * For Bearer tokens, use `withBearerToken()` instead. For Basic auth, use `withBasicAuth()`.
+     *
+     * @param authValue - The full authorization header value (e.g., `'Bearer token123'`, `'Basic base64string'`)
+     * @returns The API builder instance for chaining
      *
-     * @internal
+     * @example
+     * ```typescript
+     * api.withAuthorization('Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * api.withAuthorization('CustomScheme customToken');
+     * ```
      */
-    constructor();
-}
+    withAuthorization(authValue: string): ApiBuilder;
+    /**
+     * Sets up HTTP Basic Authentication.
+     * Encodes the username and password in base64 and sets the Authorization header.
+     *
+     * @param username - The username for Basic authentication
+     * @param password - The password for Basic authentication
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withBasicAuth('myuser', 'mypassword');
+     * // Sets: Authorization: Basic bXl1c2VyOm15cGFzc3dvcmQ=
+     * ```
+     */
+    withBasicAuth(username: string, password: string): ApiBuilder;
+    /**
+     * Sets a Bearer token for authentication.
+     * Shorthand for `withAuthorization('Bearer ' + token)`.
+     *
+     * @param token - The Bearer token (JWT, OAuth token, etc.)
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withBearerToken('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');
+     * // Sets: Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+     * ```
+     */
+    withBearerToken(token: string): ApiBuilder;
+    /**
+     * Sets cookies for the request.
+     * Cookies are sent in the Cookie header. Multiple calls will merge cookies.
+     * Cookie values can be simple strings or objects with additional cookie options.
+     *
+     * @param cookies - An object where keys are cookie names and values are either:
+     *   - A string (the cookie value)
+     *   - A CookieOptions object with `value` and optional properties (secure, httpOnly, sameSite, expires, path, domain, maxAge)
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * // Simple string cookies
+     * api.withCookies({ sessionId: 'abc123', userId: '456' });
+     * ```
+     *
+     * @example
+     * ```typescript
+     * // Cookies with options (note: options are for documentation only in request cookies)
+     * api.withCookies({
+     *   sessionId: 'abc123',
+     *   token: { value: 'xyz789', secure: true }
+     * });
+     * ```
+     */
+    withCookies(cookies: CookiesRecord): ApiBuilder;
+    /**
+     * Sets a single cookie for the request.
+     * Convenience method for adding one cookie at a time.
+     *
+     * @param name - The cookie name
+     * @param value - The cookie value as a string, or a CookieOptions object with `value` and optional properties
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withCookie('sessionId', 'abc123');
+     * ```
+     *
+     * @example
+     * ```typescript
+     * api.withCookie('token', { value: 'xyz789', secure: true });
+     * ```
+     */
+    withCookie(name: string, value: string | CookieOptions): ApiBuilder;
+    /**
+     * Sets a CSRF (Cross-Site Request Forgery) token in the request headers.
+     * This is commonly used to protect against CSRF attacks in web applications.
+     *
+     * @param token - The CSRF token value
+     * @param headerName - The name of the header to use. Defaults to `'X-CSRF-Token'`.
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * api.withCsrfToken('csrf-token-123');
+     * // Sets: X-CSRF-Token: csrf-token-123
+     * ```
+     *
+     * @example
+     * ```typescript
+     * api.withCsrfToken('token', 'X-Custom-CSRF-Header');
+     * // Sets: X-Custom-CSRF-Header: token
+     * ```
+     */
+    withCsrfToken(token: string, headerName?: string): ApiBuilder;
+    /**
+     * Disables automatic anti-CSRF protection.
+     * By default, X-Requested-With: XMLHttpRequest header is sent with all requests.
+     * @returns The API builder instance for chaining
+     */
+    withoutCsrfProtection(): ApiBuilder;
+    /**
+     * Sets common security headers to help prevent CSRF attacks
+     * @returns The API builder instance for chaining
+     */
+    withAntiCsrfHeaders(): ApiBuilder;
+    /**
+     * Add a request interceptor for this specific request
+     * Request interceptors can modify the request configuration or return an early response
+     *
+     * @param interceptor - The request interceptor function
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * api.withRequestInterceptor((config) => {
+     *   config.headers['X-Custom'] = 'value';
+     *   return config;
+     * });
+     */
+    withRequestInterceptor(interceptor: RequestInterceptor): ApiBuilder;
+    /**
+     * Add a response interceptor for this specific request
+     * Response interceptors can transform the response
+     *
+     * @param interceptor - The response interceptor function
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * api.withResponseInterceptor((response) => {
+     *   console.log('Status:', response.status);
+     *   return response;
+     * });
+     */
+    withResponseInterceptor(interceptor: ResponseInterceptor): ApiBuilder;
+    /**
+     * Add an error interceptor for this specific request
+     * Error interceptors can handle or transform errors
+     *
+     * @param interceptor - The error interceptor function
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * api.withErrorInterceptor((error) => {
+     *   console.error('Request failed:', error);
+     *   throw error;
+     * });
+     */
+    withErrorInterceptor(interceptor: ErrorInterceptor): ApiBuilder;
+    /**
+     * Adds default query parameters to all requests made through this API instance.
+     *
+     * @param params - An object containing query parameter key-value pairs
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const api = createApi()
+     *   .withBaseURL('https://api.example.com')
+     *   .withQueryParams({ apiVersion: 'v2', format: 'json' });
+     * // All requests will include ?apiVersion=v2&format=json
+     * ```
+     */
+    withQueryParams(params: Record<string, string | string[] | number | boolean | null | undefined>): ApiBuilder;
+    /**
+     * Adds a single default query parameter to all requests made through this API instance.
+     *
+     * @param key - The query parameter name
+     * @param value - The query parameter value
+     * @returns The API builder instance for chaining
+     *
+     * @example
+     * ```typescript
+     * const api = createApi()
+     *   .withBaseURL('https://api.example.com')
+     *   .withQueryParam('apiKey', 'abc123');
+     * ```
+     */
+    withQueryParam(key: string, value: string | string[] | number | boolean | null | undefined): ApiBuilder;
+};
 /**
- * Creates a new API builder instance for configuring default request settings.
- * The builder allows you to set base URLs, authentication, headers, timeouts,
- * and other options that will be applied to all requests created through it.
+ * Creates a new API builder for configuring default request settings.
+ * The API builder allows you to set up a base URL, default headers, timeout,
+ * and other configuration options that will be applied to all requests made through it.
+ *
+ * @returns A new API builder instance
  *
- * @returns A new ApiBuilder instance with all configuration methods available
  * @example
  * ```typescript
- * // Create an API instance with default configuration
- * const api = create.api()
- *   .withBaseURL("https://api.example.com")
- *   .withBearerToken("your-token")
- *   .withTimeout(5000)
- *   .withHeaders({ "X-Custom": "value" });
+ * // Create an API instance with defaults
+ * const api = api()
+ *   .withBaseURL('https://api.example.com')
+ *   .withBearerToken('token123')
+ *   .withTimeout(5000);
  *
  * // All requests will use these defaults
- * const users = await api.get("/users").getJson();
- * const newUser = await api.post("/users").withBody({ name: "John" }).getJson();
+ * const users = await api.get('/users').getJson();
+ * const newUser = await api.post('/users').withBody({ name: 'John' }).getJson();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use without URL when baseURL is set
+ * const api = api().withBaseURL('https://api.example.com');
+ * const data = await api.get().getJson(); // Requests to https://api.example.com
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Override defaults per request
+ * const api = api()
+ *   .withBaseURL('https://api.example.com')
+ *   .withTimeout(5000);
+ *
+ * // This request uses a longer timeout
+ * await api.get('/slow-endpoint').withTimeout(30000).getJson();
  * ```
  */
-export declare function api(): ApiBuilder & ApiBuilderRequestMethods;
+export declare function api(): ApiBuilder;
 export {};