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

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
@@ -223,6 +225,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/client/index.cjs

@@ -262,7 +262,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 +286,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,18 +318,34 @@ 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 errorMessage = err instanceof Error ? err.message : "Authentication failed";
+        if (onError) {
+          onError(errorMessage);
+        }
+        setError(errorMessage);
       }
     };
     const handleOAuthError = () => {
       const errorCode = searchParams.get("error");
       const errorDescription = searchParams.get("error_description");
       const errorMessage = errorDescription || errorCode || "Authentication failed";
+      if (onError) {
+        onError(errorMessage);
+      }
       setError(errorMessage);
     };
     if (searchParams.get("error")) {
@@ -330,7 +356,7 @@ function CallbackPage({
       callbackProcessedRef.current = true;
       handleCallback();
     }
-  }, [searchParams, router, config, redirectTo]);
+  }, [searchParams, router, config, redirectTo, onSuccess, onError]);
   if (error) {
     if (errorComponent) {
       return errorComponent(error);

package/dist/node/client/index.js

@@ -248,7 +248,9 @@ function CallbackPage({
   config,
   redirectTo = "/",
   loadingComponent = null,
-  errorComponent
+  errorComponent,
+  onSuccess,
+  onError
 }) {
   const router = useRouter();
   const searchParams = useSearchParams();
@@ -270,6 +272,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,18 +304,34 @@ 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 errorMessage = err instanceof Error ? err.message : "Authentication failed";
+        if (onError) {
+          onError(errorMessage);
+        }
+        setError(errorMessage);
       }
     };
     const handleOAuthError = () => {
       const errorCode = searchParams.get("error");
       const errorDescription = searchParams.get("error_description");
       const errorMessage = errorDescription || errorCode || "Authentication failed";
+      if (onError) {
+        onError(errorMessage);
+      }
       setError(errorMessage);
     };
     if (searchParams.get("error")) {
@@ -316,7 +342,7 @@ function CallbackPage({
       callbackProcessedRef.current = true;
       handleCallback();
     }
-  }, [searchParams, router, config, redirectTo]);
+  }, [searchParams, router, config, redirectTo, onSuccess, onError]);
   if (error) {
     if (errorComponent) {
       return errorComponent(error);

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth-nextjs",
-  "version": "2.12.4-alpha.6",
+  "version": "2.12.4-alpha.7",
   "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.7"
   },
   "peerDependencies": {
     "next": "14.2.25",