aspi 1.3.0 → 2.0.1

package/dist/index.d.cts

@@ -67,36 +67,176 @@ declare const getHttpErrorStatus: (status: HttpErrorCodes) => HttpErrorStatus;
  */
 type HttpMethods = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH' | 'TRACE' | 'CONNECT';
 
+/**
+ * Utility type to simplify and prettify a given type.
+ *
+ * @template Type - The type to be prettified.
+ */
 type Prettify<Type> = Type extends Function ? Type : Extract<{
     [Key in keyof Type]: Type[Key];
 }, Type>;
+/**
+ * Merge two object types, with properties from `Object2` overriding those in `Object1`.
+ *
+ * @template Object1 - The base object type.
+ * @template Object2 - The object type whose properties will take precedence.
+ */
 type Merge<Object1, Object2> = Prettify<Omit<Object1, keyof Object2> & Object2>;
+/**
+ * Represents the base URL used by Aspi.
+ *
+ * Accepts either a string representation of the URL or a native {@link URL} object.
+ */
+type BaseURL = string | URL;
+/**
+ * Base configuration for Aspi.
+ *
+ * This configuration is merged with native `RequestInit` properties and
+ * is intended to be passed alongside a `RequestInit` object when initializing
+ * an Aspi instance.
+ */
 type AspiConfigBase = {
-    baseUrl: string;
+    /**
+     * The base URL for all Aspi requests.
+     */
+    baseUrl: BaseURL;
+    /**
+     * Optional retry configuration applied to all requests.
+     */
     retryConfig?: AspiRetryConfig<AspiRequestInit>;
 };
+/**
+ * Configuration for an Aspi instance (without request body).
+ *
+ * This type includes all standard `RequestInit` properties
+ * (`headers`, `mode`, `credentials`, `cache`, `redirect`,
+ * `referrer`, `referrerPolicy`, `integrity`, `keepalive`, `signal`)
+ * merged with the base Aspi configuration defined in {@link AspiConfigBase}.
+ *
+ * @extends Merge<Pick<RequestInit,
+ *   | 'headers'
+ *   | 'mode'
+ *   | 'credentials'
+ *   | 'cache'
+ *   | 'redirect'
+ *   | 'referrer'
+ *   | 'referrerPolicy'
+ *   | 'integrity'
+ *   | 'keepalive'
+ *   | 'signal'>,
+ *   AspiConfigBase>
+ */
+interface AspiRequestInitWithoutBodyAndMethod extends Merge<Pick<RequestInit, 'headers' | 'mode' | 'credentials' | 'cache' | 'redirect' | 'referrer' | 'referrerPolicy' | 'integrity' | 'keepalive' | 'signal'>, AspiConfigBase> {
+}
+/**
+ * Configuration for an Aspi request that may include a request body.
+ *
+ * Extends {@link AspiRequestInitWithoutBody} with the optional `body`
+ * property from the native {@link RequestInit} type.
+ *
+ * @template TBody - The type of the request body (defaults to `any`).
+ * @extends Merge<Pick<RequestInit, 'body'>, AspiRequestInitWithoutBody>
+ */
+interface AspiRequestInit<TBody = any> extends Merge<Pick<RequestInit, 'body' | 'method'>, Omit<AspiRequestInitWithoutBodyAndMethod, 'retryConfig'>> {
+}
+/**
+ * Configuration options for retrying an Aspi request.
+ *
+ * @template TRequest - The request type extending {@link AspiRequestInit}.
+ */
 type AspiRetryConfig<TRequest extends AspiRequestInit> = {
+    /**
+     * Maximum number of retry attempts. If omitted, no retries are performed.
+     */
     retries?: number;
+    /**
+     * Delay before the next retry attempt.
+     *
+     * Can be a static number (milliseconds) or a function that dynamically
+     * determines the delay based on the retry state and the request/response.
+     *
+     * @param remainingRetries - Number of retries left after the current attempt.
+     * @param totalRetries - The total number of retries configured.
+     * @param request - The original {@link AspiRequest} being retried.
+     * @param response - The {@link AspiResponse} received from the failed attempt.
+     * @returns A delay in milliseconds or a promise that resolves to one.
+     */
     retryDelay?: number | ((remainingRetries: number, totalRetries: number, request: AspiRequest<TRequest>, response: AspiResponse) => number | Promise<number>);
+    /**
+     * Array of HTTP status codes that should trigger a retry.
+     */
     retryOn?: Array<HttpErrorCodes>;
+    /**
+     * Predicate function that determines whether a retry should occur based on the
+     * request and response. Returning `true` triggers a retry.
+     *
+     * @param request - The {@link AspiRequest} that was sent.
+     * @param response - The {@link AspiResponse} received.
+     * @returns A boolean or a promise that resolves to a boolean.
+     */
     retryWhile?: (request: AspiRequest<TRequest>, response: AspiResponse) => boolean | Promise<boolean>;
+    /**
+     * Callback invoked after each retry attempt.
+     *
+     * @param request - The {@link AspiRequest} that was retried.
+     * @param response - The {@link AspiResponse} from the failed attempt.
+     */
     onRetry?: (request: AspiRequest<TRequest>, response: AspiResponse) => void;
 };
-type AspiConfig = Pick<RequestInit, 'headers' | 'mode'> & AspiConfigBase;
+/**
+ * Callback type for handling custom errors.
+ *
+ * @template T - The request type extending {@link AspiRequestInit}.
+ * @template A - The shape of the error object returned by the callback.
+ * @param input - Object containing the request and response that triggered the error.
+ * @param input.request - The {@link AspiRequest} associated with the failed request.
+ * @param input.response - The {@link AspiResponse} received from the server.
+ * @returns The error data of type `A`.
+ */
 type CustomErrorCb<T extends AspiRequestInit, A extends {}> = (input: {
     request: AspiRequest<T>;
     response: AspiResponse;
 }) => A;
-type Middleware<T extends RequestInit, U extends RequestInit> = (request: T) => U;
-interface AspiRequestInit extends RequestInit, AspiConfigBase {
-}
+/**
+ * Transforms a request before it is sent.
+ *
+ * @template T - The original request type extending {@link AspiRequestInit}.
+ * @template U - The resulting request type extending {@link AspiRequestInit}.
+ * @param request - The request instance to be transformed.
+ * @returns The transformed request of type `U`.
+ */
+type RequestTransformer<T extends AspiRequestInit, U extends AspiRequestInit> = (request: T) => U;
+/**
+ * Options for configuring an Aspi request.
+ *
+ * @template TRequest - The request initialization type extending {@link AspiRequestInit}.
+ * @property {TRequest} requestConfig - The request configuration object.
+ * @property {AspiRetryConfig<TRequest>} [retryConfig] - Optional retry configuration applied to the request.
+ * @property {RequestTransformer<TRequest, TRequest>[]} [middlewares] - Optional list of request transformers that act as middleware.
+ * @property {ErrorCallbacks} [errorCbs] - Optional collection of custom error callbacks keyed by HTTP status code.
+ * @property {boolean} [throwOnError] - When `true`, the request will throw on error instead of returning an error result.
+ * @property {boolean} [shouldBeResult] - When `true`, the request returns an {@link AspiResultOk} instead of a raw response.
+ */
 type RequestOptions<TRequest extends AspiRequestInit> = {
     requestConfig: TRequest;
     retryConfig?: AspiRetryConfig<TRequest>;
-    middlewares?: Middleware<TRequest, TRequest>[];
+    middlewares?: RequestTransformer<TRequest, TRequest>[];
     errorCbs?: ErrorCallbacks;
     throwOnError?: boolean;
+    shouldBeResult?: boolean;
 };
+/**
+ * Record of custom error callbacks keyed by HTTP status code.
+ *
+ * It keeps track of the custom error callbacks (`cb`) provided for specific
+ * response codes. Each entry includes:
+ *
+ * - `cb`: a function receiving the request and response objects that generated the error.
+ * - `tag`: an optional identifier or metadata associated with the callback.
+ *
+ * This type is used in {@link RequestOptions.errorCbs} to map status codes to
+ * their corresponding handlers.
+ */
 type ErrorCallbacks = Record<number, {
     cb: (input: {
         request: any;
@@ -104,44 +244,65 @@ type ErrorCallbacks = Record<number, {
     }) => any;
     tag: unknown;
 }>;
+/**
+ * Represents a successful Aspi request result.
+ *
+ * @template TRequest - The request initialization options type extending {@link AspiRequestInit}.
+ * @template TData - The type of the response data.
+ * @property {TData} data - The parsed response payload.
+ * @property {AspiRequest<TRequest>} request - The request that was sent.
+ * @property {AspiResponse} response - The response wrapper containing status, status text, and the native {@link Response} object.
+ */
 type AspiResultOk<TRequest extends AspiRequestInit, TData> = {
     data: TData;
     request: AspiRequest<TRequest>;
     response: AspiResponse;
 };
-type AspiPlainResponse<TRequest extends AspiRequestInit, TData> = AspiResultOk<TRequest, TData>;
-
 /**
- * Response interface used in error handling
- * @interface AspiResponse
- * @property {HttpErrorCodes} status - The HTTP status code of the response
- * @property {HttpErrorStatus} statusText - The HTTP status text of the response
- * @property {Response} [response] - Optional raw Response object
- * @property {any} [responseData] - Optional response data content
+ * Represents a successful Aspi request result without any additional metadata.
+ *
+ * This type is an alias for {@link AspiResultOk} and is provided for semantic
+ * clarity when a plain response shape is desired.
+ *
+ * @template TRequest - The request initialization options type extending {@link AspiRequestInit}.
+ * @template TData - The type of the response payload.
  */
-interface AspiResponse {
-    status: HttpErrorCodes;
-    statusText: HttpErrorStatus;
-    response?: Response;
-    responseData?: any;
-}
+type AspiPlainResponse<TRequest extends AspiRequestInit, TData> = AspiResultOk<TRequest, TData>;
 /**
- * Interface representing an API request configuration
+ * Interface representing an API request configuration.
+ *
  * @interface AspiRequest
- * @template T - Request initialization options type extending AspiRequestInit
- * @property {string} baseUrl - Base URL for the API request
- * @property {string} path - Request path to append to baseUrl
- * @property {T} requestInit - Request initialization options
- * @property {URLSearchParams | null} queryParams - URL query parameters, if any
- * @property {AspiRetryConfig<T>} retryConfig - Retry configuration for failed requests
+ * @template T - Request initialization options type extending {@link AspiRequestInit}
+ * @property {string} path - Request path to append to the base URL.
+ * @property {T} requestInit - Request initialization options.
+ * @property {URLSearchParams | null} queryParams - URL query parameters, if any.
  */
 interface AspiRequest<T extends AspiRequestInit> {
-    baseUrl: string;
     path: string;
     requestInit: T;
     queryParams: URLSearchParams | null;
-    retryConfig: AspiRetryConfig<T>;
 }
+/**
+ * Represents the response returned by an Aspi request.
+ *
+ * @template TData - The type of the response payload when the request succeeds.
+ * @template IsError - `true` if the response represents an error condition; `false` otherwise.
+ *
+ * @property {HttpErrorCodes} status - HTTP status code of the response.
+ * @property {HttpErrorStatus} statusText - HTTP status text associated with the status code.
+ * @property {Response} response - The native {@link Response} object.
+ * @property {TData} [responseData] - The parsed response body. When `IsError` is `true` this property is required; otherwise it is optional.
+ */
+type AspiResponse<TData = any, IsError extends boolean = false> = Merge<{
+    status: HttpErrorCodes;
+    statusText: HttpErrorStatus;
+    response: Response;
+}, IsError extends true ? {
+    responseData: TData;
+} : {
+    responseData?: any;
+}>;
+
 /**
  * Custom error class for API errors
  * @class AspiError
@@ -150,17 +311,17 @@ interface AspiRequest<T extends AspiRequestInit> {
  * @property {AspiRe} request - The original request configuration
  * @property {AspiResponse} response - The error response details
  */
-declare class AspiError<TReq extends AspiRequestInit> extends Error {
+declare class AspiError<TRequest extends AspiRequestInit> extends Error {
     tag: "aspiError";
-    request: AspiRequest<TReq>;
-    response: AspiResponse;
+    request: AspiRequest<TRequest>;
+    response: AspiResponse<any, false>;
     /**
      * Creates an instance of AspiError
      * @param {string} message - The error message
      * @param {AspiRe} request - The request configuration
      * @param {AspiResponse} response - The error response
      */
-    constructor(message: string, request: AspiRequest<TReq>, response: AspiResponse);
+    constructor(message: string, request: AspiRequest<TRequest>, response: AspiResponse);
     /**
      * Conditionally executes callback if status matches
      * @template T
@@ -169,8 +330,8 @@ declare class AspiError<TReq extends AspiRequestInit> extends Error {
      * @returns {T | undefined} Result of callback if status matches, undefined otherwise
      */
     ifMatch<T>(status: HttpErrorStatus, cb: (args: {
-        request: AspiRequest<TReq>;
-        response: AspiResponse;
+        request: AspiRequest<TRequest>;
+        response: AspiResponse<any, false>;
     }) => T): T | undefined;
 }
 /**
@@ -606,7 +767,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     error: {};
 }> {
     #private;
-    constructor(method: HttpMethods, path: string, { requestConfig, retryConfig, middlewares, errorCbs, throwOnError, }: RequestOptions<TRequest>);
+    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>);
     /**
      * Sets the base URL for the request.
      * @param url The base URL to set
@@ -615,7 +776,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      * const request = new Request('/users', config);
      * request.setBaseUrl('https://api.example.com');
      */
-    setBaseUrl(url: string): this;
+    setBaseUrl(url: BaseURL): this;
     /**
      * Sets the retry configuration for the request.
      * @param retry The retry configuration object
@@ -631,17 +792,21 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      */
     setRetry(retry: AspiRetryConfig<TRequest>): this;
     /**
-     * Sets multiple headers for the request.
-     * @param headers An object containing header key-value pairs
-     * @returns The request instance for chaining
+     * Merges the provided headers into the request configuration.
+     *
+     * @param {HeadersInit} headers - An object or iterable containing header name/value pairs.
+     *   Existing headers are retained unless a key in this object overwrites them.
+     * @returns {this} The current {@link Request} instance for method chaining.
+     *
      * @example
+     * // Set common JSON headers
      * const request = new Request('/users', config);
      * request.setHeaders({
      *   'Content-Type': 'application/json',
-     *   'Accept': 'application/json'
+     *   'Accept': 'application/json',
      * });
      */
-    setHeaders(headers: Record<string, string>): this;
+    setHeaders(headers: HeadersInit): this;
     /**
      * Sets a single header for the request.
      * @param key The header key
@@ -831,70 +996,126 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         error: { [K in keyof Opts["error"] | "internalServerError"]: K extends "internalServerError" ? CustomError<"internalServerError", A> : Opts["error"][K]; };
     }>>;
     /**
-     * Sets a custom error handler for a specific HTTP status code.
-     * @param tag A string identifier for the error type
-     * @param status The HTTP error status to handle
-     * @param cb The callback function to handle the error
-     * @returns The request instance for chaining
+     * Register a custom error handler for a specific HTTP status code.
+     *
+     * When the response matches the provided `status`, the supplied callback `cb`
+     * is invoked and its return value is wrapped in a {@link CustomError} with the
+     * given `tag`. The method also augments the request's generic `Opts['error']`
+     * type so that the custom error is reflected in the resulting `Result`
+     * union.
+     *
+     * @template Tag - A string literal used as the error tag.
+     * @template A   - The shape of the data returned by the callback.
+     *
+     * @param {Tag} tag
+     *   A unique identifier for the custom error. This value becomes the `tag`
+     *   property of the {@link CustomError} produced by the handler.
+     *
+     * @param {HttpErrorStatus} status
+     *   The HTTP status code (e.g. `'BAD_REQUEST'`, `'NOT_FOUND'`) that should
+     *   trigger the custom handler.
+     *
+     * @param {CustomErrorCb<TRequest, A>} cb
+     *   A callback that receives the failing request and response objects and
+     *   returns an object describing the error payload.
+     *
+     * @returns {Request<Method, TRequest, Merge<Omit<Opts, 'error'>, { error: { [K in Tag | keyof Opts['error']]: K extends Tag ? CustomError<Tag, A> : Opts['error'][K]; } }>>}
+     *   The same {@link Request} instance, now typed with the newly added error
+     *   variant, allowing method‑chaining.
+     *
      * @example
+     * ```ts
      * const request = new Request('/users', config);
+     *
+     * // Attach a custom handler for a 400 Bad Request response
      * request
-        .withResult()
-        .error('customError', 'BAD_REQUEST', (error) => {
-     *   console.log('Bad request error:', error);
-     *   return {
-     *     message: 'Invalid input',
-     *     details: error.response.responseData
-     *   };
-     * });
+     *  withResult()
+     *   .error('customError', 'BAD_REQUEST', (ctx) => {
+     *     console.log('Bad request error:', ctx);
+     *     return {
+     *       message: 'Invalid input',
+     *       details: ctx.response.responseData,
+     *     };
+     *   });
      *
-     * // Later when making the request:
+     * // Later, when executing the request:
      * const result = await request.json();
-     * if (Result.isErr(result)) {
-     *   if(result.tag === 'customError') {
+     * if (Result.isErr(result) && result.tag === 'customError') {
      *   console.log(result.error.data.message); // 'Invalid input'
      * }
+     * ```
      */
     error<Tag extends string, A extends {}>(tag: Tag, status: HttpErrorStatus, cb: CustomErrorCb<TRequest, A>): Request<Method, TRequest, Merge<Omit<Opts, "error">, {
         error: { [K in Tag | keyof Opts["error"]]: K extends Tag ? CustomError<Tag, A> : Opts["error"][K]; };
     }>>;
     /**
-     * Sets query parameters for the request URL.
-     * @param params An object containing query parameter key-value pairs
-     * @returns The request instance for chaining
+     * Sets the query parameters for the request URL.
+     *
+     * Accepts any value that can be passed to the `URLSearchParams` constructor:
+     * - an object mapping keys to string values,
+     * - an iterable of `[key, value]` tuples,
+     * - a raw query string, or
+     * - an existing {@link URLSearchParams} instance.
+     *
+     * The supplied parameters replace any previously defined query parameters.
+     *
+     * @template T - The concrete type of the supplied parameters.
+     * @param {T} params - The query parameters to apply.
+     * @returns {this} The request instance for method‑chaining.
+     *
      * @example
      * const request = new Request('/users', config);
      * request.setQueryParams({
      *   page: '1',
      *   limit: '10',
-     *   sort: 'desc'
+     *   sort: 'desc',
      * });
+     *
+     * // Using a raw query string
+     * request.setQueryParams('page=1&limit=10');
+     *
+     * // Using an array of entries
+     * request.setQueryParams([['page', '1'], ['limit', '10']]);
+     *
+     * // Using an existing URLSearchParams instance
+     * const qp = new URLSearchParams({ page: '1' });
+     * request.setQueryParams(qp);
      */
     setQueryParams<T extends Record<string, string> | string[][] | string | URLSearchParams>(params: T): Request<Method, TRequest, Merge<Omit<Opts, "queryParams">, {
         queryParams: T;
     }>>;
     /**
-     * Sets the output schema for validating the response data using Zod.
-     * @param schema The Zod schema to validate the response
-     * @returns The request instance for chaining
+     * Sets a validation schema for the response data.
+     *
+     * The provided {@link StandardSchemaV1} schema will be used to validate the
+     * response payload when the request is executed. If validation fails, a
+     * `parseError` is added to the request's error type.
+     *
+     * @template TSchema - A type extending {@link StandardSchemaV1}
+     * @param schema - The schema used to validate the response data
+     * @returns The request instance for chaining with an updated generic type that
+     * includes the schema and a possible `parseError` in the error union
+     *
      * @example
+     * ```ts
      * import { z } from 'zod';
      *
      * const userSchema = z.object({
      *   id: z.number(),
      *   name: z.string(),
-     *   email: z.string().email()
+     *   email: z.string().email(),
      * });
      *
      * const request = new Request('/users', config);
      * const result = await request
      *   .withResult()
-     *   .output(userSchema)
+     *   .schema(userSchema)
      *   .json();
      *
      * if (Result.isOk(result)) {
      *   const user = result.value; // Typed and validated user data
      * }
+     * ```
      */
     schema<TSchema extends StandardSchemaV1>(schema: TSchema): Request<Method, TRequest, Merge<Omit<Opts, "schema">, {
         schema: TSchema;
@@ -903,36 +1124,77 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         }>;
     }>>;
     /**
-     * Sets the request to throw an error if the response status is not successful.
-     * @returns The request instance for chaining
+     * Configures the request to **throw** an exception when the response status
+     * indicates a failure (i.e., `!response.ok`). This disables the “Result”
+     * mode (`withResult`) and enables “throwable” mode, causing
+     * `await request.json()` (or other response helpers) to either resolve with
+     * the successful payload **or** reject with an `AspiError`/`CustomError`.
+     *
+     * Use this when you prefer traditional `try / catch` error handling over
+     * the explicit `Result` type returned by {@link withResult}.
+     *
+     * @returns This {@link Request} instance, now typed with `throwable: true` and
+     *          `withResult: false` for proper chaining.
+     *
      * @example
+     * ```ts
      * const request = new Request('/users', config);
-     * const result = await request
-     *   .withResult()
-     *   .throwable()
-     *   .json();
      *
+     * try {
+     *   const user = await request
+     *     .throwable()   // Enable throwing on HTTP errors
+     *     .json<User>(); // Will throw if the response is not ok
+     *   console.log(user);
+     * } catch (err) {
+     *   // err is either AspiError or a CustomError returned by a custom handler
+     *   console.error('Request failed:', err);
+     * }
+     * ```
      */
     throwable(): Request<Method, TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
         withResult: false;
         throwable: true;
     }>>;
     /**
-     * Executes the request and returns the JSON response.
-     * @returns A Promise containing the Result type with either successful data or error information
+     * Sends the request and parses the response body as JSON.
+     *
+     * The resolved value of the returned promise varies based on the request mode:
+     *
+     * - **Result mode** (`withResult()`): resolves to a {@link Result.Result} that
+     *   contains either an {@link AspiResultOk} with the parsed payload or a union
+     *   of possible error types (HTTP errors, custom errors, JSON‑parse errors,
+     *   schema‑validation errors, etc.).
+     *
+     * - **Throwable mode** (`throwable()`): resolves directly to the successful
+     *   payload (`AspiPlainResponse`) and throws a {@link AspiError} or
+     *   {@link CustomError} on failure.
+     *
+     * - **Default mode** (no explicit mode): resolves to a tuple
+     *   `[value, error]` where exactly one element is non‑null.
+     *
+     * @template T - The inferred output type of the response schema (if a schema
+     *   was supplied via {@link schema}). When no schema is provided `T` defaults
+     *   to `any`.
+     *
+     * @returns A promise whose shape depends on the selected mode (see description).
+     *   In Result mode it is `Result<ResultOk<…>, …>`, in throwable mode it is
+     *   `AspiPlainResponse<…>`, and otherwise a tuple
+     *   `[AspiResultOk<…> | null, Error | null]`.
+     *
      * @example
+     * // Using the Result API
      * const request = new Request('/users', config);
      * const result = await request
      *   .setQueryParams({ id: '123' })
-     *   .
-     withResult()
-     *   .notFound((error) => ({ message: 'User not found' }))
+     *   .withResult()
+     *   .notFound(() => ({ message: 'User not found' }))
      *   .json<User>();
      *
      * if (Result.isOk(result)) {
-     *   const user = result.value; // User data
+     *   // `result.value` has type `User`
+     *   console.log(result.value);
      * } else {
-     *   console.error(result.error); // Error handling
+     *   console.error(result.error);
      * }
      */
     json<T extends StandardSchemaV1.InferOutput<Opts['schema']>>(): Promise<Opts['withResult'] extends true ? Result<AspiResultOk<TRequest, T>, AspiError<TRequest> | (Opts extends {
@@ -944,14 +1206,45 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         } ? Opts['error'][keyof Opts['error']] : never) | JSONParseError) | null)
     ]>;
     /**
-     * Executes the request and returns the response as plain text.
-     * @returns A Promise containing the Result type with either successful text data or error information
+     * Executes the request and returns the response body as plain text.
+     *
+     * The method respects the request mode:
+     *
+     * - **Result mode** (`withResult()`): resolves to a {@link Result.Result}
+     *   containing either an {@link AspiResultOk} with the text payload or an
+     *   error variant.
+     * - **Throwable mode** (`throwable()`): resolves directly to the text string
+     *   and throws on error.
+     * - **Default mode**: resolves to a tuple `[value, error]` where exactly one
+     *   element is `null`.
+     *
+     * @returns {Promise<
+     *   Opts['withResult'] extends true
+     *     ? Result.Result<
+     *         AspiResultOk<TRequest, string>,
+     *         AspiError<TRequest> |
+     *         (Opts extends { error: any } ? Opts['error'][keyof Opts['error']] : never)
+     *       >
+     *     : Opts['throwable'] extends true
+     *       ? AspiPlainResponse<TRequest, string>
+     *       : [
+     *           AspiResultOk<TRequest, string> | null,
+     *           (
+     *             | AspiError<TRequest>
+     *             | (Opts extends { error: any } ? Opts['error'][keyof Opts['error']] : never)
+     *             | null
+     *           )
+     *         ]
+     * }>
+     *   A promise that resolves according to the selected request mode.
+     *
      * @example
+     * ```ts
      * const request = new Request('/data.txt', config);
      * const result = await request
      *   .setQueryParams({ version: '1' })
      *   .withResult()
-     *   .notFound((error) => ({ message: 'Text file not found' }))
+     *   .notFound(() => ({ message: 'Text file not found' }))
      *   .text();
      *
      * if (Result.isOk(result)) {
@@ -959,6 +1252,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      * } else {
      *   console.error(result.error); // Error handling
      * }
+     * ```
      */
     text(): Promise<Opts['withResult'] extends true ? Result<AspiResultOk<TRequest, string>, AspiError<TRequest> | (Opts extends {
         error: any;
@@ -969,14 +1263,49 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         } ? Opts['error'][keyof Opts['error']] : never)) | null)
     ]>;
     /**
-     * Executes the request and returns the response as a Blob.
-     * @returns A Promise containing the Result type with either successful Blob data or error information
+     * Executes the request and returns the response body as a {@link Blob}.
+     *
+     * The shape of the returned {@link Promise} depends on the request mode:
+     *
+     * - **Result mode** (`withResult()`): resolves to a {@link Result.Result} containing
+     *   either an {@link AspiResultOk} with `Blob` data or an error variant.
+     * - **Throwable mode** (`throwable()`): resolves directly to a {@link Blob}
+     *   (wrapped in {@link AspiPlainResponse}) and throws on failure.
+     * - **Default mode**: resolves to a tuple `[value, error]` where exactly one element
+     *   is `null`.
+     *
+     * @returns {Promise<
+     *   Opts['withResult'] extends true
+     *     ? Result.Result<
+     *         AspiResultOk<TRequest, Blob>,
+     *         | AspiError<TRequest>
+     *         | (Opts extends { error: any }
+     *             ? Opts['error'][keyof Opts['error']]
+     *             : never)
+     *       >
+     *     : Opts['throwable'] extends true
+     *       ? AspiPlainResponse<TRequest, Blob>
+     *       : [
+     *           AspiResultOk<TRequest, Blob> | null,
+     *           (
+     *             | (
+     *                 | AspiError<TRequest>
+     *                 | (Opts extends { error: any }
+     *                     ? Opts['error'][keyof Opts['error']]
+     *                     : never)
+     *               )
+     *             | null
+     *           ),
+     *         ]
+     * }>
+     *
      * @example
+     * ```ts
      * const request = new Request('/image.jpg', config);
      * const result = await request
      *   .setQueryParams({ size: 'large' })
      *   .withResult()
-     *   .notFound((error) => ({ message: 'Image not found' }))
+     *   .notFound(() => ({ message: 'Image not found' }))
      *   .blob();
      *
      * if (Result.isOk(result)) {
@@ -984,6 +1313,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
      * } else {
      *   console.error(result.error); // Error handling
      * }
+     * ```
      */
     blob(): Promise<Opts['withResult'] extends true ? Result<AspiResultOk<TRequest, Blob>, AspiError<TRequest> | (Opts extends {
         error: any;
@@ -994,33 +1324,122 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         } ? Opts['error'][keyof Opts['error']] : never)) | null)
     ]>;
     /**
-     * Returns the complete URL for the request including base URL, path, and query parameters.
-     * @returns The complete URL string
+     * Returns the fully‑qualified URL that will be used for the request.
+     *
+     * The URL is constructed from the configured base URL, the request path,
+     * and any query parameters added via {@link setQueryParams}.
+     *
+     * @returns {string} The complete request URL.
+     *
      * @example
+     * ```ts
      * const request = new Request('/users', config);
      * request.setBaseUrl('https://api.example.com');
      * request.setQueryParams({ id: '123' });
-     * console.log(request.url()); // 'https://api.example.com/users?id=123'
+     *
+     * console.log(request.url());
+     * // => 'https://api.example.com/users?id=123'
+     * ```
      */
     url(): string;
     /**
-     * Configures the request to return a Result type instead of a tuple.
-     * @returns The request instance for chaining with Result type return value
+     * Switches the request into **Result** mode.
+     *
+     * In Result mode the response helpers (`json`, `text`, `blob`, …) resolve to a
+     * {@link Result.Result} instance instead of the default tuple
+     * `[value, error]`. This allows callers to use pattern matching
+     * (`Result.isOk`, `Result.isErr`) to handle success and failure.
+     *
+     * Calling `withResult` disables the “throwable” behaviour (see {@link throwable}).
+     *
+     * @returns {Request<
+     *   Method,
+     *   TRequest,
+     *   Merge<
+     *     Omit<Opts, 'withResult' | 'throwable'>,
+     *     {
+     *       withResult: true;
+     *       throwable: false;
+     *     }
+     *   >
+     * >} The same {@link Request} instance, now typed with `withResult: true` and
+     * `throwable: false` for fluent chaining.
+     *
      * @example
+     * ```ts
      * const request = new Request('/users', config);
+     *
      * const result = await request
-     *   .withResult()
+     *   .withResult() // enable Result mode
      *   .json<User>();
      *
-     * // Returns Result type instead of tuple
      * if (Result.isOk(result)) {
-     *   const user = result.value;
+     *   // `result.value` is of type `User`
+     *   console.log(result.value);
      * }
+     * ```
      */
     withResult(): Request<Method, TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Returns the underlying {@link AspiRequest} object that will be used for the fetch call.
+     *
+     * This method does not perform any network activity; it simply builds and returns the
+     * request configuration, including any applied middlewares, query parameters, etc.
+     *
+     * @returns {AspiRequest<TRequest>} The constructed request object.
+     */
+    getRequest(): AspiRequest<TRequest>;
+    /**
+     * Retrieves the registry of custom error callbacks that have been
+     * registered via {@link error}. The returned object maps HTTP status
+     * codes to their corresponding callback functions and tags.
+     *
+     * @returns {ErrorCallbacks} A shallow copy of the internal error callback registry.
+     */
+    getErrorCallbackRegistry(): ErrorCallbacks;
+    /**
+     * Returns whether the request is configured to return a {@link Result.Result}
+     * instead of the default tuple or throwing.
+     *
+     * @returns {boolean} `true` when {@link withResult} has been called.
+     */
+    isResult(): boolean;
+    /**
+     * Returns whether the request is configured to throw on HTTP errors.
+     *
+     * @returns {boolean} `true` when {@link throwable} has been called.
+     */
+    isThrowable(): boolean;
+    /**
+     * Returns the effective retry configuration for this request, including defaulted values.
+     *
+     * The returned object contains:
+     * - `retries` – number of retry attempts (default 1)
+     * - `retryDelay` – delay between attempts in milliseconds or a function that returns a delay
+     * - `retryOn` – array of HTTP status codes that should trigger a retry
+     * - `retryWhile` – optional custom predicate executed after each response
+     * - `onRetry` – optional callback invoked after a retry attempt
+     *
+     * A shallow copy is returned to avoid accidental mutation of the internal state.
+     *
+     * @returns {{
+     *   retries: number;
+     *   retryDelay: number | ((attempt: number, maxAttempts: number, request: AspiRequest<TRequest>, response: AspiResponse<any, true>) => number);
+     *   retryOn: number[];
+     *   retryWhile?: (request: AspiRequest<TRequest>, response: AspiResponse<any, true>) => boolean | Promise<boolean>;
+     *   onRetry?: (request: AspiRequest<TRequest>, response: AspiResponse<any, true>) => void;
+     * }}
+     */
+    getRetryConfig(): {
+        retries: number;
+        retryDelay: number | ((remainingRetries: number, totalRetries: number, request: AspiRequest<TRequest>, response: AspiResponse) => number | Promise<number>);
+        retryOn: HttpErrorCodes[];
+        retryWhile: ((request: AspiRequest<TRequest>, response: AspiResponse) => boolean | Promise<boolean>) | undefined;
+        onRetry: ((request: AspiRequest<TRequest>, response: AspiResponse) => void) | undefined;
+    };
 }
 
 /**
@@ -1040,16 +1459,20 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
  */
 declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts extends Record<any, any> = {}> {
     #private;
-    constructor(config: AspiConfig);
+    constructor(config: AspiRequestInitWithoutBodyAndMethod);
     /**
-     * Sets the base URL for all API requests
-     * @param {string} url - The base URL to be set
-     * @returns {Aspi} The Aspi instance for chaining
+     * Sets or overrides the base URL used for all subsequent API requests.
+     *
+     * Accepts either a string or a `URL` instance. If a `URL` object is provided,
+     * it is converted to its string representation.
+     *
+     * @param url - The new base URL.
+     * @returns The current {@link Aspi} instance for chaining.
      * @example
      * const api = new Aspi({ baseUrl: 'https://api.example.com' });
      * api.setBaseUrl('https://api.newdomain.com');
      */
-    setBaseUrl(url: string): this;
+    setBaseUrl(url: string | URL): this;
     /**
      * Sets the retry configuration for failed requests
      * @param {AspiRetryConfig<TRequest>} retry - The retry configuration object
@@ -1074,35 +1497,34 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
      */
     get(path: string): Request<"GET", TRequest, Opts>;
     /**
-     * Makes a POST request to the specified path with an optional body
-     * @param {string} path - The path to make the request to
-     * @param {BodyInit} [body] - The body of the request
-     * @returns {Request} A Request instance for chaining
+     * Makes a POST request to the specified path.
+     *
+     * @param {string} path - The path to make the request to.
+     * @returns {Request} A Request instance for chaining.
+     *
      * @example
      * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-     * const response = await api.post('/users', { name: 'John' }).json();
+     * const response = await api.post('/users').json();
      */
-    post(path: string, body?: BodyInit): Request<"POST", TRequest, Opts>;
+    post(path: string): Request<"POST", TRequest, Opts>;
     /**
-     * Makes a PUT request to the specified path with an optional body
-     * @param {string} path - The path to make the request to
-     * @param {BodyInit} [body] - The body of the request
-     * @returns {Request} A Request instance for chaining
+     * Makes a PUT request to the specified path.
+     * @param {string} path - The path to make the request to.
+     * @returns {Request} A Request instance for chaining.
      * @example
      * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-     * const response = await api.put('/users/1', { name: 'John' }).json();
+     * const response = await api.put('/users/1').json();
      */
-    put(path: string, body?: BodyInit): Request<"PUT", TRequest, Opts>;
+    put(path: string): Request<"PUT", TRequest, Opts>;
     /**
-     * Makes a PATCH request to the specified path with an optional body
-     * @param {string} path - The path to make the request to
-     * @param {BodyInit} [body] - The body of the request
-     * @returns {Request} A Request instance for chaining
+     * Makes a PATCH request to the specified path.
+     * @param {string} path - The path to make the request to.
+     * @returns {Request} A Request instance for chaining.
      * @example
      * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-     * const response = await api.patch('/users/1', { name: 'John' }).json();
+     * const response = await api.patch('/users/1').json();
      */
-    patch(path: string, body?: BodyInit): Request<"PATCH", TRequest, Opts>;
+    patch(path: string): Request<"PATCH", TRequest, Opts>;
     /**
      * Makes a DELETE request to the specified path
      * @param {string} path - The path to make the request to
@@ -1131,8 +1553,9 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
      */
     options(path: string): Request<"OPTIONS", TRequest, Opts>;
     /**
-     * Sets multiple headers for all API requests
-     * @param {Record<string, string>} headers - An object containing header key-value pairs
+     * Sets multiple headers for all API requests. Existing headers are preserved
+     * and new ones are merged, overriding any duplicate keys.
+     * @param {HeadersInit} headers - An object containing header key-value pairs
      * @returns {Aspi} The Aspi instance for chaining
      * @example
      * const api = new Aspi({ baseUrl: 'https://api.example.com' });
@@ -1141,12 +1564,14 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
      *   'Accept': 'application/json'
      * });
      */
-    setHeaders(headers: Record<string, string>): this;
+    setHeaders(headers: HeadersInit): this;
     /**
-     * Sets a single header for all API requests
-     * @param {string} key - The header key
-     * @param {string} value - The header value
-     * @returns {Aspi} The Aspi instance for chaining
+     * Sets a single header for all API requests.
+     *
+     * @param key - The header name.
+     * @param value - The header value.
+     * @returns This {@link Aspi} instance for chaining.
+     *
      * @example
      * const api = new Aspi({ baseUrl: 'https://api.example.com' });
      * api.setHeader('Content-Type', 'application/json');
@@ -1162,21 +1587,31 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
      */
     setBearer(token: string): this;
     /**
-     * Use a middleware function to transform requests
-     * @param {Middleware<T, U>} fn - The middleware function to apply
-     * @returns {Aspi<U>} A new Aspi instance with the applied middleware
+     * Register a request‑transformer middleware.
+     *
+     * The supplied function receives the current request initialization object
+     * (`T`) and must return a request initialization of type `U`. The middleware
+     * is added to the internal middleware chain and will be applied to every
+     * request created by this {@link Aspi} instance.
+     *
+     * @template T - The input request type, extending the current {@link Aspi} request init type.
+     * @template U - The output request type after transformation.
+     * @param {RequestTransformer<T, U>} fn - The middleware function that transforms a request configuration.
+     * @returns {Aspi<U>} A new {@link Aspi} instance typed with the transformed request configuration.
      * @example
      * const api = new Aspi({ baseUrl: 'https://api.example.com' });
-     * api.use((req) => {
-     *   // Add custom headers
-     *   req.headers = {
-     *     ...req.headers,
-     *     'x-custom-header': 'custom-value'
+     * const apiWithHeaders = api.use((req) => {
+     *   // Add custom headers to every request
+     *   return {
+     *     ...req,
+     *     headers: {
+     *       ...req.headers,
+     *       'x-custom-header': 'custom-value',
+     *     },
      *   };
-     *   return req;
      * });
      */
-    use<T extends TRequest, U extends TRequest>(fn: Middleware<T, U>): Aspi<U>;
+    use<T extends TRequest, U extends TRequest>(fn: RequestTransformer<T, U>): Aspi<U>;
     /**
      * Registers a custom error handler for a specific HTTP status
      * @param {string} tag - The error tag identifier
@@ -1296,9 +1731,18 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
      *   .json();
      *
      */
-    throwable(): Aspi<TRequest, Prettify<Opts & {
+    throwable(): Aspi<TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
+        withResult: false;
         throwable: true;
     }>>;
+    /**
+     * Configures the request to return a Result object instead of just the response body.
+     * @returns The Aspi instance with result handling enabled.
+     */
+    withResult(): Aspi<TRequest, Merge<Omit<Opts, "withResult" | "throwable">, {
+        withResult: true;
+        throwable: false;
+    }>>;
 }
 
-export { Aspi, type AspiConfig, type AspiConfigBase, AspiError, type AspiPlainResponse, type AspiRequest, type AspiRequestInit, type AspiResponse, type AspiResultOk, type AspiRetryConfig, CustomError, type CustomErrorCb, type ErrorCallbacks, type HttpErrorCodes, type HttpErrorStatus, type HttpMethods, type JSONParseError, type Merge, type Middleware, type Prettify, Request, type RequestOptions, result as Result, getHttpErrorStatus, httpErrors, isAspiError, isCustomError };
+export { Aspi, type AspiConfigBase, AspiError, type AspiPlainResponse, type AspiRequest, type AspiRequestInit, type AspiRequestInitWithoutBodyAndMethod, type AspiResponse, type AspiResultOk, type AspiRetryConfig, type BaseURL, CustomError, type CustomErrorCb, type ErrorCallbacks, type HttpErrorCodes, type HttpErrorStatus, type HttpMethods, type JSONParseError, type Merge, type Prettify, Request, type RequestOptions, type RequestTransformer, result as Result, getHttpErrorStatus, httpErrors, isAspiError, isCustomError };