aspi 2.1.0 → 2.2.1

package/README.md

@@ -189,15 +189,15 @@ try {
 // Result mode wins (throwable is ignored)
 const result = await api
   .post('/login')
-  .withResult() // enables Result mode
-  .throwable() // ignored because withResult was called later
+  .withResult() // ignored because throwable was called later
+  .throwable() // enables throwable mode
   .json<{ token: string }>();
 
 // Throwable mode wins (Result is ignored)
 const data = await api
   .get('/profile')
-  .throwable() // enables throwable mode
-  .withResult() // ignored because throwable was called later
+  .throwable() // ignored because withResult was called later
+  .withResult() // enables Result mode
   .json();
 ```
 
@@ -537,6 +537,220 @@ class Request<
 
 ---
 
+## Result utilities
+
+`Result<T, E>` is a small tagged-union helper used throughout Aspi to represent success or failure without throwing.
+
+```ts
+type Ok<T> = { __tag: 'ok'; value: T };
+type Err<E> = { __tag: 'err'; error: E };
+type Result<T, E> = Ok<T> | Err<E>;
+```
+
+Creating Results
+
+```ts
+import * as Result from './result';
+
+const success = Result.ok(42);
+const failure = Result.err('not found');
+```
+
+Checking and Extracting
+
+```ts
+if (Result.isOk(success)) {
+  console.log(success.value); // 42
+}
+
+if (Result.isErr(failure)) {
+  console.error(failure.error); // "not found"
+}
+
+const valueOrNull = Result.getOrNull(success); // 42 | null
+const errorOrNull = Result.getErrorOrNull(failure); // "not found" | null
+
+const valueOrFallback = Result.getOrElse(failure, 0); // 0
+
+// Throwing
+const mustHaveValue = Result.getOrThrow(success); // 42
+// Result.getOrThrow(failure) throws "not found"
+```
+
+Transforming
+
+```ts
+// map value
+const doubled = Result.map(success, (n) => n * 2); // ok(84)
+
+// map error
+const upperError = Result.mapErr(failure, (e) => e.toUpperCase()); // err("NOT FOUND")
+
+// pattern matching
+const message = Result.match(success, {
+  onOk: (n) => `Got ${n}`,
+  onErr: (e) => `Error: ${e}`,
+});
+// "Got 42"
+```
+
+Tagged error helpers
+When your error type is a union with a tag field, you can use helpers to handle specific variants:
+
+```ts
+type HttpError =
+  | { tag: 'BAD_REQUEST'; details?: string }
+  | { tag: 'UNAUTHORIZED' }
+  | { tag: 'NOT_FOUND' };
+
+const result: Result<number, HttpError> = Result.err({
+  tag: 'NOT_FOUND',
+});
+
+// Handle a specific tag
+Result.catchError(result, 'NOT_FOUND', (e) => {
+  console.log('Missing resource');
+});
+
+// Handle multiple tags
+Result.catchErrors(result, {
+  BAD_REQUEST: (e) => console.log('Invalid input'),
+  UNAUTHORIZED: () => console.log('Please log in'),
+});
+```
+
+Pipe Utility
+
+```ts
+import { pipe } from './result';
+
+const label = pipe(
+  12345,
+  (cents) => cents / 100,
+  (amount) => amount.toFixed(2),
+  (str) => `$${str}`,
+);
+// "$123.45"
+```
+
+---
+
+## Experimental capabilities
+
+> **Experimental:** This API is still evolving. Names and behavior may change in minor versions.
+
+Capabilities are small plugins that wrap the low‑level fetch call for each request. They let you implement cross‑cutting behavior (logging, retries, token refresh, tracing, etc.) without changing Aspi core.
+
+```ts
+import type { Capability } from './interceptor';
+import { Aspi } from './aspi';
+
+// Capability signature
+const myCapability: Capability = ({ request }) => ({
+  async run(runner) {
+    // Called before fetch
+    console.log('→', request.path);
+
+    const res = await runner(); // performs fetch(url, requestInit)
+
+    // Called after fetch
+    console.log('←', res.status, res.statusText);
+
+    return res;
+  },
+});
+```
+
+Registering capabilities
+Capabilities are attached at the Aspi client level and apply to all requests created from that instance:
+
+```ts
+const api = new Aspi({ baseUrl: 'https://api.example.com' }).useCapability(
+  myCapability,
+);
+
+const user = await api.get('/users/1').throwable().json<User>();
+```
+
+You can register multiple capabilities; they execute in the order they were added, each wrapping the next:
+
+```ts
+const api = new Aspi({ baseUrl: 'https://api.example.com' })
+  .useCapability(loggingCapability)
+  .useCapability(tracingCapability)
+  .useCapability(refreshTokenCapability);
+```
+
+Example: token refresh (simplified)
+
+```ts
+import type { Capability } from './interceptor';
+import { Aspi } from './aspi';
+import * as Result from './result';
+
+let tokens: { accessToken: string | null; refreshToken: string | null } = {
+  accessToken: null,
+  refreshToken: null,
+};
+
+async function refreshTokenRequest(refreshToken: string) {
+  const res = await new Aspi({ baseUrl: 'https://auth.example.com' })
+    .post('/refresh')
+    .bodyJson({ refreshToken })
+    .withResult()
+    .json<{ accessToken: string; refreshToken: string }>();
+
+  await Result.match(res, {
+    onOk: ({ data }) => {
+      tokens = data;
+    },
+    onErr: (err) => {
+      tokens = { accessToken: null, refreshToken: null };
+      throw err;
+    },
+  });
+}
+
+export const refreshTokenCapability: Capability = ({ request }) => {
+  let isRefreshing = false;
+
+  return {
+    async run(runner) {
+      // First try
+      const first = await runner();
+
+      if (first.status !== 401) {
+        return first;
+      }
+
+      // No refresh token → just propagate 401
+      if (!tokens.refreshToken || isRefreshing) {
+        return first;
+      }
+
+      isRefreshing = true;
+      try {
+        await refreshTokenRequest(tokens.refreshToken);
+      } finally {
+        isRefreshing = false;
+      }
+
+      if (!tokens.accessToken) {
+        return first;
+      }
+
+      // Inject new Authorization header and retry once
+      request.requestInit.headers = {
+        ...request.requestInit.headers,
+        Authorization: `Bearer ${tokens.accessToken}`,
+      };
+
+      return runner();
+    },
+  };
+};
+```
+
 ## License
 
 MIT © Aspi contributors

package/dist/index.cjs

@@ -315,7 +315,8 @@ var Request = class {
   #shouldBeResult = false;
   #bodySchemaIssues = [];
   #throwOnError = false;
-  constructor(method, path, requestOptions) {
+  #capabilities = [];
+  constructor(method, path, requestOptions, capabilities = []) {
     this.#path = path;
     this.#middlewares = requestOptions.middlewares || [];
     this.#localRequestInit = {
@@ -326,6 +327,7 @@ var Request = class {
     this.#customErrorCbs = { ...requestOptions?.errorCbs || {} };
     this.#throwOnError = requestOptions.throwOnError || false;
     this.#shouldBeResult = requestOptions.shouldBeResult || false;
+    this.#capabilities = [...capabilities];
   }
   /**
    * Sets the base URL for the request.
@@ -1076,7 +1078,15 @@ var Request = class {
       let responseData = null;
       while (attempts <= retries) {
         try {
-          response = await fetch(url, requestInit);
+          if (this.#capabilities.length > 0) {
+            for (const capability of this.#capabilities) {
+              response = await capability({ request }).run(
+                () => fetch(url, requestInit)
+              );
+            }
+          } else {
+            response = await fetch(url, requestInit);
+          }
           responseData = await responseParser(response);
           if (responseData instanceof Error) {
             return err(responseData);
@@ -1336,6 +1346,51 @@ var Request = class {
     const cfg = this.#sanitisedRetryConfig();
     return { ...cfg };
   }
+  /**
+   * Registers a capability for this request.
+   *
+   * A capability is a small wrapper around the underlying `fetch` call that can
+   * intercept, inspect, or modify the request/response lifecycle. Each registered
+   * capability receives the constructed {@link AspiRequest} and can wrap the
+   * execution of the network call via its `run` method.
+   *
+   * Capabilities are applied in the order they are registered. For each HTTP
+   * call, the `Request` will:
+   *
+   * 1. Build an {@link AspiRequest} from the current configuration.
+   * 2. Create a runner: `() => fetch(url, requestInit)`.
+   * 3. Pass that runner through each capability in sequence, allowing them to:
+   *    - log or trace requests,
+   *    - implement retry/refresh logic,
+   *    - short‑circuit with synthetic responses, etc.
+   *
+   * @param capability - The capability factory to register. It will be invoked
+   *   for every execution of this request with the current {@link AspiRequest}.
+   *
+   * @returns This {@link Request} instance, enabling fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+   *
+   * const apiWithLogging = api.useCapability(({ request }) => ({
+   *   async run(runner) {
+   *     console.log('→', request.path, request.requestInit);
+   *     const res = await runner();
+   *     console.log('←', res.status, res.statusText);
+   *     return res;
+   *   },
+   * }));
+   *
+   * const result = await apiWithLogging
+   *   .get('/users')
+   *   .withResult()
+   *   .json();
+   * ```
+   */
+  useCapability(capability) {
+    return this.#capabilities.push(capability);
+  }
 };
 
 // src/aspi.ts
@@ -1346,6 +1401,7 @@ var Aspi = class {
   #customErrorCbs = {};
   #throwOnError = false;
   #shouldBeResult = false;
+  #capabilities = [];
   constructor(config) {
     const { retryConfig, ...requestInit } = config;
     this.#globalRequestInit = requestInit;
@@ -1388,17 +1444,22 @@ var Aspi = class {
     return this;
   }
   #createRequest(method, path) {
-    return new Request(method, path, {
-      requestConfig: {
-        ...this.#globalRequestInit,
-        method
+    return new Request(
+      method,
+      path,
+      {
+        requestConfig: {
+          ...this.#globalRequestInit,
+          method
+        },
+        middlewares: this.#middlewares,
+        errorCbs: this.#customErrorCbs,
+        throwOnError: this.#throwOnError,
+        shouldBeResult: this.#shouldBeResult,
+        retryConfig: this.#retryConfig
       },
-      middlewares: this.#middlewares,
-      errorCbs: this.#customErrorCbs,
-      throwOnError: this.#throwOnError,
-      shouldBeResult: this.#shouldBeResult,
-      retryConfig: this.#retryConfig
-    });
+      this.#capabilities
+    );
   }
   /**
    * Makes a GET request to the specified path
@@ -1693,6 +1754,47 @@ var Aspi = class {
     this.#throwOnError = false;
     return this;
   }
+  /**
+   * Registers a capability on this {@link Aspi} instance.
+   *
+   * A capability is a small, pluggable unit that can intercept and wrap the
+   * low‑level `fetch` call used by all requests created from this client.
+   * It is invoked for every request with the constructed {@link AspiRequest},
+   * and can:
+   *
+   * - inspect or mutate the outgoing request (e.g. inject auth headers),
+   * - inspect the raw {@link Response},
+   * - implement cross‑cutting concerns such as logging, tracing, retries,
+   *   or token refresh, and
+   * - short‑circuit the network call by returning a synthetic {@link Response}.
+   *
+   * Capabilities registered on the {@link Aspi} instance are propagated to every
+   * {@link Request} created via methods like {@link get}, {@link post}, etc.
+   * They are applied in the order they are registered.
+   *
+   * @param capability - The capability factory to install on this client.
+   *
+   * @returns This {@link Aspi} instance for fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+   *   .useCapability(({ request }) => ({
+   *     async run(runner) {
+   *       console.log('→', request.path);
+   *       const res = await runner();
+   *       console.log('←', res.status);
+   *       return res;
+   *     },
+   *   }));
+   *
+   * const user = await api.get('/users/1').throwable().json<User>();
+   * ```
+   */
+  useCapability(capability) {
+    this.#capabilities.push(capability);
+    return this;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/index.d.cts

@@ -366,6 +366,72 @@ interface JSONParseError extends CustomError<'jsonParseError', {
 declare const isAspiError: <TReq extends AspiRequestInit>(error: unknown) => error is AspiError<TReq>;
 declare const isCustomError: <Tag extends string, A>(error: unknown) => error is CustomError<Tag, A>;
 
+/**
+ * Arguments passed to a capability factory.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ */
+type CapabilityArgs<T extends AspiRequestInit = AspiRequestInit> = {
+    /**
+     * The fully constructed AspiRequest that will be used to execute `fetch`.
+     *
+     * You can:
+     * - inspect `request.path`, `request.requestInit`, `request.retryConfig`, etc.
+     * - mutate `request.requestInit.headers`, `signal`, or other properties
+     *   before the network call is made.
+     */
+    request: AspiRequest<T>;
+};
+/**
+ * A capability is a small wrapper around the low-level `fetch` call that can
+ * intercept outgoing requests and incoming responses.
+ *
+ * It is a factory function that receives the current {@link AspiRequest}
+ * and returns an object exposing a single `run` method. The `run` method is
+ * responsible for invoking the provided `runner` (which performs the actual
+ * `fetch`) and may:
+ *
+ * - call `runner()` directly and return its result
+ * - call `runner()` multiple times (e.g. retry, refresh token then retry)
+ * - short‑circuit by *not* calling `runner()` and returning a synthetic
+ *   {@link Response} instead
+ *
+ * Capabilities are composed in the order they are registered via
+ * `Aspi.useCapability`, with each capability wrapping the next one in the
+ * chain.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ *
+ * @example
+ * ```ts
+ * // Simple logging capability
+ * const loggingCapability: Capability = ({ request }) => ({
+ *   async run(runner) {
+ *     console.log('→', request.path, request.requestInit);
+ *     const res = await runner();
+ *     console.log('←', res.status, res.statusText);
+ *     return res;
+ *   },
+ * });
+ *
+ * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+ *   .useCapability(loggingCapability);
+ * ```
+ */
+type Capability<T extends AspiRequestInit = AspiRequestInit> = ({ request, }: CapabilityArgs<T>) => {
+    /**
+     * Executes the next step in the capability chain.
+     *
+     * @param runner - A function that, when called, performs the actual
+     *   network request (or the next capability in the chain) and resolves to
+     *   a {@link Response}.
+     *
+     * @returns A promise resolving to the final {@link Response} that should be
+     *   used by Aspi for this request.
+     */
+    run: (runner: () => Promise<Response>) => Promise<Response>;
+};
+
 type Ok<T> = {
     __tag: 'ok';
     value: T;
@@ -768,7 +834,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     error: {};
 }> {
     #private;
-    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>);
+    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>, capabilities?: Capability<TRequest>[]);
     /**
      * Sets the base URL for the request.
      * @param url The base URL to set
@@ -1441,6 +1507,49 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         retryWhile: ((request: AspiRequest<TRequest>, response: AspiResponse) => boolean | Promise<boolean>) | undefined;
         onRetry: ((request: AspiRequest<TRequest>, response: AspiResponse) => void) | undefined;
     };
+    /**
+     * Registers a capability for this request.
+     *
+     * A capability is a small wrapper around the underlying `fetch` call that can
+     * intercept, inspect, or modify the request/response lifecycle. Each registered
+     * capability receives the constructed {@link AspiRequest} and can wrap the
+     * execution of the network call via its `run` method.
+     *
+     * Capabilities are applied in the order they are registered. For each HTTP
+     * call, the `Request` will:
+     *
+     * 1. Build an {@link AspiRequest} from the current configuration.
+     * 2. Create a runner: `() => fetch(url, requestInit)`.
+     * 3. Pass that runner through each capability in sequence, allowing them to:
+     *    - log or trace requests,
+     *    - implement retry/refresh logic,
+     *    - short‑circuit with synthetic responses, etc.
+     *
+     * @param capability - The capability factory to register. It will be invoked
+     *   for every execution of this request with the current {@link AspiRequest}.
+     *
+     * @returns This {@link Request} instance, enabling fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+     *
+     * const apiWithLogging = api.useCapability(({ request }) => ({
+     *   async run(runner) {
+     *     console.log('→', request.path, request.requestInit);
+     *     const res = await runner();
+     *     console.log('←', res.status, res.statusText);
+     *     return res;
+     *   },
+     * }));
+     *
+     * const result = await apiWithLogging
+     *   .get('/users')
+     *   .withResult()
+     *   .json();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): number;
 }
 
 /**
@@ -1744,6 +1853,44 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Registers a capability on this {@link Aspi} instance.
+     *
+     * A capability is a small, pluggable unit that can intercept and wrap the
+     * low‑level `fetch` call used by all requests created from this client.
+     * It is invoked for every request with the constructed {@link AspiRequest},
+     * and can:
+     *
+     * - inspect or mutate the outgoing request (e.g. inject auth headers),
+     * - inspect the raw {@link Response},
+     * - implement cross‑cutting concerns such as logging, tracing, retries,
+     *   or token refresh, and
+     * - short‑circuit the network call by returning a synthetic {@link Response}.
+     *
+     * Capabilities registered on the {@link Aspi} instance are propagated to every
+     * {@link Request} created via methods like {@link get}, {@link post}, etc.
+     * They are applied in the order they are registered.
+     *
+     * @param capability - The capability factory to install on this client.
+     *
+     * @returns This {@link Aspi} instance for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+     *   .useCapability(({ request }) => ({
+     *     async run(runner) {
+     *       console.log('→', request.path);
+     *       const res = await runner();
+     *       console.log('←', res.status);
+     *       return res;
+     *     },
+     *   }));
+     *
+     * const user = await api.get('/users/1').throwable().json<User>();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): this;
 }
 
 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 };

package/dist/index.d.ts

@@ -366,6 +366,72 @@ interface JSONParseError extends CustomError<'jsonParseError', {
 declare const isAspiError: <TReq extends AspiRequestInit>(error: unknown) => error is AspiError<TReq>;
 declare const isCustomError: <Tag extends string, A>(error: unknown) => error is CustomError<Tag, A>;
 
+/**
+ * Arguments passed to a capability factory.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ */
+type CapabilityArgs<T extends AspiRequestInit = AspiRequestInit> = {
+    /**
+     * The fully constructed AspiRequest that will be used to execute `fetch`.
+     *
+     * You can:
+     * - inspect `request.path`, `request.requestInit`, `request.retryConfig`, etc.
+     * - mutate `request.requestInit.headers`, `signal`, or other properties
+     *   before the network call is made.
+     */
+    request: AspiRequest<T>;
+};
+/**
+ * A capability is a small wrapper around the low-level `fetch` call that can
+ * intercept outgoing requests and incoming responses.
+ *
+ * It is a factory function that receives the current {@link AspiRequest}
+ * and returns an object exposing a single `run` method. The `run` method is
+ * responsible for invoking the provided `runner` (which performs the actual
+ * `fetch`) and may:
+ *
+ * - call `runner()` directly and return its result
+ * - call `runner()` multiple times (e.g. retry, refresh token then retry)
+ * - short‑circuit by *not* calling `runner()` and returning a synthetic
+ *   {@link Response} instead
+ *
+ * Capabilities are composed in the order they are registered via
+ * `Aspi.useCapability`, with each capability wrapping the next one in the
+ * chain.
+ *
+ * @template T - The concrete request-init type used by this Aspi instance.
+ *
+ * @example
+ * ```ts
+ * // Simple logging capability
+ * const loggingCapability: Capability = ({ request }) => ({
+ *   async run(runner) {
+ *     console.log('→', request.path, request.requestInit);
+ *     const res = await runner();
+ *     console.log('←', res.status, res.statusText);
+ *     return res;
+ *   },
+ * });
+ *
+ * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+ *   .useCapability(loggingCapability);
+ * ```
+ */
+type Capability<T extends AspiRequestInit = AspiRequestInit> = ({ request, }: CapabilityArgs<T>) => {
+    /**
+     * Executes the next step in the capability chain.
+     *
+     * @param runner - A function that, when called, performs the actual
+     *   network request (or the next capability in the chain) and resolves to
+     *   a {@link Response}.
+     *
+     * @returns A promise resolving to the final {@link Response} that should be
+     *   used by Aspi for this request.
+     */
+    run: (runner: () => Promise<Response>) => Promise<Response>;
+};
+
 type Ok<T> = {
     __tag: 'ok';
     value: T;
@@ -768,7 +834,7 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
     error: {};
 }> {
     #private;
-    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>);
+    constructor(method: HttpMethods, path: string, requestOptions: RequestOptions<TRequest>, capabilities?: Capability<TRequest>[]);
     /**
      * Sets the base URL for the request.
      * @param url The base URL to set
@@ -1441,6 +1507,49 @@ declare class Request<Method extends HttpMethods, TRequest extends AspiRequestIn
         retryWhile: ((request: AspiRequest<TRequest>, response: AspiResponse) => boolean | Promise<boolean>) | undefined;
         onRetry: ((request: AspiRequest<TRequest>, response: AspiResponse) => void) | undefined;
     };
+    /**
+     * Registers a capability for this request.
+     *
+     * A capability is a small wrapper around the underlying `fetch` call that can
+     * intercept, inspect, or modify the request/response lifecycle. Each registered
+     * capability receives the constructed {@link AspiRequest} and can wrap the
+     * execution of the network call via its `run` method.
+     *
+     * Capabilities are applied in the order they are registered. For each HTTP
+     * call, the `Request` will:
+     *
+     * 1. Build an {@link AspiRequest} from the current configuration.
+     * 2. Create a runner: `() => fetch(url, requestInit)`.
+     * 3. Pass that runner through each capability in sequence, allowing them to:
+     *    - log or trace requests,
+     *    - implement retry/refresh logic,
+     *    - short‑circuit with synthetic responses, etc.
+     *
+     * @param capability - The capability factory to register. It will be invoked
+     *   for every execution of this request with the current {@link AspiRequest}.
+     *
+     * @returns This {@link Request} instance, enabling fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+     *
+     * const apiWithLogging = api.useCapability(({ request }) => ({
+     *   async run(runner) {
+     *     console.log('→', request.path, request.requestInit);
+     *     const res = await runner();
+     *     console.log('←', res.status, res.statusText);
+     *     return res;
+     *   },
+     * }));
+     *
+     * const result = await apiWithLogging
+     *   .get('/users')
+     *   .withResult()
+     *   .json();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): number;
 }
 
 /**
@@ -1744,6 +1853,44 @@ declare class Aspi<TRequest extends AspiRequestInit = AspiRequestInit, Opts exte
         withResult: true;
         throwable: false;
     }>>;
+    /**
+     * Registers a capability on this {@link Aspi} instance.
+     *
+     * A capability is a small, pluggable unit that can intercept and wrap the
+     * low‑level `fetch` call used by all requests created from this client.
+     * It is invoked for every request with the constructed {@link AspiRequest},
+     * and can:
+     *
+     * - inspect or mutate the outgoing request (e.g. inject auth headers),
+     * - inspect the raw {@link Response},
+     * - implement cross‑cutting concerns such as logging, tracing, retries,
+     *   or token refresh, and
+     * - short‑circuit the network call by returning a synthetic {@link Response}.
+     *
+     * Capabilities registered on the {@link Aspi} instance are propagated to every
+     * {@link Request} created via methods like {@link get}, {@link post}, etc.
+     * They are applied in the order they are registered.
+     *
+     * @param capability - The capability factory to install on this client.
+     *
+     * @returns This {@link Aspi} instance for fluent chaining.
+     *
+     * @example
+     * ```ts
+     * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+     *   .useCapability(({ request }) => ({
+     *     async run(runner) {
+     *       console.log('→', request.path);
+     *       const res = await runner();
+     *       console.log('←', res.status);
+     *       return res;
+     *     },
+     *   }));
+     *
+     * const user = await api.get('/users/1').throwable().json<User>();
+     * ```
+     */
+    useCapability(capability: Capability<TRequest>): this;
 }
 
 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 };

package/dist/index.js

@@ -287,7 +287,8 @@ var Request = class {
   #shouldBeResult = false;
   #bodySchemaIssues = [];
   #throwOnError = false;
-  constructor(method, path, requestOptions) {
+  #capabilities = [];
+  constructor(method, path, requestOptions, capabilities = []) {
     this.#path = path;
     this.#middlewares = requestOptions.middlewares || [];
     this.#localRequestInit = {
@@ -298,6 +299,7 @@ var Request = class {
     this.#customErrorCbs = { ...requestOptions?.errorCbs || {} };
     this.#throwOnError = requestOptions.throwOnError || false;
     this.#shouldBeResult = requestOptions.shouldBeResult || false;
+    this.#capabilities = [...capabilities];
   }
   /**
    * Sets the base URL for the request.
@@ -1048,7 +1050,15 @@ var Request = class {
       let responseData = null;
       while (attempts <= retries) {
         try {
-          response = await fetch(url, requestInit);
+          if (this.#capabilities.length > 0) {
+            for (const capability of this.#capabilities) {
+              response = await capability({ request }).run(
+                () => fetch(url, requestInit)
+              );
+            }
+          } else {
+            response = await fetch(url, requestInit);
+          }
           responseData = await responseParser(response);
           if (responseData instanceof Error) {
             return err(responseData);
@@ -1308,6 +1318,51 @@ var Request = class {
     const cfg = this.#sanitisedRetryConfig();
     return { ...cfg };
   }
+  /**
+   * Registers a capability for this request.
+   *
+   * A capability is a small wrapper around the underlying `fetch` call that can
+   * intercept, inspect, or modify the request/response lifecycle. Each registered
+   * capability receives the constructed {@link AspiRequest} and can wrap the
+   * execution of the network call via its `run` method.
+   *
+   * Capabilities are applied in the order they are registered. For each HTTP
+   * call, the `Request` will:
+   *
+   * 1. Build an {@link AspiRequest} from the current configuration.
+   * 2. Create a runner: `() => fetch(url, requestInit)`.
+   * 3. Pass that runner through each capability in sequence, allowing them to:
+   *    - log or trace requests,
+   *    - implement retry/refresh logic,
+   *    - short‑circuit with synthetic responses, etc.
+   *
+   * @param capability - The capability factory to register. It will be invoked
+   *   for every execution of this request with the current {@link AspiRequest}.
+   *
+   * @returns This {@link Request} instance, enabling fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' });
+   *
+   * const apiWithLogging = api.useCapability(({ request }) => ({
+   *   async run(runner) {
+   *     console.log('→', request.path, request.requestInit);
+   *     const res = await runner();
+   *     console.log('←', res.status, res.statusText);
+   *     return res;
+   *   },
+   * }));
+   *
+   * const result = await apiWithLogging
+   *   .get('/users')
+   *   .withResult()
+   *   .json();
+   * ```
+   */
+  useCapability(capability) {
+    return this.#capabilities.push(capability);
+  }
 };
 
 // src/aspi.ts
@@ -1318,6 +1373,7 @@ var Aspi = class {
   #customErrorCbs = {};
   #throwOnError = false;
   #shouldBeResult = false;
+  #capabilities = [];
   constructor(config) {
     const { retryConfig, ...requestInit } = config;
     this.#globalRequestInit = requestInit;
@@ -1360,17 +1416,22 @@ var Aspi = class {
     return this;
   }
   #createRequest(method, path) {
-    return new Request(method, path, {
-      requestConfig: {
-        ...this.#globalRequestInit,
-        method
+    return new Request(
+      method,
+      path,
+      {
+        requestConfig: {
+          ...this.#globalRequestInit,
+          method
+        },
+        middlewares: this.#middlewares,
+        errorCbs: this.#customErrorCbs,
+        throwOnError: this.#throwOnError,
+        shouldBeResult: this.#shouldBeResult,
+        retryConfig: this.#retryConfig
       },
-      middlewares: this.#middlewares,
-      errorCbs: this.#customErrorCbs,
-      throwOnError: this.#throwOnError,
-      shouldBeResult: this.#shouldBeResult,
-      retryConfig: this.#retryConfig
-    });
+      this.#capabilities
+    );
   }
   /**
    * Makes a GET request to the specified path
@@ -1665,6 +1726,47 @@ var Aspi = class {
     this.#throwOnError = false;
     return this;
   }
+  /**
+   * Registers a capability on this {@link Aspi} instance.
+   *
+   * A capability is a small, pluggable unit that can intercept and wrap the
+   * low‑level `fetch` call used by all requests created from this client.
+   * It is invoked for every request with the constructed {@link AspiRequest},
+   * and can:
+   *
+   * - inspect or mutate the outgoing request (e.g. inject auth headers),
+   * - inspect the raw {@link Response},
+   * - implement cross‑cutting concerns such as logging, tracing, retries,
+   *   or token refresh, and
+   * - short‑circuit the network call by returning a synthetic {@link Response}.
+   *
+   * Capabilities registered on the {@link Aspi} instance are propagated to every
+   * {@link Request} created via methods like {@link get}, {@link post}, etc.
+   * They are applied in the order they are registered.
+   *
+   * @param capability - The capability factory to install on this client.
+   *
+   * @returns This {@link Aspi} instance for fluent chaining.
+   *
+   * @example
+   * ```ts
+   * const api = new Aspi({ baseUrl: 'https://api.example.com' })
+   *   .useCapability(({ request }) => ({
+   *     async run(runner) {
+   *       console.log('→', request.path);
+   *       const res = await runner();
+   *       console.log('←', res.status);
+   *       return res;
+   *     },
+   *   }));
+   *
+   * const user = await api.get('/users/1').throwable().json<User>();
+   * ```
+   */
+  useCapability(capability) {
+    this.#capabilities.push(capability);
+    return this;
+  }
 };
 export {
   Aspi,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "aspi",
   "description": "Rest API client for typescript projects with chain of responsibility design pattern.",
-  "version": "2.1.0",
+  "version": "2.2.1",
   "module": "src/index.ts",
   "type": "module",
   "devDependencies": {