@alter-ai/connect 0.11.0 → 0.12.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alter AI, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,6 @@
 # Alter Connect SDK
 
-A lightweight JavaScript SDK for embedding OAuth integrations into an application. The SDK opens Alter Connect in a popup and reports the completed grants through typed callbacks.
+A lightweight JavaScript SDK for embedding OAuth integrations into an application. The SDK opens Alter Connect in a desktop popup, uses full-page navigation on mobile-classified devices, and validates completion data before invoking typed callbacks.
 
 **Typed OAuth callbacks | Zod-validated payloads | TypeScript included**
 
@@ -12,7 +12,8 @@ A lightweight JavaScript SDK for embedding OAuth integrations into an applicatio
 npm install @alter-ai/connect
 ```
 
-Or use via CDN:
+The package metadata declares Node.js 20.19 or later for npm tooling. Browser
+execution does not require Node.js. Or use the UMD bundle via CDN:
 
 ```html
 <script src="https://cdn.jsdelivr.net/npm/@alter-ai/connect@latest/dist/alter-connect.umd.js"></script>
@@ -33,8 +34,8 @@ const alterApp = new App({
 });
 
 const session = await alterApp.createConnectSession({
-  allowedProviders: ["google", "slack", "github"],
-  returnUrl: "https://yourapp.com/callback",
+  allowedProviders: ["provider-id"],
+  allowedOrigin: "https://app.example.com",
   // Optional. When the user approves access, the Connect UI also lets them set
   // their own usage limits on the connection being created — deny rules,
   // human approval, time windows, request quotas, and operation/parameter
@@ -45,7 +46,7 @@ const session = await alterApp.createConnectSession({
   // allowUserPolicyRules: false,
 });
 
-const session_token = session.sessionToken;
+const sessionToken = session.sessionToken;
 ```
 
 ### 3. Open the Connect UI
@@ -79,9 +80,9 @@ connectButton.addEventListener('click', () => {
   if (!sessionToken) return;
   void alterConnect.open({
     token: sessionToken,
-    onSuccess: (connections, completion) => {
-      console.log('Connected!', connections);
-      connections.forEach(conn => console.log(conn.provider, conn.grant_id));
+    onSuccess: (grants, completion) => {
+      console.log('Connected!', grants);
+      grants.forEach(grant => console.log(grant.provider, grant.grant_id));
       completion.failedGrants.forEach(failure => {
         console.warn(failure.providerId, failure.reason, failure.message);
       });
@@ -96,84 +97,20 @@ connectButton.addEventListener('click', () => {
 });
 ```
 
-The SDK handles the OAuth flow, popup windows, mobile redirects, and security checks.
+The package launches the hosted OAuth Connect UI and validates desktop popup results before callbacks receive them.
 
 ## Framework Examples
 
-### React
-
-```jsx
-import { useState } from 'react';
-import AlterConnect from '@alter-ai/connect';
-
-function ConnectButton() {
-  const [alterConnect] = useState(() => AlterConnect.create());
-
-  const handleConnect = async () => {
-    const { session_token } = await fetch('/api/alter/session')
-      .then(r => r.json());
-
-    await alterConnect.open({
-      token: session_token,
-      onSuccess: (connections) => {
-        console.log('Connected!', connections);
-      }
-    });
-  };
-
-  return <button onClick={handleConnect}>Connect Account</button>;
-}
-```
-
-### Vue
-
-```vue
-<template>
-  <button @click="handleConnect">Connect Account</button>
-</template>
-
-<script setup>
-import { ref, onMounted } from 'vue';
-import AlterConnect from '@alter-ai/connect';
-
-const alterConnect = ref(null);
-
-onMounted(() => {
-  alterConnect.value = AlterConnect.create();
-});
-
-async function handleConnect() {
-  const { session_token } = await fetch('/api/alter/session')
-    .then(r => r.json());
+React, Vue, Angular, Svelte, and vanilla applications use the same pattern:
 
-  await alterConnect.value.open({
-    token: session_token,
-    onSuccess: (connections) => console.log('Connected!', connections)
-  });
-}
-</script>
-```
+1. Create one reusable `AlterConnect` instance.
+2. Fetch a session token before enabling the Connect button.
+3. Call `open()` directly in the click handler so popup activation remains attached to the user gesture.
+4. Destroy the instance when the owning component unmounts.
 
-### Vanilla JavaScript (CDN)
-
-```html
-<button id="connect-btn">Connect Account</button>
-
-<script src="https://cdn.jsdelivr.net/npm/@alter-ai/connect@latest/dist/alter-connect.umd.js"></script>
-<script>
-  const alterConnect = AlterConnect.create();
-
-  document.getElementById('connect-btn').addEventListener('click', async () => {
-    const { session_token } = await fetch('/api/alter/session')
-      .then(r => r.json());
-
-    await alterConnect.open({
-      token: session_token,
-      onSuccess: (connections) => console.log('Connected!', connections)
-    });
-  });
-</script>
-```
+The CDN bundle exposes the same class as `window.AlterConnect`. CommonJS
+consumers read the default export with
+`require('@alter-ai/connect').default`.
 
 ## API Reference
 
@@ -190,6 +127,7 @@ const alterConnect = AlterConnect.create({
 | Option | Type | Description | Default |
 |--------|------|-------------|---------|
 | `debug` | `boolean` | Enable debug logging | `false` |
+| `baseURL` | `string` | Reserved and unsupported. Passing any value throws. | — |
 
 **Note:** Visual customization (colors, fonts, logo) is configured via the Developer Portal branding settings. Alter Connect applies the configured branding automatically.
 
@@ -197,12 +135,12 @@ const alterConnect = AlterConnect.create({
 
 ### `alterConnect.open(options)`
 
-Opens the Connect UI. On desktop, opens a centered popup window (500x700px). On mobile, uses a full-page redirect flow.
+Attempts to open Connect. Desktop uses a centered popup window (500×700 px). Mobile-classified devices use full-page navigation, with the limitation documented under [Mobile behavior](#mobile-behavior).
 
 ```javascript
 await alterConnect.open({
   token: 'sess_abc123...',
-  onSuccess: (connections, completion) => { /* ... */ },
+  onSuccess: (grants, completion) => { /* ... */ },
   onError: (error) => { /* ... */ },
   onExit: () => { /* ... */ },
   onEvent: (eventName, metadata) => { /* ... */ }
@@ -213,11 +151,17 @@ await alterConnect.open({
 |-----------|------|----------|-------------|
 | `token` | `string` | Yes | Short-lived session token created by the application backend with an Alter SDK |
 | `onSuccess` | `(grants, completion) => void` | Yes | Called with the legacy grants array and a typed completion object. `completion.failedGrants` identifies partial failures. |
-| `onError` | `(error) => void` | No | Called when connection fails. A total usage-limit application failure has code `grant_policy_application_failed` and typed `failedGrants`. |
-| `onExit` | `function` | No | Called when user closes popup |
-| `onEvent` | `function` | No | Called for analytics events |
+| `onError` | `(error) => void` | No | Called for failures delivered to the browser SDK, such as a blocked popup, a malformed result, or a total usage-limit application failure. Hosted-page-only failures require backend polling. |
+| `onExit` | `function` | No | Called when the user closes the desktop popup; this does not mark the backend session denied |
+| `onEvent` | `(eventName, metadata) => void` | No | Called once with `connect_opened` after each launch attempt, including a blocked popup |
 
-**Upgrading from 0.8.x:** `open()` no longer accepts a `baseURL` option — the widget always opens against the production Alter host. A `baseURL` override is reserved for a future release but not currently supported; contact support if you need to target a non-production deployment.
+The promise resolves after the launch attempt, not after user authorization. Missing or invalid `token` or `onSuccess` values reject the returned promise with `code: "invalid_options"`. `baseURL` is not an `OpenOptions` field: TypeScript rejects it, while plain JavaScript ignores it.
+
+`onSuccess`, `onError`, and `onExit` run through the event emitter's exception
+guard. If one throws, the SDK logs the exception and does not perform that
+callback's final state/listener cleanup; callback code should not throw.
+`onEvent` is invoked directly, so an exception from it rejects `open()` after
+the launch attempt.
 
 **Completion data (`onSuccess`):**
 
@@ -262,7 +206,8 @@ bare success.
 
 ### `alterConnect.close()`
 
-Manually closes the Connect UI.
+Closes an active popup if one exists, stops the current flow handler, removes
+the current per-open callbacks, resets `isOpen()`, and emits `close`.
 
 ```javascript
 alterConnect.close();
@@ -293,17 +238,33 @@ const unsubscribe = alterConnect.on('success', (grants, completion) => {
 // Later: unsubscribe();
 ```
 
-**Events:** `success`, `error`, `exit`, `close`, `event`
+**Emitted bus events:** `success`, `error`, `exit`, `close`. The `success` handler receives `(grants, completion)`. Analytics does not emit an `event` bus event; use the per-open `onEvent` callback.
+
+---
+
+### `alterConnect.off(event, handler)`
+
+Removes a previously registered event handler. Pass the same handler reference
+that was supplied to `on()`.
+
+```javascript
+const handleError = error => console.error(error);
+alterConnect.on('error', handleError);
+alterConnect.off('error', handleError);
+```
 
 ---
 
 ### `alterConnect.isOpen()`
 
-Checks if the Connect UI is currently open.
+Returns the SDK's open-state flag. It becomes `true` when a launch starts and
+returns to `false` when `close()` runs. A manually closed popup resets it
+automatically only when the supplied `onExit` callback returns normally; if
+`onExit` is omitted or throws, call `close()` explicitly before opening again.
 
 ```javascript
 if (alterConnect.isOpen()) {
-  console.log('Modal is open');
+  console.log('Connect is open');
 }
 ```
 
@@ -314,40 +275,54 @@ if (alterConnect.isOpen()) {
 Gets the SDK version.
 
 ```javascript
-console.log(alterConnect.getVersion()); // e.g., "0.3.0"
+console.log(alterConnect.getVersion()); // "0.2.0" in package 0.11.0
 ```
 
-## Mobile Support
+`getVersion()` reads a runtime constant embedded in the bundle. It does not currently match the package metadata version.
 
-The SDK automatically detects mobile devices and switches to an optimized flow:
+## Mobile behavior
+
+The SDK chooses the flow using user-agent, touch, viewport, and orientation checks:
 
 | Device | Flow | How It Works |
 |--------|------|-------------|
 | Desktop | Popup | Opens a centered popup (500x700px) and reports completion through callbacks |
-| Phone (<=480px) | Redirect | Full-page redirect, returns via URL params |
-| Tablet (portrait) | Redirect | Full-page redirect for better UX |
-| Tablet (landscape) | Popup | Uses popup flow like desktop |
+| Mobile-classified viewport ≤480 px | Redirect | Navigates the full page to Connect |
+| Mobile-classified viewport 481–1024 px in portrait | Redirect | Navigates the full page to Connect |
+| Other devices | Popup | Uses the desktop callback flow |
 
-No code changes needed — the SDK handles device detection automatically.
+**Redirect completion:** full-page navigation destroys the callbacks and listeners registered by the original page. Set `returnUrl` on the session and Connect navigates back to it with the outcome, which is delivered to the callbacks registered on the instance constructed by the returning page. Callback parameters that do not carry the per-flow value the SDK minted are ignored. Sessions created without a `returnUrl`, and returns arriving more than five minutes after the flow started, complete through `createConnectSession()` plus `pollConnectSession()` on the application backend.
 
-For mobile redirect flow, include a return URL when creating the session:
-
-```typescript
-const session = await alterApp.createConnectSession({
-  allowedProviders: ["google", "slack"],
-  allowedOrigin: "https://app.example.com",
-  returnUrl: "https://app.example.com/",
-});
-```
+Closing the desktop popup invokes `onExit` locally but sends no denial
+transition to the backend. A server-side poll remains pending until its timeout
+or the session expires.
 
 ## Security
 
-- **API keys stay on the backend.** The frontend only ever holds a short-lived, single-use, scope-restricted session token minted by the application backend.
-- **No secrets in the browser.** The SDK is a popup launcher + callback listener; it does not handle credentials directly.
+- **API keys stay on the backend.** The frontend only receives a short-lived session token minted by the application backend.
+- **No API keys or provider credentials in the browser.** The frontend receives only the short-lived Connect session token.
 
 ## Provider selection
 
-When `allowedProviders` lists a single provider, the Connect UI skips the selection screen and opens that provider's OAuth flow directly. With two or more, the UI shows a provider picker.
+The hosted UI renders the providers permitted by the session. When that provider is not already connected, a one-provider allowlist still renders one available provider. A verified user with an existing healthy connection can use the consent fast path; `requestedGrant`, when present, controls the sibling grant requested on that connection. Set `switchAccount: true` while creating the session to force full provider authorization.
+
+## Session-controlled behavior
+
+Provider allowlists, per-provider requested scopes, origin binding, user identity, requested sibling grants, delegated agents, onward-delegation permission, delegation scope constraints, account switching, grant-expiry bounds, and policy authoring are session-creation concerns. They are not browser `OpenOptions`. Grant-expiry bounds add a duration picker to the hosted confirmation screen.
+
+A recovery session from the server SDKs' `createConnectSessionForError()` is
+opened like any other session by passing its `sessionToken` to `open()`. This
+browser package exports none of the server-side exception classes, including
+`ReAuthRequiredError`, `NoDelegatedGrantError`, `GrantNotFoundError`,
+`CredentialRevokedError`, or the headless-flow `ConnectFlowError` family
+(`ConnectDeniedError`, `ConnectConfigError`, `ConnectTimeoutError`).
+
+With `allowUserPolicyRules` enabled, the hosted UI can author narrowing deny,
+human-approval, time-window, quota, and operation/parameter content rules.
+Human approval occurs on later API calls; Connect only authors the rule. If
+selected rules fail to apply for some providers,
+`completion.failedGrants` reports the partial failure. If no grant remains,
+`onError` receives `grant_policy_application_failed`.
 
 ## TypeScript Support
 
@@ -355,10 +330,13 @@ Full TypeScript definitions included:
 
 ```typescript
 import AlterConnect, {
-  AlterConnectConfig,
-  ConnectCompletion,
-  Grant,
-  AlterError
+  type AlterConnectConfig,
+  type OpenOptions,
+  type ConnectCompletion,
+  type ConnectFailedGrant,
+  type Provider,
+  type Grant,
+  type AlterError
 } from '@alter-ai/connect';
 
 const alterConnect = AlterConnect.create({ debug: true });
@@ -381,23 +359,11 @@ await alterConnect.open({
 });
 ```
 
-## Bundle Size
-
-| Format | Minified size |
-|--------|---------------|
-| **CJS** | ~74KB |
-| **ESM** | ~74KB |
-| **UMD** | ~74KB |
-
-The package has one runtime dependency: Zod 4 validates complete OAuth
-`postMessage` payloads before callback data is consumed.
+The package has one runtime dependency: Zod 4 validates complete cross-window result payloads before callback data is consumed.
 
 ## Browser Support
 
-- Chrome/Edge 90+
-- Firefox 88+
-- Safari 14+
-- Mobile browsers (iOS Safari 14+, Chrome Mobile)
+The 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 because it checks redirect state during construction. The repository's product E2E suite exercises Chromium; it does not establish a cross-browser version matrix. The package metadata declares Node.js 20.19 or later for npm tooling; CDN browser use does not require Node.js.
 
 ## Troubleshooting
 
@@ -408,31 +374,32 @@ The package has one runtime dependency: Zod 4 validates complete OAuth
 **Solution:** Ensure `alterConnect.open()` is called directly from a user interaction (click event):
 
 ```javascript
-// Bad - may be blocked
+// May be blocked: the network request runs after the click.
 button.addEventListener('click', async () => {
-  const token = await fetchToken(); // Async delay
-  alterConnect.open({ token }); // May be blocked
+  const token = await fetchToken();
+  void alterConnect.open({ token, onSuccess, onError });
 });
 
-// Good - no async delay before open()
+// Reliable: fetch before enabling the button.
+const token = await fetchToken();
+button.disabled = false;
+
 button.addEventListener('click', () => {
-  fetchToken().then(token => {
-    alterConnect.open({ token }); // Called synchronously
-  });
+  void alterConnect.open({ token, onSuccess, onError });
 });
 ```
 
 ### Session Token Expired
 
-**Problem:** `session_expired` error
+**Problem:** The hosted Connect page reports that the session expired or is invalid
 
-**Solution:** Session tokens expire after 10 minutes. Create a new session token.
+**Solution:** Session tokens have a 10-minute default lifetime. Create a new session and open its token. An expiry detected while binding or loading the hosted page is rendered there; it is not a reliable browser `onError` callback.
 
 ### CORS Errors
 
-**Problem:** CORS error when calling Alter API
+**Problem:** Session creation was attempted from browser code
 
-**Solution:** Session tokens must be created by the application backend, not the frontend. The SDK handles the frontend flow.
+**Solution:** Create sessions on the application backend with an Alter server SDK, then return only the short-lived session token to the browser.
 
 ## Support
 
@@ -442,4 +409,4 @@ button.addEventListener('click', () => {
 
 ## License
 
-MIT License - See [LICENSE](LICENSE) file for details
+MIT

package/THIRD_PARTY_NOTICES

@@ -0,0 +1,9 @@
+Third-Party Notices
+
+This distribution may include:
+
+- Zod, Copyright (c) 2020 Colin McDonnell, MIT License.
+- tslib, Copyright (c) Microsoft Corporation, 0BSD License.
+
+The complete corresponding license texts are available in the installed package metadata and
+the upstream projects. These notices do not modify Alter Connect's MIT License.