@spoosh/react 0.12.0 → 0.13.1-beta.0

package/README.md

@@ -1,6 +1,6 @@
 # @spoosh/react
 
-React hooks for Spoosh - `useRead`, `useWrite`, and `usePages`.
+React hooks for Spoosh - `useRead`, `useWrite`, `usePages`, and `useSSE`.
 
 **[Documentation](https://spoosh.dev/docs/react)** · **Requirements:** TypeScript >= 5.0, React >= 18.0
 
@@ -158,6 +158,61 @@ function PostList() {
 }
 ```
 
+### useSSE
+
+Subscribe to real-time data streams using Server-Sent Events (SSE).
+
+```typescript
+import { sse } from "@spoosh/transport-sse";
+
+// Setup with SSE transport
+const spoosh = new Spoosh<ApiSchema, Error>("/api").withTransports([sse()]);
+export const { useSSE } = create(spoosh);
+
+// Basic subscription
+function Notifications() {
+  const { data, isConnected, loading } = useSSE(
+    (api) => api("notifications").GET({ query: { userId: "user-123" } })
+  );
+
+  if (loading) return <div>Connecting...</div>;
+
+  return (
+    <div>
+      <span>{isConnected ? "Connected" : "Disconnected"}</span>
+      {data?.message && <p>{data.message.text}</p>}
+    </div>
+  );
+}
+
+// Subscribe to specific events only
+const { data } = useSSE(
+  (api) => api("notifications").GET({
+    query: { userId: "user-123" },
+  }),
+  { events: ["alert"] }  // Only alert events
+);
+
+// AI streaming with accumulation
+const { data, trigger } = useSSE(
+  (api) => api("chat").POST(),
+  {
+    events: ["chunk", "done"],
+    parse: "json-done",
+    accumulate: {
+      chunk: (prev, curr) => ({
+        ...curr,
+        chunk: (prev?.chunk || "") + curr.chunk,
+      }),
+    },
+    enabled: false,
+  }
+);
+
+// Start streaming on demand
+await trigger({ body: { message: "Hello" } });
+```
+
 ## API Reference
 
 ### useRead(readFn, options?)
@@ -247,3 +302,33 @@ type InfinitePage<TData> = {
 | `trigger`      | `(options?) => Promise<void>` | Trigger fetch with optional new request options |
 | `abort`        | `() => void`                  | Abort current request                           |
 | `error`        | `TError \| undefined`         | Error if request failed                         |
+
+### useSSE(subFn, options?)
+
+| Option       | Type               | Default     | Description                       |
+| ------------ | ------------------ | ----------- | --------------------------------- |
+| `enabled`    | `boolean`          | `true`      | Whether to connect automatically  |
+| `events`     | `string[]`         | all events  | Subscribe to specific events only |
+| `parse`      | `ParseConfig`      | `"auto"`    | How to parse raw event data       |
+| `accumulate` | `AccumulateConfig` | `"replace"` | How to combine events over time   |
+
+**Returns:**
+
+| Property      | Type                    | Description                    |
+| ------------- | ----------------------- | ------------------------------ |
+| `data`        | `TEvents \| undefined`  | Accumulated event data         |
+| `error`       | `TError \| undefined`   | Error if connection failed     |
+| `loading`     | `boolean`               | True during initial connection |
+| `isConnected` | `boolean`               | True when connected to stream  |
+| `trigger`     | `(options?) => Promise` | Reconnect with new options     |
+| `disconnect`  | `() => void`            | Disconnect from stream         |
+| `reset`       | `() => void`            | Reset accumulated data         |
+
+**Connection Options:**
+
+| Option        | Type                 | Description                                 |
+| ------------- | -------------------- | ------------------------------------------- |
+| `headers`     | `HeadersInit`        | Request headers                             |
+| `credentials` | `RequestCredentials` | Credentials mode                            |
+| `maxRetries`  | `number`             | Max retry attempts (default: 3)             |
+| `retryDelay`  | `number`             | Delay between retries in ms (default: 1000) |

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { ReadClient, TagMode, SpooshResponse, ExtractTriggerQuery as ExtractTriggerQuery$2, ExtractTriggerBody as ExtractTriggerBody$2, ExtractTriggerParams as ExtractTriggerParams$2, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, QueueSelectorClient, QueueItem, QueueStats, InfiniteRequestOptions, InfiniteNextContext, InfinitePage, InfinitePrevContext, StateManager, EventEmitter, PluginExecutor, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
+import { ReadClient, TagMode, SpooshResponse, ExtractTriggerQuery as ExtractTriggerQuery$3, ExtractTriggerBody as ExtractTriggerBody$3, ExtractTriggerParams as ExtractTriggerParams$3, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, QueueSelectorClient, QueueItem, QueueStats, InfiniteRequestOptions, InfiniteNextContext, InfinitePage, InfinitePrevContext, SubscriptionClient, SubscriptionAdapter, OperationType, StateManager, EventEmitter, PluginExecutor, SpooshTransport, PluginArray, ResolveTypes, MergePluginOptions, ResolverContext, ResolveResultTypes, MergePluginInstanceApi, SpooshOptions } from '@spoosh/core';
 
 type SuccessResponse<T> = Extract<T, {
     data: unknown;
@@ -43,6 +43,31 @@ type ExtractResponseParamNames<T> = SuccessReturnType<T> extends {
         params: Record<infer K, unknown>;
     };
 } ? K extends string ? K : never : never;
+type SubscriptionReturnType<T> = T extends (...args: never[]) => infer R ? R : never;
+type ExtractSubscriptionEvents<T> = SubscriptionReturnType<T> extends {
+    events: infer E;
+    requestedEvents: infer RequestedEvents;
+} ? RequestedEvents extends readonly (keyof E)[] ? E extends Record<string, unknown> ? {
+    [K in RequestedEvents[number]]: E[K] extends {
+        data: infer EventData;
+    } ? EventData : unknown;
+} : unknown : unknown : unknown;
+type ExtractSubscriptionQuery<T> = SubscriptionReturnType<T> extends {
+    query: infer Q;
+} ? Q : never;
+type ExtractSubscriptionBody<T> = SubscriptionReturnType<T> extends {
+    body: infer B;
+} ? B : never;
+type ExtractAllSubscriptionEventKeys<T> = SubscriptionReturnType<T> extends {
+    events: infer E;
+} ? E extends Record<string, unknown> ? keyof E : never : never;
+type ExtractAllSubscriptionEvents<T> = SubscriptionReturnType<T> extends {
+    events: infer E;
+} ? E extends Record<string, unknown> ? {
+    [K in keyof E]: E[K] extends {
+        data: infer EventData;
+    } ? EventData : unknown;
+} : unknown : unknown;
 
 type TagModeInArray$1 = "all" | "self";
 /**
@@ -87,7 +112,7 @@ type ExtractInputFromResponse$3<T> = T extends {
 } ? I : never;
 type TriggerOptions<T> = ExtractInputFromResponse$3<TriggerAwaitedReturn$3<T>> extends infer I ? [I] extends [never] ? {
     force?: boolean;
-} : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & {
+} : ExtractTriggerQuery$3<I> & ExtractTriggerBody$3<I> & ExtractTriggerParams$3<I> & {
     /** Force refetch even if data is cached */
     force?: boolean;
 } : {
@@ -149,26 +174,26 @@ type TriggerAwaitedReturn$2<T> = T extends (...args: any[]) => infer R ? Awaited
 type ExtractInputFromResponse$2<T> = T extends {
     input: infer I;
 } ? I : never;
-type ExtractTriggerQuery$1<I> = I extends {
+type ExtractTriggerQuery$2<I> = I extends {
     query: infer Q;
 } ? undefined extends Q ? {
     query?: Exclude<Q, undefined>;
 } : {
     query: Q;
 } : unknown;
-type ExtractTriggerBody$1<I> = I extends {
+type ExtractTriggerBody$2<I> = I extends {
     body: infer B;
 } ? undefined extends B ? {
     body?: Exclude<B, undefined> | SpooshBody<Exclude<B, undefined>>;
 } : {
     body: B | SpooshBody<B>;
 } : unknown;
-type ExtractTriggerParams$1<I> = I extends {
+type ExtractTriggerParams$2<I> = I extends {
     params: infer P;
 } ? {
     params: P;
 } : unknown;
-type WriteTriggerInput<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> : object;
+type WriteTriggerInput<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [never] ? object : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> : object;
 /**
  * Result returned by `useWrite` hook.
  *
@@ -198,21 +223,21 @@ type TriggerAwaitedReturn$1<T> = T extends (...args: any[]) => infer R ? Awaited
 type ExtractInputFromResponse$1<T> = T extends {
     input: infer I;
 } ? I : never;
-type ExtractTriggerQuery<I> = I extends {
+type ExtractTriggerQuery$1<I> = I extends {
     query: infer Q;
 } ? undefined extends Q ? {
     query?: Exclude<Q, undefined>;
 } : {
     query: Q;
 } : unknown;
-type ExtractTriggerBody<I> = I extends {
+type ExtractTriggerBody$1<I> = I extends {
     body: infer B;
 } ? undefined extends B ? {
     body?: Exclude<B, undefined> | SpooshBody<Exclude<B, undefined>>;
 } : {
     body: B | SpooshBody<B>;
 } : unknown;
-type ExtractTriggerParams<I> = I extends {
+type ExtractTriggerParams$1<I> = I extends {
     params: infer P;
 } ? {
     params: P;
@@ -221,7 +246,7 @@ type QueueTriggerBase = {
     /** Custom ID for this queue item. If not provided, one will be auto-generated. */
     id?: string;
 };
-type QueueTriggerInput<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? QueueTriggerBase : QueueTriggerBase & ExtractTriggerQuery<I> & ExtractTriggerBody<I> & ExtractTriggerParams<I> : QueueTriggerBase;
+type QueueTriggerInput<T> = ExtractInputFromResponse$1<TriggerAwaitedReturn$1<T>> extends infer I ? [I] extends [never] ? QueueTriggerBase : QueueTriggerBase & ExtractTriggerQuery$1<I> & ExtractTriggerBody$1<I> & ExtractTriggerParams$1<I> : QueueTriggerBase;
 /**
  * Options for useQueue hook.
  */
@@ -270,7 +295,7 @@ type BaseTriggerOptions = {
     /** Bypass cache and force refetch. Default: true */
     force?: boolean;
 };
-type PagesTriggerOptions<TReadFn> = ExtractInputFromResponse<TriggerAwaitedReturn<TReadFn>> extends infer I ? [I] extends [never] ? BaseTriggerOptions : ExtractTriggerQuery$2<I> & ExtractTriggerBody$2<I> & ExtractTriggerParams$2<I> & BaseTriggerOptions : BaseTriggerOptions;
+type PagesTriggerOptions<TReadFn> = ExtractInputFromResponse<TriggerAwaitedReturn<TReadFn>> extends infer I ? [I] extends [never] ? BaseTriggerOptions : ExtractTriggerQuery$3<I> & ExtractTriggerBody$3<I> & ExtractTriggerParams$3<I> & BaseTriggerOptions : BaseTriggerOptions;
 /**
  * Options for `usePages` hook.
  *
@@ -377,7 +402,107 @@ type BasePagesResult<TData, TError, TItem, TPluginResult = Record<string, unknow
 type UsePagesResult<TData, TError, TItem, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[], TTriggerOptions = object> = BasePagesResult<TData, TError, TItem, MergePluginResults<TPlugins>["read"], TTriggerOptions>;
 type PagesApiClient<TSchema, TDefaultError> = ReadClient<TSchema, TDefaultError>;
 
-type InferError<T, TDefaultError> = [T] extends [unknown] ? TDefaultError : T;
+interface BaseSubscriptionOptions {
+    enabled?: boolean;
+    /** Subscription adapter instance created by the transport-specific hook */
+    adapter: SubscriptionAdapter;
+    /** Operation type for the subscription (e.g., "sse", "websocket") */
+    operationType: OperationType;
+}
+type ExtractTriggerQuery<TQuery> = [TQuery] extends [never] ? unknown : undefined extends TQuery ? {
+    query?: Exclude<TQuery, undefined>;
+} : {
+    query: TQuery;
+};
+type ExtractTriggerBody<TBody> = [TBody] extends [never] ? unknown : undefined extends TBody ? {
+    body?: Exclude<TBody, undefined> | SpooshBody<Exclude<TBody, undefined>>;
+} : {
+    body: TBody | SpooshBody<TBody>;
+};
+type ExtractTriggerParams<TParams> = [TParams] extends [never] ? unknown : {
+    params: TParams;
+};
+type SubscriptionTriggerInput<TQuery, TBody, TParams> = [
+    TQuery,
+    TBody,
+    TParams
+] extends [never, never, never] ? object : ExtractTriggerQuery<TQuery> & ExtractTriggerBody<TBody> & ExtractTriggerParams<TParams>;
+interface BaseSubscriptionResult<TData, TError, TPluginResult, TTriggerOptions> {
+    data: TData | undefined;
+    error: TError | undefined;
+    isConnected: boolean;
+    loading: boolean;
+    meta: TPluginResult;
+    /** @internal Query key for devtool integration */
+    _queryKey: string;
+    /** @internal Subscription version for tracking resubscriptions */
+    _subscriptionVersion: number;
+    trigger: (options?: TTriggerOptions) => Promise<void>;
+    disconnect: () => void;
+}
+type SubscriptionApiClient<TSchema, TDefaultError = unknown> = SubscriptionClient<TSchema, TDefaultError>;
+
+type ParseStrategy = "auto" | "json" | "text" | "json-done";
+type AccumulateStrategy = "replace" | "merge";
+type AccumulatorFn<T = unknown> = (previous: T | undefined, current: T) => T;
+type AccumulateFieldConfig<T> = T extends Record<string, unknown> ? {
+    [K in keyof T]?: AccumulateStrategy;
+} : Record<string, AccumulateStrategy>;
+interface UseSSEOptionsBase {
+    /** Whether the subscription is enabled. Defaults to true. */
+    enabled?: boolean;
+    /** Max retry attempts on connection failure */
+    maxRetries?: number;
+    /** Delay between retries in ms */
+    retryDelay?: number;
+}
+type ParseFn = (data: string) => unknown;
+type TypedParseConfig<TEventKeys extends string> = ParseStrategy | ParseFn | Partial<Record<TEventKeys, ParseStrategy | ParseFn>>;
+type TypedAccumulateConfig<TEvents extends Record<string, unknown>> = AccumulateStrategy | {
+    [K in keyof TEvents]?: AccumulateStrategy | AccumulatorFn<TEvents[K]> | AccumulateFieldConfig<TEvents[K]>;
+};
+interface TypedUseSSEOptions<TEventKeys extends string, TEvents extends Record<string, unknown>, TSelectedEvents extends readonly TEventKeys[] = readonly TEventKeys[]> extends UseSSEOptionsBase {
+    /** Event types to listen for. If not provided, listens to all events. */
+    events?: TSelectedEvents;
+    /** Parse strategy for SSE event data. Defaults to 'auto'. */
+    parse?: TypedParseConfig<TEventKeys>;
+    /** Accumulate strategy for combining events. Defaults to 'replace'. */
+    accumulate?: TypedAccumulateConfig<TEvents>;
+}
+interface UseSSEOptions extends UseSSEOptionsBase {
+    /** Event types to listen for. If not provided, listens to all events. */
+    events?: string[];
+    /** Parse strategy for SSE event data. Defaults to 'auto'. */
+    parse?: ParseStrategy | Record<string, ParseStrategy>;
+    /** Accumulate strategy for combining events. Defaults to 'replace'. */
+    accumulate?: AccumulateStrategy | Record<string, AccumulateStrategy | AccumulatorFn>;
+}
+interface UseSSEResult<TEvents, TError> {
+    /** Accumulated data keyed by event type */
+    data: Partial<TEvents> | undefined;
+    /** Connection or parse error */
+    error: TError | undefined;
+    /** Whether currently connected to the SSE endpoint */
+    isConnected: boolean;
+    /** Whether connection is in progress */
+    loading: boolean;
+    /** Plugin metadata */
+    meta: Record<string, never>;
+    /**
+     * Manually trigger connection with optional body/query overrides
+     * @param options - Optional body and query parameters
+     */
+    trigger: (options?: {
+        body?: unknown;
+        query?: unknown;
+    }) => Promise<void>;
+    /** Disconnect from the SSE endpoint */
+    disconnect: () => void;
+    /** Reset accumulated data */
+    reset: () => void;
+}
+
+type InferError<T, TDefaultError> = unknown extends T ? TDefaultError : T;
 type WriteResolverContext<TSchema, TMethod, TDefaultError> = ResolverContext<TSchema, ExtractMethodData<TMethod>, InferError<ExtractMethodError<TMethod>, TDefaultError>, ExtractMethodQuery<TMethod>, ExtractMethodBody<TMethod>, ExtractResponseParamNames<TMethod> extends never ? never : Record<ExtractResponseParamNames<TMethod>, string | number>>;
 type ResolvedWriteOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["write"], WriteResolverContext<TSchema, TMethod, TDefaultError>>;
 type ResolvedWriteTriggerOptions<TSchema, TPlugins extends PluginArray, TMethod, TDefaultError> = ResolveTypes<MergePluginOptions<TPlugins>["writeTrigger"], WriteResolverContext<TSchema, TMethod, TDefaultError>>;
@@ -395,14 +520,29 @@ type UseQueueFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     <TQueueFn extends (api: QueueApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>>(queueFn: TQueueFn, queueOptions?: ResolvedQueueOptions<TSchema, TPlugins, TQueueFn, TDefaultError> & UseQueueOptions): UseQueueResult<ExtractMethodData<TQueueFn>, InferError<ExtractMethodError<TQueueFn>, TDefaultError>, QueueTriggerInput<TQueueFn> & ResolvedQueueTriggerOptions<TSchema, TPlugins, TQueueFn, TDefaultError>, ResolveResultTypes<MergePluginResults<TPlugins>["queue"], ResolvedQueueOptions<TSchema, TPlugins, TQueueFn, TDefaultError> & UseQueueOptions>>;
 };
 type UsePagesFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TReadFn extends (api: PagesApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<unknown, unknown>>, TRequest extends InfiniteRequestOptions = InfiniteRequestOptions, TItem = unknown>(readFn: TReadFn, readOptions: BasePagesOptions<ExtractMethodData<TReadFn>, TItem, InferError<ExtractMethodError<TReadFn>, TDefaultError>, TRequest, MergePluginResults<TPlugins>["read"]> & ResolveTypes<MergePluginOptions<TPlugins>["pages"], ResolverContext<TSchema, ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>>>) => BasePagesResult<ExtractMethodData<TReadFn>, InferError<ExtractMethodError<TReadFn>, TDefaultError>, TItem, MergePluginResults<TPlugins>["read"], PagesTriggerOptions<TReadFn>>;
+type UseSubscriptionFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TSubFn extends (api: SubscriptionApiClient<TSchema, TDefaultError>) => unknown>(subFn: TSubFn, subOptions?: BaseSubscriptionOptions) => BaseSubscriptionResult<ExtractSubscriptionEvents<TSubFn>, InferError<ExtractMethodError<TSubFn>, TDefaultError>, MergePluginResults<TPlugins>["subscribe"], SubscriptionTriggerInput<ExtractSubscriptionQuery<TSubFn>, ExtractSubscriptionBody<TSubFn>, never>>;
+type InferSSEEvents<T> = ExtractAllSubscriptionEvents<T> extends Record<string, unknown> ? ExtractAllSubscriptionEvents<T> : Record<string, unknown>;
+type FilteredEvents<TAllEvents extends Record<string, unknown>, TSelectedEvents extends readonly string[]> = TSelectedEvents[number] extends keyof TAllEvents ? Pick<TAllEvents, TSelectedEvents[number]> : TAllEvents;
+type UseSSEFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
+    <TSubFn extends (api: SubscriptionApiClient<TSchema, TDefaultError>) => {
+        _subscription: true;
+        events: Record<string, {
+            data: unknown;
+        }>;
+    }, const TSelectedEvents extends readonly Extract<ExtractAllSubscriptionEventKeys<TSubFn>, string>[]>(subFn: TSubFn, sseOptions: TypedUseSSEOptions<Extract<ExtractAllSubscriptionEventKeys<TSubFn>, string>, InferSSEEvents<TSubFn>, TSelectedEvents> & {
+        events: TSelectedEvents;
+    }): UseSSEResult<FilteredEvents<InferSSEEvents<TSubFn>, TSelectedEvents>, InferError<ExtractMethodError<TSubFn>, TDefaultError>>;
+    <TSubFn extends (api: SubscriptionApiClient<TSchema, TDefaultError>) => {
+        _subscription: true;
+        events: Record<string, {
+            data: unknown;
+        }>;
+    }>(subFn: TSubFn, sseOptions?: Omit<TypedUseSSEOptions<Extract<ExtractAllSubscriptionEventKeys<TSubFn>, string>, InferSSEEvents<TSubFn>>, "events">): UseSSEResult<InferSSEEvents<TSubFn>, InferError<ExtractMethodError<TSubFn>, TDefaultError>>;
+};
 /**
- * Spoosh React hooks interface containing useRead, useWrite, and usePages.
- *
- * @template TDefaultError - The default error type
- * @template TSchema - The API schema type
- * @template TPlugins - The plugins array type
+ * Base hooks that are always available.
  */
-type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
+type BaseSpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
     /**
      * React hook for fetching data from an API endpoint with automatic caching and revalidation.
      *
@@ -478,11 +618,62 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      * ```
      */
     useQueue: UseQueueFn<TDefaultError, TSchema, TPlugins>;
+    /**
+     * React hook for subscribing to real-time data streams (SSE, WebSocket, etc.).
+     *
+     * @param subFn - Function that selects the subscription endpoint
+     * @param subOptions - Optional configuration including `enabled`, `tags`
+     * @returns Object containing `data`, `error`, `loading`, `isSubscribed`, `emit`, `unsubscribe`
+     *
+     * @example
+     * ```tsx
+     * const { data } = useSubscription((api) =>
+     *   api("notifications").GET({ events: ["alert", "message"] })
+     * );
+     * ```
+     */
+    useSubscription: UseSubscriptionFn<TDefaultError, TSchema, TPlugins>;
 } & MergePluginInstanceApi<TPlugins, TSchema>;
+/**
+ * SSE hooks available when SSE transport is registered.
+ */
+type SSEHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
+    /**
+     * React hook for SSE streams with per-hook parsing and accumulation.
+     *
+     * @param subFn - Function that selects the SSE endpoint
+     * @param sseOptions - Configuration including `events`, `parse`, `accumulate`, `maxRetries`, `retryDelay`
+     * @returns Object containing `data`, `error`, `loading`, `isConnected`, `trigger`, `disconnect`, `reset`
+     *
+     * @example
+     * ```tsx
+     * const { data, reset } = useSSE(
+     *   (api) => api("chat").POST(),
+     *   {
+     *     events: ["chunk", "done"],
+     *     parse: "json-done",
+     *     accumulate: { chunk: "merge" },
+     *     maxRetries: 5,
+     *   }
+     * );
+     * ```
+     */
+    useSSE: UseSSEFn<TDefaultError, TSchema, TPlugins>;
+};
+/**
+ * Spoosh React hooks interface containing useRead, useWrite, and usePages.
+ * useSSE is only available when SSE transport is registered via withTransports([sse()]).
+ *
+ * @template TDefaultError - The default error type
+ * @template TSchema - The API schema type
+ * @template TPlugins - The plugins array type
+ * @template TTransports - The registered transport names
+ */
+type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray, TTransports extends string = never> = BaseSpooshReactHooks<TDefaultError, TSchema, TPlugins> & ([TTransports] extends [never] ? object : "sse" extends TTransports ? SSEHooks<TDefaultError, TSchema, TPlugins> : object);
 /**
  * Shape of a Spoosh instance required for creating React hooks.
  */
-type SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins> = {
+type SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins, TTransports extends string = never> = {
     /** The API instance */
     api: TApi;
     /** State manager for caching and state */
@@ -491,11 +682,22 @@ type SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins> = {
     eventEmitter: EventEmitter;
     /** Plugin executor for running plugins */
     pluginExecutor: PluginExecutor;
+    /** Registered transports for subscriptions */
+    transports: Map<string, SpooshTransport>;
+    /** Config with baseUrl and default options */
+    config: {
+        baseUrl: string;
+        defaultOptions: {
+            headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+            [key: string]: unknown;
+        };
+    };
     /** Type information (not used at runtime) */
     _types: {
         schema: TSchema;
         defaultError: TDefaultError;
         plugins: TPlugins;
+        transports: TTransports;
     };
 };
 
@@ -519,7 +721,7 @@ type SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins> = {
  * }
  * ```
  */
-declare function create<TSchema, TDefaultError, TPlugins extends PluginArray, TApi>(instance: SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins>): SpooshReactHooks<TDefaultError, TSchema, TPlugins>;
+declare function create<TSchema, TDefaultError, TPlugins extends PluginArray, TApi, TTransports extends string = never>(instance: SpooshInstanceShape<TApi, TSchema, TDefaultError, TPlugins, TTransports>): SpooshReactHooks<TDefaultError, TSchema, TPlugins, TTransports>;
 
 type PluginHooksConfig<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = {
     baseUrl: string;
@@ -527,4 +729,4 @@ type PluginHooksConfig<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[
     plugins: TPlugins;
 };
 
-export { type BasePagesOptions, type BasePagesResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type ExtractCoreMethodOptions, type ExtractMethodBody, type ExtractMethodData, type ExtractMethodError, type ExtractMethodOptions, type ExtractMethodQuery, type ExtractResponseBody, type ExtractResponseParamNames, type ExtractResponseQuery, type ExtractResponseRequestOptions, type PagesApiClient, type PagesTriggerOptions, type PluginHooksConfig, type QueueApiClient, type QueueTriggerInput, type ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UsePagesResult, type UseQueueOptions, type UseQueueResult, type UseReadResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };
+export { type BasePagesOptions, type BasePagesResult, type BaseReadOptions, type BaseReadResult, type BaseWriteResult, type ExtractCoreMethodOptions, type ExtractMethodBody, type ExtractMethodData, type ExtractMethodError, type ExtractMethodOptions, type ExtractMethodQuery, type ExtractResponseBody, type ExtractResponseParamNames, type ExtractResponseQuery, type ExtractResponseRequestOptions, type PagesApiClient, type PagesTriggerOptions, type PluginHooksConfig, type QueueApiClient, type QueueTriggerInput, type ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type TypedAccumulateConfig, type TypedParseConfig, type TypedUseSSEOptions, type UsePagesResult, type UseQueueOptions, type UseQueueResult, type UseReadResult, type UseSSEOptions, type UseSSEResult, type UseWriteResult, type WriteApiClient, type WriteResponseInputFields, create };