feat: architectural refactor for multi-platform extensibility

[subhankarmaiti]

Summary & Motivation

This pull request introduces a major architectural refactor of the react-native-auth0 library. The primary goal is to evolve from the existing tightly-coupled implementation to a highly abstracted, modular, and extensible architecture that cleanly supports multiple platforms (Native and Web) in a maintainable way.

The previous structure made it difficult to add new features or platforms without significant code duplication and risk of regressions. This new architecture establishes a clear separation of concerns, making the library more robust, performant, and easier for future contributors to understand and extend.

The New Architecture

The new design is built on the Dependency Inversion Principle, using a Factory pattern to provide the correct platform-specific implementation at build time. High-level modules (like the React hooks) are now completely decoupled from low-level platform details (the native bridge or auth0-spa-js).

High-Level Diagram

This diagram illustrates the new flow of control. The key concept is that the consumer-facing API is decoupled from the platform implementations via a Factory that chooses the correct module at build time.

graph TD
    subgraph " "
        direction LR
        A["React Hooks / Developer"]
    end
    
    A --> B[Auth0 Facade Class];
    B --> C{Auth0ClientFactory};
    
    subgraph " "
        direction LR
        C -- instantiates --> D["IAuth0Client (The Contract)"];
    end
    
    subgraph "Platform Implementations"
        direction LR
        subgraph " "
            E[NativeAuth0Client] --> D;
        end
        subgraph " "
            F[WebAuth0Client] --> D;
        end
    end

    subgraph " "
        direction LR
        E -- uses --> G[Native Bridge & Adapters];
    end
    
    subgraph " "
        direction LR
        F -- uses --> H[auth0-spa-js & Adapters];
    end

    G --> I[iOS / Android];
    H --> J[Browser];

    style A fill:#cde4ff,stroke:#6a9fde,stroke-width:2px
    style B fill:#d5e8d4,stroke:#82b366,stroke-width:2px
    style C fill:#d5e8d4,stroke:#82b366,stroke-width:2px
    style D fill:#fff2cc,stroke:#d6b656,stroke-width:2px

Loading

Key Architectural Components

1. src/core: The platform-agnostic heart of the library.

   • interfaces: Defines the "contract" for what our client can do (IAuth0Client, IWebAuthProvider, etc.). This is the cornerstone of the abstraction.
   • models: Concrete data models like Auth0User and Credentials that encapsulate data and related logic (e.g., isExpired()).
   • services: "Orchestrator" classes that contain the business logic for authentication flows (e.g., CredentialsOrchestrator handles the token refresh flow).

2. src/platforms: Contains the platform-specific implementations.

   • native: The complete module for iOS and Android, containing the NativeBridgeManager for low-level communication and a set of adapters that implement the core interfaces.
   • web: The complete module for React Native Web, containing a set of adapters that wrap the @auth0/auth0-spa-js library to make it conform to our core interfaces.

3. src/factory: The "decision-making" layer that runs at build time.

   • Uses platform-specific file extensions (.ts, .web.ts) to ensure the bundler (Metro/Webpack) includes only the code for the target platform. This completely severs the dependency on @auth0/auth0-spa-js in native builds.

4. src/hooks & src/index.ts (Public API):

   • The Auth0 class now acts as a simple Facade, which uses the factory to get the correct client. This maintains backward compatibility.
   • The Auth0Provider uses this facade to power the useAuth0 hook, providing a seamless and performant stateful experience. Issues with UI hanging on logout and infinite re-renders have been fixed.

Key Breaking Changes for Users

A full MIGRATION_GUIDE.md has been created, but the most critical changes are:

1. camelCase Properties: Properties on the user object are now camelCase (e.g., user.givenName instead of user.given_name).
2. expiresAt Timestamp: The Credentials object now provides a expiresAt UNIX timestamp instead of expiresIn.
3. Unified AuthError: All errors are now instances of a single, consistent AuthError class.
4. Separated Method Arguments: Methods like authorize now separate OIDC parameters and SDK options into two distinct arguments: authorize({scope}, {options}).

Testing Strategy

A comprehensive, co-located test suite has been implemented for the new architecture.

• All legacy test cases have been migrated to validate the new components, ensuring full functional parity.
• The testing setup now uses a global __mocks__ directory for react-native, creating a clean and stable test environment.
• The new structure is significantly more unit-testable, allowing for isolated testing of core services, adapters, and utilities.

How to Review This PR

Given the scope of the refactor, a commit-by-commit review is highly recommended. The commits have been structured logically to tell the story of the new architecture's construction:

1. feat(core): Introduce foundational types and interfaces...: Establishes the core contracts.
2. feat(core): Implement core data models and utility functions...: Adds the reusable building blocks.
3. feat(core): Implement platform-agnostic service orchestrators...: Introduces the platform-agnostic business logic.
4. feat(factory): Implement platform detector and client factory...: Builds the platform-selection mechanism.
5. feat(platform): Implement native platform...: Adds the complete native implementation.
6. feat(platform): Implement web platform...: Adds the complete web implementation.
7. feat(hooks): Implement public Auth0 facade and update hooks...: Wires everything up to the consumer-facing API.
8. test: Implement comprehensive test suite...: Adds all the new tests.

[nandan-bhat]

We are trying to access response.json() even when response.status is 400, 403, or 500. Is this expected ?

[nandan-bhat]

Does it handle already encoded query ?
Ignore this comment if this use-case is irrelevant here.

[nandan-bhat]

Does baseUrl always contain / ?

[nandan-bhat]

Can useAuth0 be used anywhere ?
Or should we need to add a check like this ?

const context = useContext(Auth0Context);              
if (context == null) {                                  
  throw new Error('useAuth0 must be used within Auth0Provider');
}
return context;

I don't know the complete spec here. Ignore if it's irrelevant.

[nandan-bhat]

I think snakeToCamel('_snake_case_') would return SnakeCase here, but the expectation is snakeCase.

Again, this is a very minor one 😅

[nandan-bhat]

Should we document this error in Typedoc using @throws ?

[nandan-bhat]

Should we handle the error thrown by jwtDecode ? So that developer can know exactly what went wrong ?

Ignore if it's already handled inside jwtDecode.

[nandan-bhat]

These days we drop the I on interface names and stick to plain PascalCase (so Auth0Client instead of IAuth0Client). No need to fix it right now. Revisit this whenever you get time.

Reference: https://www.typescriptlang.org/docs/handbook/interfaces.html#interfaces