@ttoss/react-auth 2.6.30 → 2.6.32

package/README.md

@@ -1,178 +1,147 @@
 # @ttoss/react-auth
 
-This module handles auth in your applications and other ttoss modules.
+AWS Cognito authentication module for React applications using AWS Amplify, built on top of `@ttoss/react-auth-core` for provider-agnostic authentication patterns.
 
-This module is intended to use with AWS Cognito. It uses [AWS Amplify](https://docs.amplify.aws/lib/auth/getting-started/q/platform/js) under the hood.
+## Installation
 
-[Amplify Auth configuration](https://docs.amplify.aws/lib/auth/start/q/platform/js#re-use-existing-authentication-resource) must be provided in your App to make Auth Module works properly.
-
-## ESM Only
+```shell
+pnpm add @ttoss/react-auth @ttoss/react-notifications aws-amplify
+```
 
-This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c).
+## Core Concepts
 
-## Getting Started
+This package provides AWS Cognito-specific implementations of the authentication patterns defined in `@ttoss/react-auth-core`. It automatically handles Amplify configuration, auth state management, and integrates with ttoss notification system.
 
-### Install
+**Key Features:**
 
-```shell
-$ yarn add @ttoss/auth @ttoss/react-notifications aws-amplify
-```
+- AWS Cognito authentication with Amplify
+- Automatic auth state synchronization
+- Built-in error handling and notifications
+- TypeScript support with full type safety
+- ESM-only package
 
-## Examples of use
+## Quick Start
 
-### Amplify config
+### 1. Configure AWS Amplify
 
 ```ts
 import { Amplify, type ResourcesConfig } from 'aws-amplify';
-import {
-  CookieStorage,
-  KeyValueStorageInterface,
-  defaultStorage,
-  sessionStorage,
-} from 'aws-amplify/utils';
-import { cognitoUserPoolsTokenProvider } from 'aws-amplify/auth/cognito';
 
+/**
+ * https://docs.amplify.aws/gen1/react/build-a-backend/auth/set-up-auth/
+ */
 const authConfig: ResourcesConfig['Auth'] = {
   Cognito: {
-    // REQUIRED Amazon Cognito User Pool Client ID (26-char alphanumeric string)
-    userPoolClientId: 'a1b2c3d4e5f6g7h8i9j0k1l2m3',
-
-    // OPTIONAL - Amazon Cognito User Pool ID
-    userPoolId: 'XX-XXXX-X_abcd1234',
-
-    loginWith: {
-      // OPTIONAL - Hosted UI configuration
-      oauth: {
-        domain: 'your_cognito_domain',
-        scopes: [
-          'phone',
-          'email',
-          'profile',
-          'openid',
-          'aws.cognito.signin.user.admin',
-        ],
-        redirectSignIn: ['http://localhost:3000/'],
-        redirectSignOut: ['http://localhost:3000/'],
-        responseType: 'code', // or 'token', note that REFRESH token will only be generated when the responseType is code
-      },
-    },
+    // ... your Cognito config
   },
 };
 
-Amplify.configure({
-  Auth: authConfig,
-});
-
-// Browser Local Storage
-// In Amplify the localStorage is the default storage mechanism. It saves the tokens in the browser's localStorage.
-// This local storage will persist across browser sessions and tabs. You can explicitly set to this storage by calling:
-cognitoUserPoolsTokenProvider.setKeyValueStorage(defaultStorage);
-
-// Cookie Storage
-// CookieStorage saves the tokens in the browser's Cookies. The cookies will persist across browser sessions and tabs.
-// You can explicitly set to this storage by calling:
-cognitoUserPoolsTokenProvider.setKeyValueStorage(
-  new CookieStorage(
-    // OPTIONAL - Configuration for cookie storage
-    {
-      // REQUIRED - Cookie domain (only required if cookieStorage is provided)
-      domain: '.yourdomain.com',
-      // OPTIONAL - Cookie path
-      path: '/',
-      // OPTIONAL - Cookie expiration in days
-      expires: 365,
-      // OPTIONAL - See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite
-      sameSite: 'strict' | 'lax' | 'none',
-      // OPTIONAL - Cookie secure flag
-      // Either true or false, indicating if the cookie transmission requires a secure protocol (https).
-      secure: true,
-    }
-  )
-);
+Amplify.configure({ Auth: authConfig });
+```
 
-// Browser Session Storage
-// sessionStorage saves the tokens in the browser's sessionStorage and these tokens will clear when a tab is closed.
-// The benefit to this storage mechanism is that the session only lasts as long as the browser is open and you
-// can sign out users when they close the tab. You can update to this storage by calling:
-cognitoUserPoolsTokenProvider.setKeyValueStorage(sessionStorage);
+### 2. Setup Authentication Provider
 
-// Custom Storage
-// You can implement your own custom storage mechanism by creating a class that implements the storage interface.
-// Here is an example that uses memory storage:
+```tsx
+import { AuthProvider } from '@ttoss/react-auth';
+import { NotificationsProvider } from '@ttoss/react-notifications';
 
-class MyCustomStorage implements KeyValueStorageInterface {
-  storageObject: Record<string, string> = {};
-  async setItem(key: string, value: string): Promise<void> {
-    this.storageObject[key] = value;
-  }
-  async getItem(key: string): Promise<string | null> {
-    return this.storageObject[key];
-  }
-  async removeItem(key: string): Promise<void> {
-    delete this.storageObject[key];
-  }
-  async clear(): Promise<void> {
-    this.storageObject = {};
-  }
+function App() {
+  return (
+    <NotificationsProvider>
+      <AuthProvider>
+        <YourApp />
+      </AuthProvider>
+    </NotificationsProvider>
+  );
 }
-
-cognitoUserPoolsTokenProvider.setKeyValueStorage(new MyCustomStorage());
 ```
 
-### PrivateRoute component
+### 3. Use Authentication in Components
 
 ```tsx
-import { useAuth } from '@ttoss/react-auth';
+import { Auth, useAuth } from '@ttoss/react-auth';
+import { Navigate } from 'react-router-dom';
+
+// Authentication form component
+function LoginPage() {
+  return <Auth />;
+}
 
-const PrivateRoute = (props: any) => {
+// Protected route component
+function PrivateRoute({ children }: { children: React.ReactNode }) {
   const { isAuthenticated } = useAuth();
 
   if (!isAuthenticated) {
-    return <Navigate to="/login" state={{ redirectTo: props.path || '/' }} />;
+    return <Navigate to="/login" />;
   }
-  return <Route {...props} />;
-};
+
+  return <>{children}</>;
+}
+
+// Using auth state
+function UserProfile() {
+  const { user, signOut } = useAuth();
+
+  return (
+    <div>
+      <h1>Welcome, {user?.email}</h1>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
 ```
 
-### Login Page
+## API Reference
 
-```tsx
-import { Auth, useAuth } from '@ttoss/react-auth';
+### `useAuth()`
 
-const Login = () => {
-  const auth = useAuth();
+Returns authentication state and methods:
 
-  const onSuccess = () => {
-    // Navigate to logged-area
-  };
+```tsx
+const {
+  user, // Current user data or null
+  isAuthenticated, // Boolean authentication status
+  signOut, // Function to sign out user
+} = useAuth();
+```
 
-  return (
-    <div>
-      <h1>Login Page</h1>
+### `getAuthData(options?)`
 
-      <Auth onSignIn={onSuccess} />
+Retrieve current authentication data programmatically:
 
-      <button onClick={auth.signOut}>Logout</button>
-    </div>
-  );
-};
-export default Login;
+```tsx
+import { getAuthData } from '@ttoss/react-auth';
+
+const authData = await getAuthData({ includeTokens: true });
 ```
 
-## Auth with Progressbar
+### `checkAuth()`
+
+Check if user is currently authenticated:
 
 ```tsx
-import { AuthProvider } from '@ttoss/react-auth';
-import { NotificationsProvider } from '@ttoss/react-notifications';
+import { checkAuth } from '@ttoss/react-auth';
 
-ReactDOM.render(
-  <React.StrictMode>
-    <NotificationsProvider>
-      <AuthProvider>
-        <App />
-      </AuthProvider>
-    </NotificationsProvider>
-  </React.StrictMode>,
-  document.getElementById('root')
+const isAuthenticated = await checkAuth();
+```
+
+## Storage Configuration
+
+Configure token storage mechanism using Amplify's storage options:
+
+```ts
+import { cognitoUserPoolsTokenProvider } from 'aws-amplify/auth/cognito';
+import { CookieStorage, sessionStorage } from 'aws-amplify/utils';
+
+// Cookie storage (recommended for production)
+cognitoUserPoolsTokenProvider.setKeyValueStorage(
+  new CookieStorage({
+    domain: '.yourdomain.com',
+    secure: true,
+    sameSite: 'strict',
+  })
 );
+
+// Session storage (clears on tab close)
+cognitoUserPoolsTokenProvider.setKeyValueStorage(sessionStorage);
 ```