ProjectConnector で end-user accounts を接続する

product のすべての user が自分の provider account を接続する必要がある場合は、ProjectConnector を使用します。backend は各 user を externalUserId で識別し、authorization links を作成し、connected account IDs を保存して、その user の actions を実行します。

この方法では、oo_proj_… 形式の project API key を使います。Connector が使用する personal api_… key とは別のものです。

project を準備する

runtime flow を実装する前に、OOMOL Console で次の resources を作成します。

Connector project。
users が接続できる service ごとの provider config。
backend secret manager に保存する project API key。

Connector for SaaS ガイドでは、Console の設定と対応する REST requests を説明しています。

インストールと初期化

npm install @oomol-lab/connector

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

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

OAuth authorization request を作成する

自分の user database にある安定した ID を externalUserId として使用します。

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

redirectUserTo(request.authorizationUrl);

user が認証した後、request が final state になるまで待ちます。

const connected = await project.waitForConnection(request);

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

project.connect.oauth は、user の操作を待つ authorization request を返します。認証が成功した後にだけ、waitForConnection が request result 内の connectedAccountId を返します。

API-key provider と custom-credential provider には、connect.apiKey または connect.customCredential を使用します。これらの method は credential を検証し、connected account を同期的に返します。

1 人の user として実行する

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

取得済みの場合は connectedAccountId を渡してください。特定の account を選択でき、最新の active account に依存せずに済みます。product が安定した aliases を使用する場合は、connectionName も利用できます。

同じ request または job に複数の操作が含まれる場合は、forUser で user を一度 bind します。

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

product boundaries を明確に保つ

product は自分の users を認証し、利用できる providers と actions を管理します。project API key は backend に保管し、一貫した externalUserId を渡し、返された account selector を対応する product user と一緒に保存してください。

authorization-request と connected-account の lifecycle fields、action ごとの precise types、errors、retries、waiting options、完全な ProjectConnector API については、TypeScript SDK referenceを参照してください。