@spoosh/core 0.8.2 → 0.9.1

package/README.md

@@ -50,6 +50,9 @@ import { createClient } from "@spoosh/core";
 const api = createClient<ApiSchema>({
   baseUrl: "/api",
 });
+
+// Import body wrappers for explicit serialization
+import { json, form, urlencoded } from "@spoosh/core";
 ```
 
 ### Make API Calls
@@ -79,14 +82,14 @@ const { data: updated } = await api("users/:id").PUT({
 // DELETE /api/users/123
 await api("users/:id").DELETE({ params: { id: 123 } });
 
-// POST with file upload (auto FormData when File detected)
+// POST with file upload (using form() wrapper for multipart/form-data)
 const { data: uploaded } = await api("upload").POST({
-  body: { file: myFile },
+  body: form({ file: myFile }),
 });
 
-// POST with form data
+// POST with form data (using urlencoded() wrapper)
 const { data: payment } = await api("payments").POST({
-  body: { amount: 1000, currency: "usd" },
+  body: urlencoded({ amount: 1000, currency: "usd" }),
 });
 ```
 
@@ -172,12 +175,12 @@ const updatedContext = await applyMiddlewares(context, middlewares, "before");
 
 ## Schema Types
 
-| Field   | Description                             | Example                                          |
-| ------- | --------------------------------------- | ------------------------------------------------ |
-| `data`  | Response data type                      | `GET: { data: User[] }`                          |
-| `body`  | Request body type (files auto-detected) | `POST: { data: User; body: CreateUserBody }`     |
-| `query` | Query parameters type                   | `GET: { data: User[]; query: { page: number } }` |
-| `error` | Typed error type                        | `GET: { data: User; error: ApiError }`           |
+| Field   | Description           | Example                                          |
+| ------- | --------------------- | ------------------------------------------------ |
+| `data`  | Response data type    | `GET: { data: User[] }`                          |
+| `body`  | Request body type     | `POST: { data: User; body: CreateUserBody }`     |
+| `query` | Query parameters type | `GET: { data: User[]; query: { page: number } }` |
+| `error` | Typed error type      | `GET: { data: User; error: ApiError }`           |
 
 Path parameters are defined using `:param` syntax in the path key (e.g., `"users/:id"`).
 

package/dist/index.d.mts

@@ -1,4 +1,8 @@
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+type WriteMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 
 type MiddlewarePhase = "before" | "after";
 type MiddlewareContext<TData = unknown, TError = unknown> = {
@@ -62,6 +66,20 @@ type SpooshOptionsExtra<TData = unknown, TError = unknown> = {
     middlewares?: SpooshMiddleware<TData, TError>[];
 };
 
+type SpooshBody<T = unknown> = {
+    readonly __spooshBody: true;
+    readonly kind: "form" | "json" | "urlencoded";
+    readonly value: T;
+};
+declare function isSpooshBody(value: unknown): value is SpooshBody;
+declare function form<T>(value: T): SpooshBody<T>;
+declare function json<T>(value: T): SpooshBody<T>;
+declare function urlencoded<T>(value: T): SpooshBody<T>;
+declare function resolveRequestBody(rawBody: unknown): {
+    body: BodyInit;
+    headers?: Record<string, string>;
+} | undefined;
+
 type RetryConfig = {
     retries?: number | false;
     retryDelay?: number;
@@ -76,9 +94,9 @@ type BaseRequestOptions$1 = {
     signal?: AbortSignal;
 };
 type BodyOption$1<TBody> = [TBody] extends [never] ? object : undefined extends TBody ? {
-    body?: Exclude<TBody, undefined>;
+    body?: Exclude<TBody, undefined> | SpooshBody<Exclude<TBody, undefined>>;
 } : {
-    body: TBody;
+    body: TBody | SpooshBody<TBody>;
 };
 type QueryOption$1<TQuery> = [TQuery] extends [never] ? object : undefined extends TQuery ? {
     query?: Exclude<TQuery, undefined>;
@@ -106,7 +124,7 @@ type MethodOptionsMap<TQueryOptions = object, TMutationOptions = object> = {
     DELETE: TMutationOptions;
 };
 type ExtractMethodOptions<TOptionsMap, TMethod extends HttpMethod> = TOptionsMap extends MethodOptionsMap<infer TQuery, infer TMutation> ? TMethod extends "GET" ? TQuery : TMutation : TOptionsMap;
-type FetchExecutor<TOptions = SpooshOptions, TRequestOptions = AnyRequestOptions> = <TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: TOptions, requestOptions?: TRequestOptions, nextTags?: boolean) => Promise<SpooshResponse<TData, TError>>;
+type FetchExecutor<TOptions = SpooshOptions, TRequestOptions = AnyRequestOptions> = <TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: TOptions, requestOptions?: TRequestOptions, nextTags?: boolean, tagPath?: string[]) => Promise<SpooshResponse<TData, TError>>;
 type TypedParamsOption<TParamNames extends string> = [TParamNames] extends [
     never
 ] ? object : {
@@ -233,6 +251,11 @@ type PluginContext<TData = unknown, TError = unknown> = {
     readonly requestTimestamp: number;
     /** Unique identifier for the hook instance. Persists across queryKey changes within the same hook. */
     readonly hookId?: string;
+    /**
+     * Prefix to strip from tags. Configured at the Spoosh instance level.
+     * Plugins can use this to normalize tags before emitting events.
+     */
+    readonly stripTagPrefix?: string;
     requestOptions: AnyRequestOptions;
     state: OperationState<TData, TError>;
     response?: SpooshResponse<TData, TError>;
@@ -578,7 +601,10 @@ type PluginExecutor = {
     /** Creates a full PluginContext with plugins accessor injected */
     createContext: <TData, TError>(input: PluginContextInput<TData, TError>) => PluginContext<TData, TError>;
 };
-declare function createPluginExecutor(initialPlugins?: SpooshPlugin[]): PluginExecutor;
+type PluginExecutorOptions = {
+    stripTagPrefix?: string;
+};
+declare function createPluginExecutor(initialPlugins?: SpooshPlugin[], options?: PluginExecutorOptions): PluginExecutor;
 
 /**
  * Resolves plugin option types based on the full context.
@@ -825,10 +851,54 @@ type ExtractParamNames<T extends string> = T extends `${string}:${infer Param}/$
  * ```
  */
 type HasParams<T extends string> = T extends `${string}:${string}` ? true : false;
+/**
+ * Extract paths that have GET methods.
+ */
+type ReadPaths<TSchema> = {
+    [K in keyof TSchema & string]: "GET" extends keyof TSchema[K] ? K : never;
+}[keyof TSchema & string];
+/**
+ * Extract paths that have write methods (POST, PUT, PATCH, DELETE).
+ */
+type WritePaths<TSchema> = {
+    [K in keyof TSchema & string]: Extract<keyof TSchema[K], WriteMethod> extends never ? never : K;
+}[keyof TSchema & string];
+/**
+ * Check if a schema path has a GET method.
+ */
+type HasReadMethod<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? "GET" extends keyof TSchema[TKey] ? true : false : false : false;
+/**
+ * Check if a schema path has any write methods.
+ */
+type HasWriteMethod<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? WriteMethod extends never ? false : Extract<keyof TSchema[TKey], WriteMethod> extends never ? false : true : false : false;
+type NormalizePrefix<T extends string> = T extends `/${infer Rest}` ? NormalizePrefix<Rest> : T extends `${infer Rest}/` ? NormalizePrefix<Rest> : T;
+type StripPrefixFromPath<TPath extends string, TPrefix extends string> = TPath extends TPrefix ? "" : TPath extends `${TPrefix}/${infer Rest}` ? Rest : TPath;
+/**
+ * Strips a prefix from all path keys in a schema.
+ * Works with any schema (Elysia, Hono, or manual).
+ *
+ * @example
+ * ```ts
+ * type FullSchema = {
+ *   "api": { GET: { data: string } };
+ *   "api/users": { GET: { data: User[] } };
+ *   "api/posts/:id": { GET: { data: Post } };
+ *   "health": { GET: { data: { status: string } } };
+ * };
+ *
+ * type ApiSchema = StripPrefix<FullSchema, "api">;
+ * // {
+ * //   "": { GET: { data: string } };
+ * //   "users": { GET: { data: User[] } };
+ * //   "posts/:id": { GET: { data: Post } };
+ * //   "health": { GET: { data: { status: string } } };
+ * // }
+ * ```
+ */
+type StripPrefix<TSchema, TPrefix extends string> = TPrefix extends "" ? TSchema : {
+    [K in keyof TSchema as K extends string ? StripPrefixFromPath<K, NormalizePrefix<TPrefix>> : K]: TSchema[K];
+};
 
-type Simplify$1<T> = {
-    [K in keyof T]: T[K];
-} & {};
 type IsNever<T> = [T] extends [never] ? true : false;
 type EndpointRequestOptions<TEndpoint, TPath extends string> = (IsNever<ExtractBody$1<TEndpoint>> extends true ? object : {
     body: ExtractBody$1<TEndpoint>;
@@ -837,14 +907,10 @@ type EndpointRequestOptions<TEndpoint, TPath extends string> = (IsNever<ExtractB
 }) & (HasParams<TPath> extends true ? {
     params: Record<ExtractParamNames<TPath>, string | number>;
 } : object);
-type EndpointMethodFn<TEndpoint, TPath extends string> = (options?: Simplify$1<EndpointRequestOptions<TEndpoint, TPath>>) => Promise<SpooshResponse<ExtractData<TEndpoint>, unknown, EndpointRequestOptions<TEndpoint, TPath>>>;
-type QueryPathMethods<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? "GET" extends keyof TSchema[TKey] ? Simplify$1<{
+type EndpointMethodFn<TEndpoint, TPath extends string> = (options?: Simplify<EndpointRequestOptions<TEndpoint, TPath>>) => Promise<SpooshResponse<ExtractData<TEndpoint>, unknown, EndpointRequestOptions<TEndpoint, TPath>>>;
+type ReadPathMethods$1<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? "GET" extends keyof TSchema[TKey] ? Simplify<{
     GET: EndpointMethodFn<TSchema[TKey]["GET"], TPath>;
 }> : never : never : never;
-type ReadPaths$1<TSchema> = {
-    [K in keyof TSchema & string]: "GET" extends keyof TSchema[K] ? K : never;
-}[keyof TSchema & string];
-type HasGetMethod$1<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? "GET" extends keyof TSchema[TKey] ? true : false : false : false;
 /**
  * Schema navigation helper for plugins that need type-safe API schema access.
  *
@@ -858,7 +924,7 @@ type HasGetMethod$1<TSchema, TPath extends string> = FindMatchingKey<TSchema, TP
  * ```ts
  * // Define your plugin's callback type
  * type MyCallbackFn<TSchema = unknown> = (
- *   api: QuerySchemaHelper<TSchema>
+ *   api: ReadSchemaHelper<TSchema>
  * ) => unknown;
  *
  * // Usage in plugin options
@@ -886,25 +952,17 @@ type HasGetMethod$1<TSchema, TPath extends string> = FindMatchingKey<TSchema, TP
  * });
  * ```
  */
-type QuerySchemaHelper<TSchema> = <TPath extends ReadPaths$1<TSchema> | (string & {})>(path: TPath) => HasGetMethod$1<TSchema, TPath> extends true ? QueryPathMethods<TSchema, TPath> : never;
-type MutationMethod$1 = "POST" | "PUT" | "PATCH" | "DELETE";
-type MutationPathMethods<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? Simplify$1<{
-    [M in MutationMethod$1 as M extends keyof TSchema[TKey] ? M : never]: M extends keyof TSchema[TKey] ? EndpointMethodFn<TSchema[TKey][M], TPath> : never;
+type ReadSchemaHelper<TSchema> = <TPath extends ReadPaths<TSchema> | (string & {})>(path: TPath) => HasReadMethod<TSchema, TPath> extends true ? ReadPathMethods$1<TSchema, TPath> : never;
+type WritePathMethods$1<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? Simplify<{
+    [M in WriteMethod as M extends keyof TSchema[TKey] ? M : never]: M extends keyof TSchema[TKey] ? EndpointMethodFn<TSchema[TKey][M], TPath> : never;
 }> : never : never;
-type WritePaths$1<TSchema> = {
-    [K in keyof TSchema & string]: Extract<keyof TSchema[K], MutationMethod$1> extends never ? never : K;
-}[keyof TSchema & string];
-type HasMutationMethod$1<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? MutationMethod$1 extends never ? false : Extract<keyof TSchema[TKey], MutationMethod$1> extends never ? false : true : false : false;
 /**
  * Schema navigation helper for plugins that need type-safe API schema access for mutations.
  *
- * Similar to QuerySchemaHelper but exposes mutation methods (POST, PUT, PATCH, DELETE).
+ * Similar to ReadSchemaHelper but exposes write methods (POST, PUT, PATCH, DELETE).
  */
-type MutationSchemaHelper<TSchema> = <TPath extends WritePaths$1<TSchema> | (string & {})>(path: TPath) => HasMutationMethod$1<TSchema, TPath> extends true ? MutationPathMethods<TSchema, TPath> : never;
+type WriteSchemaHelper<TSchema> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasWriteMethod<TSchema, TPath> extends true ? WritePathMethods$1<TSchema, TPath> : never;
 
-type Simplify<T> = {
-    [K in keyof T]: T[K];
-} & {};
 /**
  * Base request options available on all methods.
  */
@@ -941,9 +999,9 @@ type IsQueryRequired<T> = T extends {
  * Build the options type for a method.
  */
 type BodyOption<T> = [ExtractBody<T>] extends [never] ? {} : IsBodyRequired<T> extends true ? {
-    body: ExtractBody<T>;
+    body: ExtractBody<T> | SpooshBody<ExtractBody<T>>;
 } : {
-    body?: ExtractBody<T>;
+    body?: ExtractBody<T> | SpooshBody<ExtractBody<T>>;
 };
 type QueryOption<T> = [ExtractQuery<T>] extends [never] ? {} : IsQueryRequired<T> extends true ? {
     query: ExtractQuery<T>;
@@ -1014,49 +1072,52 @@ type SpooshClient<TSchema, TDefaultError = unknown> = <TPath extends SchemaPaths
 type ReadPathMethods<TSchema, TPath extends string, TDefaultError> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? "GET" extends keyof TSchema[TKey] ? Simplify<{
     GET: MethodFn<TSchema[TKey]["GET"], TDefaultError, TPath>;
 }> : never : never : never;
-/**
- * Check if a schema path has a GET method.
- */
-type HasGetMethod<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? "GET" extends keyof TSchema[TKey] ? true : false : false : false;
-/**
- * Extract paths that have GET methods.
- */
-type ReadPaths<TSchema> = {
-    [K in keyof TSchema & string]: "GET" extends keyof TSchema[K] ? K : never;
-}[keyof TSchema & string];
 /**
  * A read-only API client that only exposes GET methods.
  * Used by useRead and injectRead hooks.
  */
-type ReadClient<TSchema, TDefaultError = unknown> = <TPath extends ReadPaths<TSchema> | (string & {})>(path: TPath) => HasGetMethod<TSchema, TPath> extends true ? ReadPathMethods<TSchema, TPath, TDefaultError> : never;
-/**
- * Mutation methods (non-GET).
- */
-type MutationMethod = "POST" | "PUT" | "PATCH" | "DELETE";
+type ReadClient<TSchema, TDefaultError = unknown> = <TPath extends ReadPaths<TSchema> | (string & {})>(path: TPath) => HasReadMethod<TSchema, TPath> extends true ? ReadPathMethods<TSchema, TPath, TDefaultError> : never;
 /**
  * Write-only client type that only exposes mutation methods (POST, PUT, PATCH, DELETE).
  * Used by useWrite/injectWrite hooks to ensure only mutation operations are selected.
  */
 type WritePathMethods<TSchema, TPath extends string, TDefaultError> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? Simplify<{
-    [M in MutationMethod as M extends keyof TSchema[TKey] ? M : never]: M extends keyof TSchema[TKey] ? MethodFn<TSchema[TKey][M], TDefaultError, TPath> : never;
+    [M in WriteMethod as M extends keyof TSchema[TKey] ? M : never]: M extends keyof TSchema[TKey] ? MethodFn<TSchema[TKey][M], TDefaultError, TPath> : never;
 }> : never : never;
-/**
- * Check if a schema path has any mutation methods.
- */
-type HasMutationMethod<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? MutationMethod extends never ? false : Extract<keyof TSchema[TKey], MutationMethod> extends never ? false : true : false : false;
-/**
- * Extract paths that have mutation methods.
- */
-type WritePaths<TSchema> = {
-    [K in keyof TSchema & string]: Extract<keyof TSchema[K], MutationMethod> extends never ? never : K;
-}[keyof TSchema & string];
 /**
  * A write-only API client that only exposes mutation methods (POST, PUT, PATCH, DELETE).
  * Used by useWrite and injectWrite hooks.
  */
-type WriteClient<TSchema, TDefaultError = unknown> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasMutationMethod<TSchema, TPath> extends true ? WritePathMethods<TSchema, TPath, TDefaultError> : never;
+type WriteClient<TSchema, TDefaultError = unknown> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasWriteMethod<TSchema, TPath> extends true ? WritePathMethods<TSchema, TPath, TDefaultError> : never;
 
 type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
+/**
+ * Configuration options for Spoosh runtime behavior.
+ */
+type SpooshConfigOptions = {
+    /**
+     * Prefix to strip from tag generation.
+     *
+     * URL prefix stripping always auto-detects from baseUrl.
+     * This option only affects tag generation for cache invalidation.
+     *
+     * - `undefined`: Auto-detect from baseUrl (default)
+     * - `string`: Explicit prefix to strip from tags
+     *
+     * @example
+     * ```ts
+     * // Default: auto-detect from baseUrl
+     * // baseUrl="/api", schema="api/posts" → tags: ["posts"]
+     * new Spoosh<Schema>('https://localhost:3000/api')
+     *
+     * // Explicit prefix (when baseUrl doesn't have it)
+     * // baseUrl="/", schema="api/v1/posts" → tags: ["posts"]
+     * new Spoosh<Schema>('http://localhost:3000')
+     *   .configure({ stripTagPrefix: "api/v1" })
+     * ```
+     */
+    stripTagPrefix?: string;
+};
 interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
     baseUrl: string;
     defaultOptions?: SpooshOptions;
@@ -1070,6 +1131,8 @@ type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends
     config: {
         baseUrl: string;
         defaultOptions: SpooshOptions;
+        /** Resolved prefix to strip from tags (used for cache invalidation matching) */
+        stripTagPrefix?: string;
     };
     _types: {
         schema: TSchema;
@@ -1121,12 +1184,14 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
     private baseUrl;
     private defaultOptions;
     private _plugins;
+    private _config;
     /**
      * Creates a new Spoosh instance.
      *
      * @param baseUrl - The base URL for all API requests (e.g., '/api' or 'https://api.example.com')
      * @param defaultOptions - Optional default options applied to all requests (headers, credentials, etc.)
      * @param plugins - Internal parameter used by the `.use()` method. Do not pass directly.
+     * @param configOptions - Internal parameter used by the `.config()` method. Do not pass directly.
      *
      * @example
      * ```ts
@@ -1139,7 +1204,7 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
      * });
      * ```
      */
-    constructor(baseUrl: string, defaultOptions?: SpooshOptions, plugins?: TPlugins);
+    constructor(baseUrl: string, defaultOptions?: SpooshOptions, plugins?: TPlugins, configOptions?: SpooshConfigOptions);
     /**
      * Adds plugins to the Spoosh instance.
      *
@@ -1175,6 +1240,34 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
      * ```
      */
     use<const TNewPlugins extends PluginArray>(plugins: TNewPlugins): Spoosh<TSchema, TError, TNewPlugins>;
+    /**
+     * Configures runtime options for the Spoosh instance.
+     *
+     * Returns a **new** Spoosh instance with the updated configuration (immutable pattern).
+     * Configuration is preserved across `.use()` calls.
+     *
+     * URL prefix stripping always auto-detects from baseUrl.
+     * Tag prefix stripping defaults to URL prefix but can be overridden.
+     *
+     * @param options - Configuration options
+     * @returns A new Spoosh instance with the specified configuration
+     *
+     * @example Default behavior (auto-detect from baseUrl for both URL and tags)
+     * ```ts
+     * // baseUrl="/api", schema="api/posts"
+     * // URL: /api/posts, Tags: ["posts"]
+     * const client = new Spoosh<Schema, Error>('https://localhost:3000/api');
+     * ```
+     *
+     * @example Override tag prefix (when baseUrl doesn't have the prefix you want to strip from tags)
+     * ```ts
+     * // baseUrl="/", schema="api/v1/posts"
+     * // URL: /api/v1/posts, Tags: ["posts"] (strips "api/v1" from tags only)
+     * const client = new Spoosh<Schema, Error>('http://localhost:3000')
+     *   .configure({ stripTagPrefix: "api/v1" });
+     * ```
+     */
+    configure(options: SpooshConfigOptions): Spoosh<TSchema, TError, TPlugins>;
     /**
      * Cached instance of the underlying SpooshInstance.
      * Created lazily on first property access.
@@ -1274,6 +1367,7 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
     get config(): {
         baseUrl: string;
         defaultOptions: SpooshOptions;
+        stripTagPrefix?: string;
     };
     /**
      * Type information carrier for generic type inference.
@@ -1292,6 +1386,16 @@ type SpooshClientConfig = {
     baseUrl: string;
     defaultOptions?: SpooshOptions;
     middlewares?: SpooshMiddleware[];
+    /**
+     * Prefix to strip from tag generation.
+     *
+     * URL prefix stripping always auto-detects from baseUrl.
+     * This option only affects tag generation for cache invalidation.
+     *
+     * - `undefined`: Auto-detect from baseUrl (default, same as URL prefix)
+     * - `string`: Explicit prefix to strip from tags
+     */
+    stripTagPrefix?: string;
 };
 /**
  * Creates a lightweight type-safe API client for vanilla JavaScript/TypeScript usage.
@@ -1334,6 +1438,8 @@ declare function createClient<TSchema, TDefaultError = unknown>(config: SpooshCl
 
 declare function buildUrl(baseUrl: string, path: string[], query?: Record<string, string | number | boolean | undefined>): string;
 
+declare function __DEV__(): boolean;
+
 /**
  * Generate cache tags from URL path segments.
  * e.g., ['posts', '1'] → ['posts', 'posts/1']
@@ -1383,11 +1489,61 @@ type TagOptions = {
 declare function resolveTags(options: TagOptions | undefined, resolvedPath: string[]): string[];
 declare function resolvePath(path: string[], params: Record<string, string | number> | undefined): string[];
 
+/**
+ * Extracts the path prefix from a base URL.
+ *
+ * @param baseUrl - The base URL (absolute or relative)
+ * @returns The path portion without leading/trailing slashes
+ *
+ * @example
+ * ```ts
+ * extractPrefixFromBaseUrl("https://localhost:3000/api"); // "api"
+ * extractPrefixFromBaseUrl("/api/v1"); // "api/v1"
+ * extractPrefixFromBaseUrl("api"); // "api"
+ * ```
+ */
+declare function extractPrefixFromBaseUrl(baseUrl: string): string;
+/**
+ * Strips a prefix from path segments if the path starts with that prefix.
+ *
+ * @param pathSegments - Array of path segments
+ * @param prefix - Prefix to strip (e.g., "api" or "api/v1")
+ * @returns Path segments with prefix removed
+ *
+ * @example
+ * ```ts
+ * stripPrefixFromPath(["api", "posts"], "api"); // ["posts"]
+ * stripPrefixFromPath(["api", "v1", "users"], "api/v1"); // ["users"]
+ * stripPrefixFromPath(["posts"], "api"); // ["posts"] (no match, unchanged)
+ * ```
+ */
+declare function stripPrefixFromPath(pathSegments: string[], prefix: string): string[];
+/**
+ * Resolves the strip prefix value based on configuration.
+ *
+ * @param stripPathPrefix - Configuration value (boolean, string, or undefined)
+ * @param baseUrl - The base URL to extract prefix from when true
+ * @returns The resolved prefix string to strip
+ *
+ * @example
+ * ```ts
+ * resolveStripPrefix(true, "https://localhost:3000/api"); // "api"
+ * resolveStripPrefix("api/v1", "https://localhost:3000/api"); // "api/v1"
+ * resolveStripPrefix(false, "https://localhost:3000/api"); // ""
+ * resolveStripPrefix(undefined, "https://localhost:3000/api"); // ""
+ * ```
+ */
+declare function resolveStripPrefix(stripPathPrefix: boolean | string | undefined, baseUrl: string): string;
+
 type ProxyHandlerConfig<TOptions = SpooshOptions> = {
     baseUrl: string;
     defaultOptions: TOptions;
     fetchExecutor?: FetchExecutor<TOptions, AnyRequestOptions>;
     nextTags?: boolean;
+    /** Prefix to strip from URL path (auto-detected from baseUrl, always applied) */
+    urlPrefix?: string;
+    /** Prefix to strip from tag generation (defaults to urlPrefix) */
+    tagPrefix?: string;
 };
 /**
  * Creates an API client proxy that uses path strings instead of chained property access.
@@ -1514,7 +1670,7 @@ declare function extractPathFromSelector(fn: unknown): string;
  */
 declare function extractMethodFromSelector(fn: unknown): string | undefined;
 
-declare function executeFetch<TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: SpooshOptions & SpooshOptionsExtra, requestOptions?: AnyRequestOptions, nextTags?: boolean): Promise<SpooshResponse<TData, TError>>;
+declare function executeFetch<TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: SpooshOptions & SpooshOptionsExtra, requestOptions?: AnyRequestOptions, nextTags?: boolean, tagPath?: string[]): Promise<SpooshResponse<TData, TError>>;
 
 declare function createMiddleware<TData = unknown, TError = unknown>(name: string, phase: MiddlewarePhase, handler: SpooshMiddleware<TData, TError>["handler"]): SpooshMiddleware<TData, TError>;
 declare function applyMiddlewares<TData = unknown, TError = unknown>(context: MiddlewareContext<TData, TError>, middlewares: SpooshMiddleware<TData, TError>[], phase: MiddlewarePhase): Promise<MiddlewareContext<TData, TError>>;
@@ -1608,4 +1764,4 @@ type CreateInfiniteReadOptions<TData, TItem, TError, TRequest> = {
 };
 declare function createInfiniteReadController<TData, TItem, TError, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions>(options: CreateInfiniteReadOptions<TData, TItem, TError, TRequest>): InfiniteReadController<TData, TItem, TError>;
 
-export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type SpooshClientConfig as ClientConfig, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type EventEmitter, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type MiddlewareContext, type MiddlewareHandler, type MiddlewarePhase, type MutationSchemaHelper, type OperationController, type OperationState, type OperationType, type PageContext, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QuerySchemaHelper, type ReadClient, type RefetchEvent, type RequestOptions$1 as RequestOptions, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type RetryConfig, type RouteToPath, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Spoosh, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshMiddleware, type SpooshOptions, type SpooshOptionsExtra, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StateManager, type TagMode, type TagOptions, type WriteClient, applyMiddlewares, buildUrl, composeMiddlewares, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createMiddleware, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createSelectorProxy, createStateManager, executeFetch, extractMethodFromSelector, extractPathFromSelector, generateTags, getContentType, isJsonBody, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveTags, setHeaders, sortObjectKeys };
+export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type SpooshClientConfig as ClientConfig, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type EventEmitter, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type MiddlewareContext, type MiddlewareHandler, type MiddlewarePhase, type OperationController, type OperationState, type OperationType, type PageContext, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextInput, type PluginExecutor, type PluginExecutorOptions, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestOptions$1 as RequestOptions, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type RetryConfig, type RouteToPath, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshConfigOptions, type SpooshInstance, type SpooshMiddleware, type SpooshOptions, type SpooshOptionsExtra, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StateManager, type StripPrefix, type TagMode, type TagOptions, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, __DEV__, applyMiddlewares, buildUrl, composeMiddlewares, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createMiddleware, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createSelectorProxy, createStateManager, executeFetch, extractMethodFromSelector, extractPathFromSelector, extractPrefixFromBaseUrl, form, generateTags, getContentType, isJsonBody, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveRequestBody, resolveStripPrefix, resolveTags, setHeaders, sortObjectKeys, stripPrefixFromPath, urlencoded };