@spoosh/core 0.15.1 → 0.17.0

package/dist/index.d.mts

@@ -51,10 +51,10 @@ type SpooshResponse<TData, TError, TRequestOptions = unknown, TQuery = never, TB
  * trigger({ body: urlencoded({ key: "value" }) });
  * ```
  */
-declare class SpooshBodyClass<T> {
-    private __brand;
-}
-type SpooshBody<T = unknown> = SpooshBodyClass<T>;
+declare const __spooshBodyBrand: unique symbol;
+type SpooshBody<T = unknown> = {
+    readonly [__spooshBodyBrand]: T;
+};
 declare function isSpooshBody(value: unknown): value is SpooshBody;
 declare function form<T>(value: T): SpooshBody<T>;
 declare function json<T>(value: T): SpooshBody<T>;
@@ -252,6 +252,7 @@ type StateManager = {
 declare function createStateManager(): StateManager;
 
 declare function createInitialState<TData, TError>(): OperationState<TData, TError>;
+declare function generateSelfTagFromKey(key: string): string | undefined;
 
 /**
  * Devtool-related types for tracing and debugging.
@@ -412,6 +413,51 @@ interface RequestCompleteEvent {
     context: PluginContext;
     queryKey: string;
 }
+/** Event emitted when a subscription starts connecting */
+interface SubscriptionConnectEvent {
+    subscriptionId: string;
+    channel: string;
+    transport: string;
+    connectionUrl: string;
+    queryKey: string;
+    timestamp: number;
+    /** Event types being listened to. Empty or ["*"] means all events. */
+    listenedEvents?: string[];
+}
+/** Event emitted when a subscription successfully connects */
+interface SubscriptionConnectedEvent {
+    subscriptionId: string;
+    timestamp: number;
+}
+/** Event emitted when a subscription receives a message */
+interface SubscriptionMessageEvent {
+    subscriptionId: string;
+    messageId: string;
+    eventType: string;
+    rawData: unknown;
+    accumulatedData: Record<string, unknown>;
+    timestamp: number;
+}
+/** Event emitted when a subscription encounters an error */
+interface SubscriptionErrorEvent {
+    subscriptionId: string;
+    error: Error;
+    retryCount: number;
+    timestamp: number;
+}
+/** Event emitted when a subscription disconnects */
+interface SubscriptionDisconnectEvent {
+    subscriptionId: string;
+    reason: string;
+    timestamp: number;
+}
+/** Event emitted when hook-level accumulation updates data */
+interface SubscriptionAccumulateEvent {
+    queryKey: string;
+    eventType: string;
+    accumulatedData: Record<string, unknown>;
+    timestamp: number;
+}
 /**
  * Internal events used by core and devtools. Not for public use.
  * @internal
@@ -419,6 +465,12 @@ interface RequestCompleteEvent {
 interface DevtoolEvents {
     "spoosh:devtool-event": StandaloneEvent;
     "spoosh:request-complete": RequestCompleteEvent;
+    "spoosh:subscription:connect": SubscriptionConnectEvent;
+    "spoosh:subscription:connected": SubscriptionConnectedEvent;
+    "spoosh:subscription:message": SubscriptionMessageEvent;
+    "spoosh:subscription:error": SubscriptionErrorEvent;
+    "spoosh:subscription:disconnect": SubscriptionDisconnectEvent;
+    "spoosh:subscription:accumulate": SubscriptionAccumulateEvent;
 }
 /**
  * Event tracer API for standalone events not tied to a request lifecycle.
@@ -437,7 +489,42 @@ interface EventTracer {
     emit(msg: string, options?: EventOptions): void;
 }
 
-type OperationType = "read" | "write" | "pages" | "queue";
+interface SpooshTransport<TOptions = unknown, TMessage = unknown> {
+    name: string;
+    operationType: OperationType;
+    connect(url: string, options?: TOptions): Promise<void>;
+    disconnect(): Promise<void>;
+    subscribe(channel: string, callback: (message: TMessage) => void): () => void;
+    send(channel: string, message: TMessage): Promise<void>;
+    isConnected(): boolean;
+}
+interface SpooshTransportRegistry {
+}
+type TransportName = keyof SpooshTransportRegistry;
+interface SubscriptionContext<TData = unknown, TError = unknown> extends PluginContext {
+    channel: string;
+    message?: unknown;
+    onData?: (data: TData) => void;
+    onError?: (error: TError) => void;
+    onDisconnect?: () => void;
+    registerUnsubscribers?: (unsubscribers: Array<() => void>) => void;
+}
+interface SubscriptionAdapter<TData = unknown, TError = unknown> {
+    subscribe(context: SubscriptionContext<TData, TError>): Promise<SubscriptionHandle<TData, TError>>;
+    emit(context: SubscriptionContext<TData, TError>): Promise<{
+        success: boolean;
+        error?: TError;
+    }>;
+}
+interface SubscriptionHandle<TData = unknown, TError = unknown> {
+    unsubscribe(): void;
+    getData(): TData | undefined;
+    getError(): TError | undefined;
+    onData(callback: (data: TData) => void): () => void;
+    onError(callback: (error: TError) => void): () => void;
+}
+
+type OperationType = "read" | "write" | "pages" | "queue" | (string & {});
 type LifecyclePhase = "onMount" | "onUnmount" | "onUpdate";
 type OperationState<TData = unknown, TError = unknown> = {
     data: TData | undefined;
@@ -593,7 +680,7 @@ type PluginLifecycle = {
  *
  * // Plugin with instance-level API
  * SpooshPlugin<{
- *   instanceApi: { prefetch: (selector: Selector) => Promise<void> };
+ *   api: { prefetch: (selector: Selector) => Promise<void> };
  * }>
  * ```
  */
@@ -604,10 +691,13 @@ type PluginTypeConfig = {
     writeTriggerOptions?: object;
     queueOptions?: object;
     queueTriggerOptions?: object;
+    subscribeOptions?: object;
+    subscribeTriggerOptions?: object;
     readResult?: object;
     writeResult?: object;
     queueResult?: object;
-    instanceApi?: object;
+    subscribeResult?: object;
+    api?: object;
 };
 /**
  * Base interface for Spoosh plugins.
@@ -616,7 +706,7 @@ type PluginTypeConfig = {
  * - `middleware`: Wraps the fetch flow for full control (intercept, transform, modify)
  * - `afterResponse`: Called after every response, regardless of early returns
  * - `lifecycle`: Component lifecycle hooks (onMount, onUpdate, onUnmount)
- * - `exports`: Functions/variables accessible to other plugins
+ * - `internal`: Functions/variables accessible to other plugins
  *
  * @typeParam T - Plugin type configuration object. Specify only the types your plugin needs.
  *
@@ -659,11 +749,11 @@ interface SpooshPlugin<T extends PluginTypeConfig = PluginTypeConfig> {
     /** Component lifecycle hooks (setup, cleanup, option changes) */
     lifecycle?: PluginLifecycle;
     /** Expose functions/variables for other plugins to access via `context.plugins.get(name)` */
-    exports?: (context: PluginContext) => object;
+    internal?: (context: PluginContext) => object;
     /**
      * One-time initialization when the Spoosh instance is created.
      * Use for setting up timers, event listeners, or other side effects.
-     * Runs before instanceApi is called.
+     * Runs before api is called.
      *
      * @example
      * ```ts
@@ -688,20 +778,36 @@ interface SpooshPlugin<T extends PluginTypeConfig = PluginTypeConfig> {
     setup?: (context: SetupContext) => void;
     /**
      * Expose functions/properties on the framework adapter return value (e.g., create).
-     * Unlike `exports`, these are accessible directly from the instance, not just within plugin context.
+     * Unlike `internal`, these are accessible directly from the adapter, not just within plugin context.
      * Should be pure - use `setup` for side effects like timers or event listeners.
      *
      * @example
      * ```ts
-     * instanceApi: ({ api, stateManager }) => ({
+     * api: ({ spopiosh, stateManager }) => ({
      *   prefetch: async (selector) => { ... },
      *   invalidateAll: () => { ... },
      * })
      * ```
      */
-    instanceApi?: (context: InstanceApiContext) => T extends {
-        instanceApi: infer A;
+    api?: (context: ApiContext) => T extends {
+        api: infer A;
     } ? A : object;
+    /**
+     * Wrap a subscription adapter to add plugin behavior (e.g., caching, retry, logging).
+     * Called for subscription operations to compose adapter functionality.
+     *
+     * @example
+     * ```ts
+     * wrapAdapter: (inner) => ({
+     *   subscribe: async (ctx) => {
+     *     // Add caching logic
+     *     return inner.subscribe(ctx);
+     *   },
+     *   emit: inner.emit,
+     * })
+     * ```
+     */
+    wrapAdapter?: (inner: SubscriptionAdapter) => SubscriptionAdapter;
     /**
      * Plugin execution priority. Lower numbers run first, higher numbers run last.
      * Default: 0
@@ -834,7 +940,7 @@ interface PluginResolvers<TContext extends ResolverContext> {
 interface PluginResultResolvers<TOptions> {
 }
 /**
- * Registry for plugin exports. Extend via declaration merging for type-safe access.
+ * Registry for plugin internal APIs. Extend via declaration merging for type-safe access.
  *
  * Plugins can expose functions and variables that other plugins can access
  * via `context.plugins.get("plugin-name")`.
@@ -843,38 +949,38 @@ interface PluginResultResolvers<TOptions> {
  * ```ts
  * // In your plugin's types file:
  * declare module '@spoosh/core' {
- *   interface PluginExportsRegistry {
+ *   interface PluginInternalRegistry {
  *     "my-plugin": { myMethod: () => void }
  *   }
  * }
  * ```
  */
-interface PluginExportsRegistry {
+interface PluginInternalRegistry {
 }
 /**
- * Registry for instance API type resolution. Extend via declaration merging.
+ * Registry for public API type resolution. Extend via declaration merging.
  *
- * Plugins that expose schema-aware instance APIs should extend this interface
+ * Plugins that expose schema-aware public APIs should extend this interface
  * to get proper type inference when the API is used.
  *
  * @example
  * ```ts
  * // In your plugin's types file:
  * declare module '@spoosh/core' {
- *   interface InstanceApiResolvers<TSchema> {
+ *   interface ApiResolvers<TSchema> {
  *     myFunction: MyFn<TSchema>;
  *   }
  * }
  * ```
  */
-interface InstanceApiResolvers<TSchema> {
+interface ApiResolvers<TSchema> {
 }
 /**
- * Accessor for plugin exports with type-safe lookup.
+ * Accessor for plugin internal APIs with type-safe lookup.
  */
 type PluginAccessor = {
-    /** Get a plugin's exported API by name. Returns undefined if plugin not found. */
-    get<K extends keyof PluginExportsRegistry>(name: K): PluginExportsRegistry[K] | undefined;
+    /** Get a plugin's internal API by name. Returns undefined if plugin not found. */
+    get<K extends keyof PluginInternalRegistry>(name: K): PluginInternalRegistry[K] | undefined;
     get(name: string): unknown;
 };
 type RefetchEventReason = "focus" | "reconnect" | "polling" | "invalidate";
@@ -887,10 +993,10 @@ type RefetchEvent = {
     reason: RefetchEventReason | Omit<string, RefetchEventReason>;
 };
 /**
- * Minimal PluginExecutor interface for InstanceApiContext.
+ * Minimal PluginExecutor interface for ApiContext.
  * Avoids circular dependency with executor.ts.
  */
-type InstancePluginExecutor = {
+type ApiPluginExecutor = {
     executeMiddleware: <TData, TError>(operationType: OperationType, context: PluginContext, coreFetch: () => Promise<SpooshResponse<any, any>>) => Promise<SpooshResponse<TData, TError>>;
     createContext: (input: PluginContextInput) => PluginContext;
     getPlugins: () => readonly SpooshPlugin[];
@@ -901,14 +1007,14 @@ type InstancePluginExecutor = {
     registerContextEnhancer: (enhancer: (context: PluginContext) => void) => void;
 };
 /**
- * Context provided to plugin's instanceApi function.
- * Used for creating framework-agnostic APIs exposed on the Spoosh instance.
+ * Context provided to plugin's api function.
+ * Used for creating framework-agnostic APIs exposed on the adapter.
  */
-type InstanceApiContext<TApi = unknown> = {
-    api: TApi;
+type ApiContext<TApi = unknown> = {
+    spoosh: TApi;
     stateManager: StateManager;
     eventEmitter: EventEmitter;
-    pluginExecutor: InstancePluginExecutor;
+    pluginExecutor: ApiPluginExecutor;
     /**
      * Creates an event tracer for standalone events.
      * Only available when devtools plugin is active.
@@ -922,7 +1028,7 @@ type InstanceApiContext<TApi = unknown> = {
 type SetupContext = {
     stateManager: StateManager;
     eventEmitter: EventEmitter;
-    pluginExecutor: InstancePluginExecutor;
+    pluginExecutor: ApiPluginExecutor;
     /**
      * Creates an event tracer for standalone events.
      * Only available when devtools plugin is active.
@@ -937,6 +1043,8 @@ type PluginExecutor = {
     executeUpdateLifecycle: (operationType: OperationType, context: PluginContext, previousContext: PluginContext) => Promise<void>;
     executeMiddleware: (operationType: OperationType, context: PluginContext, coreFetch: () => Promise<SpooshResponse<any, any>>) => Promise<SpooshResponse<any, any>>;
     getPlugins: () => readonly SpooshPlugin[];
+    /** Get plugins that support a specific operation type */
+    getPluginsForOperation: (operationType: OperationType) => readonly SpooshPlugin[];
     /** Creates a full PluginContext with plugins accessor */
     createContext: (input: PluginContextInput) => PluginContext;
     /**
@@ -1003,24 +1111,24 @@ type ResolveSchemaTypes<TOptions, TSchema> = ResolveTypes<TOptions, ResolverCont
  */
 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.
+ * Resolves public API types with schema awareness.
+ * Maps each key in TApi to its resolved type from resolvers.
  *
- * Plugins extend InstanceApiResolvers via declaration merging to add their own
- * resolved instance API types.
+ * Plugins extend ApiResolvers via declaration merging to add their own
+ * resolved API types.
  *
  * @example
  * ```ts
  * // In your plugin's types.ts:
  * declare module "@spoosh/core" {
- *   interface InstanceApiResolvers<TSchema> {
+ *   interface ApiResolvers<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 ResolveApi<TApi, TSchema, TReadOptions = object> = {
+    [K in keyof TApi]: K extends keyof ApiResolvers<TSchema> ? ApiResolvers<TSchema>[K] : TApi[K];
 };
 
 type ExtractReadOptions<T> = T extends SpooshPlugin<infer Types> ? Types extends {
@@ -1044,14 +1152,17 @@ type ExtractQueueTriggerOptions<T> = T extends SpooshPlugin<infer Types> ? Types
 type ExtractQueueResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
     queueResult: infer Q;
 } ? Q : object : object;
+type ExtractSubscribeResult<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    subscribeResult: infer S;
+} ? S : 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;
+type ExtractApi<T> = T extends SpooshPlugin<infer Types> ? Types extends {
+    api: infer A;
 } ? A : object : object;
 type UnionToIntersection$1<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
 type MergePluginOptions<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
@@ -1066,18 +1177,29 @@ type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>
     read: UnionToIntersection$1<ExtractReadResult<TPlugins[number]>>;
     write: UnionToIntersection$1<ExtractWriteResult<TPlugins[number]>>;
     queue: UnionToIntersection$1<ExtractQueueResult<TPlugins[number]>>;
+    subscribe: UnionToIntersection$1<ExtractSubscribeResult<TPlugins[number]>>;
 };
-type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection$1<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
+type MergePluginApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveApi<UnionToIntersection$1<ExtractApi<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>;
 
+/**
+ * Registry for subscription methods. Transports extend via module augmentation.
+ */
+interface SpooshSubscriptionMethodRegistry {
+}
+type SubscriptionMethod = keyof SpooshSubscriptionMethodRegistry;
+type AnyMethod = HttpMethod | SubscriptionMethod;
 /**
  * An API schema where routes are defined as string keys with path patterns.
  * Define data, body, query, and error directly on each method.
  *
+ * For subscription endpoints (SSE, WebSocket), define the `events` field instead of `data`.
+ * The transport to use is determined by the hook (useSSE, useWebSocket), not the path.
+ *
  * @example
  * ```ts
  * type ApiSchema = {
@@ -1090,22 +1212,69 @@ declare function createPluginRegistry<TPlugins extends SpooshPlugin<PluginTypeCo
  *     PUT: { data: Post; body: UpdatePostBody };
  *     DELETE: { data: void };
  *   };
- *   "posts/:id/comments": {
- *     GET: { data: Comment[]; query: { page?: number } };
+ *   "notifications": {
+ *     GET: {
+ *       events: {
+ *         alert: { data: Alert };
+ *         message: { data: Message };
+ *       };
+ *       query?: { userId: string };
+ *     };
  *   };
  * };
  * ```
  */
+/**
+ * HTTP endpoint method config.
+ */
+type HttpMethodConfig = {
+    data?: unknown;
+    body?: unknown;
+    query?: unknown;
+    error?: unknown;
+};
+/**
+ * Subscription endpoint method config (SSE, WebSocket, etc.).
+ * Has events field instead of data.
+ */
+type SubscriptionMethodConfig = {
+    events?: Record<string, {
+        data: unknown;
+    }>;
+    body?: unknown;
+    query?: unknown;
+    error?: unknown;
+};
+/**
+ * Endpoint config - supports both HTTP and subscription methods.
+ * Subscription endpoints are those with an `events` field, HTTP endpoints have `data`.
+ */
+type EndpointConfig = {
+    [M in HttpMethod | SubscriptionMethod]?: HttpMethodConfig | SubscriptionMethodConfig;
+};
+/**
+ * Base API schema type.
+ */
 type ApiSchema = {
     [path: string]: {
-        [method in HttpMethod]?: {
-            data?: unknown;
-            body?: unknown;
-            query?: unknown;
-            error?: unknown;
-        };
+        [method: string]: unknown;
     };
 };
+/**
+ * Helper type for defining API schemas with proper autocomplete.
+ * Use `events` field for subscription endpoints, `data` field for HTTP endpoints.
+ *
+ * @example
+ * ```ts
+ * type MyApi = SpooshSchema<{
+ *   "posts": { GET: { data: Post[] } };
+ *   "chat": { GET: { events: { message: { data: string } } } };
+ * }>;
+ * ```
+ */
+type SpooshSchema<T extends {
+    [K in keyof T]: EndpointConfig;
+}> = T;
 /**
  * Extract data type from an endpoint.
  */
@@ -1130,28 +1299,6 @@ type ExtractQuery$1<T> = T extends {
 type ExtractError<T, TDefault = unknown> = T extends {
     error: infer E;
 } ? E : TDefault;
-/**
- * Helper type to define a type-safe API schema.
- * Use this to get type checking on your schema definition.
- *
- * @example
- * ```ts
- * type ApiSchema = SpooshSchema<{
- *   "posts": {
- *     GET: { data: Post[] };
- *     POST: { data: Post; body: CreatePostBody };
- *   };
- *   "posts/:id": {
- *     GET: { data: Post };
- *     PUT: { data: Post; body: UpdatePostBody };
- *     DELETE: { data: void };
- *   };
- * }>;
- *
- * const api = createClient<ApiSchema>({ baseUrl: "/api" });
- * ```
- */
-type SpooshSchema<T extends ApiSchema> = T;
 /**
  * Convert a route pattern like "posts/:id" to a path matcher pattern like `posts/${string}`.
  * This enables TypeScript to match actual paths like "posts/123" to their schema definitions.
@@ -1219,6 +1366,24 @@ 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;
+/**
+ * Extract paths that have methods with events (subscription endpoints).
+ */
+type SubscriptionPaths<TSchema> = {
+    [K in keyof TSchema & string]: {
+        [M in keyof TSchema[K]]: TSchema[K][M] extends {
+            events: unknown;
+        } ? K : never;
+    }[keyof TSchema[K]] extends never ? never : K;
+}[keyof TSchema & string];
+/**
+ * Check if a schema path has any method with events field.
+ */
+type HasSubscriptionMethod<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? {
+    [M in keyof TSchema[TKey]]: TSchema[TKey][M] extends {
+        events: unknown;
+    } ? true : never;
+}[keyof TSchema[TKey]] 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;
 /**
@@ -1560,6 +1725,79 @@ type QueueSelectorPathMethods<TSchema, TPath extends string, TDefaultError> = Fi
  * Used by useQueue for selecting endpoints. All input goes to trigger().
  */
 type QueueSelectorClient<TSchema, TDefaultError = unknown> = <TPath extends SchemaPaths<TSchema> | (string & {})>(path: TPath) => QueueSelectorPathMethods<TSchema, TPath, TDefaultError>;
+/**
+ * Extract events type from a method config.
+ */
+type ExtractEvents<T> = T extends {
+    events: infer E;
+} ? E : never;
+/**
+ * Transport-specific options for subscriptions.
+ */
+type SubscriptionTransportOptions = {
+    /** Keep connection alive when browser tab is hidden. Defaults to true. */
+    openWhenHidden?: boolean;
+};
+/**
+ * Strict subscription request options (for GET method).
+ * Body/query are required if schema requires them.
+ * Note: Transport options (maxRetries, retryDelay, events, parse, accumulate)
+ * are now configured at the hook level (useSSE).
+ */
+type StrictSubscriptionRequestOptions<TMethodConfig, TUserPath extends string, TRequestedEvents extends readonly (keyof ExtractEvents<TMethodConfig>)[] = readonly (keyof ExtractEvents<TMethodConfig>)[]> = Simplify<BaseRequestOptions & QueryOption<TMethodConfig> & BodyOption<TMethodConfig> & ParamsOption<TUserPath> & SubscriptionTransportOptions>;
+/**
+ * Loose subscription request options (for POST/PUT/etc methods).
+ * Body/query are always optional since they're provided via trigger().
+ * Note: Transport options (maxRetries, retryDelay, events, parse, accumulate)
+ * are now configured at the hook level (useSSE).
+ */
+type LooseSubscriptionRequestOptions<TMethodConfig, TUserPath extends string, TRequestedEvents extends readonly (keyof ExtractEvents<TMethodConfig>)[] = readonly (keyof ExtractEvents<TMethodConfig>)[]> = Simplify<BaseRequestOptions & {
+    query?: ExtractQuery<TMethodConfig>;
+} & {
+    body?: ExtractBody<TMethodConfig> | SpooshBody<ExtractBody<TMethodConfig>>;
+} & ParamsOption<TUserPath> & SubscriptionTransportOptions>;
+/**
+ * Check if strict subscription options are required (for GET method).
+ */
+type IsStrictSubscriptionOptionsRequired<TMethodConfig, TUserPath extends string> = IsBodyRequired<TMethodConfig> extends true ? true : IsQueryRequired<TMethodConfig> extends true ? true : HasParams<TUserPath> extends true ? true : false;
+/**
+ * Subscription response type that carries event types.
+ */
+type SubscriptionResponse<TMethodConfig, TRequestedEvents extends readonly (keyof ExtractEvents<TMethodConfig>)[] = readonly (keyof ExtractEvents<TMethodConfig>)[]> = {
+    _subscription: true;
+    events: ExtractEvents<TMethodConfig>;
+    requestedEvents: TRequestedEvents;
+    query: ExtractQuery<TMethodConfig>;
+    body: ExtractBody<TMethodConfig>;
+    error: ExtractError<TMethodConfig>;
+};
+type BaseSubscriptionResponse<TEvents extends Record<string, unknown> = Record<string, unknown>, TError = unknown> = {
+    _subscription: true;
+    events: TEvents;
+    requestedEvents: readonly string[];
+    query: unknown;
+    body: unknown;
+    error: TError;
+};
+/**
+ * Subscription method function type - methods with events field.
+ * GET: Strict typing (body/query required if schema requires)
+ * POST/PUT/etc: Loose typing (body/query always optional, passed to trigger)
+ */
+type SubscriptionMethodFn<TMethodConfig, TUserPath extends string, TMethod extends string> = TMethod extends "GET" ? IsStrictSubscriptionOptionsRequired<TMethodConfig, TUserPath> extends true ? <TRequestedEvents extends readonly (keyof ExtractEvents<TMethodConfig>)[]>(options: StrictSubscriptionRequestOptions<TMethodConfig, TUserPath, TRequestedEvents>) => SubscriptionResponse<TMethodConfig, TRequestedEvents> : <TRequestedEvents extends readonly (keyof ExtractEvents<TMethodConfig>)[]>(options?: StrictSubscriptionRequestOptions<TMethodConfig, TUserPath, TRequestedEvents>) => SubscriptionResponse<TMethodConfig, TRequestedEvents> : <TRequestedEvents extends readonly (keyof ExtractEvents<TMethodConfig>)[]>(options?: LooseSubscriptionRequestOptions<TMethodConfig, TUserPath, TRequestedEvents>) => SubscriptionResponse<TMethodConfig, TRequestedEvents>;
+/**
+ * Subscription path methods - only methods with events field.
+ */
+type SubscriptionPathMethods<TSchema, TPath extends string> = FindMatchingKey<TSchema, TPath> extends infer TKey ? TKey extends keyof TSchema ? Simplify<{
+    [M in HttpMethod as M extends keyof TSchema[TKey] ? TSchema[TKey][M] extends {
+        events: unknown;
+    } ? M : never : never]: M extends keyof TSchema[TKey] ? SubscriptionMethodFn<TSchema[TKey][M], TPath, M> : never;
+}> : never : never;
+/**
+ * A subscription API interface that only exposes methods with events field.
+ * Used by useSubscription hook for real-time data streams.
+ */
+type SubscriptionClient<TSchema, TDefaultError = unknown> = <TPath extends SubscriptionPaths<TSchema> | (string & {})>(path: TPath) => HasSubscriptionMethod<TSchema, TPath> extends true ? SubscriptionPathMethods<TSchema, TPath> : never;
 
 type PluginArray = readonly SpooshPlugin<PluginTypeConfig>[];
 interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
@@ -1567,11 +1805,12 @@ interface SpooshConfig<TPlugins extends PluginArray = PluginArray> {
     defaultOptions?: SpooshOptions;
     plugins?: TPlugins;
 }
-type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends PluginArray = PluginArray> = {
+type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends PluginArray = PluginArray, TTransports extends string = never> = {
     api: SpooshClient<TSchema, TDefaultError>;
     stateManager: StateManager;
     eventEmitter: EventEmitter;
     pluginExecutor: PluginExecutor;
+    transports: Map<string, SpooshTransport>;
     config: {
         baseUrl: string;
         defaultOptions: SpooshOptions;
@@ -1580,6 +1819,7 @@ type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends
         schema: TSchema;
         defaultError: TDefaultError;
         plugins: TPlugins;
+        transports: TTransports;
     };
 };
 
@@ -1638,10 +1878,11 @@ type ExtractTriggerParams<I> = I extends {
  *
  * @since 0.1.0
  */
-declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends PluginArray = []> {
+declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends PluginArray = [], TTransports extends string = never> {
     private baseUrl;
     private defaultOptions;
     private _plugins;
+    private _transports;
     /**
      * Creates a new Spoosh instance.
      *
@@ -1666,7 +1907,7 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
      * });
      * ```
      */
-    constructor(baseUrl: string, defaultOptions?: SpooshOptionsInput, plugins?: TPlugins);
+    constructor(baseUrl: string, defaultOptions?: SpooshOptionsInput, plugins?: TPlugins, transports?: Map<string, SpooshTransport>);
     /**
      * Adds plugins to the Spoosh instance.
      *
@@ -1685,7 +1926,23 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
      * ]);
      * ```
      */
-    use<const TNewPlugins extends PluginArray>(plugins: TNewPlugins): Omit<Spoosh<TSchema, TError, TNewPlugins>, "use">;
+    use<const TNewPlugins extends PluginArray>(plugins: TNewPlugins): Omit<Spoosh<TSchema, TError, TNewPlugins, TTransports>, "use">;
+    /**
+     * Registers transport implementations for real-time operations.
+     *
+     * @param transports - Array of transport instances to register
+     * @returns This Spoosh instance for method chaining
+     *
+     * @example
+     * ```ts
+     * import { sse } from '@spoosh/transport-sse';
+     *
+     * const spoosh = new Spoosh<Schema, Error>('/api')
+     *   .withTransports([sse()])
+     *   .use([...]);
+     * ```
+     */
+    withTransports<const T extends SpooshTransport[]>(transports: T): Spoosh<TSchema, TError, TPlugins, TTransports | T[number]["name"]>;
     /**
      * Cached instance of the underlying SpooshInstance.
      * Created lazily on first property access.
@@ -1796,7 +2053,18 @@ declare class Spoosh<TSchema = unknown, TError = unknown, TPlugins extends Plugi
         schema: TSchema;
         defaultError: TError;
         plugins: TPlugins;
+        transports: TTransports;
     };
+    /**
+     * Map of registered transport implementations.
+     *
+     * @example
+     * ```ts
+     * const { transports } = client;
+     * const sseTransport = transports.get('sse');
+     * ```
+     */
+    get transports(): Map<string, SpooshTransport<unknown, unknown>>;
 }
 
 /**
@@ -2075,6 +2343,8 @@ declare module "./types" {
 }
 declare const xhrTransport: Transport<XhrTransportOptions>;
 
+declare function composeAdapter(baseAdapter: SubscriptionAdapter, plugins: readonly SpooshPlugin[]): SubscriptionAdapter;
+
 declare function executeFetch<TData, TError>(baseUrl: string, path: string[], method: HttpMethod, defaultOptions: SpooshOptions, requestOptions?: AnyRequestOptions, nextTags?: boolean): Promise<SpooshResponse<TData, TError>>;
 
 type ExecuteOptions = {
@@ -2282,7 +2552,7 @@ interface QueueControllerContext {
     api: unknown;
     stateManager: StateManager;
     eventEmitter: EventEmitter;
-    pluginExecutor: InstancePluginExecutor;
+    pluginExecutor: ApiPluginExecutor;
 }
 declare function createQueueController<TData, TError, TMeta = Record<string, unknown>>(config: QueueControllerConfig, context: QueueControllerContext): QueueController<TData, TError, TMeta>;
 
@@ -2303,4 +2573,36 @@ declare class Semaphore {
     getWaitingCount(): number;
 }
 
-export { type AnyRequestOptions, type ApiSchema, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type DataAwareCallback, type DataAwareTransform, type DataChangeCallback, type DevtoolEvents, type EventEmitter, type EventListener, type EventOptions, type EventTracer, type ExecuteOptions, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type ExtractTriggerBody, type ExtractTriggerParams, type ExtractTriggerQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasWriteMethod, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteNextContext, type InfinitePage, type InfinitePageStatus, type InfinitePrevContext, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InfiniteTriggerOptions, type InstanceApiContext, type InstanceApiResolvers, type InstancePluginExecutor, type LifecyclePhase, type MergePluginInstanceApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type OperationController, type OperationState, type OperationType, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextBase, type PluginContextExtensions, type PluginContextInput, type PluginExecutor, type PluginExportsRegistry, type PluginFactory, type PluginHandler, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QueueController, type QueueControllerConfig, type QueueControllerContext, type QueueItem, type QueueItemStatus, type QueueSelectorClient, type QueueStats, type QueueTriggerInput, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestCompleteEvent, type RequestOptions$1 as RequestOptions, type RequestTracer, type ResolveInstanceApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Semaphore, type SetupContext, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type StandaloneEvent, type StateManager, type StripPrefix, type Subscriber, type TagMode, type TagOptions, type Trace, type TraceColor, type TraceEvent, type TraceInfo, type TraceListener, type TraceOptions, type TraceStage, type Transport, type TransportOption, type TransportOptionsMap, type TransportResponse, type TypedPluginContext, type TypedPluginDefinition, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, type WriteSelectorClient, __DEV__, buildUrl, clone, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createQueueController, createSelectorProxy, createSpooshPlugin, createStateManager, createTracer, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, removeHeaderKeys, resolveHeadersToRecord, resolvePath, resolvePathString, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };
+interface SubscriptionController<TData = unknown, TError = unknown> {
+    subscribe(): Promise<SubscriptionHandle<TData, TError>>;
+    subscribe(callback: () => void): () => void;
+    emit(message: unknown): Promise<{
+        success: boolean;
+        error?: TError;
+    }>;
+    unsubscribe(): void;
+    getState(): {
+        data: TData | undefined;
+        error: TError | undefined;
+        isConnected: boolean;
+    };
+    mount(): void;
+    unmount(): void;
+    setDisconnected(): void;
+}
+
+interface CreateSubscriptionControllerOptions<TData, TError> {
+    channel: string;
+    baseAdapter: SubscriptionAdapter<TData, TError>;
+    stateManager: StateManager;
+    eventEmitter: EventEmitter;
+    pluginExecutor: PluginExecutor;
+    queryKey: string;
+    operationType: OperationType;
+    path: string;
+    method: string;
+    instanceId?: string;
+}
+declare function createSubscriptionController<TData, TError>(options: CreateSubscriptionControllerOptions<TData, TError>): SubscriptionController<TData, TError>;
+
+export { type AnyMethod, type AnyRequestOptions, type ApiContext, type ApiPluginExecutor, type ApiResolvers, type ApiSchema, type BaseSubscriptionResponse, type BuiltInEvents, type CacheEntry, type CacheEntryWithKey, type CapturedCall, type ComputeRequestOptions, type CoreRequestOptionsBase, type CreateInfiniteReadOptions, type CreateOperationOptions, type CreateSubscriptionControllerOptions, type DataAwareCallback, type DataAwareTransform, type DataChangeCallback, type DevtoolEvents, type EventEmitter, type EventListener, type EventOptions, type EventTracer, type ExecuteOptions, type ExtractBody$1 as ExtractBody, type ExtractData, type ExtractError, type ExtractMethodOptions, type ExtractParamNames, type ExtractQuery$1 as ExtractQuery, type ExtractTriggerBody, type ExtractTriggerParams, type ExtractTriggerQuery, type FetchDirection, type FetchExecutor, type FindMatchingKey, HTTP_METHODS, type HasParams, type HasReadMethod, type HasSubscriptionMethod, type HasWriteMethod, type HeadersInitOrGetter, type HttpMethod, type HttpMethodKey, type InfiniteNextContext, type InfinitePage, type InfinitePageStatus, type InfinitePrevContext, type InfiniteReadController, type InfiniteReadState, type InfiniteRequestOptions, type InfiniteTriggerOptions, type LifecyclePhase, type MergePluginApi, type MergePluginOptions, type MergePluginResults, type MethodOptionsMap, type OperationController, type OperationState, type OperationType, type PluginAccessor, type PluginArray, type PluginContext, type PluginContextBase, type PluginContextExtensions, type PluginContextInput, type PluginExecutor, type PluginFactory, type PluginHandler, type PluginInternalRegistry, type PluginLifecycle, type PluginMiddleware, type PluginRegistry, type PluginRequestOptions, type PluginResolvers, type PluginResponseHandler, type PluginResultResolvers, type PluginTypeConfig, type PluginUpdateHandler, type QueueController, type QueueControllerConfig, type QueueControllerContext, type QueueItem, type QueueItemStatus, type QueueSelectorClient, type QueueStats, type QueueTriggerInput, type ReadClient, type ReadPaths, type ReadSchemaHelper, type RefetchEvent, type RequestCompleteEvent, type RequestOptions$1 as RequestOptions, type RequestTracer, type ResolveApi, type ResolveResultTypes, type ResolveSchemaTypes, type ResolveTypes, type ResolverContext, type SchemaPaths, type SelectedEndpoint, type SelectorFunction, type SelectorResult, Semaphore, type SetupContext, type Simplify, Spoosh, type SpooshBody, type SpooshClient, type SpooshConfig, type SpooshInstance, type SpooshOptions, type SpooshOptionsInput, type SpooshPlugin, type SpooshResponse, type SpooshSchema, type SpooshSubscriptionMethodRegistry, type SpooshTransport, type SpooshTransportRegistry, type StandaloneEvent, type StateManager, type StripPrefix, type Subscriber, type SubscriptionAccumulateEvent, type SubscriptionAdapter, type SubscriptionClient, type SubscriptionConnectEvent, type SubscriptionConnectedEvent, type SubscriptionContext, type SubscriptionController, type SubscriptionDisconnectEvent, type SubscriptionErrorEvent, type SubscriptionHandle, type SubscriptionMessageEvent, type SubscriptionMethod, type SubscriptionPaths, type TagMode, type TagOptions, type Trace, type TraceColor, type TraceEvent, type TraceInfo, type TraceListener, type TraceOptions, type TraceStage, type Transport, type TransportName, type TransportOption, type TransportOptionsMap, type TransportResponse, type TypedPluginContext, type TypedPluginDefinition, type WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, type WriteSelectorClient, __DEV__, buildUrl, clone, composeAdapter, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createQueueController, createSelectorProxy, createSpooshPlugin, createStateManager, createSubscriptionController, createTracer, executeFetch, extractMethodFromSelector, extractPathFromSelector, fetchTransport, form, generateSelfTagFromKey, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, removeHeaderKeys, resolveHeadersToRecord, resolvePath, resolvePathString, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };