@nibssplc/cams-sdk-react 0.0.1-beta.48 → 0.0.1-beta.50

package/README.md

@@ -1,13 +1,13 @@
 # NIBSS CAMS SDK - React
 
-React hooks and components for NIBSS CAMS SDK with support for both popup and redirect authentication flows.
+React hooks and components for NIBSS CAMS SDK with support for popup authentication and Azure AD MSAL integration.
 
 ## Installation
 
 ```bash
 npm install @nibssplc/cams-sdk-react
 
-# For MSAL redirect support (optional)
+# For Azure AD MSAL support (optional)
 npm install @azure/msal-browser @azure/msal-react
 ```
 
@@ -16,30 +16,43 @@ npm install @azure/msal-browser @azure/msal-react
 ### Popup Authentication (Default)
 
 ```tsx
-import { CAMSProvider, useCAMSAuth } from '@nibssplc/cams-sdk-react';
+import { CAMSProvider, useCAMSContext } from '@nibssplc/cams-sdk-react';
 
 function App() {
   return (
-    <CAMSProvider>
+    <CAMSProvider appCode="your-app-code" storageKey="CAMS-AUTH-SDK">
       <LoginComponent />
     </CAMSProvider>
   );
 }
 
 function LoginComponent() {
-  const { login, logout, isAuthenticated, isLoading } = useCAMSAuth();
+  const { login, logout, isAuthenticated, isLoading, userProfile, error } = useCAMSContext();
 
-  const handleLogin = () => {
-    login({
-      camsUrl: 'https://your-cams-instance.com/auth',
-      messageOrigin: 'your-cams-instance.com',
-      windowWidth: 500,
-      windowHeight: 600,
-    });
+  const handleLogin = async () => {
+    try {
+      await login({
+        camsUrl: 'https://your-cams-instance.com/auth',
+        messageOrigin: 'your-cams-instance.com',
+        windowWidth: 500,
+        windowHeight: 600,
+      });
+    } catch (err) {
+      console.error('Login failed:', err);
+    }
   };
 
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
+
   if (isAuthenticated) {
-    return <button onClick={logout}>Logout</button>;
+    return (
+      <div>
+        <p>Welcome, {userProfile?.name}!</p>
+        <button onClick={logout}>Logout</button>
+      </div>
+    );
   }
 
   return (
@@ -50,12 +63,62 @@ function LoginComponent() {
 }
 ```
 
-### MSAL Redirect Authentication with MFA
+### Direct Hook Usage
+
+```tsx
+import { useCAMSAuth } from '@nibssplc/cams-sdk-react';
+
+function LoginComponent() {
+  const { 
+    login, 
+    logout, 
+    isAuthenticated, 
+    isLoading, 
+    error, 
+    token, 
+    profile 
+  } = useCAMSAuth({
+    appCode: 'your-app-code',
+    storageKey: 'CAMS-AUTH-SDK',
+    onAuthSuccess: (token) => console.log('Login successful'),
+    onAuthError: (error) => console.error('Login failed:', error),
+  });
+
+  const handleLogin = async () => {
+    await login({
+      camsUrl: 'https://your-cams-instance.com/auth',
+      messageOrigin: 'your-cams-instance.com',
+      windowWidth: 500,
+      windowHeight: 600,
+    });
+  };
+
+  return (
+    <div>
+      {isAuthenticated ? (
+        <div>
+          <p>Welcome, {profile?.name}!</p>
+          <p>Token: {token}</p>
+          <button onClick={logout}>Logout</button>
+        </div>
+      ) : (
+        <button onClick={handleLogin} disabled={isLoading}>
+          {isLoading ? 'Logging in...' : 'Login'}
+        </button>
+      )}
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+### Azure AD MSAL Integration with MFA
 
 ```tsx
-import { CAMSMSALProvider, useCAMSMSALAuth } from '@nibssplc/cams-sdk-react';
+import { CAMSMSALProvider, useCAMSMSALContext } from '@nibssplc/cams-sdk-react';
+import { Configuration } from '@azure/msal-browser';
 
-const msalConfig = {
+const msalConfig: Configuration = {
   auth: {
     clientId: 'your-client-id',
     authority: 'https://login.microsoftonline.com/your-tenant-id',
@@ -65,7 +128,14 @@ const msalConfig = {
 
 function App() {
   return (
-    <CAMSMSALProvider msalConfig={msalConfig}>
+    <CAMSMSALProvider 
+      msalConfig={msalConfig}
+      mfaUrl="/auth/multi-factor"
+      storageKey="CAMS-MSAL-AUTH-SDK"
+      scopes={['openid', 'profile', 'email']}
+      onAuthSuccess={(token) => console.log('Auth complete:', token)}
+      onAuthError={(error) => console.error('Auth failed:', error)}
+    >
       <LoginComponent />
     </CAMSMSALProvider>
   );
@@ -75,86 +145,253 @@ function LoginComponent() {
   const { 
     login, 
     logout, 
-    completeMFA,
     isAuthenticated, 
     isLoading, 
-    isMFAPending,
-    account 
-  } = useCAMSMSALAuth({
-    scopes: ['openid', 'profile', 'email'],
-    mfaUrl: 'https://your-mfa-page.com/verify',
-    onAuthSuccess: (token) => console.log('Auth complete:', token),
-    onMFARequired: (msalToken, account) => console.log('MFA required for:', account.name),
-  });
+    error,
+    userProfile,
+    accessToken,
+    idToken
+  } = useCAMSMSALContext();
 
-  // Handle MFA completion (call this after MFA verification)
-  const handleMFAComplete = (mfaToken: string) => {
-    completeMFA(mfaToken);
-  };
+  if (error) {
+    return <div>Error: {error.message}</div>;
+  }
 
   if (isAuthenticated) {
     return (
       <div>
-        <p>Welcome, {account?.name}</p>
+        <p>Welcome, {userProfile?.name}!</p>
+        <p>Access Token: {accessToken}</p>
         <button onClick={logout}>Logout</button>
       </div>
     );
   }
 
-  if (isMFAPending) {
-    return <div>Completing MFA verification...</div>;
-  }
-
   return (
     <button onClick={login} disabled={isLoading}>
-      {isLoading ? 'Redirecting...' : 'Login with Azure AD'}
+      {isLoading ? 'Logging in...' : 'Login with Azure AD'}
     </button>
   );
 }
 ```
 
+### Direct MSAL Hook Usage
+
+```tsx
+import { useCAMSMSALAuth } from '@nibssplc/cams-sdk-react';
+import { useMsal } from '@azure/msal-react';
+
+function LoginComponent() {
+  const { 
+    login, 
+    logout, 
+    isAuthenticated, 
+    isLoading, 
+    error,
+    accessToken,
+    idToken,
+    appCode
+  } = useCAMSMSALAuth({
+    mfaUrl: '/auth/multi-factor',
+    storageKey: 'CAMS-MSAL-AUTH-SDK',
+    scopes: ['openid', 'profile', 'email'],
+    onAuthSuccess: (token) => console.log('Login successful'),
+    onAuthError: (error) => console.error('Login failed:', error),
+  });
+
+  return (
+    <div>
+      {isAuthenticated ? (
+        <div>
+          <p>Access Token: {accessToken}</p>
+          <p>ID Token: {idToken}</p>
+          <button onClick={logout}>Logout</button>
+        </div>
+      ) : (
+        <button onClick={login} disabled={isLoading}>
+          {isLoading ? 'Logging in...' : 'Login with Azure AD'}
+        </button>
+      )}
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
 ## API Reference
 
+### useCAMSAuth
+
+Hook for popup-based CAMS authentication.
+
+```tsx
+const {
+  login,           // (config: CAMSConfig) => Promise<void>
+  logout,          // () => Promise<void>
+  isAuthenticated, // boolean
+  isLoading,       // boolean
+  error,           // CAMSError | null
+  token,           // string | null
+  profile,         // Profile | null
+  appCode,         // string
+  storageKey,      // string
+} = useCAMSAuth(options);
+```
+
+**Options:**
+- `appCode: string` - Application code (required)
+- `storageKey?: string` - Storage key (default: "CAMS-AUTH-SDK")
+- `onAuthSuccess?: (token: string) => void` - Success callback
+- `onAuthError?: (error: CAMSError) => void` - Error callback
+- `onTokenExpired?: () => void` - Token expiration callback
+
 ### useCAMSMSALAuth
 
-Hook for MSAL redirect authentication.
+Hook for Azure AD MSAL authentication with MFA support.
 
 ```tsx
 const {
-  login,
-  logout,
-  isAuthenticated,
-  isLoading,
-  error,
-  token,
-  profile,
-  account
+  login,           // () => Promise<void>
+  logout,          // () => Promise<void>
+  isAuthenticated, // boolean
+  isLoading,       // boolean
+  error,           // CAMSError | null
+  idToken,         // string
+  accessToken,     // string
+  appCode,         // string
+  storageKey,      // string
 } = useCAMSMSALAuth(options);
 ```
 
 **Options:**
-- `scopes?: string[]` - OAuth scopes (default: `['openid', 'profile', 'email']`)
-- `mfaUrl?: string` - Custom MFA page URL for redirect after MSAL login
-- `onAuthSuccess?: (token: string) => void` - Success callback (after MFA completion)
+- `mfaUrl?: string` - MFA URL (default: "/auth/multi-factor")
+- `storageKey?: string` - Storage key (default: "CAMS-MSAL-AUTH-SDK")
+- `scopes?: string[]` - MSAL scopes (default: ["openid", "profile", "email"])
+- `prompt?: string` - MSAL prompt (default: "login")
+- `allowedOrigins?: string[]` - Allowed message origins
+- `messageOrigin?: string` - Expected message origin
+- `onAuthSuccess?: (token: string) => void` - Success callback
 - `onAuthError?: (error: CAMSError) => void` - Error callback
-- `onTokenExpired?: () => void` - Token expiration callback
-- `onMFARequired?: (msalToken: string, account: AccountInfo) => void` - MFA required callback
 
-**Returns:**
-- `completeMFA: (mfaToken: string) => void` - Complete MFA verification
-- `isMFAPending: boolean` - Whether MFA verification is pending
+### CAMSProvider
+
+Provider component for popup-based authentication.
+
+```tsx
+<CAMSProvider 
+  appCode="your-app-code" 
+  storageKey="CAMS-AUTH-SDK"
+  onAuthSuccess={(token) => console.log('Success')}
+  onAuthError={(error) => console.error('Error:', error)}
+  onTokenExpired={() => console.log('Token expired')}
+>
+  {children}
+</CAMSProvider>
+```
 
 ### CAMSMSALProvider
 
-Provider component for MSAL integration.
+Provider component for Azure AD MSAL integration.
 
 ```tsx
-<CAMSMSALProvider msalConfig={config} msalInstance={instance}>
+<CAMSMSALProvider 
+  msalConfig={config} 
+  msalInstance={instance}
+  mfaUrl="/auth/multi-factor"
+  storageKey="CAMS-MSAL-AUTH-SDK"
+  scopes={['openid', 'profile', 'email']}
+  onAuthSuccess={(token) => console.log('Success')}
+  onAuthError={(error) => console.error('Error:', error)}
+>
   {children}
 </CAMSMSALProvider>
 ```
 
 **Props:**
-- `msalConfig: Configuration` - MSAL configuration object
+- `msalConfig: Configuration` - MSAL configuration object (required)
 - `msalInstance?: PublicClientApplication` - Optional pre-configured MSAL instance
-- `children: ReactNode` - Child components
+- `children: ReactNode` - Child components
+- All `UseCAMSMSALAuthOptions` are also supported as props
+
+### Context Hooks
+
+#### useCAMSContext
+
+Access CAMS authentication context (must be used within `CAMSProvider`).
+
+```tsx
+const {
+  login, logout, isAuthenticated, isLoading, error, token, profile,
+  userProfile, setUserProfile, appCode, storageKey
+} = useCAMSContext();
+```
+
+#### useCAMSMSALContext
+
+Access CAMS MSAL authentication context (must be used within `CAMSMSALProvider`).
+
+```tsx
+const {
+  login, logout, isAuthenticated, isLoading, error, 
+  idToken, accessToken, appCode, storageKey,
+  userProfile, setUserProfile
+} = useCAMSMSALContext();
+```
+
+### Components
+
+#### ProtectedRoute
+
+Route component that requires authentication.
+
+```tsx
+<ProtectedRoute fallback={<LoginPage />}>
+  <Dashboard />
+</ProtectedRoute>
+```
+
+#### ClientOnly
+
+Wrapper component for client-side only rendering (useful for SSR).
+
+```tsx
+<ClientOnly fallback={<div>Loading...</div>}>
+  <CAMSProvider>
+    <App />
+  </CAMSProvider>
+</ClientOnly>
+```
+
+## Types
+
+### Profile
+
+```typescript
+interface Profile {
+  userProfile: {
+    name: string;
+    image?: string | null;
+    tokens: {
+      Bearer: string;
+    };
+  };
+}
+```
+
+### CAMSError
+
+```typescript
+class CAMSError extends Error {
+  constructor(public type: CAMSErrorType, message: string);
+}
+
+enum CAMSErrorType {
+  POPUP_BLOCKED = "POPUP_BLOCKED",
+  TIMEOUT = "TIMEOUT",
+  INVALID_ORIGIN = "INVALID_ORIGIN",
+  USER_CANCELLED = "USER_CANCELLED",
+  INVALID_URL = "INVALID_URL",
+  MAX_RETRIES_EXCEEDED = "MAX_RETRIES_EXCEEDED",
+  API_VALIDATION_ERROR = "VALIDATION_ERROR",
+}
+```

package/dist/components/CAMSProvider.d.ts

@@ -1,18 +1,13 @@
-import { ReactNode } from 'react';
-import { CAMSConfig } from '@nibssplc/cams-sdk';
+import React from "react";
+import { Profile } from '@nibssplc/cams-sdk';
 import { UseCAMSAuthReturn, UseCAMSAuthOptions } from '../hooks/useCAMSAuth';
-import { UseCAMSMSALAuthOptions } from '../hooks/useCAMSMSALAuth';
 interface CAMSContextValue extends UseCAMSAuthReturn {
-    defaultConfig?: Partial<CAMSConfig>;
-    isAuthenticated: boolean;
-    idToken: string | null;
-    accessToken: string | null;
+    userProfile: Profile | null;
+    setUserProfile: (profile: Profile | null) => void;
 }
 export interface CAMSProviderProps extends UseCAMSAuthOptions {
-    children: ReactNode;
-    defaultConfig?: Partial<CAMSConfig>;
-    msalOptions?: UseCAMSMSALAuthOptions;
+    children: React.ReactNode;
 }
-export declare function CAMSProvider({ children, defaultConfig, msalOptions, ...authOptions }: CAMSProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function CAMSProvider({ children, ...authOptions }: Readonly<CAMSProviderProps>): import("react/jsx-runtime").JSX.Element;
 export declare function useCAMSContext(): CAMSContextValue;
 export {};

package/dist/hooks/useCAMSAuth.d.ts

@@ -1,5 +1,6 @@
-import { CAMSConfig, CAMSError, Profile } from '@nibssplc/cams-sdk';
+import { CAMSConfig, CAMSError, Profile } from "@nibssplc/cams-sdk";
 export interface UseCAMSAuthOptions {
+    appCode: string;
     storageKey?: string;
     onAuthSuccess?: (token: string) => void;
     onAuthError?: (error: CAMSError) => void;
@@ -13,5 +14,7 @@ export interface UseCAMSAuthReturn {
     error: CAMSError | null;
     token: string | null;
     profile: Profile | null;
+    appCode: string;
+    storageKey: string;
 }
 export declare function useCAMSAuth(options?: UseCAMSAuthOptions): UseCAMSAuthReturn;

package/dist/hooks/useCAMSMSALAuth.d.ts

@@ -4,9 +4,11 @@ export interface UseCAMSMSALAuthOptions {
     onAuthError?: (error: CAMSError) => void;
     onTokenExpired?: () => void;
     scopes?: string[];
+    storageKey?: string;
     mfaUrl?: string;
     prompt?: string;
     messageOrigin?: string;
+    allowedOrigins?: string[];
 }
 export interface UseCAMSMSALAuthReturn {
     login: () => Promise<void>;