@routar/core 1.2.1 → 1.3.0

package/dist/index.d.cts

@@ -6,7 +6,7 @@ interface ExecuteOptions {
     params?: Record<string, unknown>;
     body?: unknown;
     /**
-     * Per-request headers injected by middleware (e.g. `defineMiddleware`).
+     * Per-request headers injected by a plugin's `onRequest` hook.
      * Headers cannot be set from `createApi` call sites directly — use middleware
      * to add dynamic headers such as `Authorization` or `X-Request-Id`.
      */
@@ -22,21 +22,51 @@ interface Executor {
     execute(options: ExecuteOptions): Promise<unknown>;
 }
 /**
- * Middleware function for an {@link Executor}.
+ * A named, composable unit of executor behavior.
  *
- * Receives the current {@link ExecuteOptions} and a `next` function to call
- * the next middleware (or the underlying transport). Must return the response
- * promise.
+ * Each lifecycle hook is optional — implement only what you need.
+ * Related concerns (e.g. auth header injection + 401 refresh) can be
+ * bundled into a single plugin.
  *
- * @example
+ * @example Auth plugin
  * ```ts
- * const myMiddleware: ExecutorMiddleware = async (opts, next) => {
- *   console.log(opts.method, opts.url);
- *   return next(opts);
+ * const authPlugin: ExecutorPlugin = {
+ *   name: 'auth',
+ *   onRequest: async (opts) => ({
+ *     ...opts,
+ *     headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
+ *   }),
+ *   onError: async (err) => {
+ *     if (isUnauthorized(err)) await refreshToken();
+ *     throw err;
+ *   },
  * };
  * ```
  */
-type ExecutorMiddleware = (options: ExecuteOptions, next: (options: ExecuteOptions) => Promise<unknown>) => Promise<unknown>;
+interface ExecutorPlugin {
+    /** Optional name — used for introspection and `eject`. */
+    name?: string;
+    /** Runs before the request is sent. Return modified opts to transform the request. */
+    onRequest?: (opts: ExecuteOptions) => ExecuteOptions | Promise<ExecuteOptions>;
+    /** Runs after a successful response. Return a modified value to transform the response. */
+    onResponse?: (response: unknown, opts: ExecuteOptions) => unknown | Promise<unknown>;
+    /** Runs when the request throws. Must re-throw (or throw a different error). */
+    onError?: (error: unknown, opts: ExecuteOptions) => never | Promise<never>;
+}
+/**
+ * Options for {@link createExecutor}.
+ *
+ * @example
+ * ```ts
+ * const executor = createExecutor(transport, {
+ *   plugins: [authPlugin, logger()],
+ * });
+ * ```
+ */
+interface CreateExecutorOptions {
+    /** Plugins applied in declaration order (first plugin is outermost). */
+    plugins?: ExecutorPlugin[];
+}
 /**
  * Any object with a `parse` method — compatible with Zod, Valibot, Yup, etc.
  *
@@ -229,55 +259,43 @@ declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executo
 declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, endpoints: TEndpoints, options?: CreateApiOptions): ApiClient<TEndpoints>;
 
 /**
- * Creates an {@link Executor} by wrapping a transport function with an
- * optional middleware chain.
+ * Creates an {@link Executor} by wrapping a transport function with plugins.
  *
- * Middlewares are applied in declaration order — the first middleware is the
- * outermost wrapper and runs first on each request.
+ * Plugins run in declaration order (first plugin is outermost).
  *
- * @param execute - The underlying transport function (fetch, axios, etc.).
- * @param middlewares - Ordered list of middlewares to apply.
+ * For `retry` and `timeout`, use the options on {@link createFetchExecutor}
+ * or configure them via the underlying HTTP client (axios, ky).
  *
  * @example
  * ```ts
- * const executor = createExecutor(
- *   async ({ method, url, body }) => {
- *     const res = await fetch(url, { method, body: JSON.stringify(body) });
- *     return res.json();
- *   },
- *   [withTimeout(5000), withRetry(3), withLogger()],
- * );
+ * const executor = createExecutor(transport, {
+ *   plugins: [authPlugin, logger()],
+ * });
  * ```
  */
-declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, middlewares?: ExecutorMiddleware[]): Executor;
+declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, options?: CreateExecutorOptions): Executor;
 /**
  * Creates an {@link Executor} that selects the underlying transport at
  * request time based on the result of `resolver`.
  *
- * Use this to unify SSR and CSR behind a single API client — the resolver
- * picks the right executor per request, so `createApi` is called once and
- * works in both environments without duplicate `*ServerApi` instances.
- *
- * The resolver receives the full {@link ExecuteOptions} so it can branch on
- * environment, URL prefix, auth context, or any runtime condition.
- *
- * @param resolver - Called on every request; returns the executor to delegate to.
- *
  * @example
  * ```ts
- * // SSR vs CSR — pick transport based on environment
  * const apiExecutor = dispatchExecutor(() =>
  *   typeof window === 'undefined' ? serverExecutor : clientExecutor,
  * );
- *
- * // Route by URL prefix — internal routes use a different transport
- * const apiExecutor = dispatchExecutor((opts) =>
- *   opts.url.startsWith('/internal') ? internalExecutor : publicExecutor,
- * );
  * ```
  */
 declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor): Executor;
 
+type FetchRetryOption = number | {
+    count: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+interface FetchExecutorOptions extends CreateExecutorOptions {
+    defaultHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    retry?: FetchRetryOption;
+    timeout?: number;
+}
 /**
  * Creates an {@link Executor} backed by the browser / Node.js `fetch` API.
  *
@@ -293,7 +311,13 @@ declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor):
  * @param baseURL - Absolute base URL prepended to every endpoint path.
  * @param options.defaultHeaders - Async factory called on every request to
  *   produce headers (e.g. reading cookies in a Next.js server component).
- * @param options.middlewares - Middleware chain applied before the fetch call.
+ * @param options.plugins - Plugins applied around the fetch call. Each retry
+ *   attempt re-runs `onRequest` hooks (so headers are refreshed per attempt)
+ *   and `onError` hooks. Token-refresh-on-401 patterns work by updating an
+ *   external token store in `onError` and letting `onRequest` pick it up on
+ *   the next attempt.
+ * @param options.retry - Number of retries, or `{ count, shouldRetry? }`.
+ * @param options.timeout - Per-attempt timeout in milliseconds.
  *
  * @example Minimal — no options needed
  * ```ts
@@ -310,22 +334,15 @@ declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor):
  * });
  * ```
  *
- * @example Next.js App Router — forward cookies from the incoming request
+ * @example With retry and timeout
  * ```ts
  * const executor = createFetchExecutor('https://api.example.com', {
- *   defaultHeaders: async () => {
- *     const { cookies } = await import('next/headers');
- *     const token = (await cookies()).get('access_token')?.value;
- *     return token ? { Authorization: `Bearer ${token}` } : {};
- *   },
- *   middlewares: [withTimeout(8_000), withRetry(2)],
+ *   retry: 2,
+ *   timeout: 8_000,
  * });
  * ```
  */
-declare function createFetchExecutor(baseURL: string, options?: {
-    defaultHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    middlewares?: ExecutorMiddleware[];
-}): Executor;
+declare function createFetchExecutor(baseURL: string, options?: FetchExecutorOptions): Executor;
 /**
  * Thrown by {@link createFetchExecutor} when the server returns a non-2xx
  * status code.
@@ -342,19 +359,10 @@ declare function createFetchExecutor(baseURL: string, options?: {
  * ```
  */
 declare class HttpError extends Error {
-    /** HTTP status code (e.g. 404, 500). */
     readonly status: number;
-    /** HTTP status text (e.g. "Not Found"). */
     readonly statusText: string;
-    /** Parsed response body, or `null` if the body was empty or not JSON. */
     readonly body: unknown;
-    constructor(
-    /** HTTP status code (e.g. 404, 500). */
-    status: number, 
-    /** HTTP status text (e.g. "Not Found"). */
-    statusText: string, 
-    /** Parsed response body, or `null` if the body was empty or not JSON. */
-    body?: unknown);
+    constructor(status: number, statusText: string, body?: unknown);
 }
 
 /**
@@ -522,71 +530,29 @@ declare function isRouterDef(entry: object): entry is RouterDef<RouterEndpoints>
 declare function defineRouter<TEndpoints extends RouterEndpoints>(prefix: string, endpoints: TEndpoints): RouterDef<TEndpoints>;
 
 /**
- * Thrown by {@link withTimeout} when a request exceeds the configured duration.
- * Distinguishable from a user-initiated {@link AbortSignal} cancellation.
+ * Thrown by the built-in `timeout` option when a request exceeds the
+ * configured duration. Distinguishable from a user-initiated
+ * {@link AbortSignal} cancellation.
  */
 declare class TimeoutError extends Error {
     readonly ms: number;
     constructor(ms: number);
 }
 /**
- * Identity helper that returns the middleware as-is.
- *
- * Wrap your middleware function with this to get full type inference on `opts`
- * and `next` without having to annotate the type manually.
- *
- * @example
- * ```ts
- * const withCorrelationId = defineMiddleware((opts, next) =>
- *   next({ ...opts, headers: { ...opts.headers, 'X-Request-Id': crypto.randomUUID() } })
- * );
- * ```
- */
-declare function defineMiddleware(fn: ExecutorMiddleware): ExecutorMiddleware;
-/**
- * Retries a failed request up to `count` additional times.
- *
- * By default all errors trigger a retry. Pass `shouldRetry` to skip retries
- * for non-transient errors (e.g. 4xx responses).
- *
- * @param count - Number of retries (not counting the initial attempt).
- * @param options.shouldRetry - Return `false` to stop retrying early.
- *   Receives the error and a zero-based `attempt` index (0 = first failure,
- *   1 = second failure, …) so you can limit retries by count or error type.
- *
- * @example
- * ```ts
- * withRetry(3, {
- *   shouldRetry: (err) => err instanceof HttpError && err.status >= 500,
- * })
- * ```
- */
-declare function withRetry(count: number, options?: {
-    shouldRetry?: (error: unknown, attempt: number) => boolean;
-}): ExecutorMiddleware;
-/**
- * Aborts a request if it does not complete within `ms` milliseconds.
- *
- * Merges the timeout signal with any existing `AbortSignal` on the request,
- * so whichever fires first wins.
- *
- * @param ms - Timeout in milliseconds.
+ * Identity helper that returns the plugin as-is, providing full type inference.
  *
  * @example
  * ```ts
- * const executor = createFetchExecutor('https://api.example.com', {
- *   middlewares: [withTimeout(5_000)],
+ * const authPlugin = definePlugin({
+ *   name: 'auth',
+ *   onRequest: async (opts) => ({
+ *     ...opts,
+ *     headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
+ *   }),
  * });
- *
- * // Combine with retry — timeout applies per attempt
- * const executor = createExecutor(transport, [
- *   withTimeout(5_000),
- *   withRetry(3, { shouldRetry: (err) => !(err instanceof HttpError && err.status < 500) }),
- *   withLogger(),
- * ]);
  * ```
  */
-declare function withTimeout(ms: number): ExecutorMiddleware;
+declare function definePlugin(plugin: ExecutorPlugin): ExecutorPlugin;
 /**
  * Logs each request and its outcome (success duration or error).
  *
@@ -594,12 +560,14 @@ declare function withTimeout(ms: number): ExecutorMiddleware;
  *
  * @example
  * ```ts
- * withLogger({ log: (msg, data) => logger.debug(msg, data) })
+ * createExecutor(transport, {
+ *   plugins: [logger({ log: (msg, data) => myLogger.debug(msg, data) })],
+ * })
  * ```
  */
-declare function withLogger(options?: {
+declare function logger(options?: {
     log?: (message: string, data?: unknown) => void;
-}): ExecutorMiddleware;
+}): ExecutorPlugin;
 
 declare function serializeParams(params: Record<string, unknown>): URLSearchParams;
 
@@ -618,4 +586,4 @@ declare class ValidationError extends Error {
     constructor(message: string, cause?: unknown);
 }
 
-export { type ApiTypes, type CreateApiOptions, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorMiddleware, HttpError, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, TimeoutError, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, createFetchExecutor, defineMiddleware, defineRouter, dispatchExecutor, endpoint, isRouterDef, joinPaths, resolvePath, serializeParams, withLogger, withRetry, withTimeout };
+export { type ApiTypes, type CreateApiOptions, type CreateExecutorOptions, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorPlugin, type FetchExecutorOptions, type FetchRetryOption, HttpError, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, TimeoutError, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, createFetchExecutor, definePlugin, defineRouter, dispatchExecutor, endpoint, isRouterDef, joinPaths, logger, resolvePath, serializeParams };

package/dist/index.d.ts

@@ -6,7 +6,7 @@ interface ExecuteOptions {
     params?: Record<string, unknown>;
     body?: unknown;
     /**
-     * Per-request headers injected by middleware (e.g. `defineMiddleware`).
+     * Per-request headers injected by a plugin's `onRequest` hook.
      * Headers cannot be set from `createApi` call sites directly — use middleware
      * to add dynamic headers such as `Authorization` or `X-Request-Id`.
      */
@@ -22,21 +22,51 @@ interface Executor {
     execute(options: ExecuteOptions): Promise<unknown>;
 }
 /**
- * Middleware function for an {@link Executor}.
+ * A named, composable unit of executor behavior.
  *
- * Receives the current {@link ExecuteOptions} and a `next` function to call
- * the next middleware (or the underlying transport). Must return the response
- * promise.
+ * Each lifecycle hook is optional — implement only what you need.
+ * Related concerns (e.g. auth header injection + 401 refresh) can be
+ * bundled into a single plugin.
  *
- * @example
+ * @example Auth plugin
  * ```ts
- * const myMiddleware: ExecutorMiddleware = async (opts, next) => {
- *   console.log(opts.method, opts.url);
- *   return next(opts);
+ * const authPlugin: ExecutorPlugin = {
+ *   name: 'auth',
+ *   onRequest: async (opts) => ({
+ *     ...opts,
+ *     headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
+ *   }),
+ *   onError: async (err) => {
+ *     if (isUnauthorized(err)) await refreshToken();
+ *     throw err;
+ *   },
  * };
  * ```
  */
-type ExecutorMiddleware = (options: ExecuteOptions, next: (options: ExecuteOptions) => Promise<unknown>) => Promise<unknown>;
+interface ExecutorPlugin {
+    /** Optional name — used for introspection and `eject`. */
+    name?: string;
+    /** Runs before the request is sent. Return modified opts to transform the request. */
+    onRequest?: (opts: ExecuteOptions) => ExecuteOptions | Promise<ExecuteOptions>;
+    /** Runs after a successful response. Return a modified value to transform the response. */
+    onResponse?: (response: unknown, opts: ExecuteOptions) => unknown | Promise<unknown>;
+    /** Runs when the request throws. Must re-throw (or throw a different error). */
+    onError?: (error: unknown, opts: ExecuteOptions) => never | Promise<never>;
+}
+/**
+ * Options for {@link createExecutor}.
+ *
+ * @example
+ * ```ts
+ * const executor = createExecutor(transport, {
+ *   plugins: [authPlugin, logger()],
+ * });
+ * ```
+ */
+interface CreateExecutorOptions {
+    /** Plugins applied in declaration order (first plugin is outermost). */
+    plugins?: ExecutorPlugin[];
+}
 /**
  * Any object with a `parse` method — compatible with Zod, Valibot, Yup, etc.
  *
@@ -229,55 +259,43 @@ declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executo
 declare function createApi<TEndpoints extends RouterEndpoints>(executor: Executor, endpoints: TEndpoints, options?: CreateApiOptions): ApiClient<TEndpoints>;
 
 /**
- * Creates an {@link Executor} by wrapping a transport function with an
- * optional middleware chain.
+ * Creates an {@link Executor} by wrapping a transport function with plugins.
  *
- * Middlewares are applied in declaration order — the first middleware is the
- * outermost wrapper and runs first on each request.
+ * Plugins run in declaration order (first plugin is outermost).
  *
- * @param execute - The underlying transport function (fetch, axios, etc.).
- * @param middlewares - Ordered list of middlewares to apply.
+ * For `retry` and `timeout`, use the options on {@link createFetchExecutor}
+ * or configure them via the underlying HTTP client (axios, ky).
  *
  * @example
  * ```ts
- * const executor = createExecutor(
- *   async ({ method, url, body }) => {
- *     const res = await fetch(url, { method, body: JSON.stringify(body) });
- *     return res.json();
- *   },
- *   [withTimeout(5000), withRetry(3), withLogger()],
- * );
+ * const executor = createExecutor(transport, {
+ *   plugins: [authPlugin, logger()],
+ * });
  * ```
  */
-declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, middlewares?: ExecutorMiddleware[]): Executor;
+declare function createExecutor(execute: (options: ExecuteOptions) => Promise<unknown>, options?: CreateExecutorOptions): Executor;
 /**
  * Creates an {@link Executor} that selects the underlying transport at
  * request time based on the result of `resolver`.
  *
- * Use this to unify SSR and CSR behind a single API client — the resolver
- * picks the right executor per request, so `createApi` is called once and
- * works in both environments without duplicate `*ServerApi` instances.
- *
- * The resolver receives the full {@link ExecuteOptions} so it can branch on
- * environment, URL prefix, auth context, or any runtime condition.
- *
- * @param resolver - Called on every request; returns the executor to delegate to.
- *
  * @example
  * ```ts
- * // SSR vs CSR — pick transport based on environment
  * const apiExecutor = dispatchExecutor(() =>
  *   typeof window === 'undefined' ? serverExecutor : clientExecutor,
  * );
- *
- * // Route by URL prefix — internal routes use a different transport
- * const apiExecutor = dispatchExecutor((opts) =>
- *   opts.url.startsWith('/internal') ? internalExecutor : publicExecutor,
- * );
  * ```
  */
 declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor): Executor;
 
+type FetchRetryOption = number | {
+    count: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+};
+interface FetchExecutorOptions extends CreateExecutorOptions {
+    defaultHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    retry?: FetchRetryOption;
+    timeout?: number;
+}
 /**
  * Creates an {@link Executor} backed by the browser / Node.js `fetch` API.
  *
@@ -293,7 +311,13 @@ declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor):
  * @param baseURL - Absolute base URL prepended to every endpoint path.
  * @param options.defaultHeaders - Async factory called on every request to
  *   produce headers (e.g. reading cookies in a Next.js server component).
- * @param options.middlewares - Middleware chain applied before the fetch call.
+ * @param options.plugins - Plugins applied around the fetch call. Each retry
+ *   attempt re-runs `onRequest` hooks (so headers are refreshed per attempt)
+ *   and `onError` hooks. Token-refresh-on-401 patterns work by updating an
+ *   external token store in `onError` and letting `onRequest` pick it up on
+ *   the next attempt.
+ * @param options.retry - Number of retries, or `{ count, shouldRetry? }`.
+ * @param options.timeout - Per-attempt timeout in milliseconds.
  *
  * @example Minimal — no options needed
  * ```ts
@@ -310,22 +334,15 @@ declare function dispatchExecutor(resolver: (opts: ExecuteOptions) => Executor):
  * });
  * ```
  *
- * @example Next.js App Router — forward cookies from the incoming request
+ * @example With retry and timeout
  * ```ts
  * const executor = createFetchExecutor('https://api.example.com', {
- *   defaultHeaders: async () => {
- *     const { cookies } = await import('next/headers');
- *     const token = (await cookies()).get('access_token')?.value;
- *     return token ? { Authorization: `Bearer ${token}` } : {};
- *   },
- *   middlewares: [withTimeout(8_000), withRetry(2)],
+ *   retry: 2,
+ *   timeout: 8_000,
  * });
  * ```
  */
-declare function createFetchExecutor(baseURL: string, options?: {
-    defaultHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
-    middlewares?: ExecutorMiddleware[];
-}): Executor;
+declare function createFetchExecutor(baseURL: string, options?: FetchExecutorOptions): Executor;
 /**
  * Thrown by {@link createFetchExecutor} when the server returns a non-2xx
  * status code.
@@ -342,19 +359,10 @@ declare function createFetchExecutor(baseURL: string, options?: {
  * ```
  */
 declare class HttpError extends Error {
-    /** HTTP status code (e.g. 404, 500). */
     readonly status: number;
-    /** HTTP status text (e.g. "Not Found"). */
     readonly statusText: string;
-    /** Parsed response body, or `null` if the body was empty or not JSON. */
     readonly body: unknown;
-    constructor(
-    /** HTTP status code (e.g. 404, 500). */
-    status: number, 
-    /** HTTP status text (e.g. "Not Found"). */
-    statusText: string, 
-    /** Parsed response body, or `null` if the body was empty or not JSON. */
-    body?: unknown);
+    constructor(status: number, statusText: string, body?: unknown);
 }
 
 /**
@@ -522,71 +530,29 @@ declare function isRouterDef(entry: object): entry is RouterDef<RouterEndpoints>
 declare function defineRouter<TEndpoints extends RouterEndpoints>(prefix: string, endpoints: TEndpoints): RouterDef<TEndpoints>;
 
 /**
- * Thrown by {@link withTimeout} when a request exceeds the configured duration.
- * Distinguishable from a user-initiated {@link AbortSignal} cancellation.
+ * Thrown by the built-in `timeout` option when a request exceeds the
+ * configured duration. Distinguishable from a user-initiated
+ * {@link AbortSignal} cancellation.
  */
 declare class TimeoutError extends Error {
     readonly ms: number;
     constructor(ms: number);
 }
 /**
- * Identity helper that returns the middleware as-is.
- *
- * Wrap your middleware function with this to get full type inference on `opts`
- * and `next` without having to annotate the type manually.
- *
- * @example
- * ```ts
- * const withCorrelationId = defineMiddleware((opts, next) =>
- *   next({ ...opts, headers: { ...opts.headers, 'X-Request-Id': crypto.randomUUID() } })
- * );
- * ```
- */
-declare function defineMiddleware(fn: ExecutorMiddleware): ExecutorMiddleware;
-/**
- * Retries a failed request up to `count` additional times.
- *
- * By default all errors trigger a retry. Pass `shouldRetry` to skip retries
- * for non-transient errors (e.g. 4xx responses).
- *
- * @param count - Number of retries (not counting the initial attempt).
- * @param options.shouldRetry - Return `false` to stop retrying early.
- *   Receives the error and a zero-based `attempt` index (0 = first failure,
- *   1 = second failure, …) so you can limit retries by count or error type.
- *
- * @example
- * ```ts
- * withRetry(3, {
- *   shouldRetry: (err) => err instanceof HttpError && err.status >= 500,
- * })
- * ```
- */
-declare function withRetry(count: number, options?: {
-    shouldRetry?: (error: unknown, attempt: number) => boolean;
-}): ExecutorMiddleware;
-/**
- * Aborts a request if it does not complete within `ms` milliseconds.
- *
- * Merges the timeout signal with any existing `AbortSignal` on the request,
- * so whichever fires first wins.
- *
- * @param ms - Timeout in milliseconds.
+ * Identity helper that returns the plugin as-is, providing full type inference.
  *
  * @example
  * ```ts
- * const executor = createFetchExecutor('https://api.example.com', {
- *   middlewares: [withTimeout(5_000)],
+ * const authPlugin = definePlugin({
+ *   name: 'auth',
+ *   onRequest: async (opts) => ({
+ *     ...opts,
+ *     headers: { ...opts.headers, Authorization: `Bearer ${await getToken()}` },
+ *   }),
  * });
- *
- * // Combine with retry — timeout applies per attempt
- * const executor = createExecutor(transport, [
- *   withTimeout(5_000),
- *   withRetry(3, { shouldRetry: (err) => !(err instanceof HttpError && err.status < 500) }),
- *   withLogger(),
- * ]);
  * ```
  */
-declare function withTimeout(ms: number): ExecutorMiddleware;
+declare function definePlugin(plugin: ExecutorPlugin): ExecutorPlugin;
 /**
  * Logs each request and its outcome (success duration or error).
  *
@@ -594,12 +560,14 @@ declare function withTimeout(ms: number): ExecutorMiddleware;
  *
  * @example
  * ```ts
- * withLogger({ log: (msg, data) => logger.debug(msg, data) })
+ * createExecutor(transport, {
+ *   plugins: [logger({ log: (msg, data) => myLogger.debug(msg, data) })],
+ * })
  * ```
  */
-declare function withLogger(options?: {
+declare function logger(options?: {
     log?: (message: string, data?: unknown) => void;
-}): ExecutorMiddleware;
+}): ExecutorPlugin;
 
 declare function serializeParams(params: Record<string, unknown>): URLSearchParams;
 
@@ -618,4 +586,4 @@ declare class ValidationError extends Error {
     constructor(message: string, cause?: unknown);
 }
 
-export { type ApiTypes, type CreateApiOptions, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorMiddleware, HttpError, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, TimeoutError, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, createFetchExecutor, defineMiddleware, defineRouter, dispatchExecutor, endpoint, isRouterDef, joinPaths, resolvePath, serializeParams, withLogger, withRetry, withTimeout };
+export { type ApiTypes, type CreateApiOptions, type CreateExecutorOptions, type EndpointSpec, type ExecuteOptions, type Executor, type ExecutorPlugin, type FetchExecutorOptions, type FetchRetryOption, HttpError, type HttpMethod, type InferResponse, type PathParams, type RequestShape, type RouterDef, type RouterEndpoints, type RouterEntry, TimeoutError, ValidationError, type Validator, type ValidatorOutput, createApi, createExecutor, createFetchExecutor, definePlugin, defineRouter, dispatchExecutor, endpoint, isRouterDef, joinPaths, logger, resolvePath, serializeParams };