Skip to content
DocspackagesDocumentation

@lunora/react

React 19 hooks built on @lunora/client, with React Server Component data loading.

PackagesReact

@lunora/react ships the official React bindings. It's a thin layer over @lunora/client that maps the cache to useSyncExternalStore, so concurrent React works correctly out of the box. The hooks live in the package root (a client boundary); server-side data loading for React Server Components / the Next.js App Router lives in @lunora/react/server.

The following root component creates a client and mounts the provider around the chat view:

import { LunoraClient } from "lunorash/client";
import { LunoraProvider, useMutation, useQuery } from "@lunora/react";
import { api } from "@/lunora/_generated/api";

const client = new LunoraClient({ url: import.meta.env.VITE_LUNORA_URL });

const Root = () => (
    <LunoraProvider client={client}>
        <Chat channelId="general" />
    </LunoraProvider>
);

<LunoraProvider client={...}>

Mounts the shared LunoraClient for the subtree. Required at the root.

useQuery(fn, args, options?)

Subscribes to a query. Returns T | undefined (undefined until the first response). Pass "skip" for args to short-circuit (no network call). Multiple useQuery calls with identical args share a single underlying network call via the in-memory cache.

The following calls subscribe to a channel's messages and to the signed-in user's profile:

const messages = useQuery(api.messages.list, { channelId });
const profile = useQuery(api.users.me, signedIn ? {} : "skip");

useMutation(fn)

Returns { mutate, pending, data, error, reset, withOptimisticUpdate }. mutate is the awaitable call; pending is ref-counted across overlapping calls from this hook, so it stays true until the last one settles. Destructure what you need:

const { mutate, pending } = useMutation(api.messages.send);

await mutate(
    { channelId, text },
    {
        optimisticUpdate: (store, args) => {
            const current = store.getQuery(api.messages.list, { channelId: args.channelId }) ?? [];

            store.setQuery(api.messages.list, { channelId: args.channelId }, [...current, draft]);
        },
    },
);

optimisticUpdate names the query it patches, which is what the send/list shape needs: the per-call optimistic: (current) => next shortcut only patches a subscription registered under the mutation's own reference and args, so it fits a query and a mutation that share a path (a counter, a document by id) and quietly does nothing for anything else.

To bind the same update to every call of a handle, use withOptimisticUpdate(update), which returns the same handle with the update applied by default.

Offline, mutate calls client.mutation at once when the client can queue the write: the optimistic update paints, and the write goes to the offline queue (or your durable outbox) to replay on reconnect. Before the shard's first connect (unless queueBeforeFirstConnect is set), or on a client with no WebSocket, the client cannot queue, so the call waits until the browser is back online and then sends. TanStack never retries; the queue owns replays.

useAction(fn)

Returns { call, pending, data, error, reset }. call is the awaitable invocation and rejects on failure; pending is ref-counted across overlapping calls from this hook, so a sibling component calling the same action never affects it.

data and error both track the latest invocation, not the last to settle: a double-click whose first call resolves after the second cannot overwrite the second's outcome. A success clears error; a failure leaves the previous data in place, so a transient error does not blank the view. reset() clears both, but does not cancel an in-flight call — its result still lands.

Unlike useMutation, the call never waits for the network, is never queued and is never retried: client.action has no offline queue and sends no idempotency key, so a paused call would fire minutes later on reconnect and a retry could run a third-party side effect twice. It fails fast instead and lets you decide.

The following handler runs a verification command and reads its pending state:

const { call: runVerify, pending } = useAction(api.commands.run);
await runVerify({ command: "lunora", args: ["verify"] });

Per-call options are { shardKey } only — there is no optimistic / optimisticUpdate and no withOptimisticUpdate. An optimistic update patches the subscription cache on the assumption a write will land; an action is not a write — it runs in the Worker, may call a third party, and has no declared effect on any query. Offering the option would imply a rollback guarantee nothing can honour.

useSubscription(fn, args)

Lower-level. Surfaces { data, error } so you can render error states without a separate useState.

useAuth()

Returns { status, user, token, setToken(next) }. Call setToken(jwt) after a sign-in flow; subsequent RPC calls carry the token automatically. It does not re-authenticate an open subscription — a socket keeps the session credential it connected with; client.setWsToken(token) rotates that.

status is the gate: "loading", "authenticated", "unauthenticated" or "unreachable" (a credential is held but the identity endpoint could not be reached — gates as authenticated). Branch on it, never on whether user is null: user is null both when signed out and when a held credential's identity has not resolved, so a user gate renders the sign-in form to a signed-in user. See the @lunora/client reference for the full table.

The following component renders by status and passes setToken to the sign-in form:

const { setToken, status, user } = useAuth();

if (status === "loading") return <Spinner />;
if (status === "unauthenticated") return <SignInForm onToken={setToken} />;
return <Dashboard email={user?.email} />;

Resolving the session also keys the client's offline-queue identity on the user id rather than the token bytes, so rotating the JWT for the same user keeps queued writes and the durable read cache instead of reading as a user switch. Between the rotation and the next session resolve, queued writes are held rather than replayed — the client cannot yet tell a refresh from an account switch.

Server Components (Next.js App Router)

Every hook in @lunora/react calls useState/useEffect and owns a live WebSocket: they're client-only, and each module declares "use client". Use them inside your own Client Components (the examples below mark "use client" on the files that call them).

Server-side data loading lives in a separate, server-safe entry, @lunora/react/server. It opens no socket and touches no browser globals, so it's safe to call from a Server Component. There are two ways to render with data already present on the first paint.

1. Prefetch + hydrate the TanStack cache

Run the query on the server, dehydrate the QueryClient, and wrap the client subtree in HydrationBoundary. The client useQuery reads the value out of the hydrated cache (same key, no loading flash) and a live subscription attaches on mount.

app/posts/page.tsx (Server Component)
import { createServerClient, prefetchQuery, dehydrate, HydrationBoundary } from "@lunora/react/server";
import { QueryClient } from "@tanstack/react-query";
import { cookies } from "next/headers";
import { api } from "@/lunora/_generated/api";
import { PostList } from "./post-list";

export default async function PostsPage() {
    const client = createServerClient({
        url: process.env.LUNORA_URL!,
        token: (await cookies()).get("session")?.value,
    });

    const queryClient = new QueryClient();
    await prefetchQuery(queryClient, client, api.posts.list, {});

    return (
        <HydrationBoundary state={dehydrate(queryClient)}>
            <PostList />
        </HydrationBoundary>
    );
}
app/posts/post-list.tsx (Client Component)
"use client";

import { useQuery } from "@lunora/react";
import { api } from "@/lunora/_generated/api";

export function PostList() {
    // Reads the server-prefetched value from cache on the first render, then
    // updates live as the WS subscription pushes changes.
    const posts = useQuery(api.posts.list, {});

    return (
        <ul>
            {posts?.map((p) => (
                <li key={p._id}>{p.title}</li>
            ))}
        </ul>
    );
}

Drop the await before prefetchQuery for fire-and-forget prefetch when you don't need the data on the first paint.

2. Preload an explicit token

When you'd rather thread one resolved value to one component without a HydrationBoundary, preloadQuery returns a serializable token you pass as a prop. The client reads it with usePreloadedQuery.

Server Component
import { createServerClient, preloadQuery } from "@lunora/react/server";
import { api } from "@/lunora/_generated/api";
import { Post } from "./post";

export default async function PostPage({ params }: { params: Promise<{ id: string }> }) {
    const { id } = await params;
    const client = createServerClient({ url: process.env.LUNORA_URL! });
    const preloaded = await preloadQuery(client, api.posts.get, { id });

    return <Post preloaded={preloaded} />;
}
Client Component
"use client";

import { usePreloadedQuery } from "@lunora/react";
import type { Preloaded } from "@lunora/react/server";

export function Post({ preloaded }: { preloaded: Preloaded<{ title: string }> }) {
    const post = usePreloadedQuery(preloaded); // server value first, then live

    // `undefined` after a sign-out or user switch, until the new identity's subscription answers.
    if (!post) {
        return <p>Loading…</p>;
    }

    return <h1>{post.title}</h1>;
}

usePreloadedQuery returns T | undefined. The preloaded value was read for whoever was signed in when the page loaded, so after a sign-out or user switch it is dropped and the hook returns undefined until the live value arrives: guard before reading fields.

Providers

Mount LunoraProvider once in a Client Component near the root. It creates (or reuses) the TanStack QueryClient that HydrationBoundary hydrates into.

app/providers.tsx
"use client";

import { LunoraClient } from "lunorash/client";
import { LunoraProvider } from "@lunora/react";
import { useState } from "react";

export function Providers({ children }: { children: React.ReactNode }) {
    const [client] = useState(() => new LunoraClient({ url: process.env.NEXT_PUBLIC_LUNORA_URL! }));
    return <LunoraProvider client={client}>{children}</LunoraProvider>;
}

@lunora/react/server reference

  • createServerClient({ url, token?, fetch? }): a request-scoped, HTTP-only LunoraClient. Build one per request so a user's token (and any cookies forwarded via fetch) never leak across requests.
  • prefetchQuery(queryClient, client, fn, args, { shardKey? }?): runs the query and seeds queryClient under the key the client hooks use.
  • preloadQuery(client, fn, args, { shardKey? }?): runs the query and returns a serializable Preloaded token for usePreloadedQuery.
  • dehydrate / HydrationBoundary: re-exported from @tanstack/react-query for convenience.

File uploads (@lunora/react/upload)

End-user file uploads (live progress, pause/resume, large-file resumable and per-part retry) are re-exported from @visulima/storage-client (Lunora does not hand-roll the uploader). useUpload speaks the protocol named in method; without it, it uses the only endpoint given, or picks between several by file size against tusThreshold. The TUS (resumable upload protocol) path survives a pause/resume and a dropped connection. Point the endpoint at a route backed by @lunora/storage/upload; these uploads are gated by your per-user row-level security (RLS) policy, not the studio adminToken. File storage walks through mounting the handler, authenticating the route, and the size limits.

TanStack Query reconciliation

The upload hooks (useUpload, useMultipartUpload, useTusUpload, useChunkedRestUpload, useFileInput, usePasteUpload) hold their own state and need no QueryClientProvider, so they coexist with Lunora's own useQuery. The @visulima/storage-client data hooks (useGetFileList …) are not re-exported and do not work against a Lunora upload route: they read files over GET, which the route refuses (405). Read stored files with ctx.storage or a signed URL.

For resumable uploads use useTusUpload (or useUpload with TUS). useChunkedRestUpload sends one chunk at a time, which the binding-backed provider requires; see Chunked REST.

Drag-and-drop uploader with a progress bar

import { useCallback, useRef, useState } from "react";
import { useUpload } from "@lunora/react/upload";

export function Uploader() {
    const [dragging, setDragging] = useState(false);
    const controlRef = useRef(null);

    // Each endpoint is its own `@lunora/storage/upload` handler: one handler
    // speaks one protocol. The hook auto-selects TUS for large files
    // (resumable), a plain multipart POST for small ones.
    const { upload, progress, isUploading, isPaused, pause, resume, abort, error, result } = useUpload({
        endpointTus: "/uploads",
        endpointMultipart: "/uploads-form",
        // Over R2 each TUS chunk is a multipart part, and R2 rejects parts under 5 MiB.
        chunkSize: 5 * 1024 * 1024,
        // Send the user's session so the server's `authorize` gate can identify them.
        headers: async () => ({ authorization: `Bearer ${await getSessionToken()}` }),
        restrictions: { maxFileSize: 5 * 1024 * 1024 * 1024, allowedFileTypes: ["video/*", "image/*"] },
        onSuccess: (file) => console.log("uploaded", file.id),
    });

    const onDrop = useCallback(
        (event: React.DragEvent) => {
            event.preventDefault();
            setDragging(false);
            const file = event.dataTransfer.files[0];
            if (file) void upload(file);
        },
        [upload],
    );

    return (
        <div
            onDragOver={(e) => {
                e.preventDefault();
                setDragging(true);
            }}
            onDragLeave={() => setDragging(false)}
            onDrop={onDrop}
            data-dragging={dragging}
            className="dropzone"
        >
            {isUploading ? (
                <>
                    <progress value={progress} max={100} />
                    <span>{progress}%</span>
                    {isPaused ? <button onClick={() => void resume?.()}>Resume</button> : <button onClick={() => pause?.()}>Pause</button>}
                    <button onClick={() => abort()}>Cancel</button>
                </>
            ) : result ? (
                <p>Uploaded ✓</p>
            ) : (
                <p>{dragging ? "Drop to upload" : "Drag a file here"}</p>
            )}
            {error ? <p role="alert">{error.message}</p> : null}
        </div>
    );
}

useUpload returns pause / resume / isPaused / offset only for the resumable protocols (TUS / chunked-REST). For a plain <input type="file">, useFileInput gives you the change-handler + selected-files plumbing; useTusUpload is the lower-level hook when you always want the resumable protocol.

Admin auth hooks

Reactive reads over the admin-gated auth plane — the /_lunora/admin/auth/* HTTP endpoints that the admin client exposes as listAuthUsers, listAuthSessions, listAuthOrganizations, and impersonateAuthUser (packages/client/src/admin/admin-client.ts). They are HTTP-only: unlike useQuery there is no live subscription behind them (the auth-admin surface does not ride the WS transport at all), so they are one-shot TanStack reads with an explicit refetch(). The worker must be built with an authAdmin and an adminToken, and the client must carry an admin-capable token.

HookReturns
useAuthUsers(options?)AdminAuthListResult<AuthUser>
useAuthSessions(options?)AdminAuthListResult<AuthSession>
useOrganizations(options?)AdminAuthListResult<Record<string, unknown>>
useImpersonate(){ data, error, pending, impersonate, reset }

AdminAuthListResult<T> is { data, error, loading, hasMore, total, loadMore, refetch }: data is the full current window (undefined before the first response), total is the server-reported count across the whole collection, and loadMore() grows the requested window by one page and re-fetches. It is a growing-window re-fetch, not a cursor accumulator — the underlying AuthPage is offset/limit-based and there is no live delta stream to keep page boundaries stable against.

Shared options: { enabled?, pageSize? } (pageSize defaults to 50). useAuthUsers adds { search?, searchField?, filterField?, filterValue?, sortBy?, sortDirection? }; useAuthSessions adds { userId? } to scope the list to one user.

AuthUser, AuthSession, AuthPage, and AuthImpersonation are re-exported from the package root, so a console UI can annotate these results without reaching into @lunora/client.

import { useAuthUsers, useImpersonate, type AuthUser } from "@lunora/react";

const UserTable = () => {
    const { data, error, hasMore, loadMore, loading, refetch, total } = useAuthUsers({ pageSize: 25, search: "acme" });
    const { impersonate, pending } = useImpersonate();

    if (loading) return <p>Loading…</p>;
    if (error) return <p role="alert">{error.message}</p>;

    return (
        <>
            <p>
                {data?.length ?? 0} of {total ?? 0}
            </p>
            <ul>
                {(data ?? []).map((user: AuthUser) => (
                    <li key={user.id}>
                        {user.email}
                        <button disabled={pending} onClick={() => void impersonate(user.id)}>
                            Impersonate
                        </button>
                    </li>
                ))}
            </ul>
            {hasMore ? <button onClick={loadMore}>Load more</button> : null}
            <button onClick={refetch}>Refresh</button>
        </>
    );
};

Mutations stay plain client.* calls (client.createAuthOrganization, client.deleteAuthOrganization, …); call the relevant hook's refetch() afterwards — nothing is invalidated implicitly.

impersonate(userId) resolves an AuthImpersonation (bearer token + target user + expiry) and deliberately does not call client.setAuthToken(...). Swapping the current session would sign the admin out of their own admin session with no visible transition and no way back; what to do with the token — open it in a second tab, surface it for copy — is the caller's decision.

Agent tool events — useAgentToolEvents(options)

Observes one agent thread's tool activity, separate from its chat transcript: which tools the model called, what they returned, which are parked on a human approval, and any in-flight ctx.reportProgress(...) updates.

options: { api, threadKey, stream?, limit? } — api is the generated api (it reads api.agents.agentMessages), and stream is the same app stream reference useAgentChat takes. Returns { events }.

Each event discriminates on type:

typeFieldsSource
calltoolCallId, toolName, input, seqdurable
resulttoolCallId?, toolName?, output, status?, seqdurable
awaiting-approvaltoolCallId?, toolName?, seqdurable
progresstoolCallId, datalive stream

Durable events come first, oldest first by seq, followed by the ephemeral progress events for the in-flight turn. With no stream reference only the durable lifecycle is surfaced. The array is rebuilt on every update — treat it as derived, not identity-stable, and key rendered rows on toolCallId/seq.

The following component renders one thread's tool timeline, keyed by event type:

import { useAgentToolEvents } from "@lunora/react";
import { api } from "@/lunora/_generated/api";

const ToolTimeline = ({ threadKey }: { threadKey: string }) => {
    const { events } = useAgentToolEvents({ api, stream: api.chat.liveEvents, threadKey });

    return (
        <ol>
            {events.map((event, index) => (
                <li key={event.type === "progress" ? `p-${index}` : event.seq}>
                    {event.type === "call" ? `→ ${event.toolName}` : null}
                    {event.type === "result" ? `← ${event.output}` : null}
                    {event.type === "awaiting-approval" ? "⏸ awaiting approval" : null}
                    {event.type === "progress" ? JSON.stringify(event.data) : null}
                </li>
            ))}
        </ol>
    );
};

Voice agents — useVoiceAgent(options)

Opens a full-duplex voice call against a voice-enabled agent — the api.agents.<name>Voice reference codegen emits. Microphone capture goes up the agent's WebSocket, synthesized speech comes back down, and transcripts plus barge-in are surfaced along the way.

options: { voice, threadKey, silenceThreshold?, silenceDurationMs?, interruptThreshold?, interruptChunks?, createMicrophone?, createSocket?, createSpeaker? }. threadKey is shared with the agent's text turns, so a voice call continues the very same conversation useAgentChat renders.

Returns { status, connected, transcript, interimTranscript, audioLevel, isMuted, error, startCall, endCall, sendText, toggleMute }. status is "idle" | "listening" | "thinking" | "speaking".

The following component starts and ends a call from one button:

import { useVoiceAgent } from "@lunora/react";
import { api } from "@/lunora/_generated/api";

const CallButton = ({ threadKey }: { threadKey: string }) => {
    const { audioLevel, endCall, startCall, status, transcript } = useVoiceAgent({
        threadKey,
        voice: api.agents.supportVoice,
    });

    return (
        <>
            <button onClick={status === "idle" ? () => void startCall() : endCall}>{status === "idle" ? "Call" : "Hang up"}</button>
            <meter max={1} value={audioLevel} />
            <p>{transcript}</p>
        </>
    );
};

Microphone and audio lifecycle

The part the type signature does not tell you:

  • Nothing opens until startCall(). Creating the handle touches neither the microphone nor the socket. startCall is what calls getUserMedia, so it has to run from a user gesture — browsers block both the permission prompt and AudioContext resumption outside one. It is idempotent while a call is active, and a denied permission lands in error rather than throwing at the call site.
  • A failed turn drops its partial answer. When the model fails mid-answer (or its stream is cut short), the text already streamed for that turn is cleared from interimTranscript and error is set; the call returns to listening. A retried turn starts its text from empty, never from the failed attempt's prefix.
  • endCall() releases everything — the socket, the microphone tracks, and the Web Audio graph — and is idempotent. The hook also tears the call down on unmount, so a component that navigates away mid-call leaks nothing.
  • audioLevel is the live input root mean square (RMS, 0–1). It drives a mic meter, and it is also what the heuristics read: silenceThreshold + silenceDurationMs decide when an utterance auto-commits (defaults 0.01 / 1200ms), and interruptThreshold + interruptChunks decide when the user barges in on the agent mid-sentence (defaults 0.15 / 3 consecutive chunks). These are room-dependent; tune them against real hardware rather than trusting the defaults.
  • createMicrophone / createSpeaker / createSocket are injection seams for tests and non-DOM hosts. The defaults are getUserMedia + Web Audio + new WebSocket(url), so the primitive is inert (and mockable) anywhere those are missing.

API reference

Provider

LunoraProvider

Type: ({ children, client, queryClient }: LunoraProviderProps) => ReactElement

Mounts the shared LunoraClient for the subtree. See the provider section.

LunoraProviderProps

Type: { children: ReactNode; client: LunoraClient; queryClient?: QueryClient }

Props for LunoraProvider. queryClient is optional; the provider creates or reuses a TanStack QueryClient when you omit it.

useLunora

Type: () => LunoraClient

Returns the LunoraClient from the nearest LunoraProvider. Use it when a component calls client.* methods directly instead of through a hook.

Queries

useQuery

Type: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => ReturnOf<F> | undefined

Subscribes to a query and returns its value, or undefined until the first response. Pass "skip" for args to make no network call. See details.

UseQueryOptions

Type: { onError?: SubscriptionErrorCallback; shardKey?: string }

Options for useQuery, useSubscription and useSuspenseQuery. onError receives the server-pushed SubscriptionError, and shardKey routes the subscription to one shard.

useSuspenseQuery

Type: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: UseQueryOptions) => ReturnOf<F>

Subscribes to a query inside a <Suspense> boundary and returns the value directly. The component suspends until the first value arrives, so the return is never undefined. There is no "skip"; use useQuery for a query that may not run.

useSubscription

Type: <F extends FunctionReference>(function_: F, args: ArgsOf<F> | "skip", options?: UseQueryOptions) => UseSubscriptionResult<ReturnOf<F>>

Lower-level hook that delivers only server-pushed values, with no initial HTTP fetch. It returns { data, error }, so you can render an error state without extra useState.

usePaginatedQuery

Type: <F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: UsePaginatedQueryOptions) => UsePaginatedQueryResult<PageItemOf<F>>

Subscribes to a paginated query and grows the result with loadMore(numberItems). The result is { results, status, isLoading, error, loadMore }, with results flattened into one array.

UsePaginatedQueryOptions

Type: { initialNumItems: number; onError?: SubscriptionErrorCallback; shardKey?: string }

Options for usePaginatedQuery. initialNumItems sets how many rows the first page loads.

useInfiniteQuery

Type: <F extends FunctionReference>(function_: F, args: "skip" | PaginatedArgs<F>, options: UseInfiniteQueryOptions) => UseInfiniteQueryResult<PageItemOf<F>>

Subscribes to a paginated query and keeps each page as its own array in pages. It adds fetchNextPage, hasNextPage and isFetchingNextPage, so the shape follows TanStack Query.

UseInfiniteQueryOptions

Type: { initialNumItems: number; onError?: SubscriptionErrorCallback; shardKey?: string }

Options for useInfiniteQuery. Changing the query, its base args, initialNumItems or shardKey resets the feed to its first page.

useClientQuery

Type: <T>(ref: ClientQueryRef<T>) => [T, Setter<T>]

Subscribes to a local-only value made with createClientQuery and returns it with a useState-style setter. It never touches the network, and every consumer of the same ref shares the value.

Mutations and actions

useMutation

Type: <F extends FunctionReference>(function_: F) => MutationHook<F>

Returns a mutation handle for a server mutation. mutate is awaitable, and pending stays true until the last overlapping call settles. See details.

MutationHook

Type: MutationHook<F extends FunctionReference> { data: ReturnOf<F> | undefined; error: Error | null; isError: boolean; mutate: (args: ArgsOf<F>, options?) => Promise<ReturnOf<F>>; pending: boolean; reset: () => void; withOptimisticUpdate: (update: OptimisticUpdate<ArgsOf<F>>) => MutationHook<F> }

The object useMutation returns. withOptimisticUpdate(update) returns a handle whose mutate applies update as the optimistic update for every call, unless a call passes its own optimisticUpdate.

useMutator

Type: <TArgs = Record<string, unknown>>(handle: MutatorHandle<TArgs>) => MutatorHook<TArgs>

Wraps a custom-mutator handle bound with bindMutators from @lunora/db. It adds React state for the in-flight and error lifecycle. Reads stay on the live query hooks.

MutatorHook

Type: { error: Error | undefined; isError: boolean; mutate: (args: TArgs) => Promise<void>; pending: boolean; reset: () => void }

The object useMutator returns. mutate resolves once the write is persisted and rejects on failure.

useAction

Type: <F extends FunctionReference>(function_: F) => ActionHook<F>

Returns a handle for a server action. call fails fast and is never queued or retried. See details.

ActionHook

Type: ActionHook<F extends FunctionReference> { call: (args: ArgsOf<F>, options?: ActionCallOptions) => Promise<ReturnOf<F>>; data: ReturnOf<F> | undefined; error: Error | undefined; pending: boolean; reset: () => void }

The object useAction returns. ActionCallOptions comes from @lunora/client. data and error track the latest invocation, not the last one to settle.

Live data

useLiveTopic

Type: <Payload>(topic: LiveTopicRef<Payload>, options?: UseLiveTopicOptions<Payload>) => UseLiveTopicResult<Payload>

Follows one topic of a defineLiveStream for the life of the component. It returns { lastEvent, error }, and lastEvent is typed by the payload the topic declares.

useStream

Type: <F extends FunctionReference<"stream">>(function_: F, args: "skip" | ArgsOf<F>, options?: UseStreamOptions) => UseStreamResult<ReturnOf<F>>

Subscribes to a streaming query and returns the chunks received so far, a status and a cancel function. Changing the function or args cancels the previous stream and starts an empty one.

UseStreamOptions

Type: { durable?: boolean; maxBuffer?: number; shardKey?: string }

Options for useStream. Set durable to resume the same run after a dropped connection, for streams the server declared durable. maxBuffer caps the chunk buffer.

usePresence

Type: <H extends HeartbeatReference, L extends ListPresentReference>(roomId: string, options: UsePresenceOptions<H, L>) => UsePresenceResult<L>

Joins a presence room and heartbeats the session on an interval. It returns the sessions present, the current sessionId and a setData setter for this session's data.

useConnectionStatus

Type: () => ConnectionStatus

Returns the aggregate live-socket status across all shard connections: "connected", "connecting", "idle", "offline" or "polling". Use it to drive a connection indicator.

useRateLimit

Type: (config: RateLimitConfig, options?: UseRateLimitOptions) => UseRateLimitResult

Predicts the outcome of a rate-limited action in the browser, using the same math as @lunora/ratelimit on the server. The server stays the source of truth. Pass a stable config so the returned callbacks keep their identity.

Authentication

useAuth

Type: () => UseAuthResult

Returns { status, user, token, setToken }. Branch on status, not on user. See details.

UseAuthResult

Type: { setToken: (token: string | null) => void; status: AuthStatus; token: string | null; user: User | null }

The object useAuth returns. status is "loading", "authenticated", "unauthenticated" or "unreachable".

useAuthState

Type: () => AuthState

Returns the sign-in state as { isAuthenticated, isLoading }, with no status string to branch on.

Authenticated

Type: ({ children }: AuthGateProps) => ReactNode

Renders children only when the session is signed in.

Unauthenticated

Type: ({ children }: AuthGateProps) => ReactNode

Renders children only when no session is signed in.

AuthLoading

Type: ({ children }: AuthGateProps) => ReactNode

Renders children only while the session state is still resolving.

Admin auth

These hooks read the admin-gated auth plane over HTTP. See details.

useAuthUsers

Type: (options?: UseAuthUsersOptions) => AdminAuthListResult<AuthUser>

Lists auth users with search, filter and sort options, one page at a time. Call loadMore() to grow the window or refetch() after a mutation.

useAuthSessions

Type: (options?: UseAuthSessionsOptions) => AdminAuthListResult<AuthSession>

Lists auth sessions. Pass userId to scope the list to one user.

useOrganizations

Type: (options?: UseOrganizationsOptions) => AdminAuthListResult<Record<string, unknown>>

Lists the auth organizations on the admin plane. It accepts the shared enabled and pageSize options.

useSignUpInvitations

Type: (options?: UseSignUpInvitationsOptions) => AdminAuthListResult<Record<string, unknown>>

Lists sign-up invitations on the admin plane. It accepts the shared enabled and pageSize options.

useImpersonate

Type: () => UseImpersonateResult

Returns { data, error, pending, impersonate, reset }. impersonate(userId) mints an impersonation session through client.impersonateAuthUser and returns its token. It never calls client.setAuthToken, so the admin's own session stays active, and it invalidates no list.

Agents

useAgent

Type: (options: UseAgentOptions) => UseAgentResult

Starts agent turns on one thread with run and returns the thread's status, thread record, pending state and cancel.

useAgentChat

Type: (options: UseAgentChatOptions) => UseAgentChatResult

Renders one thread's transcript. It returns messages, streamingText, send, and the approval actions approve, reject and supplySecret.

useAgentState

Type: <T extends Record<string, unknown> = Record<string, unknown>>(options: UseAgentStateOptions) => UseAgentStateResult<T>

Subscribes to one thread's live synced state. It returns { state, error }, with state typed by the generic T.

useAgentApprovals

Type: (options: UseAgentApprovalsOptions) => UseAgentApprovalsResult

Lists the caller's pending human-in-the-loop approvals. Each entry carries what agentResolveApproval needs to approve or reject it.

useAgentToolEvents

Type: (options: UseAgentToolEventsOptions) => UseAgentToolEventsResult

Returns one thread's tool timeline as { events }, with durable call, result, awaiting-approval and awaiting-secret events followed by live progress events. See details.

useVoiceAgent

Type: (options: UseVoiceAgentOptions) => UseVoiceAgentResult

Opens a full-duplex voice call against a voice-enabled agent on the same thread as its text turns. startCall must run from a user gesture. See details.

Flags

useFlag

Type: <T extends FlagValue>(key: string, defaultValue: T) => T

Subscribes to one feature flag and returns its live value. It returns defaultValue until the first evaluation arrives, and the flag's kind comes from the type of defaultValue.

Payments

These components come from @lunora/react/payment.

useCheckout

Type: (trigger: RedirectTrigger) => UseCheckoutResult

Runs a redirect trigger and returns { checkout, pending, error }. The trigger resolves to a RedirectTarget whose url the hook redirects the browser to. It refuses a URL that is not http or https.

CheckoutButton

Type: ({ onCheckout, ...rest }: CheckoutButtonProps) => ReactNode

Button that runs onCheckout on click and then redirects to the URL it returns.

CustomerPortalButton

Type: ({ onPortal, ...rest }: CustomerPortalButtonProps) => ReactNode

Button that runs onPortal on click and then redirects to the billing portal URL it returns.

Server

These functions come from @lunora/react/server. See the server reference.

fetchQuery

Type: <F extends FunctionReference>(options: ServerClientOptions, function_: F, args: ArgsOf<F>, callOptions?: ServerCallOptions) => Promise<ReturnOf<F>>

Runs a query once on the server and returns its result. Errors propagate.

fetchMutation

Type: <F extends FunctionReference>(options: ServerClientOptions, function_: F, args: ArgsOf<F>, callOptions?: ServerCallOptions) => Promise<ReturnOf<F>>

Runs a mutation once on the server over HTTP and returns its result. The offline queue and optimistic updates do not apply.

fetchAction

Type: <F extends FunctionReference>(options: ServerClientOptions, function_: F, args: ArgsOf<F>, callOptions?: ServerCallOptions) => Promise<ReturnOf<F>>

Runs an action once on the server and returns its result. Errors propagate.

prefetchQuery

Type: <F extends FunctionReference>(queryClient: QueryClient, client: LunoraClient, function_: F, args: ArgsOf<F>, options?: { shardKey?: string }) => Promise<void>

Runs a query and seeds queryClient under the key the client hooks read. Pair it with dehydrate and HydrationBoundary.

preloadQuery

Type: <F extends FunctionReference>(client: LunoraClient, function_: F, args: ArgsOf<F>, options?: { shardKey?: string }) => Promise<Preloaded<ReturnOf<F>>>

Runs a query and returns a serializable Preloaded token. Pass the token to usePreloadedQuery.

usePreloadedQuery

Type: <T>(preloaded: Preloaded<T>, options?: { onError?: SubscriptionErrorCallback }) => T | undefined

Reads a Preloaded token from a server component and then the live value. The result is undefined after a sign-out or user switch. See details.

hydratePreloaded

Type: <T>(preloaded: Preloaded<T>, options?: { onError?: SubscriptionErrorCallback }) => T | undefined

An alias of usePreloadedQuery under the name every adapter shares. It is a hook: call it from a component body, following the Rules of Hooks.

Errors

Use these guards to branch on the error code of a failed call. Each returns true only when the error carries the matching code.

isUnauthorizedError

Type: (error: unknown) => error is Error & { code: "UNAUTHORIZED" }

Narrows an unknown error to one with the UNAUTHORIZED code.

isForbiddenError

Type: (error: unknown) => error is Error & { code: "FORBIDDEN" }

Narrows an unknown error to one with the FORBIDDEN code.

isConflictError

Type: (error: unknown) => error is Error & { code: "CONFLICT" }

Narrows an unknown error to one with the CONFLICT code, which the server returns on a write conflict.

isRateLimitedError

Type: (error: unknown) => error is Error & { code: "TOO_MANY_REQUESTS" }

Narrows an unknown error to one with the TOO_MANY_REQUESTS code.

getErrorCode

Type: (error: unknown) => LunoraErrorCode | undefined

Returns the Lunora error code on an error. It returns undefined for a non-error, a missing code, or a code outside the known LunoraErrorCode set.

getRetryAfterMs

Type: (error: unknown) => number | undefined

Returns the retry delay in milliseconds from data.retryAfterMs on a rate-limited error, or undefined when it is absent or not a finite number.