svelte-firekit 0.1.4 → 0.1.6

package/dist/components/Collection.svelte

@@ -45,92 +45,64 @@
 	} = $props();
 
 	// Get Firestore instance only in browser environment
-	let firestore: Firestore | null = $state(null);
-	let collectionRef: CollectionReference | Query | null = $state(null);
-	let collectionService: ReturnType<typeof firekitCollection> | null = $state(null);
+	let firestore = $derived(browser ? firebaseService.getDbInstance() : null);
 
-	// Track collection state
-	let collectionState = $state({
-		loading: true,
-		data: startWith ?? ([] as DocumentData[]),
-		error: null as Error | null,
-		count: startWith?.length ?? 0
+	// Create collection reference if path string is provided
+	let collectionRef = $derived(
+		firestore && typeof ref === 'string'
+			? collection(firestore, ref)
+			: (ref as CollectionReference | Query)
+	);
+
+	// Create collection service with derived path
+	let collectionPath = $derived(typeof ref === 'string' ? ref : (ref as CollectionReference).path);
+	let collectionService = $state<ReturnType<typeof firekitCollection> | null>(null);
+
+	// Track collection state using derived computations
+	let collectionState = $derived({
+		loading: !browser
+			? false
+			: !firestore
+				? false
+				: !collectionService
+					? true
+					: collectionService.loading,
+		data: !browser
+			? (startWith ?? [])
+			: !firestore
+				? []
+				: !collectionService
+					? (startWith ?? [])
+					: collectionService.data,
+		error: !browser
+			? null
+			: !firestore
+				? new Error('Firestore instance not available')
+				: !collectionService
+					? null
+					: collectionService.error,
+		count: !browser
+			? (startWith?.length ?? 0)
+			: !firestore
+				? 0
+				: !collectionService
+					? (startWith?.length ?? 0)
+					: collectionService.size
 	});
 
-	// Subscribe to collection changes only if in browser and collection service exists
+	// Set up collection service
 	$effect(() => {
-		if (!browser) {
-			collectionState = {
-				loading: false,
-				data: startWith ?? [],
-				error: null,
-				count: startWith?.length ?? 0
-			};
-			return;
-		}
-
-		// Initialize Firestore and collection service
-		firestore = firebaseService.getDbInstance();
-		if (!firestore) {
-			collectionState = {
-				loading: false,
-				data: [],
-				error: new Error('Firestore instance not available'),
-				count: 0
-			};
+		if (!browser || !collectionPath) {
+			collectionService = null;
 			return;
 		}
 
-		// Create collection reference if path string is provided
-		collectionRef =
-			typeof ref === 'string' ? collection(firestore, ref) : (ref as CollectionReference | Query);
-
-		// Create collection service
-		collectionService = firekitCollection(
-			typeof ref === 'string' ? ref : (ref as CollectionReference).path,
-			queryConstraints
-		);
-
-		// Update state based on collection service state
-		collectionState = {
-			loading: collectionService.loading,
-			data: collectionService.data,
-			error: collectionService.error,
-			count: collectionService.size
-		};
-
-		// Set up event listener for real-time updates
-		const unsubscribe = collectionService.addEventListener((event) => {
-			if (event.type === 'data_changed') {
-				collectionState = {
-					loading: false,
-					data: event.data || [],
-					error: null,
-					count: event.data?.length || 0
-				};
-			} else if (event.type === 'error') {
-				collectionState = {
-					loading: false,
-					data: [],
-					error: event.error || null,
-					count: 0
-				};
-			} else if (event.type === 'loading_started') {
-				collectionState = {
-					...collectionState,
-					loading: true
-				};
-			} else if (event.type === 'loading_finished') {
-				collectionState = {
-					...collectionState,
-					loading: false
-				};
-			}
-		});
+		// Create new service when path or constraints change
+		const newService = firekitCollection(collectionPath, queryConstraints);
+		collectionService = newService;
 
 		return () => {
-			unsubscribe();
-			collectionService?.dispose();
+			newService?.dispose();
 		};
 	});
 </script>

package/dist/components/Doc.svelte

@@ -0,0 +1,140 @@
+<script lang="ts">
+	import { firekitDoc } from '../services/document.svelte.js';
+	import { firebaseService } from '../firebase.js';
+	import { doc } from 'firebase/firestore';
+	import { browser } from '$app/environment';
+	import type { DocumentReference, DocumentData, Firestore } from 'firebase/firestore';
+	import type { Snippet } from 'svelte';
+	import type { DocumentOptions } from '../types/document.js';
+
+	/**
+	 * Props for Doc component
+	 */
+	let {
+		ref,
+		startWith,
+		children,
+		loading,
+		options = {}
+	}: {
+		/**
+		 * Firestore document reference or path string
+		 */
+		ref: DocumentReference | string;
+		/**
+		 * Initial value to use before document is fetched
+		 */
+		startWith?: DocumentData | null;
+		/**
+		 * Content to render when document is loaded
+		 */
+		children: Snippet<[DocumentData | null, DocumentReference, Firestore]>;
+		/**
+		 * Content to render while loading
+		 */
+		loading?: Snippet<[]>;
+		/**
+		 * Document options for configuration
+		 */
+		options?: DocumentOptions;
+	} = $props();
+
+	// Get Firestore instance only in browser environment
+	let firestore = $derived(browser ? firebaseService.getDbInstance() : null);
+
+	// Create document reference if path string is provided
+	let docRef = $derived(
+		firestore && typeof ref === 'string' ? doc(firestore, ref) : (ref as DocumentReference)
+	);
+
+	// Create document service with derived path
+	let documentPath = $derived(typeof ref === 'string' ? ref : (ref as DocumentReference).path);
+	let documentService = $state<ReturnType<typeof firekitDoc> | null>(null);
+
+	// Track document state using derived computations
+	let documentState = $derived({
+		loading: !browser
+			? false
+			: !firestore
+				? false
+				: !documentService
+					? true
+					: documentService.loading,
+		data: !browser
+			? (startWith ?? null)
+			: !firestore
+				? null
+				: !documentService
+					? (startWith ?? null)
+					: documentService.data,
+		error: !browser
+			? null
+			: !firestore
+				? new Error('Firestore instance not available')
+				: !documentService
+					? null
+					: documentService.error,
+		canRefresh: !browser
+			? false
+			: !firestore
+				? false
+				: !documentService
+					? false
+					: documentService.canRefresh
+	});
+
+	// Set up document service and event listener
+	$effect(() => {
+		if (!browser || !documentPath) {
+			documentService = null;
+			return;
+		}
+
+		// Create new service when path or options change
+		const newService = firekitDoc(documentPath, startWith ?? undefined, options);
+		documentService = newService;
+
+		return () => {
+			newService?.dispose();
+		};
+	});
+</script>
+
+{#if !browser}
+	{@render children(startWith ?? null, null as any, null as any)}
+{:else if !firestore}
+	<div class="flex items-center justify-center min-h-screen">
+		<div class="text-center">
+			<div class="text-red-500 text-lg font-semibold mb-2">Firestore Not Available</div>
+			<p class="text-gray-600">Firestore instance is not available.</p>
+		</div>
+	</div>
+{:else if documentState.loading}
+	{#if loading}
+		{@render loading()}
+	{:else}
+		<div class="flex items-center justify-center min-h-screen">
+			<div class="text-center">
+				<div class="animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900 mx-auto"></div>
+				<p class="mt-2 text-gray-600">Loading document...</p>
+			</div>
+		</div>
+	{/if}
+{:else if documentState.error}
+	<div class="flex items-center justify-center min-h-screen">
+		<div class="text-center">
+			<div class="text-red-500 text-lg font-semibold mb-2">Error Loading Document</div>
+			<p class="text-gray-600 mb-4">{documentState.error.message}</p>
+			{#if documentState.canRefresh}
+				<button
+					class="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
+					onclick={() => documentService?.refresh()}
+				>
+					Retry
+				</button>
+			{/if}
+		</div>
+	</div>
+{:else}
+	{@render children(documentState.data, docRef!, firestore!)}
+{/if}

package/dist/components/{Ddoc.svelte.d.ts → Doc.svelte.d.ts}

@@ -23,6 +23,6 @@ type $$ComponentProps = {
      */
     options?: DocumentOptions;
 };
-declare const Ddoc: import("svelte").Component<$$ComponentProps, {}, "">;
-type Ddoc = ReturnType<typeof Ddoc>;
-export default Ddoc;
+declare const Doc: import("svelte").Component<$$ComponentProps, {}, "">;
+type Doc = ReturnType<typeof Doc>;
+export default Doc;

package/dist/components/upload-task.svelte

@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { ref, type StorageReference, type UploadTaskSnapshot } from 'firebase/storage';
+	import { type UploadTaskSnapshot } from 'firebase/storage';
 	import { firebaseService } from '../firebase.js';
 	import { firekitUploadTask } from '../services/storage.svelte.js';
 	import { browser } from '$app/environment';

package/dist/firebase.d.ts

@@ -18,6 +18,7 @@ declare class FirebaseService implements FirebaseServiceInstance {
     functions: FirebaseServiceInstance['functions'];
     database: FirebaseServiceInstance['database'];
     storage: FirebaseServiceInstance['storage'];
+    analytics: FirebaseServiceInstance['analytics'];
     status: FirebaseServiceStatus;
     initializationError: Error | null;
     readonly isBrowser: boolean;
@@ -93,6 +94,14 @@ declare class FirebaseService implements FirebaseServiceInstance {
      * @throws {FirebaseServiceError} If Storage initialization fails
      */
     getStorageInstance(): FirebaseServiceInstance['storage'];
+    /**
+     * Gets the Analytics instance, initializing it if necessary.
+     * Only available in browser environment.
+     *
+     * @returns {Analytics} The Analytics instance
+     * @throws {FirebaseServiceError} If Analytics initialization fails
+     */
+    getAnalyticsInstance(): FirebaseServiceInstance['analytics'];
     /**
      * Resets the Firebase service to its initial state.
      * Useful for testing or when you need to reinitialize the services.

package/dist/firebase.js

@@ -4,6 +4,7 @@ import { getAuth } from 'firebase/auth';
 import { getFunctions } from 'firebase/functions';
 import { getDatabase } from 'firebase/database';
 import { getStorage } from 'firebase/storage';
+import { getAnalytics } from 'firebase/analytics';
 import { firebaseConfig } from './config.js';
 import { FirebaseServiceStatus, FirebaseServiceError } from './types/firebase.js';
 /**
@@ -25,6 +26,7 @@ class FirebaseService {
     functions = null;
     database = null;
     storage = null;
+    analytics = null;
     status = FirebaseServiceStatus.UNINITIALIZED;
     initializationError = null;
     isBrowser = typeof window !== 'undefined';
@@ -216,6 +218,27 @@ class FirebaseService {
             throw new FirebaseServiceError('Failed to initialize Storage', 'storage');
         }
     }
+    /**
+     * Gets the Analytics instance, initializing it if necessary.
+     * Only available in browser environment.
+     *
+     * @returns {Analytics} The Analytics instance
+     * @throws {FirebaseServiceError} If Analytics initialization fails
+     */
+    getAnalyticsInstance() {
+        if (!this.isBrowser) {
+            throw new FirebaseServiceError('Analytics is not available in server environment', 'analytics');
+        }
+        try {
+            if (!this.analytics) {
+                this.analytics = getAnalytics(this.getFirebaseApp());
+            }
+            return this.analytics;
+        }
+        catch (error) {
+            throw new FirebaseServiceError('Failed to initialize Analytics', 'analytics');
+        }
+    }
     /**
      * Resets the Firebase service to its initial state.
      * Useful for testing or when you need to reinitialize the services.
@@ -229,6 +252,7 @@ class FirebaseService {
         this.functions = null;
         this.database = null;
         this.storage = null;
+        this.analytics = null;
         this.status = FirebaseServiceStatus.UNINITIALIZED;
         this.initializationError = null;
     }

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { firebaseService } from './firebase.js';
 export { firekitUser } from './services/user.svelte.js';
 export { firekitAuth } from './services/auth.js';
 export { firekitPresence } from './services/presence.svelte.js';
+export { firekitAnalytics } from './services/analytics.js';
 export { firekitDoc, firekitDocOnce, firekitDocWithMetadata } from './services/document.svelte.js';
 export { firekitDocMutations } from './services/mutations.js';
 export { firekitCollection, firekitCollectionGroup, firekitCollectionOnce } from './services/collection.svelte.js';
@@ -14,7 +15,7 @@ export { default as AuthGuard } from './components/auth-guard.svelte';
 export { default as CustomGuard } from './components/custom-guard.svelte';
 export { default as SignedIn } from './components/signed-in.svelte';
 export { default as SignedOut } from './components/signed-out.svelte';
-export { default as Doc } from './components/Ddoc.svelte';
+export { default as Doc } from './components/Doc.svelte';
 export { default as Collection } from './components/Collection.svelte';
 export { default as Node } from './components/Node.svelte';
 export { default as NodeList } from './components/node-list.svelte';

package/dist/index.js

@@ -7,6 +7,8 @@ export { firebaseService } from './firebase.js';
 export { firekitUser } from './services/user.svelte.js';
 export { firekitAuth } from './services/auth.js';
 export { firekitPresence } from './services/presence.svelte.js';
+// analytics services
+export { firekitAnalytics } from './services/analytics.js';
 // document services
 export { firekitDoc, firekitDocOnce, firekitDocWithMetadata } from './services/document.svelte.js';
 // mutations services
@@ -23,7 +25,7 @@ export { default as AuthGuard } from './components/auth-guard.svelte';
 export { default as CustomGuard } from './components/custom-guard.svelte';
 export { default as SignedIn } from './components/signed-in.svelte';
 export { default as SignedOut } from './components/signed-out.svelte';
-export { default as Doc } from './components/Ddoc.svelte';
+export { default as Doc } from './components/Doc.svelte';
 export { default as Collection } from './components/Collection.svelte';
 export { default as Node } from './components/Node.svelte';
 export { default as NodeList } from './components/node-list.svelte';

package/dist/services/analytics.d.ts

@@ -0,0 +1,272 @@
+/**
+ * @fileoverview FirekitAnalytics - Google Analytics Service for SvelteKit with Firebase Analytics
+ * @module FirekitAnalytics
+ * @version 1.0.0
+ */
+import { type Analytics } from 'firebase/analytics';
+import type { AnalyticsEvent, EcommerceItem, PurchaseEvent, FormSubmissionEvent, SearchEvent, PageViewEvent, EngagementEvent } from '../types/analytics.js';
+/**
+ * Comprehensive Firebase Analytics service for SvelteKit applications.
+ * Provides a complete analytics solution with automatic user tracking,
+ * e-commerce tracking, and SvelteKit-specific features.
+ *
+ * @class FirekitAnalytics
+ * @example
+ * ```typescript
+ * 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' }]
+ * });
+ * ```
+ */
+declare class FirekitAnalytics {
+    private static instance;
+    private analytics;
+    private _initialized;
+    private customParameters;
+    private debugMode;
+    private constructor();
+    /**
+     * Gets singleton instance of FirekitAnalytics
+     * @returns {FirekitAnalytics} The FirekitAnalytics instance
+     */
+    static getInstance(): FirekitAnalytics;
+    /**
+     * Initializes the analytics service
+     */
+    private initialize;
+    /**
+     * Checks if analytics is available
+     * @private
+     */
+    private isAnalyticsAvailable;
+    /**
+     * Gets the analytics instance
+     * @returns {Analytics | null} Firebase Analytics instance
+     */
+    getAnalyticsInstance(): Analytics | null;
+    /**
+     * Checks if analytics is initialized
+     * @returns {boolean} True if analytics is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Logs a custom analytics event
+     * @param {string} eventName Name of the event
+     * @param {Record<string, any>} parameters Event parameters
+     *
+     * @example
+     * ```typescript
+     * firekitAnalytics.trackEvent('button_click', {
+     *   button_name: 'signup',
+     *   page_location: '/home'
+     * });
+     * ```
+     */
+    trackEvent(eventName: string, parameters?: Record<string, any>): void;
+    /**
+     * Tracks page view events
+     * @param {PageViewEvent} pageView Page view data
+     *
+     * @example
+     * ```typescript
+     * firekitAnalytics.trackPageView({
+     *   page_path: '/products',
+     *   page_title: 'Products Page'
+     * });
+     * ```
+     */
+    trackPageView(pageView: PageViewEvent): void;
+    /**
+     * Sets user ID for analytics
+     * @param {string | null} userId User ID or null to clear
+     */
+    setUserId(userId: string | null): void;
+    /**
+     * Sets user properties for analytics
+     * @param {Record<string, any>} properties User properties
+     *
+     * @example
+     * ```typescript
+     * firekitAnalytics.setUserProperties({
+     *   user_type: 'premium',
+     *   subscription_plan: 'pro'
+     * });
+     * ```
+     */
+    setUserProperties(properties: Record<string, any>): void;
+    /**
+     * Tracks purchase events
+     * @param {PurchaseEvent} purchase Purchase data
+     *
+     * @example
+     * ```typescript
+     * firekitAnalytics.trackPurchase({
+     *   transaction_id: 'T12345',
+     *   value: 29.99,
+     *   currency: 'USD',
+     *   items: [{
+     *     item_id: 'prod_123',
+     *     item_name: 'Premium Plan',
+     *     price: 29.99
+     *   }]
+     * });
+     * ```
+     */
+    trackPurchase(purchase: PurchaseEvent): void;
+    /**
+     * 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: EcommerceItem, value: number, currency?: string): void;
+    /**
+     * 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: EcommerceItem, value: number, currency?: string): void;
+    /**
+     * Tracks view item events
+     * @param {EcommerceItem} item Item being viewed
+     */
+    trackViewItem(item: EcommerceItem): void;
+    /**
+     * Tracks begin checkout events
+     * @param {EcommerceItem[]} items Items in cart
+     * @param {number} value Total value
+     * @param {string} currency Currency code
+     */
+    trackBeginCheckout(items: EcommerceItem[], value: number, currency?: string): void;
+    /**
+     * Tracks form submission events
+     * @param {FormSubmissionEvent} formSubmission Form submission data
+     *
+     * @example
+     * ```typescript
+     * firekitAnalytics.trackFormSubmission({
+     *   form_name: 'contact_form',
+     *   success: true
+     * });
+     * ```
+     */
+    trackFormSubmission(formSubmission: FormSubmissionEvent): void;
+    /**
+     * Tracks search events
+     * @param {SearchEvent} search Search data
+     *
+     * @example
+     * ```typescript
+     * firekitAnalytics.trackSearch({
+     *   search_term: 'premium features',
+     *   results_count: 15
+     * });
+     * ```
+     */
+    trackSearch(search: SearchEvent): void;
+    /**
+     * Tracks custom conversion events
+     * @param {string} conversionName Name of the conversion
+     * @param {number} value Conversion value
+     * @param {string} currency Currency code
+     */
+    trackConversion(conversionName: string, value?: number, currency?: string): void;
+    /**
+     * Tracks user engagement events
+     * @param {EngagementEvent} engagement Engagement data
+     */
+    trackEngagement(engagement: EngagementEvent): void;
+    /**
+     * 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?: boolean): void;
+    /**
+     * Tracks route changes manually (useful for custom routing)
+     * @param {string} route Route path
+     * @param {string} title Page title
+     */
+    trackRouteChange(route: string, title?: string): void;
+    /**
+     * Sets custom parameters that will be included in all subsequent events
+     * @param {Record<string, any>} parameters Custom parameters
+     */
+    setCustomParameters(parameters: Record<string, any>): void;
+    /**
+     * Clears custom parameters
+     */
+    clearCustomParameters(): void;
+    /**
+     * Tracks multiple events in batch
+     * @param {AnalyticsEvent[]} events Array of events to track
+     */
+    trackEvents(events: AnalyticsEvent[]): void;
+    /**
+     * Enables or disables analytics collection
+     * @param {boolean} enabled Whether to enable analytics collection
+     */
+    setAnalyticsEnabled(enabled: boolean): void;
+    /**
+     * Sets debug mode for analytics
+     * @param {boolean} enabled Whether to enable debug mode
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Gets current debug mode status
+     * @returns {boolean} Current debug mode status
+     */
+    getDebugMode(): boolean;
+    /**
+     * Cleans up analytics resources
+     */
+    cleanup(): void;
+}
+/**
+ * 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 declare const firekitAnalytics: FirekitAnalytics;
+export {};