@pagamio/frontend-commons-lib 0.8.279 → 0.8.281

package/lib/auth/components/LoginPage.d.ts

@@ -45,6 +45,25 @@ export interface PhoneOtpLoginConfig {
     /** Optional label for the password tab (default: 'Email & Password') */
     passwordTabLabel?: string;
 }
+/**
+ * Configuration for the phone PIN login tab.
+ * When provided, a "Phone + PIN" tab is displayed alongside the password tab.
+ */
+export interface PhonePinLoginConfig {
+    /** Login with phone number and PIN. Should throw on error. */
+    loginWithPin: (phoneNumber: string, pin: string) => Promise<any>;
+    /** Optional callback when forgot PIN is clicked */
+    onForgotPin?: () => void;
+    /**
+     * Optional callback called instead of onLoginSuccess when mustChangePIN is true.
+     * Use this to redirect to the forgot-pin flow.
+     */
+    onMustChangePIN?: (phoneNumber: string, response: any) => void;
+    /** Optional label for the phone-PIN tab (default: 'Phone + PIN') */
+    tabLabel?: string;
+    /** Optional label for the password tab (default: 'Email & Password') */
+    passwordTabLabel?: string;
+}
 /**
  * Base login credentials interface that can be extended for specific implementations
  */
@@ -121,6 +140,11 @@ interface PagamioLoginPageProps<T extends CustomAuthConfig> extends BaseAuthPage
      * The tab handles the full 2-step phone OTP flow internally.
      */
     phoneOtpConfig?: PhoneOtpLoginConfig;
+    /**
+     * When provided, adds a "Phone + PIN" tab alongside the standard login form.
+     * The tab handles the 2-step phone PIN flow internally.
+     */
+    phonePinConfig?: PhonePinLoginConfig;
 }
 export interface LoginErrorProps {
     code: string;
@@ -142,6 +166,6 @@ export declare const loginPageDefaultText: {
  * Generic Login Page component
  * @template T - Authentication configuration type
  */
-export declare function PagamioLoginPage<T extends CustomAuthConfig>({ logo, text, appLabel, onForgotPassword, onLoginSuccess, onLoginError, hasCreateAccount, createAccountRoute, onCreateAccount, transformLoginData, authenticatorType, loginFieldType, customLoginFields, className, features, sideContentClass, footer, phoneOtpConfig, }: Readonly<PagamioLoginPageProps<T>>): import("react/jsx-runtime").JSX.Element;
+export declare function PagamioLoginPage<T extends CustomAuthConfig>({ logo, text, appLabel, onForgotPassword, onLoginSuccess, onLoginError, hasCreateAccount, createAccountRoute, onCreateAccount, transformLoginData, authenticatorType, loginFieldType, customLoginFields, className, features, sideContentClass, footer, phoneOtpConfig, phonePinConfig, }: Readonly<PagamioLoginPageProps<T>>): import("react/jsx-runtime").JSX.Element;
 export default PagamioLoginPage;
 export type { PagamioLoginCredentials, PagamioLoginPageProps };

package/lib/auth/components/LoginPage.js

@@ -47,7 +47,7 @@ export const loginPageDefaultText = {
  * Generic Login Page component
  * @template T - Authentication configuration type
  */
-export function PagamioLoginPage({ logo, text = loginPageDefaultText, appLabel, onForgotPassword, onLoginSuccess, onLoginError, hasCreateAccount = false, createAccountRoute, onCreateAccount, transformLoginData, authenticatorType, loginFieldType = 'username', customLoginFields, className = '', features, sideContentClass, footer, phoneOtpConfig, }) {
+export function PagamioLoginPage({ logo, text = loginPageDefaultText, appLabel, onForgotPassword, onLoginSuccess, onLoginError, hasCreateAccount = false, createAccountRoute, onCreateAccount, transformLoginData, authenticatorType, loginFieldType = 'username', customLoginFields, className = '', features, sideContentClass, footer, phoneOtpConfig, phonePinConfig, }) {
     const { login, error: authError } = useAuth();
     const { addToast } = useToast();
     const [isLoading, setIsLoading] = useState(false);
@@ -63,6 +63,8 @@ export function PagamioLoginPage({ logo, text = loginPageDefaultText, appLabel,
     const [phoneError, setPhoneError] = useState(null);
     const [phoneCountdown, setPhoneCountdown] = useState(0);
     const [canResendPhone, setCanResendPhone] = useState(true);
+    const [phonePinValue, setPhonePinValue] = useState('');
+    const [isLoggingInWithPin, setIsLoggingInWithPin] = useState(false);
     const startCountdown = (seconds) => {
         setPhoneCountdown(seconds);
         setCanResendPhone(false);
@@ -91,6 +93,11 @@ export function PagamioLoginPage({ logo, text = loginPageDefaultText, appLabel,
     ];
     const handlePhoneFormSubmit = async (data) => {
         const phone = data.phoneNumber;
+        if (phonePinConfig) {
+            setPhoneNumber(phone);
+            setPhoneStep('enterPin');
+            return;
+        }
         setIsSendingOtp(true);
         setPhoneError(null);
         try {
@@ -107,6 +114,28 @@ export function PagamioLoginPage({ logo, text = loginPageDefaultText, appLabel,
             setIsSendingOtp(false);
         }
     };
+    const handleLoginWithPin = async () => {
+        if (phonePinValue.length !== 4)
+            return;
+        setIsLoggingInWithPin(true);
+        setPhoneError(null);
+        try {
+            const response = await phonePinConfig.loginWithPin(phoneNumber, phonePinValue);
+            const responseData = response?.data ?? response;
+            if (responseData?.mustChangePIN && phonePinConfig.onMustChangePIN) {
+                phonePinConfig.onMustChangePIN(phoneNumber, response);
+            }
+            else {
+                onLoginSuccess?.(response);
+            }
+        }
+        catch (err) {
+            setPhoneError(err?.response?.data?.message ?? err?.message ?? 'Login failed. Please try again.');
+        }
+        finally {
+            setIsLoggingInWithPin(false);
+        }
+    };
     const handleResendPhoneOtp = async () => {
         if (!canResendPhone || isResendingOtp)
             return;
@@ -224,12 +253,33 @@ export function PagamioLoginPage({ logo, text = loginPageDefaultText, appLabel,
             window.location.href = createAccountRoute;
         }
     };
-    const passwordTabLabel = phoneOtpConfig?.passwordTabLabel ?? 'Email & Password';
-    const phoneTabLabel = phoneOtpConfig?.tabLabel ?? 'Phone + OTP';
-    return (_jsx(AuthPageLayout, { appLabel: appLabel, title: text.welcomeTitle, subtitle: text.welcomeSubtitle, errorMessage: activeTab === 'password' ? (error ?? authError?.message) : undefined, logo: logo, className: className, horizontal: false, sideContent: features && features.length > 0 ? _jsx(FeatureCarousel, { features: features }) : undefined, sideContentClass: sideContentClass, footer: footer, children: _jsxs("div", { className: "mt-8", children: [phoneOtpConfig && (_jsxs("div", { className: "mb-6 flex rounded-lg border border-border overflow-hidden", children: [_jsx("button", { type: "button", onClick: () => setActiveTab('password'), className: `flex-1 py-2 text-sm font-medium transition-colors ${activeTab === 'password' ? 'bg-primary text-primary-foreground' : 'bg-background text-foreground/70 hover:bg-muted'}`, children: passwordTabLabel }), _jsx("button", { type: "button", onClick: () => { setActiveTab('phone'); setPhoneStep('enterPhone'); setPhoneError(null); }, className: `flex-1 py-2 text-sm font-medium transition-colors ${activeTab === 'phone' ? 'bg-primary text-primary-foreground' : 'bg-background text-foreground/70 hover:bg-muted'}`, children: phoneTabLabel })] })), activeTab === 'password' && (_jsxs(_Fragment, { children: [_jsx(FormEngine, { fields: loginFields, onSubmit: handleSubmit, layout: "vertical", className: "mb-0 px-0", submitButtonClass: "w-full", submitButtonText: isLoading ? text.loadingButtonLabel : text.loginButtonLabel, onCancel: () => { }, showCancelButton: false, showSubmittingText: false, formRef: formRef, initialValues: {
+    const showPhoneTab = phoneOtpConfig ?? phonePinConfig;
+    const passwordTabLabel = (phoneOtpConfig?.passwordTabLabel ?? phonePinConfig?.passwordTabLabel) ?? 'Email & Password';
+    const phoneTabLabel = phoneOtpConfig?.tabLabel ?? phonePinConfig?.tabLabel ?? (phonePinConfig ? 'Phone + PIN' : 'Phone + OTP');
+    return (_jsx(AuthPageLayout, { appLabel: appLabel, title: text.welcomeTitle, subtitle: text.welcomeSubtitle, errorMessage: activeTab === 'password' ? (error ?? authError?.message) : undefined, logo: logo, className: className, horizontal: false, sideContent: features && features.length > 0 ? _jsx(FeatureCarousel, { features: features }) : undefined, sideContentClass: sideContentClass, footer: footer, children: _jsxs("div", { className: "mt-8", children: [showPhoneTab && (_jsxs("div", { className: "mb-6 flex rounded-lg border border-border overflow-hidden", children: [_jsx("button", { type: "button", onClick: () => setActiveTab('password'), className: `flex-1 py-2 text-sm font-medium transition-colors ${activeTab === 'password' ? 'bg-primary text-primary-foreground' : 'bg-background text-foreground/70 hover:bg-muted'}`, children: passwordTabLabel }), _jsx("button", { type: "button", onClick: () => {
+                                setActiveTab('phone');
+                                setPhoneStep('enterPhone');
+                                setPhoneOtpValue('');
+                                setPhonePinValue('');
+                                setPhoneError(null);
+                            }, className: `flex-1 py-2 text-sm font-medium transition-colors ${activeTab === 'phone' ? 'bg-primary text-primary-foreground' : 'bg-background text-foreground/70 hover:bg-muted'}`, children: phoneTabLabel })] })), activeTab === 'password' && (_jsxs(_Fragment, { children: [_jsx(FormEngine, { fields: loginFields, onSubmit: handleSubmit, layout: "vertical", className: "mb-0 px-0", submitButtonClass: "w-full", submitButtonText: isLoading ? text.loadingButtonLabel : text.loginButtonLabel, onCancel: () => { }, showCancelButton: false, showSubmittingText: false, formRef: formRef, initialValues: {
                                 ...(loginFieldType === 'email' ? { email: '' } : { username: '' }),
                                 password: '',
                                 rememberMe: false,
-                            } }), _jsxs("div", { className: "flex items-center justify-center gap-x-4 mt-4", children: [onForgotPassword && (_jsx(Button, { type: "button", variant: "link", onClick: onForgotPassword, className: "text-sm text-primary hover:underline", children: text.forgotPasswordLabel })), hasCreateAccount && (_jsxs(_Fragment, { children: [onForgotPassword && _jsx("span", { className: "text-muted-foreground", children: "|" }), _jsx(Button, { type: "button", variant: "link", onClick: handleCreateAccount, className: "text-sm text-primary hover:underline", children: text.createAccountLabel })] }))] })] })), activeTab === 'phone' && phoneOtpConfig && (_jsxs("div", { className: "space-y-4", children: [phoneError && (_jsx("div", { className: "rounded-lg bg-red-50 p-4 text-sm text-red-600", children: phoneError })), phoneStep === 'enterPhone' && (_jsxs(_Fragment, { children: [_jsx(FormEngine, { fields: phoneNumberField, onSubmit: handlePhoneFormSubmit, layout: "vertical", className: "mb-0 px-0", submitButtonClass: "w-full", submitButtonText: isSendingOtp ? 'Sending code...' : 'Send code', onCancel: () => { }, showCancelButton: false, showSubmittingText: false, initialValues: { phoneNumber: '' } }), hasCreateAccount && (_jsx("div", { className: "text-center mt-2", children: _jsx(Button, { type: "button", variant: "link", onClick: handleCreateAccount, className: "text-sm text-primary hover:underline", children: text.createAccountLabel }) }))] })), phoneStep === 'enterOtp' && (_jsxs(_Fragment, { children: [_jsxs("p", { className: "text-sm text-muted-foreground text-center", children: ["Enter the 6-digit code sent to ", _jsx("span", { className: "font-medium text-foreground", children: phoneNumber })] }), _jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "Verification Code" }), _jsx(OtpInput, { length: 6, value: phoneOtpValue, onChange: (v) => { setPhoneOtpValue(v); setPhoneError(null); }, disabled: isVerifyingOtp })] }), _jsx(Button, { type: "button", onClick: handleVerifyPhoneOtp, disabled: phoneOtpValue.length !== 6 || isVerifyingOtp, className: "w-full", size: "lg", children: isVerifyingOtp ? 'Verifying...' : 'Verify & Sign In' }), _jsx("div", { className: "text-center text-sm text-muted-foreground", children: canResendPhone ? (_jsx(Button, { type: "button", variant: "ghost", onClick: handleResendPhoneOtp, disabled: isResendingOtp, className: "text-sm font-medium text-primary hover:text-primary/90", children: isResendingOtp ? 'Sending...' : 'Resend code' })) : (_jsxs("span", { children: ["Resend code in ", _jsxs("span", { className: "font-medium text-foreground", children: [phoneCountdown, "s"] })] })) }), _jsx(Button, { type: "button", variant: "ghost", onClick: () => { setPhoneStep('enterPhone'); setPhoneOtpValue(''); setPhoneError(null); }, className: "w-full text-sm text-foreground/70", children: "\u2190 Change number" })] }))] }))] }) }));
+                            } }), _jsxs("div", { className: "flex items-center justify-center gap-x-4 mt-4", children: [onForgotPassword && (_jsx(Button, { type: "button", variant: "link", onClick: onForgotPassword, className: "text-sm text-primary hover:underline", children: text.forgotPasswordLabel })), hasCreateAccount && (_jsxs(_Fragment, { children: [onForgotPassword && _jsx("span", { className: "text-muted-foreground", children: "|" }), _jsx(Button, { type: "button", variant: "link", onClick: handleCreateAccount, className: "text-sm text-primary hover:underline", children: text.createAccountLabel })] }))] })] })), activeTab === 'phone' && showPhoneTab && (_jsxs("div", { className: "space-y-4", children: [phoneError && _jsx("div", { className: "rounded-lg bg-red-50 p-4 text-sm text-red-600", children: phoneError }), phoneStep === 'enterPhone' && (_jsxs(_Fragment, { children: [_jsx(FormEngine, { fields: phoneNumberField, onSubmit: handlePhoneFormSubmit, layout: "vertical", className: "mb-0 px-0", submitButtonClass: "w-full", submitButtonText: isSendingOtp ? 'Sending code...' : 'Send code', onCancel: () => { }, showCancelButton: false, showSubmittingText: false, initialValues: { phoneNumber: '' } }), hasCreateAccount && (_jsx("div", { className: "text-center mt-2", children: _jsx(Button, { type: "button", variant: "link", onClick: handleCreateAccount, className: "text-sm text-primary hover:underline", children: text.createAccountLabel }) }))] })), phoneStep === 'enterOtp' && phoneOtpConfig && (_jsxs(_Fragment, { children: [_jsxs("p", { className: "text-sm text-muted-foreground text-center", children: ["Enter the 6-digit code sent to ", _jsx("span", { className: "font-medium text-foreground", children: phoneNumber })] }), _jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "Verification Code" }), _jsx(OtpInput, { length: 6, value: phoneOtpValue, onChange: (v) => {
+                                                setPhoneOtpValue(v);
+                                                setPhoneError(null);
+                                            }, disabled: isVerifyingOtp })] }), _jsx(Button, { type: "button", onClick: handleVerifyPhoneOtp, disabled: phoneOtpValue.length !== 6 || isVerifyingOtp, className: "w-full", size: "lg", children: isVerifyingOtp ? 'Verifying...' : 'Verify & Sign In' }), _jsx("div", { className: "text-center text-sm text-muted-foreground", children: canResendPhone ? (_jsx(Button, { type: "button", variant: "ghost", onClick: handleResendPhoneOtp, disabled: isResendingOtp, className: "text-sm font-medium text-primary hover:text-primary/90", children: isResendingOtp ? 'Sending...' : 'Resend code' })) : (_jsxs("span", { children: ["Resend code in ", _jsxs("span", { className: "font-medium text-foreground", children: [phoneCountdown, "s"] })] })) }), _jsx(Button, { type: "button", variant: "ghost", onClick: () => {
+                                        setPhoneStep('enterPhone');
+                                        setPhoneOtpValue('');
+                                        setPhoneError(null);
+                                    }, className: "w-full text-sm text-foreground/70", children: "\u2190 Change number" })] })), phoneStep === 'enterPin' && phonePinConfig && (_jsxs(_Fragment, { children: [_jsxs("p", { className: "text-sm text-muted-foreground text-center", children: ["Enter your 4-digit PIN for", ' ', _jsx("span", { className: "font-medium text-foreground", children: phoneNumber })] }), _jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "PIN" }), _jsx(OtpInput, { length: 4, value: phonePinValue, onChange: (v) => {
+                                                setPhonePinValue(v);
+                                                setPhoneError(null);
+                                            }, disabled: isLoggingInWithPin })] }), _jsx(Button, { type: "button", onClick: handleLoginWithPin, disabled: phonePinValue.length !== 4 || isLoggingInWithPin, className: "w-full", size: "lg", children: isLoggingInWithPin ? 'Signing in...' : 'Sign In' }), phonePinConfig.onForgotPin && (_jsx("div", { className: "text-center", children: _jsx(Button, { type: "button", variant: "link", onClick: phonePinConfig.onForgotPin, className: "text-sm text-primary hover:underline", children: "Forgot PIN?" }) })), _jsx(Button, { type: "button", variant: "ghost", onClick: () => {
+                                        setPhoneStep('enterPhone');
+                                        setPhonePinValue('');
+                                        setPhoneError(null);
+                                    }, className: "w-full text-sm text-foreground/70", children: "\u2190 Change number" })] }))] }))] }) }));
 }
 export default PagamioLoginPage;

package/lib/auth/components/OtpVerification.js

@@ -147,9 +147,7 @@ export const OtpVerificationPage = ({ email, phoneNumber, onVerifySuccess, onBac
             setIsResending(false);
         }
     };
-    return (_jsx("div", { className: `flex min-h-screen items-center justify-center bg-muted px-4 py-12 ${classNames.container ?? ''}`, children: _jsxs("div", { className: "w-full max-w-md", children: [logo && (_jsxs("div", { className: "mb-8 flex justify-center", children: [_jsx("img", { src: logo.src, alt: logo.alt, width: logo.width, height: logo.height, className: `h-auto max-h-16${logo.darkSrc ? ' dark:hidden' : ''}` }), logo.darkSrc && (_jsx("img", { src: logo.darkSrc, alt: logo.alt, width: logo.width, height: logo.height, className: "h-auto max-h-16 hidden dark:block" }))] })), _jsxs("div", { className: `rounded-2xl border border-border bg-background p-8 shadow-sm ${classNames.card ?? ''}`, children: [_jsxs("div", { className: `mb-6 text-center ${classNames.header ?? ''}`, children: [_jsx("div", { className: `mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-primary/15 ${classNames.icon ?? ''}`, children: isPhoneMode
-                                        ? _jsx(HiOutlinePhone, { className: "h-8 w-8 text-primary" })
-                                        : _jsx(HiOutlineMail, { className: "h-8 w-8 text-primary" }) }), _jsx("h1", { className: "text-2xl font-bold text-foreground", children: text.title }), _jsx("p", { className: "mt-2 text-sm text-muted-foreground", children: text.subtitle }), _jsx("p", { className: "mt-1 font-medium text-foreground", children: isPhoneMode ? phoneNumber : email })] }), error && _jsx("div", { className: "mb-4 rounded-lg bg-red-50 p-4 text-sm text-red-600", children: error }), _jsxs("div", { className: "mb-6", children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground", children: text.codeLabel }), _jsx(OtpInput, { length: otpLength, value: otpValue, onChange: (value) => {
+    return (_jsx("div", { className: `flex min-h-screen items-center justify-center bg-muted px-4 py-12 ${classNames.container ?? ''}`, children: _jsxs("div", { className: "w-full max-w-md", children: [logo && (_jsxs("div", { className: "mb-8 flex justify-center", children: [_jsx("img", { src: logo.src, alt: logo.alt, width: logo.width, height: logo.height, className: `h-auto max-h-16${logo.darkSrc ? ' dark:hidden' : ''}` }), logo.darkSrc && (_jsx("img", { src: logo.darkSrc, alt: logo.alt, width: logo.width, height: logo.height, className: "h-auto max-h-16 hidden dark:block" }))] })), _jsxs("div", { className: `rounded-2xl border border-border bg-background p-8 shadow-sm ${classNames.card ?? ''}`, children: [_jsxs("div", { className: `mb-6 text-center ${classNames.header ?? ''}`, children: [_jsx("div", { className: `mx-auto mb-4 flex h-16 w-16 items-center justify-center rounded-full bg-primary/15 ${classNames.icon ?? ''}`, children: isPhoneMode ? (_jsx(HiOutlinePhone, { className: "h-8 w-8 text-primary" })) : (_jsx(HiOutlineMail, { className: "h-8 w-8 text-primary" })) }), _jsx("h1", { className: "text-2xl font-bold text-foreground", children: text.title }), _jsx("p", { className: "mt-2 text-sm text-muted-foreground", children: text.subtitle }), _jsx("p", { className: "mt-1 font-medium text-foreground", children: isPhoneMode ? phoneNumber : email })] }), error && _jsx("div", { className: "mb-4 rounded-lg bg-red-50 p-4 text-sm text-red-600", children: error }), _jsxs("div", { className: "mb-6", children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground", children: text.codeLabel }), _jsx(OtpInput, { length: otpLength, value: otpValue, onChange: (value) => {
                                         setOtpValue(value);
                                         clearError();
                                     }, disabled: isVerifying })] }), _jsx(Button, { onClick: handleVerify, disabled: otpValue.length !== otpLength || isVerifying, className: "w-full", size: "lg", children: isVerifying ? (_jsxs(_Fragment, { children: [_jsx(Loader, { size: "sm", className: "mr-2" }), text.verifyingButton] })) : (text.verifyButton) }), _jsx("div", { className: "mt-6 text-center", children: canResend ? (_jsx(Button, { type: "button", variant: "ghost", onClick: handleResend, disabled: isResending, className: "text-sm font-medium text-primary hover:text-primary/90 disabled:text-muted-foreground", children: isResending ? text.resendingButton : text.resendButton })) : (_jsxs("p", { className: "text-sm text-muted-foreground", children: [text.resendCountdownText, " ", _jsxs("span", { className: "font-medium text-foreground", children: [countdown, "s"] })] })) }), _jsx("div", { className: "mt-6 border-t border-border pt-6", children: _jsxs(Button, { type: "button", variant: "ghost", onClick: onBack, className: "flex w-full items-center justify-center gap-2 text-sm text-foreground/70 hover:text-foreground", children: [_jsx(HiOutlineArrowLeft, { className: "h-4 w-4" }), text.backButton] }) })] })] }) }));

package/lib/auth/components/PhoneForgotPinPage.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Phone Forgot PIN Page component.
+ * Guides the user through a 3-step flow to reset their phone PIN:
+ *   1. Enter phone number → triggers OTP send
+ *   2. Enter 4-digit OTP → returns a verificationToken
+ *   3. Set a new 4-digit PIN (with confirmation)
+ */
+import React from 'react';
+export interface PhoneForgotPinPageProps {
+    /**
+     * Called with the phone number to trigger an OTP send.
+     * Should call POST /auth/forgot-phone-pin. Should throw on error.
+     */
+    onRequestOtp: (phoneNumber: string) => Promise<any>;
+    /**
+     * Called with phone + OTP to verify and obtain a verificationToken.
+     * Should call POST /auth/verify-phone-otp. Should throw on error.
+     * Must resolve to an object containing `verificationToken`.
+     */
+    onVerifyOtp: (phoneNumber: string, otpCode: string) => Promise<{
+        verificationToken: string;
+    }>;
+    /**
+     * Called with phone, verificationToken, and new PIN to complete the reset.
+     * Should call POST /auth/set-phone-pin. Should throw on error.
+     */
+    onSetPin: (phoneNumber: string, verificationToken: string, pin: string) => Promise<any>;
+    /** Called on successful PIN reset (after onSetPin resolves). */
+    onSuccess?: (response: any) => void;
+    /** Called when the user clicks "Back to login". */
+    onBackToLogin?: () => void;
+    /** Optional initial phone number to pre-fill (used when redirected from mustChangePIN flow) */
+    initialPhoneNumber?: string;
+    /** Optional logo configuration */
+    logo?: {
+        src: string;
+        darkSrc?: string;
+        alt: string;
+        width: number;
+        height: number;
+    };
+    /** Optional feature list to display in side carousel */
+    features?: {
+        title: string;
+        description: string;
+        icon?: React.ReactNode;
+    }[];
+    /** Optional footer content */
+    footer?: React.ReactNode;
+    /** Optional app label (e.g. "COMMERCE") */
+    appLabel?: string;
+}
+declare const PhoneForgotPinPage: React.FC<PhoneForgotPinPageProps>;
+export default PhoneForgotPinPage;

package/lib/auth/components/PhoneForgotPinPage.js

@@ -0,0 +1,131 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Phone Forgot PIN Page component.
+ * Guides the user through a 3-step flow to reset their phone PIN:
+ *   1. Enter phone number → triggers OTP send
+ *   2. Enter 4-digit OTP → returns a verificationToken
+ *   3. Set a new 4-digit PIN (with confirmation)
+ */
+import React, { useState } from 'react';
+import { Button } from '../../components';
+import { FormEngine } from '../../form-engine';
+import { AuthPageLayout } from './AuthPageLayout';
+import { FeatureCarousel } from './FeatureCarousel';
+import { OtpInput } from './OtpVerification';
+const PhoneForgotPinPage = ({ onRequestOtp, onVerifyOtp, onSetPin, onSuccess, onBackToLogin, initialPhoneNumber = '', logo, features, footer, appLabel, }) => {
+    const [step, setStep] = useState('enterPhone');
+    const [phoneNumber, setPhoneNumber] = useState('');
+    const [otpValue, setOtpValue] = useState('');
+    const [verificationToken, setVerificationToken] = useState('');
+    const [pin, setPin] = useState('');
+    const [confirmPin, setConfirmPin] = useState('');
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState(null);
+    // Step 1 — phone number field config
+    const phoneFields = [
+        {
+            name: 'phoneNumber',
+            label: 'Phone Number',
+            type: 'tel',
+            placeholder: '+27 82 123 4567',
+            gridSpan: 12,
+            defaultCountry: 'ZA',
+            validation: { required: 'Phone number is required' },
+        },
+    ];
+    const formRef = React.useRef(null);
+    // Auto-submit if initialPhoneNumber is provided (mustChangePIN redirect)
+    React.useEffect(() => {
+        if (initialPhoneNumber) {
+            handlePhoneSubmit({ phoneNumber: initialPhoneNumber }).catch(() => { });
+        }
+    }, []);
+    const handlePhoneSubmit = async (data) => {
+        const phone = data.phoneNumber;
+        setIsLoading(true);
+        setError(null);
+        try {
+            await onRequestOtp(phone);
+            setPhoneNumber(phone);
+            setStep('enterOtp');
+        }
+        catch (err) {
+            setError(err?.response?.data?.message ?? err?.message ?? 'Failed to send OTP. Please try again.');
+            throw err;
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    const handleVerifyOtp = async () => {
+        if (otpValue.length !== 4)
+            return;
+        setIsLoading(true);
+        setError(null);
+        try {
+            const result = await onVerifyOtp(phoneNumber, otpValue);
+            const token = result?.data?.verificationToken ?? result?.verificationToken;
+            if (!token) {
+                throw new Error('Verification failed. Please try again.');
+            }
+            setVerificationToken(token);
+            setStep('enterPin');
+        }
+        catch (err) {
+            setError(err?.response?.data?.message ?? err?.message ?? 'Invalid code. Please try again.');
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    const handleSetPin = async () => {
+        if (pin.length !== 4 || confirmPin.length !== 4)
+            return;
+        if (pin !== confirmPin) {
+            setError('PINs do not match. Please try again.');
+            return;
+        }
+        setIsLoading(true);
+        setError(null);
+        try {
+            const response = await onSetPin(phoneNumber, verificationToken, pin);
+            onSuccess?.(response);
+        }
+        catch (err) {
+            setError(err?.response?.data?.message ?? err?.message ?? 'Failed to set PIN. Please try again.');
+        }
+        finally {
+            setIsLoading(false);
+        }
+    };
+    const stepTitles = {
+        enterPhone: {
+            title: 'Reset Your PIN',
+            subtitle: "Enter your phone number and we'll send you a verification code.",
+        },
+        enterOtp: {
+            title: 'Enter Verification Code',
+            subtitle: `We sent a 4-digit code to ${phoneNumber}`,
+        },
+        enterPin: {
+            title: 'Set New PIN',
+            subtitle: `Create a new 4-digit PIN for ${phoneNumber}`,
+        },
+    };
+    const { title, subtitle } = stepTitles[step];
+    return (_jsx(AuthPageLayout, { appLabel: appLabel, title: title, subtitle: subtitle, errorMessage: error, logo: logo, horizontal: false, sideContent: features && features.length > 0 ? _jsx(FeatureCarousel, { features: features }) : undefined, footer: footer, children: _jsxs("div", { className: "mt-8 space-y-4", children: [step === 'enterPhone' && (_jsxs(_Fragment, { children: [_jsx(FormEngine, { fields: phoneFields, onSubmit: handlePhoneSubmit, layout: "vertical", className: "mb-0 px-0", submitButtonClass: "w-full", submitButtonText: isLoading ? 'Sending code...' : 'Send verification code', onCancel: () => { }, showCancelButton: false, showSubmittingText: false, formRef: formRef, initialValues: { phoneNumber: initialPhoneNumber } }), onBackToLogin && (_jsx("div", { className: "text-center", children: _jsx(Button, { type: "button", variant: "link", onClick: onBackToLogin, className: "text-sm text-primary hover:underline", children: "Back to login" }) }))] })), step === 'enterOtp' && (_jsxs(_Fragment, { children: [_jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "Verification Code" }), _jsx(OtpInput, { length: 4, value: otpValue, onChange: (v) => {
+                                        setOtpValue(v);
+                                        setError(null);
+                                    }, disabled: isLoading })] }), _jsx(Button, { type: "button", onClick: handleVerifyOtp, disabled: otpValue.length !== 4 || isLoading, className: "w-full", size: "lg", children: isLoading ? 'Verifying...' : 'Verify Code' }), _jsx(Button, { type: "button", variant: "ghost", onClick: () => {
+                                setStep('enterPhone');
+                                setOtpValue('');
+                                setError(null);
+                            }, className: "w-full text-sm text-foreground/70", children: "\u2190 Change number" })] })), step === 'enterPin' && (_jsxs(_Fragment, { children: [_jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "New PIN" }), _jsx(OtpInput, { length: 4, value: pin, onChange: (v) => {
+                                        setPin(v);
+                                        setError(null);
+                                    }, disabled: isLoading })] }), _jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "Confirm PIN" }), _jsx(OtpInput, { length: 4, value: confirmPin, onChange: (v) => {
+                                        setConfirmPin(v);
+                                        setError(null);
+                                    }, disabled: isLoading })] }), _jsx(Button, { type: "button", onClick: handleSetPin, disabled: pin.length !== 4 || confirmPin.length !== 4 || isLoading, className: "w-full", size: "lg", children: isLoading ? 'Setting PIN...' : 'Set New PIN' })] }))] }) }));
+};
+export default PhoneForgotPinPage;

package/lib/auth/components/PhonePinSetupPage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Phone PIN Setup Page component.
+ * Shown after phone OTP verification to let the user set their 4-digit PIN.
+ * Used for both initial account setup and PIN reset (via the forgot-PIN flow).
+ */
+import React from 'react';
+export interface PhonePinSetupPageProps {
+    /** The phone number the PIN is being set for (displayed to the user) */
+    phoneNumber: string;
+    /**
+     * Called when the user submits a valid PIN.
+     * Receives the 4-digit PIN as a plain string. Should throw on error.
+     */
+    onPinSet: (pin: string) => Promise<any>;
+    /** Optional logo configuration */
+    logo?: {
+        src: string;
+        darkSrc?: string;
+        alt: string;
+        width: number;
+        height: number;
+    };
+    /** Optional feature list to display in side carousel */
+    features?: {
+        title: string;
+        description: string;
+        icon?: React.ReactNode;
+    }[];
+    /** Optional footer content */
+    footer?: React.ReactNode;
+    /** Optional app label (e.g. "COMMERCE") */
+    appLabel?: string;
+}
+declare const PhonePinSetupPage: React.FC<PhonePinSetupPageProps>;
+export default PhonePinSetupPage;

package/lib/auth/components/PhonePinSetupPage.js

@@ -0,0 +1,44 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Phone PIN Setup Page component.
+ * Shown after phone OTP verification to let the user set their 4-digit PIN.
+ * Used for both initial account setup and PIN reset (via the forgot-PIN flow).
+ */
+import { useState } from 'react';
+import { Button } from '../../components';
+import { AuthPageLayout } from './AuthPageLayout';
+import { FeatureCarousel } from './FeatureCarousel';
+import { OtpInput } from './OtpVerification';
+const PhonePinSetupPage = ({ phoneNumber, onPinSet, logo, features, footer, appLabel, }) => {
+    const [pin, setPin] = useState('');
+    const [confirmPin, setConfirmPin] = useState('');
+    const [isSubmitting, setIsSubmitting] = useState(false);
+    const [error, setError] = useState(null);
+    const handleSubmit = async () => {
+        if (pin.length !== 4 || confirmPin.length !== 4)
+            return;
+        if (pin !== confirmPin) {
+            setError('PINs do not match. Please try again.');
+            return;
+        }
+        setIsSubmitting(true);
+        setError(null);
+        try {
+            await onPinSet(pin);
+        }
+        catch (err) {
+            setError(err?.response?.data?.message ?? err?.message ?? 'Failed to set PIN. Please try again.');
+        }
+        finally {
+            setIsSubmitting(false);
+        }
+    };
+    return (_jsx(AuthPageLayout, { appLabel: appLabel, title: "Set Your PIN", subtitle: `Create a 4-digit PIN for ${phoneNumber}`, errorMessage: error, logo: logo, horizontal: false, sideContent: features && features.length > 0 ? _jsx(FeatureCarousel, { features: features }) : undefined, footer: footer, children: _jsxs("div", { className: "mt-8 space-y-6", children: [_jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "Create PIN" }), _jsx(OtpInput, { length: 4, value: pin, onChange: (v) => {
+                                setPin(v);
+                                setError(null);
+                            }, disabled: isSubmitting })] }), _jsxs("div", { children: [_jsx("p", { className: "mb-2 block text-sm font-medium text-foreground text-center", children: "Confirm PIN" }), _jsx(OtpInput, { length: 4, value: confirmPin, onChange: (v) => {
+                                setConfirmPin(v);
+                                setError(null);
+                            }, disabled: isSubmitting })] }), _jsx(Button, { type: "button", onClick: handleSubmit, disabled: pin.length !== 4 || confirmPin.length !== 4 || isSubmitting, className: "w-full", size: "lg", children: isSubmitting ? 'Setting PIN...' : 'Set PIN' })] }) }));
+};
+export default PhonePinSetupPage;

package/lib/auth/components/index.d.ts

@@ -1,5 +1,5 @@
 export { default as LogoutButton } from './LogoutButton';
-export { default as PagamioLoginPage, loginPageDefaultText, type LoginFieldType, type PagamioLoginCredentials, type PagamioLoginPageProps, type PhoneOtpLoginConfig, } from './LoginPage';
+export { default as PagamioLoginPage, loginPageDefaultText, type LoginFieldType, type PagamioLoginCredentials, type PagamioLoginPageProps, type PhoneOtpLoginConfig, type PhonePinLoginConfig, } from './LoginPage';
 export { default as ChangePasswordPage, type ChangePasswordPageProps } from './ChangePasswordPage';
 export { type PostDataProps } from './hooks/useChangeUserPassword';
 export { default as PagamioCustomerRegistrationPage, customerRegistrationPageDefaultText, type PagamioCustomerRegistrationPageProps, } from './CustomerRegistrationPage';
@@ -9,3 +9,5 @@ export { AuthPageLayout as PagamioAuthPageLayout } from './AuthPageLayout';
 export { FeatureCarousel, type FeatureCarouselProps, type FeatureItem } from './FeatureCarousel';
 export { default as OtpVerificationPage, OtpInput, otpVerificationDefaultText, type OtpInputProps, type OtpVerificationConfig, type OtpVerificationHandlers, type PhoneOtpVerificationHandlers, type OtpVerificationPageProps, type OtpVerificationText, } from './OtpVerification';
 export { passwordValidation } from './AuthFormUtils';
+export { default as PhonePinSetupPage, type PhonePinSetupPageProps } from './PhonePinSetupPage';
+export { default as PhoneForgotPinPage, type PhoneForgotPinPageProps } from './PhoneForgotPinPage';

package/lib/auth/components/index.js

@@ -8,3 +8,5 @@ export { AuthPageLayout as PagamioAuthPageLayout } from './AuthPageLayout';
 export { FeatureCarousel } from './FeatureCarousel';
 export { default as OtpVerificationPage, OtpInput, otpVerificationDefaultText, } from './OtpVerification';
 export { passwordValidation } from './AuthFormUtils';
+export { default as PhonePinSetupPage } from './PhonePinSetupPage';
+export { default as PhoneForgotPinPage } from './PhoneForgotPinPage';

package/lib/form-engine/components/FieldWrapper.js

@@ -45,11 +45,18 @@ const FieldWrapper = ({ field, control, errors, layout, onFieldUpdate, onFieldCh
         }
     };
     if (field.name === 'email') {
+        const emailPattern = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/;
+        const existingValidate = field.validation?.validate;
         field.validation = {
             ...field.validation,
-            pattern: {
-                value: /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/,
-                message: 'Please enter a valid email address',
+            // Use validate instead of pattern so empty values are allowed (field is not required unless
+            // the required rule is explicitly set). pattern always runs even on empty strings.
+            validate: (value) => {
+                if (!value)
+                    return true;
+                if (!emailPattern.test(value))
+                    return 'Please enter a valid email address';
+                return existingValidate ? existingValidate(value) : true;
             },
         };
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pagamio/frontend-commons-lib",
   "description": "Pagamio library for Frontend reusable components like the form engine and table container",
-  "version": "0.8.279",
+  "version": "0.8.281",
   "publishConfig": {
     "access": "public",
     "provenance": false