Connection

A lazy reference to the connection called name in the current (or given) user. With createIfMissing it's created on first use, for integration: holding data when given (a key you hold), pending with a connect link otherwise. An existing connection is used as it is. Given integration, operations(), operation() and events() read the catalog without loading or creating the connection.

A lazy reference by NoClick id; credential:<id> for an account connected in the app.

Create a connection called name (unique per user; a duplicate throws Conflict with existingId). With data it holds that credential at once; without, it's pending and connectUrl is where someone connects it.

The connection with this id or name.

The current user's connections (the account's own outside asUser), or those userFilter covers: named ones newest first, then, in the account's own scope, the accounts connected in the app. origin keeps only "api" or "app" ones.

const fromTheApp = await Connection.list({ origin: "app" });

One page of connections; pass nextCursor back as cursor.

The services a connection can be made to and the model providers agents think with: every integration, or those whose name or label contains query (case-insensitive), each with how a person connects it (connectWith) and how many of its operations run with no account, by its name (accountFreeOperationCount). kind: "model" keeps the model providers an agent's modelConnection names; kind: "app" the services whose operations are tools.

const [crm] = await Connection.integrations("hubspot");
const hubspot = Connection.fromName("crm", { integration: crm, createIfMissing: true });
const providers = await Connection.integrations(undefined, { kind: "model" });

A tool ref to some of its operations, for tools (gmail.only("send_email_message")); a lazy createIfMissing connection is still created first.

One of its repositories (owner/name on its git host; a github connection) checked out in an agent's workspace, for Agent repos: cloned into /workspace/<path> (the repository's name when omitted) at a conversation's first turn. The agent's git reaches that repository only, through NoClick, with a key made for its sandbox; the connection's own token never enters it. push is the branches it may push to, as globs: NoClick refuses a push to any other ref, and without it the checkout is read-only. gh only reads it; give the agent the connection's operations for pull requests and issues. Sends nothing.

const github = Connection.fromName("github", { integration: "github", createIfMissing: true });
const repos = [github.checkout("acme/docs", { push: "noclick/*" })];

What its integration can do: every operation, or those whose name or description contains search (case-insensitive), with parameter schemas and whether each needsAccount.

One of its integration's operations; throws NotFound for a name it doesn't have.

The app events its integration can wake an agent with, for OnEvent (what it pushes as it happens, never a poll).

A new link where someone connects (or reconnects) this connection's account; await link.wait() resolves to the connected Connection. The connection's own connectUrl is now this link's.

Ask the user (or sendTo) to connect it; await link.wait() resolves to the Connection. A connection of your account's own has no user: send it to "owner" (your account's owner) or an email.

Resolve once an account is connected (at once when it is). It follows the connection, not one link: an account connected through any of its links ends the wait, and a link that lapses after a fresh one was made (connectLink() or request(), from anywhere) hands the wait to the fresh one. Throws OperationExpired when the open link lapses with no fresh one, or OperationTimeout after timeoutS seconds.

Replace the connection's credential with one you hold (a rotated key), validated first.

Run one of the integration's operations in this account. Throws NeedsConnection while pending (an operation whose needsAccount is false runs anyway, on NoClick's key, or on your own key once connected, and needs no connection at all through run) and CredentialDisconnected once revoked (both carry connectUrl); a policy may throw PolicyDenied or ApprovalRequired. Resolves to the operation's data (what the service answered); a service that refuses the call throws UpstreamError in its own words, its HTTP status in details.upstream_status.

The allowed values of an ID-like field (channels, repos, sheets) in this account.

Re-check the account against the provider.

From now on its owner approves each call of these operations wherever it runs (your code, agents, the app's workflows); "*" means every operation. It only adds to approvalOperations; lifting one is done in the app. On one shared with your account it throws PermissionDenied.

await Connection.fromName("gmail").requireApproval("send_email_message", "delete_message");

Mark it as a test account (or, with false, not one). An app's preview only reads through a connection; through a test account it writes as well, as production does. Only the account that connected it marks it (PermissionDenied on one shared with yours), and it must hold an account (InvalidRequest while pending).

await Connection.fromName("slack-sandbox").markTestAccount();

A fresh OAuth access token for calling the provider yourself (credentials:token scope). A model provider's connection never hands out its key or plan token (PermissionDenied).

Delete the connection, revoking its account at the provider where possible.