@atzentis/auth-expo 0.0.16 → 0.1.0

package/dist/index.d.ts

@@ -1,13 +1,429 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+import { TextInputProps, TextInput } from 'react-native';
+import * as _atzentis_auth_locales from '@atzentis/auth-locales';
+import { AuthLocalization } from '@atzentis/auth-locales';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { QueryClient } from '@tanstack/react-query';
+
+interface AuthContainerProps {
+    children: ReactNode;
+}
 /**
- * @atzentis/auth-expo - React Native/Expo integration for Atzentis Auth SDK
+ * Root layout for auth screens. Handles keyboard avoidance, safe area insets,
+ * and centering content on tablets.
+ */
+declare function AuthContainer({ children }: AuthContainerProps): react_jsx_runtime.JSX.Element;
+
+interface AuthGateProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+declare function AuthGate({ children, fallback }: AuthGateProps): react_jsx_runtime.JSX.Element;
+
+interface ErrorFeedbackProps {
+    message: string;
+}
+/**
+ * Displays an error message with a red alert icon.
+ * Used in auth screens to show validation or API errors.
+ */
+declare function ErrorFeedback({ message }: ErrorFeedbackProps): react_jsx_runtime.JSX.Element;
+
+interface FormInputProps extends Omit<TextInputProps, "onChangeText" | "value"> {
+    error?: string;
+    label?: string;
+    onChangeText?: (text: string) => void;
+    value?: string;
+}
+/**
+ * Form text input with optional label and error display.
+ * Designed for react-hook-form Controller render prop.
+ */
+declare const FormInput: React.ForwardRefExoticComponent<FormInputProps & React.RefAttributes<TextInput>>;
+
+interface FormPasswordInputProps extends Omit<TextInputProps, "onChangeText" | "value"> {
+    error?: string;
+    label?: string;
+    onChangeText?: (text: string) => void;
+    value?: string;
+}
+/**
+ * Form password input with show/hide toggle, optional label and error display.
+ * Designed for react-hook-form Controller render prop.
+ */
+declare const FormPasswordInput: React.ForwardRefExoticComponent<FormPasswordInputProps & React.RefAttributes<TextInput>>;
+
+type OAuthProvider = "google" | "apple" | "github";
+interface OAuthButtonProps {
+    disabled?: boolean;
+    onError?: (error: Error) => void;
+    onSuccess?: () => void;
+    provider: OAuthProvider;
+}
+declare function OAuthButton({ disabled, onError, onSuccess, provider }: OAuthButtonProps): react_jsx_runtime.JSX.Element;
+
+interface ProtectedScreenProps {
+    children: ReactNode;
+    fallback?: ReactNode;
+}
+declare function ProtectedScreen({ children, fallback }: ProtectedScreenProps): react_jsx_runtime.JSX.Element | null;
+
+interface SuccessFeedbackProps {
+    message: string;
+}
+/**
+ * Displays a success message with a green checkmark icon.
+ */
+declare function SuccessFeedback({ message }: SuccessFeedbackProps): react_jsx_runtime.JSX.Element;
+
+interface SubmitButtonProps {
+    disabled?: boolean;
+    label: string;
+    loading: boolean;
+    loadingLabel: string;
+    onPress: () => void;
+}
+/**
+ * Submit button with loading state and optional haptic feedback.
+ * Uses @expo/ui Button for native appearance inside Host wrapper.
+ */
+declare function SubmitButton({ disabled, label, loading, loadingLabel, onPress, }: SubmitButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Available auth screen routes.
+ */
+type AuthRoute = "login" | "signup" | "phone-login" | "magic-link" | "forgot-password" | "reset-password" | "verify-email" | "two-factor";
+interface AuthViewProps {
+    /** Which auth screen to render. Defaults to "login". */
+    route?: AuthRoute;
+    /** Called on successful authentication. */
+    onSuccess?: () => void;
+    /** Token for deep link screens (reset-password, verify-email, magic-link). */
+    token?: string;
+    /** Whether biometric auth is available (login screen only). */
+    biometricAvailable?: boolean;
+    /** Handler for biometric button press (login screen only). */
+    onBiometricPress?: () => void;
+    /** Fallback content when route doesn't match. */
+    fallback?: ReactNode;
+}
+/**
+ * AuthView — Route-based renderer for auth screens.
+ *
+ * Maps a route name to the appropriate auth screen component.
+ * For use with expo-router layouts or custom navigation.
+ *
+ * @example
+ * // In app/(auth)/[...slug].tsx:
+ * import { AuthView } from "@atzentis/auth-expo";
+ *
+ * export default function AuthRoute() {
+ *   const { slug } = useLocalSearchParams();
+ *   const route = (slug as string[])?.[0] ?? "login";
+ *   const params = useLocalSearchParams();
+ *   return (
+ *     <AuthView
+ *       route={route}
+ *       token={params.token as string}
+ *       onSuccess={() => router.replace("/(app)")}
+ *     />
+ *   );
+ * }
+ */
+declare function AuthView({ route, onSuccess, token, biometricAvailable, onBiometricPress, fallback, }: AuthViewProps): react_jsx_runtime.JSX.Element;
+
+interface EmailVerificationScreenProps {
+    onSuccess?: () => void;
+    token?: string;
+}
+/** Auto-verifies an email address using the `token` prop from a deep-link URL. */
+declare function EmailVerificationScreen({ onSuccess, token }: EmailVerificationScreenProps): react_jsx_runtime.JSX.Element;
+
+interface ForgotPasswordScreenProps {
+    onSuccess?: () => void;
+}
+/** Screen for requesting a password-reset email with a 60-second resend cooldown. */
+declare function ForgotPasswordScreen({ onSuccess }: ForgotPasswordScreenProps): react_jsx_runtime.JSX.Element;
+
+interface LoginScreenProps {
+    biometricAvailable?: boolean;
+    onBiometricPress?: () => void;
+    onSuccess?: () => void;
+}
+/** Email/password login screen with optional biometric button (iOS only). */
+declare function LoginScreen({ biometricAvailable, onBiometricPress, onSuccess, }: LoginScreenProps): react_jsx_runtime.JSX.Element;
+
+interface MagicLinkScreenProps {
+    onSuccess?: () => void;
+    token?: string;
+}
+/** Magic-link login screen: sends link via email, then auto-verifies when a `token` prop is provided. */
+declare function MagicLinkScreen({ onSuccess, token }: MagicLinkScreenProps): react_jsx_runtime.JSX.Element;
+
+interface PhoneLoginScreenProps {
+    onSuccess?: () => void;
+}
+/** Two-step phone login screen: collect phone number, then verify the OTP code sent via SMS. */
+declare function PhoneLoginScreen({ onSuccess }: PhoneLoginScreenProps): react_jsx_runtime.JSX.Element;
+
+interface ResetPasswordScreenProps {
+    onSuccess?: () => void;
+    token?: string;
+}
+/** Token-based password reset screen; shows an error state when no token is provided. */
+declare function ResetPasswordScreen({ onSuccess, token }: ResetPasswordScreenProps): react_jsx_runtime.JSX.Element;
+
+interface SignupScreenProps {
+    onSuccess?: () => void;
+}
+/** Email/password registration screen with name, email, and password fields. */
+declare function SignupScreen({ onSuccess }: SignupScreenProps): react_jsx_runtime.JSX.Element;
+
+interface TwoFactorScreenProps {
+    onSuccess?: () => void;
+}
+/** TOTP/backup-code verification screen shown after initial credentials are accepted. */
+declare function TwoFactorScreen({ onSuccess }: TwoFactorScreenProps): react_jsx_runtime.JSX.Element;
+
+interface ChangeEmailScreenProps {
+    onSuccess?: () => void;
+    redirectUrl?: string;
+}
+/** Settings screen for changing the account email address; sends a verification link with a resend cooldown. */
+declare function ChangeEmailScreen({ onSuccess, redirectUrl }: ChangeEmailScreenProps): react_jsx_runtime.JSX.Element;
+
+interface ChangePasswordScreenProps {
+    onSuccess?: () => void;
+}
+/** Settings screen for changing the current user's password (requires current password). */
+declare function ChangePasswordScreen({ onSuccess }: ChangePasswordScreenProps): react_jsx_runtime.JSX.Element;
+
+interface DeleteAccountScreenProps {
+    confirmationPhrase?: string;
+    onSuccess?: () => void;
+}
+/** Destructive settings screen for permanent account deletion; requires typing a confirmation phrase and password. */
+declare function DeleteAccountScreen({ confirmationPhrase, onSuccess, }: DeleteAccountScreenProps): react_jsx_runtime.JSX.Element;
+
+interface SessionsScreenProps {
+    onSuccess?: () => void;
+}
+/** Settings screen listing all active sessions with individual revoke and revoke-all-others actions. */
+declare function SessionsScreen({ onSuccess }: SessionsScreenProps): react_jsx_runtime.JSX.Element;
+
+interface TwoFactorSettingsScreenProps {
+    onSuccess?: () => void;
+}
+/** Settings screen for enabling or disabling TOTP two-factor authentication; shows the secret, verify step, and backup codes. */
+declare function TwoFactorSettingsScreen({ onSuccess }: TwoFactorSettingsScreenProps): react_jsx_runtime.JSX.Element;
+
+interface UpdateAvatarScreenProps {
+    onSuccess?: () => void;
+}
+/** Settings screen for uploading or removing the current user's avatar using the image library. */
+declare function UpdateAvatarScreen({ onSuccess }: UpdateAvatarScreenProps): react_jsx_runtime.JSX.Element;
+
+interface UpdateNameScreenProps {
+    onSuccess?: () => void;
+}
+/** Settings screen for updating the current user's display name. */
+declare function UpdateNameScreen({ onSuccess }: UpdateNameScreenProps): react_jsx_runtime.JSX.Element;
+
+interface UpdateUsernameScreenProps {
+    onSuccess?: () => void;
+}
+/** Settings screen for updating the account username with debounced availability checking. */
+declare function UpdateUsernameScreen({ onSuccess }: UpdateUsernameScreenProps): react_jsx_runtime.JSX.Element;
+
+interface OrganizationMembersScreenProps {
+    organizationId: string;
+    isAdmin?: boolean;
+    onSuccess?: () => void;
+}
+/** Screen displaying organization members with role management and removal actions (admin only). */
+declare function OrganizationMembersScreen({ organizationId, isAdmin, onSuccess, }: OrganizationMembersScreenProps): react_jsx_runtime.JSX.Element;
+
+interface OrganizationSwitcherScreenProps {
+    currentOrgId?: string;
+    onSwitch?: (orgId: string) => void;
+}
+/** Screen listing all organizations the user belongs to; selecting one sets it as the active organization. */
+declare function OrganizationSwitcherScreen({ currentOrgId, onSwitch, }: OrganizationSwitcherScreenProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Returns the Better Auth client instance from the nearest `AuthProvider`.
+ *
+ * @throws {Error} If called outside of an `AuthProvider`.
+ * @returns The configured Better Auth client with expo plugin.
+ */
+declare function useAuthClient(): Record<string, any>;
+
+/**
+ * Returns the resolved auth localization strings and the `localizeErrors` flag
+ * from the nearest `AuthProvider`.
+ *
+ * @returns `{ localization, localizeErrors }` — use `localization.SIGN_IN` etc. inside SDK screens.
+ */
+declare function useAuthLocalization(): {
+    localization: _atzentis_auth_locales.AuthLocalization;
+    localizeErrors: boolean;
+};
+
+declare function useAuthRedirect(): {
+    redirectToSignIn: (returnUrl?: string) => void;
+    redirectToSignUp: (returnUrl?: string) => void;
+};
+
+interface BiometricAvailability {
+    hasHardware: boolean;
+    isEnrolled: boolean;
+    supportedTypes: number[];
+}
+/**
+ * Hook for biometric authentication (Face ID / Touch ID / fingerprint).
+ *
+ * @returns An object with:
+ *   - `checkAvailability` — async function that resolves with `{ hasHardware, isEnrolled, supportedTypes }`.
+ *   - `authenticate` — TanStack mutation that accepts a `promptMessage` string and triggers the system biometric prompt.
+ *
+ * @example
+ * ```tsx
+ * const { checkAvailability, authenticate } = useBiometric();
+ * const available = await checkAvailability();
+ * if (available.isEnrolled) {
+ *   authenticate.mutate("Authenticate to sign in");
+ * }
+ * ```
+ */
+declare function useBiometric(): {
+    checkAvailability: () => Promise<BiometricAvailability>;
+    authenticate: _tanstack_react_query.UseMutationResult<{
+        success: boolean;
+        error?: string;
+    }, Error, string, unknown>;
+};
+
+interface LoginInput {
+    email: string;
+    password: string;
+}
+/**
+ * Mutation hook for email/password login.
+ *
+ * On success, writes the returned user and session into the TanStack Query cache
+ * via the `authKeys` factory so that `useUser` and `useSession` update immediately.
  *
- * Provides:
- * - Secure token storage via expo-secure-store
- * - Native device signal collection
- * - OAuth deep linking handler
- * - Push notification token management
- * - Phone sign-in screen
+ * @returns A TanStack `UseMutationResult` — call `.mutate({ email, password })` to sign in.
  */
-declare const VERSION = "0.0.1";
+declare function useLogin(): _tanstack_react_query.UseMutationResult<any, Error, LoginInput, unknown>;
+
+/**
+ * Mutation hook for signing out the current user.
+ *
+ * On success, sets user and session cache to `null` and invalidates all
+ * session-related queries so the UI reflects the signed-out state immediately.
+ *
+ * @returns A TanStack `UseMutationResult` — call `.mutate()` with no arguments to sign out.
+ */
+declare function useLogout(): _tanstack_react_query.UseMutationResult<any, Error, void, unknown>;
+
+interface RequestPasswordResetInput {
+    email: string;
+    redirectTo?: string;
+}
+/**
+ * Mutation hook for requesting a password reset email.
+ */
+declare function useRequestPasswordReset(): _tanstack_react_query.UseMutationResult<boolean, Error, RequestPasswordResetInput, unknown>;
+
+interface ResetPasswordInput {
+    newPassword: string;
+    token: string;
+}
+/**
+ * Mutation hook for resetting a password using a token from the reset email.
+ */
+declare function useResetPassword(): _tanstack_react_query.UseMutationResult<boolean, Error, ResetPasswordInput, unknown>;
+
+interface SignupInput {
+    email: string;
+    name: string;
+    password: string;
+}
+/**
+ * Mutation hook for email/password signup.
+ *
+ * On success, writes the returned user and session into the TanStack Query cache
+ * via the `authKeys` factory so that `useUser` and `useSession` update immediately.
+ *
+ * @returns A TanStack `UseMutationResult` — call `.mutate({ email, name, password })` to register.
+ */
+declare function useSignup(): _tanstack_react_query.UseMutationResult<any, Error, SignupInput, unknown>;
+
+/**
+ * Query hook for the current session.
+ *
+ * Fetches via `client.getSession()` and extracts the session object.
+ * Data is cached for 5 minutes (`staleTime`). Returns `null` when not authenticated.
+ *
+ * @returns A TanStack `UseQueryResult<Session | null>`.
+ */
+declare function useSession(): _tanstack_react_query.UseQueryResult<any, Error>;
+
+/**
+ * Query hook for the current authenticated user.
+ *
+ * Fetches via `client.getSession()` and extracts the user object.
+ * Data is cached for 5 minutes (`staleTime`). Returns `null` when not authenticated.
+ *
+ * @returns A TanStack `UseQueryResult<User | null>`.
+ */
+declare function useUser(): _tanstack_react_query.UseQueryResult<any, Error>;
+
+interface AuthProviderProps {
+    baseURL: string;
+    children: React.ReactNode;
+    locales?: Record<string, AuthLocalization>;
+    localization?: Partial<AuthLocalization>;
+    queryClient?: QueryClient;
+}
+/**
+ * Provides authentication context for Expo/React Native applications.
+ *
+ * Wraps Better Auth client with SecureStore for token persistence and
+ * expo-localization for automatic language detection.
+ *
+ * @param props - Provider configuration
+ * @param props.baseURL - Base URL of the Better Auth server
+ * @param props.children - Child components
+ * @param props.locales - Language packs keyed by BCP 47 language code (e.g. `{ el, de }`)
+ * @param props.localization - Per-key overrides applied on top of the resolved locale
+ * @param props.queryClient - Optional external TanStack QueryClient; a default one is created if omitted
+ * @returns JSX element wrapping children with auth, localization, and query contexts
+ *
+ * @example
+ * ```tsx
+ * import { el, de } from "@atzentis/auth-locales";
+ *
+ * export default function RootLayout() {
+ *   return (
+ *     <AuthProvider
+ *       baseURL="https://auth.example.com"
+ *       locales={{ el, de }}
+ *     >
+ *       <Slot />
+ *     </AuthProvider>
+ *   );
+ * }
+ * ```
+ */
+declare function AuthProvider({ baseURL, children, locales, localization: localizationOverride, queryClient: externalQueryClient, }: AuthProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * @atzentis/auth-expo - React Native/Expo integration for Atzentis Auth SDK
+ */
+
+declare const VERSION = "0.1.0";
 
-export { VERSION };
+export { AuthContainer, AuthGate, type AuthGateProps, AuthProvider, type AuthRoute, AuthView, type AuthViewProps, ChangeEmailScreen, type ChangeEmailScreenProps, ChangePasswordScreen, type ChangePasswordScreenProps, DeleteAccountScreen, type DeleteAccountScreenProps, EmailVerificationScreen, type EmailVerificationScreenProps, ErrorFeedback, ForgotPasswordScreen, type ForgotPasswordScreenProps, FormInput, FormPasswordInput, LoginScreen, type LoginScreenProps, MagicLinkScreen, type MagicLinkScreenProps, OAuthButton, type OAuthButtonProps, OrganizationMembersScreen, type OrganizationMembersScreenProps, OrganizationSwitcherScreen, type OrganizationSwitcherScreenProps, PhoneLoginScreen, type PhoneLoginScreenProps, ProtectedScreen, type ProtectedScreenProps, ResetPasswordScreen, type ResetPasswordScreenProps, SessionsScreen, type SessionsScreenProps, SignupScreen, type SignupScreenProps, SubmitButton, SuccessFeedback, TwoFactorScreen, type TwoFactorScreenProps, TwoFactorSettingsScreen, type TwoFactorSettingsScreenProps, UpdateAvatarScreen, type UpdateAvatarScreenProps, UpdateNameScreen, type UpdateNameScreenProps, UpdateUsernameScreen, type UpdateUsernameScreenProps, VERSION, useAuthClient, useAuthLocalization, useAuthRedirect, useBiometric, useLogin, useLogout, useRequestPasswordReset, useResetPassword, useSession, useSignup, useUser };