svelte-firekit 0.1.9 → 0.2.0

package/dist/services/analytics.js

@@ -1,476 +1,144 @@
-/**
- * @fileoverview FirekitAnalytics - Google Analytics Service for SvelteKit with Firebase Analytics
- * @module FirekitAnalytics
- * @version 1.0.0
- */
-import { logEvent, setUserId, setUserProperties, setAnalyticsCollectionEnabled } from 'firebase/analytics';
+import { getAnalytics, logEvent, setUserId, setUserProperties, setDefaultEventParameters, setAnalyticsCollectionEnabled, setConsent, isSupported } from 'firebase/analytics';
 import { firebaseService } from '../firebase.js';
-import { firekitAuth } from './auth.js';
+function getApp() {
+    const app = firebaseService.getFirebaseApp();
+    if (!app)
+        throw new Error('Firebase app is not initialized.');
+    return app;
+}
 /**
- * Comprehensive Firebase Analytics service for SvelteKit applications.
- * Provides a complete analytics solution with automatic user tracking,
- * e-commerce tracking, and SvelteKit-specific features.
+ * Firebase Analytics wrapper.
+ *
+ * Lazily initializes Analytics (checks `isSupported()` first) and
+ * provides a clean, typed API for event logging and user properties.
  *
- * @class FirekitAnalytics
  * @example
- * ```typescript
+ * ```ts
  * import { firekitAnalytics } from 'svelte-firekit';
  *
- * // Track a custom event
- * firekitAnalytics.trackEvent('button_click', { button_name: 'signup' });
- *
- * // Track a purchase
- * firekitAnalytics.trackPurchase({
- *   transaction_id: 'T12345',
- *   value: 29.99,
- *   currency: 'USD',
- *   items: [{ item_id: 'prod_123', item_name: 'Premium Plan' }]
- * });
+ * firekitAnalytics.logEvent('purchase', { value: 9.99, currency: 'USD' });
+ * firekitAnalytics.setUserId(user.uid);
  * ```
  */
 class FirekitAnalytics {
     static instance;
-    analytics = null;
-    _initialized = false;
-    customParameters = {};
-    debugMode = false;
-    constructor() {
-        if (typeof window !== 'undefined') {
-            this.initialize();
-        }
-    }
-    /**
-     * Gets singleton instance of FirekitAnalytics
-     * @returns {FirekitAnalytics} The FirekitAnalytics instance
-     */
+    _analytics = null;
+    _initPromise = null;
+    constructor() { }
     static getInstance() {
         if (!FirekitAnalytics.instance) {
             FirekitAnalytics.instance = new FirekitAnalytics();
         }
         return FirekitAnalytics.instance;
     }
-    /**
-     * Initializes the analytics service
-     */
-    initialize() {
-        if (this._initialized || typeof window === 'undefined')
-            return;
-        try {
-            this.analytics = firebaseService.getAnalyticsInstance();
-            this._initialized = true;
-            console.log('FirekitAnalytics initialized successfully');
-        }
-        catch (error) {
-            console.error('Failed to initialize FirekitAnalytics:', error);
-            this._initialized = false;
-        }
-    }
-    /**
-     * Checks if analytics is available
-     * @private
-     */
-    isAnalyticsAvailable() {
-        return this._initialized && this.analytics !== null;
-    }
-    /**
-     * Gets the analytics instance
-     * @returns {Analytics | null} Firebase Analytics instance
-     */
-    getAnalyticsInstance() {
-        return this.analytics;
-    }
-    /**
-     * Checks if analytics is initialized
-     * @returns {boolean} True if analytics is initialized
-     */
-    isInitialized() {
-        return this._initialized;
-    }
-    // ========================================
-    // CORE TRACKING FUNCTIONS
-    // ========================================
-    /**
-     * Logs a custom analytics event
-     * @param {string} eventName Name of the event
-     * @param {Record<string, any>} parameters Event parameters
+    _init() {
+        if (this._initPromise)
+            return this._initPromise;
+        this._initPromise = (async () => {
+            if (typeof window === 'undefined')
+                return;
+            const supported = await isSupported();
+            if (!supported)
+                return;
+            this._analytics = getAnalytics(getApp());
+        })();
+        return this._initPromise;
+    }
+    async _get() {
+        await this._init();
+        return this._analytics;
+    }
+    // ── Event logging ─────────────────────────────────────────────────────────
+    /**
+     * Logs a custom or standard analytics event.
      *
      * @example
-     * ```typescript
-     * firekitAnalytics.trackEvent('button_click', {
-     *   button_name: 'signup',
-     *   page_location: '/home'
-     * });
+     * ```ts
+     * firekitAnalytics.logEvent('sign_up', { method: 'google' });
+     * firekitAnalytics.logEvent('page_view', { page_title: 'Home' });
      * ```
      */
-    trackEvent(eventName, parameters = {}) {
-        if (!this.isAnalyticsAvailable()) {
-            console.warn('Analytics not available, event not tracked:', eventName);
+    async logEvent(eventName, eventParams) {
+        const a = await this._get();
+        if (!a)
             return;
-        }
-        try {
-            const mergedParameters = { ...this.customParameters, ...parameters };
-            logEvent(this.analytics, eventName, mergedParameters);
-            if (this.debugMode) {
-                console.log('Analytics Event:', eventName, mergedParameters);
-            }
-        }
-        catch (error) {
-            console.error('Failed to track event:', eventName, error);
-        }
-    }
-    /**
-     * Tracks page view events
-     * @param {PageViewEvent} pageView Page view data
-     *
-     * @example
-     * ```typescript
-     * firekitAnalytics.trackPageView({
-     *   page_path: '/products',
-     *   page_title: 'Products Page'
-     * });
-     * ```
-     */
-    trackPageView(pageView) {
-        this.trackEvent('page_view', {
-            page_path: pageView.page_path,
-            page_title: pageView.page_title || document.title,
-            page_location: pageView.page_location || window.location.href,
-            page_referrer: pageView.page_referrer || document.referrer
-        });
+        logEvent(a, eventName, eventParams);
     }
+    // ── User identity ─────────────────────────────────────────────────────────
     /**
-     * Sets user ID for analytics
-     * @param {string | null} userId User ID or null to clear
+     * Sets the Analytics user ID.
+     * Pass `null` to clear the user ID (e.g. on sign-out).
      */
-    setUserId(userId) {
-        if (!this.isAnalyticsAvailable())
+    async setUserId(id) {
+        const a = await this._get();
+        if (!a)
             return;
-        try {
-            setUserId(this.analytics, userId);
-        }
-        catch (error) {
-            console.error('Failed to set user ID:', error);
-        }
+        setUserId(a, id);
     }
     /**
-     * Sets user properties for analytics
-     * @param {Record<string, any>} properties User properties
+     * Sets Analytics user properties.
      *
      * @example
-     * ```typescript
-     * firekitAnalytics.setUserProperties({
-     *   user_type: 'premium',
-     *   subscription_plan: 'pro'
-     * });
+     * ```ts
+     * firekitAnalytics.setUserProperties({ plan: 'pro', locale: 'en-US' });
      * ```
      */
-    setUserProperties(properties) {
-        if (!this.isAnalyticsAvailable())
+    async setUserProperties(properties) {
+        const a = await this._get();
+        if (!a)
             return;
-        try {
-            setUserProperties(this.analytics, properties);
-        }
-        catch (error) {
-            console.error('Failed to set user properties:', error);
-        }
+        setUserProperties(a, properties);
     }
-    // ========================================
-    // E-COMMERCE TRACKING
-    // ========================================
+    // ── Screen / page tracking ────────────────────────────────────────────────
     /**
-     * Tracks purchase events
-     * @param {PurchaseEvent} purchase Purchase data
+     * Logs a screen_view event.
      *
      * @example
-     * ```typescript
-     * firekitAnalytics.trackPurchase({
-     *   transaction_id: 'T12345',
-     *   value: 29.99,
-     *   currency: 'USD',
-     *   items: [{
-     *     item_id: 'prod_123',
-     *     item_name: 'Premium Plan',
-     *     price: 29.99
-     *   }]
-     * });
+     * ```ts
+     * firekitAnalytics.setCurrentScreen('ProductDetail');
      * ```
      */
-    trackPurchase(purchase) {
-        const parameters = {
-            transaction_id: purchase.transaction_id,
-            value: purchase.value,
-            currency: purchase.currency || 'USD'
-        };
-        if (purchase.tax !== undefined)
-            parameters.tax = purchase.tax;
-        if (purchase.shipping !== undefined)
-            parameters.shipping = purchase.shipping;
-        if (purchase.items)
-            parameters.items = purchase.items;
-        this.trackEvent('purchase', parameters);
-    }
-    /**
-     * Tracks add to cart events
-     * @param {EcommerceItem} item Item being added to cart
-     * @param {number} value Total value of the cart
-     * @param {string} currency Currency code
-     *
-     * @example
-     * ```typescript
-     * firekitAnalytics.trackAddToCart({
-     *   item_id: 'prod_123',
-     *   item_name: 'Premium Plan',
-     *   price: 29.99
-     * }, 29.99, 'USD');
-     * ```
-     */
-    trackAddToCart(item, value, currency = 'USD') {
-        this.trackEvent('add_to_cart', {
-            currency,
-            value,
-            items: [item]
-        });
-    }
-    /**
-     * Tracks remove from cart events
-     * @param {EcommerceItem} item Item being removed from cart
-     * @param {number} value Total value of the cart
-     * @param {string} currency Currency code
-     */
-    trackRemoveFromCart(item, value, currency = 'USD') {
-        this.trackEvent('remove_from_cart', {
-            currency,
-            value,
-            items: [item]
-        });
-    }
-    /**
-     * Tracks view item events
-     * @param {EcommerceItem} item Item being viewed
-     */
-    trackViewItem(item) {
-        this.trackEvent('view_item', {
-            items: [item]
-        });
+    async setCurrentScreen(screenName) {
+        const a = await this._get();
+        if (!a)
+            return;
+        logEvent(a, 'screen_view', { screen_name: screenName });
     }
+    // ── Defaults & consent ────────────────────────────────────────────────────
     /**
-     * Tracks begin checkout events
-     * @param {EcommerceItem[]} items Items in cart
-     * @param {number} value Total value
-     * @param {string} currency Currency code
+     * Sets default parameters that will be included with every logged event.
      */
-    trackBeginCheckout(items, value, currency = 'USD') {
-        this.trackEvent('begin_checkout', {
-            currency,
-            value,
-            items
-        });
+    async setDefaultEventParameters(params) {
+        await this._get();
+        if (params)
+            setDefaultEventParameters(params);
     }
-    // ========================================
-    // ENGAGEMENT TRACKING
-    // ========================================
     /**
-     * Tracks form submission events
-     * @param {FormSubmissionEvent} formSubmission Form submission data
-     *
-     * @example
-     * ```typescript
-     * firekitAnalytics.trackFormSubmission({
-     *   form_name: 'contact_form',
-     *   success: true
-     * });
-     * ```
+     * Enables or disables Analytics data collection.
+     * Useful for respecting user consent.
      */
-    trackFormSubmission(formSubmission) {
-        const parameters = {
-            form_name: formSubmission.form_name
-        };
-        if (formSubmission.form_id)
-            parameters.form_id = formSubmission.form_id;
-        if (formSubmission.success !== undefined)
-            parameters.success = formSubmission.success;
-        if (formSubmission.error_message)
-            parameters.error_message = formSubmission.error_message;
-        this.trackEvent('form_submit', parameters);
+    async setCollectionEnabled(enabled) {
+        const a = await this._get();
+        if (!a)
+            return;
+        setAnalyticsCollectionEnabled(a, enabled);
     }
     /**
-     * Tracks search events
-     * @param {SearchEvent} search Search data
+     * Updates consent settings (GDPR, CCPA, etc.).
      *
      * @example
-     * ```typescript
-     * firekitAnalytics.trackSearch({
-     *   search_term: 'premium features',
-     *   results_count: 15
+     * ```ts
+     * firekitAnalytics.setConsent({
+     *   analytics_storage: 'granted',
+     *   ad_storage: 'denied'
      * });
      * ```
      */
-    trackSearch(search) {
-        const parameters = {
-            search_term: search.search_term
-        };
-        if (search.results_count !== undefined)
-            parameters.results_count = search.results_count;
-        if (search.category)
-            parameters.category = search.category;
-        this.trackEvent('search', parameters);
-    }
-    /**
-     * Tracks custom conversion events
-     * @param {string} conversionName Name of the conversion
-     * @param {number} value Conversion value
-     * @param {string} currency Currency code
-     */
-    trackConversion(conversionName, value, currency = 'USD') {
-        const parameters = {};
-        if (value !== undefined) {
-            parameters.value = value;
-            parameters.currency = currency;
-        }
-        this.trackEvent(conversionName, parameters);
-    }
-    /**
-     * Tracks user engagement events
-     * @param {EngagementEvent} engagement Engagement data
-     */
-    trackEngagement(engagement) {
-        const parameters = {};
-        if (engagement.engagement_time_msec)
-            parameters.engagement_time_msec = engagement.engagement_time_msec;
-        if (engagement.session_id)
-            parameters.session_id = engagement.session_id;
-        this.trackEvent('user_engagement', parameters);
-    }
-    // ========================================
-    // SVELTEKIT-SPECIFIC FUNCTIONS
-    // ========================================
-    /**
-     * Initializes automatic page tracking for SvelteKit
-     * @param {boolean} trackInitialPage Whether to track the initial page load
-     *
-     * @example
-     * ```typescript
-     * // In your app.html or layout
-     * firekitAnalytics.initPageTracking();
-     * ```
-     */
-    initPageTracking(trackInitialPage = true) {
-        if (typeof window === 'undefined')
+    async setConsent(settings) {
+        const a = await this._get();
+        if (!a)
             return;
-        // Track initial page load
-        if (trackInitialPage) {
-            this.trackPageView({
-                page_path: window.location.pathname,
-                page_title: document.title
-            });
-        }
-        // Listen for SvelteKit navigation events
-        window.addEventListener('sveltekit:navigation-end', () => {
-            this.trackPageView({
-                page_path: window.location.pathname,
-                page_title: document.title
-            });
-        });
-        // Fallback for other navigation events
-        window.addEventListener('popstate', () => {
-            this.trackPageView({
-                page_path: window.location.pathname,
-                page_title: document.title
-            });
-        });
-    }
-    /**
-     * Tracks route changes manually (useful for custom routing)
-     * @param {string} route Route path
-     * @param {string} title Page title
-     */
-    trackRouteChange(route, title) {
-        this.trackPageView({
-            page_path: route,
-            page_title: title || document.title
-        });
-    }
-    // ========================================
-    // UTILITY FUNCTIONS
-    // ========================================
-    /**
-     * Sets custom parameters that will be included in all subsequent events
-     * @param {Record<string, any>} parameters Custom parameters
-     */
-    setCustomParameters(parameters) {
-        this.customParameters = { ...this.customParameters, ...parameters };
-    }
-    /**
-     * Clears custom parameters
-     */
-    clearCustomParameters() {
-        this.customParameters = {};
-    }
-    /**
-     * Tracks multiple events in batch
-     * @param {AnalyticsEvent[]} events Array of events to track
-     */
-    trackEvents(events) {
-        events.forEach((event) => {
-            this.trackEvent(event.name, event.parameters);
-        });
-    }
-    /**
-     * Enables or disables analytics collection
-     * @param {boolean} enabled Whether to enable analytics collection
-     */
-    setAnalyticsEnabled(enabled) {
-        if (!this.isAnalyticsAvailable())
-            return;
-        try {
-            setAnalyticsCollectionEnabled(this.analytics, enabled);
-        }
-        catch (error) {
-            console.error('Failed to set analytics collection enabled:', error);
-        }
-    }
-    /**
-     * Sets debug mode for analytics
-     * @param {boolean} enabled Whether to enable debug mode
-     */
-    setDebugMode(enabled) {
-        this.debugMode = enabled;
-    }
-    /**
-     * Gets current debug mode status
-     * @returns {boolean} Current debug mode status
-     */
-    getDebugMode() {
-        return this.debugMode;
-    }
-    /**
-     * Cleans up analytics resources
-     */
-    cleanup() {
-        this.customParameters = {};
-        this.debugMode = false;
+        setConsent(settings);
     }
 }
-/**
- * Pre-initialized singleton instance of FirekitAnalytics.
- * This is the main export that should be used throughout your application.
- *
- * @example
- * ```typescript
- * import { firekitAnalytics } from 'svelte-firekit';
- *
- * // Track a custom event
- * firekitAnalytics.trackEvent('button_click', { button_name: 'signup' });
- *
- * // Initialize page tracking
- * firekitAnalytics.initPageTracking();
- *
- * // Track a purchase
- * firekitAnalytics.trackPurchase({
- *   transaction_id: 'T12345',
- *   value: 29.99,
- *   currency: 'USD'
- * });
- * ```
- */
 export const firekitAnalytics = FirekitAnalytics.getInstance();

package/dist/services/app-check.svelte.d.ts

@@ -0,0 +1,82 @@
+import { type AppCheckOptions, type AppCheckTokenResult } from 'firebase/app-check';
+export type { AppCheckOptions, AppCheckTokenResult };
+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') });
+ * ```
+ */
+declare class FirekitAppCheck {
+    private static instance;
+    private appCheck;
+    private unsubscribeToken;
+    private _initialized;
+    private _loading;
+    private _error;
+    private _token;
+    private _tokenExpireTime;
+    private _isTokenValid;
+    private constructor();
+    static getInstance(): FirekitAppCheck;
+    /** Whether App Check has been initialized. */
+    get initialized(): boolean;
+    /** True while a token request is in flight. */
+    get loading(): boolean;
+    /** Last error from initialization or token fetch. */
+    get error(): Error | null;
+    /** The current App Check token string, or null if not yet acquired. */
+    get token(): string | null;
+    /** Whether the current token is present and has not expired locally. */
+    get isTokenValid(): boolean;
+    /**
+     * Initializes App Check. Must be called before any other Firebase network call.
+     * Idempotent — subsequent calls are no-ops.
+     */
+    initialize(options: AppCheckOptions): void;
+    /**
+     * 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.
+     */
+    getToken(forceRefresh?: boolean): Promise<AppCheckTokenResult | null>;
+    /**
+     * Returns a limited-use token (one-time use, not cached).
+     * Use this for sensitive operations like account deletion or payment flows.
+     */
+    getLimitedUseToken(): Promise<AppCheckTokenResult | null>;
+    /**
+     * Enables or disables automatic background token refresh.
+     */
+    setAutoRefresh(enabled: boolean): void;
+    dispose(): void;
+}
+export declare const firekitAppCheck: FirekitAppCheck;