@lunora/react 0.0.0 → 1.0.0-alpha.10

package/dist/index.d.mts

@@ -0,0 +1,556 @@
+import { ReactNode, ReactElement } from 'react';
+import { LunoraClient, OptimisticUpdate, User, ConnectionStatus, ReturnOf, ArgsOf, FunctionReference, MutatorHandle, Preloaded } from '@lunora/client';
+export type { ArgsOf, FunctionReference, LunoraClient, MutatorHandle, MutatorTransaction, OptimisticLocalStore, OptimisticUpdate, Preloaded, ReturnOf, User } from '@lunora/client';
+import { QueryClient } from '@tanstack/react-query';
+export { type L as LunoraQueryOptions, l as lunoraQueryOptions } from "./packem_shared/query-options.d-D4okOpO8.mjs";
+import { PaginationStatus } from '@lunora/client/pagination';
+export type { PaginationResult, PaginationStatus } from '@lunora/client/pagination';
+import { RateLimitStatus, RateLimitConfig } from '@lunora/ratelimit';
+interface AuthGateProps {
+  children: ReactNode;
+}
+/** Renders `children` only once a token is set on the client (after hydration). */
+declare const Authenticated: ({
+  children
+}: AuthGateProps) => ReactNode;
+/** Renders `children` only when auth has settled and no token is set. */
+declare const Unauthenticated: ({
+  children
+}: AuthGateProps) => ReactNode;
+/** Renders `children` while auth is still settling (before hydration completes). */
+declare const AuthLoading: ({
+  children
+}: AuthGateProps) => ReactNode;
+/**
+* Resolved auth-gate state. `isLoading` covers the window before the client has
+* hydrated — the server render and the first hydration render both report
+* loading, so the markup agrees and no signed-out UI flashes in.
+*/
+interface AuthState {
+  isAuthenticated: boolean;
+  isLoading: boolean;
+}
+/**
+* Three-state auth status for gating UI. Reports `isLoading` until the client
+* has hydrated, then `isAuthenticated` tracks whether a token is set on the
+* shared client.
+*
+* Lunora auth is token-based and resolves synchronously once the token is
+* known, so the loading window is hydration rather than a server round-trip —
+* use it (via {@link AuthState}) to render a fallback while it settles.
+*/
+declare const useAuthState: () => AuthState;
+interface LunoraProviderProps {
+  children: ReactNode;
+  client: LunoraClient;
+  /**
+  * Bring-your-own QueryClient. When omitted, the provider creates one with
+  * defaults tuned for Lunora's push-driven model: `staleTime: Infinity` (the
+  * WS subscription is the only invalidation signal), `retry: 0` (failures
+  * route through the offline queue on the client), and `gcTime: 5min` (keep
+  * results around for a short return-to-view window).
+  *
+  * If a parent `<QueryClientProvider>` is already mounted, the provider
+  * uses *that* client and does NOT install an inner one (so apps with their
+  * own setup don't double-wrap).
+  */
+  queryClient?: QueryClient;
+}
+/**
+* Provides both the {@link LunoraClient} and a TanStack `QueryClient` to the
+* tree. The detection logic for a parent QueryClientProvider keeps this safe to
+* drop into an app that already runs TanStack Query for its own purposes.
+*/
+declare const LunoraProvider: ({
+  children,
+  client,
+  queryClient
+}: LunoraProviderProps) => ReactElement;
+/**
+* Read the {@link LunoraClient} from the nearest `<LunoraProvider>`. Kept
+* colocated with the provider for back-compat.
+*/
+declare const useLunora: () => LunoraClient;
+/**
+* Client-safe mirror of `@lunora/payment`'s `Subscription`. Re-declared here
+* (rather than imported) so this React entry never pulls in the server-only
+* `@lunora/payment` module graph — the kit stays React + DOM only. Keep this in
+* sync with `packages/payment/src/types.ts`.
+*/
+interface Subscription {
+  readonly cancelAtPeriodEnd: boolean;
+  readonly createdAt: number;
+  readonly currentPeriodEnd?: number;
+  readonly id: string;
+  readonly priceId: string;
+  readonly provider: "polar" | "stripe";
+  readonly quantity: number;
+  readonly referenceId: string;
+  readonly state: "active" | "canceled" | "past_due" | "paused" | "trialing";
+  readonly updatedAt: number;
+}
+/** The `{ url }` shape every checkout/portal trigger resolves to. */
+interface RedirectTarget {
+  readonly url: string;
+}
+/** A thunk the app supplies that calls its own Lunora action and resolves a redirect URL. */
+type RedirectTrigger = () => Promise<RedirectTarget>;
+interface UseCheckoutResult {
+  /** Run the trigger and redirect the browser to the resolved URL. Resolves once the redirect is issued; rejects on failure. */
+  checkout: () => Promise<void>;
+  /** The most recent failure, or `undefined`. */
+  error: Error | undefined;
+  /** `true` while the trigger is in flight (before the redirect is issued). */
+  pending: boolean;
+}
+/**
+* Decoupled redirect-on-resolve primitive shared by `CheckoutButton` and
+* `CustomerPortalButton`. The app passes a `trigger` thunk that calls its own
+* Lunora action (the one wrapping `LunoraPayment.createCheckout` /
+* `createPortalSession`) and resolves `{ url }`; this hook awaits it, flips
+* `pending`, surfaces any `error`, and on success navigates via
+* `location.assign(url)`.
+*
+* Mirrors Convex's `CheckoutLink` / `CustomerPortalLink` flow (trigger an action
+* that returns a URL, then redirect) while staying agnostic of the app's
+* function names.
+*/
+declare const useCheckout: (trigger: RedirectTrigger) => UseCheckoutResult;
+/**
+* Presentational props shared by the redirect buttons. Kept to a curated set
+* (rather than spreading arbitrary button attributes) so the component stays
+* within the repo's `react/jsx-props-no-spreading` rule while covering the
+* common styling / accessibility hooks.
+*/
+interface RedirectButtonOwnProps {
+  /** Accessible label when the visible `children` are icon-only. */
+  "aria-label"?: string;
+  children?: ReactNode;
+  className?: string;
+  /** Force-disable the control regardless of pending state. */
+  disabled?: boolean;
+  /** Called with the failure when the trigger rejects. The error is also surfaced via `useCheckout`. */
+  onError?: (error: Error) => void;
+  title?: string;
+}
+interface CheckoutButtonProps extends RedirectButtonOwnProps {
+  /** Calls the app's checkout action and resolves the hosted-checkout `{ url }`. */
+  onCheckout: RedirectTrigger;
+}
+interface CustomerPortalButtonProps extends RedirectButtonOwnProps {
+  /** Calls the app's portal action and resolves the customer-portal `{ url }`. */
+  onPortal: RedirectTrigger;
+}
+/**
+* Button that starts a hosted checkout. On click it awaits `onCheckout` (a thunk
+* that calls the app's checkout action) and redirects to the returned URL,
+* disabling itself while the request is in flight.
+*/
+declare const CheckoutButton: ({
+  onCheckout,
+  ...rest
+}: CheckoutButtonProps) => ReactNode;
+/**
+* Button that opens the provider's customer portal. On click it awaits
+* `onPortal` (a thunk that calls the app's portal action) and redirects to the
+* returned URL, disabling itself while the request is in flight.
+*/
+declare const CustomerPortalButton: ({
+  onPortal,
+  ...rest
+}: CustomerPortalButtonProps) => ReactNode;
+interface UseQueryOptions {
+  shardKey?: string;
+}
+interface UseMutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unknown> {
+  optimistic?: (current: TCurrent | undefined) => TValue;
+  /**
+  * Convex-parity multi-query optimistic update forwarded to
+  * `client.mutation`. Patches many subscribed queries at once via an
+  * `OptimisticLocalStore`, rolled back atomically on failure.
+  */
+  optimisticUpdate?: OptimisticUpdate<TArgs>;
+  shardKey?: string;
+}
+interface UseSubscriptionResult<T> {
+  data: T | undefined;
+  error: Error | undefined;
+}
+interface UsePaginatedQueryOptions {
+  /** Page size for the first page (and the default for `loadMore`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface UsePaginatedQueryResult<T> {
+  /** `true` while the first page or a `loadMore` page is in flight. */
+  isLoading: boolean;
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  loadMore: (numberItems: number) => void;
+  /** Flattened items across every loaded page, in order. */
+  results: T[];
+  status: PaginationStatus;
+}
+interface UseInfiniteQueryOptions {
+  /** Page size for the first page (and the default for `fetchNextPage`). */
+  initialNumItems: number;
+  shardKey?: string;
+}
+interface UseInfiniteQueryResult<T> {
+  /** Request the next page. A no-op unless `status === "CanLoadMore"`. */
+  fetchNextPage: (numberItems?: number) => void;
+  /** `true` when the loaded tail reports it can load another page. */
+  hasNextPage: boolean;
+  /** `true` while a `fetchNextPage` page (beyond the first) is in flight. */
+  isFetchingNextPage: boolean;
+  /** `true` while the first page is in flight. */
+  isLoading: boolean;
+  /** One inner array per loaded page, in order; unresolved pages are omitted. */
+  pages: T[][];
+  status: PaginationStatus;
+}
+interface UseAuthResult {
+  setToken: (token: string | null) => void;
+  token: string | null;
+  user: User | null;
+}
+/**
+* Token + identity plumbing. The token lives on the shared `LunoraClient`;
+* `setToken(jwt)` after a sign-in makes subsequent RPC calls carry the
+* `Authorization` header. `user` is resolved from better-auth's `get-session`
+* endpoint via `client.getCurrentUser()` — fetched on mount and refetched
+* whenever the token changes (`onAuthTokenChange`), and `null` when signed out.
+*
+* Multiple `useAuth` instances stay in sync: both `token` and `user` are read
+* through `useSyncExternalStore` over the shared client (and a per-client
+* identity store), so a `setToken` from one component re-renders every mounted
+* hook with the freshly-resolved user.
+*/
+declare const useAuth: () => UseAuthResult;
+/**
+* Reactive view of the client's aggregate live-socket status across all shard
+* connections. Re-renders on every transition (`idle` → `connecting` →
+* `connected` → `offline`). Use it to drive a connection indicator so an
+* operator can tell a healthy live channel from a silently-dropped socket.
+*/
+declare const useConnectionStatus: () => ConnectionStatus;
+/** A targeting context merged on top of the app's default (`defineFlags({ identify })`). */
+type FlagContext = Record<string, unknown>;
+/** The value kinds a flag resolves to — OpenFeature's boolean / number / string / structured (JSON) flags. */
+type FlagValue = boolean | number | string | {
+  [key: string]: unknown;
+} | unknown[] | null;
+/**
+* Subscribe to a single feature flag, live over Lunora's WebSocket.
+*
+* Returns `defaultValue` until the first evaluation lands, then the server's
+* resolved value — re-pushed whenever the provider re-evaluates (e.g. a flag is
+* toggled in Cloudflare Flagship). The flag's kind is inferred from
+* `defaultValue`'s runtime type, so `useFlag("dark", false)` reads a boolean and
+* `useFlag("hero", "control")` a string. `context` supplies a per-call targeting
+* context merged on top of the app's default `identify` targeting key.
+*
+* Evaluation runs through whatever OpenFeature provider the app wired in
+* `lunora/flags.ts`; the read never throws — a provider error resolves the
+* default (the same fail-open contract as server-side `ctx.flags`).
+*/
+declare const useFlag: <T extends FlagValue>(key: string, defaultValue: T, context?: FlagContext) => T;
+/**
+* Subscribe to several feature flags at once, live over Lunora's WebSocket.
+*
+* Pass a record of `key → defaultValue`; each flag's kind is inferred from its
+* default, and the result is the same-shaped record with resolved values (the
+* defaults until each evaluation lands). A single `context` applies to every
+* flag. This is the batched form of {@link useFlag} — one effect manages one
+* subscription per key, so it stays rules-of-hooks-safe even as the flag set
+* changes between renders.
+*/
+declare const useFlags: <T extends Record<string, FlagValue>>(flags: T, context?: FlagContext) => T;
+/** The args a paginated query exposes minus the framework-supplied page cursor. */
+type PaginatedArgs<F> = Omit<ArgsOf<F>, "paginationOpts">;
+/** The element type of the `page` array a paginated query returns. */
+type PageItemOf<F> = ReturnOf<F> extends {
+  page: (infer T)[];
+} ? T : unknown;
+/**
+* Subscribe to a reactively-paginated query and grow the feed page by page.
+*
+* The query function must accept a `paginationOpts: { numItems, cursor,
+* endCursor }` arg and return a `PaginationResult` (the shape
+* `ctx.db.query(...).paginate` yields). Pages are tracked as an ordered list of
+* stable boundary cursors: each loaded page is a live subscription over a
+* FIXED `(lower, upper]` range whose upper bound is the next page's lower bound.
+* Because boundaries are shared stable cursors, inserting or deleting a row in
+* the middle of the list grows/shrinks the affected page in place without
+* duplicating or skipping rows across page boundaries — the bug the legacy
+* "first N after the previous page's last row" model suffered under live edits.
+*
+* `loadMore` appends the next page off the open-ended tail's `continueCursor`;
+* it is a no-op unless `status === "CanLoadMore"`. Background split/join
+* maintenance keeps page sizes near `initialNumItems` as edits accumulate (see
+* `use-paginated-core.ts`).
+*
+* Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
+* feed to its first page. The public return shape (`results` / `status` /
+* `loadMore`) is unchanged from the legacy keyset implementation.
+*/
+declare const usePaginatedQuery: <F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: UsePaginatedQueryOptions) => UsePaginatedQueryResult<PageItemOf<F>>;
+/**
+* Subscribe to a reactively-paginated query and expose its pages discretely.
+*
+* Shares `usePaginatedQuery`'s reactive-pagination engine — pages are fixed
+* `(lower, upper]` cursor ranges with shared stable boundaries, so a row
+* inserted or deleted mid-list grows/shrinks the affected page without
+* duplicating or skipping rows across boundaries — but keeps each page as its
+* own inner array rather than flattening them, and adds the
+* TanStack-Query-style `fetchNextPage` / `hasNextPage` / `isFetchingNextPage`
+* shape. `fetchNextPage` appends the next page off the open-ended tail's
+* `continueCursor`; it is a no-op unless `status === "CanLoadMore"`.
+*
+* Changing `fn`, the base `args`, `initialNumItems`, or `shardKey` resets the
+* feed to its first page. The public return shape is unchanged from the legacy
+* keyset implementation.
+*/
+declare const useInfiniteQuery: <F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: UseInfiniteQueryOptions) => UseInfiniteQueryResult<PageItemOf<F>>;
+type CallOptions<F extends FunctionReference> = UseMutationCallOptions<unknown, unknown, ArgsOf<F>>;
+interface MutationHook<F extends FunctionReference> {
+  /** The latest invocation's resolved value, or `undefined` before the first success. */
+  data: ReturnOf<F> | undefined;
+  /** The latest invocation's error, or `null`. */
+  error: Error | null;
+  /** `true` when the latest invocation rejected. */
+  isError: boolean;
+  mutate: (args: ArgsOf<F>, options?: CallOptions<F>) => Promise<ReturnOf<F>>;
+  /** `true` while ANY invocation from this hook is in flight (ref-counted, so overlapping calls compose). */
+  pending: boolean;
+  /** Clear the latest `data`/`error` back to idle. */
+  reset: () => void;
+  /**
+  * Bind a Convex-parity multi-query optimistic update to this mutation.
+  * Returns a `{ mutate, pending, … }` whose `mutate` forwards `update` as the
+  * `optimisticUpdate` for every call — unless a per-call `optimisticUpdate`
+  * is supplied in the call options, which overrides the bound one.
+  */
+  withOptimisticUpdate: (update: OptimisticUpdate<ArgsOf<F>>) => MutationHook<F>;
+}
+/**
+* Returns `{ mutate, pending, data, error, reset, withOptimisticUpdate }` for the
+* given mutation reference. Prefer destructuring at the call site so the React
+* linter can track dependencies on each field independently.
+*
+* Built on TanStack Query's mutation cache (the same cache the query hooks use),
+* so it composes with Query Devtools and exposes the latest call's `data`/`error`
+* plus `reset()`. `mutate` maps to `mutateAsync`, so it stays an awaitable that
+* rejects on failure (rather than TanStack's fire-and-forget `mutate`).
+*
+* `pending` is ref-counted across overlapping invocations of THIS hook instance
+* (driven by the mutation's `onMutate`/`onSettled` lifecycle), so it flips back to
+* `false` only once every concurrent call has settled — and a sibling component
+* mutating the same function never affects it (TanStack's own `isPending` tracks
+* just the latest invocation).
+*
+* Optimistic updates stay client-owned: the `optimistic` / `optimisticUpdate`
+* call options pass straight through to `client.mutation`, which applies and
+* rolls them back against the Lunora subscription cache (Convex parity) — not
+* through TanStack's `onMutate`.
+*/
+declare const useMutation: <F extends FunctionReference>(function_: F) => MutationHook<F>;
+interface MutatorHook<TArgs> {
+  /** The latest invocation's error, or `undefined`. */
+  error: Error | undefined;
+  /** `true` when the latest invocation rejected. */
+  isError: boolean;
+  /** Run the mutator; resolves once the write is persisted, rejects on failure. */
+  mutate: (args: TArgs) => Promise<void>;
+  /** `true` while ANY invocation from this hook is in flight (ref-counted, so overlapping calls compose). */
+  pending: boolean;
+  /** Clear the latest `error` back to idle. */
+  reset: () => void;
+}
+/**
+* Ergonomic `{ mutate, pending, error, isError, reset }` wrapper over a bound
+* custom-mutator handle from `@lunora/db`'s `bindMutators`. The optimistic
+* overlay and server-authoritative push are owned by the bound handle (and
+* TanStack DB's optimistic-transaction layer rebases pending overlays on every
+* sync tick) — this hook only surfaces React state for the in-flight/error
+* lifecycle. Reads stay on the existing `useLiveQuery`; no new query hook is
+* needed.
+*
+* `pending` is ref-counted across overlapping invocations of THIS hook instance,
+* so it clears only once every concurrent call has settled.
+*/
+declare const useMutator: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>;
+/**
+* Hydrate a query from a {@link Preloaded} token produced by `preloadQuery`
+* during SSR, then keep it live.
+*
+* The first render returns the preloaded value (TanStack's `initialData`),
+* so the server markup and the initial client markup match — no hydration
+* mismatch, no loading flash. After mount, a WS subscription attaches so
+* later server pushes update the value just like `useQuery`.
+*
+* The {@link Preloaded} token's `value` seeds `initialData`; we don't need a
+* full dehydrate/hydrate dance because the consumer hands us the resolved
+* value directly. Apps that want to share a pre-populated QueryClient across
+* many preloaded queries can pass their own `queryClient` to `LunoraProvider`
+* and hydrate it themselves via TanStack's `hydrate(qc, dehydratedState)`.
+*/
+declare const usePreloadedQuery: <T>(preloaded: Preloaded<T>) => T;
+/**
+* The PLAN4 §1 framework-neutral name for the preloaded-hydration handoff:
+* `hydratePreloaded(preloaded)` seeds the SSR value on the first paint, then
+* attaches a live WS subscription on mount. It is a thin alias of
+* {@link usePreloadedQuery} so the React adapter exposes the same
+* `hydratePreloaded` primitive every other adapter (Solid, Svelte, Vue) will,
+* while existing callers of `usePreloadedQuery` keep working unchanged.
+*
+* It carries React's Rules-of-Hooks contract (it calls hooks internally), so
+* call it like a hook — at the top level of a component, unconditionally.
+*/
+declare const hydratePreloaded: <T>(preloaded: Preloaded<T>) => T;
+/**
+* `usePresence` — collaborative-awareness hook, the client half of the
+* `@lunora/server` `definePresence` preset (Convex `@convex-dev/presence`
+* parity).
+*
+* It drives the two presence functions the server component ships:
+*
+* - **heartbeat** (a mutation): called on mount, on a fixed interval, and again
+* whenever the tab becomes visible, to upsert the caller's presence row and
+* refresh its `lastSeen`. On unmount the interval is cleared. Each heartbeat
+* carries the latest `data` from a ref, so `setData` takes effect on the next
+* tick without re-subscribing or resetting the timer.
+* - **listPresent** (a query): subscribed to over the live-query WS, so the
+* present-list updates reactively. Because the server patches a single row per
+* heartbeat, the client's **per-row subscription delta merge** applies just that
+* row to the cached list instead of re-sending every member — the list stays
+* cheap even with many participants heart-beating.
+*
+* `sessionId` defaults to a stable per-mount id (one row per tab); pass your own
+* to dedupe across tabs by user. TTL/expiry is server-side: a member that stops
+* heart-beating drops out of `listPresent` once `lastSeen` ages past the TTL, so
+* the hook needs no client-side reaping.
+*
+* The two `FunctionReference`s come from your generated `api` (e.g.
+* `api.presence.heartbeat` / `api.presence.listPresent`) — passed in so the hook
+* stays decoupled from any specific app schema.
+*/
+/**
+* A heartbeat mutation reference: takes `{ roomId, sessionId, data? }` (the shape
+* `definePresence().functions.heartbeat` registers).
+*/
+type HeartbeatReference = FunctionReference<"mutation", {
+  data?: Record<string, unknown>;
+  roomId: string;
+  sessionId: string;
+}>;
+/**
+* A listPresent query reference: takes `{ roomId }` and returns the array of
+* present members.
+*/
+type ListPresentReference = FunctionReference<"query", {
+  roomId: string;
+}>;
+interface UsePresenceOptions<H extends HeartbeatReference, L extends ListPresentReference> {
+  /** Awareness blob for the first heartbeat (selection, cursor, name, color…). */
+  data?: Record<string, unknown>;
+  /** The `api.*` reference for the presence heartbeat mutation. */
+  heartbeat: H;
+  /** Heartbeat cadence in ms. Defaults to 10s — keep it well under the server TTL. */
+  intervalMs?: number;
+  /** The `api.*` reference for the presence listPresent query. */
+  listPresent: L;
+  /**
+  * Stable id for this presence row. Defaults to a fresh per-mount id (one row
+  * per tab). Pass a user/connection id to control deduping.
+  */
+  sessionId?: string;
+  /** Forwarded to the heartbeat mutation / listPresent subscription when sharding by room. */
+  shardKey?: string;
+}
+interface UsePresenceResult<L extends ListPresentReference> {
+  /** The present members for the room, as `listPresent` returns them. `undefined` until the first push. */
+  present: ReturnOf<L> | undefined;
+  /** This mount's session id (generated when not supplied). */
+  sessionId: string;
+  /** Replace the awareness `data` sent with subsequent heartbeats, and heartbeat once now. */
+  setData: (data: Record<string, unknown> | undefined) => void;
+}
+declare const usePresence: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: UsePresenceOptions<H, L>) => UsePresenceResult<L>;
+/**
+* Subscribe to a server query.
+*
+* Returns `undefined` until the first response lands. Pass `"skip"` for
+* `args` to short-circuit the query (no network call, no subscription).
+*
+* Internally this routes through TanStack Query: the queryKey is
+* `["lunora", fn.__lunoraRef, args, shardKey]` (TanStack hashes structurally
+* so an args object built in a different key order still dedupes). The
+* subscription registry shares a single WS subscription across every consumer
+* of the same queryKey; pushes call `queryClient.setQueryData(...)`.
+*/
+declare const useQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => ReturnOf<F> | undefined;
+interface UseRateLimitOptions {
+  /** Clock injection for tests. Defaults to `Date.now`. */
+  now?: () => number;
+  /**
+  * Re-render cadence in milliseconds while throttled, so `retryAfter` ticks
+  * down and `disabled` flips back automatically. Defaults to `1000`.
+  */
+  tickMs?: number;
+}
+interface UseRateLimitResult {
+  /** Would consuming `count` (default 1) succeed right now? Does not consume. */
+  check: (count?: number) => boolean;
+  /** Optimistically consume `count` (default 1) locally; mirrors the server algorithm. */
+  consume: (count?: number) => RateLimitStatus;
+  /** `true` while a single unit cannot be consumed — convenient for disabling a control. */
+  disabled: boolean;
+  /** `true` while a single unit can be consumed. */
+  ok: boolean;
+  /** Clear local accounting (e.g. after the server confirms a reset). */
+  reset: () => void;
+  /** Milliseconds until the next unit is available. `0` when `ok`. */
+  retryAfter: number;
+}
+/**
+* Client-side mirror of a rate limit for instant UX — disable a button or show
+* a countdown without a round-trip. It runs the same token-bucket / fixed-window
+* math as `@lunora/ratelimit` on the server, so the prediction agrees with the
+* authoritative check; the server remains the source of truth.
+*
+* `config` is read on every render; pass a stable reference (module constant or
+* `useMemo`) so the `consume`/`check` callbacks keep a steady identity.
+*/
+declare const useRateLimit: (config: RateLimitConfig, options?: UseRateLimitOptions) => UseRateLimitResult;
+/** The lifecycle of a stream the hook is observing. */
+type UseStreamStatus = "complete" | "error" | "idle" | "streaming";
+interface UseStreamResult<T> {
+  /** Force-cancel the stream and resolve the iterator. Safe to call multiple times. */
+  cancel: () => void;
+  /** Chunks the server has pushed so far, in arrival order. */
+  chunks: ReadonlyArray<T>;
+  error: Error | undefined;
+  status: UseStreamStatus;
+}
+interface UseStreamOptions {
+  /** Forwarded to `client.stream()` — caps the in-flight chunk buffer. */
+  maxBuffer?: number;
+  shardKey?: string;
+}
+/**
+* Subscribe to a streaming query. Returns the chunks pushed so far plus a
+* lifecycle status and a cancel function. Changing `fn` or the serialized
+* `args` resets the stream — the previous iterator is cancelled and a fresh
+* one opens with empty `chunks`.
+*
+* Pass `"skip"` for `args` to keep the hook mounted without opening a stream
+* (mirrors `useQuery` / `useSubscription`).
+*/
+declare const useStream: <F extends FunctionReference<"stream">>(function_: F, args: "skip" | ArgsOf<F>, options?: UseStreamOptions) => UseStreamResult<ReturnOf<F>>;
+/**
+* Subscribe to a real-time stream from the server. Unlike `useQuery`, this
+* hook does not issue an initial HTTP fetch — it only delivers values that
+* the server pushes over the WS.
+*/
+declare const useSubscription: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>;
+export { AuthLoading, type AuthState, Authenticated, CheckoutButton, type CheckoutButtonProps, CustomerPortalButton, type CustomerPortalButtonProps, type FlagContext, type FlagValue, type HeartbeatReference, type ListPresentReference, LunoraProvider, type LunoraProviderProps, type MutationHook, type MutatorHook, type PageItemOf, type PaginatedArgs, type RedirectTarget, type RedirectTrigger, type Subscription, Unauthenticated, type UseAuthResult, type UseCheckoutResult, type UseInfiniteQueryOptions, type UseInfiniteQueryResult, type UseMutationCallOptions, type UsePaginatedQueryOptions, type UsePaginatedQueryResult, type UsePresenceOptions, type UsePresenceResult, type UseQueryOptions, type UseRateLimitOptions, type UseRateLimitResult, type UseStreamOptions, type UseStreamResult, type UseStreamStatus, type UseSubscriptionResult, hydratePreloaded, useAuth, useAuthState, useCheckout, useConnectionStatus, useFlag, useFlags, useInfiniteQuery, useLunora, useMutation, useMutator, usePaginatedQuery, usePreloadedQuery, usePresence, useQuery, useRateLimit, useStream, useSubscription };