@erikey/react 0.4.30 → 0.4.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erikey/react",
-  "version": "0.4.30",
+  "version": "0.4.32",
   "description": "React SDK for Erikey - B2B authentication and user management. UI components based on better-auth-ui.",
   "main": "./dist/index.mjs",
   "module": "./dist/index.mjs",

package/src/ui/components/auth/auth-flow.tsx

@@ -0,0 +1,254 @@
+"use client"
+
+import { type ReactNode, useCallback, useMemo, useState } from "react"
+
+import { AuthUIContext, AuthUIProvider } from "../../lib/auth-ui-provider"
+import type { AuthUIProviderProps } from "../../lib/auth-ui-provider"
+import type {
+    AuthFlowEvent,
+    AuthFlowEventHandler,
+    AuthFlowView
+} from "../../types/auth-flow-events"
+import type { AuthViewPaths } from "../../lib/view-paths"
+import type { AuthViewClassNames } from "./auth-view"
+import { AuthView as AuthViewComponent } from "./auth-view"
+
+export interface AuthFlowProps
+    extends Omit<AuthUIProviderProps, "children" | "navigate"> {
+    /**
+     * Navigation mode for auth flow:
+     * - "internal": Manages view state internally without URL changes (single page)
+     * - "route": Uses URL-based navigation (Better Auth native behavior)
+     * @default "internal"
+     */
+    mode?: "internal" | "route"
+    /**
+     * Event handler for auth flow events.
+     * Called with typed events during sign-in, sign-up, verification, etc.
+     */
+    onEvent?: AuthFlowEventHandler
+    /**
+     * Initial view to display
+     * @default "SIGN_IN"
+     */
+    initialView?: AuthFlowView
+    /**
+     * URL to redirect to after successful authentication.
+     * In "internal" mode, called after AUTH_SUCCESS event.
+     */
+    redirectTo?: string
+    /**
+     * Custom navigate function for "route" mode.
+     * Defaults to window.location.href change.
+     */
+    navigate?: (href: string) => void
+    /**
+     * Additional class names for the auth view
+     */
+    className?: string
+    /**
+     * Class name overrides for specific elements
+     */
+    classNames?: AuthViewClassNames
+    /**
+     * Custom card header content
+     */
+    cardHeader?: ReactNode
+    /**
+     * Custom card footer content
+     */
+    cardFooter?: ReactNode
+    /**
+     * Layout for social provider buttons
+     * @default "auto"
+     */
+    socialLayout?: "auto" | "horizontal" | "grid" | "vertical"
+    /**
+     * Number of visual separators in OTP inputs
+     * @default 0
+     */
+    otpSeparators?: 0 | 1 | 2
+}
+
+/**
+ * Mapping from AuthFlowView to AuthViewPaths key
+ */
+const flowViewToPathKey: Record<AuthFlowView, keyof AuthViewPaths> = {
+    SIGN_IN: "SIGN_IN",
+    SIGN_UP: "SIGN_UP",
+    EMAIL_VERIFICATION: "EMAIL_VERIFICATION",
+    TWO_FACTOR: "TWO_FACTOR",
+    FORGOT_PASSWORD: "FORGOT_PASSWORD",
+    RESET_PASSWORD: "RESET_PASSWORD",
+    MAGIC_LINK: "MAGIC_LINK"
+}
+
+/**
+ * Parse a path to determine the view
+ */
+function parsePathToView(path: string): { view: AuthFlowView; email?: string } {
+    const url = new URL(path, "http://localhost")
+    const pathname = url.pathname
+    const email = url.searchParams.get("email") || undefined
+
+    if (pathname.includes("email-verification")) {
+        return { view: "EMAIL_VERIFICATION", email }
+    }
+    if (pathname.includes("two-factor")) {
+        return { view: "TWO_FACTOR", email }
+    }
+    if (pathname.includes("forgot-password")) {
+        return { view: "FORGOT_PASSWORD", email }
+    }
+    if (pathname.includes("reset-password")) {
+        return { view: "RESET_PASSWORD", email }
+    }
+    if (pathname.includes("sign-up")) {
+        return { view: "SIGN_UP", email }
+    }
+    if (pathname.includes("magic-link")) {
+        return { view: "MAGIC_LINK", email }
+    }
+    return { view: "SIGN_IN", email }
+}
+
+/**
+ * AuthFlow - Unified authentication component
+ *
+ * Handles all auth states (sign-in, sign-up, verification, 2FA) with two modes:
+ * - "internal": Single-page experience with state-based view switching
+ * - "route": URL-based navigation (Better Auth native)
+ *
+ * Emits typed events via onEvent for full observability.
+ *
+ * @example
+ * // Internal mode (single page)
+ * <AuthFlow
+ *   mode="internal"
+ *   authClient={authClient}
+ *   onEvent={(event) => {
+ *     if (event.type === 'AUTH_SUCCESS') {
+ *       router.push('/dashboard');
+ *     }
+ *     if (event.type === 'SIGN_UP_START') {
+ *       analytics.track('signup_started');
+ *     }
+ *   }}
+ * />
+ *
+ * @example
+ * // Route mode (URL changes)
+ * <AuthFlow
+ *   mode="route"
+ *   authClient={authClient}
+ *   basePath="/auth"
+ * />
+ */
+export function AuthFlow({
+    mode = "internal",
+    onEvent,
+    initialView = "SIGN_IN",
+    redirectTo = "/",
+    navigate: externalNavigate,
+    className,
+    classNames,
+    cardHeader,
+    cardFooter,
+    socialLayout = "auto",
+    otpSeparators = 0,
+    // AuthUIProvider props
+    authClient,
+    basePath = "/auth",
+    ...providerProps
+}: AuthFlowProps) {
+    // Internal state for "internal" mode
+    const [currentView, setCurrentView] = useState<AuthFlowView>(initialView)
+    const [verifyEmail, setVerifyEmail] = useState<string | undefined>()
+
+    // Handle navigation based on mode
+    const handleNavigate = useCallback(
+        (href: string) => {
+            if (mode === "route") {
+                // In route mode, use external navigate or default to location change
+                if (externalNavigate) {
+                    externalNavigate(href)
+                } else {
+                    window.location.href = href
+                }
+                return
+            }
+
+            // In internal mode, parse the path and update state
+            const { view, email } = parsePathToView(href)
+
+            // Emit view change event
+            onEvent?.({ type: "VIEW_CHANGE", view, email })
+
+            setCurrentView(view)
+            if (email) {
+                setVerifyEmail(email)
+            }
+        },
+        [mode, externalNavigate, onEvent]
+    )
+
+    // Combined event handler that wraps user's onEvent
+    const handleAuthEvent = useCallback(
+        (event: AuthFlowEvent) => {
+            // Forward to user's handler
+            onEvent?.(event)
+
+            // In internal mode, handle AUTH_SUCCESS by redirecting
+            if (mode === "internal" && event.type === "AUTH_SUCCESS") {
+                if (externalNavigate) {
+                    externalNavigate(redirectTo)
+                } else {
+                    window.location.href = redirectTo
+                }
+            }
+        },
+        [onEvent, mode, redirectTo, externalNavigate]
+    )
+
+    // Get the view key for AuthView component
+    const viewKey = useMemo(() => {
+        if (mode === "route") {
+            return undefined // Let AuthView determine from URL
+        }
+        return flowViewToPathKey[currentView]
+    }, [mode, currentView])
+
+    return (
+        <AuthUIProvider
+            authClient={authClient}
+            basePath={basePath}
+            navigate={handleNavigate}
+            onAuthEvent={handleAuthEvent}
+            redirectTo={redirectTo}
+            {...providerProps}
+        >
+            <AuthViewComponent
+                className={className}
+                classNames={classNames}
+                cardHeader={cardHeader}
+                cardFooter={cardFooter}
+                socialLayout={socialLayout}
+                otpSeparators={otpSeparators}
+                redirectTo={redirectTo}
+                view={viewKey}
+            />
+        </AuthUIProvider>
+    )
+}
+
+/**
+ * Hook to emit auth events from within the auth flow.
+ * Can be used by custom components within AuthFlow.
+ */
+export function useAuthFlowEvent() {
+    const context = AuthUIContext
+    // This hook allows custom components to emit events
+    // Usage: const emitEvent = useAuthFlowEvent()
+    // emitEvent({ type: 'CUSTOM_EVENT', ... })
+    return context
+}

package/src/ui/components/auth/forms/email-verification-form.tsx

@@ -26,6 +26,11 @@ export interface EmailVerificationFormProps {
     className?: string
     classNames?: AuthFormClassNames
     callbackURL?: string
+    /**
+     * Email address to verify. If not provided, reads from URL query params.
+     * Prop takes priority over URL params (for state-based navigation).
+     */
+    email?: string
     isSubmitting?: boolean
     localization: Partial<AuthLocalization>
     otpSeparators?: 0 | 1 | 2
@@ -41,6 +46,7 @@ export function EmailVerificationForm({
     classNames,
     otpSeparators,
     callbackURL,
+    email: emailProp,
     isSubmitting,
     redirectTo,
     setIsSubmitting
@@ -55,15 +61,22 @@ export function EmailVerificationForm({
         localizeErrors,
         navigate,
         basePath,
-        viewPaths
+        viewPaths,
+        emailVerification,
+        onAuthEvent
     } = useContext(AuthUIContext)
 
     localization = { ...contextLocalization, ...localization }
 
-    const email =
+    // Determine verification method from context (OTP vs Link)
+    const isOtpMethod = emailVerification?.otp ?? true
+
+    // Priority: prop > URL params (prop is explicit for state-based navigation)
+    const emailFromUrl =
         typeof window !== "undefined"
             ? new URLSearchParams(window.location.search).get("email") || ""
             : ""
+    const email = emailProp || emailFromUrl
 
     const { onSuccess, isPending: transitionPending } = useOnSuccessTransition({
         redirectTo
@@ -103,7 +116,21 @@ export function EmailVerificationForm({
         }
     }, [countdown])
 
+    // Emit verification start event on mount
+    useEffect(() => {
+        if (email) {
+            onAuthEvent?.({
+                type: "VERIFICATION_START",
+                email,
+                method: isOtpMethod ? "otp" : "link"
+            })
+        }
+    }, [email, isOtpMethod, onAuthEvent])
+
     async function verifyCode({ code }: z.infer<typeof formSchema>) {
+        // Emit code submitted event
+        onAuthEvent?.({ type: "VERIFICATION_CODE_SUBMITTED", email })
+
         try {
             const data = await authClient.emailOtp.verifyEmail({
                 email,
@@ -111,9 +138,27 @@ export function EmailVerificationForm({
                 fetchOptions: { throw: true }
             })
 
+            // Build user object for events
+            const user = (data as { user?: Record<string, unknown> }).user as {
+                id: string
+                email: string
+                name?: string | null
+                image?: string | null
+                emailVerified: boolean
+            }
+
             if ("token" in data && data.token) {
+                const session = {
+                    token: data.token as string,
+                    user
+                }
+                onAuthEvent?.({ type: "VERIFICATION_SUCCESS", user, session })
+                onAuthEvent?.({ type: "AUTH_SUCCESS", user, session })
                 await onSuccess()
             } else {
+                // No token - verification succeeded but no session
+                const session = { user }
+                onAuthEvent?.({ type: "VERIFICATION_SUCCESS", user, session })
                 navigate(
                     `${basePath}/${viewPaths.SIGN_IN}${window.location.search}`
                 )
@@ -123,13 +168,24 @@ export function EmailVerificationForm({
                 })
             }
         } catch (error) {
+            const errorMessage = getLocalizedError({
+                error,
+                localization,
+                localizeErrors
+            })
+
+            const errorCode = (
+                error as { error?: { code?: string; message?: string } }
+            )?.error?.code
+
+            onAuthEvent?.({
+                type: "VERIFICATION_ERROR",
+                error: { message: errorMessage, code: errorCode }
+            })
+
             toast({
                 variant: "error",
-                message: getLocalizedError({
-                    error,
-                    localization,
-                    localizeErrors
-                })
+                message: errorMessage
             })
 
             form.reset()
@@ -149,6 +205,8 @@ export function EmailVerificationForm({
                 fetchOptions: { throw: true }
             })
 
+            onAuthEvent?.({ type: "VERIFICATION_CODE_RESENT", email })
+
             toast({
                 variant: "success",
                 message: localization.EMAIL_OTP_VERIFICATION_SENT!
@@ -167,6 +225,40 @@ export function EmailVerificationForm({
         }
     }
 
+    async function resendVerificationLink() {
+        if (resendDisabled) return
+
+        setResendDisabled(true)
+        setCountdown(30)
+
+        try {
+            await authClient.sendVerificationEmail({
+                email,
+                fetchOptions: { throw: true }
+            })
+
+            onAuthEvent?.({ type: "VERIFICATION_CODE_RESENT", email })
+
+            toast({
+                variant: "success",
+                message:
+                    (localization as Record<string, string | undefined>)
+                        .VERIFICATION_EMAIL_SENT || "Verification email sent!"
+            })
+        } catch (error) {
+            toast({
+                variant: "error",
+                message: getLocalizedError({
+                    error,
+                    localization,
+                    localizeErrors
+                })
+            })
+            setResendDisabled(false)
+            setCountdown(0)
+        }
+    }
+
     if (!email) {
         return (
             <div className={cn("grid w-full gap-6", className)}>
@@ -183,6 +275,58 @@ export function EmailVerificationForm({
         )
     }
 
+    // Link-based verification: show "check your email" message
+    // Use type assertion for custom localization keys
+    const loc = localization as Record<string, string | undefined>
+
+    if (!isOtpMethod) {
+        return (
+            <div className={cn("grid w-full gap-6", className, classNames?.base)}>
+                <div className="text-center space-y-2">
+                    <h2 className="font-semibold text-lg">
+                        {loc.CHECK_YOUR_EMAIL || "Check your email"}
+                    </h2>
+                    <p className="text-muted-foreground text-sm">
+                        {loc.VERIFICATION_LINK_SENT_TO ||
+                            "We sent a verification link to"}{" "}
+                        <strong>{email}</strong>
+                    </p>
+                    <p className="text-muted-foreground text-xs">
+                        {loc.CLICK_LINK_TO_VERIFY ||
+                            "Click the link in your email to verify your account."}
+                    </p>
+                </div>
+
+                <div className="grid gap-4">
+                    <Button
+                        type="button"
+                        variant="outline"
+                        onClick={resendVerificationLink}
+                        disabled={resendDisabled}
+                        className={cn("w-full", classNames?.button)}
+                    >
+                        {resendDisabled
+                            ? `${localization.RESEND_VERIFICATION_EMAIL || "Resend verification email"} (${countdown}s)`
+                            : localization.RESEND_VERIFICATION_EMAIL ||
+                              "Resend verification email"}
+                    </Button>
+
+                    {onCancel && (
+                        <Button
+                            type="button"
+                            variant="ghost"
+                            onClick={onCancel}
+                            className="w-full"
+                        >
+                            {localization.CANCEL || "Cancel"}
+                        </Button>
+                    )}
+                </div>
+            </div>
+        )
+    }
+
+    // OTP-based verification: show OTP input form
     return (
         <Form {...form}>
             <form

package/src/ui/components/auth/forms/sign-in-form.tsx

@@ -68,7 +68,8 @@ export function SignInForm({
         toast,
         Link,
         localizeErrors,
-        emailVerification
+        emailVerification,
+        onAuthEvent
     } = useContext(AuthUIContext)
 
     const rememberMeEnabled = credentials?.rememberMe
@@ -115,6 +116,9 @@ export function SignInForm({
         password,
         rememberMe
     }: z.infer<typeof formSchema>) {
+        // Emit start event
+        onAuthEvent?.({ type: "SIGN_IN_START", email })
+
         try {
             let response: Record<string, unknown> = {}
 
@@ -145,10 +149,26 @@ export function SignInForm({
             }
 
             if (response.twoFactorRedirect) {
+                onAuthEvent?.({ type: "SIGN_IN_REQUIRES_2FA", email })
                 navigate(
                     `${basePath}/${viewPaths.TWO_FACTOR}${window.location.search}`
                 )
             } else {
+                // Build user and session for events
+                const user = response.user as {
+                    id: string
+                    email: string
+                    name?: string | null
+                    image?: string | null
+                    emailVerified: boolean
+                }
+                const session = {
+                    token: response.token as string | undefined,
+                    user
+                }
+
+                onAuthEvent?.({ type: "SIGN_IN_SUCCESS", user, session })
+                onAuthEvent?.({ type: "AUTH_SUCCESS", user, session })
                 await onSuccess()
             }
         } catch (error) {
@@ -161,6 +181,16 @@ export function SignInForm({
                 localizeErrors
             })
 
+            const errorCode = (
+                error as { error?: { code?: string; message?: string } }
+            )?.error?.code
+
+            // Emit error event
+            onAuthEvent?.({
+                type: "SIGN_IN_ERROR",
+                error: { message: errorMessage, code: errorCode }
+            })
+
             // Set inline error for display
             form.setError("root", { message: errorMessage })
 
@@ -170,11 +200,8 @@ export function SignInForm({
                 message: errorMessage
             })
 
-            if (
-                emailVerification?.otp &&
-                (error as { error?: { code?: string; message?: string } })
-                    ?.error?.code === "EMAIL_NOT_VERIFIED"
-            ) {
+            if (errorCode === "EMAIL_NOT_VERIFIED") {
+                onAuthEvent?.({ type: "SIGN_IN_REQUIRES_VERIFICATION", email })
                 navigate(
                     `${basePath}/${
                         viewPaths.EMAIL_VERIFICATION

package/src/ui/components/auth/forms/sign-up-form.tsx

@@ -92,7 +92,8 @@ export function SignUpForm({
         toast,
         avatar,
         localizeErrors,
-        emailVerification
+        emailVerification,
+        onAuthEvent
     } = useContext(AuthUIContext)
 
     const confirmPasswordEnabled = credentials?.confirmPassword
@@ -331,6 +332,13 @@ export function SignUpForm({
         image,
         ...additionalFieldValues
     }: z.infer<typeof formSchema>) {
+        // Emit start event
+        onAuthEvent?.({
+            type: "SIGN_UP_START",
+            email: email as string,
+            name: name as string | undefined
+        })
+
         try {
             // Validate additional fields with custom validators if provided
             for (const [field, value] of Object.entries(
@@ -384,18 +392,56 @@ export function SignUpForm({
                 fetchOptions
             })
 
+            // Type the response for type safety
+            const response = data as {
+                user?: {
+                    id: string
+                    email: string
+                    name?: string | null
+                    image?: string | null
+                    emailVerified: boolean
+                }
+                token?: string
+                twoFactorRedirect?: boolean
+            }
+
+            // Build user object for events
+            const user = response.user
+
+            // Emit sign up success (user created)
+            if (user) {
+                onAuthEvent?.({ type: "SIGN_UP_SUCCESS", user })
+            }
+
             // Check for 2FA redirect first (same pattern as sign-in form)
-            if ((data as { twoFactorRedirect?: boolean }).twoFactorRedirect) {
+            if (response.twoFactorRedirect) {
                 navigate(
                     `${basePath}/${viewPaths.TWO_FACTOR}${window.location.search}`
                 )
-            } else if ("token" in data && data.token) {
+            } else if (response.token && user) {
+                // Token present = verified or no verification required
+                const session = {
+                    token: response.token,
+                    user
+                }
+                onAuthEvent?.({ type: "AUTH_SUCCESS", user, session })
                 await onSuccess()
-            } else if (emailVerification?.otp) {
+            } else if (user && user.emailVerified === false) {
+                // No token + emailVerified: false = needs verification
+                // This is response-based (Better Auth pattern), not config-based
+                onAuthEvent?.({
+                    type: "SIGN_UP_REQUIRES_VERIFICATION",
+                    email: email as string
+                })
                 navigate(
                     `${basePath}/${viewPaths.EMAIL_VERIFICATION}?email=${encodeURIComponent(email as string)}`
                 )
             } else {
+                // Fallback: redirect to sign-in (e.g., link-based verification sent)
+                onAuthEvent?.({
+                    type: "SIGN_UP_REQUIRES_VERIFICATION",
+                    email: email as string
+                })
                 navigate(
                     `${basePath}/${viewPaths.SIGN_IN}${window.location.search}`
                 )
@@ -411,6 +457,16 @@ export function SignUpForm({
                 localizeErrors
             })
 
+            const errorCode = (
+                error as { error?: { code?: string; message?: string } }
+            )?.error?.code
+
+            // Emit error event
+            onAuthEvent?.({
+                type: "SIGN_UP_ERROR",
+                error: { message: errorMessage, code: errorCode }
+            })
+
             // Set inline error for display
             form.setError("root", { message: errorMessage })