@spoosh/core 0.9.0 → 0.9.1

package/dist/index.d.mts

@@ -124,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 : {
@@ -251,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>;
@@ -596,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.
@@ -863,6 +871,33 @@ type HasReadMethod<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPa
  * 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 IsNever<T> = [T] extends [never] ? true : false;
 type EndpointRequestOptions<TEndpoint, TPath extends string> = (IsNever<ExtractBody$1<TEndpoint>> extends true ? object : {
@@ -1056,6 +1091,33 @@ type WritePathMethods<TSchema, TPath extends string, TDefaultError> = FindMatchi
 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;
@@ -1069,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;
@@ -1120,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
@@ -1138,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.
      *
@@ -1174,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.
@@ -1273,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.
@@ -1291,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.
@@ -1384,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.
@@ -1515,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>>;
@@ -1609,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 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 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 SpooshInstance, type SpooshMiddleware, type SpooshOptions, type SpooshOptionsExtra, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StateManager, 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, form, generateTags, getContentType, isJsonBody, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded };
+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 };

package/dist/index.d.ts

@@ -124,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 : {
@@ -251,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>;
@@ -596,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.
@@ -863,6 +871,33 @@ type HasReadMethod<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPa
  * 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 IsNever<T> = [T] extends [never] ? true : false;
 type EndpointRequestOptions<TEndpoint, TPath extends string> = (IsNever<ExtractBody$1<TEndpoint>> extends true ? object : {
@@ -1056,6 +1091,33 @@ type WritePathMethods<TSchema, TPath extends string, TDefaultError> = FindMatchi
 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;
@@ -1069,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;
@@ -1120,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
@@ -1138,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.
      *
@@ -1174,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.
@@ -1273,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.
@@ -1291,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.
@@ -1384,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.
@@ -1515,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>>;
@@ -1609,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 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 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 SpooshInstance, type SpooshMiddleware, type SpooshOptions, type SpooshOptionsExtra, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StateManager, 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, form, generateTags, getContentType, isJsonBody, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded };
+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 };

package/dist/index.js

@@ -41,6 +41,7 @@ __export(src_exports, {
   executeFetch: () => executeFetch,
   extractMethodFromSelector: () => extractMethodFromSelector,
   extractPathFromSelector: () => extractPathFromSelector,
+  extractPrefixFromBaseUrl: () => extractPrefixFromBaseUrl,
   form: () => form,
   generateTags: () => generateTags,
   getContentType: () => getContentType,
@@ -53,9 +54,11 @@ __export(src_exports, {
   resolveHeadersToRecord: () => resolveHeadersToRecord,
   resolvePath: () => resolvePath,
   resolveRequestBody: () => resolveRequestBody,
+  resolveStripPrefix: () => resolveStripPrefix,
   resolveTags: () => resolveTags,
   setHeaders: () => setHeaders,
   sortObjectKeys: () => sortObjectKeys,
+  stripPrefixFromPath: () => stripPrefixFromPath,
   urlencoded: () => urlencoded
 });
 module.exports = __toCommonJS(src_exports);
@@ -368,11 +371,41 @@ function resolvePath(path, params) {
   });
 }
 
+// src/utils/stripPathPrefix.ts
+function extractPrefixFromBaseUrl(baseUrl) {
+  const isAbsolute = /^https?:\/\//.test(baseUrl);
+  if (isAbsolute) {
+    try {
+      const url = new URL(baseUrl);
+      return url.pathname.replace(/^\/|\/$/g, "");
+    } catch {
+      return "";
+    }
+  }
+  return baseUrl.replace(/^\/|\/$/g, "");
+}
+function stripPrefixFromPath(pathSegments, prefix) {
+  if (!prefix) return pathSegments;
+  const prefixSegments = prefix.split("/").filter(Boolean);
+  if (prefixSegments.length === 0) return pathSegments;
+  const startsWithPrefix = prefixSegments.every(
+    (seg, i) => pathSegments[i] === seg
+  );
+  return startsWithPrefix ? pathSegments.slice(prefixSegments.length) : pathSegments;
+}
+function resolveStripPrefix(stripPathPrefix, baseUrl) {
+  if (!stripPathPrefix) return "";
+  if (stripPathPrefix === true) {
+    return extractPrefixFromBaseUrl(baseUrl);
+  }
+  return stripPathPrefix.replace(/^\/|\/$/g, "");
+}
+
 // src/fetch.ts
 var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var isNetworkError = (err) => err instanceof TypeError;
 var isAbortError = (err) => err instanceof DOMException && err.name === "AbortError";
-async function executeFetch(baseUrl, path, method, defaultOptions, requestOptions, nextTags) {
+async function executeFetch(baseUrl, path, method, defaultOptions, requestOptions, nextTags, tagPath) {
   const middlewares = defaultOptions.middlewares ?? [];
   let context = {
     baseUrl,
@@ -392,7 +425,8 @@ async function executeFetch(baseUrl, path, method, defaultOptions, requestOption
     defaultOptions: context.defaultOptions,
     requestOptions: context.requestOptions,
     middlewareFetchInit: context.fetchInit,
-    nextTags
+    nextTags,
+    tagPath
   });
   context.response = response;
   if (middlewares.length > 0) {
@@ -424,7 +458,8 @@ async function executeCoreFetch(config) {
     defaultOptions,
     requestOptions,
     middlewareFetchInit,
-    nextTags
+    nextTags,
+    tagPath
   } = config;
   const {
     middlewares: _,
@@ -449,7 +484,7 @@ async function executeCoreFetch(config) {
   }
   fetchInit.cache = requestOptions?.cache ?? fetchDefaults?.cache;
   if (nextTags) {
-    const autoTags = generateTags(path);
+    const autoTags = generateTags(tagPath ?? path);
     const userNext = requestOptions?.next;
     fetchInit.next = {
       tags: userNext?.tags ?? autoTags,
@@ -540,8 +575,11 @@ function createProxyHandler(config) {
     baseUrl,
     defaultOptions,
     fetchExecutor = executeFetch,
-    nextTags
+    nextTags,
+    urlPrefix,
+    tagPrefix
   } = config;
+  const effectiveTagPrefix = tagPrefix ?? urlPrefix;
   return ((path) => {
     return new Proxy(
       {},
@@ -554,13 +592,16 @@ function createProxyHandler(config) {
           }
           return (options) => {
             const resolvedPath = resolvePath2(path, options?.params);
+            const urlPath = urlPrefix ? stripPrefixFromPath(resolvedPath, urlPrefix) : resolvedPath;
+            const tagPath = effectiveTagPrefix ? stripPrefixFromPath(resolvedPath, effectiveTagPrefix) : resolvedPath;
             return fetchExecutor(
               baseUrl,
-              resolvedPath,
+              urlPath,
               method,
               defaultOptions,
               options,
-              nextTags
+              nextTags,
+              tagPath
             );
           };
         }
@@ -843,7 +884,8 @@ function sortByDependencies(plugins) {
   }
   return sorted;
 }
-function createPluginExecutor(initialPlugins = []) {
+function createPluginExecutor(initialPlugins = [], options = {}) {
+  const { stripTagPrefix } = options;
   validateDependencies(initialPlugins);
   const plugins = sortByDependencies(initialPlugins);
   const frozenPlugins = Object.freeze([...plugins]);
@@ -927,6 +969,9 @@ function createPluginExecutor(initialPlugins = []) {
         ctx.headers = { ...ctx.headers, ...newHeaders };
         ctx.requestOptions.headers = ctx.headers;
       };
+      if (stripTagPrefix) {
+        ctx.stripTagPrefix = stripTagPrefix;
+      }
       return ctx;
     }
   };
@@ -945,12 +990,14 @@ var Spoosh = class _Spoosh {
   baseUrl;
   defaultOptions;
   _plugins;
+  _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
@@ -963,10 +1010,11 @@ var Spoosh = class _Spoosh {
    * });
    * ```
    */
-  constructor(baseUrl, defaultOptions, plugins) {
+  constructor(baseUrl, defaultOptions, plugins, configOptions) {
     this.baseUrl = baseUrl;
     this.defaultOptions = defaultOptions || {};
     this._plugins = plugins || [];
+    this._config = configOptions || {};
   }
   /**
    * Adds plugins to the Spoosh instance.
@@ -1006,7 +1054,43 @@ var Spoosh = class _Spoosh {
     return new _Spoosh(
       this.baseUrl,
       this.defaultOptions,
-      plugins
+      plugins,
+      this._config
+    );
+  }
+  /**
+   * 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) {
+    return new _Spoosh(
+      this.baseUrl,
+      this.defaultOptions,
+      this._plugins,
+      { ...this._config, ...options }
     );
   }
   /**
@@ -1022,13 +1106,19 @@ var Spoosh = class _Spoosh {
    */
   getInstance() {
     if (!this._instance) {
+      const urlPrefix = extractPrefixFromBaseUrl(this.baseUrl) || void 0;
+      const tagPrefix = this._config.stripTagPrefix ?? urlPrefix;
       const api = createProxyHandler({
         baseUrl: this.baseUrl,
-        defaultOptions: this.defaultOptions
+        defaultOptions: this.defaultOptions,
+        urlPrefix,
+        tagPrefix
       });
       const stateManager = createStateManager();
       const eventEmitter = createEventEmitter();
-      const pluginExecutor = createPluginExecutor([...this._plugins]);
+      const pluginExecutor = createPluginExecutor([...this._plugins], {
+        stripTagPrefix: tagPrefix
+      });
       this._instance = {
         api,
         stateManager,
@@ -1036,7 +1126,8 @@ var Spoosh = class _Spoosh {
         pluginExecutor,
         config: {
           baseUrl: this.baseUrl,
-          defaultOptions: this.defaultOptions
+          defaultOptions: this.defaultOptions,
+          stripTagPrefix: tagPrefix
         },
         _types: {
           schema: void 0,
@@ -1155,12 +1246,21 @@ var Spoosh = class _Spoosh {
 
 // src/createClient.ts
 function createClient(config) {
-  const { baseUrl, defaultOptions = {}, middlewares = [] } = config;
+  const {
+    baseUrl,
+    defaultOptions = {},
+    middlewares = [],
+    stripTagPrefix
+  } = config;
   const optionsWithMiddlewares = { ...defaultOptions, middlewares };
+  const urlPrefix = extractPrefixFromBaseUrl(baseUrl) || void 0;
+  const tagPrefix = stripTagPrefix ?? urlPrefix;
   return createProxyHandler({
     baseUrl,
     defaultOptions: optionsWithMiddlewares,
-    nextTags: true
+    nextTags: true,
+    urlPrefix,
+    tagPrefix
   });
 }
 

package/dist/index.mjs

@@ -306,11 +306,41 @@ function resolvePath(path, params) {
   });
 }
 
+// src/utils/stripPathPrefix.ts
+function extractPrefixFromBaseUrl(baseUrl) {
+  const isAbsolute = /^https?:\/\//.test(baseUrl);
+  if (isAbsolute) {
+    try {
+      const url = new URL(baseUrl);
+      return url.pathname.replace(/^\/|\/$/g, "");
+    } catch {
+      return "";
+    }
+  }
+  return baseUrl.replace(/^\/|\/$/g, "");
+}
+function stripPrefixFromPath(pathSegments, prefix) {
+  if (!prefix) return pathSegments;
+  const prefixSegments = prefix.split("/").filter(Boolean);
+  if (prefixSegments.length === 0) return pathSegments;
+  const startsWithPrefix = prefixSegments.every(
+    (seg, i) => pathSegments[i] === seg
+  );
+  return startsWithPrefix ? pathSegments.slice(prefixSegments.length) : pathSegments;
+}
+function resolveStripPrefix(stripPathPrefix, baseUrl) {
+  if (!stripPathPrefix) return "";
+  if (stripPathPrefix === true) {
+    return extractPrefixFromBaseUrl(baseUrl);
+  }
+  return stripPathPrefix.replace(/^\/|\/$/g, "");
+}
+
 // src/fetch.ts
 var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 var isNetworkError = (err) => err instanceof TypeError;
 var isAbortError = (err) => err instanceof DOMException && err.name === "AbortError";
-async function executeFetch(baseUrl, path, method, defaultOptions, requestOptions, nextTags) {
+async function executeFetch(baseUrl, path, method, defaultOptions, requestOptions, nextTags, tagPath) {
   const middlewares = defaultOptions.middlewares ?? [];
   let context = {
     baseUrl,
@@ -330,7 +360,8 @@ async function executeFetch(baseUrl, path, method, defaultOptions, requestOption
     defaultOptions: context.defaultOptions,
     requestOptions: context.requestOptions,
     middlewareFetchInit: context.fetchInit,
-    nextTags
+    nextTags,
+    tagPath
   });
   context.response = response;
   if (middlewares.length > 0) {
@@ -362,7 +393,8 @@ async function executeCoreFetch(config) {
     defaultOptions,
     requestOptions,
     middlewareFetchInit,
-    nextTags
+    nextTags,
+    tagPath
   } = config;
   const {
     middlewares: _,
@@ -387,7 +419,7 @@ async function executeCoreFetch(config) {
   }
   fetchInit.cache = requestOptions?.cache ?? fetchDefaults?.cache;
   if (nextTags) {
-    const autoTags = generateTags(path);
+    const autoTags = generateTags(tagPath ?? path);
     const userNext = requestOptions?.next;
     fetchInit.next = {
       tags: userNext?.tags ?? autoTags,
@@ -478,8 +510,11 @@ function createProxyHandler(config) {
     baseUrl,
     defaultOptions,
     fetchExecutor = executeFetch,
-    nextTags
+    nextTags,
+    urlPrefix,
+    tagPrefix
   } = config;
+  const effectiveTagPrefix = tagPrefix ?? urlPrefix;
   return ((path) => {
     return new Proxy(
       {},
@@ -492,13 +527,16 @@ function createProxyHandler(config) {
           }
           return (options) => {
             const resolvedPath = resolvePath2(path, options?.params);
+            const urlPath = urlPrefix ? stripPrefixFromPath(resolvedPath, urlPrefix) : resolvedPath;
+            const tagPath = effectiveTagPrefix ? stripPrefixFromPath(resolvedPath, effectiveTagPrefix) : resolvedPath;
             return fetchExecutor(
               baseUrl,
-              resolvedPath,
+              urlPath,
               method,
               defaultOptions,
               options,
-              nextTags
+              nextTags,
+              tagPath
             );
           };
         }
@@ -781,7 +819,8 @@ function sortByDependencies(plugins) {
   }
   return sorted;
 }
-function createPluginExecutor(initialPlugins = []) {
+function createPluginExecutor(initialPlugins = [], options = {}) {
+  const { stripTagPrefix } = options;
   validateDependencies(initialPlugins);
   const plugins = sortByDependencies(initialPlugins);
   const frozenPlugins = Object.freeze([...plugins]);
@@ -865,6 +904,9 @@ function createPluginExecutor(initialPlugins = []) {
         ctx.headers = { ...ctx.headers, ...newHeaders };
         ctx.requestOptions.headers = ctx.headers;
       };
+      if (stripTagPrefix) {
+        ctx.stripTagPrefix = stripTagPrefix;
+      }
       return ctx;
     }
   };
@@ -883,12 +925,14 @@ var Spoosh = class _Spoosh {
   baseUrl;
   defaultOptions;
   _plugins;
+  _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
@@ -901,10 +945,11 @@ var Spoosh = class _Spoosh {
    * });
    * ```
    */
-  constructor(baseUrl, defaultOptions, plugins) {
+  constructor(baseUrl, defaultOptions, plugins, configOptions) {
     this.baseUrl = baseUrl;
     this.defaultOptions = defaultOptions || {};
     this._plugins = plugins || [];
+    this._config = configOptions || {};
   }
   /**
    * Adds plugins to the Spoosh instance.
@@ -944,7 +989,43 @@ var Spoosh = class _Spoosh {
     return new _Spoosh(
       this.baseUrl,
       this.defaultOptions,
-      plugins
+      plugins,
+      this._config
+    );
+  }
+  /**
+   * 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) {
+    return new _Spoosh(
+      this.baseUrl,
+      this.defaultOptions,
+      this._plugins,
+      { ...this._config, ...options }
     );
   }
   /**
@@ -960,13 +1041,19 @@ var Spoosh = class _Spoosh {
    */
   getInstance() {
     if (!this._instance) {
+      const urlPrefix = extractPrefixFromBaseUrl(this.baseUrl) || void 0;
+      const tagPrefix = this._config.stripTagPrefix ?? urlPrefix;
       const api = createProxyHandler({
         baseUrl: this.baseUrl,
-        defaultOptions: this.defaultOptions
+        defaultOptions: this.defaultOptions,
+        urlPrefix,
+        tagPrefix
       });
       const stateManager = createStateManager();
       const eventEmitter = createEventEmitter();
-      const pluginExecutor = createPluginExecutor([...this._plugins]);
+      const pluginExecutor = createPluginExecutor([...this._plugins], {
+        stripTagPrefix: tagPrefix
+      });
       this._instance = {
         api,
         stateManager,
@@ -974,7 +1061,8 @@ var Spoosh = class _Spoosh {
         pluginExecutor,
         config: {
           baseUrl: this.baseUrl,
-          defaultOptions: this.defaultOptions
+          defaultOptions: this.defaultOptions,
+          stripTagPrefix: tagPrefix
         },
         _types: {
           schema: void 0,
@@ -1093,12 +1181,21 @@ var Spoosh = class _Spoosh {
 
 // src/createClient.ts
 function createClient(config) {
-  const { baseUrl, defaultOptions = {}, middlewares = [] } = config;
+  const {
+    baseUrl,
+    defaultOptions = {},
+    middlewares = [],
+    stripTagPrefix
+  } = config;
   const optionsWithMiddlewares = { ...defaultOptions, middlewares };
+  const urlPrefix = extractPrefixFromBaseUrl(baseUrl) || void 0;
+  const tagPrefix = stripTagPrefix ?? urlPrefix;
   return createProxyHandler({
     baseUrl,
     defaultOptions: optionsWithMiddlewares,
-    nextTags: true
+    nextTags: true,
+    urlPrefix,
+    tagPrefix
   });
 }
 
@@ -1681,6 +1778,7 @@ export {
   executeFetch,
   extractMethodFromSelector,
   extractPathFromSelector,
+  extractPrefixFromBaseUrl,
   form,
   generateTags,
   getContentType,
@@ -1693,8 +1791,10 @@ export {
   resolveHeadersToRecord,
   resolvePath,
   resolveRequestBody,
+  resolveStripPrefix,
   resolveTags,
   setHeaders,
   sortObjectKeys,
+  stripPrefixFromPath,
   urlencoded
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spoosh/core",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "license": "MIT",
   "description": "Type-safe API client with plugin middleware system",
   "keywords": [