OpenMax
免费试用

概览

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 再导出:名片上由宿主决定去向的动作