better-auth-harmony/dist/email.d.ts

Validation and normalization for better-auth

import { User } from 'better-auth';
import { BetterAuthPlugin } from 'better-auth/types';
import normalizeEmail from 'validator/es/lib/normalizeEmail';
import { Matcher } from './email/matchers.js';

interface UserWithNormalizedEmail extends User {
    normalizedEmail?: string | null;
}
interface EmailHarmonyOptions {
    /**
     * Allow logging in with any version of the unnormalized email address. Also works for password
     * reset. For example a user who signed up with the email `johndoe@googlemail.com` may also log
     * in with `john.doe@gmail.com`. Makes 1 extra database query for every login attempt.
     * @default false
     */
    allowNormalizedSignin?: boolean;
    /**
     * Function to validate email. Default is `validateEmail`.
     */
    validator?: (email: string) => boolean | Promise<boolean>;
    /**
     * Function to normalize email address. Default is `validator.normalizeEmail(t)`.
     * @see https://github.com/validatorjs/validator.js#sanitizers
     */
    normalizer?: typeof normalizeEmail;
    /**
     * Specify in which routes the plugin should run, for example by path.
     * @example <caption>Ready-made matchers</caption>
     * import * as matchers from 'better-auth-harmony/email/matchers';
     *
     * export const auth = betterAuth({
     *   // ... other config options
     *   plugins: [
     *     emailHarmony({
     *       matchers: {
     *         signIn: [matchers.emailOtpVerify, matchers.emailOtpForget, matchers.emailOtpReset]
     *       }
     *     })
     *   ]
     * });
     */
    matchers?: {
        /**
         * Specify where the plugin should run to look up users by normalized email address if
         * `allowNormalizedSignin` is true.
         * @default [`allEmailSignIn`]
         */
        signIn?: Matcher[];
        /**
         * Specify which requests the plugin should validate, for example in which routes by path.
         * @default [`allEmail`]
         */
        validation?: Matcher[];
    };
}
/**
 * The default validation function runs `validator.isEmail(email) && Mailchecker.isValid(email)`.
 * @see https://github.com/validatorjs/validator.js#validators
 * @see https://github.com/FGRibreau/mailchecker
 * @param email The email address to validate
 * @returns Boolean indicating whether the address should be accepted (`true`), or rejected
 *   (`false`).
 */
declare const validateEmail: (email: string) => boolean;
declare const emailHarmony: ({ allowNormalizedSignin, validator, matchers, normalizer }?: EmailHarmonyOptions) => BetterAuthPlugin;

export { type EmailHarmonyOptions, type UserWithNormalizedEmail, emailHarmony as default, validateEmail };