@spoosh/react 0.11.0 → 0.13.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ReadClient, TagMode, SpooshResponse, SpooshPlugin, PluginTypeConfig, MergePluginResults, WriteSelectorClient, SpooshBody, QueueSelectorClient, QueueItem, QueueStats, 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";
 /**
@@ -81,28 +106,13 @@ type ResponseInputFields<TQuery, TBody, TParamNames extends string> = [
 ] extends [never, never, never] ? object : {
     input: ReadInputFields<TQuery, TBody, TParamNames>;
 };
-type TriggerAwaitedReturn$2<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$2<T> = T extends {
+type TriggerAwaitedReturn$3<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse$3<T> = T extends {
     input: infer I;
 } ? I : never;
-type ExtractTriggerQuery$2<I> = I extends {
-    query: infer Q;
-} ? {
-    query?: Q;
-} : unknown;
-type ExtractTriggerBody$2<I> = I extends {
-    body: infer B;
-} ? {
-    body?: B;
-} : unknown;
-type ExtractTriggerParams$2<I> = I extends {
-    params: infer P;
-} ? {
-    params?: P;
-} : unknown;
-type TriggerOptions<T> = ExtractInputFromResponse$2<TriggerAwaitedReturn$2<T>> extends infer I ? [I] extends [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;
 } : {
@@ -160,30 +170,30 @@ type InputFields<TQuery, TBody, TParamNames extends string> = OptionalQueryField
 type WriteResponseInputFields<TQuery, TBody, TParamNames extends string> = [TQuery, TBody, TParamNames] extends [never, never, never] ? object : {
     input: InputFields<TQuery, TBody, TParamNames> | undefined;
 };
-type TriggerAwaitedReturn$1<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse$1<T> = T extends {
+type TriggerAwaitedReturn$2<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+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$1<TriggerAwaitedReturn$1<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.
  *
@@ -209,25 +219,25 @@ type BaseWriteResult<TData, TError, TOptions, TMeta = Record<string, unknown>> =
 type UseWriteResult<TData, TError, TOptions, TMeta, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseWriteResult<TData, TError, TOptions, TMeta> & MergePluginResults<TPlugins>["write"];
 type WriteApiClient<TSchema, TDefaultError> = WriteSelectorClient<TSchema, TDefaultError>;
 
-type TriggerAwaitedReturn<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
-type ExtractInputFromResponse<T> = T extends {
+type TriggerAwaitedReturn$1<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+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;
@@ -236,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<TriggerAwaitedReturn<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.
  */
@@ -277,41 +287,25 @@ type UseQueueResult<TData, TError, TTriggerInput, TMeta = object> = {
 type QueueApiClient<TSchema, TDefaultError> = QueueSelectorClient<TSchema, TDefaultError>;
 
 type TagModeInArray = "all" | "self";
-type AnyInfiniteRequestOptions = {
-    query?: Record<string, unknown>;
-    params?: Record<string, string | number>;
-    body?: unknown;
-};
-/**
- * Context passed to `canFetchNext` and `nextPageRequest` callbacks.
- */
-type InfiniteNextContext<TData, TRequest> = {
-    /** The latest fetched response data */
-    response: TData | undefined;
-    /** All responses fetched so far */
-    allResponses: TData[];
-    /** The current request options (query, params, body) */
-    request: TRequest;
-};
-/**
- * Context passed to `canFetchPrev` and `prevPageRequest` callbacks.
- */
-type InfinitePrevContext<TData, TRequest> = {
-    /** The latest fetched response data */
-    response: TData | undefined;
-    /** All responses fetched so far */
-    allResponses: TData[];
-    /** The current request options (query, params, body) */
-    request: TRequest;
+type TriggerAwaitedReturn<T> = T extends (...args: never[]) => infer R ? Awaited<R> : never;
+type ExtractInputFromResponse<T> = T extends {
+    input: infer I;
+} ? I : never;
+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$3<I> & ExtractTriggerBody$3<I> & ExtractTriggerParams$3<I> & BaseTriggerOptions : BaseTriggerOptions;
 /**
- * Options for `useInfiniteRead` hook.
+ * Options for `usePages` hook.
  *
  * @template TData - The response data type for each page
  * @template TItem - The item type after merging all responses
+ * @template TError - The error type
  * @template TRequest - The request options type (query, params, body)
+ * @template TMeta - Plugin metadata type
  */
-type BaseInfiniteReadOptions<TData, TItem, TRequest = AnyInfiniteRequestOptions> = {
+type BasePagesOptions<TData, TItem, TError = unknown, TRequest = InfiniteRequestOptions, TMeta = Record<string, unknown>> = {
     /** Whether to fetch automatically on mount. Default: true */
     enabled?: boolean;
     /**
@@ -322,30 +316,66 @@ type BaseInfiniteReadOptions<TData, TItem, TRequest = AnyInfiniteRequestOptions>
      *   - 'none' should only be used as string (use `tags: 'none'` not in array)
      */
     tags?: TagMode | (TagModeInArray | (string & {}))[];
-    /** Callback to determine if there's a next page to fetch */
-    canFetchNext: (ctx: InfiniteNextContext<TData, TRequest>) => boolean;
-    /** Callback to build the request options for the next page */
-    nextPageRequest: (ctx: InfiniteNextContext<TData, TRequest>) => Partial<TRequest>;
-    /** Callback to merge all responses into a single array of items */
-    merger: (allResponses: TData[]) => TItem[];
-    /** Callback to determine if there's a previous page to fetch */
-    canFetchPrev?: (ctx: InfinitePrevContext<TData, TRequest>) => boolean;
-    /** Callback to build the request options for the previous page */
-    prevPageRequest?: (ctx: InfinitePrevContext<TData, TRequest>) => Partial<TRequest>;
+    /**
+     * Callback to determine if there's a next page to fetch.
+     * Receives the last page to check for pagination indicators.
+     * Default: `() => false` (no next page fetching)
+     *
+     * @example
+     * ```ts
+     * canFetchNext: ({ lastPage }) => lastPage?.data?.nextCursor != null
+     * ```
+     */
+    canFetchNext?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => boolean;
+    /**
+     * Callback to build the request options for the next page.
+     * Return only the fields that change - they will be **merged** with the initial request.
+     * Default: `() => ({})` (no changes to request)
+     *
+     * @example
+     * ```ts
+     * // Initial: { query: { cursor: 0, limit: 10 } }
+     * // Only return cursor - limit is preserved automatically
+     * nextPageRequest: ({ lastPage }) => ({
+     *   query: { cursor: lastPage?.data?.nextCursor }
+     * })
+     * ```
+     */
+    nextPageRequest?: (ctx: InfiniteNextContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
+    /**
+     * Callback to merge all pages into a single array of items.
+     *
+     * @example
+     * ```ts
+     * merger: (pages) => pages.flatMap(p => p.data?.items ?? [])
+     * ```
+     */
+    merger: (pages: InfinitePage<TData, TError, TMeta>[]) => TItem[];
+    /**
+     * Callback to determine if there's a previous page to fetch.
+     * Receives the first page to check for pagination indicators.
+     */
+    canFetchPrev?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => boolean;
+    /**
+     * Callback to build the request options for the previous page.
+     * Return only the fields that change - they will be **merged** with the initial request.
+     */
+    prevPageRequest?: (ctx: InfinitePrevContext<TData, TError, TRequest, TMeta>) => Partial<TRequest>;
 };
 /**
- * Result returned by `useInfiniteRead` hook.
+ * Result returned by `usePages` hook.
  *
  * @template TData - The response data type for each page
  * @template TError - The error type
  * @template TItem - The item type after merging all responses
  * @template TPluginResult - Plugin-provided result fields
+ * @template TTriggerOptions - Options that can be passed to trigger()
  */
-type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string, unknown>> = {
-    /** Merged items from all fetched responses */
+type BasePagesResult<TData, TError, TItem, TPluginResult = Record<string, unknown>, TTriggerOptions = object> = {
+    /** Merged items from all fetched pages */
     data: TItem[] | undefined;
-    /** Array of all raw response data */
-    allResponses: TData[] | undefined;
+    /** Array of all pages with status, data, error, and meta per page */
+    pages: InfinitePage<TData, TError, TPluginResult>[];
     /** True during the initial load (no data yet) */
     loading: boolean;
     /** True during any fetch operation */
@@ -358,23 +388,121 @@ type BaseInfiniteReadResult<TData, TError, TItem, TPluginResult = Record<string,
     canFetchNext: boolean;
     /** Whether there's a previous page available to fetch */
     canFetchPrev: boolean;
-    /** Plugin-provided metadata */
-    meta: TPluginResult;
     /** Fetch the next page */
     fetchNext: () => Promise<void>;
     /** Fetch the previous page */
     fetchPrev: () => Promise<void>;
-    /** Trigger refetch of all pages from the beginning */
-    trigger: () => Promise<void>;
+    /** Trigger refetch of all pages from the beginning, optionally with new request options */
+    trigger: (options?: TTriggerOptions) => Promise<void>;
     /** Abort the current fetch operation */
     abort: () => void;
     /** Error from the last failed request */
     error: TError | undefined;
 };
-type UseInfiniteReadResult<TData, TError, TItem, TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[]> = BaseInfiniteReadResult<TData, TError, TItem> & MergePluginResults<TPlugins>["read"];
-type InfiniteReadApiClient<TSchema, TDefaultError> = ReadClient<TSchema, TDefaultError>;
+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>>;
@@ -391,23 +519,30 @@ type UseWriteFn<TDefaultError, TSchema, TPlugins extends PluginArray> = {
 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 InfiniteReadResolverContext<TSchema, TData, TError, TRequest> = ResolverContext<TSchema, TData, TError, TRequest extends {
-    query: infer Q;
-} ? Q : never, TRequest extends {
-    body: infer B;
-} ? B : never, TRequest extends {
-    params: infer P;
-} ? P : never>;
-type ResolvedInfiniteReadOptions<TSchema, TPlugins extends PluginArray, TData, TError, TRequest> = ResolveTypes<MergePluginOptions<TPlugins>["infiniteRead"], InfiniteReadResolverContext<TSchema, TData, TError, TRequest>>;
-type UseInfiniteReadFn<TDefaultError, TSchema, TPlugins extends PluginArray> = <TData, TItem, TError = TDefaultError, TRequest extends AnyInfiniteRequestOptions = AnyInfiniteRequestOptions>(readFn: (api: InfiniteReadApiClient<TSchema, TDefaultError>) => Promise<SpooshResponse<TData, TError>>, readOptions: BaseInfiniteReadOptions<TData, TItem, TRequest> & ResolvedInfiniteReadOptions<TSchema, TPlugins, TData, TError, TRequest>) => BaseInfiniteReadResult<TData, TError, TItem, MergePluginResults<TPlugins>["read"]>;
+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 useInfiniteRead.
- *
- * @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.
      *
@@ -448,21 +583,21 @@ type SpooshReactHooks<TDefaultError, TSchema, TPlugins extends PluginArray> = {
      *
      * @param readFn - Function that selects the API endpoint to call
      * @param readOptions - Configuration including `canFetchNext`, `nextPageRequest`, `merger`, and optional `canFetchPrev`/`prevPageRequest`
-     * @returns Object containing `data`, `allResponses`, `fetchNext`, `fetchPrev`, `canFetchNext`, `canFetchPrev`, `loading`, `fetching`, and pagination states
+     * @returns Object containing `data`, `pages`, `fetchNext`, `fetchPrev`, `canFetchNext`, `canFetchPrev`, `loading`, `fetching`, and pagination states
      *
      * @example
      * ```tsx
-     * const { data, fetchNext, canFetchNext, loading } = useInfiniteRead(
+     * const { data, fetchNext, canFetchNext, loading } = usePages(
      *   (api) => api("posts").GET(),
      *   {
-     *     canFetchNext: ({ response }) => !!response?.nextCursor,
-     *     nextPageRequest: ({ response }) => ({ query: { cursor: response?.nextCursor } }),
-     *     merger: (responses) => responses.flatMap(r => r.items)
+     *     canFetchNext: ({ lastPage }) => !!lastPage?.data?.nextCursor,
+     *     nextPageRequest: ({ lastPage }) => ({ query: { cursor: lastPage?.data?.nextCursor } }),
+     *     merger: (pages) => pages.flatMap(p => p.data?.items ?? [])
      *   }
      * );
      * ```
      */
-    useInfiniteRead: UseInfiniteReadFn<TDefaultError, TSchema, TPlugins>;
+    usePages: UsePagesFn<TDefaultError, TSchema, TPlugins>;
     /**
      * React hook for queued operations with concurrency control.
      *
@@ -483,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 */
@@ -496,27 +682,38 @@ 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;
     };
 };
 
 /**
- * Creates React hooks (useRead, useWrite, useInfiniteRead) from a Spoosh instance.
+ * Creates React hooks (useRead, useWrite, usePages) from a Spoosh instance.
  *
  * @template TSchema - The API schema type
  * @template TDefaultError - The default error type
  * @template TPlugins - The plugins array type
  * @template TApi - The API type
  * @param instance - The Spoosh instance containing api, stateManager, eventEmitter, and pluginExecutor
- * @returns An object containing useRead, useWrite, useInfiniteRead hooks and plugin instance APIs
+ * @returns An object containing useRead, useWrite, usePages hooks and plugin instance APIs
  *
  * @example
  * ```ts
- * const { useRead, useWrite, useInfiniteRead } = create(spooshInstance);
+ * const { useRead, useWrite, usePages } = create(spooshInstance);
  *
  * function MyComponent() {
  *   const { data, loading } = useRead((api) => api("posts").GET());
@@ -524,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;
@@ -532,4 +729,4 @@ type PluginHooksConfig<TPlugins extends readonly SpooshPlugin<PluginTypeConfig>[
     plugins: TPlugins;
 };
 
-export { type AnyInfiniteRequestOptions, type BaseInfiniteReadOptions, type BaseInfiniteReadResult, 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 InfiniteNextContext, type InfinitePrevContext, type InfiniteReadApiClient, type PluginHooksConfig, type QueueApiClient, type QueueTriggerInput, type ReadApiClient, type ResponseInputFields, type SpooshReactHooks, type TriggerOptions, type UseInfiniteReadResult, 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 };