Call connected Apps with the SDK

Use Connector when backend code needs to call Apps connected to your own OOMOL account. This path uses the hosted OOMOL Connector gateway and a personal API key shaped like api_….

Install the SDK

npm install @oomol-lab/connector

The SDK requires Node 18 or later. It also runs in other environments that provide standard fetch and AbortController APIs, but the personal API key must remain in a trusted backend environment.

Create a personal API key

Create a key in OOMOL Console, then store it as a backend secret:

export OOMOL_API_KEY=api_...

Do not place this key in a browser bundle, mobile client, public repository, prompt, or client-side log.

Execute the first action

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

const oomol = new Connector({ apiKey: process.env.OOMOL_API_KEY! });

const result = await oomol.execute("gmail.search_threads", {
  query: "is:unread",
});

The namespace form executes the same action:

const result = await oomol.gmail.search_threads({ query: "is:unread" });

Use executeRaw when you also need executionId, actionId, and the response message for logs or support.

Select a connected account

When the same provider has multiple connections, select one with connectionName:

await oomol.execute(
  "gmail.search_threads",
  { query: "from:ceo" },
  { connectionName: "work" },
);

Use oomol.apps.list() to inspect the connections available to the current OOMOL account. Connection creation and removal remain in OOMOL Console.

Discover actions

Use the catalog to inspect providers, actions, and their runtime schemas:

const providers = await oomol.catalog.providers({ q: "mail" });
const actions = await oomol.catalog.actions("gmail");
const action = await oomol.catalog.action("gmail.search_threads");

When an upstream endpoint does not have a modeled action, use proxy to call it through the selected connection.

Continue with the reference

See the TypeScript SDK reference for precise action types, configuration precedence, retries, timeouts, cancellation, proxy behavior, errors, and the complete Connector API.

Use ProjectConnector instead when each user of your product must connect a separate account.