@alter-ai/connect 0.2.0 → 0.2.1

package/README.md

@@ -1,8 +1,10 @@
 # Alter Connect SDK
 
-A lightweight JavaScript SDK for embedding OAuth integrations into your application. Connect your users to Google, Slack, Microsoft, and more with just a few lines of code.
+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.
 
-## 🚀 Quick Start
+**~10KB minified | Zero dependencies | TypeScript included**
+
+## Quick Start
 
 ### 1. Install
 
@@ -31,9 +33,15 @@ const response = await fetch('https://api.alterai.dev/oauth/connect/session', {
   body: JSON.stringify({
     end_user: {
       id: 'user_123',
-      email: 'user@example.com'
+      email: 'user@example.com',
+      name: 'John Doe'
+    },
+    attributes: {
+      user_id: 'user_123',
+      org_id: 'org_456'
     },
-    allowed_providers: ['google', 'slack', 'microsoft']
+    allowed_providers: ['google', 'slack', 'microsoft'],
+    allowed_origin: 'https://yourapp.com'
   })
 });
 
@@ -45,7 +53,7 @@ const { session_token } = await response.json();
 ```javascript
 import AlterConnect from '@alter-ai/connect';
 
-// Initialize SDK
+// Initialize SDK (no API key needed!)
 const alterConnect = AlterConnect.create();
 
 // Get session token from YOUR backend
@@ -60,13 +68,16 @@ await alterConnect.open({
   },
   onError: (error) => {
     console.error('Failed:', error);
+  },
+  onExit: () => {
+    console.log('User closed the window');
   }
 });
 ```
 
-That's it! The SDK handles the OAuth flow, popup windows, and all security.
+That's it! The SDK handles the OAuth flow, popup windows, mobile redirects, and all security.
 
-## 📖 Framework Examples
+## Framework Examples
 
 ### React
 
@@ -143,100 +154,7 @@ async function handleConnect() {
 </script>
 ```
 
-## 🎨 Branding & Customization
-
-**Branding is now managed through the Developer Portal** and automatically applied to the Connect UI at runtime.
-
-### Managing Branding (Developer Portal)
-
-Configure your app's branding through the Developer Portal API:
-
-#### Initial Setup or Complete Rebrand (PUT)
-
-Use PUT for initial branding setup or to completely replace existing branding:
-
-```javascript
-// Create or fully replace branding
-await fetch('https://api.alterai.dev/api/v1/developer/apps/{app_id}/branding', {
-  method: 'PUT',
-  headers: {
-    'Authorization': `Bearer ${DEVELOPER_TOKEN}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    logo_url: 'https://your-domain.com/logo.png',  // Required
-    colors: {                                        // Required
-      primary: '#6366f1',
-      text: '#1f2937',
-      background: '#ffffff'
-    },
-    font_family: 'Inter, sans-serif'  // Optional
-  })
-});
-```
-
-#### Partial Updates (PATCH)
-
-Use PATCH to update specific branding fields:
-
-```javascript
-// Update only font (logo + colors preserved)
-await fetch('https://api.alterai.dev/api/v1/developer/apps/{app_id}/branding', {
-  method: 'PATCH',
-  headers: {
-    'Authorization': `Bearer ${DEVELOPER_TOKEN}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    font_family: 'Roboto, sans-serif'
-  })
-});
-
-// Update logo + colors (font preserved)
-await fetch('https://api.alterai.dev/api/v1/developer/apps/{app_id}/branding', {
-  method: 'PATCH',
-  headers: {
-    'Authorization': `Bearer ${DEVELOPER_TOKEN}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    logo_url: 'https://your-domain.com/new-logo.png',
-    colors: {
-      primary: '#ff0000',
-      text: '#000000',
-      background: '#ffffff'
-    }
-  })
-});
-```
-
-**Important Rules:**
-- **PUT:** Requires `logo_url` and `colors`. Font is optional. Replaces all existing branding.
-- **PATCH:** Requires existing branding (use PUT first). If updating logo or colors, both must be provided together. Font can be updated independently.
-- **DELETE:** Removes all branding and reverts to Alter defaults.
-
-### How It Works
-
-1. **Configure branding** in the Developer Portal
-2. **SDK fetches branding** automatically when `alterConnect.open()` is called
-3. **Branding is applied** instantly to the Connect UI
-4. **No redeployment needed** - changes take effect immediately
-
-### Fallback Behavior
-
-If no branding is configured or the API call fails, the SDK gracefully falls back to Alter's default branding.
-
-### SDK Configuration Options
-
-For local development or debugging, you can still configure some options:
-
-```javascript
-const alterConnect = AlterConnect.create({
-  debug: true  // Enable console logging
-});
-```
-
-## 📚 API Reference
+## API Reference
 
 ### `AlterConnect.create(config?)`
 
@@ -244,42 +162,40 @@ Creates a new SDK instance.
 
 ```javascript
 const alterConnect = AlterConnect.create({
-  debug: false
+  debug: true  // Enable console logging (default: false)
 });
 ```
 
-**Config Options:**
-
 | Option | Type | Description | Default |
 |--------|------|-------------|---------|
 | `debug` | `boolean` | Enable debug logging | `false` |
 
-**Note:** Branding (colors, fonts, logo) is now managed through the Developer Portal and fetched automatically at runtime.
+**Note:** Visual customization (colors, fonts, logo) is configured via the Developer Portal branding settings. The backend-served Connect UI applies your branding automatically.
 
 ---
 
 ### `alterConnect.open(options)`
 
-Opens the Connect UI modal.
+Opens the Connect UI. On desktop, opens a centered popup window (500x700px). On mobile, uses a full-page redirect flow.
 
 ```javascript
 await alterConnect.open({
   token: 'sess_abc123...',
+  baseURL: 'https://api.alterai.dev',  // Optional
   onSuccess: (connection) => { /* ... */ },
   onError: (error) => { /* ... */ },
-  onExit: () => { /* ... */ }
+  onExit: () => { /* ... */ },
+  onEvent: (eventName, metadata) => { /* ... */ }
 });
 ```
 
-**Options:**
-
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
-| `token` | `string` | ✅ Yes | Session token from your backend |
+| `token` | `string` | Yes | Session token from your backend |
 | `baseURL` | `string` | No | Alter API URL (usually auto-detected) |
-| `onSuccess` | `function` | ✅ Yes | Called when connection succeeds |
+| `onSuccess` | `function` | Yes | Called when connection succeeds |
 | `onError` | `function` | No | Called when connection fails |
-| `onExit` | `function` | No | Called when user closes modal |
+| `onExit` | `function` | No | Called when user closes popup |
 | `onEvent` | `function` | No | Called for analytics events |
 
 **Connection Object (onSuccess):**
@@ -292,9 +208,12 @@ await alterConnect.open({
   account_identifier: string;   // e.g., 'user@gmail.com'
   timestamp: string;            // ISO 8601 timestamp
   operation: 'creation' | 'reauth';
-  scopes: string[];            // Granted OAuth scopes
+  scopes: string[];             // Granted OAuth scopes
   status: 'active' | 'pending' | 'error';
-  metadata?: object;           // Additional provider data
+  metadata?: {
+    account_display_name?: string;
+    account_email?: string;
+  };
 }
 ```
 
@@ -330,6 +249,22 @@ alterConnect.destroy();
 
 ---
 
+### `alterConnect.on(event, handler)`
+
+Register an event listener. Returns an unsubscribe function.
+
+```javascript
+const unsubscribe = alterConnect.on('success', (connection) => {
+  console.log('Connected:', connection);
+});
+
+// Later: unsubscribe();
+```
+
+**Events:** `success`, `error`, `exit`, `close`, `event`
+
+---
+
 ### `alterConnect.isOpen()`
 
 Checks if the Connect UI is currently open.
@@ -340,8 +275,6 @@ if (alterConnect.isOpen()) {
 }
 ```
 
-**Returns:** `boolean`
-
 ---
 
 ### `alterConnect.getVersion()`
@@ -349,14 +282,38 @@ if (alterConnect.isOpen()) {
 Gets the SDK version.
 
 ```javascript
-console.log(alterConnect.getVersion()); // "0.1.0"
+console.log(alterConnect.getVersion()); // "0.2.1"
 ```
 
-**Returns:** `string`
+## Mobile Support
+
+The SDK automatically detects mobile devices and switches to an optimized flow:
+
+| 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 |
+
+No code changes needed — the SDK handles device detection automatically.
+
+For mobile redirect flow, include a `return_url` when creating the session:
+
+```javascript
+// Backend session creation with mobile support
+body: JSON.stringify({
+  end_user: { id: 'user_123', email: 'user@example.com' },
+  attributes: { user_id: 'user_123' },
+  allowed_providers: ['google', 'slack'],
+  allowed_origin: 'https://yourapp.com',  // For desktop popup (postMessage)
+  return_url: 'https://yourapp.com/'      // For mobile redirect (return destination)
+})
+```
 
-## 🔒 Security Architecture
+## Security Architecture
 
-The SDK uses a **Plaid-style token architecture** for security:
+The SDK uses a **Plaid-style token architecture**:
 
 ```
 Frontend (Public)          Backend (Secure)           Alter API
@@ -375,140 +332,63 @@ Frontend (Public)          Backend (Secure)           Alter API
      │  4. { session_token }    │                        │
      │<─────────────────────────│                        │
      │                          │                        │
-     │  5. SDK.open({ token })  │                        │
-     │──────────────────────────┼───────────────────────>│
-     │                          │  6. OAuth flow         │
-     │<─────────────────────────┴────────────────────────│
-     │  7. onSuccess(connection)│                        │
+     │  5. SDK opens popup to backend Connect UI         │
+     │───────────────────────────────────────────────────>│
+     │                          │                        │
+     │     6. Backend handles auth + OAuth               │
+     │                          │                        │
+     │  7. postMessage(connection)                       │
+     │<──────────────────────────────────────────────────│
+     │  8. onSuccess(connection) │                        │
 ```
 
 **Key Security Features:**
 
-✅ **API keys never touch frontend** - Only backend has API key
-✅ **Session tokens are short-lived** - Expire after 10 minutes
-✅ **Session tokens are single-use** - Can only create one connection
-✅ **Session tokens are scoped** - Locked to specific user & providers
-✅ **No secrets in browser** - SDK is purely a UI component
+- **API keys never touch frontend** - Only backend has API key
+- **Session tokens are short-lived** - Expire after 10 minutes
+- **Session tokens are single-use** - Can only create one connection
+- **Session tokens are scoped** - Locked to specific user & providers
+- **No secrets in browser** - SDK is purely a popup launcher + callback listener
 
-## 💡 Smart UX
+## Smart UX
 
 ### Single Provider Flow
 
-When only 1 provider is allowed, the SDK **skips the selection UI** and opens OAuth directly:
+When only 1 provider is allowed, the Connect UI **skips the selection screen** and opens OAuth directly:
 
 ```javascript
-// Backend
-allowed_providers: ['google']
-
-// SDK behavior: Opens Google OAuth immediately (no modal)
+// Backend: allowed_providers: ['google']
+// Result: Opens Google OAuth immediately (no selection screen)
 ```
 
 ### Multiple Provider Flow
 
-When 2+ providers are allowed, the SDK shows a **provider selection modal**:
+When 2+ providers are allowed, the Connect UI shows a **provider selection screen**:
 
 ```javascript
-// Backend
-allowed_providers: ['google', 'slack', 'microsoft']
-
-// SDK behavior: Shows modal with provider grid
+// Backend: allowed_providers: ['google', 'slack', 'microsoft']
+// Result: Shows provider selection, user picks one
 ```
 
-## 🎯 Common Patterns
-
-### Save Connection to Your Database
-
-```javascript
-await alterConnect.open({
-  token: sessionToken,
-  onSuccess: async (connection) => {
-    // Save to YOUR database
-    await fetch('/api/connections', {
-      method: 'POST',
-      body: JSON.stringify({
-        connection_id: connection.connection_id,
-        user_id: currentUserId,
-        provider: connection.provider
-      })
-    });
-  }
-});
-```
-
-### Validate Provider Type
-
-```javascript
-await alterConnect.open({
-  token: sessionToken,
-  onSuccess: async (connection) => {
-    // Ensure user connected the right provider
-    if (connection.provider !== 'google') {
-      alert('Please connect your Gmail account');
-      return;
-    }
-
-    await saveConnection(connection);
-  }
-});
-```
-
-### Validate Email Domain
-
-```javascript
-await alterConnect.open({
-  token: sessionToken,
-  onSuccess: async (connection) => {
-    // Ensure user connected a work email
-    if (!connection.account_identifier.endsWith('@company.com')) {
-      alert('Please connect your @company.com work email');
-      return;
-    }
-
-    await saveConnection(connection);
-  }
-});
-```
-
-### Handle Errors Gracefully
-
-```javascript
-await alterConnect.open({
-  token: sessionToken,
-  onSuccess: (connection) => {
-    console.log('Connected!', connection);
-  },
-  onError: (error) => {
-    if (error.code === 'popup_blocked') {
-      alert('Please allow popups for this site');
-    } else if (error.code === 'session_expired') {
-      alert('Session expired. Please try again.');
-    } else {
-      alert(`Connection failed: ${error.message}`);
-    }
-  },
-  onExit: () => {
-    console.log('User cancelled');
-  }
-});
-```
-
-## 📦 TypeScript Support
+## TypeScript Support
 
 Full TypeScript definitions included:
 
 ```typescript
-import AlterConnect, { Connection, AlterError } from '@alter-ai/connect';
+import AlterConnect, {
+  AlterConnectConfig,
+  Connection,
+  AlterError
+} from '@alter-ai/connect';
 
-const alterConnect = AlterConnect.create({
-  customization: { colors: { primary: '#6366f1' } }
-});
+const alterConnect = AlterConnect.create({ debug: true });
 
 await alterConnect.open({
   token: sessionToken,
   onSuccess: (connection: Connection) => {
-    // TypeScript knows all properties
     console.log(connection.connection_id);
     console.log(connection.provider);
+    console.log(connection.scopes);
   },
   onError: (error: AlterError) => {
     console.error(error.code, error.message);
@@ -516,21 +396,24 @@ await alterConnect.open({
 });
 ```
 
-## 🌐 Browser Support
+## Bundle Size
+
+| Format | Size | Gzipped |
+|--------|------|---------|
+| **CJS** | ~10KB | ~3.5KB |
+| **ESM** | ~10KB | ~3.4KB |
+| **UMD** | ~11KB | ~3.5KB |
+
+Zero runtime dependencies.
+
+## Browser Support
 
 - Chrome/Edge 90+
 - Firefox 88+
 - Safari 14+
 - Mobile browsers (iOS Safari 14+, Chrome Mobile)
 
-## 📊 Bundle Size
-
-- **UMD:** 21KB minified
-- **ESM:** 21KB minified
-- **CJS:** 21KB minified
-- **Zero runtime dependencies**
-
-## 🐛 Troubleshooting
+## Troubleshooting
 
 ### Popup Blocked
 
@@ -539,13 +422,13 @@ await alterConnect.open({
 **Solution:** Ensure `alterConnect.open()` is called directly from a user interaction (click event):
 
 ```javascript
-// ❌ Bad - may be blocked
+// Bad - may be blocked
 button.addEventListener('click', async () => {
   const token = await fetchToken(); // Async delay
   alterConnect.open({ token }); // May be blocked
 });
 
-// ✅ Good - no async delay before open()
+// Good - no async delay before open()
 button.addEventListener('click', () => {
   fetchToken().then(token => {
     alterConnect.open({ token }); // Called synchronously
@@ -565,13 +448,13 @@ button.addEventListener('click', () => {
 
 **Solution:** Session tokens should be created from your **backend**, not frontend. The SDK handles all frontend API calls.
 
-## 🤝 Support
+## Support
 
 - **Documentation:** [https://docs.alterai.dev](https://docs.alterai.dev)
 - **API Reference:** [https://api.alterai.dev/docs](https://api.alterai.dev/docs)
-- **Issues:** [GitHub Issues](https://github.com/alter-ai/alter-vault/issues)
+- **Issues:** [GitHub Issues](https://github.com/AlterAIDev/Alter-Vault/issues)
 - **Email:** support@alterai.dev
 
-## 📄 License
+## License
 
 MIT License - See [LICENSE](LICENSE) file for details

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alter-ai/connect",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "JavaScript SDK for Alter Connect - Secure OAuth integration UI",
   "main": "dist/alter-connect.cjs.js",
   "module": "dist/alter-connect.esm.js",