Подключение аккаунтов конечных пользователей с ProjectConnector

Используйте ProjectConnector, когда каждому пользователю продукта нужно подключить собственный аккаунт провайдера. Backend идентифицирует каждого пользователя по externalUserId, создаёт authorization links, хранит ID подключённых аккаунтов и выполняет actions для этого пользователя.

Этот путь использует project API key вида oo_proj_…. Он отличается от personal key api_…, который используется с Connector.

Подготовьте project

Перед реализацией runtime flow создайте в OOMOL Console следующие ресурсы:

1. Project Connector.
2. Provider config для каждого сервиса, доступного пользователям.
3. Project API key, сохранённый в менеджере секретов backend.

В руководстве 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 и custom credential используйте connect.apiKey или connect.customCredential. Эти методы проверяют credential и синхронно возвращают подключённый аккаунт.

Выполните action для одного пользователя

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

Передавайте connectedAccountId, когда он известен. Он выбирает конкретный аккаунт и не зависит от последнего активного аккаунта. Если продукт использует стабильные aliases, доступен connectionName.

Если несколько операций относятся к одному запросу или job, один раз привяжите пользователя с помощью forUser:

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

Сохраняйте явные границы продукта

Ваш продукт аутентифицирует собственных пользователей и контролирует доступные им провайдеры и actions. Храните project API key на backend, передавайте постоянный externalUserId и сохраняйте полученный selector аккаунта рядом с соответствующим пользователем продукта.

В справочнике TypeScript SDK описаны поля жизненного цикла authorization requests и connected accounts, точные типы actions, ошибки, повторные попытки, параметры ожидания и полный API ProjectConnector.