spry-apps-dropdown 2.0.3 → 3.0.0

package/dist/keycloakLogout.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Main logout: Remove account from localStorage, then redirect to soft-logout endpoint
+ * Always redirects back to the app after logout
+ *
+ * @param accountId - The account ID to remove
+ * @param keycloakConfig - Keycloak configuration
+ * @param redirectUrl - (Optional) URL to redirect back to after logout (defaults to window.location.origin)
+ */
+export declare function mainLogout(accountId: string, keycloakConfig: KeycloakConfig, redirectUrl?: string): void;
+import type { KeycloakConfig, OIDCUser } from './types';
+export interface LogoutResult {
+    success: boolean;
+    message: string;
+    remainingAccounts: number;
+}
+/**
+ * Clear Keycloak SSO session via fetch (without redirect)
+ * Used before signinRedirect to handle SSO collision when adding new account
+ *
+ * Important: Soft-logout clears Keycloak SSO cookies without revoking tokens.
+ * This preserves offline refresh tokens for multi-account switching.
+ *
+ * @param user - Current OIDC user with refresh_token
+ * @param keycloakConfig - Keycloak configuration
+ * @returns Success boolean
+ */
+export declare function clearSSOSessionBeforeAddAccount(_user: OIDCUser | null, keycloakConfig: KeycloakConfig): Promise<boolean>;
+/**
+ * Sign out a single account and optionally switch to another
+ * Uses silent token revocation (no redirect) to logout without interrupting the user.
+ * Removes the account from local storage after successful logout.
+ *
+ * Only redirects if this is the LAST account AND revocation fails.
+ *
+ * @param user - The OIDC user object containing id_token and refresh_token
+ * @param keycloakConfig - Keycloak configuration
+ * @param accountId - The account ID to remove
+ * @returns LogoutResult with success status and remaining account count
+ */
+export declare function logoutAccount(user: OIDCUser, keycloakConfig: KeycloakConfig, accountId: string): Promise<LogoutResult>;
+/**
+ * Sign out all accounts and clear all sessions
+ * This destroys the entire multi-account session
+ */
+export declare function logoutAllAccounts(accounts: Array<{
+    accountId: string;
+    user: OIDCUser;
+}>, keycloakConfig: KeycloakConfig): Promise<LogoutResult>;
+/**
+ * Soft logout: Remove an account from local storage without calling Keycloak
+ * Use this when Keycloak endpoint is unavailable but you want to clear local session
+ */
+export declare function logoutAccountLocally(accountId: string): LogoutResult;
+/**
+ * Check if logout succeeded but we should still update the UI
+ * (e.g., Keycloak endpoint failed but we removed locally)
+ */
+export declare function isLogoutPartiallySuccessful(result: LogoutResult): boolean;

package/dist/syncBridge.d.ts

@@ -0,0 +1,8 @@
+import type { SyncBridgeClient } from './types';
+interface SyncBridgeOptions {
+    bridgeUrl: string;
+    timeoutMs?: number;
+}
+export declare function createSyncBridgeClient(options: SyncBridgeOptions | null | undefined): SyncBridgeClient | null;
+export declare function getBridgeStorageKey(): string;
+export {};

package/dist/tokenUtils.d.ts

@@ -0,0 +1,58 @@
+/**
+ * JWT token validation and inspection utilities
+ * Handles checking token expiry, decoding payloads, and refresh token validation
+ */
+import type { OIDCUser, StoredAccount } from './types';
+/**
+ * Decode a JWT token without validation (client-side only)
+ * WARNING: Does not validate signature. For verification, rely on server.
+ */
+export declare function decodeToken(token: string): Record<string, unknown> | null;
+/**
+ * Check if an access token has expired with a buffer
+ * Returns true if token is expired OR expiring within buffer seconds
+ */
+export declare function isTokenExpired(token: string | undefined, bufferSeconds?: number): boolean;
+/**
+ * Check if a refresh token has expired with a buffer
+ * Similar to isTokenExpired but with longer buffer (5 minutes)
+ */
+export declare function isRefreshTokenExpired(token: string | undefined, bufferSeconds?: number): boolean;
+/**
+ * Get the expiry timestamp of a token (in milliseconds)
+ * Returns null if token is invalid or missing exp claim
+ */
+export declare function getTokenExpiryTime(token: string | undefined): number | null;
+/**
+ * Get the remaining lifetime of a token in seconds
+ * Returns 0 or negative if expired
+ */
+export declare function getTokenTimeRemaining(token: string | undefined): number;
+/**
+ * Extract user info from OIDC User object
+ * Returns email, name, and avatar for display
+ */
+export declare function extractUserInfo(user: OIDCUser): {
+    email: string;
+    name: string;
+    avatar: string | undefined;
+};
+/**
+ * Check if a stored account's tokens are stale
+ * This checks both access token and refresh token expiry
+ */
+export declare function isAccountStale(account: StoredAccount): boolean;
+/**
+ * Check if we need to refresh the access token for a user
+ * This is different from checking if it's stale; we refresh proactively
+ */
+export declare function shouldRefreshAccessToken(token: string | undefined): boolean;
+/**
+ * Check if we need to refresh the refresh token
+ * Refresh tokens have longer buffer time
+ */
+export declare function shouldRefreshRefreshToken(token: string | undefined): boolean;
+/**
+ * Check if an access token is valid right now (ignoring buffer)
+ */
+export declare function isAccessTokenValid(token: string | undefined): boolean;

package/dist/types.d.ts

@@ -78,4 +78,60 @@ export interface TopBarProps {
     appsCacheTime?: number;
     profileRefetchInterval?: number;
     profileCacheTime?: number;
+    accountManager?: UseAccountManagerReturn;
+}
+export interface KeycloakConfig {
+    authority: string;
+    client_id: string;
+    redirect_uri?: string;
+    post_logout_redirect_uri?: string;
+}
+export interface OIDCUser {
+    access_token: string;
+    refresh_token?: string;
+    id_token?: string;
+    expires_in?: number;
+    profile?: {
+        sub: string;
+        email?: string;
+        name?: string;
+        given_name?: string;
+        family_name?: string;
+        picture?: string;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+export interface StoredAccountMetadata {
+    accountId: string;
+    lastUsed: number;
+    isStale: boolean;
+    createdAt: number;
+}
+export interface StoredAccount extends StoredAccountMetadata {
+    user: OIDCUser;
+}
+export interface AccountsState {
+    accounts: StoredAccount[];
+    activeAccountId: string | null;
+    lastUpdated: number;
+}
+export interface SyncBridgeClient {
+    getAccountsState: () => Promise<AccountsState | null>;
+    setAccountsState: (state: AccountsState) => Promise<void>;
+}
+export interface UseAccountManagerOptions {
+    keycloakConfig: KeycloakConfig;
+    initialUser: OIDCUser | null | undefined;
+    onAccountSwitch: (user: OIDCUser) => void;
+    signinRedirect?: (args?: import('oidc-client-ts').SigninRedirectArgs) => Promise<void>;
+    syncBridge?: SyncBridgeClient | null;
+}
+export interface UseAccountManagerReturn {
+    accounts: StoredAccount[];
+    activeAccount: StoredAccount | null;
+    switchAccount: (accountId: string) => Promise<void>;
+    addNewAccount: () => Promise<void>;
+    removeAccount: (accountId: string) => Promise<void>;
+    refreshAccountToken: (accountId: string) => Promise<void>;
 }

package/dist/useAccountManager.d.ts

@@ -0,0 +1,28 @@
+/**
+ * useAccountManager Hook
+ * Core integration point for multi-account switching with Keycloak
+ *
+ * Manages account storage, switching, and token refresh
+ * Handles redirect-based add account flow with state flags
+ *
+ * Redirect Flow (5 steps):
+ * 1. Save state before redirect (current user, flags, return URL)
+ * 2. Clear SSO session via fetch, then signinRedirect
+ * 3. Keycloak redirects back, primary auth provider (ReactKeycloak) processes callback
+ * 4. On mount, detect flag, wait for initialUser, add to accounts, call onAccountSwitch
+ * 5. Navigate to return URL
+ */
+import type { UseAccountManagerOptions, UseAccountManagerReturn } from './types';
+/**
+ * Hook for managing multi-account switching with redirect-based add account flow
+ *
+ * Usage:
+ * ```
+ * const accountManager = useAccountManager({
+ *   keycloakConfig: { authority: '...', client_id: '...', redirect_uri: '...' },
+ *   initialUser: keycloak.user, // From @react-keycloak/web
+ *   onAccountSwitch: (user) => updateKeycloakTokens(user.access_token, user.refresh_token)
+ * })
+ * ```
+ */
+export declare function useAccountManager(options: UseAccountManagerOptions): UseAccountManagerReturn;

package/dist/useSpryAccountManager.d.ts

@@ -0,0 +1,8 @@
+export declare function useSpryAccountManager(): {
+    removeAccount: (accountId: string) => Promise<void>;
+    accounts: import("./types").StoredAccount[];
+    activeAccount: import("./types").StoredAccount | null;
+    switchAccount: (accountId: string) => Promise<void>;
+    addNewAccount: () => Promise<void>;
+    refreshAccountToken: (accountId: string) => Promise<void>;
+};

package/dist/useSpryAuth.d.ts

@@ -0,0 +1 @@
+export declare function useSpryAuth(): import("react-oidc-context").AuthContextProps;

package/dist/userManagerPool.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Main logout handler: removes account from localStorage and redirects to soft-logout endpoint
+ * @param accountId - The account ID to remove
+ * @param keycloakConfig - Keycloak configuration
+ * @param redirectUrl - (Optional) URL to redirect back to after logout (defaults to window.location.origin)
+ */
+export declare function handleMainLogout(accountId: string, keycloakConfig: KeycloakConfig, redirectUrl?: string): void;
+/**
+ * UserManager pool for managing per-account Keycloak token refresh
+ * Each account has its own UserManager instance for isolated token refresh lifecycle
+ *
+ * Redirect Flow:
+ * - Uses signinRedirect for adding accounts (not popup)
+ * - State flags in localStorage track redirect progress
+ * - On callback, useAccountManager detects the flag and processes new account
+ */
+import { UserManager } from 'oidc-client-ts';
+import type { KeycloakConfig, OIDCUser } from './types';
+/**
+ * Create a new UserManager instance for a specific Keycloak realm
+ */
+export declare function createUserManager(keycloakConfig: KeycloakConfig, accountId: string): Promise<UserManager>;
+/**
+ * Maintain a map of UserManager instances, one per account
+ * This allows each account to manage its own token refresh independently
+ */
+declare class UserManagerPoolImpl {
+    private pool;
+    getOrCreate(keycloakConfig: KeycloakConfig, accountId: string): Promise<UserManager>;
+    remove(accountId: string): void;
+    clear(): void;
+    has(accountId: string): boolean;
+}
+export declare const userManagerPool: UserManagerPoolImpl;
+/**
+ * Refresh the access token for a specific account using signinSilent
+ * Updates the stored account with new tokens on success
+ */
+export declare function refreshTokenForAccount(accountId: string, user: OIDCUser, keycloakConfig: KeycloakConfig): Promise<OIDCUser | null>;
+/**
+ * Handle token expiry by marking account as stale
+ * The next time user tries to switch to this account, they'll see the stale badge
+ * and can click to trigger signinPopup with prompt=login
+ */
+export declare function handleTokenExpired(accountId: string): void;
+/**
+ * Initiate sign-in redirect for adding a new account
+ *
+ * This is a fallback function used when signinRedirect is not available from context.
+ * The standard flow uses addNewAccount in useAccountManager which handles soft-logout + signinRedirect.
+ */
+export declare function signinRedirectForNewAccount(keycloakConfig: KeycloakConfig, tempAccountId: string): Promise<void>;
+/**
+ * Revoke a token for a specific account (silent, no redirect)
+ * Uses Keycloak's token revocation endpoint to invalidate the refresh token
+ *
+ * For multi-account scenarios, use this instead of signoutRedirect to avoid the logout page
+ */
+export declare function revokeTokenForAccount(user: OIDCUser, keycloakConfig: KeycloakConfig): Promise<boolean>;
+/**
+ * Sign out a specific account from Keycloak (in-browser redirect)
+ * This invalidates the Keycloak session for that account
+ *
+ * WARNING: This redirects to Keycloak logout page. Only use this when logging out the last account
+ * or when you want to redirect to login page. For multi-account logout, use revokeTokenForAccount instead.
+ */
+export declare function signoutAccountFromKeycloak(user: OIDCUser, keycloakConfig: KeycloakConfig, tempAccountId: string): Promise<void>;
+/**
+ * Validate if an account's tokens can be refreshed
+ * Returns true if the refresh token is still valid (not expired)
+ */
+export declare function canRefreshAccount(user: OIDCUser): boolean;
+/**
+ * Get a list of accounts that can be refreshed
+ * Useful for background refresh tasks
+ */
+export declare function getRefreshableAccounts(accounts: Array<{
+    accountId: string;
+    user: OIDCUser;
+}>): Array<{
+    accountId: string;
+    user: OIDCUser;
+}>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spry-apps-dropdown",
-  "version": "2.0.3",
+  "version": "3.0.0",
   "description": "React components for Spry apps dropdown and profile menu with dynamic API integration - Google-style UI",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -32,13 +32,15 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@mui/material": "^6.0.0",
-    "@mui/icons-material": "^6.0.0",
-    "framer-motion": "^11.0.0",
     "@emotion/react": "^11.11.0",
-    "@emotion/styled": "^11.11.0"
+    "@emotion/styled": "^11.11.0",
+    "@mui/icons-material": "^6.0.0",
+    "@mui/material": "^6.0.0",
+    "framer-motion": "^11.0.0"
   },
   "peerDependencies": {
+    "oidc-client-ts": "^1.0.0",
+    "react-oidc-context": "^3.3.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
@@ -46,6 +48,8 @@
     "@types/react": "^19.0.1",
     "@types/react-dom": "^19.0.1",
     "@vitejs/plugin-react": "^4.3.4",
+    "oidc-client-ts": "^3.4.1",
+    "react-oidc-context": "^3.3.0",
     "typescript": "^5.9.3",
     "vite": "^7.2.4"
   }