@imtbl/auth-nextjs 2.12.4-alpha.6 → 2.12.4-alpha.8

package/README.md

@@ -61,10 +61,12 @@ const config = {
 };
 
 export default function Callback() {
-  return <CallbackPage config={config} />;
+  return <CallbackPage config={config} redirectTo="/dashboard" />;
 }
 ```
 
+See [CallbackPage Props](#callbackpage-props) for all available options.
+
 ### 4. Add Provider to Layout
 
 ```typescript
@@ -166,14 +168,15 @@ export const config = {
 
 The `ImmutableAuthConfig` object accepts the following properties:
 
-| Property               | Type     | Required | Default                                          | Description                    |
-| ---------------------- | -------- | -------- | ------------------------------------------------ | ------------------------------ |
-| `clientId`             | `string` | Yes      | -                                                | Immutable OAuth client ID      |
-| `redirectUri`          | `string` | Yes      | -                                                | OAuth callback redirect URI    |
-| `logoutRedirectUri`    | `string` | No       | -                                                | Where to redirect after logout |
-| `audience`             | `string` | No       | `"platform_api"`                                 | OAuth audience                 |
-| `scope`                | `string` | No       | `"openid profile email offline_access transact"` | OAuth scopes                   |
-| `authenticationDomain` | `string` | No       | `"https://auth.immutable.com"`                   | Authentication domain          |
+| Property               | Type     | Required | Default                                          | Description                                     |
+| ---------------------- | -------- | -------- | ------------------------------------------------ | ----------------------------------------------- |
+| `clientId`             | `string` | Yes      | -                                                | Immutable OAuth client ID                       |
+| `redirectUri`          | `string` | Yes      | -                                                | OAuth callback redirect URI (for redirect flow) |
+| `popupRedirectUri`     | `string` | No       | `redirectUri`                                    | OAuth callback redirect URI for popup flow      |
+| `logoutRedirectUri`    | `string` | No       | -                                                | Where to redirect after logout                  |
+| `audience`             | `string` | No       | `"platform_api"`                                 | OAuth audience                                  |
+| `scope`                | `string` | No       | `"openid profile email offline_access transact"` | OAuth scopes                                    |
+| `authenticationDomain` | `string` | No       | `"https://auth.immutable.com"`                   | Authentication domain                           |
 
 ## Environment Variables
 
@@ -223,6 +226,69 @@ openssl rand -base64 32
 | `useAccessToken()`      | Hook returning `getAccessToken` function               |
 | `CallbackPage`          | Pre-built callback page component for OAuth redirects  |
 
+#### CallbackPage Props
+
+| Prop               | Type                                                  | Default | Description                                                        |
+| ------------------ | ----------------------------------------------------- | ------- | ------------------------------------------------------------------ |
+| `config`           | `ImmutableAuthConfig`                                 | -       | Required. Immutable auth configuration                             |
+| `redirectTo`       | `string \| ((user: ImmutableUser) => string \| void)` | `"/"`   | Where to redirect after successful auth (supports dynamic routing) |
+| `loadingComponent` | `React.ReactElement \| null`                          | `null`  | Custom loading UI while processing authentication                  |
+| `errorComponent`   | `(error: string) => React.ReactElement \| null`       | -       | Custom error UI component                                          |
+| `onSuccess`        | `(user: ImmutableUser) => void \| Promise<void>`      | -       | Callback fired after successful authentication                     |
+| `onError`          | `(error: string) => void`                             | -       | Callback fired when authentication fails                           |
+
+**Example with all props:**
+
+```tsx
+// app/callback/page.tsx
+"use client";
+
+import { CallbackPage } from "@imtbl/auth-nextjs/client";
+import { Spinner } from "@/components/ui/spinner";
+
+const config = {
+  clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+  redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
+};
+
+export default function Callback() {
+  return (
+    <CallbackPage
+      config={config}
+      // Dynamic redirect based on user
+      redirectTo={(user) => {
+        if (user.email?.endsWith("@admin.com")) return "/admin";
+        return "/dashboard";
+      }}
+      // Custom loading UI
+      loadingComponent={
+        <div className="flex items-center justify-center min-h-screen">
+          <Spinner />
+          <span>Completing authentication...</span>
+        </div>
+      }
+      // Custom error UI
+      errorComponent={(error) => (
+        <div className="text-center p-8">
+          <h2 className="text-red-500">Authentication Error</h2>
+          <p>{error}</p>
+          <a href="/">Return Home</a>
+        </div>
+      )}
+      // Success callback for analytics
+      onSuccess={async (user) => {
+        await analytics.track("login_success", { userId: user.sub });
+      }}
+      // Error callback for logging
+      onError={(error) => {
+        console.error("Auth failed:", error);
+        Sentry.captureMessage(error);
+      }}
+    />
+  );
+}
+```
+
 **`useImmutableAuth()` Return Value:**
 
 | Property          | Type                    | Description                                      |

package/dist/node/{chunk-BRDI4KXS.js → chunk-BLU3AV4X.js}

@@ -247,6 +247,9 @@ function createImmutableAuth(config, overrides) {
     if (overrides.callbacks.redirect) {
       composedCallbacks.redirect = overrides.callbacks.redirect;
     }
+    if (overrides.callbacks.authorized) {
+      composedCallbacks.authorized = overrides.callbacks.authorized;
+    }
   }
   const mergedConfig = {
     ...authConfig,

package/dist/node/client/index.cjs

@@ -76,22 +76,24 @@ function ImmutableAuthInner({
   const [isAuthReady, setIsAuthReady] = (0, import_react.useState)(false);
   const { data: session, update: updateSession } = (0, import_react2.useSession)();
   (0, import_react.useEffect)(() => {
-    if (typeof window === "undefined") return;
+    if (typeof window === "undefined") return void 0;
     const configKey = [
       config.clientId,
       config.redirectUri,
+      config.popupRedirectUri || "",
       config.logoutRedirectUri || "",
       config.audience || DEFAULT_AUDIENCE,
       config.scope || DEFAULT_SCOPE,
       config.authenticationDomain || DEFAULT_AUTH_DOMAIN
     ].join(":");
     if (prevConfigRef.current === configKey) {
-      return;
+      return void 0;
     }
     prevConfigRef.current = configKey;
     const newAuth = new import_auth2.Auth({
       clientId: config.clientId,
       redirectUri: config.redirectUri,
+      popupRedirectUri: config.popupRedirectUri,
       logoutRedirectUri: config.logoutRedirectUri,
       audience: config.audience || DEFAULT_AUDIENCE,
       scope: config.scope || DEFAULT_SCOPE,
@@ -99,6 +101,11 @@ function ImmutableAuthInner({
     });
     setAuth(newAuth);
     setIsAuthReady(true);
+    return () => {
+      setAuth(null);
+      setIsAuthReady(false);
+      prevConfigRef.current = null;
+    };
   }, [config]);
   (0, import_react.useEffect)(() => {
     if (!auth || !isAuthReady) return;
@@ -262,7 +269,9 @@ function CallbackPage({
   config,
   redirectTo = "/",
   loadingComponent = null,
-  errorComponent
+  errorComponent,
+  onSuccess,
+  onError
 }) {
   const router = (0, import_navigation.useRouter)();
   const searchParams = (0, import_navigation.useSearchParams)();
@@ -284,6 +293,14 @@ function CallbackPage({
           if (!authUser) {
             throw new Error("Authentication failed: no user data received from login callback");
           }
+          const user = {
+            sub: authUser.profile.sub,
+            email: authUser.profile.email,
+            nickname: authUser.profile.nickname
+          };
+          if (onSuccess) {
+            await onSuccess(user);
+          }
           window.close();
         } else if (authUser) {
           const tokenData = {
@@ -308,29 +325,58 @@ function CallbackPage({
           if (!result?.ok) {
             throw new Error("NextAuth sign-in failed: unknown error");
           }
-          router.replace(redirectTo);
+          const user = {
+            sub: authUser.profile.sub,
+            email: authUser.profile.email,
+            nickname: authUser.profile.nickname
+          };
+          if (onSuccess) {
+            await onSuccess(user);
+          }
+          const resolvedRedirectTo = typeof redirectTo === "function" ? redirectTo(user) || "/" : redirectTo;
+          router.replace(resolvedRedirectTo);
         } else {
           throw new Error("Authentication failed: no user data received from login callback");
         }
       } catch (err) {
-        setError(err instanceof Error ? err.message : "Authentication failed");
+        const errorMessage2 = err instanceof Error ? err.message : "Authentication failed";
+        if (onError) {
+          onError(errorMessage2);
+        }
+        setError(errorMessage2);
       }
     };
     const handleOAuthError = () => {
       const errorCode = searchParams.get("error");
       const errorDescription = searchParams.get("error_description");
-      const errorMessage = errorDescription || errorCode || "Authentication failed";
-      setError(errorMessage);
+      const errorMessage2 = errorDescription || errorCode || "Authentication failed";
+      if (onError) {
+        onError(errorMessage2);
+      }
+      setError(errorMessage2);
     };
-    if (searchParams.get("error")) {
+    if (callbackProcessedRef.current) {
+      return;
+    }
+    const hasError = searchParams.get("error");
+    const hasCode = searchParams.get("code");
+    if (hasError) {
+      callbackProcessedRef.current = true;
       handleOAuthError();
       return;
     }
-    if (searchParams.get("code") && !callbackProcessedRef.current) {
+    if (hasCode) {
       callbackProcessedRef.current = true;
       handleCallback();
+      return;
+    }
+    callbackProcessedRef.current = true;
+    const errorMessage = "Invalid callback: missing OAuth parameters. Please try logging in again.";
+    if (onError) {
+      onError(errorMessage);
     }
-  }, [searchParams, router, config, redirectTo]);
+    setError(errorMessage);
+  }, [searchParams, router, config, redirectTo, onSuccess, onError]);
   if (error) {
     if (errorComponent) {
       return errorComponent(error);

package/dist/node/client/index.js

@@ -62,22 +62,24 @@ function ImmutableAuthInner({
   const [isAuthReady, setIsAuthReady] = useState(false);
   const { data: session, update: updateSession } = useSession();
   useEffect(() => {
-    if (typeof window === "undefined") return;
+    if (typeof window === "undefined") return void 0;
     const configKey = [
       config.clientId,
       config.redirectUri,
+      config.popupRedirectUri || "",
       config.logoutRedirectUri || "",
       config.audience || DEFAULT_AUDIENCE,
       config.scope || DEFAULT_SCOPE,
       config.authenticationDomain || DEFAULT_AUTH_DOMAIN
     ].join(":");
     if (prevConfigRef.current === configKey) {
-      return;
+      return void 0;
     }
     prevConfigRef.current = configKey;
     const newAuth = new Auth({
       clientId: config.clientId,
       redirectUri: config.redirectUri,
+      popupRedirectUri: config.popupRedirectUri,
       logoutRedirectUri: config.logoutRedirectUri,
       audience: config.audience || DEFAULT_AUDIENCE,
       scope: config.scope || DEFAULT_SCOPE,
@@ -85,6 +87,11 @@ function ImmutableAuthInner({
     });
     setAuth(newAuth);
     setIsAuthReady(true);
+    return () => {
+      setAuth(null);
+      setIsAuthReady(false);
+      prevConfigRef.current = null;
+    };
   }, [config]);
   useEffect(() => {
     if (!auth || !isAuthReady) return;
@@ -248,7 +255,9 @@ function CallbackPage({
   config,
   redirectTo = "/",
   loadingComponent = null,
-  errorComponent
+  errorComponent,
+  onSuccess,
+  onError
 }) {
   const router = useRouter();
   const searchParams = useSearchParams();
@@ -270,6 +279,14 @@ function CallbackPage({
           if (!authUser) {
             throw new Error("Authentication failed: no user data received from login callback");
           }
+          const user = {
+            sub: authUser.profile.sub,
+            email: authUser.profile.email,
+            nickname: authUser.profile.nickname
+          };
+          if (onSuccess) {
+            await onSuccess(user);
+          }
           window.close();
         } else if (authUser) {
           const tokenData = {
@@ -294,29 +311,58 @@ function CallbackPage({
           if (!result?.ok) {
             throw new Error("NextAuth sign-in failed: unknown error");
           }
-          router.replace(redirectTo);
+          const user = {
+            sub: authUser.profile.sub,
+            email: authUser.profile.email,
+            nickname: authUser.profile.nickname
+          };
+          if (onSuccess) {
+            await onSuccess(user);
+          }
+          const resolvedRedirectTo = typeof redirectTo === "function" ? redirectTo(user) || "/" : redirectTo;
+          router.replace(resolvedRedirectTo);
         } else {
           throw new Error("Authentication failed: no user data received from login callback");
         }
       } catch (err) {
-        setError(err instanceof Error ? err.message : "Authentication failed");
+        const errorMessage2 = err instanceof Error ? err.message : "Authentication failed";
+        if (onError) {
+          onError(errorMessage2);
+        }
+        setError(errorMessage2);
       }
     };
     const handleOAuthError = () => {
       const errorCode = searchParams.get("error");
       const errorDescription = searchParams.get("error_description");
-      const errorMessage = errorDescription || errorCode || "Authentication failed";
-      setError(errorMessage);
+      const errorMessage2 = errorDescription || errorCode || "Authentication failed";
+      if (onError) {
+        onError(errorMessage2);
+      }
+      setError(errorMessage2);
     };
-    if (searchParams.get("error")) {
+    if (callbackProcessedRef.current) {
+      return;
+    }
+    const hasError = searchParams.get("error");
+    const hasCode = searchParams.get("code");
+    if (hasError) {
+      callbackProcessedRef.current = true;
       handleOAuthError();
       return;
     }
-    if (searchParams.get("code") && !callbackProcessedRef.current) {
+    if (hasCode) {
       callbackProcessedRef.current = true;
       handleCallback();
+      return;
+    }
+    callbackProcessedRef.current = true;
+    const errorMessage = "Invalid callback: missing OAuth parameters. Please try logging in again.";
+    if (onError) {
+      onError(errorMessage);
     }
-  }, [searchParams, router, config, redirectTo]);
+    setError(errorMessage);
+  }, [searchParams, router, config, redirectTo, onSuccess, onError]);
   if (error) {
     if (errorComponent) {
       return errorComponent(error);

package/dist/node/index.cjs

@@ -290,6 +290,9 @@ function createImmutableAuth(config, overrides) {
     if (overrides.callbacks.redirect) {
       composedCallbacks.redirect = overrides.callbacks.redirect;
     }
+    if (overrides.callbacks.authorized) {
+      composedCallbacks.authorized = overrides.callbacks.authorized;
+    }
   }
   const mergedConfig = {
     ...authConfig,

package/dist/node/index.js

@@ -9,7 +9,7 @@ import {
   createImmutableAuth,
   isTokenExpired,
   refreshAccessToken
-} from "./chunk-BRDI4KXS.js";
+} from "./chunk-BLU3AV4X.js";
 export {
   DEFAULT_AUDIENCE,
   DEFAULT_AUTH_DOMAIN,

package/dist/node/server/index.cjs

@@ -284,6 +284,9 @@ function createImmutableAuth(config, overrides) {
     if (overrides.callbacks.redirect) {
       composedCallbacks.redirect = overrides.callbacks.redirect;
     }
+    if (overrides.callbacks.authorized) {
+      composedCallbacks.authorized = overrides.callbacks.authorized;
+    }
   }
   const mergedConfig = {
     ...authConfig,

package/dist/node/server/index.js

@@ -1,7 +1,7 @@
 import {
   createAuthConfig,
   createImmutableAuth
-} from "../chunk-BRDI4KXS.js";
+} from "../chunk-BLU3AV4X.js";
 
 // src/server/index.ts
 import { NextResponse } from "next/server";

package/dist/types/client/callback.d.ts

@@ -1,14 +1,30 @@
 import React from 'react';
-import type { ImmutableAuthConfig } from '../types';
+import type { ImmutableAuthConfig, ImmutableUser } from '../types';
 export interface CallbackPageProps {
     /**
      * Immutable auth configuration
      */
     config: ImmutableAuthConfig;
     /**
-     * URL to redirect to after successful authentication (when not in popup)
+     * URL to redirect to after successful authentication (when not in popup).
+     * Can be a string or a function that receives the authenticated user.
+     * If a function returns void/undefined, defaults to "/".
+     * @default "/"
+     *
+     * @example Static redirect
+     * ```tsx
+     * <CallbackPage config={config} redirectTo="/dashboard" />
+     * ```
+     *
+     * @example Dynamic redirect based on user
+     * ```tsx
+     * <CallbackPage
+     *   config={config}
+     *   redirectTo={(user) => user.email?.endsWith('@admin.com') ? '/admin' : '/dashboard'}
+     * />
+     * ```
      */
-    redirectTo?: string;
+    redirectTo?: string | ((user: ImmutableUser) => string | void);
     /**
      * Custom loading component
      */
@@ -17,6 +33,19 @@ export interface CallbackPageProps {
      * Custom error component
      */
     errorComponent?: (error: string) => React.ReactElement | null;
+    /**
+     * Callback fired after successful authentication.
+     * Receives the authenticated user as a parameter.
+     * Called before redirect (non-popup) or before window.close (popup).
+     * If this callback returns a Promise, it will be awaited before proceeding.
+     */
+    onSuccess?: (user: ImmutableUser) => void | Promise<void>;
+    /**
+     * Callback fired when authentication fails.
+     * Receives the error message as a parameter.
+     * Called before the error UI is displayed.
+     */
+    onError?: (error: string) => void;
 }
 /**
  * Callback page component for handling OAuth redirects (App Router version).
@@ -39,4 +68,4 @@ export interface CallbackPageProps {
  * }
  * ```
  */
-export declare function CallbackPage({ config, redirectTo, loadingComponent, errorComponent, }: CallbackPageProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function CallbackPage({ config, redirectTo, loadingComponent, errorComponent, onSuccess, onError, }: CallbackPageProps): import("react/jsx-runtime").JSX.Element | null;

package/dist/types/types.d.ts

@@ -9,9 +9,14 @@ export interface ImmutableAuthConfig {
      */
     clientId: string;
     /**
-     * OAuth callback redirect URI
+     * OAuth callback redirect URI (used for redirect flow)
      */
     redirectUri: string;
+    /**
+     * OAuth callback redirect URI for popup flow
+     * If not provided, falls back to redirectUri
+     */
+    popupRedirectUri?: string;
     /**
      * Where to redirect after logout
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth-nextjs",
-  "version": "2.12.4-alpha.6",
+  "version": "2.12.4-alpha.8",
   "description": "Next.js App Router authentication integration for Immutable SDK using Auth.js v5",
   "author": "Immutable",
   "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
@@ -51,7 +51,7 @@
     "dist"
   ],
   "dependencies": {
-    "@imtbl/auth": "2.12.4-alpha.6"
+    "@imtbl/auth": "2.12.4-alpha.8"
   },
   "peerDependencies": {
     "next": "14.2.25",