ProjectConnector로 최종 사용자 계정 연결하기

제품의 모든 사용자가 각자의 제공자 계정을 연결해야 할 때 ProjectConnector을 사용하세요. 백엔드는 externalUserId로 각 사용자를 식별하고, 인증 링크를 생성하며, 연결된 계정 ID를 저장하고, 해당 사용자를 위해 작업을 실행합니다.

이 경로는 oo_proj_… 형태의 프로젝트 API 키를 사용합니다. Connector에서 사용하는 개인 api_… 키와는 별개입니다.

프로젝트 준비하기

런타임 흐름을 작성하기 전에 OOMOL Console에서 다음 리소스를 생성하세요:

Connector 프로젝트.
사용자가 연결할 수 있는 각 서비스에 대한 제공자 구성.
백엔드 시크릿 관리자에 저장된 프로젝트 API 키.

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 키 및 사용자 지정 자격 증명 제공자의 경우 connect.apiKey 또는 connect.customCredential를 사용하세요. 이 메서드들은 자격 증명을 검증하고 연결된 계정을 동기적으로 반환합니다.

한 사용자를 위해 실행하기

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

connectedAccountId이 있으면 전달하세요. 특정 계정 하나를 선택하고 최신 활성 계정에 의존하지 않도록 합니다. 제품에서 안정적인 별칭을 사용하는 경우에는 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" },
);

제품 경계를 명확히 유지하기

제품은 자체 사용자를 인증하고 사용자가 사용할 수 있는 제공자와 작업을 제어합니다. 프로젝트 API 키는 백엔드에 보관하고, 일관된 externalUserId을 전달하며, 반환된 계정 선택자를 해당 제품 사용자 옆에 저장하세요.

인증 요청 및 연결된 계정 수명 주기 필드, 정확한 작업 유형, 오류, 재시도, 대기 옵션, 그리고 전체 ProjectConnector API는 TypeScript SDK 레퍼런스를 참조하세요.