Chat packages

Three packages over one conversation store. Pick the layer that matches how much of the UI you want to own.

Three layers

ConversationStore is the single source of truth all three build on — the React hook bridges it through useSyncExternalStore, and the custom element wraps the same object.

@cheela/ui

npm install @cheela/ui

CheelaProvider

Holds the client and config. Everything else reads from its context, so several chats on a page share one authenticated client.

Chat

<Chat
  initialMessages={saved}
  placeholder="Ask me anything..."
  className="my-chat"
  onMessage={(message) => persist(message)}
  onError={(error) => toast(error.message)}
  renderMessage={(message) => <MyBubble message={message} />}
/>

Chat never takes an apiKey — it reads the shared client from context.

Primitives

Exported so you can rebuild the layout without rebuilding the behaviour: MessageList, MessageBubble, MessageActions, ChatInput, Markdown, Spinner, plus cn for class merging.

The first three take an optional onReply, which is what makes a capability’s reply buttons live — Chat wires it to sendMessage for you. Rendering one of them yourself without a handler drops reply actions rather than rendering them dead; links are unaffected. A disabled prop refuses input while a turn is in flight, matching the composer.

Hooks

import { useCheelaChat } from "@cheela/ui";

function MyChat() {
  const { messages, status, error, sendMessage, reset } = useCheelaChat({
    initialMessages: [],
  });

  return (
    <form onSubmit={(e) => { e.preventDefault(); sendMessage(text); }}>
      {/* your markup */}
    </form>
  );
}

useCheelaClient() and useCheelaConfig() return the context’s client and resolved config directly. useResolvedTheme() turns auto into a concrete value.

@cheela/client

npm install @cheela/client

No React, no DOM assumptions. Use it for Vue, Svelte, Solid, a CLI, or a server-side integration.

import { ExecutionClient, ConversationStore } from "@cheela/client";

const client = new ExecutionClient({
  apiKey: "ch_pk_...",
  endUserToken: () => session?.token,
});

const store = new ConversationStore(client);
const unsubscribe = store.subscribe(() => render(store.getState()));

await store.sendMessage("Where is order 8812?");

ExecutionClient

execute() takes the request body plus an optional signal for cancellation.

ConversationStore

Owns the transcript and the request lifecycle. It is a plain observable — subscribe, getState, getServerSnapshot — which is what lets React consume it through useSyncExternalStore without a second copy of the state.

interface ConversationState {
  readonly messages: readonly Message[];
  readonly status: "idle" | "submitting" | "error";
  readonly error?: CheelaClientError;
}

Streaming events

type ExecutionStreamEvent =
  | { type: "text"; content: string }
  | { type: "capability_start"; capability: string }
  | { type: "capability_end"; capability: string; durationMs: number; error?: string }
  | { type: "done"; result: ExecutionResult };

capability_start and capability_end are what let a UI say “checking your order…” while it happens. The stream always ends with done, including on failure.

Errors

import { CheelaAuthError, CheelaClientError } from "@cheela/client";

try {
  await client.execute({ messages });
} catch (error) {
  if (error instanceof CheelaAuthError) {
    // check the key is the ch_pk_ one
  } else if (error instanceof CheelaClientError) {
    // network, or an API error
  }
}

A failed execution is not an error here — it resolves normally with status: "failed". Only transport and auth problems throw.

@cheela/web-component

Two builds, for two situations.

Script tag

<script src="https://unpkg.com/@cheela/web-component/dist/cheela-chat.js"></script>
<cheela-chat api-key="ch_pk_..." theme="auto"></cheela-chat>

The loader defines the element immediately and fetches the heavier core chunk only when one mounts, resolved relative to its own script URL.

Bundler import

import "@cheela/web-component";

This build bundles the core statically. Deferring it is your own bundler’s dynamic import() to make, one level up.

Attributes and API

All four are observed — changing one reconfigures the mounted widget rather than remounting it. configure() is the programmatic equivalent, and window.Cheela.init(element, options) mounts one imperatively.

Registration is guarded, so importing twice does not throw on a duplicate custom-element name.

Practical setup in Embed chat.