@spoosh/core 0.1.0-beta.0 → 0.2.0

package/dist/index.d.ts

@@ -176,6 +176,40 @@ type EventEmitter = {
 };
 declare function createEventEmitter(): EventEmitter;
 
+type Subscriber = () => void;
+type CacheEntryWithKey<TData = unknown, TError = unknown> = {
+    key: string;
+    entry: CacheEntry<TData, TError>;
+};
+declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
+type StateManager = {
+    createQueryKey: (params: {
+        path: string[];
+        method: string;
+        options?: unknown;
+    }) => string;
+    getCache: <TData, TError>(key: string) => CacheEntry<TData, TError> | undefined;
+    setCache: <TData, TError>(key: string, entry: Partial<CacheEntry<TData, TError>>) => void;
+    deleteCache: (key: string) => void;
+    subscribeCache: (key: string, callback: Subscriber) => () => void;
+    getCacheByTags: <TData>(tags: string[]) => CacheEntry<TData> | undefined;
+    getCacheEntriesByTags: <TData, TError>(tags: string[]) => CacheEntryWithKey<TData, TError>[];
+    getCacheEntriesBySelfTag: <TData, TError>(selfTag: string) => CacheEntryWithKey<TData, TError>[];
+    setPluginResult: (key: string, data: Record<string, unknown>) => void;
+    /** Mark all cache entries with matching tags as stale */
+    markStale: (tags: string[]) => void;
+    /** Get all cache entries */
+    getAllCacheEntries: <TData, TError>() => CacheEntryWithKey<TData, TError>[];
+    /** Get the number of cache entries */
+    getSize: () => number;
+    /** Set a pending promise for a query key (for deduplication) */
+    setPendingPromise: (key: string, promise: Promise<unknown> | undefined) => void;
+    /** Get a pending promise for a query key */
+    getPendingPromise: (key: string) => Promise<unknown> | undefined;
+    clear: () => void;
+};
+declare function createStateManager(): StateManager;
+
 type OperationType = "read" | "write" | "infiniteRead";
 type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
 type OperationState<TData = unknown, TError = unknown> = {
@@ -536,40 +570,6 @@ type InstanceApiContext<TApi = unknown> = {
     pluginExecutor: InstancePluginExecutor;
 };
 
-type Subscriber = () => void;
-type CacheEntryWithKey<TData = unknown, TError = unknown> = {
-    key: string;
-    entry: CacheEntry<TData, TError>;
-};
-declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
-type StateManager = {
-    createQueryKey: (params: {
-        path: string[];
-        method: string;
-        options?: unknown;
-    }) => string;
-    getCache: <TData, TError>(key: string) => CacheEntry<TData, TError> | undefined;
-    setCache: <TData, TError>(key: string, entry: Partial<CacheEntry<TData, TError>>) => void;
-    deleteCache: (key: string) => void;
-    subscribeCache: (key: string, callback: Subscriber) => () => void;
-    getCacheByTags: <TData>(tags: string[]) => CacheEntry<TData> | undefined;
-    getCacheEntriesByTags: <TData, TError>(tags: string[]) => CacheEntryWithKey<TData, TError>[];
-    getCacheEntriesBySelfTag: <TData, TError>(selfTag: string) => CacheEntryWithKey<TData, TError>[];
-    setPluginResult: (key: string, data: Record<string, unknown>) => void;
-    /** Mark all cache entries with matching tags as stale */
-    markStale: (tags: string[]) => void;
-    /** Get all cache entries */
-    getAllCacheEntries: <TData, TError>() => CacheEntryWithKey<TData, TError>[];
-    /** Get the number of cache entries */
-    getSize: () => number;
-    /** Set a pending promise for a query key (for deduplication) */
-    setPendingPromise: (key: string, promise: Promise<unknown> | undefined) => void;
-    /** Get a pending promise for a query key */
-    getPendingPromise: (key: string) => Promise<unknown> | undefined;
-    clear: () => void;
-};
-declare function createStateManager(): StateManager;
-
 type PluginExecutor = {
     /** Execute lifecycle hooks for onMount or onUnmount */
     executeLifecycle: <TData, TError>(phase: "onMount" | "onUnmount", operationType: OperationType, context: PluginContext<TData, TError>) => Promise<void>;
@@ -583,6 +583,117 @@ type PluginExecutor = {
 };
 declare function createPluginExecutor(initialPlugins?: SpooshPlugin[]): PluginExecutor;
 
+/**
+ * Resolves plugin option types based on the full context.
+ *
+ * This is the single entry point for all type resolution. It receives
+ * the full ResolverContext containing schema, data, error, and input types,
+ * and resolves each option key accordingly.
+ *
+ * Plugins extend PluginResolvers via declaration merging to add their own
+ * resolved option types.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types.ts:
+ * declare module "@spoosh/core" {
+ *   interface PluginResolvers<TContext> {
+ *     myOption: MyResolvedType<TContext["data"]> | undefined;
+ *   }
+ * }
+ *
+ * // Type resolution:
+ * type ResolvedOptions = ResolveTypes<
+ *   MergePluginOptions<TPlugins>["read"],
+ *   {
+ *     schema: ApiSchema;
+ *     data: Post[];
+ *     error: Error;
+ *     input: { query: { page: number }; body: never; params: never; formData: never };
+ *   }
+ * >;
+ * ```
+ */
+type ResolveTypes<TOptions, TContext extends ResolverContext> = {
+    [K in keyof TOptions]: K extends keyof PluginResolvers<TContext> ? PluginResolvers<TContext>[K] : TOptions[K] extends DataAwareCallback<infer R, unknown, unknown> | undefined ? DataAwareCallback<R, TContext["data"], TContext["error"]> | undefined : TOptions[K] extends DataAwareTransform<unknown, unknown> | undefined ? DataAwareTransform<TContext["data"], TContext["error"]> | undefined : TOptions[K];
+};
+/**
+ * Resolves schema-aware types in plugin options.
+ * This is a simplified resolver for write operations that only need schema context.
+ */
+type ResolveSchemaTypes<TOptions, TSchema> = ResolveTypes<TOptions, ResolverContext<TSchema>>;
+/**
+ * Resolves plugin result types based on the options passed to the hook.
+ *
+ * This allows plugins to infer result types from the options. For example,
+ * the transform plugin can infer `transformedData` type from the response
+ * transformer's return type.
+ *
+ * @example
+ * ```ts
+ * // Usage in hooks:
+ * type ResolvedResults = ResolveResultTypes<PluginResults["read"], TReadOpts>;
+ * // If TReadOpts has { transform: { response: (d) => { count: number } } }
+ * // Then transformedData will be { count: number } | undefined
+ * ```
+ */
+type ResolveResultTypes<TResults, TOptions> = TResults & PluginResultResolvers<TOptions>;
+/**
+ * Resolves instance API types with schema awareness.
+ * Maps each key in TInstanceApi to its resolved type from resolvers.
+ *
+ * Plugins extend InstanceApiResolvers via declaration merging to add their own
+ * resolved instance API types.
+ *
+ * @example
+ * ```ts
+ * // In your plugin's types.ts:
+ * declare module "@spoosh/core" {
+ *   interface InstanceApiResolvers<TSchema> {
+ *     prefetch: PrefetchFn<TSchema>;
+ *   }
+ * }
+ * ```
+ */
+type ResolveInstanceApi<TInstanceApi, TSchema, TReadOptions = object> = {
+    [K in keyof TInstanceApi]: K extends keyof InstanceApiResolvers<TSchema> ? InstanceApiResolvers<TSchema>[K] : TInstanceApi[K];
+};
+
+type ExtractReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    readOptions: infer R;
+} ? R : object : object;
+type ExtractWriteOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    writeOptions: infer W;
+} ? W : object : object;
+type ExtractInfiniteReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    infiniteReadOptions: infer I;
+} ? I : object : object;
+type ExtractReadResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    readResult: infer R;
+} ? R : object : object;
+type ExtractWriteResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    writeResult: infer W;
+} ? W : object : object;
+type ExtractInstanceApi<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    instanceApi: infer A;
+} ? A : object : object;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
+    read: UnionToIntersection<ExtractReadOptions<TPlugins[number]>>;
+    write: UnionToIntersection<ExtractWriteOptions<TPlugins[number]>>;
+    infiniteRead: UnionToIntersection<ExtractInfiniteReadOptions<TPlugins[number]>>;
+};
+type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
+    read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
+    write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
+};
+type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
+type PluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]> = {
+    plugins: TPlugins;
+    _options: MergePluginOptions<TPlugins>;
+};
+declare function createPluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]>(plugins: [...TPlugins]): PluginRegistry<TPlugins>;
+
 declare const EndpointBrand: unique symbol;
 /**
  * Define an API endpoint with its data, request options, and error types.
@@ -722,72 +833,6 @@ type SpooshClient<TSchema, TDefaultError = unknown, TOptionsMap = object, TParam
     [K in keyof StaticPathKeys<TSchema> as K extends SchemaMethod ? never : K]: SpooshClient<TSchema[K], TDefaultError, TOptionsMap, TParamNames, TRootSchema>;
 };
 
-type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
-interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
-    baseUrl: string;
-    defaultOptions?: SpooshOptions;
-    plugins?: TPlugins;
-}
-type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends PluginArray = PluginArray> = {
-    api: SpooshClient<TSchema, TDefaultError, CoreRequestOptionsBase>;
-    stateManager: StateManager;
-    eventEmitter: EventEmitter;
-    pluginExecutor: PluginExecutor;
-    config: {
-        baseUrl: string;
-        defaultOptions: SpooshOptions;
-    };
-    _types: {
-        schema: TSchema;
-        defaultError: TDefaultError;
-        plugins: TPlugins;
-    };
-};
-
-declare function createSpoosh<TSchema = unknown, TDefaultError = unknown, const TPlugins extends PluginArray = PluginArray>(config: SpooshConfig<TPlugins>): SpooshInstance<TSchema, TDefaultError, TPlugins>;
-
-type SpooshClientConfig = {
-    baseUrl: string;
-    defaultOptions?: SpooshOptions;
-    middlewares?: SpooshMiddleware[];
-};
-/**
- * Creates a lightweight type-safe API client for vanilla JavaScript/TypeScript usage.
- *
- * This is a simpler alternative to `createSpoosh` for users who don't need
- * the full plugin system, state management, or React integration.
- *
- * @param config - Client configuration
- * @returns Type-safe API client
- *
- * @example
- * ```ts
- * type ApiSchema = {
- *   posts: {
- *     $get: Endpoint<Post[]>;
- *     $post: Endpoint<Post, CreatePostBody>;
- *     _: {
- *       $get: Endpoint<Post>;
- *       $delete: Endpoint<void>;
- *     };
- *   };
- * };
- *
- * type ApiError = {
- *   message: string;
- * }
- *
- * const api = createClient<ApiSchema, ApiError>({
- *   baseUrl: "/api",
- * });
- *
- * // Type-safe API calls
- * const { data } = await api.posts.$get();
- * const { data: post } = await api.posts[123].$get();
- * ```
- */
-declare function createClient<TSchema, TDefaultError = unknown>(config: SpooshClientConfig): SpooshClient<TSchema, TDefaultError>;
-
 type QueryMethod = "$get";
 type MutationMethod = "$post" | "$put" | "$patch" | "$delete";
 type HasQueryMethods<TSchema> = TSchema extends object ? "$get" extends keyof TSchema ? true : TSchema extends {
@@ -860,13 +905,353 @@ type MutationOnlyClient<TSchema, TDefaultError = unknown, TOptionsMap = object,
     [K in keyof StaticPathKeys<TSchema> as K extends SchemaMethod ? never : HasMutationMethods<TSchema[K]> extends true ? K : never]: MutationOnlyClient<TSchema[K], TDefaultError, TOptionsMap, TParamNames>;
 };
 
-declare function buildUrl(baseUrl: string, path: string[], query?: Record<string, string | number | boolean | undefined>): string;
-
+type ExtractEndpointData<T> = T extends {
+    data: infer D;
+} ? D : T extends void ? void : T;
+type ExtractEndpointRequestOptions<T> = {
+    [K in Extract<keyof T, "query" | "body" | "params">]?: T[K];
+};
+type EndpointToMethod<T> = (options?: ExtractEndpointRequestOptions<T>) => Promise<SpooshResponse<ExtractEndpointData<T>, unknown, ExtractEndpointRequestOptions<T>>>;
 /**
- * Generate cache tags from URL path segments.
- * e.g., ['posts', '1'] → ['posts', 'posts/1']
- */
-declare function generateTags(path: string[]): string[];
+ * Schema navigation helper for plugins that need type-safe API schema access.
+ *
+ * This type transforms the API schema into a navigable structure where:
+ * - Static path segments become nested properties
+ * - Dynamic segments (`_`) become index signatures
+ * - `$get` endpoints become callable method types
+ *
+ * Use this in plugin option types that need to reference API endpoints:
+ *
+ * @example
+ * ```ts
+ * // Define your plugin's callback type
+ * type MyCallbackFn<TSchema = unknown> = (
+ *   api: QuerySchemaHelper<TSchema>
+ * ) => unknown;
+ *
+ * // Usage in plugin options
+ * interface MyPluginWriteOptions {
+ *   myCallback?: MyCallbackFn<unknown>;
+ * }
+ *
+ * // Register for schema resolution
+ * declare module '@spoosh/core' {
+ *   interface SchemaResolvers<TSchema> {
+ *     myCallback: MyCallbackFn<TSchema> | undefined;
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // User's code - paths are type-checked!
+ * trigger({
+ *   myCallback: (api) => [
+ *     api.posts.$get,           // ✓ Valid
+ *     api.users[1].$get,        // ✓ Dynamic segment
+ *     api.nonexistent.$get,     // ✗ Type error
+ *   ],
+ * });
+ * ```
+ */
+type QuerySchemaHelper<TSchema> = {
+    [K in keyof TSchema as K extends SchemaMethod | "_" ? never : HasQueryMethods<TSchema[K]> extends true ? K : never]: K extends keyof TSchema ? QuerySchemaHelper<TSchema[K]> : never;
+} & {
+    [K in "$get" as K extends keyof TSchema ? K : never]: K extends keyof TSchema ? EndpointToMethod<TSchema[K]> : never;
+} & (TSchema extends {
+    _: infer D;
+} ? HasQueryMethods<D> extends true ? {
+    /**
+     * Dynamic path segment placeholder for routes like `/posts/:id`.
+     *
+     * @example
+     * ```ts
+     * // In plugin callback - reference the endpoint
+     * myCallback: (api) => api.posts._.$get
+     * ```
+     */
+    _: QuerySchemaHelper<D>;
+    [key: string]: QuerySchemaHelper<D>;
+    [key: number]: QuerySchemaHelper<D>;
+} : object : object);
+
+type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
+interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
+    baseUrl: string;
+    defaultOptions?: SpooshOptions;
+    plugins?: TPlugins;
+}
+type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends PluginArray = PluginArray> = {
+    api: SpooshClient<TSchema, TDefaultError, CoreRequestOptionsBase>;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: PluginExecutor;
+    config: {
+        baseUrl: string;
+        defaultOptions: SpooshOptions;
+    };
+    _types: {
+        schema: TSchema;
+        defaultError: TDefaultError;
+        plugins: TPlugins;
+    };
+};
+
+/**
+ * Class-based builder for creating Spoosh instances with type-safe plugin inference.
+ *
+ * @template TSchema - The API schema type defining endpoints and their types
+ * @template TError - Default error type for all requests (defaults to unknown)
+ * @template TPlugins - A const tuple of plugin instances for type inference (defaults to empty array)
+ *
+ * @example Basic usage
+ * ```ts
+ * const client = new Spoosh<ApiSchema, Error>('/api')
+ *   .use([cachePlugin(), retryPlugin()]);
+ *
+ * const { api } = client;
+ * const response = await api.posts.$get();
+ * ```
+ *
+ * @example With default options
+ * ```ts
+ * const client = new Spoosh<ApiSchema, Error>('/api', {
+ *   headers: { 'Authorization': 'Bearer token' }
+ * }).use([cachePlugin()]);
+ * ```
+ *
+ * @example With React hooks
+ * ```ts
+ * import { createReactSpoosh } from '@spoosh/react';
+ *
+ * const client = new Spoosh<ApiSchema, Error>('/api')
+ *   .use([cachePlugin(), retryPlugin()]);
+ *
+ * const { useRead, useWrite } = createReactSpoosh(client);
+ * ```
+ *
+ * @since 0.1.0
+ */
+declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends PluginArray = []> {
+    private baseUrl;
+    private defaultOptions;
+    private _plugins;
+    /**
+     * 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.
+     *
+     * @example
+     * ```ts
+     * // Simple usage
+     * const client = new Spoosh<ApiSchema, Error>('/api');
+     *
+     * // With default headers
+     * const client = new Spoosh<ApiSchema, Error>('/api', {
+     *   headers: { 'X-API-Key': 'secret' }
+     * });
+     * ```
+     */
+    constructor(baseUrl: string, defaultOptions?: SpooshOptions, plugins?: TPlugins);
+    /**
+     * Adds plugins to the Spoosh instance.
+     *
+     * Returns a **new** Spoosh instance with updated plugin types (immutable pattern).
+     * Each call to `.use()` replaces the previous plugins rather than adding to them.
+     *
+     * @template TNewPlugins - The const tuple type of the new plugins array
+     * @param plugins - Array of plugin instances to use
+     * @returns A new Spoosh instance with the specified plugins
+     *
+     * @example Single use() call
+     * ```ts
+     * const client = new Spoosh<Schema, Error>('/api')
+     *   .use([cachePlugin(), retryPlugin(), debouncePlugin()]);
+     * ```
+     *
+     * @example Chaining use() calls (replaces plugins)
+     * ```ts
+     * const client1 = new Spoosh<Schema, Error>('/api')
+     *   .use([cachePlugin()]);
+     *
+     * // This replaces cachePlugin with retryPlugin
+     * const client2 = client1.use([retryPlugin()]);
+     * ```
+     *
+     * @example With plugin configuration
+     * ```ts
+     * const client = new Spoosh<Schema, Error>('/api').use([
+     *   cachePlugin({ staleTime: 5000 }),
+     *   retryPlugin({ retries: 3, retryDelay: 1000 }),
+     *   prefetchPlugin(),
+     * ]);
+     * ```
+     */
+    use<const TNewPlugins extends PluginArray>(plugins: TNewPlugins): Spoosh<TSchema, TError, TNewPlugins>;
+    /**
+     * Cached instance of the underlying SpooshInstance.
+     * Created lazily on first property access.
+     * @private
+     */
+    private _instance?;
+    /**
+     * Gets or creates the underlying SpooshInstance.
+     * Uses lazy initialization for optimal performance.
+     * @private
+     */
+    private getInstance;
+    /**
+     * The type-safe API client for making requests.
+     *
+     * Provides a proxy-based interface for accessing endpoints defined in your schema.
+     *
+     * @example
+     * ```ts
+     * const client = new Spoosh<ApiSchema, Error>('/api').use([...]);
+     * const { api } = client;
+     *
+     * // GET request
+     * const { data } = await api.posts.$get();
+     *
+     * // POST request with body
+     * const { data } = await api.posts.$post({ body: { title: 'Hello' } });
+     *
+     * // Dynamic path parameters
+     * const { data } = await api.posts[postId].$get();
+     * ```
+     */
+    get api(): SpooshClient<TSchema, TError, CoreRequestOptionsBase>;
+    /**
+     * State manager for cache and state operations.
+     *
+     * Provides methods for managing cached data, invalidating entries, and retrieving state.
+     *
+     * @example
+     * ```ts
+     * const { stateManager } = client;
+     *
+     * // Get cached data
+     * const cache = stateManager.getCache('posts.$get');
+     *
+     * // Invalidate cache by tag
+     * stateManager.invalidate(['posts']);
+     *
+     * // Clear all cache
+     * stateManager.clearCache();
+     * ```
+     */
+    get stateManager(): StateManager;
+    /**
+     * Event emitter for subscribing to refetch and invalidation events.
+     *
+     * Used internally by plugins and hooks to trigger re-fetches.
+     *
+     * @example
+     * ```ts
+     * const { eventEmitter } = client;
+     *
+     * // Subscribe to refetch events
+     * eventEmitter.on('refetch', ({ queryKey, reason }) => {
+     *   console.log(`Refetching ${queryKey} due to ${reason}`);
+     * });
+     * ```
+     */
+    get eventEmitter(): EventEmitter;
+    /**
+     * Plugin executor that manages plugin lifecycle and middleware.
+     *
+     * Provides access to registered plugins and their execution context.
+     *
+     * @example
+     * ```ts
+     * const { pluginExecutor } = client;
+     *
+     * // Get all registered plugins
+     * const plugins = pluginExecutor.getPlugins();
+     *
+     * // Check if a plugin is registered
+     * const hasCache = plugins.some(p => p.name === 'cache');
+     * ```
+     */
+    get pluginExecutor(): PluginExecutor;
+    /**
+     * Configuration object containing baseUrl and defaultOptions.
+     *
+     * @example
+     * ```ts
+     * const { config } = client;
+     * console.log(config.baseUrl); // '/api'
+     * console.log(config.defaultOptions); // { headers: {...} }
+     * ```
+     */
+    get config(): {
+        baseUrl: string;
+        defaultOptions: SpooshOptions;
+    };
+    /**
+     * Type information carrier for generic type inference.
+     * Used internally by TypeScript for type resolution.
+     *
+     * @internal
+     */
+    get _types(): {
+        schema: TSchema;
+        defaultError: TError;
+        plugins: TPlugins;
+    };
+}
+
+type SpooshClientConfig = {
+    baseUrl: string;
+    defaultOptions?: SpooshOptions;
+    middlewares?: SpooshMiddleware[];
+};
+/**
+ * Creates a lightweight type-safe API client for vanilla JavaScript/TypeScript usage.
+ *
+ * This is a simpler alternative to `Spoosh` for users who don't need
+ * the full plugin system, state management, or React integration.
+ *
+ * @param config - Client configuration
+ * @returns Type-safe API client
+ *
+ * @example
+ * ```ts
+ * type ApiSchema = {
+ *   posts: {
+ *     $get: Endpoint<Post[]>;
+ *     $post: Endpoint<Post, CreatePostBody>;
+ *     _: {
+ *       $get: Endpoint<Post>;
+ *       $delete: Endpoint<void>;
+ *     };
+ *   };
+ * };
+ *
+ * type ApiError = {
+ *   message: string;
+ * }
+ *
+ * const api = createClient<ApiSchema, ApiError>({
+ *   baseUrl: "/api",
+ * });
+ *
+ * // Type-safe API calls
+ * const { data } = await api.posts.$get();
+ * const { data: post } = await api.posts[123].$get();
+ * ```
+ */
+declare function createClient<TSchema, TDefaultError = unknown>(config: SpooshClientConfig): SpooshClient<TSchema, TDefaultError>;
+
+declare function buildUrl(baseUrl: string, path: string[], query?: Record<string, string | number | boolean | undefined>): string;
+
+/**
+ * Generate cache tags from URL path segments.
+ * e.g., ['posts', '1'] → ['posts', 'posts/1']
+ */
+declare function generateTags(path: string[]): string[];
 
 declare function isJsonBody(body: unknown): body is Record<string, unknown> | unknown[];
 
@@ -1046,187 +1431,6 @@ declare function createMiddleware<TData = unknown, TError = unknown>(name: strin
 declare function applyMiddlewares<TData = unknown, TError = unknown>(context: MiddlewareContext<TData, TError>, middlewares: SpooshMiddleware<TData, TError>[], phase: MiddlewarePhase): Promise<MiddlewareContext<TData, TError>>;
 declare function composeMiddlewares<TData = unknown, TError = unknown>(...middlewareLists: (SpooshMiddleware<TData, TError>[] | undefined)[]): SpooshMiddleware<TData, TError>[];
 
-/**
- * Resolves plugin option types based on the full context.
- *
- * This is the single entry point for all type resolution. It receives
- * the full ResolverContext containing schema, data, error, and input types,
- * and resolves each option key accordingly.
- *
- * Plugins extend PluginResolvers via declaration merging to add their own
- * resolved option types.
- *
- * @example
- * ```ts
- * // In your plugin's types.ts:
- * declare module "@spoosh/core" {
- *   interface PluginResolvers<TContext> {
- *     myOption: MyResolvedType<TContext["data"]> | undefined;
- *   }
- * }
- *
- * // Type resolution:
- * type ResolvedOptions = ResolveTypes<
- *   MergePluginOptions<TPlugins>["read"],
- *   {
- *     schema: ApiSchema;
- *     data: Post[];
- *     error: Error;
- *     input: { query: { page: number }; body: never; params: never; formData: never };
- *   }
- * >;
- * ```
- */
-type ResolveTypes<TOptions, TContext extends ResolverContext> = {
-    [K in keyof TOptions]: K extends keyof PluginResolvers<TContext> ? PluginResolvers<TContext>[K] : TOptions[K] extends DataAwareCallback<infer R, unknown, unknown> | undefined ? DataAwareCallback<R, TContext["data"], TContext["error"]> | undefined : TOptions[K] extends DataAwareTransform<unknown, unknown> | undefined ? DataAwareTransform<TContext["data"], TContext["error"]> | undefined : TOptions[K];
-};
-/**
- * Resolves schema-aware types in plugin options.
- * This is a simplified resolver for write operations that only need schema context.
- */
-type ResolveSchemaTypes<TOptions, TSchema> = ResolveTypes<TOptions, ResolverContext<TSchema>>;
-/**
- * Resolves plugin result types based on the options passed to the hook.
- *
- * This allows plugins to infer result types from the options. For example,
- * the transform plugin can infer `transformedData` type from the response
- * transformer's return type.
- *
- * @example
- * ```ts
- * // Usage in hooks:
- * type ResolvedResults = ResolveResultTypes<PluginResults["read"], TReadOpts>;
- * // If TReadOpts has { transform: { response: (d) => { count: number } } }
- * // Then transformedData will be { count: number } | undefined
- * ```
- */
-type ResolveResultTypes<TResults, TOptions> = TResults & PluginResultResolvers<TOptions>;
-/**
- * Resolves instance API types with schema awareness.
- * Maps each key in TInstanceApi to its resolved type from resolvers.
- *
- * Plugins extend InstanceApiResolvers via declaration merging to add their own
- * resolved instance API types.
- *
- * @example
- * ```ts
- * // In your plugin's types.ts:
- * declare module "@spoosh/core" {
- *   interface InstanceApiResolvers<TSchema> {
- *     prefetch: PrefetchFn<TSchema>;
- *   }
- * }
- * ```
- */
-type ResolveInstanceApi<TInstanceApi, TSchema, TReadOptions = object> = {
-    [K in keyof TInstanceApi]: K extends keyof InstanceApiResolvers<TSchema> ? InstanceApiResolvers<TSchema>[K] : TInstanceApi[K];
-};
-
-type ExtractReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    readOptions: infer R;
-} ? R : object : object;
-type ExtractWriteOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    writeOptions: infer W;
-} ? W : object : object;
-type ExtractInfiniteReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    infiniteReadOptions: infer I;
-} ? I : object : object;
-type ExtractReadResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    readResult: infer R;
-} ? R : object : object;
-type ExtractWriteResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    writeResult: infer W;
-} ? W : object : object;
-type ExtractInstanceApi<T> = T extends SpooshPlugin<infer Types> ? Types extends {
-    instanceApi: infer A;
-} ? A : object : object;
-type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
-type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
-    read: UnionToIntersection<ExtractReadOptions<TPlugins[number]>>;
-    write: UnionToIntersection<ExtractWriteOptions<TPlugins[number]>>;
-    infiniteRead: UnionToIntersection<ExtractInfiniteReadOptions<TPlugins[number]>>;
-};
-type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
-    read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
-    write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
-};
-type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
-type PluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]> = {
-    plugins: TPlugins;
-    _options: MergePluginOptions<TPlugins>;
-};
-declare function createPluginRegistry<TPlugins extends SpooshPlugin<PluginTypeConfig>[]>(plugins: [...TPlugins]): PluginRegistry<TPlugins>;
-
-type ExtractEndpointData<T> = T extends {
-    data: infer D;
-} ? D : T extends void ? void : T;
-type ExtractEndpointRequestOptions<T> = {
-    [K in Extract<keyof T, "query" | "body" | "params">]?: T[K];
-};
-type EndpointToMethod<T> = (options?: ExtractEndpointRequestOptions<T>) => Promise<SpooshResponse<ExtractEndpointData<T>, unknown, ExtractEndpointRequestOptions<T>>>;
-/**
- * Schema navigation helper for plugins that need type-safe API schema access.
- *
- * This type transforms the API schema into a navigable structure where:
- * - Static path segments become nested properties
- * - Dynamic segments (`_`) become index signatures
- * - `$get` endpoints become callable method types
- *
- * Use this in plugin option types that need to reference API endpoints:
- *
- * @example
- * ```ts
- * // Define your plugin's callback type
- * type MyCallbackFn<TSchema = unknown> = (
- *   api: QuerySchemaHelper<TSchema>
- * ) => unknown;
- *
- * // Usage in plugin options
- * interface MyPluginWriteOptions {
- *   myCallback?: MyCallbackFn<unknown>;
- * }
- *
- * // Register for schema resolution
- * declare module '@spoosh/core' {
- *   interface SchemaResolvers<TSchema> {
- *     myCallback: MyCallbackFn<TSchema> | undefined;
- *   }
- * }
- * ```
- *
- * @example
- * ```ts
- * // User's code - paths are type-checked!
- * trigger({
- *   myCallback: (api) => [
- *     api.posts.$get,           // ✓ Valid
- *     api.users[1].$get,        // ✓ Dynamic segment
- *     api.nonexistent.$get,     // ✗ Type error
- *   ],
- * });
- * ```
- */
-type QuerySchemaHelper<TSchema> = {
-    [K in keyof TSchema as K extends SchemaMethod | "_" ? never : HasQueryMethods<TSchema[K]> extends true ? K : never]: K extends keyof TSchema ? QuerySchemaHelper<TSchema[K]> : never;
-} & {
-    [K in "$get" as K extends keyof TSchema ? K : never]: K extends keyof TSchema ? EndpointToMethod<TSchema[K]> : never;
-} & (TSchema extends {
-    _: infer D;
-} ? HasQueryMethods<D> extends true ? {
-    /**
-     * Dynamic path segment placeholder for routes like `/posts/:id`.
-     *
-     * @example
-     * ```ts
-     * // In plugin callback - reference the endpoint
-     * myCallback: (api) => api.posts._.$get
-     * ```
-     */
-    _: QuerySchemaHelper<D>;
-    [key: string]: QuerySchemaHelper<D>;
-    [key: number]: QuerySchemaHelper<D>;
-} : object : object);
-
 type ExecuteOptions = {
     force?: boolean;
 };
@@ -1315,4 +1519,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 BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type SpooshClientConfig as ClientConfig, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type Endpoint, type EventEmitter, type ExtractBody, type ExtractData, type ExtractError, type ExtractFormData, type ExtractMethodDef, type ExtractMethodOptions, type ExtractQuery, type ExtractUrlEncoded, type FetchDirection, type FetchExecutor, HTTP_METHODS, type HasMethod, type HasQueryMethods, type HasRequiredOptions, 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 MethodFn, type MethodOptionsMap, type MiddlewareContext, type MiddlewareHandler, type MiddlewarePhase, type MutationOnlyClient, type NormalizeEndpoint, 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 QueryOnlyClient, type QuerySchemaHelper, type RefetchEvent, type RequestOptions, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type RetryConfig, type SchemaMethod, type SelectedEndpoint, type SelectorFunction, type SelectorResult, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshMiddleware, type SpooshOptions, type SpooshOptionsExtra, type SpooshPlugin, type SpooshResponse, type StateManager, type StaticPathKeys, type TagOptions, applyMiddlewares, buildUrl, composeMiddlewares, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createMiddleware, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createSelectorProxy, createSpoosh, createStateManager, executeFetch, extractMethodFromSelector, extractPathFromSelector, generateTags, isJsonBody, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveTags, setHeaders, sortObjectKeys };
+export { type AnyRequestOptions, 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 Endpoint, type EventEmitter, type ExtractBody, type ExtractData, type ExtractError, type ExtractFormData, type ExtractMethodDef, type ExtractMethodOptions, type ExtractQuery, type ExtractUrlEncoded, type FetchDirection, type FetchExecutor, HTTP_METHODS, type HasMethod, type HasQueryMethods, type HasRequiredOptions, 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 MethodFn, type MethodOptionsMap, type MiddlewareContext, type MiddlewareHandler, type MiddlewarePhase, type MutationOnlyClient, type NormalizeEndpoint, 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 QueryOnlyClient, type QuerySchemaHelper, type RefetchEvent, type RequestOptions, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type RetryConfig, type SchemaMethod, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Spoosh, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshMiddleware, type SpooshOptions, type SpooshOptionsExtra, type SpooshPlugin, type SpooshResponse, type StateManager, type StaticPathKeys, type TagOptions, applyMiddlewares, buildUrl, composeMiddlewares, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createMiddleware, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createSelectorProxy, createStateManager, executeFetch, extractMethodFromSelector, extractPathFromSelector, generateTags, isJsonBody, mergeHeaders, objectToFormData, objectToUrlEncoded, resolveHeadersToRecord, resolvePath, resolveTags, setHeaders, sortObjectKeys };