Providers

ClientSessionProvider creates a ClientSession once on mount, connects it, and exposes it to descendants through React context. The hooks in @ably/ai-transport/react read the session via this provider, so wrap every subtree that uses them in one.

Nest multiple providers with distinct channelName values to manage more than one session in the same tree. Each provider merges its slot into the parent registry so descendants can address any registered session by channelName.

import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';
import { ClientSessionProvider } from '@ably/ai-transport/react';
import { UIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });

function App() {
  return (
    <AblyProvider client={ably}>
      <ClientSessionProvider channelName="conversation-42" codec={UIMessageCodec}>
        <Chat />
      </ClientSessionProvider>
    </AblyProvider>
  );
}

ClientSessionProvider

The provider reads the Ably Realtime client from the surrounding <AblyProvider> and forwards it, along with the supplied props, to createClientSession. The session is created once on first render via useRef. connect() is invoked from a useEffect so the session is subscribed and attached before the first descendant read.

If createClientSession throws, the error is stored on the slot alongside an undefined session. useClientSession surfaces it as sessionError so the component tree does not crash.

Props

ClientSessionProviderProps extends all ClientSessionOptions except client (which is read from <AblyProvider>).

ClientSessionSlot

A single entry in the registry holding the session and any error from construction. useClientSession returns this shape.

Bake hook types with createSessionHooks

A factory that captures the codec's four type parameters once and returns a bundle of type-safe hooks plus a narrowed ClientSessionProvider. Hook call sites need no type parameters once you have called the factory.

Use this when you have one codec for the whole app and want call sites that look like const view = useView({ limit: 30 }) without generics. The Vercel React entry point already exports a bundle baked to the Vercel types.

// session.ts: shared module
import { createSessionHooks } from '@ably/ai-transport/react';
import type {
  VercelInput,
  VercelOutput,
  VercelProjection,
} from '@ably/ai-transport/vercel';
import type { UIMessage } from 'ai';

export const {
  ClientSessionProvider,
  useClientSession,
  useView,
  useTree,
  useCreateView,
  useAblyMessages,
} = createSessionHooks<VercelInput, VercelOutput, VercelProjection, UIMessage>();

The factory takes four type parameters. Omitting them leaves every hook inferred as unknown; pass them explicitly so call sites stay type-safe.

Returns

Example

Nested providers with distinct channel names and a child component that addresses each session by name.

import * as Ably from 'ably';
import { AblyProvider } from 'ably/react';
import { ClientSessionProvider, useClientSession } from '@ably/ai-transport/react';
import { UIMessageCodec } from '@ably/ai-transport/vercel';

const ably = new Ably.Realtime({ authUrl: '/api/auth/token' });

function App() {
  return (
    <AblyProvider client={ably}>
      <ClientSessionProvider channelName="ai:main" codec={UIMessageCodec}>
        <ClientSessionProvider channelName="ai:aux" codec={UIMessageCodec}>
          <Chat />
        </ClientSessionProvider>
      </ClientSessionProvider>
    </AblyProvider>
  );
}

function Chat() {
  const { session: main } = useClientSession({ channelName: 'ai:main' });
  const { session: aux, sessionError } = useClientSession({ channelName: 'ai:aux' });

  if (sessionError) return <ErrorBanner error={sessionError} />;
  return <SplitPane mainSession={main} auxSession={aux} />;
}