Client options

The browser (or any HTTP caller) needs a flow kind, a user id, and a base URL. React reads those from FlowProvider so each hook does not repeat them.

Narrative: Client, React.

createClient

import { createClient } from "@flow-state-dev/client";

const client = createClient({
  flowKind: "hello-chat",
  userId: "devuser",
});

Every request path the client builds already starts with /api/flows. Leave baseUrl off when the API is mounted on the same origin — setting it to "/api/flows" produces /api/flows/api/flows/….

Field	Type	Default	What it does
flowKind	string	required	Which flow to call.
userId	string	required	Caller identity sent on every request. The server still resolves the principal from your auth hook; this is the client's claim.
baseUrl	string	same origin	Prefix put in front of /api/flows/…. Omit it for a same-origin app (Next.js route handler, the node host). Set an origin such as https://api.example.com when the API lives elsewhere.
fetcher	typeof fetch	global fetch	Custom fetch (tests, extra headers).

createTypedClient({ flow, userId, ... }) adds the same connection fields and types sendAction from the flow instance.

sendAction options

Passed per call, not at client construction.

Field	Type	Default	What it does
sessionId	string	new ephemeral session	Existing session to continue.
requestId	string	minted	Correlate a client-generated id with the server request.
orgId	string	—	Binds the request to an org only under the default principal resolver. A flow with its own authentication.resolvePrincipal takes the org from the verified principal and ignores this value, so a caller cannot claim an org it was not granted. Under such a flow the resolver has to return the org, or a requireOrg block still rejects the request.
metadata	object	—	Request metadata. Stored on the request record and visible in traces. Session title and tags are set through the session API, not here.

FlowProvider

import { FlowProvider } from "@flow-state-dev/react";

<FlowProvider flowKind="hello-chat" userId="devuser">
  <Chat />
</FlowProvider>

Field	Type	What it does
flowKind	string	Default flow for hooks.
userId	string	Default caller id.
sessionId	string	Default session. useFlow({ autoCreateSession: true }) can mint one instead.
baseUrl	string	Forwarded to the client. Same rule: omit it for a same-origin app.
renderers	RendererRegistry	Custom item renderers. Nested providers merge; child keys override.
children	ReactNode	The tree that may call hooks.

Hooks (useFlow, useSession, useAction, useClientData, useVoice, …) accept the same connection fields as overrides. Hook-specific options (item visibility, auto-create, subscribe keys) are documented on React.

What the client can see

The server decides the snapshot. Scope client.expose / client.derived and each resource's client block are the gates. The browser cannot opt into private state by passing a flag. See Client access and Flow options.

See also

• Runtime — the server those clients call
• Authentication
• React API