svelte-firekit 0.0.25 → 0.1.0

package/dist/services/auth.d.ts

@@ -0,0 +1,389 @@
+/**
+ * @fileoverview FirekitAuth - Complete Firebase Authentication Service for Svelte
+ * @module FirekitAuth
+ * @version 1.0.0
+ */
+import { type User } from 'firebase/auth';
+import { type UserProfile, type AuthState, type PasswordUpdateResult, type AccountDeletionResult, type PhoneVerificationResult } from '../types/auth.js';
+/**
+ * Comprehensive Firebase Authentication service for Svelte applications.
+ * Provides a complete authentication solution with automatic Firestore integration,
+ * error handling, and support for all major authentication methods.
+ *
+ * @class FirekitAuth
+ * @example
+ * ```typescript
+ * import { firekitAuth } from 'svelte-firekit';
+ *
+ * // Sign in with Google
+ * await firekitAuth.signInWithGoogle();
+ *
+ * // Register new user
+ * await firekitAuth.registerWithEmail("user@example.com", "password123", "John Doe");
+ *
+ * // Listen to auth state changes
+ * const unsubscribe = firekitAuth.onAuthStateChanged((user) => {
+ *   console.log('User:', user);
+ * });
+ * ```
+ */
+declare class FirekitAuth {
+    private static instance;
+    private auth;
+    private firestore;
+    private authState;
+    private stateListeners;
+    private recaptchaVerifiers;
+    private constructor();
+    /**
+     * Gets singleton instance of FirekitAuth
+     * @returns {FirekitAuth} The FirekitAuth instance
+     */
+    static getInstance(): FirekitAuth;
+    /**
+     * Initializes the authentication state listener
+     * @private
+     */
+    private initializeAuthStateListener;
+    /**
+     * Notifies all state listeners of auth state changes
+     * @private
+     */
+    private notifyStateListeners;
+    /**
+     * Maps Firebase User to UserProfile interface
+     * @private
+     */
+    private mapFirebaseUserToProfile;
+    /**
+     * Updates user data in Firestore with comprehensive profile information
+     * @private
+     */
+    private updateUserInFirestore;
+    /**
+     * Handles Firebase authentication errors and throws FirekitAuthError
+     * @private
+     */
+    private handleAuthError;
+    /**
+     * Gets the current authentication state
+     * @returns {AuthState} Current authentication state
+     */
+    getState(): AuthState;
+    /**
+     * Gets the current authenticated user
+     * @returns {User | null} Current Firebase user or null
+     */
+    getCurrentUser(): User | null;
+    /**
+     * Gets the current user profile
+     * @returns {UserProfile | null} Current user profile or null
+     */
+    getCurrentUserProfile(): UserProfile | null;
+    /**
+     * Waits for auth initialization to complete
+     * @returns {Promise<UserProfile | null>} Promise that resolves when auth is initialized
+     */
+    waitForAuth(): Promise<UserProfile | null>;
+    /**
+     * Subscribes to authentication state changes
+     * @param {Function} callback Callback function to handle state changes
+     * @returns {Function} Unsubscribe function
+     */
+    onAuthStateChanged(callback: (state: AuthState) => void): () => void;
+    /**
+     * Signs in user with email and password
+     * @param {string} email User's email address
+     * @param {string} password User's password
+     * @returns {Promise<UserProfile>} Promise resolving to user profile
+     * @throws {FirekitAuthError} If sign-in fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const user = await firekitAuth.signInWithEmail("user@example.com", "password123");
+     *   console.log("Signed in:", user.displayName);
+     * } catch (error) {
+     *   console.error("Sign-in failed:", error.message);
+     * }
+     * ```
+     */
+    signInWithEmail(email: string, password: string): Promise<UserProfile>;
+    /**
+     * Signs in user with Google popup
+     * @returns {Promise<UserProfile>} Promise resolving to user profile
+     * @throws {FirekitAuthError} If sign-in fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const user = await firekitAuth.signInWithGoogle();
+     *   console.log("Signed in with Google:", user.email);
+     * } catch (error) {
+     *   if (error.code === 'auth/popup-closed-by-user') {
+     *     console.log("User cancelled sign-in");
+     *   }
+     * }
+     * ```
+     */
+    signInWithGoogle(): Promise<UserProfile>;
+    /**
+     * Signs in user with Facebook popup
+     * @returns {Promise<UserProfile>} Promise resolving to user profile
+     * @throws {FirekitAuthError} If sign-in fails
+     */
+    signInWithFacebook(): Promise<UserProfile>;
+    /**
+     * Signs in user with Apple popup
+     * @returns {Promise<UserProfile>} Promise resolving to user profile
+     * @throws {FirekitAuthError} If sign-in fails
+     */
+    signInWithApple(): Promise<UserProfile>;
+    /**
+     * Signs in user anonymously
+     * @returns {Promise<UserProfile>} Promise resolving to user profile
+     * @throws {FirekitAuthError} If sign-in fails
+     *
+     * @example
+     * ```typescript
+     * const user = await firekitAuth.signInAnonymously();
+     * console.log("Anonymous user:", user.uid);
+     * ```
+     */
+    signInAnonymously(): Promise<UserProfile>;
+    /**
+     * Initiates phone number sign-in process
+     * @param {string} phoneNumber Phone number in international format
+     * @param {string} recaptchaContainerId ID of the reCAPTCHA container element
+     * @returns {Promise<PhoneVerificationResult>} Promise resolving to verification result
+     * @throws {FirekitAuthError} If verification initiation fails
+     *
+     * @example
+     * ```typescript
+     * const verification = await firekitAuth.signInWithPhoneNumber("+1234567890", "recaptcha-container");
+     * const user = await verification.confirm("123456");
+     * ```
+     */
+    signInWithPhoneNumber(phoneNumber: string, recaptchaContainerId: string): Promise<PhoneVerificationResult>;
+    /**
+     * Registers new user with email and password
+     * @param {string} email User's email address
+     * @param {string} password User's password
+     * @param {string} [displayName] User's display name
+     * @param {boolean} [sendVerification=true] Whether to send email verification
+     * @returns {Promise<UserProfile>} Promise resolving to user profile
+     * @throws {FirekitAuthError} If registration fails
+     *
+     * @example
+     * ```typescript
+     * const user = await firekitAuth.registerWithEmail(
+     *   "user@example.com",
+     *   "password123",
+     *   "John Doe"
+     * );
+     * console.log("Registered:", user.displayName);
+     * ```
+     */
+    registerWithEmail(email: string, password: string, displayName?: string, sendVerification?: boolean): Promise<UserProfile>;
+    /**
+     * Sends password reset email
+     * @param {string} email User's email address
+     * @returns {Promise<void>} Promise that resolves when email is sent
+     * @throws {FirekitAuthError} If sending fails
+     *
+     * @example
+     * ```typescript
+     * await firekitAuth.sendPasswordReset("user@example.com");
+     * console.log("Password reset email sent");
+     * ```
+     */
+    sendPasswordReset(email: string): Promise<void>;
+    /**
+     * Confirms password reset with code
+     * @param {string} code Password reset code from email
+     * @param {string} newPassword New password
+     * @returns {Promise<void>} Promise that resolves when password is reset
+     * @throws {FirekitAuthError} If reset fails
+     */
+    confirmPasswordReset(code: string, newPassword: string): Promise<void>;
+    /**
+     * Updates user password with reauthentication
+     * @param {string} newPassword New password
+     * @param {string} currentPassword Current password for reauthentication
+     * @returns {Promise<PasswordUpdateResult>} Promise resolving to update result
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitAuth.updatePassword("newPassword123", "oldPassword123");
+     * if (result.success) {
+     *   console.log("Password updated successfully");
+     * } else {
+     *   console.error("Update failed:", result.message);
+     * }
+     * ```
+     */
+    updatePassword(newPassword: string, currentPassword: string): Promise<PasswordUpdateResult>;
+    /**
+     * Updates user profile
+     * @param {Object} profile Profile update data
+     * @param {string} [profile.displayName] New display name
+     * @param {string} [profile.photoURL] New photo URL
+     * @returns {Promise<void>} Promise that resolves when profile is updated
+     * @throws {FirekitAuthError} If update fails
+     *
+     * @example
+     * ```typescript
+     * await firekitAuth.updateUserProfile({
+     *   displayName: "John Smith",
+     *   photoURL: "https://example.com/photo.jpg"
+     * });
+     * ```
+     */
+    updateUserProfile(profile: {
+        displayName?: string;
+        photoURL?: string;
+    }): Promise<void>;
+    /**
+     * Updates user email address
+     * @param {string} newEmail New email address
+     * @returns {Promise<void>} Promise that resolves when email is updated
+     * @throws {FirekitAuthError} If update fails
+     *
+     * @example
+     * ```typescript
+     * await firekitAuth.updateEmail("newemail@example.com");
+     * ```
+     */
+    updateEmail(newEmail: string): Promise<void>;
+    /**
+     * Sends email verification to current user
+     * @returns {Promise<void>} Promise that resolves when verification email is sent
+     * @throws {FirekitAuthError} If sending fails
+     *
+     * @example
+     * ```typescript
+     * await firekitAuth.sendEmailVerification();
+     * console.log("Verification email sent");
+     * ```
+     */
+    sendEmailVerification(): Promise<void>;
+    /**
+     * Reloads current user to get updated email verification status
+     * @returns {Promise<void>} Promise that resolves when user is reloaded
+     * @throws {FirekitAuthError} If reload fails
+     */
+    reloadUser(): Promise<void>;
+    /**
+     * Gets the current user's ID token
+     * @param {boolean} [forceRefresh=false] Whether to force token refresh
+     * @returns {Promise<string>} Promise resolving to ID token
+     * @throws {FirekitAuthError} If getting token fails
+     *
+     * @example
+     * ```typescript
+     * const token = await firekitAuth.getIdToken();
+     * // Use token for authenticated API calls
+     * ```
+     */
+    getIdToken(forceRefresh?: boolean): Promise<string>;
+    /**
+     * Reauthenticates current user with email/password
+     * @param {string} currentPassword Current password
+     * @returns {Promise<void>} Promise that resolves when reauthentication succeeds
+     * @throws {FirekitAuthError} If reauthentication fails
+     * @private
+     */
+    private reauthenticateUser;
+    /**
+     * Deletes user account and associated data
+     * @param {string} [currentPassword] Current password for reauthentication (required for email/password accounts)
+     * @returns {Promise<AccountDeletionResult>} Promise resolving to deletion result
+     *
+     * @example
+     * ```typescript
+     * const result = await firekitAuth.deleteAccount("currentPassword123");
+     * if (result.success) {
+     *   console.log("Account deleted successfully");
+     * }
+     * ```
+     */
+    deleteAccount(currentPassword?: string): Promise<AccountDeletionResult>;
+    /**
+     * Signs out current user
+     * @returns {Promise<void>} Promise that resolves when sign-out completes
+     * @throws {FirekitAuthError} If sign-out fails
+     *
+     * @example
+     * ```typescript
+     * await firekitAuth.signOut();
+     * console.log("User signed out");
+     * ```
+     */
+    signOut(): Promise<void>;
+    /**
+     * Checks if user is authenticated
+     * @returns {boolean} True if user is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Checks if user is anonymous
+     * @returns {boolean} True if user is anonymous
+     */
+    isAnonymous(): boolean;
+    /**
+     * Checks if user's email is verified
+     * @returns {boolean} True if email is verified
+     */
+    isEmailVerified(): boolean;
+    /**
+     * Gets user's primary email address
+     * @returns {string | null} User's email or null
+     */
+    getUserEmail(): string | null;
+    /**
+     * Gets user's display name
+     * @returns {string | null} User's display name or null
+     */
+    getUserDisplayName(): string | null;
+    /**
+     * Gets user's photo URL
+     * @returns {string | null} User's photo URL or null
+     */
+    getUserPhotoURL(): string | null;
+    /**
+     * Gets user's UID
+     * @returns {string | null} User's UID or null
+     */
+    getUserId(): string | null;
+    /**
+     * Cleans up all resources
+     * @returns {Promise<void>} Promise that resolves when cleanup is complete
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Pre-initialized singleton instance of FirekitAuth.
+ * This is the main export that should be used throughout your application.
+ *
+ * @example
+ * ```typescript
+ * import { firekitAuth } from 'svelte-firekit';
+ *
+ * // Sign in with email
+ * await firekitAuth.signInWithEmail("user@example.com", "password");
+ *
+ * // Listen to auth state
+ * const unsubscribe = firekitAuth.onAuthStateChanged((state) => {
+ *   if (state.user) {
+ *     console.log("User is signed in:", state.user.email);
+ *   } else {
+ *     console.log("User is signed out");
+ *   }
+ * });
+ *
+ * // Clean up listener
+ * unsubscribe();
+ * ```
+ */
+export declare const firekitAuth: FirekitAuth;
+export {};