@spoosh/core 0.15.0 → 0.16.0

package/dist/index.d.mts

@@ -412,6 +412,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 +464,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 +488,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;
@@ -604,9 +690,12 @@ type PluginTypeConfig = {
     writeTriggerOptions?: object;
     queueOptions?: object;
     queueTriggerOptions?: object;
+    subscribeOptions?: object;
+    subscribeTriggerOptions?: object;
     readResult?: object;
     writeResult?: object;
     queueResult?: object;
+    subscribeResult?: object;
     instanceApi?: object;
 };
 /**
@@ -702,6 +791,22 @@ interface SpooshPlugin<T extends PluginTypeConfig = PluginTypeConfig> {
     instanceApi?: (context: InstanceApiContext) => T extends {
         instanceApi: 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
@@ -937,6 +1042,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;
     /**
@@ -1044,6 +1151,9 @@ 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;
@@ -1053,31 +1163,42 @@ type ExtractWriteResult<T> = T extends SpooshPlugin<infer Types> ? Types extends
 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 UnionToIntersection$1<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]>>;
-    pages: UnionToIntersection<ExtractPagesOptions<TPlugins[number]>>;
-    writeTrigger: UnionToIntersection<ExtractWriteTriggerOptions<TPlugins[number]>>;
-    queue: UnionToIntersection<ExtractQueueOptions<TPlugins[number]>>;
-    queueTrigger: UnionToIntersection<ExtractQueueTriggerOptions<TPlugins[number]>>;
+    read: UnionToIntersection$1<ExtractReadOptions<TPlugins[number]>>;
+    write: UnionToIntersection$1<ExtractWriteOptions<TPlugins[number]>>;
+    pages: UnionToIntersection$1<ExtractPagesOptions<TPlugins[number]>>;
+    writeTrigger: UnionToIntersection$1<ExtractWriteTriggerOptions<TPlugins[number]>>;
+    queue: UnionToIntersection$1<ExtractQueueOptions<TPlugins[number]>>;
+    queueTrigger: UnionToIntersection$1<ExtractQueueTriggerOptions<TPlugins[number]>>;
 };
 type MergePluginResults<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
-    read: UnionToIntersection<ExtractReadResult<TPlugins[number]>>;
-    write: UnionToIntersection<ExtractWriteResult<TPlugins[number]>>;
-    queue: UnionToIntersection<ExtractQueueResult<TPlugins[number]>>;
+    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<ExtractInstanceApi<TPlugins[number]>>, TSchema, MergePluginOptions<TPlugins>["read"]>;
+type MergePluginInstanceApi<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TSchema = unknown> = ResolveInstanceApi<UnionToIntersection$1<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>;
 
+/**
+ * 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 +1211,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 +1298,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 +1365,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;
 /**
@@ -1311,12 +1475,103 @@ type WritePathMethods$1<TSchema, TPath extends string> = FindMatchingKey<TSchema
  */
 type WriteSchemaHelper<TSchema> = <TPath extends WritePaths<TSchema> | (string & {})>(path: TPath) => HasWriteMethod<TSchema, TPath> extends true ? WritePathMethods$1<TSchema, TPath> : never;
 
+/**
+ * Check for exact type equality using function type assignability.
+ * Two types are equal if functions returning them are mutually assignable.
+ */
+type Equals<X, Y> = (<T>() => T extends X ? 1 : 2) extends <T>() => T extends Y ? 1 : 2 ? true : false;
+/**
+ * Convert bare `object` type to `never` to exclude it from the union.
+ * Preserves all other types including interfaces and types with actual properties.
+ */
+type FilterObjectType<T> = Equals<T, object> extends true ? never : T;
+/**
+ * Convert a union type to an intersection type.
+ * This merges all properties from all types in the union.
+ */
+type UnionToIntersection<U> = (U extends unknown ? (arg: U) => void : never) extends (arg: infer I) => void ? I : never;
+/**
+ * Extract all option types from plugin configuration and create a union, then intersect.
+ * This allows middleware to access all properties from all option types.
+ * object types are converted to unknown which doesn't affect the intersection.
+ */
+type ExtractPluginOptionsUnion<T extends PluginTypeConfig> = UnionToIntersection<FilterObjectType<T extends {
+    readOptions: infer R;
+} ? R : never> | FilterObjectType<T extends {
+    writeOptions: infer W;
+} ? W : never> | FilterObjectType<T extends {
+    writeTriggerOptions: infer WT;
+} ? WT : never> | FilterObjectType<T extends {
+    queueTriggerOptions: infer QT;
+} ? QT : never> | FilterObjectType<T extends {
+    pagesOptions: infer P;
+} ? P : never> | FilterObjectType<T extends {
+    queueOptions: infer Q;
+} ? Q : never>>;
+/**
+ * Plugin context with typed pluginOptions based on plugin configuration.
+ */
+type TypedPluginContext<T extends PluginTypeConfig> = Omit<PluginContext, "pluginOptions"> & {
+    pluginOptions?: ExtractPluginOptionsUnion<T>;
+};
+/**
+ * Plugin definition with typed context for middleware and handlers.
+ */
+type TypedPluginDefinition<T extends PluginTypeConfig> = Omit<SpooshPlugin<T>, "middleware" | "afterResponse" | "lifecycle"> & {
+    middleware?: (context: TypedPluginContext<T>, next: () => Promise<any>) => Promise<any>;
+    afterResponse?: (context: TypedPluginContext<T>, response: any) => any;
+    lifecycle?: {
+        onMount?: (context: TypedPluginContext<T>) => void | Promise<void>;
+        onUpdate?: (context: TypedPluginContext<T>, previousContext: TypedPluginContext<T>) => void | Promise<void>;
+        onUnmount?: (context: TypedPluginContext<T>) => void | Promise<void>;
+    };
+};
+/**
+ * Helper to create a Spoosh plugin with automatic type inference for plugin options.
+ *
+ * This eliminates the need for manual type assertions in middleware by automatically
+ * intersecting all option types, making all properties accessible:
+ *
+ * ```ts
+ * // Before:
+ * const pluginOptions = context.pluginOptions as CacheReadOptions | undefined;
+ * const staleTime = pluginOptions?.staleTime ?? defaultStaleTime;
+ *
+ * // After (with createSpooshPlugin):
+ * const staleTime = context.pluginOptions?.staleTime ?? defaultStaleTime;
+ * ```
+ *
+ * @typeParam T - Plugin type configuration (readOptions, writeOptions, etc.)
+ * @param definition - Plugin definition with typed context
+ * @returns Typed Spoosh plugin
+ *
+ * @example
+ * ```ts
+ * export const cachePlugin = (config: CachePluginConfig = {}) =>
+ *   createSpooshPlugin<{
+ *     readOptions: CacheReadOptions;
+ *     writeOptions: CacheWriteOptions;
+ *     pagesOptions: CachePagesOptions;
+ *   }>({
+ *     name: "spoosh:cache",
+ *     operations: ["read", "write", "pages"],
+ *     middleware: async (context, next) => {
+ *       // context.pluginOptions is automatically typed as an intersection:
+ *       // CacheReadOptions & CachePagesOptions (CacheWriteOptions filtered as it's just 'object')
+ *       // All properties from all option types are accessible:
+ *       const staleTime = context.pluginOptions?.staleTime ?? defaultStaleTime;
+ *       return next();
+ *     },
+ *   });
+ * ```
+ */
+declare function createSpooshPlugin<T extends PluginTypeConfig>(definition: TypedPluginDefinition<T>): SpooshPlugin<T>;
+
 /**
  * Base request options available on all methods.
  */
 type BaseRequestOptions = {
     headers?: HeadersInitOrGetter;
-    cache?: RequestCache;
     signal?: AbortSignal;
 };
 /**
@@ -1469,6 +1724,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> {
@@ -1476,11 +1804,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;
@@ -1489,6 +1818,7 @@ type SpooshInstance<TSchema = unknown, TDefaultError = unknown, TPlugins extends
         schema: TSchema;
         defaultError: TDefaultError;
         plugins: TPlugins;
+        transports: TTransports;
     };
 };
 
@@ -1547,10 +1877,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.
      *
@@ -1575,7 +1906,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.
      *
@@ -1594,7 +1925,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.
@@ -1705,7 +2052,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>>;
 }
 
 /**
@@ -1984,6 +2342,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 = {
@@ -2212,4 +2572,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 WriteClient, type WriteMethod, type WritePaths, type WriteSchemaHelper, type WriteSelectorClient, __DEV__, buildUrl, clone, containsFile, createClient, createEventEmitter, createInfiniteReadController, createInitialState, createOperationController, createPluginExecutor, createPluginRegistry, createProxyHandler, createQueueController, createSelectorProxy, 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 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 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 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, generateTags, getContentType, isAbortError, isJsonBody, isNetworkError, isSpooshBody, json, mergeHeaders, objectToFormData, objectToUrlEncoded, removeHeaderKeys, resolveHeadersToRecord, resolvePath, resolvePathString, resolveRequestBody, resolveTags, setHeaders, sortObjectKeys, urlencoded, xhrTransport };