@alter-ai/connect 0.10.0 → 0.11.1

package/README.md

@@ -1,8 +1,8 @@
 # Alter Connect SDK
 
-A lightweight JavaScript SDK for embedding OAuth integrations into your application. The SDK opens a backend-served Connect UI in a popup — the backend handles auth, provider selection, branding, and OAuth, then sends results back via postMessage.
+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.
 
-**~10KB minified | Zero dependencies | TypeScript included**
+**Typed OAuth callbacks | Zod-validated payloads | TypeScript included**
 
 ## Quick Start
 
@@ -12,18 +12,19 @@ A lightweight JavaScript SDK for embedding OAuth integrations into your applicat
 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>
 ```
 
-### 2. Get a Session Token from Your Backend
+### 2. Get a Session Token from the Application Backend
 
-Your backend creates a short-lived session token using the [Alter SDK](https://www.npmjs.com/package/@alter-ai/alter-sdk):
+The application backend creates a short-lived session token using the [Alter SDK](https://www.npmjs.com/package/@alter-ai/alter-sdk):
 
 ```typescript
-// YOUR backend (Node.js example using @alter-ai/alter-sdk)
+// Application backend (Node.js example using @alter-ai/alter-sdk)
 import { App, CallerType } from "@alter-ai/alter-sdk";
 
 const alterApp = new App({
@@ -33,11 +34,19 @@ 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
+  // rules. They can only narrow what they are granting, never widen it, and
+  // they can change or remove the limits later in their wallet.
+  //
+  // This step is enabled by default. To hide it, pass:
+  // allowUserPolicyRules: false,
 });
 
-const session_token = session.sessionToken;
+const sessionToken = session.sessionToken;
 ```
 
 ### 3. Open the Connect UI
@@ -48,104 +57,60 @@ import AlterConnect from '@alter-ai/connect';
 // Initialize SDK (no API key needed!)
 const alterConnect = AlterConnect.create();
 
-// Get session token from YOUR backend
-const { session_token } = await fetch('/api/alter/session').then(r => r.json());
-
-// Open Connect UI
-await alterConnect.open({
-  token: session_token,
-  onSuccess: (connections) => {
-    console.log('Connected!', connections);
-    // Save each connection.grant_id to your database
-    connections.forEach(conn => console.log(conn.provider, conn.grant_id));
-  },
-  onError: (error) => {
-    console.error('Failed:', error);
-  },
-  onExit: () => {
-    console.log('User closed the window');
-  }
-});
-```
-
-That's it! The SDK handles the OAuth flow, popup windows, mobile redirects, and all security.
-
-## 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>;
+const connectButton = document.querySelector('#connect-button');
+if (!(connectButton instanceof HTMLButtonElement)) {
+  throw new Error('Connect button is missing');
 }
-```
-
-### 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());
+connectButton.disabled = true;
+
+// Prefetch before the user interacts. Browsers may block a popup opened only
+// after an awaited network request has detached it from the click gesture.
+let sessionToken = null;
+fetch('/api/alter/session')
+  .then(response => response.json())
+  .then(({ session_token }) => {
+    sessionToken = session_token;
+    connectButton.disabled = false;
+  })
+  .catch(() => {
+    console.error('Unable to prepare the Connect session');
+  });
 
-  await alterConnect.value.open({
-    token: session_token,
-    onSuccess: (connections) => console.log('Connected!', connections)
+connectButton.addEventListener('click', () => {
+  if (!sessionToken) return;
+  void alterConnect.open({
+    token: sessionToken,
+    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);
+      });
+    },
+    onError: (error) => {
+      console.error('Failed:', error);
+    },
+    onExit: () => {
+      console.log('User closed the window');
+    }
   });
-}
-</script>
+});
 ```
 
-### Vanilla JavaScript (CDN)
+The package launches the hosted OAuth Connect UI and validates desktop popup results before callbacks receive them.
 
-```html
-<button id="connect-btn">Connect Account</button>
+## Framework Examples
 
-<script src="https://cdn.jsdelivr.net/npm/@alter-ai/connect@latest/dist/alter-connect.umd.js"></script>
-<script>
-  const alterConnect = AlterConnect.create();
+React, Vue, Angular, Svelte, and vanilla applications use the same pattern:
 
-  document.getElementById('connect-btn').addEventListener('click', async () => {
-    const { session_token } = await fetch('/api/alter/session')
-      .then(r => r.json());
+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.
 
-    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
 
@@ -162,19 +127,20 @@ 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. The backend-served Connect UI applies your branding automatically.
+**Note:** Visual customization (colors, fonts, logo) is configured via the Developer Portal branding settings. Alter Connect applies the configured branding automatically.
 
 ---
 
 ### `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) => { /* ... */ },
+  onSuccess: (grants, completion) => { /* ... */ },
   onError: (error) => { /* ... */ },
   onExit: () => { /* ... */ },
   onEvent: (eventName, metadata) => { /* ... */ }
@@ -183,51 +149,65 @@ await alterConnect.open({
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `token` | `string` | Yes | Session token from your backend |
-| `onSuccess` | `function` | Yes | Called with array of connections on success |
-| `onError` | `function` | No | Called when connection fails |
-| `onExit` | `function` | No | Called when user closes popup |
-| `onEvent` | `function` | No | Called for analytics events |
+| `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 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 |
+
+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.
 
-**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.
+`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.
 
-**Grants Array (onSuccess):**
+**Completion data (`onSuccess`):**
 
-`onSuccess` receives an array of `Grant` objects (multi-provider flow):
+For compatibility, the first argument remains an array of `Grant` objects. The
+second argument makes partial completion explicit:
 
 ```typescript
-// Each connection in the array:
-{
-  grant_id: string;             // Unique ID - store this!
-  provider: string;             // e.g., 'google', 'slack'
-  provider_name: string;        // e.g., 'Google', 'Slack'
-  account_identifier: string;   // e.g., 'user@gmail.com'
-  timestamp: string;            // ISO 8601 timestamp
-  operation: 'creation' | 'reauth';
-  scopes: string[];             // Granted OAuth scopes
-  status: 'active' | 'pending' | 'error';
-  metadata?: {
-    account_display_name?: string;
-    account_email?: string;
-  };
+interface ConnectCompletion {
+  grants: Grant[];
+  failedGrants: Array<{
+    providerId: string;
+    reason: string;
+    message: string;
+  }>;
 }
 ```
 
+`failedGrants` is empty for full success. When at least one provider succeeds,
+it identifies any providers whose grants were revoked because the selected
+usage limits could not be applied. Unknown `reason` strings are preserved.
+
 **Error Object (onError):**
 
 ```typescript
 {
-  code: string;     // e.g., 'invalid_token', 'popup_blocked'
-  message: string;  // Human-readable message
-  details?: object; // Additional error context
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+  failedGrants?: Array<{
+    providerId: string;
+    reason: string;
+    message: string;
+  }>;
 }
 ```
 
+A completion with no successful grants and one or more failed grants invokes
+`onError` with `code: "grant_policy_application_failed"` instead of reporting
+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();
@@ -250,24 +230,41 @@ alterConnect.destroy();
 Register an event listener. Returns an unsubscribe function.
 
 ```javascript
-const unsubscribe = alterConnect.on('success', (connection) => {
-  console.log('Connected:', connection);
+const unsubscribe = alterConnect.on('success', (grants, completion) => {
+  console.log('Connected:', grants);
+  console.log('Providers not kept:', completion.failedGrants);
 });
 
 // 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');
 }
 ```
 
@@ -278,41 +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.
+
+## Mobile behavior
 
-The SDK automatically detects mobile devices and switches to an optimized flow:
+The SDK chooses the flow using user-agent, touch, viewport, and orientation checks:
 
 | Device | Flow | How It Works |
 |--------|------|-------------|
-| Desktop | Popup | Opens centered popup (500x700px), communicates via postMessage |
-| 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 |
+| Desktop | Popup | Opens a centered popup (500x700px) and reports completion through callbacks |
+| 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.
+**Current limitation:** OAuth Connect does not navigate back to the session's `returnUrl`. Full-page navigation also destroys the callbacks and listeners registered by the original page. Do not rely on browser callbacks for mobile completion; use `createConnectSession()` plus `pollConnectSession()` on the application backend.
 
-For mobile redirect flow, include a `return_url` when creating the session:
-
-```javascript
-// Backend session creation with mobile support
-body: JSON.stringify({
-  allowed_providers: ['google', 'slack'],
-  allowed_origin: 'https://yourapp.com',  // For desktop popup (postMessage)
-  return_url: 'https://yourapp.com/'      // For mobile redirect (return destination)
-})
-```
+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
 
@@ -320,21 +330,28 @@ Full TypeScript definitions included:
 
 ```typescript
 import AlterConnect, {
-  AlterConnectConfig,
-  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 });
 
 await alterConnect.open({
   token: sessionToken,
-  onSuccess: (grants: Grant[]) => {
+  onSuccess: (grants: Grant[], completion: ConnectCompletion) => {
     for (const grant of grants) {
-      console.log(grant.grant_id);  // Store this in your DB!
+      console.log(grant.grant_id);  // Store this in the application database
       console.log(grant.provider);
       console.log(grant.scopes);
     }
+    for (const failure of completion.failedGrants) {
+      console.warn(failure.providerId, failure.message);
+    }
   },
   onError: (error: AlterError) => {
     console.error(error.code, error.message);
@@ -342,22 +359,11 @@ await alterConnect.open({
 });
 ```
 
-## Bundle Size
-
-| Format | Size | Gzipped |
-|--------|------|---------|
-| **CJS** | ~10KB | ~3.5KB |
-| **ESM** | ~10KB | ~3.4KB |
-| **UMD** | ~11KB | ~3.5KB |
-
-Zero runtime dependencies.
+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
 
@@ -368,31 +374,32 @@ Zero runtime dependencies.
 **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 should be created from your **backend**, not frontend. The SDK handles all frontend API calls.
+**Solution:** Create sessions on the application backend with an Alter server SDK, then return only the short-lived session token to the browser.
 
 ## Support
 
@@ -402,4 +409,4 @@ button.addEventListener('click', () => {
 
 ## License
 
-MIT License - See [LICENSE](LICENSE) file for details
+MIT