/**
 * Authentication Utility Functions
 *
 * Helper functions and constants for authentication components, including
 * provider display metadata, URL construction, popup handling, error formatting,
 * and form validation utilities.
 *
 * @module auth/utils
 */
import { AuthProviderName, PasswordRules } from './types';
import { ControllerValidation } from '../form';
import type { AuthError } from '../../better-auth/types';
/**
 * Mapping of every supported social provider name to its display metadata.
 *
 * Contains the human-readable name, Iconify icon identifier, and hex brand color
 * for each {@link AuthProviderName}.
 *
 * @example
 * ```ts
 * const info = providerInfo['google']
 * // { name: 'Google', icon: 'logos:google-icon', color: '#4285f4' }
 * ```
 */
export declare const providerInfo: Record<AuthProviderName, {
    name: string;
    icon: string;
    color: string;
}>;
/**
 * Returns the human-readable display name for a social provider.
 *
 * @param provider - The provider identifier.
 * @returns The formatted provider name (e.g., `'Google'`), or the raw identifier if not found.
 *
 * @example
 * ```ts
 * formatProviderName('github') // 'GitHub'
 * ```
 */
export declare function formatProviderName(provider: AuthProviderName): string;
/**
 * Returns the Iconify icon identifier for a social provider.
 *
 * @param provider - The provider identifier.
 * @returns The icon string (e.g., `'logos:google-icon'`), or `'mdi:account'` as a fallback.
 *
 * @example
 * ```ts
 * getProviderIcon('github') // 'logos:github-icon'
 * ```
 */
export declare function getProviderIcon(provider: AuthProviderName): string;
/**
 * Returns the brand hex color for a social provider.
 *
 * @param provider - The provider identifier.
 * @returns The hex color string (e.g., `'#4285f4'`), or `'#666'` as a fallback.
 *
 * @example
 * ```ts
 * getProviderColor('google') // '#4285f4'
 * ```
 */
export declare function getProviderColor(provider: AuthProviderName): string;
/**
 * Formats a social login button label by replacing `{provider}` in a template string.
 *
 * @param provider - The provider identifier.
 * @param template - The template string containing `{provider}` placeholder. @default 'Continue with {provider}'
 * @returns The formatted string with the provider name substituted.
 *
 * @example
 * ```ts
 * formatSocialLoginText('google') // 'Continue with Google'
 * formatSocialLoginText('github', 'Sign in via {provider}') // 'Sign in via GitHub'
 * ```
 */
export declare function formatSocialLoginText(provider: AuthProviderName, template?: string): string;
/**
 * Default password validation rules used across auth components.
 *
 * Requires at least 8 characters, one uppercase letter, one lowercase letter,
 * and one number. Special characters are not required by default.
 */
export declare const defaultPasswordRules: PasswordRules;
/**
 * Checks whether a string matches a basic email format.
 *
 * Uses a simple regex for client-side validation. This is not a comprehensive
 * RFC 5322 check but covers common email patterns.
 *
 * @param email - The string to test.
 * @returns `true` if the string looks like a valid email address.
 *
 * @example
 * ```ts
 * isValidEmail('user@example.com') // true
 * isValidEmail('not-an-email')     // false
 * ```
 */
export declare function isValidEmail(email: string): boolean;
/**
 * Generates a random alphanumeric string, typically used for OAuth state parameters.
 *
 * Note: Uses `Math.random()`, which is not cryptographically secure. For
 * production OAuth flows, consider using `crypto.getRandomValues()` instead.
 *
 * @param length - The length of the generated string. @default 32
 * @returns A random alphanumeric string of the specified length.
 *
 * @example
 * ```ts
 * const state = generateRandomString(16) // e.g., 'aB3kPm7xNq2wLz9R'
 * ```
 */
export declare function generateRandomString(length?: number): string;
/**
 * Constructs an OAuth authorization URL for a social login provider.
 *
 * Builds a URL with query parameters for `client_id`, `redirect_uri`, `scope`,
 * `state`, and `response_type`. Provider-specific base URLs and default scopes
 * are built in. Custom scopes and additional query parameters can be provided.
 *
 * This is a basic implementation. For production use, consider using your
 * auth library's built-in OAuth URL construction.
 *
 * @param provider - The social provider to generate the URL for.
 * @param clientId - The OAuth client ID.
 * @param redirectUri - The URI to redirect to after authentication.
 * @param scopes - OAuth scopes to request. Defaults to provider-specific defaults if empty.
 * @param customParams - Additional query parameters to include in the URL.
 * @returns The fully constructed OAuth authorization URL.
 * @throws {Error} If the provider is not supported.
 *
 * @example
 * ```ts
 * const url = createSocialLoginUrl('google', 'my-client-id', 'https://myapp.com/callback')
 * ```
 */
export declare function createSocialLoginUrl(provider: AuthProviderName, clientId: string, redirectUri: string, scopes?: string[], customParams?: Record<string, string>): string;
/**
 * Opens a popup window for social login and listens for the result via `postMessage`.
 *
 * The popup is monitored for closure (user cancellation) and for messages from
 * the popup window. Expected message types are `SOCIAL_LOGIN_SUCCESS` and
 * `SOCIAL_LOGIN_ERROR`, sent from the OAuth callback page.
 *
 * @typeParam T - The type of the success result data.
 * @param url - The OAuth authorization URL to open in the popup.
 * @param provider - The social provider name (used for the popup window name).
 * @param onSuccess - Callback invoked with the result data on successful login.
 * @param onError - Callback invoked with an error on failure or cancellation.
 *
 * @example
 * ```ts
 * openSocialLoginPopup<{ token: string }>(
 *   authUrl,
 *   'google',
 *   (result) => console.log('Token:', result.token),
 *   (error) => console.error('Failed:', error.message)
 * )
 * ```
 */
export declare function openSocialLoginPopup<T>(url: string, provider: AuthProviderName, onSuccess?: (result: T) => void, onError?: (error: Error) => void): void;
/**
 * Formats an unknown error value into a human-readable error message string.
 *
 * Handles `Error` instances, plain strings, objects with a `message` property,
 * and falls back to a generic error message.
 *
 * @param error - The error value to format.
 * @returns A human-readable error message string.
 *
 * @example
 * ```ts
 * formatAuthError(new Error('Invalid credentials')) // 'Invalid credentials'
 * formatAuthError('Something went wrong')           // 'Something went wrong'
 * formatAuthError(42)                               // 'An unexpected error occurred'
 * ```
 */
export declare function formatAuthError(error: unknown): string;
/**
 * Checks whether the code is running in a browser environment.
 *
 * @returns `true` if `window` and `document` are available, `false` otherwise.
 */
export declare function isBrowser(): boolean;
/**
 * Wraps an async form submission task into a form controller validation function.
 *
 * Creates a function that can be passed to `useForm`'s `onSubmit` option. It
 * handles loading state (via `onStart`/`onEnd` callbacks), invokes the task,
 * and converts the result into a `Validation` value compatible with the form
 * controller system.
 *
 * @typeParam T - The form data type.
 * @param options - Configuration for the validation wrapper.
 * @param options.task - The async function to call with the form value. Returns an error message or `null`.
 * @param options.message - A fallback error message used if the task throws.
 * @param options.onStart - Called before the task begins (e.g., to set loading state).
 * @param options.onEnd - Called after the task completes (e.g., to clear loading state).
 * @returns An async function that accepts a value of type `T` and returns a `Validation`.
 *
 * @example
 * ```ts
 * const onSubmit = requestToControllerValidation({
 *   task: async (data) => {
 *     const error = await api.signIn(data)
 *     return error ?? null
 *   },
 *   message: 'Sign in failed',
 *   onStart: () => loading.set(true),
 *   onEnd: () => loading.set(false),
 * })
 * ```
 */
export declare function requestToControllerValidation<T>({ task, message, onStart, onEnd, }: {
    task: undefined | ((value: T) => Promise<AuthError | null>);
    message: string;
    onStart?: () => void;
    onEnd?: () => void;
}): (value: T) => Promise<ControllerValidation>;