@ beeper/ chat-adapter- matrix (英语)

矩阵适配器 聊天SDK它运行在Matrix同步而不是webhooks上,并与Beeper对话以及WhatsApp,Telegram,Instagram,和Signal等网络相接.

安装

需要节点.js >=22。 。 。 .

pnpm add chat @beeper/chat-adapter-matrix

使用量

createMatrixAdapter() 读取其配置时从环境变量中调用无参数.

import { Chat } from "chat";
import { createMemoryState } from "@chat-adapter/state-memory";
import { createMatrixAdapter } from "@beeper/chat-adapter-matrix";

const matrix = createMatrixAdapter();

const bot = new Chat({
  userName: process.env.MATRIX_BOT_USERNAME ?? "beeper-bot",
  state: createMemoryState(),
  adapters: { matrix },
});

bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  await thread.post(`Hi ${message.author.userName}. Mention me or run /ping.`);
});

bot.onSlashCommand("/ping", async (event) => {
  await event.channel.post("pong");
});

await bot.initialize();

聊天 SDK 概念, 如 Chat, (中文(简体) ), Thread, (中文(简体) ), Message订阅费和处理费都一样 见核心API的上游文件:

• 开始
• 使用量
• 线索、信件和频道
• 直接信件

认证

访问令牌

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
});

用户名/ 密码

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "password",
    username: process.env.MATRIX_USERNAME!,
    password: process.env.MATRIX_PASSWORD!,
    userID: process.env.MATRIX_USER_ID,
  },
});

默认

• 持续行为在Chat提供 state 适配器.
• 建议Redis或另一个耐久状态适配器重启耐久性.
• deviceID 尽可能从认证中推断出,然后从国家中再用,并且只作为最后手段产生.
• recoveryKey 允许E2EE.
• inviteAutoJoin: {} 允许邀请自动加入.

常见选项

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
  recoveryKey: process.env.MATRIX_RECOVERY_KEY,
  commandPrefix: "/",
  roomAllowlist: ["!room:beeper.com"],
  inviteAutoJoin: {
    inviterAllowlist: ["@alice:beeper.com", "@ops:beeper.com"],
  },
  matrixSDKLogLevel: "error",
});

高级调制保留代码配置 :

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
  e2ee: {
    useIndexedDB: false,
    cryptoDatabasePrefix: "beeper-matrix-bot",
  },
  persistence: {
    keyPrefix: "my-bot",
    session: {
      ttlMs: 86_400_000,
    },
    sync: {
      persistIntervalMs: 10_000,
    },
  },
});

环境变量

createMatrixAdapter() 没有参数只使用这些 env vars :

使用其中之一 MATRIX_ACCESS_TOKEN,或 MATRIX_USERNAME 加号 MATRIX_PASSWORD。 。 。 .

线索模型

• 母体室是一个Chat SDK频道.
• 上层房间信息属于频道时间表.
• 使用 Chat SDK 线程的矩阵线程响应映射 roomID + rootEventID。 。 。 .
• openDM(userId) 在可能的情况下重新使用现有的直接房间,并在需要时创建一个直接房间.

特征

持久性

为生产,将适配器与Redis等耐用Chat状态适配器配对.

import { Chat } from "chat";
import { createRedisState } from "@chat-adapter/state-redis";
import { createMatrixAdapter } from "@beeper/chat-adapter-matrix";

const matrix = createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
  recoveryKey: process.env.MATRIX_RECOVERY_KEY,
});

const bot = new Chat({
  userName: process.env.MATRIX_BOT_USERNAME ?? "beeper-bot",
  state: createRedisState({ url: process.env.REDIS_URL! }),
  adapters: { matrix },
});

持久性包括:

• 生成或推断设备ID
• 密码登录会话
• 管理部房间制图
• 矩阵同步快照
• 启用 E2EE 时的 E2EE 秘密捆绑

信件和历史 API

适配器支持:

• fetchMessage(threadId, messageId)
• fetchMessages(threadId, options)
• fetchChannelMessages(channelId, options)
• fetchThread(threadId)
• fetchChannelInfo(channelId)
• listThreads(channelId, options)
• openDM(userId)

限制

• handleWebhook() 返回时 501 因为Matrix在这里使用同步投票.
• 贺卡、模式和电文没有执行.
• 在适配器层没有实施原生流化.
• 斜线命令从纯文本消息中解析; Matrix 不提供本地斜线命令事件 .

实例

• examples/bot.ts 用于地方发展.
• examples/bot.redis.ts 使用 Redis 后置状态重新启动耐久性.
• examples/.env.example 列出所支持的env vars 实例.
• scripts/get-access-token.ts 帮助以交互方式生成比珀证书 .

关于特定版本的修改,见 变动情况。 。 。 .

许可证

麻省理工学院