@mohasinac/appkit 2.1.3 → 2.2.0

package/dist/features/auth/components/LoginForm.js

@@ -0,0 +1,18 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { Alert, Div, Heading, Row, Text, Label } from "../../../ui";
+export function LoginForm({ onSubmit, onGoogleLogin, isLoading = false, error, labels = {}, renderSocialButtons, renderCreateAccountLink, renderForgotPasswordLink, renderSubmitButton, className = "", }) {
+    const [values, setValues] = useState({
+        email: "",
+        password: "",
+        rememberMe: false,
+    });
+    const handleSubmit = useCallback(async (e) => {
+        e.preventDefault();
+        await onSubmit(values);
+    }, [onSubmit, values]);
+    return (_jsx(Div, { className: `flex items-center justify-center min-h-[60vh] px-4 ${className}`, children: _jsxs(Div, { className: "max-w-md w-full space-y-6", children: [_jsxs(Div, { className: "text-center", children: [_jsx(Heading, { level: 1, className: "text-3xl font-extrabold", children: labels.title ?? "Sign In" }), (labels.subtitle || renderCreateAccountLink) && (_jsxs(Text, { className: "mt-2 text-sm text-neutral-600", children: [labels.subtitle ?? "Or", " ", renderCreateAccountLink?.()] }))] }), error && (_jsx(Alert, { variant: "error", compact: true, children: error })), _jsxs("form", { className: "space-y-4", onSubmit: handleSubmit, noValidate: true, children: [_jsxs(Div, { children: [_jsx(Label, { htmlFor: "login-email", className: "block text-sm font-medium mb-1", children: labels.emailLabel ?? "Email address" }), _jsx("input", { id: "login-email", name: "email", type: "email", autoComplete: "username", required: true, placeholder: labels.emailPlaceholder ?? "you@example.com", value: values.email, onChange: (e) => setValues({ ...values, email: e.target.value }), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Div, { children: [_jsx(Label, { htmlFor: "login-password", className: "block text-sm font-medium mb-1", children: labels.passwordLabel ?? "Password" }), _jsx("input", { id: "login-password", name: "password", type: "password", autoComplete: "current-password", required: true, placeholder: labels.passwordPlaceholder ?? "••••••••", value: values.password, onChange: (e) => setValues({ ...values, password: e.target.value }), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Row, { justify: "between", children: [_jsxs(Row, { className: "gap-2", children: [_jsx("input", { id: "login-remember", type: "checkbox", checked: values.rememberMe ?? false, onChange: (e) => setValues({ ...values, rememberMe: e.target.checked }), className: "h-4 w-4 rounded border-neutral-300 accent-primary" }), _jsx(Label, { htmlFor: "login-remember", className: "text-sm", children: labels.rememberMe ?? "Remember me" })] }), renderForgotPasswordLink?.()] }), renderSubmitButton ? (renderSubmitButton(isLoading, labels)) : (_jsx("button", { type: "submit", disabled: isLoading, className: "w-full rounded-lg bg-primary px-4 py-2.5 text-sm font-semibold text-white disabled:opacity-60 hover:bg-primary/90 transition-colors", children: isLoading
+                                ? (labels.submittingLabel ?? "Signing in…")
+                                : (labels.submitLabel ?? "Sign in") }))] }), renderSocialButtons?.()] }) }));
+}

package/dist/features/auth/components/RegisterForm.d.ts

@@ -0,0 +1,36 @@
+import React from "react";
+export interface RegisterFormValues {
+    email: string;
+    password: string;
+    confirmPassword: string;
+    displayName: string;
+    acceptTerms: boolean;
+}
+export interface RegisterFormProps {
+    onSubmit: (values: RegisterFormValues) => Promise<void>;
+    isLoading?: boolean;
+    error?: string | null;
+    success?: string | null;
+    labels?: {
+        title?: string;
+        subtitle?: string;
+        displayNameLabel?: string;
+        displayNamePlaceholder?: string;
+        emailLabel?: string;
+        emailPlaceholder?: string;
+        passwordLabel?: string;
+        passwordPlaceholder?: string;
+        confirmPasswordLabel?: string;
+        confirmPasswordPlaceholder?: string;
+        acceptTermsLabel?: string;
+        submitLabel?: string;
+        submittingLabel?: string;
+        passwordMismatch?: string;
+    };
+    renderSocialButtons?: () => React.ReactNode;
+    renderLoginLink?: () => React.ReactNode;
+    renderTermsLink?: () => React.ReactNode;
+    renderPasswordStrength?: (password: string) => React.ReactNode;
+    className?: string;
+}
+export declare function RegisterForm({ onSubmit, isLoading, error, success, labels, renderSocialButtons, renderLoginLink, renderTermsLink, renderPasswordStrength, className, }: RegisterFormProps): import("react/jsx-runtime").JSX.Element;

package/dist/features/auth/components/RegisterForm.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { Alert, Div, Heading, Label, Text } from "../../../ui";
+export function RegisterForm({ onSubmit, isLoading = false, error, success, labels = {}, renderSocialButtons, renderLoginLink, renderTermsLink, renderPasswordStrength, className = "", }) {
+    const [values, setValues] = useState({
+        email: "",
+        password: "",
+        confirmPassword: "",
+        displayName: "",
+        acceptTerms: false,
+    });
+    const [validationError, setValidationError] = useState(null);
+    const handleSubmit = useCallback(async (e) => {
+        e.preventDefault();
+        setValidationError(null);
+        if (values.password !== values.confirmPassword) {
+            setValidationError(labels.passwordMismatch ?? "Passwords do not match");
+            return;
+        }
+        await onSubmit(values);
+    }, [onSubmit, values, labels.passwordMismatch]);
+    const displayError = error ?? validationError;
+    return (_jsx(Div, { className: `flex items-center justify-center min-h-[60vh] px-4 ${className}`, children: _jsxs(Div, { className: "max-w-md w-full space-y-6", children: [_jsxs(Div, { className: "text-center", children: [_jsx(Heading, { level: 1, className: "text-3xl font-extrabold", children: labels.title ?? "Create Account" }), (labels.subtitle || renderLoginLink) && (_jsxs(Text, { className: "mt-2 text-sm text-neutral-600", children: [labels.subtitle ?? "Already have an account?", " ", renderLoginLink?.()] }))] }), success && (_jsx(Alert, { variant: "success", compact: true, children: success })), displayError && (_jsx(Alert, { variant: "error", compact: true, children: displayError })), _jsxs("form", { className: "space-y-4", onSubmit: handleSubmit, noValidate: true, children: [_jsxs(Div, { children: [_jsx(Label, { htmlFor: "reg-name", className: "block text-sm font-medium mb-1", children: labels.displayNameLabel ?? "Full name" }), _jsx("input", { id: "reg-name", name: "displayName", type: "text", autoComplete: "name", required: true, placeholder: labels.displayNamePlaceholder ?? "Your name", value: values.displayName, onChange: (e) => setValues({ ...values, displayName: e.target.value }), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Div, { children: [_jsx(Label, { htmlFor: "reg-email", className: "block text-sm font-medium mb-1", children: labels.emailLabel ?? "Email address" }), _jsx("input", { id: "reg-email", name: "email", type: "email", autoComplete: "username", required: true, placeholder: labels.emailPlaceholder ?? "you@example.com", value: values.email, onChange: (e) => setValues({ ...values, email: e.target.value }), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Div, { children: [_jsx(Label, { htmlFor: "reg-password", className: "block text-sm font-medium mb-1", children: labels.passwordLabel ?? "Password" }), _jsx("input", { id: "reg-password", name: "password", type: "password", autoComplete: "new-password", required: true, placeholder: labels.passwordPlaceholder ?? "••••••••", value: values.password, onChange: (e) => setValues({ ...values, password: e.target.value }), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" }), renderPasswordStrength?.(values.password)] }), _jsxs(Div, { children: [_jsx(Label, { htmlFor: "reg-confirm", className: "block text-sm font-medium mb-1", children: labels.confirmPasswordLabel ?? "Confirm password" }), _jsx("input", { id: "reg-confirm", name: "confirmPassword", type: "password", autoComplete: "new-password", required: true, placeholder: labels.confirmPasswordPlaceholder ?? "••••••••", value: values.confirmPassword, onChange: (e) => setValues({ ...values, confirmPassword: e.target.value }), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Div, { className: "flex items-start gap-2", children: [_jsx("input", { id: "reg-terms", type: "checkbox", required: true, checked: values.acceptTerms, onChange: (e) => setValues({ ...values, acceptTerms: e.target.checked }), className: "mt-0.5 h-4 w-4 rounded border-neutral-300 accent-primary" }), _jsxs(Label, { htmlFor: "reg-terms", className: "text-sm leading-snug", children: [labels.acceptTermsLabel ?? "I accept the", " ", renderTermsLink?.()] })] }), _jsx("button", { type: "submit", disabled: isLoading, className: "w-full rounded-lg bg-primary px-4 py-2.5 text-sm font-semibold text-white disabled:opacity-60 hover:bg-primary/90 transition-colors", children: isLoading
+                                ? (labels.submittingLabel ?? "Creating account…")
+                                : (labels.submitLabel ?? "Create account") })] }), renderSocialButtons?.()] }) }));
+}

package/dist/features/auth/components/ResetPasswordView.d.ts

@@ -0,0 +1,23 @@
+import React from "react";
+export interface ResetPasswordViewProps {
+    /** OOB code from URL */
+    oobCode: string;
+    onSubmit: (oobCode: string, newPassword: string) => Promise<void>;
+    isLoading?: boolean;
+    error?: string | null;
+    success?: string | null;
+    labels?: {
+        title?: string;
+        description?: string;
+        passwordLabel?: string;
+        passwordPlaceholder?: string;
+        confirmPasswordLabel?: string;
+        confirmPasswordPlaceholder?: string;
+        submitLabel?: string;
+        submittingLabel?: string;
+        passwordMismatch?: string;
+    };
+    renderLoginLink?: () => React.ReactNode;
+    className?: string;
+}
+export declare function ResetPasswordView({ oobCode, onSubmit, isLoading, error, success, labels, renderLoginLink, className, }: ResetPasswordViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/features/auth/components/ResetPasswordView.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useState } from "react";
+import { Alert, Div, Heading, Label, Text } from "../../../ui";
+export function ResetPasswordView({ oobCode, onSubmit, isLoading = false, error, success, labels = {}, renderLoginLink, className = "", }) {
+    const [password, setPassword] = useState("");
+    const [confirm, setConfirm] = useState("");
+    const [validationError, setValidationError] = useState(null);
+    const handleSubmit = useCallback(async (e) => {
+        e.preventDefault();
+        setValidationError(null);
+        if (password !== confirm) {
+            setValidationError(labels.passwordMismatch ?? "Passwords do not match");
+            return;
+        }
+        await onSubmit(oobCode, password);
+    }, [oobCode, onSubmit, password, confirm, labels.passwordMismatch]);
+    const displayError = error ?? validationError;
+    return (_jsx(Div, { className: `flex items-center justify-center min-h-[60vh] px-4 ${className}`, children: _jsxs(Div, { className: "max-w-md w-full space-y-6", children: [_jsxs(Div, { className: "text-center", children: [_jsx(Heading, { level: 1, className: "text-3xl font-extrabold", children: labels.title ?? "Reset Password" }), labels.description && (_jsx(Text, { className: "mt-2 text-sm text-neutral-600", children: labels.description }))] }), displayError && (_jsx(Alert, { variant: "error", compact: true, children: displayError })), success ? (_jsxs(Alert, { variant: "success", compact: true, children: [success, renderLoginLink && _jsx(Div, { className: "mt-2", children: renderLoginLink() })] })) : (_jsxs("form", { className: "space-y-4", onSubmit: handleSubmit, noValidate: true, children: [_jsxs(Div, { children: [_jsx(Label, { htmlFor: "rp-password", className: "block text-sm font-medium mb-1", children: labels.passwordLabel ?? "New password" }), _jsx("input", { id: "rp-password", name: "password", type: "password", autoComplete: "new-password", required: true, placeholder: labels.passwordPlaceholder ?? "••••••••", value: password, onChange: (e) => setPassword(e.target.value), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsxs(Div, { children: [_jsx(Label, { htmlFor: "rp-confirm", className: "block text-sm font-medium mb-1", children: labels.confirmPasswordLabel ?? "Confirm new password" }), _jsx("input", { id: "rp-confirm", name: "confirmPassword", type: "password", autoComplete: "new-password", required: true, placeholder: labels.confirmPasswordPlaceholder ?? "••••••••", value: confirm, onChange: (e) => setConfirm(e.target.value), className: "w-full rounded-lg border border-neutral-300 px-3 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-primary" })] }), _jsx("button", { type: "submit", disabled: isLoading, className: "w-full rounded-lg bg-primary px-4 py-2.5 text-sm font-semibold text-white disabled:opacity-60 hover:bg-primary/90 transition-colors", children: isLoading
+                                ? (labels.submittingLabel ?? "Resetting…")
+                                : (labels.submitLabel ?? "Reset password") })] }))] }) }));
+}

package/dist/features/auth/components/SocialAuthButtons.d.ts

@@ -0,0 +1,8 @@
+interface SocialAuthButtonsProps {
+    onGoogle: () => void;
+    disabled?: boolean;
+    dividerLabel: string;
+    googleLabel: string;
+}
+export declare function SocialAuthButtons({ onGoogle, disabled, dividerLabel, googleLabel, }: SocialAuthButtonsProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/features/auth/components/SocialAuthButtons.js

@@ -0,0 +1,6 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Button, Div, Span } from "../../../ui";
+export function SocialAuthButtons({ onGoogle, disabled, dividerLabel, googleLabel, }) {
+    return (_jsxs(_Fragment, { children: [_jsxs(Div, { className: "relative", children: [_jsx(Div, { className: "absolute inset-0 flex items-center", children: _jsx(Div, { className: "w-full border-t border-neutral-200" }) }), _jsx(Div, { className: "relative flex justify-center text-sm", children: _jsx(Span, { className: "px-2 bg-white text-neutral-500", children: dividerLabel }) })] }), _jsx(Div, { className: "grid grid-cols-1 gap-3", children: _jsxs(Button, { type: "button", onClick: onGoogle, disabled: disabled, variant: "outline", className: "inline-flex items-center justify-center rounded-md border border-neutral-300 bg-white px-4 py-2 text-sm font-medium text-neutral-900 hover:bg-neutral-50 disabled:cursor-not-allowed disabled:opacity-50", children: [_jsxs("svg", { className: "mr-2 h-5 w-5", viewBox: "0 0 24 24", "aria-hidden": "true", children: [_jsx("path", { fill: "currentColor", d: "M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92c-.26 1.37-1.04 2.53-2.21 3.31v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.09z" }), _jsx("path", { fill: "currentColor", d: "M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z" }), _jsx("path", { fill: "currentColor", d: "M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z" }), _jsx("path", { fill: "currentColor", d: "M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z" })] }), googleLabel] }) })] }));
+}

package/dist/features/auth/components/VerifyEmailView.d.ts

@@ -0,0 +1,20 @@
+import React from "react";
+export interface VerifyEmailViewProps {
+    /** Status of the verification */
+    status: "loading" | "success" | "error";
+    error?: string | null;
+    labels?: {
+        loadingTitle?: string;
+        loadingDescription?: string;
+        successTitle?: string;
+        successDescription?: string;
+        errorTitle?: string;
+        errorDescription?: string;
+        retryLabel?: string;
+        continueLabel?: string;
+    };
+    onRetry?: () => void;
+    renderContinueButton?: () => React.ReactNode;
+    className?: string;
+}
+export declare function VerifyEmailView({ status, error, labels, onRetry, renderContinueButton, className, }: VerifyEmailViewProps): import("react/jsx-runtime").JSX.Element;

package/dist/features/auth/components/VerifyEmailView.js

@@ -0,0 +1,8 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Div, Heading, Text } from "../../../ui";
+export function VerifyEmailView({ status, error, labels = {}, onRetry, renderContinueButton, className = "", }) {
+    return (_jsx(Div, { className: `flex items-center justify-center min-h-[60vh] px-4 ${className}`, children: _jsxs(Div, { className: "max-w-md w-full bg-white rounded-2xl border border-neutral-200 shadow-sm p-8 text-center", children: [status === "loading" && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "w-12 h-12 rounded-full border-4 border-primary border-t-transparent animate-spin mx-auto mb-6" }), _jsx(Heading, { level: 2, className: "text-xl font-semibold mb-2", children: labels.loadingTitle ?? "Verifying your email…" }), _jsx(Text, { className: "text-neutral-500", children: labels.loadingDescription ?? "Please wait a moment." })] })), status === "success" && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "w-12 h-12 rounded-full bg-green-100 flex items-center justify-center mx-auto mb-6", children: _jsx("svg", { className: "w-6 h-6 text-green-600", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M5 13l4 4L19 7" }) }) }), _jsx(Heading, { level: 2, className: "text-xl font-semibold mb-2", children: labels.successTitle ?? "Email verified!" }), _jsx(Text, { className: "text-neutral-500 mb-6", children: labels.successDescription ??
+                                "Your email has been verified successfully." }), renderContinueButton?.()] })), status === "error" && (_jsxs(_Fragment, { children: [_jsx(Div, { className: "w-12 h-12 rounded-full bg-red-100 flex items-center justify-center mx-auto mb-6", children: _jsx("svg", { className: "w-6 h-6 text-red-600", fill: "none", stroke: "currentColor", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { strokeLinecap: "round", strokeLinejoin: "round", strokeWidth: 2, d: "M6 18L18 6M6 6l12 12" }) }) }), _jsx(Heading, { level: 2, className: "text-xl font-semibold mb-2", children: labels.errorTitle ?? "Verification failed" }), _jsx(Text, { className: "text-neutral-500 mb-2", children: error ??
+                                labels.errorDescription ??
+                                "The verification link may have expired." }), onRetry && (_jsx("button", { onClick: onRetry, className: "mt-4 rounded-lg bg-primary px-4 py-2 text-sm font-semibold text-white hover:bg-primary/90 transition-colors", children: labels.retryLabel ?? "Try again" }))] }))] }) }));
+}

package/dist/features/auth/components/index.d.ts

@@ -0,0 +1,14 @@
+export { RoleGate, ProtectedRoute } from "./Guards";
+export type { RoleGateProps, ProtectedRouteProps, AuthGuardUser, AuthRouteConfig, } from "./Guards";
+export { SocialAuthButtons } from "./SocialAuthButtons";
+export { AuthStatusPanel } from "./AuthStatusPanel";
+export { LoginForm } from "./LoginForm";
+export type { LoginFormProps, LoginFormValues } from "./LoginForm";
+export { RegisterForm } from "./RegisterForm";
+export type { RegisterFormProps, RegisterFormValues } from "./RegisterForm";
+export { ForgotPasswordView } from "./ForgotPasswordView";
+export type { ForgotPasswordViewProps } from "./ForgotPasswordView";
+export { ResetPasswordView } from "./ResetPasswordView";
+export type { ResetPasswordViewProps } from "./ResetPasswordView";
+export { VerifyEmailView } from "./VerifyEmailView";
+export type { VerifyEmailViewProps } from "./VerifyEmailView";

package/dist/features/auth/components/index.js

@@ -0,0 +1,8 @@
+export { RoleGate, ProtectedRoute } from "./Guards";
+export { SocialAuthButtons } from "./SocialAuthButtons";
+export { AuthStatusPanel } from "./AuthStatusPanel";
+export { LoginForm } from "./LoginForm";
+export { RegisterForm } from "./RegisterForm";
+export { ForgotPasswordView } from "./ForgotPasswordView";
+export { ResetPasswordView } from "./ResetPasswordView";
+export { VerifyEmailView } from "./VerifyEmailView";

package/dist/features/auth/consent-otp.d.ts

@@ -0,0 +1,52 @@
+import "server-only";
+import { getAdminDb } from "../../providers/db-firebase";
+/** OTP validity window (10 minutes). */
+export declare const CONSENT_OTP_EXPIRY_MS: number;
+/** Used in email body text so it stays in sync with CONSENT_OTP_EXPIRY_MS. */
+export declare const CONSENT_OTP_EXPIRY_MINUTES = 10;
+/** Per-user send cooldown (15 minutes). */
+export declare const CONSENT_OTP_COOLDOWN_MS: number;
+/** Maximum number of partial-order bypass credits a user can accumulate. */
+export declare const CONSENT_OTP_MAX_BYPASS_CREDITS = 3;
+/** Maximum failed verification attempts before the OTP is locked. */
+export declare const CONSENT_OTP_MAX_ATTEMPTS = 5;
+/** Rate-limit config for the verify endpoint / action (10 attempts per 5 min). */
+export declare const CONSENT_OTP_VERIFY_RATE_LIMIT: {
+    readonly limit: 10;
+    readonly window: 300;
+};
+type Db = ReturnType<typeof getAdminDb>;
+/** Reference to a user's consent OTP document for a given address. */
+export declare function consentOtpRef(db: Db, uid: string, addressId: string): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+/** Reference to a user's consent OTP rate-limit metadata document. */
+export declare function consentOtpRateLimitRef(db: Db, uid: string): FirebaseFirestore.DocumentReference<FirebaseFirestore.DocumentData, FirebaseFirestore.DocumentData>;
+/** HMAC-SHA256 hash of an OTP code. */
+export declare function hashOtp(code: string): string;
+/** Generate a cryptographically-secure random 6-digit OTP string. */
+export declare function generateOtpCode(): string;
+/** Obfuscate an email address for display (e.g. j***e@example.com). */
+export declare function maskEmail(email: string): string;
+/** Shape of a consent OTP document as returned from Firestore. */
+export interface ConsentOtpDoc {
+    codeHash: string;
+    expiresAt: FirebaseFirestore.Timestamp;
+    attempts: number;
+    verified: boolean;
+}
+/**
+ * Enforce the per-user send rate-limit.
+ * Throws AuthorizationError("consentOtpRateLimit") when throttled and no bypass credits remain.
+ */
+export declare function enforceConsentOtpRateLimit(uid: string): Promise<void>;
+/** Write (or overwrite) a consent OTP document for a given user + address. */
+export declare function saveConsentOtp(uid: string, addressId: string, data: Record<string, unknown>): Promise<void>;
+/** Read a consent OTP document. Returns null when the document does not exist. */
+export declare function readConsentOtp(uid: string, addressId: string): Promise<ConsentOtpDoc | null>;
+/** Partially update a consent OTP document. */
+export declare function patchConsentOtp(uid: string, addressId: string, data: Record<string, unknown>): Promise<void>;
+/** Build the consent OTP email subject and HTML body. */
+export declare function buildConsentOtpEmail(recipientName: string, code: string, siteName: string): {
+    subject: string;
+    html: string;
+};
+export {};

package/dist/features/auth/consent-otp.js

@@ -0,0 +1,120 @@
+import "server-only";
+/**
+ * Consent OTP - Shared constants, path helpers, and utilities
+ */
+import { createHmac, randomInt } from "crypto";
+import { getAdminDb } from "../../providers/db-firebase";
+import { AuthorizationError } from "../../errors";
+import { escapeHtml, resolveDate } from "../../utils";
+import { USER_COLLECTION } from "./schemas";
+const HMAC_KEY = process.env.CONSENT_OTP_HMAC_KEY ||
+    process.env.HMAC_SECRET ||
+    "consent-otp-secret";
+/** OTP validity window (10 minutes). */
+export const CONSENT_OTP_EXPIRY_MS = 10 * 60 * 1000;
+/** Used in email body text so it stays in sync with CONSENT_OTP_EXPIRY_MS. */
+export const CONSENT_OTP_EXPIRY_MINUTES = 10;
+/** Per-user send cooldown (15 minutes). */
+export const CONSENT_OTP_COOLDOWN_MS = 15 * 60 * 1000;
+/** Maximum number of partial-order bypass credits a user can accumulate. */
+export const CONSENT_OTP_MAX_BYPASS_CREDITS = 3;
+/** Maximum failed verification attempts before the OTP is locked. */
+export const CONSENT_OTP_MAX_ATTEMPTS = 5;
+/** Rate-limit config for the verify endpoint / action (10 attempts per 5 min). */
+export const CONSENT_OTP_VERIFY_RATE_LIMIT = {
+    limit: 10,
+    window: 300,
+};
+/** Reference to a user's consent OTP document for a given address. */
+export function consentOtpRef(db, uid, addressId) {
+    return db
+        .collection(USER_COLLECTION)
+        .doc(uid)
+        .collection("consentOtps")
+        .doc(addressId);
+}
+/** Reference to a user's consent OTP rate-limit metadata document. */
+export function consentOtpRateLimitRef(db, uid) {
+    return db
+        .collection(USER_COLLECTION)
+        .doc(uid)
+        .collection("consentOtpRateLimit")
+        .doc("meta");
+}
+/** HMAC-SHA256 hash of an OTP code. */
+export function hashOtp(code) {
+    return createHmac("sha256", HMAC_KEY).update(code).digest("hex");
+}
+/** Generate a cryptographically-secure random 6-digit OTP string. */
+export function generateOtpCode() {
+    return String(randomInt(100000, 1000000));
+}
+/** Obfuscate an email address for display (e.g. j***e@example.com). */
+export function maskEmail(email) {
+    const [local, domain] = email.split("@");
+    if (!domain)
+        return "***";
+    const masked = local.length <= 2
+        ? "*".repeat(local.length)
+        : local[0] + "*".repeat(local.length - 2) + local[local.length - 1];
+    return `${masked}@${domain}`;
+}
+/**
+ * Enforce the per-user send rate-limit.
+ * Throws AuthorizationError("consentOtpRateLimit") when throttled and no bypass credits remain.
+ */
+export async function enforceConsentOtpRateLimit(uid) {
+    const db = getAdminDb();
+    const metaRef = consentOtpRateLimitRef(db, uid);
+    await db.runTransaction(async (tx) => {
+        const metaSnap = await tx.get(metaRef);
+        const meta = metaSnap.exists
+            ? metaSnap.data()
+            : null;
+        const lastSentMs = resolveDate(meta?.lastSentAt)?.getTime() ?? 0;
+        const bypassCredits = meta?.bypassCredits ?? 0;
+        const elapsed = Date.now() - lastSentMs;
+        if (elapsed < CONSENT_OTP_COOLDOWN_MS) {
+            if (bypassCredits <= 0) {
+                throw new AuthorizationError("consentOtpRateLimit");
+            }
+            tx.set(metaRef, { lastSentAt: new Date(), bypassCredits: bypassCredits - 1 }, { merge: true });
+        }
+        else {
+            tx.set(metaRef, { lastSentAt: new Date() }, { merge: true });
+        }
+    });
+}
+/** Write (or overwrite) a consent OTP document for a given user + address. */
+export async function saveConsentOtp(uid, addressId, data) {
+    const db = getAdminDb();
+    await consentOtpRef(db, uid, addressId).set(data);
+}
+/** Read a consent OTP document. Returns null when the document does not exist. */
+export async function readConsentOtp(uid, addressId) {
+    const db = getAdminDb();
+    const snap = await consentOtpRef(db, uid, addressId).get();
+    if (!snap.exists)
+        return null;
+    return snap.data();
+}
+/** Partially update a consent OTP document. */
+export async function patchConsentOtp(uid, addressId, data) {
+    const db = getAdminDb();
+    await consentOtpRef(db, uid, addressId).update(data);
+}
+/** Build the consent OTP email subject and HTML body. */
+export function buildConsentOtpEmail(recipientName, code, siteName) {
+    return {
+        subject: `${siteName}: Consent verification code - shipping to ${recipientName}`,
+        html: `
+      <div style="font-family:sans-serif;max-width:480px;margin:0 auto;padding:24px">
+        <h2 style="margin-bottom:8px">Third-Party Shipping Consent</h2>
+        <p style="color:#555">You are about to place an order that will be shipped to <strong>${escapeHtml(recipientName)}</strong>.</p>
+        <p style="color:#555">Enter this code to confirm your consent:</p>
+        <div style="font-size:36px;font-weight:bold;letter-spacing:8px;text-align:center;margin:24px 0;padding:16px;background:#f3f4f6;border-radius:8px">${code}</div>
+        <p style="color:#888;font-size:12px">This code expires in ${CONSENT_OTP_EXPIRY_MINUTES} minutes. If you did not request this, please ignore this email.</p>
+      </div>
+    `,
+    };
+}

package/dist/features/auth/hooks/useAuth.d.ts

@@ -0,0 +1,81 @@
+import "client-only";
+import type { AuthUser } from "../types";
+interface UseCurrentUserOptions {
+    initialData?: AuthUser | null;
+    enabled?: boolean;
+}
+export declare function useCurrentUser(opts?: UseCurrentUserOptions): {
+    user: AuthUser | null;
+    isLoading: boolean;
+    isAuthenticated: boolean;
+    error: Error | null;
+    refetch: (options?: import("@tanstack/query-core").RefetchOptions) => Promise<import("@tanstack/query-core").QueryObserverResult<AuthUser | null, Error>>;
+};
+export interface LoginCredentials {
+    email: string;
+    password: string;
+}
+export interface RegisterData {
+    email: string;
+    password: string;
+    displayName?: string;
+    acceptTerms: boolean;
+}
+export interface ChangePasswordData {
+    currentPassword: string;
+    newPassword: string;
+}
+export interface ForgotPasswordData {
+    email: string;
+}
+export interface ResetPasswordData {
+    token: string;
+    newPassword: string;
+}
+export interface ResendVerificationData {
+    email: string;
+}
+export interface VerifyEmailData {
+    token: string;
+}
+export declare function useLogin(options?: {
+    onSuccess?: () => void;
+    onError?: (error: unknown) => void;
+}): import("@tanstack/react-query").UseMutationResult<unknown, Error, LoginCredentials, unknown>;
+export declare function useGoogleLogin(options?: {
+    onSuccess?: (data: {
+        isNewUser: boolean;
+        uid: string;
+        role: string;
+    } | null) => void;
+    onError?: (error: unknown) => void;
+    onSessionSynced?: () => Promise<void> | void;
+}): {
+    mutate: () => Promise<void>;
+    isLoading: boolean;
+};
+export declare function useRegister(options?: {
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: unknown) => void;
+}): import("@tanstack/react-query").UseMutationResult<unknown, Error, RegisterData, unknown>;
+export declare function useVerifyEmail(options?: {
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: unknown) => void;
+}): import("@tanstack/react-query").UseMutationResult<unknown, Error, VerifyEmailData, unknown>;
+export declare function useResendVerification(options?: {
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: unknown) => void;
+}): import("@tanstack/react-query").UseMutationResult<unknown, Error, ResendVerificationData, unknown>;
+export declare function useForgotPassword(options?: {
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: unknown) => void;
+}): import("@tanstack/react-query").UseMutationResult<unknown, Error, ForgotPasswordData, unknown>;
+export declare function useResetPassword(options?: {
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: unknown) => void;
+}): import("@tanstack/react-query").UseMutationResult<unknown, Error, ResetPasswordData, unknown>;
+export declare function useChangePassword(options?: {
+    onSuccess?: (data: unknown) => void;
+    onError?: (error: unknown) => void;
+}): import("@tanstack/react-query").UseMutationResult<unknown, Error, ChangePasswordData, unknown>;
+export {};

package/dist/features/auth/hooks/useAuth.js

@@ -0,0 +1,164 @@
+"use client";
+import "client-only";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useMutation, useQuery } from "@tanstack/react-query";
+import { getClientAuthProvider } from "../../../contracts/client-auth";
+import { apiClient } from "../../../http";
+import { useAuthEvent } from "./useAuthEvent";
+import { RealtimeEventStatus } from "../../../react/hooks/useRealtimeEvent";
+import { AUTH_ENDPOINTS, ACCOUNT_ENDPOINTS, } from "../../../constants/api-endpoints";
+export function useCurrentUser(opts) {
+    const query = useQuery({
+        queryKey: ["auth", "me"],
+        queryFn: async () => {
+            try {
+                return await apiClient.get(AUTH_ENDPOINTS.ME);
+            }
+            catch {
+                return null;
+            }
+        },
+        initialData: opts?.initialData ?? undefined,
+        enabled: opts?.enabled,
+        staleTime: 5 * 60 * 1000,
+    });
+    return {
+        user: query.data ?? null,
+        isLoading: query.isLoading,
+        isAuthenticated: !!query.data,
+        error: query.error,
+        refetch: query.refetch,
+    };
+}
+export function useLogin(options) {
+    return useMutation({
+        mutationFn: async (credentials) => {
+            await apiClient.post(AUTH_ENDPOINTS.LOGIN, {
+                email: credentials.email.trim(),
+                password: credentials.password,
+            });
+            await getClientAuthProvider().signInWithEmailAndPassword(credentials.email.trim(), credentials.password);
+            return { success: true };
+        },
+        onSuccess: options?.onSuccess,
+        onError: options?.onError,
+    });
+}
+export function useGoogleLogin(options) {
+    const authEvent = useAuthEvent();
+    const [initiating, setInitiating] = useState(false);
+    const onSuccessRef = useRef(options?.onSuccess);
+    const onErrorRef = useRef(options?.onError);
+    const onSessionSyncedRef = useRef(options?.onSessionSynced);
+    useEffect(() => {
+        onSuccessRef.current = options?.onSuccess;
+    }, [options?.onSuccess]);
+    useEffect(() => {
+        onErrorRef.current = options?.onError;
+    }, [options?.onError]);
+    useEffect(() => {
+        onSessionSyncedRef.current = options?.onSessionSynced;
+    }, [options?.onSessionSynced]);
+    useEffect(() => {
+        if (authEvent.status === RealtimeEventStatus.SUCCESS) {
+            Promise.resolve(onSessionSyncedRef.current?.()).then(() => {
+                onSuccessRef.current?.(authEvent.data);
+            });
+        }
+        else if (authEvent.status === RealtimeEventStatus.FAILED ||
+            authEvent.status === RealtimeEventStatus.TIMEOUT) {
+            onErrorRef.current?.(new Error(authEvent.error ?? "Sign-in failed. Please try again."));
+        }
+    }, [authEvent.status, authEvent.error, authEvent.data]);
+    const mutate = useCallback(async () => {
+        const popup = window.open(`${window.location.origin}/auth.html`, "oauth_google", "width=500,height=660,left=400,top=100");
+        if (!popup) {
+            onErrorRef.current?.(new Error("Popup blocked. Please allow popups for this site."));
+            return;
+        }
+        try {
+            setInitiating(true);
+            authEvent.reset();
+            const { eventId, customToken } = await apiClient.post(AUTH_ENDPOINTS.EVENT_INIT, {});
+            const url = `${window.location.origin}${AUTH_ENDPOINTS.GOOGLE_START}?eventId=${encodeURIComponent(eventId)}`;
+            localStorage.setItem("letitrip_oauth_redirect", url);
+            authEvent.subscribe(eventId, customToken);
+        }
+        catch (err) {
+            popup.close();
+            onErrorRef.current?.(err instanceof Error ? err : new Error("Failed to start sign-in."));
+        }
+        finally {
+            setInitiating(false);
+        }
+    }, [authEvent]);
+    const isLoading = initiating ||
+        authEvent.status === RealtimeEventStatus.SUBSCRIBING ||
+        authEvent.status === RealtimeEventStatus.PENDING;
+    return { mutate, isLoading };
+}
+export function useRegister(options) {
+    return useMutation({
+        mutationFn: async (data) => {
+            const response = await apiClient.post(AUTH_ENDPOINTS.REGISTER, {
+                email: data.email.trim(),
+                password: data.password,
+                displayName: data.displayName?.trim() || "",
+                acceptTerms: data.acceptTerms,
+            });
+            await getClientAuthProvider().signInWithEmailAndPassword(data.email.trim(), data.password);
+            return { success: true, ...response };
+        },
+        onSuccess: options?.onSuccess,
+        onError: options?.onError,
+    });
+}
+export function useVerifyEmail(options) {
+    return useMutation({
+        mutationFn: async ({ token }) => {
+            const authProvider = getClientAuthProvider();
+            await authProvider.applyActionCode(token);
+            await authProvider.reloadCurrentUser();
+            return { success: true, emailVerified: true };
+        },
+        onSuccess: options?.onSuccess,
+        onError: options?.onError,
+    });
+}
+export function useResendVerification(options) {
+    return useMutation({
+        mutationFn: (data) => apiClient.post(AUTH_ENDPOINTS.RESEND_VERIFICATION, data),
+        onSuccess: options?.onSuccess,
+        onError: options?.onError,
+    });
+}
+export function useForgotPassword(options) {
+    return useMutation({
+        mutationFn: async (data) => {
+            await getClientAuthProvider().sendPasswordResetEmail(data.email);
+            return { success: true };
+        },
+        onSuccess: options?.onSuccess,
+        onError: options?.onError,
+    });
+}
+export function useResetPassword(options) {
+    return useMutation({
+        mutationFn: async (data) => {
+            await getClientAuthProvider().confirmPasswordReset(data.token, data.newPassword);
+            return { success: true };
+        },
+        onSuccess: options?.onSuccess,
+        onError: options?.onError,
+    });
+}
+export function useChangePassword(options) {
+    return useMutation({
+        mutationFn: async (data) => {
+            await getClientAuthProvider().reauthenticateAndChangePassword(data.currentPassword, data.newPassword);
+            return apiClient.post(ACCOUNT_ENDPOINTS.CHANGE_PASSWORD, data);
+        },
+        onSuccess: options?.onSuccess,
+        onError: options?.onError,
+    });
+}