使用 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 綁定一次使用者：

Slack 範例要求該使用者已有名為「work」的連線。請使用後端為該 Slack 帳號儲存的連線名稱。forUser 只綁定使用者；帳號選擇器應傳入 execute 的選項。

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

明確產品邊界

你的產品負責鑑權自己的使用者，並控制使用者可以使用哪些 providers 與 actions。Project API key 只儲存在後端；始終傳入一致的 externalUserId，並把返回的帳號選擇器儲存到對應業務使用者下。

TypeScript SDK 參考包含授權請求與 connected account 的生命週期欄位、精確 action 類型、錯誤、重試、等待選項和完整 ProjectConnector API。