Connect SDK

@alter-ai/connect is a browser package that opens an Alter-hosted Connect UI (in a popup window, or inline inside an element on the page) and reports OAuth grants through typed callbacks. It includes Zod as a runtime dependency so cross-window results are validated before application callbacks receive them. It is the frontend half of the Call APIs on behalf of users flow.

A session minted for exactly one provider shows no Alter page before the provider: the popup and redirect flows go straight to that provider’s sign-in, and the inline flow does the same from the application’s click when the session’s single_provider flag is passed to open() as singleProvider (falling back to a single tile only if the browser blocks the window). The user still confirms the connection on the way back unless the session was also minted with direct, a separate opt-out the application chooses. See Exactly one provider in the embedding guide.

npm install @alter-ai/connect

The package metadata declares Node.js 20.19 or later for npm tooling. The CDN browser bundle does not require Node.js.

Or via CDN:

<script src="https://cdn.jsdelivr.net/npm/@alter-ai/connect@latest/dist/alter-connect.umd.js"></script>

Framework-agnostic. Works with React, Vue, Angular, Svelte, or no framework.

The CDN bundle exposes AlterConnect as a global. ES modules use the npm package’s default export plus the named type exports listed in Types. CommonJS consumers access the class as require("@alter-ai/connect").default.

For an end-to-end walk-through, see Embed the Connect widget. This section is API reference.

When to use Connect

Flow	Use it when
Browser Connect package	A browser application wants the Alter-hosted provider picker, consent UI, and branding, either in a desktop popup or rendered inline inside the application’s own layout, with callbacks on completion.
createConnectSession() plus pollConnectSession()	The application backend needs to own result recovery, including flows where popup callbacks are unavailable.
connect() in the TypeScript or Python SDK	A local interactive process can launch a browser, or print a URL for the user, and block while the SDK polls for completion.

The server-side methods live in the TypeScript SDK and Python SDK. They are also the source of recovery-specific exceptions; the browser package returns AlterError objects instead of exporting the server SDK exception classes.

Warning

Without a container, the browser package detects mobile-classified devices and navigates the whole page to Connect. Callbacks and event-bus listeners registered before that navigation do not survive it — set returnUrl on the session, construct an instance on the returning page, and register .on("success", ...) / .on("error", ...) listeners on that instance. The SDK retains the redirect outcome until the matching first listener attaches. Use the backend session polling flow for sessions created without a returnUrl. The inline flow (container) never navigates the page on any device.

Pages

create()

Construct an AlterConnect instance.

open()

Launch the Connect UI: popup, inline in a container, or the mobile redirect flow.

Events & callbacks

onSuccess, onError, onExit, onEvent, and the on/off event bus.

Types

All seven named type exports, including grants, completion data, errors, and options.

Browser support

The distributed CJS, ESM, and UMD bundles target ES2020 and use modern browser APIs including popup or full-page navigation, postMessage, URL parsing, and sessionStorage. Importing the package is side-effect free, but AlterConnect.create() must run in a browser context. The repository’s product E2E coverage exercises Chromium; it does not establish a cross-browser version matrix.