chat-agent-toolkit 1.2.72 → 1.2.74

package/src/connectors/index.ts

@@ -0,0 +1,128 @@
+/**
+ * OpenConnector Integration for OOMOL SaaS
+ *
+ * Multi-tenant connector platform for OAuth & credential management.
+ * Allows users to link external accounts (Gmail, Slack, GitHub, Airtable, etc.)
+ * securely managed by OOMOL Cloud.
+ *
+ * @module connectors
+ * @see {@link https://connector.oomol.com}
+ * @example
+ * ```ts
+ * import { ProjectConnector } from "chat-agent-toolkit/connectors";
+ *
+ * const project = new ProjectConnector({
+ *   apiKey: process.env.OOMOL_PROJECT_API_KEY,
+ * });
+ *
+ * const user = project.forUser(userId);
+ * const oauth = await user.connect.oauth({
+ *   service: "gmail",
+ *   returnUri: "https://myapp.com/oauth-callback",
+ * });
+ * ```
+ */
+
+// Re-export OOMOL Connector SDK types and classes
+export type {
+  ConnectorError as OOMOLConnectorError,
+  ProjectConnector as OOMOLProjectConnector,
+} from "@oomol-lab/connector";
+export { ConnectorError, ProjectConnector } from "@oomol-lab/connector";
+
+// Catalog data: 900+ integrated providers with OAuth/API-key support
+import catalogJson from "./catalog.json";
+import providerIndexJson from "./openconnector-providers-index.json";
+
+export type CatalogProvider = {
+  service: string;
+  displayName: string;
+  categories: string[];
+  authTypes: ("oauth2" | "api_key" | "custom_credential" | "no_auth")[];
+  actionCount: number;
+};
+
+export type ProviderIndexEntry = CatalogProvider & {
+  homepageUrl?: string;
+  actions?: string[];
+};
+
+/**
+ * Lightweight provider catalog (basic info: service, display name, auth types).
+ * ~900 providers, fast catalog search and picker UI.
+ */
+export const catalog: CatalogProvider[] = catalogJson as CatalogProvider[];
+
+/**
+ * Detailed provider index with action lists and metadata.
+ * Use for deep integration: listing available actions, mapping capabilities.
+ */
+export const providerIndex: ProviderIndexEntry[] =
+  providerIndexJson as ProviderIndexEntry[];
+
+/**
+ * Search the catalog by service name or display name.
+ * @param query Search term (case-insensitive)
+ * @param limit Max results
+ * @returns Matching providers
+ */
+export function searchCatalog(query: string, limit = 100): CatalogProvider[] {
+  const q = query.toLowerCase();
+  return catalog
+    .filter(
+      (p) =>
+        p.service.toLowerCase().includes(q) ||
+        p.displayName.toLowerCase().includes(q)
+    )
+    .slice(0, limit);
+}
+
+/**
+ * Get a provider by service ID.
+ * @param serviceId The provider's service identifier (e.g., "gmail", "slack")
+ * @returns Provider info or undefined
+ */
+export function getCatalogProvider(serviceId: string): CatalogProvider | undefined {
+  return catalog.find((p) => p.service === serviceId);
+}
+
+/**
+ * Get detailed provider info including actions.
+ * @param serviceId The provider's service identifier
+ * @returns Detailed provider entry or undefined
+ */
+export function getProviderDetails(serviceId: string): ProviderIndexEntry | undefined {
+  return providerIndex.find((p) => p.service === serviceId);
+}
+
+/**
+ * Filter catalog by authentication type.
+ * @param authType The auth type to filter by
+ * @returns Providers supporting this auth type
+ */
+export function getCatalogByAuthType(
+  authType: "oauth2" | "api_key" | "custom_credential" | "no_auth"
+): CatalogProvider[] {
+  return catalog.filter((p) => p.authTypes.includes(authType));
+}
+
+/**
+ * Filter catalog by category.
+ * @param category The category to filter by (e.g., "Communication", "Productivity")
+ * @returns Providers in this category
+ */
+export function getCatalogByCategory(category: string): CatalogProvider[] {
+  return catalog.filter((p) => p.categories.includes(category));
+}
+
+/**
+ * Get all unique categories in the catalog.
+ * @returns Sorted list of category names
+ */
+export function getCatalogCategories(): string[] {
+  const categories = new Set<string>();
+  catalog.forEach((p) => p.categories.forEach((c) => categories.add(c)));
+  return Array.from(categories).sort();
+}
+
+export type { Express } from "express";

package/src/connectors/oomol-saas-server.js

@@ -0,0 +1,125 @@
+/**
+ * Multi-tenant connector server on OOMOL Cloud (https://connector.oomol.com/v1).
+ *
+ * OOMOL hosts everything: OAuth apps, credential vault, token refresh, provider calls.
+ * Each of YOUR app's users links THEIR OWN accounts (Gmail, Slack, GitHub, ...) via
+ * ProjectConnector — the composio/pipedream "managed auth" model.
+ *
+ * Setup:
+ *   1. Create a project in the OOMOL console and copy its API key (oo_proj_...).
+ *   2. OOMOL_PROJECT_API_KEY=oo_proj_... npm start
+ *
+ * externalUserId = your app's own user id (from your auth/session layer). NEVER let the
+ * client pick another user's id — derive it server-side from the authenticated session.
+ */
+import express from "express";
+import { readFile } from "node:fs/promises";
+import { ConnectorError, ProjectConnector } from "@oomol-lab/connector";
+
+const PORT = process.env.PORT ?? 8787;
+const APP_ORIGIN = process.env.APP_ORIGIN ?? `http://localhost:${PORT}`;
+
+const project = new ProjectConnector({
+  apiKey: process.env.OOMOL_PROJECT_API_KEY ?? "oo_proj_missing",
+  // baseUrl defaults to OOMOL Cloud: https://connector.oomol.com/v1
+});
+
+const catalog = JSON.parse(await readFile(new URL("./catalog.json", import.meta.url), "utf8"));
+const byService = new Map(catalog.map((p) => [p.service, p]));
+
+const app = express();
+app.use(express.json());
+
+// DEMO ONLY: replace with your real session auth. Everything below trusts req.userId.
+app.use((req, _res, next) => {
+  req.userId = req.get("x-user-id") ?? "demo_user";
+  next();
+});
+
+/** Provider catalog for your "add a connection" picker. */
+app.get("/api/catalog", (req, res) => {
+  const q = (req.query.q ?? "").toString().toLowerCase();
+  const list = q
+    ? catalog.filter((p) => p.service.includes(q) || p.displayName.toLowerCase().includes(q))
+    : catalog;
+  res.json(list.slice(0, Number(req.query.limit ?? 100)));
+});
+
+/**
+ * Start a connection for the logged-in user.
+ * OAuth providers  -> returns { authorizationUrl, requestId } — redirect the user there.
+ * API-key/custom   -> pass { apiKey } or { values } — connects synchronously.
+ */
+app.post("/api/connections", async (req, res) => {
+  const { service, connectionName, apiKey, values } = req.body ?? {};
+  const provider = byService.get(service);
+  if (!provider) return res.status(404).json({ error: "unknown_service", service });
+
+  const user = project.forUser(req.userId);
+  try {
+    if (provider.authTypes.includes("oauth2") && !apiKey && !values) {
+      const request = await user.connect.oauth({
+        service,
+        connectionName,
+        returnUri: `${APP_ORIGIN}/connected?service=${encodeURIComponent(service)}`,
+      });
+      // Redirect your user to authorizationUrl; poll GET /api/connections/requests/:id after.
+      return res.json({
+        pending: true,
+        requestId: request.id,
+        authorizationUrl: request.authorizationUrl,
+        status: request.status,
+      });
+    }
+    const account = apiKey
+      ? await user.connect.apiKey({ service, apiKey, connectionName })
+      : await user.connect.customCredential({ service, values: values ?? {}, connectionName });
+    return res.json({
+      pending: false,
+      connectedAccountId: account.connectedAccountId,
+      status: account.status,
+      available: account.available,
+    });
+  } catch (err) {
+    return sendConnectorError(res, err);
+  }
+});
+
+/** Poll an OAuth connection request until the user finishes authorizing. */
+app.get("/api/connections/requests/:id", async (req, res) => {
+  try {
+    const request = await project.getConnectionRequest(req.params.id);
+    res.json(request); // status: initiated | connected | failed | expired
+  } catch (err) {
+    sendConnectorError(res, err);
+  }
+});
+
+/** Run any catalog action as the logged-in user (e.g. "gmail.search_threads"). */
+app.post("/api/actions/:actionId", async (req, res) => {
+  const { input = {}, connectionName } = req.body ?? {};
+  try {
+    const out = await project
+      .forUser(req.userId)
+      .executeRaw(req.params.actionId, input, connectionName ? { connectionName } : undefined);
+    res.json(out); // { data, executionId, actionId, message }
+  } catch (err) {
+    sendConnectorError(res, err);
+  }
+});
+
+/** Landing page OOMOL returns the user to after OAuth consent. */
+app.get("/connected", (req, res) => {
+  res.send(`<p>${req.query.service ?? "Account"} connected — you can close this tab.</p>`);
+});
+
+function sendConnectorError(res, err) {
+  if (err instanceof ConnectorError) {
+    // e.g. provider_config_not_found, connection_alias_conflict, app_not_ready, client_wait_timeout
+    return res.status(err.status || 502).json({ error: err.code, message: err.message });
+  }
+  console.error(err);
+  return res.status(500).json({ error: "internal_error" });
+}
+
+app.listen(PORT, () => console.log(`OOMOL SaaS connector server on :${PORT} (gateway: connector.oomol.com)`));