Version and known gaps
CHAT_OPENMAX_VERSION and KNOWN_GAPS_CHAT_OPENMAX, the known gaps that apply to OpenMax only.
Version and known gaps
Known gaps that only hold for OpenMax, and the package version. Gaps that have nothing to do with the backend are in KNOWN_GAPS_CHAT_SDK of @openmaxai/chat-sdk. Status and an index of every export are on the Overview.
KNOWN_GAPS_CHAT_OPENMAX
const KNOWN_GAPS_CHAT_OPENMAX: readonly string[];
Known unhandled cases, in array order:
- The
syncack (POST /api/v1/sync/ack) is sent only when the device id is persisted:storageis"localStorage"and the id reads back after it is written. With the default"memory", or when storage is unavailable or does not read back, there is no ack and no paging, so the server keeps no cursor for this device and every connect replays the oldest 100 events of the inbox (withhas_more). That number is fixed and does not grow, but every connect brings an extra batch ofmessagessignals; unread counts are not affected. A persisted id can still expire: a Safari private window clears it on close, storage written by script in a cross-site iframe lasts at most 7 days (ITP), and users can clear site data. Each of these leaves one more inactive cursor row on the server (the server does not clean up cursors and they have no TTL). The ack needs themessages:read_state:writescope and paging needsmessages:sync:read(thechatpreset has both); an API key with hand-picked scopes that lacks them gets403, which the package swallows, falling back to no ack. A new device starts fromseq0, at most 600 events per connect (1 frame plus 5 pages), so a large inbox takes several connects to catch up. - With the default host, the attachment PUT goes straight to the
upload_urlreturned by prepare; the SDK does not proxy it. Whether CORS blocks this step whenupload_urland the embedding page are cross-origin has not been measured. - With the default host, attachment upload works only inside
<ConversationScope conversationId>: when a conversation view is not wrapped in it, there is no attachment button (limitsreturns 0) andattachments.startrejects. Whether to wrap is up to you; the SDK cannot tell that a view was meant to be a conversation. - When the embedding page and
baseUrlare cross-origin, every REST request carriesAuthorization(token mode), so the browser sends a CORS preflight (OPTIONS) first. If the server blocksOPTIONS, evenGET /api/v1/mefails, independent of uploads, so a cross-origin setup needs CORS allowed for the whole API, not only fordevice_id. - Received attachment URLs (
download_urlfromresolveUrls) are handed over as they are; the SDK does not proxy them. Whether images and previews show whendownload_urland the embedding page are cross-origin has not been measured. - The realtime
message.updatedframe carries no body, so the message area fetches the message by id each time (GET …/conversations/{cid}/messages/{mid}). The server pushes your own edits back to you (including the device that made the edit), so each of your own edits costs one extra fetch too; the fetch happens before the store de-duplicates bychange_seq, so it remains even with the change log connected. - The edit request carries only
content: no structured @mentions (neither the contract nor the backend edit endpoint has them), and notypeorfallback_text; after an image message is edited into plain text, the message'stypeand the preview text in the conversation list stay as they were. - The one-line form (
createChatHost(config)in@openmaxai/chat-openmax/react) does not takeonUnauthorized: the type rejects it, and passing it in JavaScript throwsChatSdkConfigErrorwhen the host is built. When the credentials become invalid (after a401the token is renewed once throughgetToken({ refresh: true })and the retry still fails; a renewal that fails because of the network is anetworkerror and calls no callback), calls still throwChatSdkRequestErrorwith kindunauthorizedand realtime stops reconnecting. The SDK shows "session expired" once throughattention.notify(there is no signed-out UI state, and when the host has not wiredattentionthe user sees nothing), and the integrator gets no callback to send the user to sign in. For a callback, use the{ adapter }form; see React entry point. - The one-line form does not take
onEventeither (passing it throwsChatSdkConfigErrorat host creation), so a host built that way has no event outlet andemitin message-display plugins does nothing. To receive events, use the{ adapter }form. - The one-line form does not take
cardseither (passing it throwsChatSdkConfigErrorat host creation), so a host built that way never draws business-card buttons (there is nowhere to say which business operations are allowed). For card capabilities, usecreateChatHost({ adapter: createOpenMaxAdapter(config), cards: { isOperationAllowed } }). - The one-line form does not take
profileCardActionseither (passing it throwsChatSdkConfigErrorat host creation), so a host built that way has no profile card (message avatars and the DM header's avatar and name are not clickable). For profile cards, use the{ adapter }form and passprofileCardActionsthere. - In a conversation with read receipts off (
GET …/read-cursorsanswers412; the server enables receipts only for DM and GROUP), every time the conversation opens one request is sent that is bound to be refused: the package does not read the conversation'sread_receipt_modefirst (conversation list rows don't carry it). The refusal draws no receipt and shows no error; it only costs a round trip. A real conversation with receipts off has not been measured on a real backend (only with the endpoint stubbed to answer412). If receipts are turned off at runtime (the organization-level switch), the snapshot already fetched keeps being drawn until the host's read-cursor block is cleared, the host is rebuilt (createChatHostcalled again) or the page reloads; reopening the conversation in the meantime does not clear it. The block is cleared only when the adapter'ssessionreports that the scope has ended (an organization switch, removal or sign-out), and this package's adapter does not providesession(seecreateOpenMaxAdapter). So with the one-line form, or with the{ adapter }form when the application has not added asessionto the adapter itself, an organization switch, removal or sign-out does not clear it; the snapshot stays until the host is rebuilt or the page reloads. #work-item candidates (workItems.search) fetch one page only:GET /api/v1/work-referencesis called withlimit=50(the server's maximum) and the backend has no cursor, so past 50 projects or matches the rest are not shown; a query longer than 100 characters gets422from the server, which throwsChatSdkRequestErrorand the composer shows no panel.- Agent runs (factory option
agentActivity, on by default; read-only progress (experimental · transitional), replaced when the planned Agent runs capability lands):agent_activityframes arrive only while the realtime connection is up, and the server does not persist, replay or snapshot them, so frames during a disconnect or before connecting are lost and opening a conversation does not fetch runs in progress; with the feature switched off on the backend there are no frames andagent_runis stripped from replies, so nothing shows even with the option on; frames are fanned out per connection, so each open connection receives its own copy. Receiving frames over the SDK's connection has not been measured on a real backend. - When the server closes the realtime connection with close code
4007(credential_revoked), it is treated as invalid credentials and not reconnected. The server sends4007on connections opened with a short-lived token when the Key is revoked, rotated or all Keys are revoked, and when the user is removed from that organization; when the token expires it sends4003instead, and the SDK backs off and reconnects as usual, renewing the token once when the ticket request gets401. After the Key is revoked, rotated or all Keys are revoked, the server sends4007on open connections within about 1 second. Removal from the organization also uses4007, so realtime reportsunauthorized(callsonUnauthorized, or shows "session expired" without it), while REST answers the same situation with403AUTH_ORG_MEMBERSHIP_REQUIRED(forbidden): the two sides disagree on the kind. Receiving4007or4003over the SDK's connection has not been measured on a real backend. - After the ticket request is refused (
403, for example a personal API Key without the permission to get a ticket), realtime stops and reportsforbiddenonce throughsink.error; but the SDK shows nothing for a connection given up withforbidden(noonUnauthorized, noattentionnotice, and the connection status bar is still planned), so the UI does not show that realtime has stopped and new messages from others appear only after a reload. To find out, wrapadapter.realtime.connectyourself and catchsink.error.
Each item in the array is an English sentence and can be shown on a page as is.
CHAT_OPENMAX_VERSION
const CHAT_OPENMAX_VERSION: string;
The package version, the same value as CHAT_SDK_VERSION in @openmaxai/chat-sdk: the two packages share one version number.
In a package installed from npm it equals that package's version in its package.json (written in at pack time). In a source checkout or an unpacked build it is a development placeholder that matches no published version. The type is string, not a literal type.
