Overview
Overview of the OpenMax adapter package @openmaxai/chat-openmax: status, the two entry points, wiring it in, and an index of every export.
Overview
@openmaxai/chat-openmax connects @openmaxai/chat-sdk to the OpenMax backend: the REST client, tokens, the realtime connection (ticket exchange, frame decoding, backoff reconnects), the device id, the attachment upload channel and URL resolution all live in this package. It offers an adapter, createOpenMaxAdapter, and a one-line createChatHost. The shared parts (how a host is assembled, the adapter interface, the error model, the components) are on @openmaxai/chat-sdk.
These pages are written from the source in the package and are the package's own interface reference: this page is the overview (status, entry points, wiring it into a host, an index of every export), and the signature and description of each export are on the six pages below. A step-by-step setup is in Connecting to OpenMax.
In this section
- Adapter:
createOpenMaxAdapterwith its configOpenMaxChatConfig, the credentialsOpenMaxAuth, thegetTokenhintOpenMaxGetTokenOptionsand the token-with-expiryOpenMaxToken, plus which endpoints each adapter member calls;openMaxSharedRealtimefor borrowing a realtime connection the host already owns. - Errors:
ChatSdkRequestError, how HTTP statuses map to error kinds, and how the token is renewed after a401. - React entry point:
createChatHostin@openmaxai/chat-openmax/react, plus the Provider and list hook re-exported from@openmaxai/chat-sdk/react. - Message endpoints: the endpoints behind reactions, edits, recalls, edit history and the change log, how realtime frames become signals, and
toEditMessageContentandtoMessageEdits, which you can reuse when writing your own host. - Card verdicts: how a failed card submission is judged (
classifyCardActionError), how a successful response becomes the settled record (cardStateFromSubmit), and the request body for form-card answers (formAnswersBody). - Known gaps and version:
KNOWN_GAPS_CHAT_OPENMAX,CHAT_OPENMAX_VERSION.
Status
- Published as a prerelease. The package is on npm as a
3.0.0prerelease and is released together with@openmaxai/chat-sdkunder the same version; pin an exact version. - The API may still change. Every export is marked
@experimental; names and shapes may change. @openmaxai/chat-sdkis a peer dependency. A page may hold only one copy of@openmaxai/chat-sdk; otherwiseChatProviderdoes not recognise the hosts built here.- Available: REST identity, messages, conversations, uploads and URL resolution; the realtime connection (ticket exchange, frame decoding, backoff reconnects,
reconnectedafter reconnecting); one token renewal and one re-send after a401; errors sorted into theChatSdkErrorkinds by HTTP status; reactions, edits, recalls, edit history, the change log and the read-cursor snapshot (loadReadCursors). - Only with a persisted device id: the
syncack and paging (storage: "localStorage"). - Not yet: the items listed in
KNOWN_GAPS_CHAT_OPENMAX; see Known gaps and version.
Entry points
| Entry point | What is in it | Dependencies |
|---|---|---|
@openmaxai/chat-openmax |
The adapter, the config types, the request error, the converters for the edit request body and edit history, the card verdict functions, the known gaps, the version constant | Runtime dependency @openmaxai/chat-internals, installed with this package (do not import it); it holds the OpenMax REST client and the shared strings; peers @openmaxai/chat, @openmaxai/chat-sdk, @openmaxai/chat-store, react, react-dom, react-i18next, i18next |
@openmaxai/chat-openmax/react |
The one-line createChatHost, plus the Provider, conversation scope and list hook re-exported from @openmaxai/chat-sdk/react |
peer react 19, @openmaxai/chat-sdk |
Using it in a host
One line: pass the config straight to createChatHost, and import the rest (Provider, conversation scope, list hook) from the same entry point.
host.ts
import {
createChatHost,
ChatProvider,
ConversationScope,
useChatSdkConversationList,
} from "@openmaxai/chat-openmax/react";
export const host = createChatHost({
baseUrl: "https://openmax.com",
wsUrl: "wss://openmax.com/ws", // or realtime: "off"
auth: { mode: "token", getToken: async (options) => fetchShortLivedToken(options) },
locale: "en-US",
});
To handle expired credentials yourself (send the user to sign in), build the adapter yourself and pass it to createChatHost from @openmaxai/chat-sdk/react:
host.ts
import { createOpenMaxAdapter } from "@openmaxai/chat-openmax";
import { createChatHost } from "@openmaxai/chat-sdk/react";
export const host = createChatHost({
adapter: createOpenMaxAdapter(config),
onUnauthorized: () => redirectToLogin(),
});
The two forms differ in one place only: the one-line form does not take onUnauthorized or onEvent, the { adapter } form does. Neither takes queryClient (the SDK does not use react-query, see @openmaxai/chat-sdk · When your app uses react-query). On hosts built either way, endpointUrl, authToken and clientId of inboundDelivery are an empty string, undefined and an empty string: the realtime URL, the token and the device id stay inside the adapter and are not exposed on the host.
@openmaxai/chat-openmax
The root entry point; it does not depend on React. The table lists all its exports, each linking to the page with its signature and description.
| Export | Kind | Description |
|---|---|---|
createOpenMaxAdapter |
Function | Builds the OpenMax ChatSdkAdapter |
OpenMaxChatConfig |
Interface | The config |
OpenMaxAuth |
Type | Where credentials come from; only token is implemented |
OpenMaxGetTokenOptions |
Interface | The { refresh: true } passed when getToken is asked again after a 401 |
OpenMaxToken |
Interface | A token with its expiry, which getToken may return instead of a string |
openMaxSharedRealtime |
Function | Borrows the realtime connection the host already owns, replacing the adapter's realtime |
OpenMaxFrameSource |
Interface | The host's connection: subscribe to raw frames, ask whether it is open |
OpenMaxFrameListener |
Interface | A listener of OpenMaxFrameSource |
OpenMaxSharedRealtimeOptions |
Interface | Options of openMaxSharedRealtime |
ChatSdkRequestError |
Class | A failed REST request; extends ChatSdkError |
toEditMessageContent |
Function | The body of the edit request |
OpenMaxEditMessageBody |
Interface | What toEditMessageContent returns |
toMessageEdits |
Function | Turns the items of the edit-history endpoint into ChatMessageEdit |
OpenMaxMessageEditItem |
Interface | One item of the edit-history endpoint |
classifyCardActionError |
Function | The verdict for a failed card submission |
OpenMaxCardErrorVerdict |
Interface | What classifyCardActionError returns |
OpenMaxCardErrorStage |
Type | Which hop the failure happened on |
cardStateFromSubmit |
Function | The settled record built from a submit response |
OpenMaxCardSubmitResult |
Interface | The data of the submit endpoint |
OpenMaxCardStateRecord |
Interface | What cardStateFromSubmit returns |
OpenMaxCardFormAnswerRecord |
Interface | One settled form-card answer |
formAnswersBody |
Function | The request body for form-card answers |
KNOWN_GAPS_CHAT_OPENMAX |
Constant | Known gaps that only hold for OpenMax |
CHAT_OPENMAX_VERSION |
Constant | The package version |
The signature blocks are generated from the source code; the descriptions are written by hand. The package's own test checks that neither leaves out any export.
@openmaxai/chat-openmax/react
The one-line entry point. When connecting to OpenMax, importing from here is enough.
| Export | Kind | Description |
|---|---|---|
createChatHost |
Function | Takes the config (or { adapter }) and builds a host |
OpenMaxChatConfig |
Interface | Same as in the root entry point |
OpenMaxAuth |
Type | Same as in the root entry point |
OpenMaxGetTokenOptions |
Interface | Same as in the root entry point |
OpenMaxToken |
Interface | Same as in the root entry point |
ChatSdkHost |
Type | Re-exported from @openmaxai/chat-sdk/react: what createChatHost returns |
ChatProvider |
Component | Re-exported from @openmaxai/chat-sdk/react: installs the host |
ConversationScope |
Component | Re-exported from @openmaxai/chat-sdk/react: binds attachment uploads to one conversation |
CwsChatProvider |
Component | Re-exported from @openmaxai/chat-sdk/react: old name of ChatProvider, deprecated |
CwsConversationScope |
Component | Re-exported from @openmaxai/chat-sdk/react: old name of ConversationScope, deprecated |
useChatSdkConversationList |
Hook | Re-exported from @openmaxai/chat-sdk/react: the conversation list data |
ChatSdkAdapterProfiles |
Interface | Re-exported from @openmaxai/chat-sdk/react: the adapter's profile card data |
ChatSdkProfileCardActions |
Interface | Re-exported from @openmaxai/chat-sdk/react: the profile card actions whose destination the host decides |
