Connect SDK

@alter-ai/connect is a browser package that opens an Alter-hosted Connect UI 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.

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, branding, and desktop popup callbacks.
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

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.

Pages

create()

Construct an AlterConnect instance.

open()

Launch the Connect UI, including 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.