Conecta cuentas de usuario final con ProjectConnector

Usa ProjectConnector cuando cada usuario de tu producto necesita conectar su propia cuenta de proveedor. Tu backend identifica a cada usuario con externalUserId, crea enlaces de autorización, almacena los IDs de cuentas conectadas y ejecuta acciones para ese usuario.

Esta ruta usa una clave de API de proyecto con el formato oo_proj_…. Es independiente de la clave personal api_… que usa Connector.

Prepara el proyecto

Antes de escribir el flujo de ejecución, crea estos recursos en OOMOL Console:

1. Un proyecto de Connector.
2. Una configuración de proveedor para cada servicio que los usuarios puedan conectar.
3. Una clave de API de proyecto almacenada en el gestor de secretos de tu backend.

La guía de Connector for SaaS cubre la configuración en Console y las solicitudes REST correspondientes.

Instala e inicializa

npm install @oomol-lab/connector

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

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

Crea una solicitud de autorización OAuth

Usa un ID estable de tu propia base de datos de usuarios como externalUserId:

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

redirectUserTo(request.authorizationUrl);

Después de que el usuario autorice, espera a que la solicitud alcance un estado final:

const connected = await project.waitForConnection(request);

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

project.connect.oauth devuelve una solicitud de autorización que espera al usuario. Solo después de que la autorización se realice correctamente, waitForConnection devuelve un connectedAccountId en el resultado de la solicitud.

Para proveedores con clave de API y credenciales personalizadas, usa connect.apiKey o connect.customCredential. Estos métodos validan la credencial y devuelven una cuenta conectada de forma síncrona.

Ejecuta para un usuario

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

Pasa connectedAccountId cuando lo tengas. Selecciona una cuenta específica y evita depender de la última cuenta activa. connectionName está disponible cuando tu producto usa alias estables en su lugar.

Vincula al usuario una vez con forUser cuando varias operaciones pertenezcan a la misma solicitud o trabajo:

El ejemplo de Slack requiere una conexión existente llamada “work” para este usuario. Usa el nombre de conexión que tu backend guardó para esa cuenta de Slack. forUser solo vincula al usuario; el selector de cuenta se pasa en las opciones de execute.

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

Mantén explícitos los límites del producto

Tu producto autentica a sus propios usuarios y controla qué proveedores y acciones pueden usar. Mantén la clave de API de proyecto en el backend, pasa un externalUserId consistente y almacena el selector de cuenta devuelto junto al usuario del producto correspondiente.

Consulta la referencia del SDK de TypeScript para los campos del ciclo de vida de solicitudes de autorización y cuentas conectadas, tipos de acciones precisos, errores, reintentos, opciones de espera y la API completa de ProjectConnector.