Connecter les comptes des utilisateurs finaux avec ProjectConnector

Utilisez ProjectConnector lorsque chaque utilisateur de votre produit doit connecter son propre compte fournisseur. Votre backend identifie chaque utilisateur avec externalUserId, crée des liens d’autorisation, stocke les ID des comptes connectés et exécute les opérations pour cet utilisateur.

Ce parcours utilise une clé API de projet au format oo_proj_…. Elle est distincte de la clé personnelle api_… utilisée par Connector.

Préparer le projet

Avant d’écrire le flux runtime, créez ces ressources dans OOMOL Console :

1. Un projet Connector.
2. Une configuration de fournisseur pour chaque service que les utilisateurs peuvent connecter.
3. Une clé API de projet stockée dans le gestionnaire de secrets de votre backend.

Le guide Connector for SaaS couvre la configuration de Console et les requêtes REST correspondantes.

Installer et initialiser

npm install @oomol-lab/connector

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

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

Créer une demande d’autorisation OAuth

Utilisez un ID stable provenant de votre propre base de données utilisateur comme externalUserId :

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

redirectUserTo(request.authorizationUrl);

Après l’autorisation par l’utilisateur, attendez que la demande atteigne un état final :

const connected = await project.waitForConnection(request);

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

project.connect.oauth renvoie une demande d’autorisation qui attend l’utilisateur. Ce n’est qu’après une autorisation réussie que waitForConnection renvoie un connectedAccountId dans le résultat de la demande.

Pour les fournisseurs utilisant une clé API ou des identifiants personnalisés, utilisez connect.apiKey ou connect.customCredential. Ces méthodes valident les identifiants et renvoient un compte connecté de manière synchrone.

Exécuter une opération pour un utilisateur

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

Transmettez connectedAccountId lorsque vous le possédez. Il sélectionne un compte précis et évite de dépendre du dernier compte actif. connectionName reste disponible si votre produit utilise des alias stables.

Liez une fois l’utilisateur avec forUser lorsque plusieurs opérations appartiennent à la même requête ou au même job :

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

Maintenir des limites de produit explicites

Votre produit authentifie ses propres utilisateurs et contrôle les fournisseurs et les opérations qu’ils peuvent utiliser. Conservez la clé API du projet sur le backend, transmettez un externalUserId cohérent et stockez le sélecteur de compte renvoyé avec l’utilisateur correspondant de votre produit.

Consultez la référence du SDK TypeScript pour les champs de cycle de vie des demandes d’autorisation et des comptes connectés, les types précis des opérations, les erreurs, les nouvelles tentatives, les options d’attente et l’API ProjectConnector complète.