spry-apps-dropdown 3.0.0 → 3.0.2

package/README.md

@@ -1,71 +1,17 @@
 # spry-apps-dropdown
-## Integration Guide
 
-### 1. OIDC/Keycloak Setup
-
-This package requires OIDC authentication. Use `react-oidc-context` or `@react-keycloak/web` for best results.
-
-**Example OIDC config:**
-
-```tsx
-const oidcConfig = {
-  authority: 'https://auth.sprylogin.com/realms/sprylogin',
-  client_id: 'my-app-client',
-  redirect_uri: window.location.origin,
-  post_logout_redirect_uri: window.location.origin,
-  onSigninCallback: () => {
-    window.history.replaceState({}, document.title, window.location.pathname)
-  },
-}
-```
-
-### 2. Multi-Account Management
-
-The package supports multi-account switching, add-account, and soft logout. All account state is stored in localStorage for cross-app/iframe sync.
-
-**Syncing across apps/iframe:**
-- Use the same localStorage key (`spry_accounts`) in all apps.
-- When an account is added, removed, or switched, update localStorage and reload state in all apps.
-- For iframe/bridge integration, use a shared localStorage or a custom syncBridge client.
-
-### 3. Add Another Account Flow
-
-When adding another account:
-- A flag (`spry_add_account_pending`) is set in localStorage.
-- After soft logout, the app checks this flag and triggers OIDC login for the new account.
-- On callback, the new account is added and set as active.
-
-### 4. Cross-App Sync
-
-To sync active account and account removal across apps:
-- Listen for changes to `spry_accounts` in localStorage (using the `storage` event or polling).
-- When the accounts state changes, update your app's state and UI.
-- If using an iframe bridge, ensure the bridge propagates account changes to all connected apps.
-
-### 5. Troubleshooting
-
-- If new accounts are not added after login, ensure your OIDC provider updates the user context before the callback runs.
-- If cross-app sync is not working, check that all apps use the same localStorage key and listen for changes.
-- For CORS or redirect issues, verify your OIDC config and Keycloak setup.
-
-### 6. Example Integration
-
-See the Quick Start and Usage sections below for full code examples.
-
-
-A React component library for displaying Spry apps dropdown and profile menu with dynamic API integration. Features a Google-style UI with beautiful animations.
+A React component library for Spry apps dropdown and profile menu with **multi-account switching**. Features a Google-style UI with beautiful animations and automatic Keycloak authentication.
 
 ## Features
 
 - 🎨 Beautiful Material-UI design with smooth animations (Google-inspired)
-- 🔄 Automatic data fetching from API
-- 💾 Built-in caching and refetching
+- 👥 **Multi-account switching** - Users can log into multiple accounts and switch between them
+- 🔄 Automatic data fetching from API with caching
+- 🔐 Built-in Keycloak/OIDC authentication via react-oidc-context
 - ⚡ Loading and error states
 - 📱 Responsive layout
 - 🎯 TypeScript support
-- 🔌 Easy integration
-- 👤 Profile menu with avatar, account management, and sign out (always shows Manage your Account)
-- 🎛️ Combined TopBar component with both apps dropdown and profile menu
+- 🔌 Easy integration - Just 3 steps!
 
 ## Installation
 
@@ -73,18 +19,28 @@ A React component library for displaying Spry apps dropdown and profile menu wit
 npm install spry-apps-dropdown react-oidc-context oidc-client-ts
 ```
 
-This package expects `react`, `react-dom`, `react-oidc-context`, and `oidc-client-ts` to be provided by the consuming app.
+**Peer Dependencies:**
+- `react` ^18.0.0 || ^19.0.0
+- `react-dom` ^18.0.0 || ^19.0.0
+- `react-oidc-context` ^3.3.0
+- `oidc-client-ts` ^1.0.0
+
+---
 
-## React OIDC Quick Start (Lowest Effort)
+## Quick Start (3 Steps)
+
+### Step 1: Wrap Your App with `SpryAuthProvider`
 
 ```tsx
+// main.tsx or index.tsx
 import React from 'react'
 import ReactDOM from 'react-dom/client'
-import { SpryAuthProvider, TopBar, useSpryAccountManager } from 'spry-apps-dropdown'
+import { SpryAuthProvider } from 'spry-apps-dropdown'
+import App from './App'
 
 const oidcConfig = {
   authority: 'https://auth.sprylogin.com/realms/sprylogin',
-  client_id: 'my-app-client',
+  client_id: 'your-client-id',
   redirect_uri: window.location.origin,
   post_logout_redirect_uri: window.location.origin,
   onSigninCallback: () => {
@@ -92,17 +48,6 @@ const oidcConfig = {
   },
 }
 
-function App() {
-  const accountManager = useSpryAccountManager()
-
-  return (
-    <TopBar
-      apiUrl="https://your-api.com"
-      accountManager={accountManager}
-    />
-  )
-}
-
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
     <SpryAuthProvider config={oidcConfig}>
@@ -112,253 +57,252 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 )
 ```
 
-## Usage
-
-### TopBar Component (Easiest - Recommended for v2.0+)
-
-The `TopBar` component combines both apps dropdown and profile menu in a single component, just like Google's interface:
+### Step 2: Use `useSpryAccountManager` Hook
 
 ```tsx
-import { TopBar } from 'spry-apps-dropdown'
+// App.tsx
+import { useSpryAccountManager } from 'spry-apps-dropdown'
+
+function App() {
+  const accountManager = useSpryAccountManager()
 
-function MyAppBar() {
   return (
-    <AppBar>
-      <Toolbar>
-        <Typography variant="h6" sx={{ flexGrow: 1 }}>
-          My App
-        </Typography>
-        
-        <TopBar
-          apiUrl="https://your-api.com"
-          onSignOut={() => handleLogout()}
-          getAuthToken={() => yourAuthToken}
-          appsRefetchInterval={30000}  // 30 seconds
-          appsCacheTime={30000}
-          profileRefetchInterval={5 * 60 * 1000}  // 5 minutes
-          profileCacheTime={5 * 60 * 1000}
-        />
-      </Toolbar>
-    </AppBar>
+    <div>
+      {/* Your app content */}
+    </div>
   )
 }
 ```
 
-### Profile Menu Only
-
-Use just the profile menu component:
+### Step 3: Add the TopBar Component
 
 ```tsx
-import { ProfileMenuConnected } from 'spry-apps-dropdown'
+// App.tsx
+import { TopBar, useSpryAuth, useSpryAccountManager } from 'spry-apps-dropdown'
+
+function App() {
+  const auth = useSpryAuth()
+  const accountManager = useSpryAccountManager()
 
-function MyComponent() {
   return (
-    <ProfileMenuConnected
-      apiUrl="https://your-api.com"
-      onSignOut={() => handleLogout()}
-      getAuthToken={() => yourAuthToken}
-      refetchInterval={5 * 60 * 1000}  // 5 minutes
-      cacheTime={5 * 60 * 1000}
-    />
+    <div>
+      <AppBar>
+        <Toolbar>
+          <Typography variant="h6" sx={{ flexGrow: 1 }}>
+            My App
+          </Typography>
+
+          <TopBar
+            apiUrl="https://sprylogin.com/apps-api"
+            onSignOut={() => auth.signoutRedirect()}
+            getAuthToken={() => auth.user?.access_token || null}
+            accountManager={accountManager}
+          />
+        </Toolbar>
+      </AppBar>
+
+      {/* Your app content */}
+    </div>
   )
 }
 ```
 
-### Apps Dropdown Only (Basic Usage)
+**That's it!** Your app now has:
+- ✅ Multi-account switching
+- ✅ Apps dropdown
+- ✅ Profile menu
+- ✅ Automatic authentication
 
-Import `AppsDropdownConnected` for automatic API integration:
+---
+
+## Using Auth Token in Your API Calls
+
+Get the current user's token using `useSpryAuth()`:
 
 ```tsx
-import { useState, useRef } from 'react'
-import { IconButton } from '@mui/material'
-import { Apps } from '@mui/icons-material'
-import { AppsDropdownConnected } from 'spry-apps-dropdown'
+import { useSpryAuth } from 'spry-apps-dropdown'
 
 function MyComponent() {
-  const [appsMenuOpen, setAppsMenuOpen] = useState(false)
-  const appsButtonRef = useRef<HTMLButtonElement>(null)
+  const auth = useSpryAuth()
 
-  return (
-    <>
-      <IconButton
-        ref={appsButtonRef}
-        onClick={() => setAppsMenuOpen(!appsMenuOpen)}
-      >
-        <Apps />
-      </IconButton>
-
-      <AppsDropdownConnected
-        apiUrl="http://localhost:3002"
-        open={appsMenuOpen}
-        onClose={() => setAppsMenuOpen(false)}
-        buttonRef={appsButtonRef}
-      />
-    </>
-  )
+  useEffect(() => {
+    const token = auth.user?.access_token
+
+    fetch('/api/data', {
+      headers: {
+        'Authorization': `Bearer ${token}`
+      }
+    })
+  }, [auth.user])
 }
 ```
 
-### Advanced Usage
-
-Use `AppsDropdown` directly with custom data source:
+**For React Query:**
 
 ```tsx
-import { AppsDropdown, useAppsData } from 'spry-apps-dropdown'
+import { useSpryAuth } from 'spry-apps-dropdown'
+import { useQuery } from '@tanstack/react-query'
 
 function MyComponent() {
-  const [appsMenuOpen, setAppsMenuOpen] = useState(false)
-  const appsButtonRef = useRef<HTMLButtonElement>(null)
-  
-  // Use the hook for more control
-  const { apps, isLoading, error, refetch } = useAppsData('http://localhost:3002', {
-    refetchInterval: 10 * 60 * 1000, // 10 minutes
-    cacheTime: 10 * 60 * 1000 // 10 minutes
+  const auth = useSpryAuth()
+
+  const { data } = useQuery({
+    queryKey: ['data'],
+    queryFn: async () => {
+      const token = auth.user?.access_token
+      const res = await fetch('/api/data', {
+        headers: { 'Authorization': `Bearer ${token}` }
+      })
+      return res.json()
+    },
+    enabled: !!auth.user,
   })
-
-  return (
-    <>
-      <IconButton ref={appsButtonRef} onClick={() => setAppsMenuOpen(!appsMenuOpen)}>
-        <Apps />
-      </IconButton>
-
-      <AppsDropdown
-        apps={apps}
-        open={appsMenuOpen}
-        onClose={() => setAppsMenuOpen(false)}
-        buttonRef={appsButtonRef}
-        isLoading={isLoading}
-        error={error}
-        onRetry={refetch}
-      />
-    </>
-  )
 }
 ```
 
+---
+
+## Multi-Account Switching
+
+The package automatically handles multi-account switching:
+
+1. **User clicks "Add Another Account"** in ProfileMenu
+2. **Redirects to Keycloak** for login (with `prompt=login`)
+3. **New account is added** to localStorage
+4. **User can switch** between accounts from ProfileMenu
+5. **API calls automatically use** the active account's token
+
+**No manual code needed** - it just works!
+
+---
+
 ## API Reference
 
-### `TopBar` (New in v2.0)
+### `TopBar` Component
 
-Combined component with both apps dropdown and profile menu, positioned side by side like Google's interface.
+Combined apps dropdown + profile menu (recommended).
 
 #### Props
 
 | Prop | Type | Required | Default | Description |
 |------|------|----------|---------|-------------|
 | `apiUrl` | `string` | Yes | - | Base URL for apps API |
+| `accountManager` | `UseAccountManagerReturn` | Yes | - | Account manager from `useSpryAccountManager()` |
 | `profileApiUrl` | `string` | No | Same as `apiUrl` | Base URL for profile API |
 | `onSignOut` | `() => void` | No | - | Callback when user signs out |
-| `getAuthToken` | `() => string \| null \| Promise<string \| null>` | No | - | Function to get auth token |
+| `getAuthToken` | `() => string \| null` | No | - | Function to get auth token |
 | `profileHeaders` | `Record<string, string>` | No | - | Custom headers for profile API |
 | `showAppsDropdown` | `boolean` | No | `true` | Show apps dropdown |
 | `showProfileMenu` | `boolean` | No | `true` | Show profile menu |
-| `appsRefetchInterval` | `number` | No | `300000` (5 min) | Apps refetch interval in ms |
-| `appsCacheTime` | `number` | No | `300000` (5 min) | Apps cache duration in ms |
-| `profileRefetchInterval` | `number` | No | `300000` (5 min) | Profile refetch interval in ms |
-| `profileCacheTime` | `number` | No | `300000` (5 min) | Profile cache duration in ms |
-
-### `ProfileMenuConnected` (New in v2.0)
-
-Profile menu component with automatic API integration.
-
-#### Props
-
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `apiUrl` | `string` | Yes | - | Base URL for profile API |
-| `onSignOut` | `() => void` | No | - | Callback when user signs out |
-| `onManageAccount` | `() => void` | No | - | Callback for Manage your Account button. If not provided, it redirects to `https://sprylogin.com/my-account/` |
-| `getAuthToken` | `() => string \| null \| Promise<string \| null>` | No | - | Function to get auth token |
-| `headers` | `Record<string, string>` | No | - | Custom headers for API requests |
-| `refetchInterval` | `number` | No | `300000` (5 min) | Auto-refetch interval in ms |
-| `cacheTime` | `number` | No | `300000` (5 min) | Cache duration in ms |
+| `appsRefetchInterval` | `number` | No | `300000` (5 min) | Apps refetch interval (ms) |
+| `appsCacheTime` | `number` | No | `300000` (5 min) | Apps cache duration (ms) |
+| `profileRefetchInterval` | `number` | No | `300000` (5 min) | Profile refetch interval (ms) |
+| `profileCacheTime` | `number` | No | `300000` (5 min) | Profile cache duration (ms) |
 
-### Manage Account behavior
+---
 
-The Manage your Account button is always shown. It uses this order:
+### `SpryAuthProvider` Component
 
-1. `onManageAccount` callback (if provided)
-2. `profile.manageAccountUrl` (if present)
-3. Default: `https://sprylogin.com/my-account/`
-
-### `AppsDropdownConnected`
-
-The main component with automatic API integration.
+Wraps your app with Keycloak/OIDC authentication.
 
 #### Props
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `apiUrl` | `string` | Yes | - | Base URL of the Spry Apps API |
-| `open` | `boolean` | Yes | - | Whether the dropdown is open |
-| `onClose` | `() => void` | Yes | - | Callback when dropdown closes |
-| `buttonRef` | `React.RefObject<HTMLButtonElement>` | No | - | Ref for positioning |
-| `refetchInterval` | `number` | No | `300000` (5 min) | Auto-refetch interval in ms |
-| `cacheTime` | `number` | No | `300000` (5 min) | Cache duration in ms |
-
-### `AppsDropdown`
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `config` | `UserManagerSettings` | Yes | OIDC configuration object |
+| `children` | `ReactNode` | Yes | Your app components |
 
-The presentational component for custom implementations.
+**Example config:**
 
-#### Props
+```tsx
+const oidcConfig = {
+  authority: 'https://auth.sprylogin.com/realms/sprylogin',
+  client_id: 'my-app-client',
+  redirect_uri: window.location.origin,
+  post_logout_redirect_uri: window.location.origin,
+  onSigninCallback: () => {
+    window.history.replaceState({}, document.title, window.location.pathname)
+  },
+}
+```
 
-| Prop | Type | Required | Default | Description |
-|------|------|----------|---------|-------------|
-| `apps` | `App[]` | Yes | - | Array of apps to display |
-| `open` | `boolean` | Yes | - | Whether the dropdown is open |
-| `onClose` | `() => void` | Yes | - | Callback when dropdown closes |
-| `buttonRef` | `React.RefObject<HTMLButtonElement>` | No | - | Ref for positioning |
-| `isLoading` | `boolean` | No | `false` | Loading state |
-| `error` | `string \| null` | No | `null` | Error message |
-| `onRetry` | `() => void` | No | - | Retry callback |
+---
 
-### `useAppsData`
+### `useSpryAccountManager()` Hook
 
-Hook for fetching apps data.
+Returns account manager for multi-account switching.
 
-#### Parameters
+#### Returns
 
 ```typescript
-useAppsData(apiUrl: string, options?: {
-  refetchInterval?: number  // Default: 300000 (5 minutes)
-  cacheTime?: number        // Default: 300000 (5 minutes)
-})
+{
+  accounts: StoredAccount[]        // All logged-in accounts
+  activeAccount: StoredAccount     // Currently active account
+  switchAccount: (id: string) => Promise<void>
+  addNewAccount: () => Promise<void>
+  removeAccount: (id: string) => Promise<void>
+  refreshAccountToken: (id: string) => Promise<void>
+}
 ```
 
+---
+
+### `useSpryAuth()` Hook
+
+Returns the current authentication state (alias for `useAuth()` from react-oidc-context).
+
 #### Returns
 
 ```typescript
 {
-  apps: App[]              // Array of apps
-  isLoading: boolean       // Loading state
-  error: string | null     // Error message if any
-  refetch: () => Promise<void>  // Manual refetch function
+  user: User | null               // Current user object
+  isAuthenticated: boolean        // Is user logged in
+  isLoading: boolean             // Is auth loading
+  signinRedirect: () => Promise<void>
+  signoutRedirect: () => Promise<void>
+  // ... other react-oidc-context methods
 }
 ```
 
-### Types
+---
 
-```typescript
-interface App {
-  id: string
-  name: string
-  description: string
-  url: string
-  iconUrl: string
-  color: string
-  order: number
-  createdAt: string
-  updatedAt: string
+## Advanced: Handling Account Switches
+
+If you're using React Query and want to refetch data when accounts switch:
+
+```tsx
+import { useSpryAccountManager } from 'spry-apps-dropdown'
+import { useQueryClient } from '@tanstack/react-query'
+import { useEffect } from 'react'
+
+function useMultiAccountManager() {
+  const queryClient = useQueryClient()
+  const accountManager = useSpryAccountManager()
+
+  // Listen for account switches and invalidate queries
+  useEffect(() => {
+    const handleAccountSwitch = () => {
+      queryClient.invalidateQueries() // Refetch all data
+    }
+
+    window.addEventListener('auth:account-switched', handleAccountSwitch)
+    return () => window.removeEventListener('auth:account-switched', handleAccountSwitch)
+  }, [queryClient])
+
+  return accountManager
 }
 ```
 
+---
+
 ## Backend API Requirements
 
-The component expects the following API endpoint structure:
+Your backend should expose these endpoints:
 
 ### `GET /api/apps`
 
-Returns:
+Returns list of apps for the dropdown.
+
 ```json
 {
   "apps": [
@@ -378,26 +322,17 @@ Returns:
 }
 ```
 
-### `GET /api/profile` (New in v2.0)
+### `GET /api/profile`
 
-Returns user profile information. Supports multiple authentication methods:
+Returns user profile information (requires Bearer token).
 
-**Option 1: JWT Token (via Authorization header)**
 ```http
 GET /api/profile
 Authorization: Bearer <jwt-token>
 ```
 
-**Option 2: Custom Headers**
-```http
-GET /api/profile
-X-User-Email: user@example.com
-X-User-FirstName: John
-X-User-LastName: Doe
-X-User-Avatar: https://example.com/avatar.jpg
-```
-
 **Response:**
+
 ```json
 {
   "email": "user@example.com",
@@ -408,52 +343,113 @@ X-User-Avatar: https://example.com/avatar.jpg
 }
 ```
 
-See [spry-apps-server](https://github.com/your-org/spry-apps-server) for the reference backend implementation.
+---
 
-## Styling
+## Customization
 
-The component uses Material-UI components. You can customize the appearance using the MUI theme:
+### Custom Theme
 
 ```tsx
 import { ThemeProvider, createTheme } from '@mui/material/styles'
 
 const theme = createTheme({
-  // Your custom theme
+  palette: {
+    primary: {
+      main: '#1a73e8',
+    },
+  },
 })
 
-function App() {
-  return (
-    <ThemeProvider theme={theme}>
-      <AppsDropdownConnected {...props} />
-    </ThemeProvider>
-  )
-}
+<ThemeProvider theme={theme}>
+  <SpryAuthProvider config={oidcConfig}>
+    <App />
+  </SpryAuthProvider>
+</ThemeProvider>
 ```
 
-## Caching
+### Hide Apps Dropdown or Profile Menu
+
+```tsx
+<TopBar
+  apiUrl="https://sprylogin.com/apps-api"
+  showAppsDropdown={false}  // Hide apps dropdown
+  showProfileMenu={true}     // Show only profile menu
+  accountManager={accountManager}
+/>
+```
 
-The component automatically caches apps data in `localStorage` to provide instant loading on subsequent visits. The cache respects the `cacheTime` option.
+---
 
-## Error Handling
+## Troubleshooting
 
-- Network errors are caught and displayed with a retry button
-- Cached data is used as fallback when API is unavailable
-- Loading spinner shown during initial fetch
+### "User not authenticated" error
+
+Make sure you wrapped your app with `SpryAuthProvider`:
+
+```tsx
+<SpryAuthProvider config={oidcConfig}>
+  <App />
+</SpryAuthProvider>
+```
+
+### Account switching doesn't work
+
+Pass the `accountManager` prop to `TopBar`:
+
+```tsx
+const accountManager = useSpryAccountManager()
+
+<TopBar accountManager={accountManager} {...otherProps} />
+```
+
+### API calls use wrong token after switching
+
+Use `useSpryAuth()` to get the current token:
+
+```tsx
+const auth = useSpryAuth()
+const token = auth.user?.access_token
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support included. Types are automatically available:
+
+```tsx
+import type {
+  UseAccountManagerReturn,
+  StoredAccount,
+  OIDCUser,
+  TopBarProps
+} from 'spry-apps-dropdown'
+```
+
+---
 
 ## Browser Support
 
 - Modern browsers with ES2020 support
 - Requires localStorage API
 
+---
+
 ## License
 
 MIT
 
-## Contributing
+---
 
-Contributions are welcome! Please open an issue or submit a pull request.
-
-## Related
+## Related Documentation
 
+- [INTEGRATION.md](./INTEGRATION.md) - Detailed multi-account integration guide
 - [Spry Apps Server](https://github.com/your-org/spry-apps-server) - Backend API server
-- [Spry Account](https://github.com/your-org/spry-account) - Reference implementation
+
+---
+
+## Support
+
+For issues or questions:
+- Open an issue on GitHub
+- Check INTEGRATION.md for detailed guides