OpenMax
Free Trial

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: createOpenMaxAdapter with its config OpenMaxChatConfig, the credentials OpenMaxAuth, the getToken hint OpenMaxGetTokenOptions and the token-with-expiry OpenMaxToken, plus which endpoints each adapter member calls; openMaxSharedRealtime for borrowing a realtime connection the host already owns.
  • Errors: ChatSdkRequestError, how HTTP statuses map to error kinds, and how the token is renewed after a 401.
  • React entry point: createChatHost in @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 toEditMessageContent and toMessageEdits, 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.0 prerelease and is released together with @openmaxai/chat-sdk under the same version; pin an exact version.
  • The API may still change. Every export is marked @experimental; names and shapes may change.
  • @openmaxai/chat-sdk is a peer dependency. A page may hold only one copy of @openmaxai/chat-sdk; otherwise ChatProvider does not recognise the hosts built here.
  • Available: REST identity, messages, conversations, uploads and URL resolution; the realtime connection (ticket exchange, frame decoding, backoff reconnects, reconnected after reconnecting); one token renewal and one re-send after a 401; errors sorted into the ChatSdkError kinds by HTTP status; reactions, edits, recalls, edit history, the change log and the read-cursor snapshot (loadReadCursors).
  • Only with a persisted device id: the sync ack 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