feat: architectural refactor for multi-platform extensibility

.husky/pre-push

@@ -0,0 +1 @@
+npm run prepush

.shiprc

@@ -1,6 +1,6 @@
 {
     "files": {
-        "src/networking/telemetry.ts": [],
+        "src/core/utils/telemetry.ts": [],
         ".version": []
     },
     "postbump": "node scripts/jsdocs.js"

EXAMPLES-WEB.md

@@ -0,0 +1,171 @@
+# React Native Auth0 for Web: Examples
+
+This guide provides usage examples specifically for developers targeting **React Native Web**. The web platform uses the underlying `@auth0/auth0-spa-js` library, and its features are aligned with browser security best practices.
+
+## 1. The Hooks-Based Approach (Recommended)
+
+This is the simplest and recommended way to integrate Auth0. The `Auth0Provider` handles all the complexity of the redirect flow automatically.
+
+### Step 1: Wrap Your App in the `Auth0Provider`
+
+In your main application entry point (e.g., `App.tsx`), wrap your application with the provider.
+
+```jsx
+// src/App.tsx
+import React from 'react';
+import { Auth0Provider } from 'react-native-auth0';
+import config from './auth0-configuration';
+import MainComponent from './MainComponent'; // Your main app UI
+
+const App = () => (
+  <Auth0Provider domain={config.domain} clientId={config.clientId}>
+    <MainComponent />
+  </Auth0Provider>
+);
+
+export default App;
+```
+
+### Step 2: Use the `useAuth0` Hook in Your Components
+
+The `Auth0Provider` will automatically handle the redirect callback when your app loads. The `useAuth0` hook will then provide the authentication state.
+
+```jsx
+// src/MainComponent.tsx
+import React from 'react';
+import { useAuth0 } from 'react-native-auth0';
+import { View, Button, Text, ActivityIndicator } from 'react-native';
+
+const MainComponent = () => {
+  const { authorize, clearSession, user, isLoading, error } = useAuth0();
+
+  const onLogin = async () => {
+    try {
+      // This triggers a redirect to the Auth0 Universal Login page.
+      await authorize({ scope: 'openid profile email' });
+    } catch (e) {
+      console.error('Login error:', e);
+    }
+  };
+
+  const onLogout = async () => {
+    try {
+      await clearSession();
+    } catch (e) {
+      console.error('Logout error:', e);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <View>
+        <ActivityIndicator size="large" />
+      </View>
+    );
+  }
+
+  return (
+    <View>
+      {error && <Text>Error: {error.message}</Text>}
+      {user ? (
+        <>
+          <Text>Welcome, {user.name}!</Text>
+          <Button title="Log Out" onPress={onLogout} />
+        </>
+      ) : (
+        <Button title="Log In" onPress={onLogin} />
+      )}
+    </View>
+  );
+};
+```
+
+## 2. The Class-Based / Manual Approach
+
+If you are not using React Hooks or need more fine-grained control, you can instantiate the `Auth0` class and handle the redirect callback manually.
+
+### Step 1: Instantiate the `Auth0` Client
+
+Create a singleton instance of the client.
+
+```javascript
+// src/api/auth0.ts
+import Auth0 from 'react-native-auth0';
+import config from '../auth0-configuration';
+
+const auth0 = new Auth0({
+  domain: config.domain,
+  clientId: config.clientId,
+});
+
+export default auth0;
+```
+
+### Step 2: Handle the Redirect Callback
+
+In your application's root component or entry point, you need to add logic to process the result from Auth0 after the user is redirected back.
+
+```jsx
+// src/App.tsx
+import React, { useEffect, useState } from 'react';
+import { View, Button, Text } from 'react-native';
+import auth0 from './api/auth0'; // Import your singleton
+import type { User } from 'react-native-auth0';
+
+const App = () => {
+  const [user, setUser] = useState<User | null>(null);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    const checkSession = async () => {
+      // Check if the URL contains redirect parameters
+      if (window.location.search.includes('code=') && window.location.search.includes('state=')) {
+        try {
+          // Process the redirect
+          await auth0.webAuth.handleRedirectCallback();
+        } catch (e) {
+          console.error(e);
+        }
+        // Clean the URL
+        window.history.replaceState({}, document.title, '/');
+      }
+
+      // After handling a potential redirect, check for an existing session
+      try {
+        const credentials = await auth0.credentialsManager.getCredentials();
+        // Assuming you have a way to decode the idToken to get the user
+        // const decodedUser = jwt_decode(credentials.idToken);
+        // setUser(decodedUser);
+      } catch (e) {
+        // No credentials, user is not logged in
+        setUser(null);
+      }
+      setIsLoading(false);
+    };
+
+    checkSession();
+  }, []);
+
+  const onLogin = async () => {
+    await auth0.webAuth.authorize({ scope: 'openid profile email' });
+  };
+
+  const onLogout = async () => {
+    await auth0.webAuth.clearSession();
+  };
+
+  // ... Render UI based on isLoading and user state ...
+};
+```
+
+## Unsupported Web Features
+
+For security reasons, the web platform **does not support** direct authentication grants. The following methods from the `auth` provider will throw a `NotImplemented` error:
+
+- `auth.passwordRealm()`
+- `auth.loginWithOTP()`
+- `auth.loginWithSMS()`
+- `auth.loginWithEmail()`
+- `auth.refreshToken()`
+
+All these flows should be configured in your [Auth0 Universal Login](https://auth0.com/docs/universal-login) page and initiated via the `authorize()` method.

MIGRATION_GUIDE.md

@@ -2,69 +2,159 @@
 
 ## Upgrading from v4 -> v5
 
-### Compatibility Requirements
+Version 5.0 of `react-native-auth0` is a significant update featuring a complete architectural overhaul. This new foundation improves performance, maintainability, and provides a more consistent API across all platforms.
 
-- **React**: v5 requires React 19 or higher
-- **React Native**: v5 requires React Native 0.78.0 or higher
-- **Expo**: v5 requires Expo 53 or higher
+Upgrading from v4.x requires addressing several breaking changes. Please follow this guide carefully.
 
-### Breaking Changes
+## 1. Compatibility & Installation
 
-- **Platform Compatibility**: The minimum iOS deployment target is now 14.0. Update your iOS/Podfile with:
+Before updating the library, ensure your project meets the new minimum requirements.
 
-  ```
-  platform :ios, '14.0'
-  ```
+### Environment Requirements
 
-- **Android Requirements**: Android SDK API level 35 or higher is now required
+- **React:** `19.0.0` or higher
+- **React Native:** `0.78.0` or higher
+- **Expo:** SDK `53` or higher
+- **iOS:** Deployment Target `14.0`
+- **Android:** Target SDK `35` or higher
 
-### Migration Steps
+### Updating Your Project
 
-#### For Regular React Native Projects
+#### For Standard React Native Projects:
 
-1. First, ensure your project uses React 19 and React Native 0.78.0 or higher:
+1.  **Upgrade React Native:**
+    ```bash
+    npm install react@^19.0.0 react-native@^0.78.0
+    ```
+2.  **Update this Library:**
+    ```bash
+    npm install react-native-auth0@beta
+    ```
+3.  **Update iOS Target:** In your `ios/Podfile`, set the platform version:
+    ```ruby
+    platform :ios, '14.0'
+    ```
+4.  **Install Pods:**
+    ```bash
+    cd ios && pod install && cd ..
+    ```
 
-   ```bash
-   npm install react@^19.0.0
-   npm install react-native@^0.78.0
-   ```
+#### For Expo Projects:
 
-2. Update the react-native-auth0 package:
+1.  **Upgrade Expo SDK:**
+    ```bash
+    npx expo upgrade
+    ```
+2.  **Update this Library:**
+    ```bash
+    npm install react-native-auth0@beta
+    ```
+3.  **Rebuild Native Code:**
+    ```bash
+    npx expo prebuild --clean
+    ```
+    > **Warning:** This will overwrite any manual changes in your `ios` and `android` directories.
 
-   ```bash
-   npm install react-native-auth0@beta
-   ```
+## 2. Breaking API Changes
 
-3. Update your iOS minimum deployment target in your Podfile:
+The following API changes require code modifications in your application.
 
-   ```ruby
-   platform :ios, '14.0'
-   ```
+### Change #1: User Profile Properties are now `camelCase`
 
-4. Install the updated pods:
-   ```bash
-   cd ios && pod install && cd ..
-   ```
+To align with modern JavaScript standards, all properties on the `user` object are now `camelCase`.
 
-#### For Expo Projects
+**✅ Action Required:** Update all references to `user` properties.
 
-1. Update to Expo 53 or higher:
+| Before (snake_case)   | After (camelCase)    |
+| :-------------------- | :------------------- |
+| `user.given_name`     | `user.givenName`     |
+| `user.family_name`    | `user.familyName`    |
+| `user.email_verified` | `user.emailVerified` |
+| `user.phone_number`   | `user.phoneNumber`   |
+| ...and so on.         |                      |
 
-   ```bash
-   npx expo upgrade
-   ```
+### Change #2: Credentials Object uses `expiresAt`
 
-2. Update the react-native-auth0 package:
+The `Credentials` object no longer includes `expiresIn` (a duration). It now provides `expiresAt`, an absolute **UNIX timestamp** (in seconds), making expiration checks simpler and less error-prone.
 
-   ```bash
-   npm install react-native-auth0@beta
-   ```
+**✅ Action Required:** Replace all logic using `expiresIn` with `expiresAt`.
 
-3. Rebuild your app:
-   ```bash
-   npx expo prebuild --clean
-   ```
-   Note: This will reset any manual changes to your native code.
+**Before:**
+
+```javascript
+const expiresAt = Date.now() / 1000 + credentials.expiresIn;
+if (isExpired(expiresAt)) {
+  // ...
+}
+```
+
+**After:**
+
+```javascript
+// Direct comparison is now possible
+if (credentials.expiresAt < Date.now() / 1000) {
+  // ...
+}
+
+// Or, use the new helper method (if you have an instance of the Credentials model):
+if (credentials.isExpired()) {
+  // ...
+}
+```
+
+### Change #3: Standardized `AuthError` Object
+
+All errors thrown by the library are now instances of a single, consistent `AuthError` class. This replaces multiple error types like `CredentialsManagerError`.
+
+**✅ Action Required:** Update your `try...catch` blocks to handle the new unified error object.
+
+**Before:**
+
+```javascript
+catch (e) {
+  // Inconsistent properties like e.error, e.error_description
+  console.error(e.message);
+}
+```
+
+**After:**
+
+```javascript
+import { AuthError } from 'react-native-auth0';
+
+catch (e) {
+  if (e instanceof AuthError) {
+    // Consistent properties are now available
+    console.error(e.name, e.message); // e.g., 'invalid_grant', 'The refresh token is invalid.'
+  }
+}
+```
+
+### Change #4: Updated `authorize` and `clearSession` Signatures
+
+For improved clarity, SDK-specific options (like `ephemeralSession`) have been moved into a separate, second `options` object.
+
+**✅ Action Required:** Restructure calls to `authorize` and `clearSession`.
+
+**Before:**
+
+```javascript
+// Mixed parameters and options
+await authorize({
+  scope: 'openid profile',
+  ephemeralSession: true,
+});
+```
+
+**After:**
+
+```javascript
+// Parameters and options are now separate arguments
+await authorize(
+  { scope: 'openid profile' }, // 1. OIDC / Auth0 Parameters
+  { ephemeralSession: true } // 2. SDK-Specific Options
+);
+```
 
 ## Upgrading from v3 -> v4