svelte-firekit 0.1.8 → 0.2.0

package/dist/services/app-check.svelte.js

@@ -0,0 +1,159 @@
+import { initializeAppCheck, getToken, getLimitedUseToken, onTokenChanged, setTokenAutoRefreshEnabled } from 'firebase/app-check';
+import { firebaseService } from '../firebase.js';
+export { ReCaptchaV3Provider, ReCaptchaEnterpriseProvider, CustomProvider } from 'firebase/app-check';
+/**
+ * App Check service — secures all Firebase service calls with attestation tokens.
+ *
+ * **Must be initialized before any other Firebase service makes a network call.**
+ * Use the `appCheckOptions` prop on `<FirebaseApp>`, or call `firekitAppCheck.initialize()`
+ * manually as early as possible in your app lifecycle.
+ *
+ * Supports reCAPTCHA Enterprise, reCAPTCHA v3, and custom providers.
+ *
+ * @example Via FirebaseApp component
+ * ```svelte
+ * <FirebaseApp
+ *   {config}
+ *   appCheckOptions={{ provider: new ReCaptchaEnterpriseProvider('SITE_KEY'), isTokenAutoRefreshEnabled: true }}
+ * >
+ * ```
+ *
+ * @example Programmatic initialization
+ * ```ts
+ * import { firekitAppCheck, ReCaptchaEnterpriseProvider } from 'svelte-firekit';
+ * firekitAppCheck.initialize({
+ *   provider: new ReCaptchaEnterpriseProvider('SITE_KEY'),
+ *   isTokenAutoRefreshEnabled: true
+ * });
+ * ```
+ *
+ * @example Debug mode in development
+ * ```ts
+ * // Set this BEFORE calling initialize() — Firebase SDK picks it up automatically
+ * if (import.meta.env.DEV) {
+ *   (self as any).FIREBASE_APPCHECK_DEBUG_TOKEN = true;
+ * }
+ * firekitAppCheck.initialize({ provider: new ReCaptchaEnterpriseProvider('SITE_KEY') });
+ * ```
+ */
+class FirekitAppCheck {
+    static instance;
+    appCheck = null;
+    unsubscribeToken = null;
+    // ── Reactive state ───────────────────────────────────────────────────────────
+    _initialized = $state(false);
+    _loading = $state(false);
+    _error = $state(null);
+    _token = $state(null);
+    _tokenExpireTime = $state(null);
+    // ── Derived ──────────────────────────────────────────────────────────────────
+    _isTokenValid = $derived(this._token !== null &&
+        this._tokenExpireTime !== null &&
+        this._tokenExpireTime > Date.now());
+    constructor() { }
+    static getInstance() {
+        if (!FirekitAppCheck.instance) {
+            FirekitAppCheck.instance = new FirekitAppCheck();
+        }
+        return FirekitAppCheck.instance;
+    }
+    // ── Public getters ───────────────────────────────────────────────────────────
+    /** Whether App Check has been initialized. */
+    get initialized() { return this._initialized; }
+    /** True while a token request is in flight. */
+    get loading() { return this._loading; }
+    /** Last error from initialization or token fetch. */
+    get error() { return this._error; }
+    /** The current App Check token string, or null if not yet acquired. */
+    get token() { return this._token; }
+    /** Whether the current token is present and has not expired locally. */
+    get isTokenValid() { return this._isTokenValid; }
+    // ── Initialization ───────────────────────────────────────────────────────────
+    /**
+     * Initializes App Check. Must be called before any other Firebase network call.
+     * Idempotent — subsequent calls are no-ops.
+     */
+    initialize(options) {
+        if (this._initialized || typeof window === 'undefined')
+            return;
+        try {
+            const app = firebaseService.getFirebaseApp();
+            if (!app)
+                throw new Error('Firebase app not initialized.');
+            this.appCheck = initializeAppCheck(app, options);
+            // Store the instance on firebaseService for other services to reference
+            firebaseService.appCheck = this.appCheck;
+            // Subscribe to token changes for reactive updates
+            this.unsubscribeToken = onTokenChanged(this.appCheck, (tokenResult) => {
+                this._token = tokenResult.token;
+                this._error = null;
+            }, (err) => {
+                this._error = err;
+            });
+            this._initialized = true;
+            this._error = null;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+            throw this._error;
+        }
+    }
+    // ── Token methods ────────────────────────────────────────────────────────────
+    /**
+     * Returns the current App Check token, fetching a fresh one if needed.
+     * @param forceRefresh - Force a new token even if the current one is valid.
+     */
+    async getToken(forceRefresh = false) {
+        if (!this.appCheck)
+            return null;
+        try {
+            this._loading = true;
+            const result = await getToken(this.appCheck, forceRefresh);
+            this._token = result.token;
+            this._error = null;
+            return result;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+            return null;
+        }
+        finally {
+            this._loading = false;
+        }
+    }
+    /**
+     * Returns a limited-use token (one-time use, not cached).
+     * Use this for sensitive operations like account deletion or payment flows.
+     */
+    async getLimitedUseToken() {
+        if (!this.appCheck)
+            return null;
+        try {
+            this._loading = true;
+            const result = await getLimitedUseToken(this.appCheck);
+            this._error = null;
+            return result;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+            return null;
+        }
+        finally {
+            this._loading = false;
+        }
+    }
+    /**
+     * Enables or disables automatic background token refresh.
+     */
+    setAutoRefresh(enabled) {
+        if (!this.appCheck)
+            return;
+        setTokenAutoRefreshEnabled(this.appCheck, enabled);
+    }
+    // ── Cleanup ──────────────────────────────────────────────────────────────────
+    dispose() {
+        this.unsubscribeToken?.();
+        this.unsubscribeToken = null;
+    }
+}
+export const firekitAppCheck = FirekitAppCheck.getInstance();

package/dist/services/auth.d.ts

@@ -1,402 +1,113 @@
+import { type User, type MultiFactorError, type MultiFactorResolver, type MultiFactorInfo } from 'firebase/auth';
+import { type SignInResult, type RegistrationResult, type OAuthSignInResult, type PhoneVerificationResult, type PasswordUpdateResult, type AccountDeletionResult } from '../types/auth.js';
 /**
- * @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, type SignInResult, type RegistrationResult, type OAuthSignInResult } 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.
+ * Firebase Authentication service.
+ * Handles all auth operations — sign in, register, sign out, profile updates.
+ * Reactive state (loading, user, isAuthenticated) lives in `firekitUser`.
  *
- * @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);
- * });
- * ```
+ * await firekitAuth.registerWithEmail('user@example.com', 'password', 'Jane Doe');
+ * await firekitAuth.signOut();
  */
 declare class FirekitAuth {
     private static instance;
     private auth;
     private firestore;
-    private _servicesInitialized;
-    private authState;
-    private stateListeners;
     private recaptchaVerifiers;
     private constructor();
-    /**
-     * Gets singleton instance of FirekitAuth
-     * @returns {FirekitAuth} The FirekitAuth instance
-     */
     static getInstance(): FirekitAuth;
-    /**
-     * Initializes Firebase services and auth state listener
-     * @private
-     */
-    private initializeServices;
-    /**
-     * 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<SignInResult>} Promise resolving to sign-in result
-     * @throws {FirekitAuthError} If sign-in fails
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const result = await firekitAuth.signInWithEmail("user@example.com", "password123");
-     *   console.log("Signed in:", result.user.displayName);
-     *   console.log("Is new user:", result.isNewUser);
-     * } catch (error) {
-     *   console.error("Sign-in failed:", error.message);
-     * }
-     * ```
-     */
+    private bootstrap;
+    private getAuth;
+    private syncToFirestore;
+    private profile;
     signInWithEmail(email: string, password: string): Promise<SignInResult>;
-    /**
-     * Signs in user with Google popup
-     * @returns {Promise<OAuthSignInResult>} Promise resolving to OAuth sign-in result
-     * @throws {FirekitAuthError} If sign-in fails
-     *
-     * @example
-     * ```typescript
-     * try {
-     *   const result = await firekitAuth.signInWithGoogle();
-     *   console.log("Signed in with Google:", result.user.email);
-     *   console.log("Is new user:", result.isNewUser);
-     *   console.log("Access token:", result.accessToken);
-     * } catch (error) {
-     *   if (error.code === 'auth/popup-closed-by-user') {
-     *     console.log("User cancelled sign-in");
-     *   }
-     * }
-     * ```
-     */
     signInWithGoogle(): Promise<OAuthSignInResult>;
-    /**
-     * Signs in user with Facebook popup
-     * @returns {Promise<OAuthSignInResult>} Promise resolving to OAuth sign-in result
-     * @throws {FirekitAuthError} If sign-in fails
-     */
     signInWithFacebook(): Promise<OAuthSignInResult>;
-    /**
-     * Signs in user with Apple popup
-     * @returns {Promise<OAuthSignInResult>} Promise resolving to OAuth sign-in result
-     * @throws {FirekitAuthError} If sign-in fails
-     */
     signInWithApple(): Promise<OAuthSignInResult>;
-    /**
-     * Signs in user anonymously
-     * @returns {Promise<SignInResult>} Promise resolving to sign-in result
-     * @throws {FirekitAuthError} If sign-in fails
-     *
-     * @example
-     * ```typescript
-     * const result = await firekitAuth.signInAnonymously();
-     * console.log("Anonymous user:", result.user.uid);
-     * console.log("Is new user:", result.isNewUser);
-     * ```
-     */
+    signInWithGithub(): Promise<OAuthSignInResult>;
+    signInWithTwitter(): Promise<OAuthSignInResult>;
+    signInWithMicrosoft(): Promise<OAuthSignInResult>;
+    private signInWithOAuth;
     signInAnonymously(): Promise<SignInResult>;
-    /**
-     * 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<RegistrationResult>} Promise resolving to registration result
-     * @throws {FirekitAuthError} If registration fails
-     *
-     * @example
-     * ```typescript
-     * const result = await firekitAuth.registerWithEmail(
-     *   "user@example.com",
-     *   "password123",
-     *   "John Doe"
-     * );
-     * console.log("Registered:", result.user.displayName);
-     * console.log("Email verification sent:", result.emailVerificationSent);
-     * ```
-     */
     registerWithEmail(email: string, password: string, displayName?: string, sendVerification?: boolean): Promise<RegistrationResult>;
-    /**
-     * 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");
-     * ```
-     */
+    signOut(): Promise<void>;
     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();
-     * ```
-     */
     sendEmailVerification(): Promise<void>;
-    /**
-     * Reloads user to get updated data
-     * @returns {Promise<void>} Promise that resolves when user is reloaded
-     * @throws {FirekitAuthError} If reload fails
-     *
-     * @example
-     * ```typescript
-     * await firekitAuth.reloadUser();
-     * ```
-     */
     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();
-     * ```
-     */
     getIdToken(forceRefresh?: boolean): Promise<string>;
-    /**
-     * Reauthenticates user with current password
-     * @private
-     */
-    private reauthenticateUser;
-    /**
-     * Deletes user account
-     * @param {string} [currentPassword] Current password for reauthentication
-     * @returns {Promise<AccountDeletionResult>} Promise resolving to deletion result
-     *
-     * @example
-     * ```typescript
-     * const result = await firekitAuth.deleteAccount("currentPassword123");
-     * if (result.success) {
-     *   console.log("Account deleted successfully");
-     * } else {
-     *   console.error("Deletion failed:", result.message);
-     * }
-     * ```
-     */
     deleteAccount(currentPassword?: string): Promise<AccountDeletionResult>;
+    reauthenticate(currentPassword: string): Promise<void>;
+    signInWithCustomToken(token: string): Promise<SignInResult>;
+    /** Signs in with a SAML provider (popup). */
+    signInWithSAML(providerId: string): Promise<OAuthSignInResult>;
+    /** Signs in with a SAML provider (redirect). Pair with `getRedirectResult()` on load. */
+    signInWithSAMLRedirect(providerId: string): Promise<void>;
     /**
-     * Signs out the 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");
-     * ```
+     * Signs in with a generic OIDC/OAuth2 provider (popup).
+     * @param providerId  Firebase provider ID, e.g. `'oidc.my-provider'`
+     * @param scopes      Additional OAuth scopes to request.
      */
-    signOut(): Promise<void>;
+    signInWithOIDC(providerId: string, scopes?: string[]): Promise<OAuthSignInResult>;
+    /** Signs in with a generic OIDC/OAuth2 provider (redirect). Pair with `getRedirectResult()` on load. */
+    signInWithOIDCRedirect(providerId: string, scopes?: string[]): Promise<void>;
+    signInWithGoogleRedirect(): Promise<void>;
+    signInWithFacebookRedirect(): Promise<void>;
+    signInWithAppleRedirect(): Promise<void>;
+    signInWithGithubRedirect(): Promise<void>;
+    signInWithTwitterRedirect(): Promise<void>;
+    signInWithMicrosoftRedirect(): Promise<void>;
     /**
-     * Checks if user is authenticated
-     * @returns {boolean} True if user is authenticated
+     * Completes a redirect sign-in flow.
+     * Call this once on app load to pick up the result of a `signInWith*Redirect()` call.
+     * Returns null if no redirect sign-in is pending.
      */
-    isAuthenticated(): boolean;
+    getRedirectResult(): Promise<OAuthSignInResult | null>;
     /**
-     * Checks if user is anonymous
-     * @returns {boolean} True if user is anonymous
+     * Starts phone MFA enrollment for the currently signed-in user.
+     * Returns a `verificationId` to pass to `completeMFAEnrollment()`.
      */
-    isAnonymous(): boolean;
+    startPhoneMFAEnrollment(phoneNumber: string, recaptchaContainerId: string): Promise<string>;
     /**
-     * Checks if user's email is verified
-     * @returns {boolean} True if email is verified
+     * Completes phone MFA enrollment using the SMS code.
      */
-    isEmailVerified(): boolean;
-    /**
-     * Gets user's email address
-     * @returns {string | null} User's email or null
-     */
-    getUserEmail(): string | null;
+    completeMFAEnrollment(verificationId: string, code: string, displayName?: string): Promise<void>;
+    /** Returns all enrolled MFA factors for the currently signed-in user. */
+    getMFAEnrolledFactors(): MultiFactorInfo[];
+    /** Unenrolls a specific MFA factor by its UID or `MultiFactorInfo` object. */
+    unenrollMFA(factorUidOrInfo: string | MultiFactorInfo): Promise<void>;
     /**
-     * Gets user's display name
-     * @returns {string | null} User's display name or null
+     * Gets the `MultiFactorResolver` from a sign-in error that requires MFA.
+     * Catch this error from any `signIn*` method when MFA is required.
      */
-    getUserDisplayName(): string | null;
+    getMFAResolver(error: MultiFactorError): MultiFactorResolver;
     /**
-     * Gets user's photo URL
-     * @returns {string | null} User's photo URL or null
-     */
-    getUserPhotoURL(): string | null;
-    /**
-     * Gets user's unique ID
-     * @returns {string | null} User's UID or null
+     * Sends an SMS code to complete an MFA sign-in challenge.
+     * Returns a `verificationId` to pass to `completeMFASignIn()`.
+     *
+     * @param resolver       From `getMFAResolver(error)`.
+     * @param factorIndex    Index into `resolver.hints` (default 0).
+     * @param recaptchaContainerId  DOM container ID for reCAPTCHA (required for phone MFA).
      */
-    getUserId(): string | null;
+    startMFASignIn(resolver: MultiFactorResolver, factorIndex: number | undefined, recaptchaContainerId: string): Promise<string>;
     /**
-     * Cleans up resources and listeners
-     * @returns {Promise<void>} Promise that resolves when cleanup completes
+     * Completes MFA sign-in using the SMS code.
      */
+    completeMFASignIn(resolver: MultiFactorResolver, verificationId: string, code: string): Promise<SignInResult>;
+    getCurrentUser(): User | null;
+    isAuthenticated(): boolean;
+    isAnonymous(): boolean;
+    isEmailVerified(): boolean;
     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 {};