@imtbl/auth-next-client 2.12.7-alpha.9 → 2.12.8-alpha.0

package/README.md

@@ -27,6 +27,10 @@ npm install @imtbl/auth-next-client @imtbl/auth-next-server next-auth@5
 - `next` >= 14.0.0
 - `next-auth` >= 5.0.0-beta.25
 
+### Next.js 14 Compatibility
+
+This package is compatible with both Next.js 14 and 15. It uses only standard APIs available in both versions (`next/navigation` for `useRouter`, `next-auth/react`). No Next.js 15-only APIs are used.
+
 ## Quick Start
 
 ### 1. Set Up Server-Side Auth
@@ -100,6 +104,42 @@ export default function Callback() {
 }
 ```
 
+### Default Auth (Zero Config)
+
+When using `createAuthConfig()` with no args on the server, you can call login/logout with no config—sandbox clientId and redirectUri are used:
+
+```tsx
+// With default auth - no config needed
+function LoginButton() {
+  const { isAuthenticated } = useImmutableSession();
+  const { loginWithPopup, isLoggingIn, error } = useLogin();
+
+  if (isAuthenticated) return <p>You are logged in!</p>;
+
+  return (
+    <button onClick={() => loginWithPopup()} disabled={isLoggingIn}>
+      {isLoggingIn ? "Signing in..." : "Sign In"}
+    </button>
+  );
+}
+```
+
+Or with custom config (pass full LoginConfig/LogoutConfig when overriding):
+
+```tsx
+// With custom config - pass complete config
+loginWithPopup({
+  clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+  redirectUri: `${window.location.origin}/callback`,
+});
+logout({
+  clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+  logoutRedirectUri: process.env.NEXT_PUBLIC_BASE_URL!,
+});
+```
+
+See the [wallets-connect-with-nextjs](../../examples/passport/wallets-connect-with-nextjs) example for a full integration with `@imtbl/wallet`.
+
 ### 5. Add Login Button
 
 Use the `useLogin` hook for login flows with built-in state management:

package/dist/node/index.cjs

@@ -22,7 +22,15 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   CallbackPage: () => CallbackPage,
+  DEFAULT_AUDIENCE: () => DEFAULT_AUDIENCE,
+  DEFAULT_AUTH_DOMAIN: () => DEFAULT_AUTH_DOMAIN,
+  DEFAULT_LOGOUT_REDIRECT_URI_PATH: () => DEFAULT_LOGOUT_REDIRECT_URI_PATH,
+  DEFAULT_REDIRECT_URI_PATH: () => DEFAULT_REDIRECT_URI_PATH,
+  DEFAULT_SANDBOX_CLIENT_ID: () => DEFAULT_SANDBOX_CLIENT_ID,
+  DEFAULT_SCOPE: () => DEFAULT_SCOPE,
+  IMMUTABLE_PROVIDER_ID: () => IMMUTABLE_PROVIDER_ID,
   MarketingConsentStatus: () => import_auth3.MarketingConsentStatus,
+  deriveDefaultRedirectUri: () => deriveDefaultRedirectUri,
   useImmutableSession: () => useImmutableSession,
   useLogin: () => useLogin,
   useLogout: () => useLogout
@@ -36,10 +44,14 @@ var import_react2 = require("next-auth/react");
 var import_auth = require("@imtbl/auth");
 
 // src/constants.ts
+var DEFAULT_AUTH_DOMAIN = "https://auth.immutable.com";
+var DEFAULT_AUDIENCE = "platform_api";
+var DEFAULT_SCOPE = "openid profile email offline_access transact";
 var IMMUTABLE_PROVIDER_ID = "immutable";
-var DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
-var DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1e3;
-var TOKEN_EXPIRY_BUFFER_MS = 60 * 1e3;
+var DEFAULT_SANDBOX_CLIENT_ID = "mjtCL8mt06BtbxSkp2vbrYStKWnXVZfo";
+var DEFAULT_REDIRECT_URI_PATH = "/callback";
+var DEFAULT_LOGOUT_REDIRECT_URI_PATH = "/";
+var TOKEN_EXPIRY_BUFFER_MS = 6e4;
 
 // src/idTokenStorage.ts
 var ID_TOKEN_STORAGE_KEY = "imtbl_id_token";
@@ -213,6 +225,18 @@ function CallbackPage({
 var import_react3 = require("react");
 var import_react4 = require("next-auth/react");
 var import_auth2 = require("@imtbl/auth");
+
+// src/defaultConfig.ts
+function deriveDefaultRedirectUri() {
+  if (typeof window === "undefined") {
+    throw new Error(
+      "[auth-next-client] deriveDefaultRedirectUri requires window. Login hooks run in the browser when the user triggers login."
+    );
+  }
+  return `${window.location.origin}${DEFAULT_REDIRECT_URI_PATH}`;
+}
+
+// src/hooks.tsx
 var pendingRefresh = null;
 function deduplicatedUpdate(update) {
   if (!pendingRefresh) {
@@ -222,6 +246,30 @@ function deduplicatedUpdate(update) {
   }
   return pendingRefresh;
 }
+function getSandboxLoginConfig() {
+  const redirectUri = deriveDefaultRedirectUri();
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    redirectUri,
+    popupRedirectUri: redirectUri,
+    scope: DEFAULT_SCOPE,
+    audience: DEFAULT_AUDIENCE,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN
+  };
+}
+function getSandboxLogoutConfig() {
+  if (typeof window === "undefined") {
+    throw new Error(
+      "[auth-next-client] getSandboxLogoutConfig requires window. Logout runs in the browser when the user triggers it."
+    );
+  }
+  const logoutRedirectUri = window.location.origin + DEFAULT_LOGOUT_REDIRECT_URI_PATH;
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    logoutRedirectUri,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN
+  };
+}
 function useImmutableSession() {
   const { data: sessionData, status, update } = (0, import_react4.useSession)();
   const [isRefreshing, setIsRefreshing] = (0, import_react3.useState)(false);
@@ -240,11 +288,12 @@ function useImmutableSession() {
   setIsRefreshingRef.current = setIsRefreshing;
   (0, import_react3.useEffect)(() => {
     if (!session?.accessTokenExpires) return;
+    if (session?.error) return;
     const timeUntilExpiry = session.accessTokenExpires - Date.now() - TOKEN_EXPIRY_BUFFER_MS;
     if (timeUntilExpiry <= 0) {
       deduplicatedUpdate(() => updateRef.current());
     }
-  }, [session?.accessTokenExpires]);
+  }, [session?.accessTokenExpires, session?.error]);
   (0, import_react3.useEffect)(() => {
     if (session?.idToken) {
       storeIdToken(session.idToken);
@@ -353,7 +402,8 @@ function useLogin() {
     setIsLoggingIn(true);
     setError(null);
     try {
-      const tokens = await (0, import_auth2.loginWithPopup)(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await (0, import_auth2.loginWithPopup)(fullConfig, options);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Login failed";
@@ -367,7 +417,8 @@ function useLogin() {
     setIsLoggingIn(true);
     setError(null);
     try {
-      const tokens = await (0, import_auth2.loginWithEmbedded)(config);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await (0, import_auth2.loginWithEmbedded)(fullConfig);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Login failed";
@@ -381,7 +432,8 @@ function useLogin() {
     setIsLoggingIn(true);
     setError(null);
     try {
-      await (0, import_auth2.loginWithRedirect)(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      await (0, import_auth2.loginWithRedirect)(fullConfig, options);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Login failed";
       setError(errorMessage);
@@ -406,7 +458,8 @@ function useLogout() {
     try {
       clearStoredIdToken();
       await (0, import_react4.signOut)({ redirect: false });
-      (0, import_auth2.logoutWithRedirect)(config);
+      const fullConfig = config ?? getSandboxLogoutConfig();
+      (0, import_auth2.logoutWithRedirect)(fullConfig);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Logout failed";
       setError(errorMessage);
@@ -426,7 +479,15 @@ var import_auth3 = require("@imtbl/auth");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CallbackPage,
+  DEFAULT_AUDIENCE,
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_LOGOUT_REDIRECT_URI_PATH,
+  DEFAULT_REDIRECT_URI_PATH,
+  DEFAULT_SANDBOX_CLIENT_ID,
+  DEFAULT_SCOPE,
+  IMMUTABLE_PROVIDER_ID,
   MarketingConsentStatus,
+  deriveDefaultRedirectUri,
   useImmutableSession,
   useLogin,
   useLogout

package/dist/node/index.js

@@ -7,10 +7,14 @@ import { signIn } from "next-auth/react";
 import { handleLoginCallback as handleAuthCallback } from "@imtbl/auth";
 
 // src/constants.ts
+var DEFAULT_AUTH_DOMAIN = "https://auth.immutable.com";
+var DEFAULT_AUDIENCE = "platform_api";
+var DEFAULT_SCOPE = "openid profile email offline_access transact";
 var IMMUTABLE_PROVIDER_ID = "immutable";
-var DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
-var DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1e3;
-var TOKEN_EXPIRY_BUFFER_MS = 60 * 1e3;
+var DEFAULT_SANDBOX_CLIENT_ID = "mjtCL8mt06BtbxSkp2vbrYStKWnXVZfo";
+var DEFAULT_REDIRECT_URI_PATH = "/callback";
+var DEFAULT_LOGOUT_REDIRECT_URI_PATH = "/";
+var TOKEN_EXPIRY_BUFFER_MS = 6e4;
 
 // src/idTokenStorage.ts
 var ID_TOKEN_STORAGE_KEY = "imtbl_id_token";
@@ -194,6 +198,18 @@ import {
   loginWithRedirect as rawLoginWithRedirect,
   logoutWithRedirect as rawLogoutWithRedirect
 } from "@imtbl/auth";
+
+// src/defaultConfig.ts
+function deriveDefaultRedirectUri() {
+  if (typeof window === "undefined") {
+    throw new Error(
+      "[auth-next-client] deriveDefaultRedirectUri requires window. Login hooks run in the browser when the user triggers login."
+    );
+  }
+  return `${window.location.origin}${DEFAULT_REDIRECT_URI_PATH}`;
+}
+
+// src/hooks.tsx
 var pendingRefresh = null;
 function deduplicatedUpdate(update) {
   if (!pendingRefresh) {
@@ -203,6 +219,30 @@ function deduplicatedUpdate(update) {
   }
   return pendingRefresh;
 }
+function getSandboxLoginConfig() {
+  const redirectUri = deriveDefaultRedirectUri();
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    redirectUri,
+    popupRedirectUri: redirectUri,
+    scope: DEFAULT_SCOPE,
+    audience: DEFAULT_AUDIENCE,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN
+  };
+}
+function getSandboxLogoutConfig() {
+  if (typeof window === "undefined") {
+    throw new Error(
+      "[auth-next-client] getSandboxLogoutConfig requires window. Logout runs in the browser when the user triggers it."
+    );
+  }
+  const logoutRedirectUri = window.location.origin + DEFAULT_LOGOUT_REDIRECT_URI_PATH;
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    logoutRedirectUri,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN
+  };
+}
 function useImmutableSession() {
   const { data: sessionData, status, update } = useSession();
   const [isRefreshing, setIsRefreshing] = useState2(false);
@@ -221,11 +261,12 @@ function useImmutableSession() {
   setIsRefreshingRef.current = setIsRefreshing;
   useEffect2(() => {
     if (!session?.accessTokenExpires) return;
+    if (session?.error) return;
     const timeUntilExpiry = session.accessTokenExpires - Date.now() - TOKEN_EXPIRY_BUFFER_MS;
     if (timeUntilExpiry <= 0) {
       deduplicatedUpdate(() => updateRef.current());
     }
-  }, [session?.accessTokenExpires]);
+  }, [session?.accessTokenExpires, session?.error]);
   useEffect2(() => {
     if (session?.idToken) {
       storeIdToken(session.idToken);
@@ -334,7 +375,8 @@ function useLogin() {
     setIsLoggingIn(true);
     setError(null);
     try {
-      const tokens = await rawLoginWithPopup(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await rawLoginWithPopup(fullConfig, options);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Login failed";
@@ -348,7 +390,8 @@ function useLogin() {
     setIsLoggingIn(true);
     setError(null);
     try {
-      const tokens = await rawLoginWithEmbedded(config);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await rawLoginWithEmbedded(fullConfig);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Login failed";
@@ -362,7 +405,8 @@ function useLogin() {
     setIsLoggingIn(true);
     setError(null);
     try {
-      await rawLoginWithRedirect(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      await rawLoginWithRedirect(fullConfig, options);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Login failed";
       setError(errorMessage);
@@ -387,7 +431,8 @@ function useLogout() {
     try {
       clearStoredIdToken();
       await signOut({ redirect: false });
-      rawLogoutWithRedirect(config);
+      const fullConfig = config ?? getSandboxLogoutConfig();
+      rawLogoutWithRedirect(fullConfig);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : "Logout failed";
       setError(errorMessage);
@@ -406,7 +451,15 @@ function useLogout() {
 import { MarketingConsentStatus } from "@imtbl/auth";
 export {
   CallbackPage,
+  DEFAULT_AUDIENCE,
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_LOGOUT_REDIRECT_URI_PATH,
+  DEFAULT_REDIRECT_URI_PATH,
+  DEFAULT_SANDBOX_CLIENT_ID,
+  DEFAULT_SCOPE,
+  IMMUTABLE_PROVIDER_ID,
   MarketingConsentStatus,
+  deriveDefaultRedirectUri,
   useImmutableSession,
   useLogin,
   useLogout

package/dist/types/constants.d.ts

@@ -1,37 +1,15 @@
 /**
- * Shared constants for @imtbl/auth-next-client
- */
-/**
- * Default Immutable authentication domain
+ * Client-side constants for @imtbl/auth-next-client.
+ * Defined locally to avoid importing from auth-next-server (which uses next/server).
+ * Values must stay in sync with auth-next-server constants.
  */
 export declare const DEFAULT_AUTH_DOMAIN = "https://auth.immutable.com";
-/**
- * Default OAuth audience
- */
 export declare const DEFAULT_AUDIENCE = "platform_api";
-/**
- * Default OAuth scopes
- */
 export declare const DEFAULT_SCOPE = "openid profile email offline_access transact";
-/**
- * NextAuth credentials provider ID for Immutable
- */
 export declare const IMMUTABLE_PROVIDER_ID = "immutable";
-/**
- * Default NextAuth API base path
- */
 export declare const DEFAULT_NEXTAUTH_BASE_PATH = "/api/auth";
-/**
- * Default token expiry in seconds (15 minutes)
- * Used as fallback when exp claim cannot be extracted from JWT
- */
-export declare const DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
-/**
- * Default token expiry in milliseconds
- */
-export declare const DEFAULT_TOKEN_EXPIRY_MS: number;
-/**
- * Buffer time in milliseconds before token expiry to trigger refresh.
- * Matches TOKEN_EXPIRY_BUFFER_SECONDS (60s) in @imtbl/auth-next-server.
- */
-export declare const TOKEN_EXPIRY_BUFFER_MS: number;
+export declare const DEFAULT_SANDBOX_CLIENT_ID = "mjtCL8mt06BtbxSkp2vbrYStKWnXVZfo";
+export declare const DEFAULT_REDIRECT_URI_PATH = "/callback";
+export declare const DEFAULT_LOGOUT_REDIRECT_URI_PATH = "/";
+export declare const DEFAULT_TOKEN_EXPIRY_MS = 900000;
+export declare const TOKEN_EXPIRY_BUFFER_MS = 60000;

package/dist/types/defaultConfig.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sandbox default redirect URI for zero-config mode.
+ * Defined locally to avoid importing from auth-next-server (which uses next/server).
+ * OAuth requires an absolute URL; this runs in the browser when login is invoked.
+ *
+ * @internal
+ */
+export declare function deriveDefaultRedirectUri(): string;

package/dist/types/hooks.d.ts

@@ -86,53 +86,87 @@ export interface UseImmutableSessionReturn {
 export declare function useImmutableSession(): UseImmutableSessionReturn;
 /**
  * Return type for useLogin hook
+ *
+ * Config is optional - when omitted, defaults are auto-derived (clientId, redirectUri, etc.).
+ * When provided, must be a complete LoginConfig.
  */
 export interface UseLoginReturn {
     /** Start login with popup flow */
-    loginWithPopup: (config: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
+    loginWithPopup: (config?: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
     /** Start login with embedded modal flow */
-    loginWithEmbedded: (config: LoginConfig) => Promise<void>;
+    loginWithEmbedded: (config?: LoginConfig) => Promise<void>;
     /** Start login with redirect flow (navigates away from page) */
-    loginWithRedirect: (config: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
+    loginWithRedirect: (config?: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
     /** Whether login is currently in progress */
     isLoggingIn: boolean;
     /** Error message from the last login attempt, or null if none */
     error: string | null;
 }
 /**
- * Hook to handle Immutable authentication login flows.
+ * Hook to handle Immutable authentication login flows with automatic defaults.
  *
  * Provides login functions that:
  * 1. Handle OAuth authentication via popup, embedded modal, or redirect
  * 2. Automatically sign in to NextAuth after successful authentication
  * 3. Track loading and error states
+ * 4. Auto-detect clientId and redirectUri if not provided (uses defaults)
  *
- * Config is passed at call time to allow different configurations for different
- * login methods (e.g., different redirectUri vs popupRedirectUri).
+ * Config can be passed at call time or omitted to use sensible defaults:
+ * - `clientId`: Auto-detected based on environment (sandbox vs production)
+ * - `redirectUri`: Auto-derived from `window.location.origin + '/callback'`
+ * - `popupRedirectUri`: Auto-derived from `window.location.origin + '/callback'` (same as redirectUri)
+ * - `logoutRedirectUri`: Auto-derived from `window.location.origin`
+ * - `scope`: `'openid profile email offline_access transact'`
+ * - `audience`: `'platform_api'`
+ * - `authenticationDomain`: `'https://auth.immutable.com'`
  *
  * Must be used within a SessionProvider from next-auth/react.
  *
- * @example
+ * @example Minimal usage (uses all defaults)
  * ```tsx
  * import { useLogin, useImmutableSession } from '@imtbl/auth-next-client';
  *
- * const config = {
- *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
- *   redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
- *   popupRedirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback/popup`,
- * };
+ * function LoginButton() {
+ *   const { isAuthenticated } = useImmutableSession();
+ *   const { loginWithPopup, isLoggingIn, error } = useLogin();
+ *
+ *   if (isAuthenticated) {
+ *     return <p>You are logged in!</p>;
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => loginWithPopup()} disabled={isLoggingIn}>
+ *         {isLoggingIn ? 'Signing in...' : 'Sign In'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom configuration
+ * ```tsx
+ * import { useLogin, useImmutableSession } from '@imtbl/auth-next-client';
  *
  * function LoginButton() {
  *   const { isAuthenticated } = useImmutableSession();
  *   const { loginWithPopup, isLoggingIn, error } = useLogin();
  *
+ *   const handleLogin = () => {
+ *     loginWithPopup({
+ *       clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID,
+ *       redirectUri: `${window.location.origin}/callback`,
+ *     });
+ *   };
+ *
  *   if (isAuthenticated) {
  *     return <p>You are logged in!</p>;
  *   }
  *
  *   return (
  *     <>
- *       <button onClick={() => loginWithPopup(config)} disabled={isLoggingIn}>
+ *       <button onClick={handleLogin} disabled={isLoggingIn}>
  *         {isLoggingIn ? 'Signing in...' : 'Sign In'}
  *       </button>
  *       {error && <p style={{ color: 'red' }}>{error}</p>}
@@ -152,9 +186,11 @@ export interface UseLogoutReturn {
      * This ensures that when the user logs in again, they will be prompted to select
      * an account instead of being automatically logged in with the previous account.
      *
-     * @param config - Logout configuration with clientId and optional redirectUri
+     * Config is optional - defaults will be auto-derived if not provided.
+     *
+     * @param config - Optional logout configuration with clientId and optional redirectUri
      */
-    logout: (config: LogoutConfig) => Promise<void>;
+    logout: (config?: LogoutConfig) => Promise<void>;
     /** Whether logout is currently in progress */
     isLoggingOut: boolean;
     /** Error message from the last logout attempt, or null if none */
@@ -171,16 +207,38 @@ export interface UseLogoutReturn {
  * an account (for social logins like Google) instead of being automatically logged
  * in with the previous account.
  *
+ * Config is optional - defaults will be auto-derived if not provided:
+ * - `clientId`: Auto-detected based on environment (sandbox vs production)
+ * - `logoutRedirectUri`: Auto-derived from `window.location.origin`
+ *
  * Must be used within a SessionProvider from next-auth/react.
  *
- * @example
+ * @example Minimal usage (uses all defaults)
  * ```tsx
  * import { useLogout, useImmutableSession } from '@imtbl/auth-next-client';
  *
- * const logoutConfig = {
- *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
- *   logoutRedirectUri: process.env.NEXT_PUBLIC_BASE_URL!,
- * };
+ * function LogoutButton() {
+ *   const { isAuthenticated } = useImmutableSession();
+ *   const { logout, isLoggingOut, error } = useLogout();
+ *
+ *   if (!isAuthenticated) {
+ *     return null;
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => logout()} disabled={isLoggingOut}>
+ *         {isLoggingOut ? 'Signing out...' : 'Sign Out'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom configuration
+ * ```tsx
+ * import { useLogout, useImmutableSession } from '@imtbl/auth-next-client';
  *
  * function LogoutButton() {
  *   const { isAuthenticated } = useImmutableSession();
@@ -192,7 +250,13 @@ export interface UseLogoutReturn {
  *
  *   return (
  *     <>
- *       <button onClick={() => logout(logoutConfig)} disabled={isLoggingOut}>
+ *       <button
+ *         onClick={() => logout({
+ *           clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID,
+ *           logoutRedirectUri: `${window.location.origin}/custom-logout`,
+ *         })}
+ *         disabled={isLoggingOut}
+ *       >
  *         {isLoggingOut ? 'Signing out...' : 'Sign Out'}
  *       </button>
  *       {error && <p style={{ color: 'red' }}>{error}</p>}

package/dist/types/index.d.ts

@@ -28,3 +28,5 @@ export type { ImmutableUserClient, ImmutableTokenDataClient, ZkEvmInfo, } from '
 export type { ImmutableAuthConfig, ImmutableTokenData, ImmutableUser, AuthProps, AuthPropsWithData, ProtectedAuthProps, ProtectedAuthPropsWithData, } from '@imtbl/auth-next-server';
 export type { LoginConfig, StandaloneLoginOptions, DirectLoginOptions, LogoutConfig, } from '@imtbl/auth';
 export { MarketingConsentStatus } from '@imtbl/auth';
+export { DEFAULT_AUTH_DOMAIN, DEFAULT_AUDIENCE, DEFAULT_SCOPE, IMMUTABLE_PROVIDER_ID, DEFAULT_SANDBOX_CLIENT_ID, DEFAULT_REDIRECT_URI_PATH, DEFAULT_LOGOUT_REDIRECT_URI_PATH, } from './constants';
+export { deriveDefaultRedirectUri } from './defaultConfig';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth-next-client",
-  "version": "2.12.7-alpha.9",
+  "version": "2.12.8-alpha.0",
   "description": "Immutable Auth.js v5 integration for Next.js - Client-side components",
   "author": "Immutable",
   "license": "Apache-2.0",
@@ -27,11 +27,11 @@
     }
   },
   "dependencies": {
-    "@imtbl/auth": "2.12.7-alpha.9",
-    "@imtbl/auth-next-server": "2.12.7-alpha.9"
+    "@imtbl/auth": "2.12.8-alpha.0",
+    "@imtbl/auth-next-server": "2.12.8-alpha.0"
   },
   "peerDependencies": {
-    "next": "^15.0.0",
+    "next": "^14.0.0 || ^15.0.0",
     "next-auth": "^5.0.0-beta.25",
     "react": "^18.2.0 || ^19.0.0"
   },
@@ -56,7 +56,7 @@
     "@types/react": "^18.3.5",
     "eslint": "^8.56.0",
     "jest": "^29.7.0",
-    "next": "^15.1.6",
+    "next": "^15.2.6",
     "next-auth": "^5.0.0-beta.30",
     "react": "^18.2.0",
     "tsup": "^8.3.0",

package/src/constants.ts

@@ -1,45 +1,16 @@
 /**
- * Shared constants for @imtbl/auth-next-client
+ * Client-side constants for @imtbl/auth-next-client.
+ * Defined locally to avoid importing from auth-next-server (which uses next/server).
+ * Values must stay in sync with auth-next-server constants.
  */
 
-/**
- * Default Immutable authentication domain
- */
 export const DEFAULT_AUTH_DOMAIN = 'https://auth.immutable.com';
-
-/**
- * Default OAuth audience
- */
 export const DEFAULT_AUDIENCE = 'platform_api';
-
-/**
- * Default OAuth scopes
- */
 export const DEFAULT_SCOPE = 'openid profile email offline_access transact';
-
-/**
- * NextAuth credentials provider ID for Immutable
- */
 export const IMMUTABLE_PROVIDER_ID = 'immutable';
-
-/**
- * Default NextAuth API base path
- */
 export const DEFAULT_NEXTAUTH_BASE_PATH = '/api/auth';
-
-/**
- * Default token expiry in seconds (15 minutes)
- * Used as fallback when exp claim cannot be extracted from JWT
- */
-export const DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
-
-/**
- * Default token expiry in milliseconds
- */
-export const DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1000;
-
-/**
- * Buffer time in milliseconds before token expiry to trigger refresh.
- * Matches TOKEN_EXPIRY_BUFFER_SECONDS (60s) in @imtbl/auth-next-server.
- */
-export const TOKEN_EXPIRY_BUFFER_MS = 60 * 1000;
+export const DEFAULT_SANDBOX_CLIENT_ID = 'mjtCL8mt06BtbxSkp2vbrYStKWnXVZfo';
+export const DEFAULT_REDIRECT_URI_PATH = '/callback';
+export const DEFAULT_LOGOUT_REDIRECT_URI_PATH = '/';
+export const DEFAULT_TOKEN_EXPIRY_MS = 900_000;
+export const TOKEN_EXPIRY_BUFFER_MS = 60_000;

package/src/defaultConfig.ts

@@ -0,0 +1,19 @@
+/**
+ * Sandbox default redirect URI for zero-config mode.
+ * Defined locally to avoid importing from auth-next-server (which uses next/server).
+ * OAuth requires an absolute URL; this runs in the browser when login is invoked.
+ *
+ * @internal
+ */
+
+import { DEFAULT_REDIRECT_URI_PATH } from './constants';
+
+export function deriveDefaultRedirectUri(): string {
+  if (typeof window === 'undefined') {
+    throw new Error(
+      '[auth-next-client] deriveDefaultRedirectUri requires window. '
+      + 'Login hooks run in the browser when the user triggers login.',
+    );
+  }
+  return `${window.location.origin}${DEFAULT_REDIRECT_URI_PATH}`;
+}

package/src/hooks.test.tsx

@@ -23,6 +23,10 @@ jest.mock('@imtbl/auth', () => ({
   logoutWithRedirect: jest.fn(),
 }));
 
+jest.mock('./defaultConfig', () => ({
+  deriveDefaultRedirectUri: jest.fn(() => 'http://localhost:3000/callback'),
+}));
+
 import { useImmutableSession } from './hooks';
 
 // ---------------------------------------------------------------------------
@@ -287,6 +291,23 @@ describe('useImmutableSession', () => {
       // Should NOT have called update -- token is still valid
       expect(mockUpdate).not.toHaveBeenCalled();
     });
+
+    it('does not trigger refresh when session has error (prevents infinite loop)', async () => {
+      // Simulate: token expired and last refresh failed (e.g. RefreshTokenError)
+      const sessionWithError = createSession({
+        accessTokenExpires: Date.now() - 1000, // expired
+        error: 'RefreshTokenError',
+      });
+      setupUseSession(sessionWithError);
+
+      await act(async () => {
+        renderHook(() => useImmutableSession());
+      });
+
+      // Must NOT call update - otherwise we would retry refresh repeatedly
+      // and cause an infinite loop (update -> same session with error -> effect re-runs -> update again).
+      expect(mockUpdate).not.toHaveBeenCalled();
+    });
   });
 
   describe('getUser() respects pending refresh', () => {
@@ -313,5 +334,35 @@ describe('useImmutableSession', () => {
       // getUser() should have waited for the refresh and gotten the fresh token
       expect(user?.accessToken).toBe('user-fresh-token');
     });
+
+    it('getUser(true) still calls update with forceRefresh even when session has error', async () => {
+      // Session is in error state (e.g. previous refresh failed)
+      const sessionWithError = createSession({
+        accessTokenExpires: Date.now() - 1000,
+        error: 'RefreshTokenError',
+      });
+      setupUseSession(sessionWithError);
+
+      // Server recovers and returns a valid session (e.g. user re-authenticated elsewhere)
+      const recoveredSession = createSession({
+        accessToken: 'recovered-token',
+        accessTokenExpires: Date.now() + 10 * 60 * 1000,
+        user: { sub: 'user-1', email: 'recovered@test.com' },
+      });
+      mockUpdate.mockResolvedValue(recoveredSession);
+
+      const { result } = renderHook(() => useImmutableSession());
+
+      let user: any;
+      await act(async () => {
+        user = await result.current.getUser(true);
+      });
+
+      // forceRefresh must have been attempted (proactive effect does NOT run when session.error is set)
+      expect(mockUpdate).toHaveBeenCalledWith({ forceRefresh: true });
+      // When server returns a good session, we get the user
+      expect(user?.accessToken).toBe('recovered-token');
+      expect(user?.profile?.email).toBe('recovered@test.com');
+    });
   });
 });

package/src/hooks.tsx

@@ -18,7 +18,16 @@ import {
   loginWithRedirect as rawLoginWithRedirect,
   logoutWithRedirect as rawLogoutWithRedirect,
 } from '@imtbl/auth';
-import { IMMUTABLE_PROVIDER_ID, TOKEN_EXPIRY_BUFFER_MS } from './constants';
+import { deriveDefaultRedirectUri } from './defaultConfig';
+import {
+  IMMUTABLE_PROVIDER_ID,
+  TOKEN_EXPIRY_BUFFER_MS,
+  DEFAULT_SANDBOX_CLIENT_ID,
+  DEFAULT_LOGOUT_REDIRECT_URI_PATH,
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_SCOPE,
+  DEFAULT_AUDIENCE,
+} from './constants';
 import { storeIdToken, getStoredIdToken, clearStoredIdToken } from './idTokenStorage';
 
 // ---------------------------------------------------------------------------
@@ -42,6 +51,37 @@ function deduplicatedUpdate(
   return pendingRefresh;
 }
 
+// ---------------------------------------------------------------------------
+// Sandbox defaults for zero-config (no config or full config - no merge)
+// ---------------------------------------------------------------------------
+
+function getSandboxLoginConfig(): LoginConfig {
+  const redirectUri = deriveDefaultRedirectUri();
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    redirectUri,
+    popupRedirectUri: redirectUri,
+    scope: DEFAULT_SCOPE,
+    audience: DEFAULT_AUDIENCE,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN,
+  };
+}
+
+function getSandboxLogoutConfig(): LogoutConfig {
+  if (typeof window === 'undefined') {
+    throw new Error(
+      '[auth-next-client] getSandboxLogoutConfig requires window. '
+      + 'Logout runs in the browser when the user triggers it.',
+    );
+  }
+  const logoutRedirectUri = window.location.origin + DEFAULT_LOGOUT_REDIRECT_URI_PATH;
+  return {
+    clientId: DEFAULT_SANDBOX_CLIENT_ID,
+    logoutRedirectUri,
+    authenticationDomain: DEFAULT_AUTH_DOMAIN,
+  };
+}
+
 /**
  * Internal session type with full token data (not exported).
  * Used internally by the hook for token validation, refresh logic, and getUser/getAccessToken.
@@ -181,6 +221,8 @@ export function useImmutableSession(): UseImmutableSessionReturn {
   // `!isRefreshing` to briefly lose their cached data, resulting in UI flicker.
   useEffect(() => {
     if (!session?.accessTokenExpires) return;
+    // Don't retry if the last refresh already failed - prevents infinite loops
+    if (session?.error) return;
 
     const timeUntilExpiry = session.accessTokenExpires - Date.now() - TOKEN_EXPIRY_BUFFER_MS;
 
@@ -188,7 +230,7 @@ export function useImmutableSession(): UseImmutableSessionReturn {
       // Already expired -- refresh silently
       deduplicatedUpdate(() => updateRef.current());
     }
-  }, [session?.accessTokenExpires]);
+  }, [session?.accessTokenExpires, session?.error]);
 
   // ---------------------------------------------------------------------------
   // Sync idToken to localStorage
@@ -341,14 +383,17 @@ export function useImmutableSession(): UseImmutableSessionReturn {
 
 /**
  * Return type for useLogin hook
+ *
+ * Config is optional - when omitted, defaults are auto-derived (clientId, redirectUri, etc.).
+ * When provided, must be a complete LoginConfig.
  */
 export interface UseLoginReturn {
   /** Start login with popup flow */
-  loginWithPopup: (config: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
+  loginWithPopup: (config?: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
   /** Start login with embedded modal flow */
-  loginWithEmbedded: (config: LoginConfig) => Promise<void>;
+  loginWithEmbedded: (config?: LoginConfig) => Promise<void>;
   /** Start login with redirect flow (navigates away from page) */
-  loginWithRedirect: (config: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
+  loginWithRedirect: (config?: LoginConfig, options?: StandaloneLoginOptions) => Promise<void>;
   /** Whether login is currently in progress */
   isLoggingIn: boolean;
   /** Error message from the last login attempt, or null if none */
@@ -356,39 +401,70 @@ export interface UseLoginReturn {
 }
 
 /**
- * Hook to handle Immutable authentication login flows.
+ * Hook to handle Immutable authentication login flows with automatic defaults.
  *
  * Provides login functions that:
  * 1. Handle OAuth authentication via popup, embedded modal, or redirect
  * 2. Automatically sign in to NextAuth after successful authentication
  * 3. Track loading and error states
+ * 4. Auto-detect clientId and redirectUri if not provided (uses defaults)
  *
- * Config is passed at call time to allow different configurations for different
- * login methods (e.g., different redirectUri vs popupRedirectUri).
+ * Config can be passed at call time or omitted to use sensible defaults:
+ * - `clientId`: Auto-detected based on environment (sandbox vs production)
+ * - `redirectUri`: Auto-derived from `window.location.origin + '/callback'`
+ * - `popupRedirectUri`: Auto-derived from `window.location.origin + '/callback'` (same as redirectUri)
+ * - `logoutRedirectUri`: Auto-derived from `window.location.origin`
+ * - `scope`: `'openid profile email offline_access transact'`
+ * - `audience`: `'platform_api'`
+ * - `authenticationDomain`: `'https://auth.immutable.com'`
  *
  * Must be used within a SessionProvider from next-auth/react.
  *
- * @example
+ * @example Minimal usage (uses all defaults)
  * ```tsx
  * import { useLogin, useImmutableSession } from '@imtbl/auth-next-client';
  *
- * const config = {
- *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
- *   redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
- *   popupRedirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback/popup`,
- * };
+ * function LoginButton() {
+ *   const { isAuthenticated } = useImmutableSession();
+ *   const { loginWithPopup, isLoggingIn, error } = useLogin();
+ *
+ *   if (isAuthenticated) {
+ *     return <p>You are logged in!</p>;
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => loginWithPopup()} disabled={isLoggingIn}>
+ *         {isLoggingIn ? 'Signing in...' : 'Sign In'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom configuration
+ * ```tsx
+ * import { useLogin, useImmutableSession } from '@imtbl/auth-next-client';
  *
  * function LoginButton() {
  *   const { isAuthenticated } = useImmutableSession();
  *   const { loginWithPopup, isLoggingIn, error } = useLogin();
  *
+ *   const handleLogin = () => {
+ *     loginWithPopup({
+ *       clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID,
+ *       redirectUri: `${window.location.origin}/callback`,
+ *     });
+ *   };
+ *
  *   if (isAuthenticated) {
  *     return <p>You are logged in!</p>;
  *   }
  *
  *   return (
  *     <>
- *       <button onClick={() => loginWithPopup(config)} disabled={isLoggingIn}>
+ *       <button onClick={handleLogin} disabled={isLoggingIn}>
  *         {isLoggingIn ? 'Signing in...' : 'Sign In'}
  *       </button>
  *       {error && <p style={{ color: 'red' }}>{error}</p>}
@@ -434,16 +510,18 @@ export function useLogin(): UseLoginReturn {
   /**
    * Login with a popup window.
    * Opens a popup for OAuth authentication, then signs in to NextAuth.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
   const loginWithPopup = useCallback(async (
-    config: LoginConfig,
+    config?: LoginConfig,
     options?: StandaloneLoginOptions,
   ): Promise<void> => {
     setIsLoggingIn(true);
     setError(null);
 
     try {
-      const tokens = await rawLoginWithPopup(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await rawLoginWithPopup(fullConfig, options);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Login failed';
@@ -457,13 +535,15 @@ export function useLogin(): UseLoginReturn {
   /**
    * Login with an embedded modal.
    * Shows a modal for login method selection, then opens a popup for OAuth.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
-  const loginWithEmbedded = useCallback(async (config: LoginConfig): Promise<void> => {
+  const loginWithEmbedded = useCallback(async (config?: LoginConfig): Promise<void> => {
     setIsLoggingIn(true);
     setError(null);
 
     try {
-      const tokens = await rawLoginWithEmbedded(config);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      const tokens = await rawLoginWithEmbedded(fullConfig);
       await signInWithTokens(tokens);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Login failed';
@@ -479,16 +559,18 @@ export function useLogin(): UseLoginReturn {
    * Redirects the page to OAuth authentication.
    * After authentication, the user will be redirected to your callback page.
    * Use the CallbackPage component to complete the flow.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
   const loginWithRedirect = useCallback(async (
-    config: LoginConfig,
+    config?: LoginConfig,
     options?: StandaloneLoginOptions,
   ): Promise<void> => {
     setIsLoggingIn(true);
     setError(null);
 
     try {
-      await rawLoginWithRedirect(config, options);
+      const fullConfig = config ?? getSandboxLoginConfig();
+      await rawLoginWithRedirect(fullConfig, options);
       // Note: The page will redirect, so this code may not run
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Login failed';
@@ -518,9 +600,11 @@ export interface UseLogoutReturn {
    * This ensures that when the user logs in again, they will be prompted to select
    * an account instead of being automatically logged in with the previous account.
    *
-   * @param config - Logout configuration with clientId and optional redirectUri
+   * Config is optional - defaults will be auto-derived if not provided.
+   *
+   * @param config - Optional logout configuration with clientId and optional redirectUri
    */
-  logout: (config: LogoutConfig) => Promise<void>;
+  logout: (config?: LogoutConfig) => Promise<void>;
   /** Whether logout is currently in progress */
   isLoggingOut: boolean;
   /** Error message from the last logout attempt, or null if none */
@@ -538,16 +622,38 @@ export interface UseLogoutReturn {
  * an account (for social logins like Google) instead of being automatically logged
  * in with the previous account.
  *
+ * Config is optional - defaults will be auto-derived if not provided:
+ * - `clientId`: Auto-detected based on environment (sandbox vs production)
+ * - `logoutRedirectUri`: Auto-derived from `window.location.origin`
+ *
  * Must be used within a SessionProvider from next-auth/react.
  *
- * @example
+ * @example Minimal usage (uses all defaults)
  * ```tsx
  * import { useLogout, useImmutableSession } from '@imtbl/auth-next-client';
  *
- * const logoutConfig = {
- *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
- *   logoutRedirectUri: process.env.NEXT_PUBLIC_BASE_URL!,
- * };
+ * function LogoutButton() {
+ *   const { isAuthenticated } = useImmutableSession();
+ *   const { logout, isLoggingOut, error } = useLogout();
+ *
+ *   if (!isAuthenticated) {
+ *     return null;
+ *   }
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => logout()} disabled={isLoggingOut}>
+ *         {isLoggingOut ? 'Signing out...' : 'Sign Out'}
+ *       </button>
+ *       {error && <p style={{ color: 'red' }}>{error}</p>}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example With custom configuration
+ * ```tsx
+ * import { useLogout, useImmutableSession } from '@imtbl/auth-next-client';
  *
  * function LogoutButton() {
  *   const { isAuthenticated } = useImmutableSession();
@@ -559,7 +665,13 @@ export interface UseLogoutReturn {
  *
  *   return (
  *     <>
- *       <button onClick={() => logout(logoutConfig)} disabled={isLoggingOut}>
+ *       <button
+ *         onClick={() => logout({
+ *           clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID,
+ *           logoutRedirectUri: `${window.location.origin}/custom-logout`,
+ *         })}
+ *         disabled={isLoggingOut}
+ *       >
  *         {isLoggingOut ? 'Signing out...' : 'Sign Out'}
  *       </button>
  *       {error && <p style={{ color: 'red' }}>{error}</p>}
@@ -575,8 +687,9 @@ export function useLogout(): UseLogoutReturn {
   /**
    * Logout with federated logout.
    * First clears the NextAuth session, then redirects to the auth domain's logout endpoint.
+   * Config is optional - defaults will be auto-derived if not provided.
    */
-  const logout = useCallback(async (config: LogoutConfig): Promise<void> => {
+  const logout = useCallback(async (config?: LogoutConfig): Promise<void> => {
     setIsLoggingOut(true);
     setError(null);
 
@@ -588,10 +701,13 @@ export function useLogout(): UseLogoutReturn {
       // We use redirect: false to handle the redirect ourselves for federated logout
       await signOut({ redirect: false });
 
+      // Create full config with defaults
+      const fullConfig = config ?? getSandboxLogoutConfig();
+
       // Redirect to the auth domain's logout endpoint using the standalone function
       // This clears the upstream session (Auth0/Immutable) so that on next login,
       // the user will be prompted to select an account instead of auto-logging in
-      rawLogoutWithRedirect(config);
+      rawLogoutWithRedirect(fullConfig);
     } catch (err) {
       const errorMessage = err instanceof Error ? err.message : 'Logout failed';
       setError(errorMessage);

package/src/index.ts

@@ -59,3 +59,15 @@ export type {
   LogoutConfig,
 } from '@imtbl/auth';
 export { MarketingConsentStatus } from '@imtbl/auth';
+
+// Re-export constants and default config helpers for consumer convenience
+export {
+  DEFAULT_AUTH_DOMAIN,
+  DEFAULT_AUDIENCE,
+  DEFAULT_SCOPE,
+  IMMUTABLE_PROVIDER_ID,
+  DEFAULT_SANDBOX_CLIENT_ID,
+  DEFAULT_REDIRECT_URI_PATH,
+  DEFAULT_LOGOUT_REDIRECT_URI_PATH,
+} from './constants';
+export { deriveDefaultRedirectUri } from './defaultConfig';