概览
OpenMax 适配器包 @openmaxai/chat-openmax 的概览:状态、两个入口、怎么接,以及全部导出的索引。
概览
@openmaxai/chat-openmax 把 @openmaxai/chat-sdk 接到 OpenMax 后端:REST 客户端、令牌、实时连接(换票、帧解码、退避重连)、设备标识、附件上传通道与地址换算,都在这个包里。它对外给一个适配器 createOpenMaxAdapter,和一个一行接好的 createChatHost。通用部分(宿主怎么组装、适配器接口、错误模型、组件)见 @openmaxai/chat-sdk。
这一组页面按包里现有的源码写,是这个包自己的接口参考:本页是概览(状态、入口、在宿主里怎么接、全部导出的索引),每个导出的签名和说明分在下面六页。一步步接入见接入 OpenMax。
本节内容
- 适配器:
createOpenMaxAdapter和它的构造参数OpenMaxChatConfig、凭据OpenMaxAuth、getToken的提示OpenMaxGetTokenOptions、带到期时间的令牌OpenMaxToken,以及适配器每个成员打哪些接口;宿主已有自己的实时连接时借用它的openMaxSharedRealtime。 - 错误:
ChatSdkRequestError,HTTP 状态怎么映射成错误种类,401之后怎么续期。 - React 入口:
@openmaxai/chat-openmax/react的createChatHost,以及从@openmaxai/chat-sdk/react再导出的 Provider 和列表 hook。 - 消息接口:表态、编辑、撤回、修订历史、改动日志打的接口,实时帧怎么翻成信号,以及自己写宿主时可复用的
toEditMessageContent、toMessageEdits。 - 卡片判决:卡片提交失败怎么判(
classifyCardActionError)、成功的返回怎么拼成落定记录(cardStateFromSubmit)、表单卡答案的请求体(formAnswersBody)。 - 已知缺口与版本:
KNOWN_GAPS_CHAT_OPENMAX、CHAT_OPENMAX_VERSION。
状态
- 已作为预发布版本发布。 本包以
3.0.0预发布版本发布在 npm 上,与@openmaxai/chat-sdk用同一个版本号一起发布;要锁定确切版本号。 - API 还可能变。 所有导出都标
@experimental,名字和形状都可能调整。 @openmaxai/chat-sdk是 peer 依赖。 页面里只能有一份@openmaxai/chat-sdk,ChatProvider才认得这里造的宿主。- 已有: REST 的身份、消息、会话、上传与地址换算,实时连接(换票、帧解码、断线退避重连、重连后发
reconnected),401之后续一次令牌、重发一次,错误按 HTTP 状态归成ChatSdkError的种类,表态、编辑、撤回、修订历史、改动日志,已读游标快照(loadReadCursors)。 - 只在设备标识持久时有:
sync回执与翻页(storage: "localStorage")。 - 还没有:
KNOWN_GAPS_CHAT_OPENMAX列出的各条,见已知缺口与版本。
入口
| 入口 | 里面有什么 | 依赖 |
|---|---|---|
@openmaxai/chat-openmax |
适配器、构造参数类型、请求错误、编辑请求体与修订历史的转换函数、卡片判决函数、已知缺口、版本常量 | 运行期依赖 @openmaxai/chat-internals,随本包安装(不要直接 import);OpenMax REST 客户端和共用文案都在它里面;peer @openmaxai/chat、@openmaxai/chat-sdk、@openmaxai/chat-store、react、react-dom、react-i18next、i18next |
@openmaxai/chat-openmax/react |
一行接好的 createChatHost,再导出 @openmaxai/chat-sdk/react 的 Provider、会话面和列表 hook |
peer react 19、@openmaxai/chat-sdk |
在宿主里怎么用
一行接好:构造参数直接交给 createChatHost,其余(Provider、会话面、列表 hook)也从这一个入口引入。
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", // 或 realtime: "off"
auth: { mode: "token", getToken: async (options) => fetchShortLivedToken(options) },
locale: "zh-CN",
});
要在凭据彻底失效时自己处理(跳登录页),自己造适配器,再交给 @openmaxai/chat-sdk/react 的 createChatHost:
host.ts
import { createOpenMaxAdapter } from "@openmaxai/chat-openmax";
import { createChatHost } from "@openmaxai/chat-sdk/react";
export const host = createChatHost({
adapter: createOpenMaxAdapter(config),
onUnauthorized: () => redirectToLogin(),
});
两种写法的差别只有一处:一行写法不收 onUnauthorized 与 onEvent,{ adapter } 写法收。两种写法都不收 queryClient(SDK 不用 react-query,见 @openmaxai/chat-sdk · 应用自己用 react-query)。两种写法造的宿主上,inboundDelivery 的 endpointUrl、authToken、clientId 都是空串、undefined、空串:实时地址、令牌、设备标识只在适配器里,不经宿主外露。
@openmaxai/chat-openmax
根入口,不依赖 React。下表是它的全部导出,链接指向写着签名和说明的那一页。
| 导出 | 种类 | 说明 |
|---|---|---|
createOpenMaxAdapter |
函数 | 造 OpenMax 的 ChatSdkAdapter |
OpenMaxChatConfig |
接口 | 构造参数 |
OpenMaxAuth |
类型 | 凭据来源,只实现了 token |
OpenMaxGetTokenOptions |
接口 | 401 之后再问 getToken 时带的 { refresh: true } |
OpenMaxToken |
接口 | 带到期时间的令牌,getToken 可以回它代替字符串 |
openMaxSharedRealtime |
函数 | 借用宿主自己那条实时连接,替换适配器的 realtime |
OpenMaxFrameSource |
接口 | 宿主那条连接:订阅原始帧、问开着没有 |
OpenMaxFrameListener |
接口 | OpenMaxFrameSource 的订阅者 |
OpenMaxSharedRealtimeOptions |
接口 | openMaxSharedRealtime 的可选参数 |
ChatSdkRequestError |
类 | 一次 REST 请求失败;extends ChatSdkError |
toEditMessageContent |
函数 | 编辑接口的请求体 |
OpenMaxEditMessageBody |
接口 | toEditMessageContent 的返回值 |
toMessageEdits |
函数 | 修订历史接口的 items 转成 ChatMessageEdit |
OpenMaxMessageEditItem |
接口 | 修订历史接口的一项 |
classifyCardActionError |
函数 | 卡片提交失败的判决 |
OpenMaxCardErrorVerdict |
接口 | classifyCardActionError 的返回值 |
OpenMaxCardErrorStage |
类型 | 失败发生在哪一跳 |
cardStateFromSubmit |
函数 | 用提交返回拼落定记录 |
OpenMaxCardSubmitResult |
接口 | 提交接口返回的 data |
OpenMaxCardStateRecord |
接口 | cardStateFromSubmit 的返回值 |
OpenMaxCardFormAnswerRecord |
接口 | 表单卡一道题的落定答案 |
formAnswersBody |
函数 | 表单卡答案的请求体 |
KNOWN_GAPS_CHAT_OPENMAX |
常量 | 只对 OpenMax 成立的已知缺口 |
CHAT_OPENMAX_VERSION |
常量 | 包的版本 |
签名块从源码生成,说明是手写的;包内测试检查两者都没落下任何导出。
@openmaxai/chat-openmax/react
一行入口。接 OpenMax 时只从这里引入就够了。
| 导出 | 种类 | 说明 |
|---|---|---|
createChatHost |
函数 | 收构造参数(或 { adapter }),造一个宿主 |
OpenMaxChatConfig |
接口 | 同根入口 |
OpenMaxAuth |
类型 | 同根入口 |
OpenMaxGetTokenOptions |
接口 | 同根入口 |
OpenMaxToken |
接口 | 同根入口 |
ChatSdkHost |
类型 | 从 @openmaxai/chat-sdk/react 再导出:createChatHost 的返回值 |
ChatProvider |
组件 | 从 @openmaxai/chat-sdk/react 再导出:安装宿主 |
ConversationScope |
组件 | 从 @openmaxai/chat-sdk/react 再导出:把附件上传绑到一条会话 |
CwsChatProvider |
组件 | 从 @openmaxai/chat-sdk/react 再导出:ChatProvider 的旧名,已弃用 |
CwsConversationScope |
组件 | 从 @openmaxai/chat-sdk/react 再导出:ConversationScope 的旧名,已弃用 |
useChatSdkConversationList |
hook | 从 @openmaxai/chat-sdk/react 再导出:会话列表的数据 |
ChatSdkAdapterProfiles |
接口 | 从 @openmaxai/chat-sdk/react 再导出:适配器上名片的取数 |
ChatSdkProfileCardActions |
接口 | 从 @openmaxai/chat-sdk/react 再导出:名片上由宿主决定去向的动作 |
