svelte-firekit 0.1.9 → 0.2.1

package/README.md

@@ -1,502 +1,698 @@
-# Svelte Firebase Library
+# svelte-firekit
 
-A comprehensive, production-ready Firebase integration library for Svelte 5 applications. Built with reactive state management using Svelte 5 runes, providing a complete solution for authentication, Firestore, Storage, Realtime Database, Analytics, and more.
+A complete Firebase integration library for **Svelte 5** and **SvelteKit**. Built with Svelte 5 runes throughout, works in any Svelte 5 project — not just SvelteKit.
 
-## 🚀 Features
+- Firebase v12 (modular SDK)
+- Svelte 5 runes (`$state`, `$derived`) — fully reactive, no stores
+- SSR-safe — all services degrade gracefully on the server
+- Works without SvelteKit (`$app/*`, `$env/*` are never imported)
 
-- **Complete Firebase Integration** - All Firebase products supported
-- **Svelte 5 Runes** - Reactive state management with optimal performance
-- **TypeScript First** - Full type safety and excellent developer experience
-- **SSR Compatible** - Server-side rendering support
-- **Real-time Updates** - Live data synchronization across all services
-- **Authentication System** - Complete auth solution with multiple providers
-- **Advanced Querying** - Complex Firestore queries with type safety
-- **File Management** - Storage upload/download with progress tracking
-- **Presence System** - User online/offline tracking with geolocation
-- **Analytics Integration** - Comprehensive event tracking
-- **Error Handling** - Robust error management with retry mechanisms
-- **Performance Optimized** - Persistent cache, memory management, and optimizations
+---
 
-## 📦 Installation
+## Installation
 
-```bash
+```sh
 npm install svelte-firekit firebase
 ```
 
-## 🔧 Quick Setup
+---
+
+## Setup
 
-### 1. Environment Variables
+### 1. Initialize Firebase
 
-Create a `.env` file with your Firebase configuration:
+Call `initFirekit` once before your app renders — in your root layout or entry point:
 
-```dotenv
-PUBLIC_FIREBASE_API_KEY=your_api_key
-PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
-PUBLIC_FIREBASE_PROJECT_ID=your_project_id
-PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
-PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
-PUBLIC_FIREBASE_APP_ID=your_app_id
-PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id
+```ts
+import { initFirekit } from 'svelte-firekit';
+
+initFirekit({
+  apiKey: '...',
+  authDomain: '...',
+  projectId: '...',
+  storageBucket: '...',
+  messagingSenderId: '...',
+  appId: '...',
+  databaseURL: '...' // required for Realtime Database
+});
 ```
 
-### 2. Initialize Firebase
+### 2. Wrap your app
 
 ```svelte
-<script>
-	import { FirebaseApp } from 'svelte-firekit';
+<!-- +layout.svelte -->
+<script lang="ts">
+  import { FirebaseApp } from 'svelte-firekit';
+  import { firebaseConfig } from '$lib/firebase';
 </script>
 
-<FirebaseApp>
-	<!-- Your app content -->
+<FirebaseApp config={firebaseConfig}>
+  {@render children()}
 </FirebaseApp>
 ```
 
-### 3. Basic Usage
+`FirebaseApp` initializes Firebase, sets up Svelte context for all services, and optionally enables App Check:
 
 ```svelte
-<script>
-	import { firekitUser, firekitCollection, firekitDoc } from 'svelte-firekit';
-
-	// Reactive user state
-	const user = $derived(firekitUser.user);
-	const isAuthenticated = $derived(firekitUser.isAuthenticated);
-
-	// Reactive document
-	const userDoc = firekitDoc('users/123');
-
-	// Reactive collection
-	const posts = firekitCollection('posts', [
-		where('published', '==', true),
-		orderBy('createdAt', 'desc'),
-		limit(10)
-	]);
-</script>
-
-{#if isAuthenticated}
-	<h1>Welcome, {user?.displayName}!</h1>
-
-	{#if userDoc.loading}
-		<p>Loading user data...</p>
-	{:else if userDoc.data}
-		<p>Email: {userDoc.data.email}</p>
-	{/if}
-
-	<h2>Recent Posts</h2>
-	{#each posts.data as post}
-		<article>
-			<h3>{post.title}</h3>
-			<p>{post.content}</p>
-		</article>
-	{/each}
-{/if}
+<FirebaseApp {config} appCheckOptions={{ provider: new ReCaptchaEnterpriseProvider('SITE_KEY'), isTokenAutoRefreshEnabled: true }}>
+  {@render children()}
+</FirebaseApp>
 ```
 
-## 📚 Core Services
+---
 
-### Authentication
+## Authentication
 
-```typescript
+```ts
 import { firekitAuth, firekitUser } from 'svelte-firekit';
+```
 
-// Sign in methods
+### Sign in
+
+```ts
+// Email / password
 await firekitAuth.signInWithEmail('user@example.com', 'password');
+
+// OAuth (popup)
 await firekitAuth.signInWithGoogle();
+await firekitAuth.signInWithGithub();
 await firekitAuth.signInWithFacebook();
 await firekitAuth.signInWithApple();
+await firekitAuth.signInWithTwitter();
+await firekitAuth.signInWithMicrosoft();
+
+// OAuth (redirect — call getRedirectResult() on app load)
+await firekitAuth.signInWithGoogleRedirect();
+const result = await firekitAuth.getRedirectResult(); // null if no pending redirect
+
+// SAML / OIDC
+await firekitAuth.signInWithSAML('saml.my-provider');
+await firekitAuth.signInWithOIDC('oidc.my-provider', ['email', 'profile']);
+
+// Custom token (server-issued)
+await firekitAuth.signInWithCustomToken(token);
 
-// User registration
-await firekitAuth.registerWithEmail('user@example.com', 'password', 'John Doe');
+// Anonymous
+await firekitAuth.signInAnonymously();
 
-// Reactive user state
-const user = $derived(firekitUser.user);
-const isAuthenticated = $derived(firekitUser.isAuthenticated);
-const isEmailVerified = $derived(firekitUser.isEmailVerified);
+// Phone
+const { confirm } = await firekitAuth.signInWithPhoneNumber('+1234567890', 'recaptcha-container');
+await confirm('123456');
 ```
 
-### Firestore Documents
+### Registration & profile
+
+```ts
+await firekitAuth.registerWithEmail('user@example.com', 'password', 'Jane Doe');
+await firekitAuth.updateUserProfile({ displayName: 'Jane', photoURL: 'https://...' });
+await firekitAuth.updateEmail('new@example.com');
+await firekitAuth.updatePassword('newPassword', 'currentPassword');
+await firekitAuth.sendPasswordReset('user@example.com');
+await firekitAuth.sendEmailVerification();
+await firekitAuth.signOut();
+await firekitAuth.deleteAccount('currentPassword');
+```
 
-```typescript
-import { firekitDoc, firekitDocOnce } from 'svelte-firekit';
+### Multi-factor authentication (MFA)
 
-// Real-time document subscription
-const userDoc = firekitDoc<User>('users/123', {
-	name: 'Loading...',
-	email: ''
-});
+```ts
+// Enroll phone MFA
+const verificationId = await firekitAuth.startPhoneMFAEnrollment('+1234567890', 'recaptcha-container');
+await firekitAuth.completeMFAEnrollment(verificationId, '123456', 'My Phone');
 
-// One-time document fetch
-const userData = firekitDocOnce<User>('users/123');
+// Check enrolled factors
+const factors = firekitAuth.getMFAEnrolledFactors();
 
-// Access reactive state
-const isLoading = $derived(userDoc.loading);
-const userData = $derived(userDoc.data);
-const userError = $derived(userDoc.error);
+// Unenroll
+await firekitAuth.unenrollMFA(factors[0]);
 
-$effect(() => {
-	if (isLoading) console.log('Loading...');
-	if (userData) console.log('User:', userData);
-	if (userError) console.error('Error:', userError);
-});
+// Complete an MFA-required sign-in (catch the MultiFactorError first)
+try {
+  await firekitAuth.signInWithEmail(email, password);
+} catch (err) {
+  const resolver = firekitAuth.getMFAResolver(err);
+  const verificationId = await firekitAuth.startMFASignIn(resolver, 0, 'recaptcha-container');
+  const result = await firekitAuth.completeMFASignIn(resolver, verificationId, '123456');
+}
 ```
 
-### Firestore Collections
+### Reactive user state
 
-```typescript
-import { firekitCollection, where, orderBy, limit } from 'svelte-firekit';
+```svelte
+<script lang="ts">
+  import { firekitUser } from 'svelte-firekit';
+</script>
 
-// Simple collection
-const users = firekitCollection<User>('users');
+{#if firekitUser.loading}
+  <p>Loading...</p>
+{:else if firekitUser.isAuthenticated}
+  <p>Welcome, {firekitUser.user?.displayName}</p>
+{:else}
+  <p>Not signed in</p>
+{/if}
+```
 
-// With query constraints
-const activeUsers = firekitCollection<User>('users', [
-	where('active', '==', true),
-	orderBy('name'),
-	limit(10)
-]);
+| Property | Type | Description |
+|---|---|---|
+| `user` | `UserProfile \| null` | Current user profile |
+| `loading` | `boolean` | Auth state initializing |
+| `isAuthenticated` | `boolean` | Signed in and not anonymous |
+| `isAnonymous` | `boolean` | Anonymous session |
+| `initialized` | `boolean` | First auth state received |
+
+```ts
+// Wait for auth to initialize (useful for SSR / load functions)
+const user = await firekitUser.waitForAuth();
+```
 
-// Advanced options
-const paginatedUsers = firekitCollection<User>('users', {
-	pagination: { enabled: true, pageSize: 20 },
-	cache: { enabled: true, ttl: 300000 }
-});
+### Auth components
 
-// Access reactive state
-const usersData = $derived(users.data);
-const usersLoading = $derived(users.loading);
-const usersError = $derived(users.error);
+```svelte
+<SignedIn>  <p>Only shown when signed in</p>  </SignedIn>
+<SignedOut> <p>Only shown when signed out</p> </SignedOut>
 
-$effect(() => {
-	console.log('Users:', usersData);
-	console.log('Loading:', usersLoading);
-	console.log('Error:', usersError);
-});
+<!-- Route guard with redirect callback -->
+<AuthGuard requireAuth={true} onUnauthorized={() => goto('/login')}>
+  <p>Protected content</p>
+</AuthGuard>
+
+<!-- Custom guard with async checks (e.g. role verification) -->
+<CustomGuard
+  verificationChecks={[
+    async () => { const doc = await getDoc(...); return doc.data()?.role === 'admin'; }
+  ]}
+  onUnauthorized={() => goto('/403')}
+>
+  <p>Admin only</p>
+</CustomGuard>
 ```
 
-### Document Mutations
+---
 
-```typescript
-import { firekitDocMutations } from 'svelte-firekit';
+## Firestore
 
-// Create document
-const result = await firekitDocMutations.add(
-	'users',
-	{
-		name: 'John Doe',
-		email: 'john@example.com'
-	},
-	{
-		timestamps: true,
-		validate: true
-	}
-);
+### Reactive document
 
-// Update document
-await firekitDocMutations.update('users/123', {
-	name: 'Jane Doe'
-});
+```svelte
+<script lang="ts">
+  import { firekitDoc } from 'svelte-firekit';
 
-// Delete document
-await firekitDocMutations.delete('users/123');
+  const post = firekitDoc<Post>('posts/post-id');
+</script>
 
-// Batch operations
-const batchResult = await firekitDocMutations.batch([
-	{ type: 'create', path: 'users', data: userData },
-	{ type: 'update', path: 'profiles/123', data: profileUpdate }
-]);
+{#if post.loading}<p>Loading...</p>{/if}
+{#if post.data}<h1>{post.data.title}</h1>{/if}
 ```
 
-### Storage Management
+Using the `<Doc>` component:
 
-```typescript
-import { firekitDownloadUrl, firekitUploadTask, firekitStorageList } from 'svelte-firekit';
+```svelte
+<Doc path="posts/post-id">
+  {#snippet data(post)}
+    <h1>{post.title}</h1>
+  {/snippet}
+  {#snippet loading()}<p>Loading...</p>{/snippet}
+</Doc>
+```
 
-// Download URL
-const imageUrl = firekitDownloadUrl('images/photo.jpg');
-const downloadUrl = $derived(imageUrl.url);
+**Change path reactively:**
 
-// File upload with progress
-const upload = firekitUploadTask('uploads/file.pdf', file);
-const uploadProgress = $derived(upload.progress);
-const uploadCompleted = $derived(upload.completed);
-const uploadDownloadUrl = $derived(upload.downloadURL);
+```ts
+post.setPath('posts/other-id'); // tears down listener, re-subscribes
+```
 
-$effect(() => {
-	if (downloadUrl) console.log('Image URL:', downloadUrl);
-	console.log('Upload progress:', uploadProgress);
-	if (uploadCompleted) console.log('Download URL:', uploadDownloadUrl);
-});
+**One-time fetch:**
 
-// Storage listing
-const files = firekitStorageList('uploads');
-const fileItems = $derived(files.items);
-const filePrefixes = $derived(files.prefixes);
+```ts
+const post = firekitDocOnce<Post>('posts/post-id');
+```
 
-$effect(() => {
-	console.log('Files:', fileItems);
-	console.log('Folders:', filePrefixes);
-});
+### Reactive collection
+
+```svelte
+<script lang="ts">
+  import { firekitCollection } from 'svelte-firekit';
+  import { where, orderBy } from 'firebase/firestore';
+
+  const posts = firekitCollection<Post>('posts', [
+    where('published', '==', true),
+    orderBy('createdAt', 'desc')
+  ]);
+</script>
+
+{#each posts.data as post}
+  <p>{post.title}</p>
+{/each}
 ```
 
-### Realtime Database
+**Cursor-based pagination:**
 
-```typescript
-import { firekitRealtimeDB, firekitRealtimeList } from 'svelte-firekit';
+```ts
+await posts.setPagination(10);   // 10 per page, switches to one-time fetch
+await posts.nextPage();          // next page (replaces data)
+await posts.prevPage();          // previous page
+await posts.loadMore();          // append next page (infinite scroll)
+await posts.resetPagination();   // back to page 1
 
-// Single value
-const userStatus = firekitRealtimeDB<{ online: boolean }>('users/123/status');
+posts.currentPage  // number
+posts.hasMore      // boolean
+```
 
-// List data
-const messages = firekitRealtimeList<Message>('messages');
+**Fluent query builder:**
 
-// Access data
-const statusData = $derived(userStatus.data);
-const messagesList = $derived(messages.list);
+```ts
+import { FirekitQueryBuilder } from 'svelte-firekit';
 
-$effect(() => {
-	console.log('Status:', statusData);
-	console.log('Messages:', messagesList);
-});
+const constraints = new FirekitQueryBuilder<Post>()
+  .where('published', '==', true)
+  .orderBy('createdAt', 'desc')
+  .limit(20)
+  .build();
+```
 
-// Update data
-await userStatus.set({ online: true });
-await messages.push({ text: 'Hello', userId: '123' });
+**Collection group:**
+
+```ts
+const allComments = firekitCollectionGroup<Comment>('comments');
 ```
 
-### Presence System
+### Document mutations
 
-```typescript
-import { firekitPresence } from 'svelte-firekit';
+```ts
+import { firekitMutations } from 'svelte-firekit';
 
-// Initialize presence
-await firekitPresence.initialize(user, {
-	geolocation: {
-		enabled: true,
-		type: 'browser',
-		requireConsent: true
-	}
+await firekitMutations.add('posts', { title: 'Hello' });
+await firekitMutations.set('posts/id', { title: 'Hello' });
+await firekitMutations.update('posts/id', { title: 'Updated' });
+await firekitMutations.delete('posts/id');
+
+// Existence check
+const exists = await firekitMutations.exists('posts/id');
+
+// Field value helpers
+await firekitMutations.update('posts/id', {
+  views: firekitMutations.increment(1),
+  tags: firekitMutations.arrayUnion('svelte'),
+  draft: firekitMutations.deleteField(),
+  updatedAt: firekitMutations.serverTimestamp()
 });
 
-// Set presence status
-await firekitPresence.setPresence('online');
+// Batch (auto-chunked at 500)
+await firekitMutations.batchOps([
+  { type: 'set',    path: 'posts', id: 'a', data: { title: 'A' } },
+  { type: 'update', path: 'posts/b', data: { views: 1 } },
+  { type: 'delete', path: 'posts/c' }
+]);
 
-// Access reactive state
-const presenceStatus = $derived(firekitPresence.status);
-const presenceLocation = $derived(firekitPresence.location);
-const presenceSessions = $derived(firekitPresence.sessions);
+// Transaction
+await firekitMutations.transaction(async (tx) => {
+  const snap = await tx.get(ref);
+  tx.update(ref, { count: snap.data().count + 1 });
+});
 ```
 
-### Analytics
+### Timestamps and options
 
-```typescript
-import { firekitAnalytics } from 'svelte-firekit';
+```ts
+// Auto-adds createdAt/updatedAt
+await firekitMutations.add('posts', data, { timestamps: true, userId: uid });
 
-// Track custom events
-firekitAnalytics.trackEvent('button_click', {
-	button_name: 'signup',
-	page_location: '/home'
+// Retry on failure
+await firekitMutations.set('posts/id', data, {
+  retry: { enabled: true, maxAttempts: 3, baseDelay: 200, strategy: 'exponential' }
 });
+```
 
-// Track purchases
-firekitAnalytics.trackPurchase({
-	transaction_id: 'T12345',
-	value: 29.99,
-	currency: 'USD',
-	items: [{ item_id: 'prod_123', item_name: 'Premium Plan' }]
-});
+### Bundles
 
-// Set user properties
-firekitAnalytics.setUserProperties({
-	user_type: 'premium',
-	subscription_plan: 'pro'
-});
+```ts
+import { loadFirestoreBundle, getNamedQuery } from 'svelte-firekit';
+import { getDocs } from 'firebase/firestore';
+
+const res = await fetch('/bundles/featured.bundle');
+await loadFirestoreBundle(res.body!);
+
+const q = await getNamedQuery<Post>('featured-posts');
+if (q) {
+  const snap = await getDocs(q);
+}
 ```
 
-## 🧩 Components
+---
 
-### Authentication Components
+## Realtime Database
 
 ```svelte
-<script>
-	import { AuthGuard, SignedIn, SignedOut } from 'svelte-firekit';
+<script lang="ts">
+  import { firekitNode, firekitNodeList } from 'svelte-firekit';
+
+  const counter = firekitNode<number>('counters/visitors');
+  const messages = firekitNodeList<Message>('chat/messages');
 </script>
 
-<!-- Route protection -->
-<AuthGuard requireAuth={true} redirectTo="/login">
-	<h1>Protected Content</h1>
-</AuthGuard>
+<p>Visitors: {counter.data}</p>
 
-<!-- Conditional rendering -->
-<SignedIn>
-	<h1>Welcome back!</h1>
-</SignedIn>
+{#each messages.list as msg}
+  <p>{msg.text}</p>
+{/each}
+```
 
-<SignedOut>
-	<h1>Please sign in</h1>
-</SignedOut>
+```ts
+await counter.set(42);
+await counter.update({ count: 10 });
+await messages.push({ text: 'Hello!', userId: uid });
+await messages.remove();
+const once = await messages.fetchOnce();
 ```
 
-### Data Components
+Using the `<Node>` component:
 
 ```svelte
-<script>
-	import { Doc, Collection } from 'svelte-firekit';
+<Node path="chat/messages">
+  {#snippet data(messages)}<p>{messages}</p>{/snippet}
+</Node>
+```
+
+---
+
+## Firebase Storage
+
+```svelte
+<script lang="ts">
+  import { firekitDownloadUrl, firekitUploadTask } from 'svelte-firekit';
+
+  const avatar = firekitDownloadUrl('images/avatar.jpg');
+  let file: File;
+  $: upload = file ? firekitUploadTask('uploads/' + file.name, file) : null;
 </script>
 
-<!-- Document component -->
-<Doc ref="users/123" let:data let:ref let:firestore>
-	<h1>{data.name}</h1>
-	<p>{data.email}</p>
-</Doc>
+{#if avatar.url}<img src={avatar.url} alt="avatar" />{/if}
+
+{#if upload}
+  <progress value={upload.progress} max={100} />
+  {#if upload.downloadURL}<img src={upload.downloadURL} />{/if}
+{/if}
+```
+
+```ts
+import { deleteFile, getFileMetadata, updateFileMetadata } from 'svelte-firekit';
 
-<!-- Collection component -->
-<Collection ref="posts" let:data let:ref let:firestore let:count>
-	<h1>Posts ({count})</h1>
-	{#each data as post}
-		<article>
-			<h2>{post.title}</h2>
-			<p>{post.content}</p>
-		</article>
-	{/each}
-</Collection>
+await deleteFile('images/old.jpg');
+const meta = await getFileMetadata('images/avatar.jpg');
+await updateFileMetadata('images/avatar.jpg', {
+  contentType: 'image/webp',
+  customMetadata: { uploadedBy: uid }
+});
 ```
 
-### Storage Components
+List files:
 
 ```svelte
-<script>
-	import { StorageList, DownloadURL, UploadTask } from 'svelte-firekit';
+<script lang="ts">
+  import { firekitStorageList } from 'svelte-firekit';
+  const dir = firekitStorageList('uploads/2024');
 </script>
+{#each dir.items as item}<p>{item.name}</p>{/each}
+```
+
+Using the `<DownloadURL>` and `<UploadTask>` components:
 
-<!-- Storage listing -->
-<StorageList path="uploads" let:items let:prefixes>
-	<h2>Files</h2>
-	{#each items as item}
-		<p>{item.name}</p>
-	{/each}
-
-	<h2>Folders</h2>
-	{#each prefixes as prefix}
-		<p>{prefix.name}</p>
-	{/each}
-</StorageList>
-
-<!-- Download URL -->
-<DownloadURL path="images/photo.jpg" let:url let:loading let:error>
-	{#if loading}
-		<p>Loading image...</p>
-	{:else if url}
-		<img src={url} alt="Photo" />
-	{:else if error}
-		<p>Error: {error.message}</p>
-	{/if}
+```svelte
+<DownloadURL path="images/avatar.jpg">
+  {#snippet data(url)}<img src={url} />{/snippet}
 </DownloadURL>
 
-<!-- Upload with progress -->
-<UploadTask path="uploads/file.pdf" file={selectedFile} let:progress let:completed let:error>
-	{#if !completed}
-		<div class="progress-bar">
-			<div class="progress" style="width: {progress}%"></div>
-		</div>
-		<p>{progress}% uploaded</p>
-	{:else}
-		<p>Upload complete!</p>
-	{/if}
+<UploadTask path="uploads/file.jpg" {file}>
+  {#snippet data({ progress, downloadURL })}<progress value={progress} max={100} />{/snippet}
 </UploadTask>
 ```
 
-## 🎯 Best Practices
+---
 
-### 1. Use Reactive State
+## Cloud Functions
 
-```typescript
-// ✅ Good - Reactive state
-const user = $derived(firekitUser.user);
-const isAuthenticated = $derived(firekitUser.isAuthenticated);
+```ts
+import { firekitCallable, firekitCallableFromURL } from 'svelte-firekit';
 
-// ❌ Avoid - Direct service calls in templates
-const user = firekitUser.getCurrentUser();
+const sendWelcome = firekitCallable<{ userId: string }, { sent: boolean }>('sendWelcomeEmail');
+const result = await sendWelcome.call({ userId: 'abc' });
+// sendWelcome.loading, sendWelcome.error, sendWelcome.result
+
+const fn = firekitCallableFromURL<Input, Output>('https://region-project.cloudfunctions.net/fn');
 ```
 
-### 2. Handle Loading States
+---
 
-```svelte
-{#if userDoc.loading}
-	<LoadingSpinner />
-{:else if userDoc.error}
-	<ErrorMessage error={userDoc.error} />
-{:else if userDoc.data}
-	<UserProfile user={userDoc.data} />
-{/if}
+## Firebase AI (Gemini)
+
+```ts
+import { firekitGenerate, firekitStream, firekitChat } from 'svelte-firekit';
+
+// One-shot
+const gen = firekitGenerate({ model: 'gemini-2.0-flash' });
+await gen.generate('Summarize: ...');
+// gen.text, gen.loading, gen.error
+
+// Streaming
+const stream = firekitStream({ model: 'gemini-2.0-flash' });
+await stream.generate('Write a poem about Svelte.');
+// stream.text updates token-by-token, stream.streaming
+
+// Multi-turn chat
+const chat = firekitChat({ model: 'gemini-2.0-flash' });
+await chat.send('Hello!');
+await chat.send('Tell me more.');
+// chat.history, chat.pendingText, chat.streaming
 ```
 
-### 3. Clean Up Subscriptions
+Switch between Google AI and Vertex AI:
 
-```typescript
-import { onDestroy } from 'svelte';
+```ts
+import { GoogleAIBackend, VertexAIBackend } from 'svelte-firekit';
+
+const gen = firekitGenerate({ backend: 'vertexai', model: 'gemini-2.0-flash' });
+```
 
-const userDoc = firekitDoc('users/123');
+Content helpers:
 
-onDestroy(() => {
-	userDoc.dispose();
+```ts
+import { textPart, imagePart, imageUrlPart } from 'svelte-firekit';
+
+await gen.generate([textPart('Describe this image:'), imagePart(base64)]);
+```
+
+---
+
+## Remote Config
+
+```ts
+import { firekitRemoteConfig } from 'svelte-firekit';
+
+const rc = firekitRemoteConfig({
+  defaults: { welcomeMessage: 'Hello!', featureEnabled: false },
+  minimumFetchIntervalMs: 3_600_000,
+  realtime: true // subscribe to live config updates
 });
+
+await rc.fetchAndActivate();
+
+const msg = rc.getString('welcomeMessage');
+const flag = rc.getBoolean('featureEnabled');
+const count = rc.getNumber('itemsPerPage', 10);
 ```
 
-### 4. Use Type Safety
+---
+
+## Performance Monitoring
 
-```typescript
-interface User {
-	id: string;
-	name: string;
-	email: string;
-	active: boolean;
-}
+```ts
+import { firekitPerformance } from 'svelte-firekit';
+
+// Simple trace
+const stop = await firekitPerformance.startTrace('load-dashboard');
+// ... work ...
+stop();
 
-const userDoc = firekitDoc<User>('users/123');
-const users = firekitCollection<User>('users');
+// Timed block
+const duration = await firekitPerformance.measure('render-posts', async () => {
+  await loadPosts();
+});
 ```
 
-### 5. Optimize Queries
+---
+
+## Analytics
 
-```typescript
-// ✅ Good - Specific queries
-const activeUsers = firekitCollection('users', where('active', '==', true), limit(10));
+```ts
+import { firekitAnalytics } from 'svelte-firekit';
 
-// ❌ Avoid - Fetching all data
-const allUsers = firekitCollection('users');
+await firekitAnalytics.logEvent('purchase', { value: 9.99, currency: 'USD' });
+await firekitAnalytics.setUserId('uid123');
+await firekitAnalytics.setUserProperties({ plan: 'pro' });
+await firekitAnalytics.logScreenView('Dashboard');
 ```
 
-## 📚 Documentation
+---
 
-For complete documentation, examples, and API reference, visit:
+## Messaging (FCM)
 
-**[https://sveltefirekit.com](https://sveltefirekit.com)**
+```ts
+import { firekitMessaging } from 'svelte-firekit';
 
-### Key Sections:
+const token = await firekitMessaging.requestPermission('YOUR_VAPID_KEY');
+// firekitMessaging.token, firekitMessaging.permission, firekitMessaging.supported
 
-- [Installation Guide](https://sveltefirekit.com/installation) - Complete setup guide
-- [Authentication](https://sveltefirekit.com/auth) - User authentication and management
-- [Firestore Collections](https://sveltefirekit.com/collections) - Real-time data management
-- [Document Operations](https://sveltefirekit.com/documents) - Individual document handling
-- [File Storage](https://sveltefirekit.com/storage) - File upload and management
-- [Realtime Database](https://sveltefirekit.com/realtime) - Real-time data synchronization
-- [Analytics](https://sveltefirekit.com/analytics) - User and event tracking
-- [Components](https://sveltefirekit.com/components) - Pre-built Svelte components
-- [Presence System](https://sveltefirekit.com/presence) - User online/offline tracking
+// Listen for foreground messages
+const unsub = await firekitMessaging.onMessage((payload) => {
+  console.log(payload.notification?.title);
+});
+```
 
-## 🤝 Contributing
+---
+
+## In-App Messaging
+
+```ts
+import { firekitInAppMessaging } from 'svelte-firekit';
+
+// Suppress during critical flows (e.g. checkout)
+firekitInAppMessaging.suppress();
+// ... complete checkout ...
+firekitInAppMessaging.unsuppress();
+
+// firekitInAppMessaging.suppressed  (reactive boolean)
+// firekitInAppMessaging.supported
+```
+
+---
+
+## Presence
+
+```ts
+import { firekitPresence } from 'svelte-firekit';
+
+await firekitPresence.initialize(user, {
+  sessionTTL: 30 * 60_000,
+  trackDeviceInfo: true,
+  geolocation: { enabled: true, type: 'browser', requireConsent: true }
+});
+
+await firekitPresence.setPresence('away');
+
+const stats = firekitPresence.getStats();
+// stats.onlineSessions, stats.totalSessions, stats.uniqueDevices
+
+await firekitPresence.dispose();
+```
+
+---
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+## App Check
 
-## 📄 License
+```svelte
+<script>
+  import { ReCaptchaEnterpriseProvider } from 'svelte-firekit';
+</script>
+
+<FirebaseApp
+  {config}
+  appCheckOptions={{
+    provider: new ReCaptchaEnterpriseProvider('SITE_KEY'),
+    isTokenAutoRefreshEnabled: true
+  }}
+>
+  {@render children()}
+</FirebaseApp>
+```
+
+---
+
+## Context helpers
+
+After `<FirebaseApp>`, you can retrieve any raw Firebase service instance from Svelte context:
 
-MIT License - see [LICENSE](LICENSE) for details.
+```ts
+import {
+  getFirestoreContext,
+  getAuthContext,
+  getStorageContext,
+  getRTDBContext,
+  getFunctionsContext,
+  getAppCheckContext
+} from 'svelte-firekit';
 
-## 🆘 Support
+// Inside a component:
+const db = getFirestoreContext();
+const auth = getAuthContext();
+```
+
+---
+
+## SSR
+
+All services return safe defaults on the server (`loading: false`, empty arrays, `null` data) — no Firebase network calls happen during SSR. The only exception is `firekitPresence`, which is browser-only and will throw if you call `initialize()` on the server.
 
-- [Documentation](https://sveltefirekit.com)
-- [GitHub Issues](https://github.com/code-gio/svelte-firekit/issues)
-- [Discussions](https://github.com/code-gio/svelte-firekit/discussions)
+```ts
+// Safe in load functions / SSR — resolves immediately on server
+const user = await firekitUser.waitForAuth();
+const posts = firekitCollection<Post>('posts');
+const data = await posts.waitForReady();
+```
 
 ---
 
-**Built with ❤️ for the Svelte community**
+## API Reference
+
+### Services
+
+| Import | Description |
+|---|---|
+| `firekitAuth` | Auth operations (sign-in, register, MFA, SAML/OIDC, redirect) |
+| `firekitUser` | Reactive current user state |
+| `firekitMutations` | Firestore CRUD, batch, transactions |
+| `firekitPresence` | User presence tracking via RTDB |
+| `firekitRemoteConfig()` | Remote Config per-instance |
+| `firekitPerformance` | Performance Monitoring traces |
+| `firekitAnalytics` | Analytics event logging |
+| `firekitMessaging` | Firebase Cloud Messaging |
+| `firekitInAppMessaging` | In-App Messaging suppression control |
+| `firekitAppCheck` | App Check initialization |
+
+### Reactive classes
+
+| Import | Description |
+|---|---|
+| `FirekitDoc` / `firekitDoc()` | Reactive Firestore document |
+| `FirekitCollection` / `firekitCollection()` | Reactive Firestore collection with pagination |
+| `FirekitCollectionGroup` / `firekitCollectionGroup()` | Collection group query |
+| `FirekitNode` / `firekitNode()` | Reactive RTDB node |
+| `FirekitNodeList` / `firekitNodeList()` | Reactive RTDB list |
+| `FirekitDownloadUrl` / `firekitDownloadUrl()` | Reactive Storage download URL |
+| `FirekitStorageList` / `firekitStorageList()` | Reactive Storage directory listing |
+| `FirekitUploadTask` / `firekitUploadTask()` | Reactive resumable upload |
+| `FirekitGenerate` / `firekitGenerate()` | One-shot AI generation |
+| `FirekitStream` / `firekitStream()` | Streaming AI generation |
+| `FirekitChat` / `firekitChat()` | Multi-turn AI chat session |
+| `FirekitCallable` / `firekitCallable()` | Typed Cloud Function caller |
+| `FirekitCallableFromURL` / `firekitCallableFromURL()` | Cloud Function by URL |
+
+### Components
+
+| Component | Description |
+|---|---|
+| `<FirebaseApp>` | Root provider, initializes Firebase |
+| `<SignedIn>` | Render when authenticated |
+| `<SignedOut>` | Render when not authenticated |
+| `<AuthGuard>` | Redirect unauthenticated users |
+| `<CustomGuard>` | Async role/permission guard |
+| `<Doc>` | Reactive Firestore document |
+| `<Collection>` | Reactive Firestore collection |
+| `<Node>` | Reactive RTDB node |
+| `<DownloadURL>` | Storage download URL |
+| `<UploadTask>` | Resumable file upload |
+
+---
+
+## License
+
+MIT © Giovani Rodriguez