docs: update examples and README to use RefreshTokenMode enum for online access

Author: subhankarmaiti

EXAMPLES.md

@@ -219,22 +219,24 @@ This makes ORTs a good fit for SPAs that want a refresh-token renewal path whose
 
 ### Enabling Online Access
 
-Set `refreshTokenMode: 'online'` together with `useRefreshTokens: true` and `useDpop: true`:
+Set `refreshTokenMode` to `RefreshTokenMode.Online` together with `useRefreshTokens: true` and `useDpop: true`:
 
 ```js
+import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
 const auth0 = await createAuth0Client({
   domain: '<AUTH0_DOMAIN>',
   clientId: '<AUTH0_CLIENT_ID>',
   useRefreshTokens: true, // required — online access is a refresh-token grant
-  refreshTokenMode: 'online',
+  refreshTokenMode: RefreshTokenMode.Online,
   useDpop: true, // required — DPoP is mandatory for online access
   authorizationParams: {
     redirect_uri: '<MY_CALLBACK_URL>'
   }
 });
 ```
 
-`refreshTokenMode` is a sub-option of `useRefreshTokens`. It defaults to `'offline'` (the rotating [offline refresh tokens](#refresh-tokens) described above); setting it to `'online'` opts into Online Refresh Tokens.
+`refreshTokenMode` is a sub-option of `useRefreshTokens`. It defaults to `RefreshTokenMode.Offline` (the rotating [offline refresh tokens](#refresh-tokens) described above); setting it to `RefreshTokenMode.Online` opts into Online Refresh Tokens. Always reference the exported `RefreshTokenMode` enum rather than hard-coding the mode.
 
 Enabling this option causes the SDK to:
 
@@ -243,16 +245,16 @@ Enabling this option causes the SDK to:
 - Store the non-rotating ORT in the existing cache and reuse it on every refresh, never replacing it.
 
 > [!NOTE]
-> Online access is **opt-in**. When `refreshTokenMode` is unset or `'offline'`, the SDK behaves exactly as before.
+> Online access is **opt-in**. When `refreshTokenMode` is unset or `RefreshTokenMode.Offline`, the SDK behaves exactly as before.
 
 > [!NOTE]
 > This feature requires the `online_refresh_tokens` flag to be enabled for your tenant and `allow_online_access` to be enabled on the resource server (on by default).
 
-### `refreshTokenMode: 'offline'` vs. `'online'`
+### `RefreshTokenMode.Offline` vs. `RefreshTokenMode.Online`
 
-`refreshTokenMode` selects which refresh-token type the refresh-token grant uses. It is a sub-option of `useRefreshTokens` (which must be `true` for either mode) and defaults to `'offline'`:
+`refreshTokenMode` selects which refresh-token type the refresh-token grant uses. It is a sub-option of `useRefreshTokens` (which must be `true` for either mode) and defaults to `RefreshTokenMode.Offline`:
 
-| | `refreshTokenMode: 'offline'` (default) | `refreshTokenMode: 'online'` |
+| | `RefreshTokenMode.Offline` (default) | `RefreshTokenMode.Online` |
 | --- | --- | --- |
 | Requires | `useRefreshTokens: true` | `useRefreshTokens: true` + `useDpop: true` |
 | Scope injected | `offline_access` | `online_access` |
@@ -266,32 +268,34 @@ The two modes inject mutually exclusive scopes (`offline_access` vs. `online_acc
 
 The SDK enforces the DPoP requirement at two layers:
 
-1. **Compile-time (TypeScript).** When you call `createAuth0Client` with `refreshTokenMode` set to the literal `'online'`, the compiler requires both `useRefreshTokens: true` and `useDpop: true`:
+1. **Compile-time (TypeScript).** When you call `createAuth0Client` with `refreshTokenMode: RefreshTokenMode.Online`, the compiler requires both `useRefreshTokens: true` and `useDpop: true`:
 
    ```ts
-   // ❌ compile error: `useRefreshTokens: true` and `useDpop: true` are required when `refreshTokenMode: 'online'`
-   createAuth0Client({ domain, clientId, refreshTokenMode: 'online' });
+   import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
+   // ❌ compile error: `useRefreshTokens: true` and `useDpop: true` are required for online mode
+   createAuth0Client({ domain, clientId, refreshTokenMode: RefreshTokenMode.Online });
 
    // ❌ compile error: `useDpop: true` is still required
-   createAuth0Client({ domain, clientId, refreshTokenMode: 'online', useRefreshTokens: true });
+   createAuth0Client({ domain, clientId, refreshTokenMode: RefreshTokenMode.Online, useRefreshTokens: true });
 
    // ✅ valid
-   createAuth0Client({ domain, clientId, refreshTokenMode: 'online', useRefreshTokens: true, useDpop: true });
+   createAuth0Client({ domain, clientId, refreshTokenMode: RefreshTokenMode.Online, useRefreshTokens: true, useDpop: true });
    ```
 
    > [!NOTE]
-   > The compile-time check only narrows when `refreshTokenMode` is the **literal** `'online'`. A dynamically-typed value (e.g. `refreshTokenMode: someString`), an `as any` cast, or plain JavaScript all bypass it — which is why the runtime check below exists too.
+   > The compile-time check narrows on the online mode value. A dynamically-typed value (e.g. a `refreshTokenMode` read from config at runtime), an `as any` cast, or plain JavaScript all bypass it — which is why the runtime check below exists too.
 
-2. **Runtime (all consumers, including plain JS).** The `Auth0Client` constructor throws an `InvalidConfigurationError` when `refreshTokenMode: 'online'` but `useRefreshTokens` or `useDpop` is not `true`. The error's `suggestion` tells you exactly which option to set:
+2. **Runtime (all consumers, including plain JS).** The `Auth0Client` constructor throws an `InvalidConfigurationError` when online mode is requested but `useRefreshTokens` or `useDpop` is not `true`. The error's `suggestion` tells you exactly which option to set:
 
    ```js
-   import { InvalidConfigurationError } from '@auth0/auth0-spa-js';
+   import { createAuth0Client, RefreshTokenMode, InvalidConfigurationError } from '@auth0/auth0-spa-js';
 
    try {
      const auth0 = await createAuth0Client({
        domain: '<AUTH0_DOMAIN>',
        clientId: '<AUTH0_CLIENT_ID>',
-       refreshTokenMode: 'online',
+       refreshTokenMode: RefreshTokenMode.Online,
        useRefreshTokens: true // missing useDpop: true
      });
    } catch (e) {
@@ -317,11 +321,13 @@ After logout, the ORT is no longer valid; a subsequent `getTokenSilently()` fall
 Online access is compatible with [MRRT](#using-multi-resource-refresh-tokens): a single ORT can be exchanged for access tokens across the audiences allowed by your refresh-token policies. The ORT remains non-rotating throughout — the same token is reused for every cross-audience exchange.
 
 ```js
+import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
 const auth0 = await createAuth0Client({
   domain: '<AUTH0_DOMAIN>',
   clientId: '<AUTH0_CLIENT_ID>',
   useRefreshTokens: true,
-  refreshTokenMode: 'online',
+  refreshTokenMode: RefreshTokenMode.Online,
   useDpop: true,
   useMrrt: true,
   authorizationParams: {

README.md

@@ -116,22 +116,24 @@ window.addEventListener('load', async () => {
 
 ### Online Access
 
-Set `refreshTokenMode: 'online'` (together with the required `useRefreshTokens: true` and `useDpop: true`) to use **Online Refresh Tokens** — non-rotating refresh tokens bound to the Auth0 session lifetime. The SDK injects the `online_access` scope and routes renewal through the refresh-token grant.
+Set `refreshTokenMode` to `RefreshTokenMode.Online` (together with the required `useRefreshTokens: true` and `useDpop: true`) to use **Online Refresh Tokens** — non-rotating refresh tokens bound to the Auth0 session lifetime. The SDK injects the `online_access` scope and routes renewal through the refresh-token grant.
 
 ```js
+import { createAuth0Client, RefreshTokenMode } from '@auth0/auth0-spa-js';
+
 const auth0 = await createAuth0Client({
   domain: '<AUTH0_DOMAIN>',
   clientId: '<AUTH0_CLIENT_ID>',
   useRefreshTokens: true,
-  refreshTokenMode: 'online',
+  refreshTokenMode: RefreshTokenMode.Online,
   useDpop: true,
   authorizationParams: {
     redirect_uri: '<MY_CALLBACK_URL>'
   }
 });
 ```
 
-`refreshTokenMode` is a sub-option of `useRefreshTokens`: it defaults to `'offline'` (the rotating refresh tokens described above) and must be set to `'online'` for Online Refresh Tokens. Online mode requires both `useRefreshTokens: true` and `useDpop: true`. See [Online Access](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md#online-access-online-refresh-tokens) in EXAMPLES.md for the full guide.
+`refreshTokenMode` is a sub-option of `useRefreshTokens`: it defaults to `RefreshTokenMode.Offline` (the rotating refresh tokens described above) and must be set to `RefreshTokenMode.Online` for Online Refresh Tokens. Online mode requires both `useRefreshTokens: true` and `useDpop: true`. See [Online Access](https://github.com/auth0/auth0-spa-js/blob/main/EXAMPLES.md#online-access-online-refresh-tokens) in EXAMPLES.md for the full guide.
 
 ### More Examples
 

__tests__/Auth0Client/onlineAccess.types.test.ts

@@ -1,16 +1,9 @@
 /**
- * Compile-time enforcement of the online-access option, via `createAuth0Client`
- * overloads (the interface itself stays plain, non-breaking optional fields).
- *
- * These assertions are validated by ts-jest's type checker at test time: each
- * `@ts-expect-error` MUST sit over a genuine type error, or TypeScript reports an
- * unused-directive error and the suite fails. The runtime safety net (the
- * `InvalidConfigurationError` throw) is covered separately in onlineAccess.test.ts.
- *
- * The overloads only narrow on a literal `refreshTokenMode: 'online'`, so these cover
- * the common literal mistakes a TS user would make at the call site.
+ * Compile-time enforcement of the online-access overloads, type-checked by ts-jest:
+ * each `@ts-expect-error` must sit over a genuine type error. The runtime safety net
+ * is covered in onlineAccess.test.ts.
  */
-import { createAuth0Client } from '../../src';
+import { createAuth0Client, RefreshTokenMode } from '../../src';
 
 const base = {
   domain: 'example.auth0.com',
@@ -19,10 +12,17 @@ const base = {
 
 describe('createAuth0Client — online access type enforcement', () => {
   it('requires useRefreshTokens: true and useDpop: true when refreshTokenMode is online', () => {
-    // Compile-only — never invoked. Wrapped in a never-true guard so the calls
-    // are type-checked but do not execute (no DOM/crypto needed).
+    // Compile-only — type-checked but never executed.
     const _typecheck = async () => {
-      // Valid combo.
+      // Valid combo, using the RefreshTokenMode enum.
+      await createAuth0Client({
+        ...base,
+        refreshTokenMode: RefreshTokenMode.Online,
+        useRefreshTokens: true,
+        useDpop: true
+      });
+
+      // Raw string still accepted for backward compatibility.
       await createAuth0Client({
         ...base,
         refreshTokenMode: 'online',
@@ -31,22 +31,22 @@ describe('createAuth0Client — online access type enforcement', () => {
       });
 
       // Missing useRefreshTokens → compile error.
-      // @ts-expect-error refreshTokenMode: 'online' requires useRefreshTokens: true
-      await createAuth0Client({ ...base, refreshTokenMode: 'online', useDpop: true });
+      // @ts-expect-error online mode requires useRefreshTokens: true
+      await createAuth0Client({ ...base, refreshTokenMode: RefreshTokenMode.Online, useDpop: true });
 
       // Missing useDpop → compile error.
-      // @ts-expect-error refreshTokenMode: 'online' requires useDpop: true
+      // @ts-expect-error online mode requires useDpop: true
       await createAuth0Client({
         ...base,
-        refreshTokenMode: 'online',
+        refreshTokenMode: RefreshTokenMode.Online,
         useRefreshTokens: true
       });
 
       // useDpop: false → compile error.
-      // @ts-expect-error refreshTokenMode: 'online' requires useDpop: true (not false)
+      // @ts-expect-error online mode requires useDpop: true (not false)
       await createAuth0Client({
         ...base,
-        refreshTokenMode: 'online',
+        refreshTokenMode: RefreshTokenMode.Online,
         useRefreshTokens: true,
         useDpop: false
       });
@@ -60,6 +60,8 @@ describe('createAuth0Client — online access type enforcement', () => {
     const _typecheck = async () => {
       // Legacy combos remain valid — the overloads must not constrain them.
       await createAuth0Client({ ...base, useRefreshTokens: true, useDpop: false });
+      await createAuth0Client({ ...base, refreshTokenMode: RefreshTokenMode.Offline, useRefreshTokens: true });
+      // Raw string still accepted for backward compatibility.
       await createAuth0Client({ ...base, refreshTokenMode: 'offline', useRefreshTokens: true });
     };
     void _typecheck;

src/Auth0Client.ts

@@ -195,12 +195,7 @@ export class Auth0Client {
     refreshTokenMode: 'offline',
   };
 
-  /**
-   * Validates the online-access configuration and returns whether online mode is enabled.
-   *
-   * Online mode (`refreshTokenMode: 'online'`) is a refresh-token grant, so it requires
-   * `useRefreshTokens: true`, and it requires DPoP, so `useDpop: true` is mandatory.
-   */
+  /** Validates online-access config and returns whether online mode is enabled. */
   private resolveOnlineAccess(options: Auth0ClientOptions): boolean {
 
     if (options.refreshTokenMode !== 'online') {
@@ -285,12 +280,7 @@ export class Auth0Client {
       ? this.cookieStorage
       : SessionStorage;
 
-    // Construct the scopes based on the following:
-    // 1. Always include `openid`
-    // 2. Include the scopes provided in `authorizationParams. This defaults to `profile email`
-    // 3. Add `online_access` when in online-access mode, otherwise `offline_access` if
-    //    `useRefreshTokens` is enabled. Online and offline are mutually exclusive — online
-    //    must never inject `offline_access`.
+    // `online_access` and `offline_access` are mutually exclusive — inject at most one.
     this.scope = injectDefaultScopes(
       this.options.authorizationParams.scope,
       'openid',
@@ -353,7 +343,6 @@ export class Auth0Client {
     );
 
     // Don't use web workers unless using refresh tokens in memory.
-    // Online mode requires `useRefreshTokens: true`, so it is covered here too.
     if (
       typeof window !== 'undefined' &&
       window.Worker &&
@@ -1511,9 +1500,8 @@ export class Auth0Client {
         }
       );
 
-      // If is refreshed with MRRT, we update all entries that have the old
-      // refresh_token with the new one if the server responded with one.
-      // Online Refresh Tokens are non-rotating, so the stored RT is never replaced.
+      // Propagate a rotated RT to all MRRT entries. Skipped for online mode,
+      // where ORTs are non-rotating.
       if (
         !this.onlineAccess &&
         tokenResult.refresh_token &&

src/errors.ts

@@ -29,9 +29,8 @@ export class GenericError extends Error {
 }
 
 /**
- * Thrown at construction time when the Auth0Client is configured with an invalid combination
- * of options (e.g. `refreshTokenMode: 'online'` without `useDpop: true`). Carries a `suggestion` with
- * the exact configuration change to make.
+ * Thrown at construction time for an invalid option combination (e.g.
+ * `refreshTokenMode: 'online'` without `useDpop: true`). The `suggestion` names the fix.
  */
 export class InvalidConfigurationError extends GenericError {
   constructor(message: string, public suggestion: string) {

src/global.ts

@@ -9,6 +9,22 @@ import { CompleteResponse } from './myaccount';
  */
 export type InteractiveErrorHandler = 'popup';
 
+/**
+ * The refresh-token variant used when `useRefreshTokens: true`.
+ *
+ * - {@link RefreshTokenMode.Offline} (default): rotating offline refresh tokens.
+ * - {@link RefreshTokenMode.Online}: non-rotating Online Refresh Tokens (ORTs).
+ */
+// `const` object, not a TS `enum`, so members stay string-literal types and
+// remain assignable to the `createAuth0Client` overloads.
+export const RefreshTokenMode = {
+  Offline: 'offline',
+  Online: 'online'
+} as const;
+
+export type RefreshTokenMode =
+  (typeof RefreshTokenMode)[keyof typeof RefreshTokenMode];
+
 export interface AuthorizationParams {
   /**
    * - `'page'`: displays the UI with a full page view
@@ -314,21 +330,15 @@ export interface Auth0ClientOptions {
 
   /**
    * Selects the refresh-token variant used when `useRefreshTokens: true`.
+   * Defaults to {@link RefreshTokenMode.Offline}.
    *
-   * - `'offline'` (default): rotating offline refresh tokens, requested via the
-   *   `offline_access` scope. This is the existing behavior.
-   * - `'online'`: non-rotating Online Refresh Tokens (ORTs), bound to the Auth0
-   *   session lifetime, requested via the `online_access` scope. When the session
-   *   ends or is revoked, the ORT becomes invalid.
-   *
-   * Online mode requires `useRefreshTokens: true` (it is a kind of refresh-token
-   * grant) and `useDpop: true` (DPoP is mandatory for online access). The
-   * `online_access` and `offline_access` scopes are mutually exclusive — online
-   * mode never injects `offline_access`.
+   * - {@link RefreshTokenMode.Offline} (default): rotating offline refresh tokens (`offline_access`).
+   * - {@link RefreshTokenMode.Online}: non-rotating, session-bound Online Refresh Tokens (`online_access`).
    *
-   * Defaults to `'offline'` — when unset the SDK behaves exactly as before.
+   * Online mode requires `useRefreshTokens: true` and `useDpop: true`. The
+   * `online_access` and `offline_access` scopes are mutually exclusive.
    */
-  refreshTokenMode?: 'offline' | 'online';
+  refreshTokenMode?: RefreshTokenMode;
 
   /**
    * Configures automatic handling of interactive authentication errors.

src/index.ts

@@ -6,11 +6,9 @@ import './global';
 export * from './global';
 
 /**
- * Online mode (`refreshTokenMode: 'online'`) is a refresh-token grant and requires DPoP.
- * When `refreshTokenMode` is the literal `'online'`, the compiler requires both
- * `useRefreshTokens: true` and `useDpop: true`. This only narrows on the literal `'online'`;
- * dynamic values, casts, and plain JS are covered by the runtime check in the
- * `Auth0Client` constructor.
+ * Online mode requires `useRefreshTokens: true` and `useDpop: true`, enforced here at
+ * compile time. Dynamic values, casts, and plain JS are covered by the runtime check in
+ * the `Auth0Client` constructor.
  */
 export async function createAuth0Client(
   options: Auth0ClientOptions & {