使用 ProjectConnector 连接终端用户账号

当产品里的每个用户都要连接自己的 provider 账号时，使用 ProjectConnector。你的后端通过 externalUserId 标识用户，创建授权链接，保存 connected account ID，再代该用户执行 action。

这条路径使用形如 oo_proj_… 的 project API key，与 Connector 使用的个人 api_… key 相互独立。

准备 project

编写运行期流程前，先在 OOMOL Console 创建：

一个 Connector project。
用户可以连接的每个 service 对应的 provider config。
一个保存在后端密钥管理系统中的 project API key。

Connector for SaaS 使用指南包含 Console 配置步骤与对应的 REST 请求。

安装并初始化

npm install @oomol-lab/connector

import { ProjectConnector } from "@oomol-lab/connector";

const project = new ProjectConnector({
  apiKey: process.env.OOMOL_PROJECT_API_KEY!,
});

创建 OAuth 授权请求

使用业务数据库中的稳定用户 ID 作为 externalUserId：

const request = await project.connect.oauth("user_42", {
  service: "gmail",
  connectionName: "work",
  returnUri: "https://app.example.com/connected",
});

redirectUserTo(request.authorizationUrl);

用户完成授权后，等待请求进入最终状态：

const connected = await project.waitForConnection(request);

if (connected.status === "connected") {
  saveConnectedAccountId(connected.connectedAccountId);
}

project.connect.oauth 返回的是等待用户完成的授权请求。授权成功后，waitForConnection 才会在请求结果中返回 connectedAccountId。

对于 API key 和自定义凭据类型的 provider，使用 connect.apiKey 或 connect.customCredential。这两个方法会同步验证凭据并返回 connected account。

代一个用户执行 action

const result = await project.execute(
  "user_42",
  "gmail.search_threads",
  { query: "is:unread" },
  { connectedAccountId: "ca-1" },
);

已经保存 connectedAccountId 时，优先显式传入。它会选择一个确定的账号，避免依赖“最新 active 账号”。如果产品使用稳定 alias，也可以传 connectionName。

同一个请求或任务需要执行多次操作时，可以通过 forUser 绑定一次用户：

const user = project.forUser("user_42");
await user.execute("slack.post_message", {
  channel: "#general",
  text: "shipped",
});

明确产品边界

你的产品负责鉴权自己的用户，并控制用户可以使用哪些 providers 与 actions。Project API key 只保存在后端；始终传入一致的 externalUserId，并把返回的账号选择器保存到对应业务用户下。

TypeScript SDK 参考包含授权请求与 connected account 的生命周期字段、精确 action 类型、错误、重试、等待选项和完整 ProjectConnector API。