API reference
Every package and entry point, what it exports, and which parts are planned.
API reference
The packages are on npm as 3.0.0 prereleases; exports may change between prereleases, so pin an exact version. Terms used here (host, capability, adapter, run) are defined in Core concepts.
Packages and entry points
| Package | Entry point | What's in it | Status |
|---|---|---|---|
@openmaxai/chat |
@openmaxai/chat |
Re-exports the common parts of the entries below, and CHAT_VERSION |
Available |
@openmaxai/chat/host |
ChatHost and every capability type, useChatHost, error helpers |
Available | |
@openmaxai/chat/conversation-list |
ConversationList, a resizable column wrapper |
Available | |
@openmaxai/chat/message-thread |
MessageThread |
Available | |
@openmaxai/chat/composer |
The plugin API, COMPOSER_PLUGINS, ChatFileDropZone |
Available | |
@openmaxai/chat/header |
ChatHeader |
Available | |
@openmaxai/chat/group-management |
CreateGroupModal, ChatInfoPanel, AddMemberContainer |
Available | |
@openmaxai/chat/surfaces |
Floating windows, docked column, minimized dock, mobile drawer | Available | |
@openmaxai/chat/preview |
ChatContractSmoke, a minimal self-check view |
Available | |
@openmaxai/chat/agent-runs |
Agent run progress, tool steps, stop button, run list, Agent panel | Planned | |
@openmaxai/chat-sdk |
@openmaxai/chat-sdk |
The adapter interface, ChatSdkError, local storage, CHAT_SDK_VERSION (no React) |
Available |
@openmaxai/chat-sdk/react |
createChatHost, useChatSdkConversationList, local capability helpers |
Available | |
@openmaxai/chat-sdk/react |
ChatProvider (the one entry point for the host and composer plugins), ConversationScope |
||
@openmaxai/chat-sdk/testing |
The in-memory adapter createMemoryAdapter |
Available | |
@openmaxai/chat-sdk/testing |
The adapter conformance suite | Planned | |
@openmaxai/chat-sdk/devtools |
The ChatDevtools panel; see Devtools |
Available | |
@openmaxai/chat-openmax |
@openmaxai/chat-openmax, @openmaxai/chat-openmax/react |
The OpenMax adapter and the one-line createChatHost |
Available |
@openmaxai/chat-store |
@openmaxai/chat-store, @openmaxai/chat-store/react |
The message store: single write entry point, gap-fill scheduler, storage interface; no UI | In the code, not wired to the UI yet |
@openmaxai/chat-store/inspect |
The read-only inspection API: inspection snapshots and the stream of store events | Planned |
Choosing an entry point
| You want | Import | Guide |
|---|---|---|
| The whole chat on OpenMax | createChatHost from @openmaxai/chat-openmax/react, components (CwsConversationList, CwsMessageThread, …) from @openmaxai/chat-sdk/react |
Connect to OpenMax |
| Your own backend | An adapter passed to createChatHost from @openmaxai/chat-sdk/react, the same components; or a hand-written host completed with createLocalPorts, installed with ChatProvider as well |
Connect your own backend |
| One component | Its own entry point (@openmaxai/chat/header, …) |
A host from either createChatHost is used like this: the SDK components go inside ChatRoot, and your global CSS imports @openmaxai/chat-sdk/styles.css.
app.tsx
import { createChatHost } from "@openmaxai/chat-openmax/react";
import {
ChatProvider,
ChatRoot,
ChatSplitLayout,
ConversationHeader,
CwsConversationList,
CwsMessageThread,
useChatSdkConversationList,
} from "@openmaxai/chat-sdk/react";
import { useState } from "react";
const host = createChatHost({ baseUrl, wsUrl, auth });
export function App() {
return (
<ChatProvider host={host}>
<ChatRoot style={{ display: "flex", height: "100%" }}>
<Chat />
</ChatRoot>
</ChatProvider>
);
}
function Chat() {
const { conversations } = useChatSdkConversationList();
const [selectedId, setSelectedId] = useState<string | null>(null);
const selected = conversations.find((c) => c.id === selectedId) ?? null;
return (
<ChatSplitLayout
open={selected !== null}
list={
<CwsConversationList
selectedId={selectedId}
onSelect={(c) => setSelectedId(c.id)}
onDeselect={() => setSelectedId(null)}
/>
}
>
{selected && (
<>
<ConversationHeader
conversation={selected}
onBack={() => setSelectedId(null)}
/>
<CwsMessageThread key={selected.id} conversation={selected} />
</>
)}
</ChatSplitLayout>
);
}
A hand-written host and "one component" use the components of @openmaxai/chat, which have no style root: the stylesheet applies only inside the .omx-chat component root each SDK component brings along, and ChatRoot is not a style scope itself, so they render unstyled. Put them inside ChatRoot and wrap them in an element with the class omx-chat (plus omx-dark in dark mode, with colorScheme="dark" on ChatRoot), or style them yourself. A wrapper alone is not enough: outside ChatRoot, dialogs, menus and popovers portal to document.body, outside your wrapper, and get no styles; within ChatRoot they land in its overlay container, which carries the class omx-chat.
Pages
- @openmaxai/chat: Components, the ChatHost fields, provider and hooks, per entry point.
- Host capabilities: Members of every ChatHost capability: signatures, required or not, what to do on errors.
- Data model: Every field of messages, conversations, members, attachments, read state and the other types.
- @openmaxai/chat-sdk: createChatHost, the adapter interface, errors, components and hooks, local data, the in-memory test adapter.
- @openmaxai/chat-store: The message store package: the store, write entry point events, gap-fill scheduler, storage interface.
- @openmaxai/chat-openmax: The OpenMax adapter, its error mapping and the one-line createChatHost.
Signatures on the @openmaxai/chat-sdk, @openmaxai/chat-store and @openmaxai/chat-openmax pages are generated from the source; the @openmaxai/chat tables are written by hand from the source.
