@imtbl/auth-next-client 2.12.5-alpha.13

package/dist/node/index.js

@@ -0,0 +1,486 @@
+'use client';
+
+// src/provider.tsx
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  useCallback,
+  useMemo
+} from "react";
+import {
+  SessionProvider,
+  useSession,
+  signIn,
+  signOut
+} from "next-auth/react";
+import {
+  Auth,
+  AuthEvents
+} from "@imtbl/auth";
+
+// src/utils/token.ts
+import { decodeJwtPayload } 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_NEXTAUTH_BASE_PATH = "/api/auth";
+var DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
+var DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1e3;
+
+// src/utils/token.ts
+function getTokenExpiry(accessToken) {
+  if (!accessToken) {
+    return Date.now() + DEFAULT_TOKEN_EXPIRY_MS;
+  }
+  try {
+    const payload = decodeJwtPayload(accessToken);
+    if (payload.exp && typeof payload.exp === "number") {
+      return payload.exp * 1e3;
+    }
+    return Date.now() + DEFAULT_TOKEN_EXPIRY_MS;
+  } catch {
+    return Date.now() + DEFAULT_TOKEN_EXPIRY_MS;
+  }
+}
+
+// src/provider.tsx
+import { jsx } from "react/jsx-runtime";
+var ImmutableAuthContext = createContext(null);
+function ImmutableAuthInner({
+  children,
+  config,
+  basePath
+}) {
+  const [auth, setAuth] = useState(null);
+  const prevConfigRef = useRef(null);
+  const authInstanceRef = useRef(null);
+  const [isAuthReady, setIsAuthReady] = useState(false);
+  const { data: session, update: updateSession } = useSession();
+  useEffect(() => {
+    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,
+      config.passportDomain || ""
+    ].join(":");
+    if (prevConfigRef.current === configKey && authInstanceRef.current !== null) {
+      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,
+      authenticationDomain: config.authenticationDomain || DEFAULT_AUTH_DOMAIN,
+      passportDomain: config.passportDomain
+    });
+    authInstanceRef.current = newAuth;
+    setAuth(newAuth);
+    setIsAuthReady(true);
+    return () => {
+      authInstanceRef.current = null;
+      setAuth(null);
+      setIsAuthReady(false);
+    };
+  }, [config]);
+  useEffect(() => {
+    if (!auth || !isAuthReady) return void 0;
+    const handleLoggedIn = async (authUser) => {
+      if (session?.accessToken && authUser.accessToken !== session.accessToken) {
+        await updateSession({
+          accessToken: authUser.accessToken,
+          refreshToken: authUser.refreshToken,
+          idToken: authUser.idToken,
+          accessTokenExpires: getTokenExpiry(authUser.accessToken),
+          zkEvm: authUser.zkEvm
+        });
+      }
+    };
+    const handleTokenRefreshed = async (authUser) => {
+      await updateSession({
+        accessToken: authUser.accessToken,
+        refreshToken: authUser.refreshToken,
+        idToken: authUser.idToken,
+        accessTokenExpires: getTokenExpiry(authUser.accessToken),
+        zkEvm: authUser.zkEvm
+      });
+    };
+    const handleUserRemoved = async (payload) => {
+      console.warn("[auth-next-client] User removed from Auth SDK:", payload.reason, payload.error);
+      await signOut({ redirect: false });
+    };
+    const handleLoggedOut = async () => {
+      await signOut({ redirect: false });
+    };
+    auth.eventEmitter.on(AuthEvents.LOGGED_IN, handleLoggedIn);
+    auth.eventEmitter.on(AuthEvents.TOKEN_REFRESHED, handleTokenRefreshed);
+    auth.eventEmitter.on(AuthEvents.USER_REMOVED, handleUserRemoved);
+    auth.eventEmitter.on(AuthEvents.LOGGED_OUT, handleLoggedOut);
+    return () => {
+      auth.eventEmitter.removeListener(AuthEvents.LOGGED_IN, handleLoggedIn);
+      auth.eventEmitter.removeListener(AuthEvents.TOKEN_REFRESHED, handleTokenRefreshed);
+      auth.eventEmitter.removeListener(AuthEvents.USER_REMOVED, handleUserRemoved);
+      auth.eventEmitter.removeListener(AuthEvents.LOGGED_OUT, handleLoggedOut);
+    };
+  }, [auth, isAuthReady, session, updateSession]);
+  const contextValue = useMemo(
+    () => ({ auth, config, basePath }),
+    [auth, config, basePath]
+  );
+  return /* @__PURE__ */ jsx(ImmutableAuthContext.Provider, { value: contextValue, children });
+}
+function ImmutableAuthProvider({
+  children,
+  config,
+  session,
+  basePath = DEFAULT_NEXTAUTH_BASE_PATH
+}) {
+  return /* @__PURE__ */ jsx(SessionProvider, { session, basePath, children: /* @__PURE__ */ jsx(ImmutableAuthInner, { config, basePath, children }) });
+}
+function useImmutableAuth() {
+  const context = useContext(ImmutableAuthContext);
+  const { data: sessionData, status } = useSession();
+  const [isLoggingIn, setIsLoggingIn] = useState(false);
+  if (!context) {
+    throw new Error("useImmutableAuth must be used within ImmutableAuthProvider");
+  }
+  const session = sessionData;
+  const { auth } = context;
+  const isLoading = status === "loading";
+  const isAuthenticated = status === "authenticated" && !!session;
+  const user = session?.user ? {
+    sub: session.user.sub,
+    email: session.user.email,
+    nickname: session.user.nickname
+  } : null;
+  const handleSignIn = useCallback(async (options) => {
+    if (!auth) {
+      throw new Error("Auth not initialized");
+    }
+    setIsLoggingIn(true);
+    try {
+      const authUser = await auth.login(options);
+      if (!authUser) {
+        throw new Error("Login failed");
+      }
+      const tokenData = {
+        accessToken: authUser.accessToken,
+        refreshToken: authUser.refreshToken,
+        idToken: authUser.idToken,
+        accessTokenExpires: getTokenExpiry(authUser.accessToken),
+        profile: {
+          sub: authUser.profile.sub,
+          email: authUser.profile.email,
+          nickname: authUser.profile.nickname
+        },
+        zkEvm: authUser.zkEvm
+      };
+      const result = await signIn(IMMUTABLE_PROVIDER_ID, {
+        tokens: JSON.stringify(tokenData),
+        redirect: false
+      });
+      if (result?.error) {
+        throw new Error(`NextAuth sign-in failed: ${result.error}`);
+      }
+      if (!result?.ok) {
+        throw new Error("NextAuth sign-in failed: unknown error");
+      }
+    } finally {
+      setIsLoggingIn(false);
+    }
+  }, [auth]);
+  const handleSignOut = useCallback(async () => {
+    if (auth) {
+      try {
+        await auth.getLogoutUrl();
+      } catch (error) {
+        console.warn("[auth-next-client] Logout cleanup error:", error);
+        await signOut({ redirect: false });
+      }
+    } else {
+      await signOut({ redirect: false });
+    }
+  }, [auth]);
+  const getAccessToken = useCallback(async () => {
+    if (auth) {
+      try {
+        const token = await auth.getAccessToken();
+        if (token) {
+          return token;
+        }
+      } catch {
+      }
+    }
+    if (session?.error) {
+      throw new Error(
+        session.error === "TokenExpired" ? "Session expired. Please log in again." : `Authentication error: ${session.error}`
+      );
+    }
+    if (session?.accessToken) {
+      return session.accessToken;
+    }
+    throw new Error("No access token available");
+  }, [auth, session]);
+  return {
+    user,
+    session,
+    isLoading,
+    isLoggingIn,
+    isAuthenticated,
+    signIn: handleSignIn,
+    signOut: handleSignOut,
+    getAccessToken,
+    auth
+  };
+}
+function useAccessToken() {
+  const { getAccessToken } = useImmutableAuth();
+  return getAccessToken;
+}
+function useHydratedData(props, fetcher) {
+  const { getAccessToken, auth } = useImmutableAuth();
+  const {
+    ssr,
+    data: serverData,
+    fetchError
+  } = props;
+  const needsClientFetch = !ssr || Boolean(fetchError);
+  const [data, setData] = useState(serverData);
+  const [isLoading, setIsLoading] = useState(needsClientFetch);
+  const [error, setError] = useState(
+    fetchError ? new Error(fetchError) : null
+  );
+  const hasFetchedRef = useRef(false);
+  const fetchIdRef = useRef(0);
+  const prevPropsRef = useRef({ serverData, ssr, fetchError });
+  useEffect(() => {
+    const prevProps = prevPropsRef.current;
+    const propsChanged = prevProps.serverData !== serverData || prevProps.ssr !== ssr || prevProps.fetchError !== fetchError;
+    if (propsChanged) {
+      prevPropsRef.current = { serverData, ssr, fetchError };
+      hasFetchedRef.current = false;
+      fetchIdRef.current += 1;
+      if (ssr && !fetchError) {
+        setData(serverData);
+        setIsLoading(false);
+        setError(null);
+      } else {
+        setData(null);
+        setIsLoading(true);
+        setError(fetchError ? new Error(fetchError) : null);
+      }
+    }
+  }, [serverData, ssr, fetchError]);
+  const fetchData = useCallback(async () => {
+    const currentFetchId = fetchIdRef.current;
+    setIsLoading(true);
+    setError(null);
+    try {
+      const token = await getAccessToken();
+      const result = await fetcher(token);
+      if (fetchIdRef.current === currentFetchId) {
+        setData(result);
+      }
+    } catch (err) {
+      if (fetchIdRef.current === currentFetchId) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (fetchIdRef.current === currentFetchId) {
+        setIsLoading(false);
+      }
+    }
+  }, [fetcher, getAccessToken]);
+  useEffect(() => {
+    if (hasFetchedRef.current) return;
+    if (!needsClientFetch) return;
+    if (!ssr && !auth) return;
+    hasFetchedRef.current = true;
+    fetchData();
+  }, [needsClientFetch, ssr, auth, fetchData]);
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: fetchData
+  };
+}
+
+// src/callback.tsx
+import { useEffect as useEffect2, useState as useState2, useRef as useRef2 } from "react";
+import { useRouter } from "next/navigation";
+import { signIn as signIn2 } from "next-auth/react";
+import { Auth as Auth2 } from "@imtbl/auth";
+import { jsx as jsx2, jsxs } from "react/jsx-runtime";
+function getSearchParams() {
+  if (typeof window === "undefined") {
+    return new URLSearchParams();
+  }
+  return new URLSearchParams(window.location.search);
+}
+function CallbackPage({
+  config,
+  redirectTo = "/",
+  loadingComponent = null,
+  errorComponent,
+  onSuccess,
+  onError
+}) {
+  const router = useRouter();
+  const [error, setError] = useState2(null);
+  const callbackProcessedRef = useRef2(false);
+  useEffect2(() => {
+    const searchParams = getSearchParams();
+    const handleCallback = async () => {
+      try {
+        const auth = new Auth2({
+          clientId: config.clientId,
+          redirectUri: config.redirectUri,
+          popupRedirectUri: config.popupRedirectUri,
+          logoutRedirectUri: config.logoutRedirectUri,
+          audience: config.audience || DEFAULT_AUDIENCE,
+          scope: config.scope || DEFAULT_SCOPE,
+          authenticationDomain: config.authenticationDomain || DEFAULT_AUTH_DOMAIN,
+          passportDomain: config.passportDomain
+        });
+        const authUser = await auth.loginCallback();
+        if (window.opener) {
+          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 = {
+            accessToken: authUser.accessToken,
+            refreshToken: authUser.refreshToken,
+            idToken: authUser.idToken,
+            accessTokenExpires: getTokenExpiry(authUser.accessToken),
+            profile: {
+              sub: authUser.profile.sub,
+              email: authUser.profile.email,
+              nickname: authUser.profile.nickname
+            },
+            zkEvm: authUser.zkEvm
+          };
+          const result = await signIn2(IMMUTABLE_PROVIDER_ID, {
+            tokens: JSON.stringify(tokenData),
+            redirect: false
+          });
+          if (result?.error) {
+            throw new Error(`NextAuth sign-in failed: ${result.error}`);
+          }
+          if (!result?.ok) {
+            throw new Error("NextAuth sign-in failed: unknown error");
+          }
+          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) {
+        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 errorMessage2 = errorDescription || errorCode || "Authentication failed";
+      if (onError) {
+        onError(errorMessage2);
+      }
+      setError(errorMessage2);
+    };
+    if (callbackProcessedRef.current) {
+      return;
+    }
+    const hasError = searchParams.get("error");
+    const hasCode = searchParams.get("code");
+    if (hasError) {
+      callbackProcessedRef.current = true;
+      handleOAuthError();
+      return;
+    }
+    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);
+    }
+    setError(errorMessage);
+  }, [router, config, redirectTo, onSuccess, onError]);
+  if (error) {
+    if (errorComponent) {
+      return errorComponent(error);
+    }
+    return /* @__PURE__ */ jsxs("div", { style: { padding: "2rem", textAlign: "center" }, children: [
+      /* @__PURE__ */ jsx2("h2", { style: { color: "#dc3545" }, children: "Authentication Error" }),
+      /* @__PURE__ */ jsx2("p", { children: error }),
+      /* @__PURE__ */ jsx2(
+        "button",
+        {
+          onClick: () => router.push("/"),
+          type: "button",
+          style: {
+            padding: "0.5rem 1rem",
+            marginTop: "1rem",
+            cursor: "pointer"
+          },
+          children: "Return to Home"
+        }
+      )
+    ] });
+  }
+  if (loadingComponent) {
+    return loadingComponent;
+  }
+  return /* @__PURE__ */ jsx2("div", { style: { padding: "2rem", textAlign: "center" }, children: /* @__PURE__ */ jsx2("p", { children: "Completing authentication..." }) });
+}
+
+// src/index.ts
+import { MarketingConsentStatus } from "@imtbl/auth";
+export {
+  CallbackPage,
+  ImmutableAuthProvider,
+  MarketingConsentStatus,
+  useAccessToken,
+  useHydratedData,
+  useImmutableAuth
+};

package/dist/node/provider.d.ts

@@ -0,0 +1,66 @@
+import type { Session } from 'next-auth';
+import type { ImmutableAuthProviderProps, UseImmutableAuthReturn } from './types';
+/**
+ * Provider component for Immutable authentication with Auth.js v5
+ *
+ * Wraps your app to provide authentication state via useImmutableAuth hook.
+ *
+ * @example App Router (recommended)
+ * ```tsx
+ * // app/providers.tsx
+ * "use client";
+ * import { ImmutableAuthProvider } from "@imtbl/auth-next-client";
+ *
+ * const config = {
+ *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+ *   redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
+ * };
+ *
+ * export function Providers({ children }: { children: React.ReactNode }) {
+ *   return (
+ *     <ImmutableAuthProvider config={config}>
+ *       {children}
+ *     </ImmutableAuthProvider>
+ *   );
+ * }
+ * ```
+ */
+export declare function ImmutableAuthProvider({ children, config, session, basePath, }: ImmutableAuthProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access Immutable authentication state and methods
+ *
+ * Must be used within an ImmutableAuthProvider.
+ */
+export declare function useImmutableAuth(): UseImmutableAuthReturn;
+/**
+ * Hook to get a function that returns a valid access token
+ */
+export declare function useAccessToken(): () => Promise<string>;
+/**
+ * Result from useHydratedData hook
+ */
+export interface UseHydratedDataResult<T> {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => Promise<void>;
+}
+/**
+ * Props for useHydratedData hook - matches AuthPropsWithData from server
+ */
+export interface HydratedDataProps<T> {
+    session: Session | null;
+    ssr: boolean;
+    data: T | null;
+    fetchError?: string;
+    authError?: string;
+}
+/**
+ * Hook for hydrating server-fetched data with automatic client-side fallback.
+ *
+ * This is the recommended pattern for components that receive data from `getAuthenticatedData`:
+ * - When `ssr: true` and `data` exists: Uses pre-fetched server data immediately (no loading state)
+ * - When `ssr: false`: Refreshes token client-side and fetches data
+ * - When `fetchError` exists: Retries fetch client-side
+ */
+export declare function useHydratedData<T>(props: HydratedDataProps<T>, fetcher: (accessToken: string) => Promise<T>): UseHydratedDataResult<T>;

package/dist/node/types.d.ts

@@ -0,0 +1,133 @@
+import type { DefaultSession, Session } from 'next-auth';
+export type { ImmutableAuthConfig, ImmutableTokenData, ZkEvmUser, ImmutableUser, } from '@imtbl/auth-next-server';
+/**
+ * zkEVM wallet information
+ */
+export interface ZkEvmInfo {
+    ethAddress: string;
+    userAdminAddress: string;
+}
+/**
+ * Auth.js v5 module augmentation to add Immutable-specific fields
+ */
+declare module 'next-auth' {
+    interface Session extends DefaultSession {
+        user: {
+            sub: string;
+            email?: string;
+            nickname?: string;
+        } & DefaultSession['user'];
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        accessTokenExpires: number;
+        zkEvm?: ZkEvmInfo;
+        error?: string;
+    }
+    interface User {
+        id: string;
+        sub: string;
+        email?: string | null;
+        nickname?: string;
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        accessTokenExpires: number;
+        zkEvm?: ZkEvmInfo;
+    }
+}
+/**
+ * Props for ImmutableAuthProvider
+ */
+export interface ImmutableAuthProviderProps {
+    children: React.ReactNode;
+    /**
+     * Immutable auth configuration
+     */
+    config: {
+        clientId: string;
+        redirectUri: string;
+        popupRedirectUri?: string;
+        logoutRedirectUri?: string;
+        audience?: string;
+        scope?: string;
+        authenticationDomain?: string;
+        passportDomain?: string;
+    };
+    /**
+     * Initial session from server (for SSR hydration)
+     * Can be Session from auth() or any compatible session object
+     */
+    session?: Session | DefaultSession | null;
+    /**
+     * Custom base path for Auth.js API routes
+     * Use this when you have multiple auth endpoints (e.g., per environment)
+     * @default "/api/auth"
+     */
+    basePath?: string;
+}
+/**
+ * User profile from Immutable (local definition for client)
+ */
+export interface ImmutableUserClient {
+    sub: string;
+    email?: string;
+    nickname?: string;
+}
+/**
+ * Token data passed from client to Auth.js credentials provider
+ */
+export interface ImmutableTokenDataClient {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    accessTokenExpires: number;
+    profile: {
+        sub: string;
+        email?: string;
+        nickname?: string;
+    };
+    zkEvm?: ZkEvmInfo;
+}
+/**
+ * Return type of useImmutableAuth hook
+ */
+export interface UseImmutableAuthReturn {
+    /**
+     * Current user profile (null if not authenticated)
+     */
+    user: ImmutableUserClient | null;
+    /**
+     * Full Auth.js session with tokens
+     */
+    session: Session | null;
+    /**
+     * Whether authentication state is loading (initial session fetch)
+     */
+    isLoading: boolean;
+    /**
+     * Whether a login flow is in progress (popup open, waiting for OAuth callback)
+     */
+    isLoggingIn: boolean;
+    /**
+     * Whether user is authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * Sign in with Immutable (opens popup)
+     * @param options - Optional login options (cached session, silent login, redirect flow, direct login)
+     */
+    signIn: (options?: import('@imtbl/auth').LoginOptions) => Promise<void>;
+    /**
+     * Sign out from both Auth.js and Immutable
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Get a valid access token (refreshes if needed)
+     */
+    getAccessToken: () => Promise<string>;
+    /**
+     * The underlying Auth instance (for advanced use)
+     */
+    auth: import('@imtbl/auth').Auth | null;
+}

package/dist/node/utils/token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extract the expiry timestamp from a JWT access token.
+ * Returns the expiry as a Unix timestamp in milliseconds.
+ *
+ * @param accessToken - JWT access token
+ * @returns Expiry timestamp in milliseconds, or a default 15-minute expiry if extraction fails
+ */
+export declare function getTokenExpiry(accessToken: string | undefined): number;

package/jest.config.ts

@@ -0,0 +1,16 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  clearMocks: true,
+  coverageProvider: 'v8',
+  moduleDirectories: ['node_modules', 'src'],
+  testEnvironment: 'jsdom',
+  transform: {
+    '^.+\\.(t|j)sx?$': '@swc/jest',
+  },
+  transformIgnorePatterns: [],
+  restoreMocks: true,
+  roots: ['<rootDir>/src'],
+};
+
+export default config;