svelte-firekit 0.2.5 → 0.2.6

package/README.md

@@ -7,6 +7,8 @@ A complete Firebase integration library for **Svelte 5** and **SvelteKit**. Buil
 - SSR-safe — all services degrade gracefully on the server
 - Works without SvelteKit (`$app/*`, `$env/*` are never imported)
 
+**Documentation:** [sveltefirekit.com](https://sveltefirekit.com/)
+
 ---
 
 ## Installation
@@ -162,28 +164,41 @@ try {
 
 ```ts
 // Wait for auth to initialize (useful for SSR / load functions)
-const user = await firekitUser.waitForAuth();
+const user = await firekitUser.waitForAuth();        // 10s timeout (default)
+const user = await firekitUser.waitForAuth(5_000);   // custom timeout in ms
 ```
 
 ### Auth components
 
+All auth components wait for Firebase Auth to initialize before rendering. Use the optional `fallback` snippet to show a loading state.
+
 ```svelte
-<SignedIn>  <p>Only shown when signed in</p>  </SignedIn>
-<SignedOut> <p>Only shown when signed out</p> </SignedOut>
+<SignedIn>
+  {#snippet children(user)}<p>Welcome, {user.displayName}</p>{/snippet}
+  {#snippet fallback()}<p>Loading...</p>{/snippet}
+</SignedIn>
+
+<SignedOut>
+  {#snippet children(signIn)}<button onclick={signIn}>Sign in</button>{/snippet}
+  {#snippet fallback()}<p>Loading...</p>{/snippet}
+</SignedOut>
 
 <!-- Route guard with redirect callback -->
 <AuthGuard requireAuth={true} onUnauthorized={() => goto('/login')}>
-  <p>Protected content</p>
+  {#snippet children(user, signOut)}<p>Protected content</p>{/snippet}
+  {#snippet fallback()}<p>Loading...</p>{/snippet}
 </AuthGuard>
 
 <!-- Custom guard with async checks (e.g. role verification) -->
 <CustomGuard
   verificationChecks={[
-    async () => { const doc = await getDoc(...); return doc.data()?.role === 'admin'; }
+    async (user) => user.emailVerified,
+    async (user) => { const doc = await getDoc(...); return doc.data()?.role === 'admin'; }
   ]}
   onUnauthorized={() => goto('/403')}
 >
-  <p>Admin only</p>
+  {#snippet children(user, signOut)}<p>Admin only</p>{/snippet}
+  {#snippet fallback()}<p>Checking permissions...</p>{/snippet}
 </CustomGuard>
 ```
 
@@ -415,16 +430,44 @@ List files:
 {#each dir.items as item}<p>{item.name}</p>{/each}
 ```
 
-Using the `<DownloadURL>` and `<UploadTask>` components:
+### File upload validation
+
+Validate files before uploading — checks size, MIME type, and image dimensions.
+
+```ts
+import { validateFile } from 'svelte-firekit';
+
+const result = await validateFile(file, {
+  maxSize: 5 * 1024 * 1024,          // 5 MB
+  accept: ['image/png', 'image/jpeg', '.webp'],
+  maxWidth: 2048,
+  maxHeight: 2048,
+  minWidth: 100
+});
+
+if (!result.valid) {
+  result.errors.forEach((e) => console.log(e.code, e.message));
+}
+```
+
+The `<UploadTask>` component supports an optional `validate` prop and `invalid` snippet:
+
+```svelte
+<UploadTask path="uploads/{file.name}" {file} validate={{ maxSize: 5_000_000, accept: ['image/*'] }}>
+  {#snippet uploading(task)}<progress value={task.progress} max={100} />{/snippet}
+  {#snippet complete(url)}<img src={url} alt="uploaded" />{/snippet}
+  {#snippet invalid(result)}
+    {#each result.errors as err}<p class="error">{err.message}</p>{/each}
+  {/snippet}
+</UploadTask>
+```
+
+Using the `<DownloadURL>` component:
 
 ```svelte
 <DownloadURL path="images/avatar.jpg">
   {#snippet data(url)}<img src={url} />{/snippet}
 </DownloadURL>
-
-<UploadTask path="uploads/file.jpg" {file}>
-  {#snippet data({ progress, downloadURL })}<progress value={progress} max={100} />{/snippet}
-</UploadTask>
 ```
 
 ---
@@ -566,6 +609,44 @@ firekitInAppMessaging.unsuppress();
 
 ---
 
+## Network / Offline Status
+
+Track browser connectivity and Firestore sync state reactively.
+
+```svelte
+<script lang="ts">
+  import { firekitNetwork } from 'svelte-firekit';
+</script>
+
+{#if !firekitNetwork.online}
+  <p>You're offline. Changes will sync when reconnected.</p>
+{:else if firekitNetwork.hasPendingWrites}
+  <p>Saving...</p>
+{:else}
+  <p>All changes saved</p>
+{/if}
+```
+
+Using the `<NetworkStatus>` component:
+
+```svelte
+<NetworkStatus>
+  {#snippet online()}<span class="green">Connected</span>{/snippet}
+  {#snippet offline()}<span class="red">Offline</span>{/snippet}
+  {#snippet pending()}<span>Saving...</span>{/snippet}
+</NetworkStatus>
+```
+
+Manual control:
+
+```ts
+await firekitNetwork.goOffline();   // force offline mode
+await firekitNetwork.goOnline();    // reconnect
+firekitNetwork.trackWrite();        // mark a pending write
+```
+
+---
+
 ## Presence
 
 ```ts
@@ -656,6 +737,7 @@ const data = await posts.waitForReady();
 | `firekitAnalytics` | Analytics event logging |
 | `firekitMessaging` | Firebase Cloud Messaging |
 | `firekitInAppMessaging` | In-App Messaging suppression control |
+| `firekitNetwork` | Reactive network/offline status |
 | `firekitAppCheck` | App Check initialization |
 
 ### Reactive classes
@@ -676,6 +758,12 @@ const data = await posts.waitForReady();
 | `FirekitCallable` / `firekitCallable()` | Typed Cloud Function caller |
 | `FirekitCallableFromURL` / `firekitCallableFromURL()` | Cloud Function by URL |
 
+### Utilities
+
+| Import | Description |
+|---|---|
+| `validateFile()` | Pre-upload file validation (size, type, dimensions) |
+
 ### Components
 
 | Component | Description |
@@ -689,7 +777,8 @@ const data = await posts.waitForReady();
 | `<Collection>` | Reactive Firestore collection |
 | `<Node>` | Reactive RTDB node |
 | `<DownloadURL>` | Storage download URL |
-| `<UploadTask>` | Resumable file upload |
+| `<UploadTask>` | Resumable file upload with optional validation |
+| `<NetworkStatus>` | Network/sync status display |
 
 ---
 

package/dist/components/NetworkStatus.svelte

@@ -0,0 +1,37 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import { firekitNetwork } from '../services/network.svelte.js';
+
+	/**
+	 * Renders snippets based on network/sync status.
+	 *
+	 * @example
+	 * ```svelte
+	 * <NetworkStatus>
+	 *   {#snippet online()}<span class="dot green" />{/snippet}
+	 *   {#snippet offline()}<span class="dot red">Offline</span>{/snippet}
+	 *   {#snippet pending()}<span>Saving...</span>{/snippet}
+	 * </NetworkStatus>
+	 * ```
+	 */
+	let {
+		online: onlineSnippet,
+		offline: offlineSnippet,
+		pending: pendingSnippet
+	}: {
+		/** Rendered when online and all writes are synced. */
+		online?: Snippet;
+		/** Rendered when the browser is offline. */
+		offline?: Snippet;
+		/** Rendered when there are pending Firestore writes. */
+		pending?: Snippet;
+	} = $props();
+</script>
+
+{#if !firekitNetwork.online && offlineSnippet}
+	{@render offlineSnippet()}
+{:else if firekitNetwork.hasPendingWrites && pendingSnippet}
+	{@render pendingSnippet()}
+{:else if firekitNetwork.online && onlineSnippet}
+	{@render onlineSnippet()}
+{/if}

package/dist/components/NetworkStatus.svelte.d.ts

@@ -0,0 +1,12 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    /** Rendered when online and all writes are synced. */
+    online?: Snippet;
+    /** Rendered when the browser is offline. */
+    offline?: Snippet;
+    /** Rendered when there are pending Firestore writes. */
+    pending?: Snippet;
+};
+declare const NetworkStatus: import("svelte").Component<$$ComponentProps, {}, "">;
+type NetworkStatus = ReturnType<typeof NetworkStatus>;
+export default NetworkStatus;

package/dist/components/UploadTask.svelte

@@ -2,16 +2,20 @@
 	import type { Snippet } from 'svelte';
 	import type { UploadMetadata } from 'firebase/storage';
 	import { FirekitUploadTask, type UploadState } from '../services/storage.svelte.js';
+	import { validateFile } from '../utils/validation.js';
+	import type { FileValidationOptions, FileValidationResult } from '../types/storage.js';
 
 	/**
 	 * Manages a Firebase Storage upload with reactive progress.
-	 *
-	 * Exposes upload controls (pause, resume, cancel) and progress state
-	 * to the `uploading` snippet.
+	 * Optionally validates the file before uploading.
 	 *
 	 * @example
 	 * ```svelte
-	 * <UploadTask path="uploads/{file.name}" {file}>
+	 * <UploadTask
+	 *   path="uploads/{file.name}"
+	 *   {file}
+	 *   validate={{ maxSize: 5 * 1024 * 1024, accept: ['image/*'] }}
+	 * >
 	 *   {#snippet uploading(task)}
 	 *     <progress value={task.progress} max={100} />
 	 *     <button onclick={task.pause}>Pause</button>
@@ -19,6 +23,11 @@
 	 *   {#snippet complete(url)}
 	 *     <img src={url} alt="uploaded" />
 	 *   {/snippet}
+	 *   {#snippet invalid(result)}
+	 *     {#each result.errors as err}
+	 *       <p class="error">{err.message}</p>
+	 *     {/each}
+	 *   {/snippet}
 	 * </UploadTask>
 	 * ```
 	 */
@@ -26,9 +35,11 @@
 		path,
 		file,
 		metadata,
+		validate,
 		uploading: uploadingSnippet,
 		complete: completeSnippet,
-		error: errorSnippet
+		error: errorSnippet,
+		invalid: invalidSnippet
 	}: {
 		/** Storage destination path. */
 		path: string;
@@ -36,6 +47,8 @@
 		file: Blob | Uint8Array | ArrayBuffer;
 		/** Optional upload metadata (content type, custom metadata, etc.). */
 		metadata?: UploadMetadata;
+		/** Optional validation rules. Only applied when `file` is a File instance. */
+		validate?: FileValidationOptions;
 		/**
 		 * Rendered while the upload is active.
 		 * Receives an object with `{ progress, state, bytesTransferred, totalBytes, pause, resume, cancel }`.
@@ -51,25 +64,55 @@
 		}]>;
 		/** Rendered after a successful upload. Receives the download URL. */
 		complete?: Snippet<[string]>;
-		/** Rendered on error. */
+		/** Rendered on upload error. */
 		error?: Snippet<[Error]>;
+		/** Rendered when validation fails. Receives the validation result with errors. */
+		invalid?: Snippet<[FileValidationResult]>;
 	} = $props();
 
-	const task = new FirekitUploadTask(path, file, metadata);
+	let validationResult = $state<FileValidationResult | null>(null);
+	let task = $state<FirekitUploadTask | null>(null);
+	let started = false;
+
+	// Run validation (if configured) then start upload.
+	// Uses $effect so Svelte properly tracks the prop references.
+	$effect(() => {
+		if (started) return;
+		started = true;
+
+		if (validate && file instanceof File) {
+			validateFile(file, validate).then((result) => {
+				validationResult = result;
+				if (result.valid) {
+					task = new FirekitUploadTask(path, file as Blob, metadata);
+				}
+			});
+		} else {
+			task = new FirekitUploadTask(path, file, metadata);
+		}
+	});
 </script>
 
-{#if task.error && errorSnippet}
-	{@render errorSnippet(task.error)}
-{:else if task.completed && completeSnippet && task.downloadURL}
-	{@render completeSnippet(task.downloadURL)}
-{:else if task.active && uploadingSnippet}
-	{@render uploadingSnippet({
-		progress: task.progress,
-		state: task.state,
-		bytesTransferred: task.bytesTransferred,
-		totalBytes: task.totalBytes,
-		pause: () => task.pause(),
-		resume: () => task.resume(),
-		cancel: () => task.cancel()
-	})}
+{#if validationResult && !validationResult.valid}
+	{#if invalidSnippet}
+		{@render invalidSnippet(validationResult)}
+	{:else if errorSnippet}
+		{@render errorSnippet(new Error(validationResult.errors.map((e) => e.message).join('; ')))}
+	{/if}
+{:else if task}
+	{#if task.error && errorSnippet}
+		{@render errorSnippet(task.error)}
+	{:else if task.completed && completeSnippet && task.downloadURL}
+		{@render completeSnippet(task.downloadURL)}
+	{:else if task.active && uploadingSnippet}
+		{@render uploadingSnippet({
+			progress: task.progress,
+			state: task.state,
+			bytesTransferred: task.bytesTransferred,
+			totalBytes: task.totalBytes,
+			pause: () => task!.pause(),
+			resume: () => task!.resume(),
+			cancel: () => task!.cancel()
+		})}
+	{/if}
 {/if}

package/dist/components/UploadTask.svelte.d.ts

@@ -1,6 +1,7 @@
 import type { Snippet } from 'svelte';
 import type { UploadMetadata } from 'firebase/storage';
 import { type UploadState } from '../services/storage.svelte.js';
+import type { FileValidationOptions, FileValidationResult } from '../types/storage.js';
 type $$ComponentProps = {
     /** Storage destination path. */
     path: string;
@@ -8,6 +9,8 @@ type $$ComponentProps = {
     file: Blob | Uint8Array | ArrayBuffer;
     /** Optional upload metadata (content type, custom metadata, etc.). */
     metadata?: UploadMetadata;
+    /** Optional validation rules. Only applied when `file` is a File instance. */
+    validate?: FileValidationOptions;
     /**
      * Rendered while the upload is active.
      * Receives an object with `{ progress, state, bytesTransferred, totalBytes, pause, resume, cancel }`.
@@ -25,8 +28,10 @@ type $$ComponentProps = {
     ]>;
     /** Rendered after a successful upload. Receives the download URL. */
     complete?: Snippet<[string]>;
-    /** Rendered on error. */
+    /** Rendered on upload error. */
     error?: Snippet<[Error]>;
+    /** Rendered when validation fails. Receives the validation result with errors. */
+    invalid?: Snippet<[FileValidationResult]>;
 };
 declare const UploadTask: import("svelte").Component<$$ComponentProps, {}, "">;
 type UploadTask = ReturnType<typeof UploadTask>;

package/dist/index.d.ts

@@ -20,6 +20,7 @@ export { FirekitRemoteConfig, firekitRemoteConfig, type FirekitRemoteConfigOptio
 export { firekitPerformance, type PerformanceTrace } from './services/performance.js';
 export { firekitMessaging, type MessagePayload } from './services/messaging.svelte.js';
 export { firekitAnalytics } from './services/analytics.js';
+export { firekitNetwork } from './services/network.svelte.js';
 export { loadFirestoreBundle, getNamedQuery } from './services/bundles.js';
 export { default as FirebaseApp } from './components/FirebaseApp.svelte';
 export { default as SignedIn } from './components/SignedIn.svelte';
@@ -31,5 +32,6 @@ export { default as Collection } from './components/Collection.svelte';
 export { default as Node } from './components/Node.svelte';
 export { default as DownloadURL } from './components/DownloadURL.svelte';
 export { default as UploadTask } from './components/UploadTask.svelte';
+export { default as NetworkStatus } from './components/NetworkStatus.svelte';
 export * from './types/index.js';
 export * from './utils/index.js';

package/dist/index.js

@@ -32,6 +32,8 @@ export { firekitPerformance } from './services/performance.js';
 export { firekitMessaging } from './services/messaging.svelte.js';
 // ─── Analytics ────────────────────────────────────────────────────────────────
 export { firekitAnalytics } from './services/analytics.js';
+// ─── Network / Offline ───────────────────────────────────────────────────────
+export { firekitNetwork } from './services/network.svelte.js';
 // ─── Firestore bundles ────────────────────────────────────────────────────────
 export { loadFirestoreBundle, getNamedQuery } from './services/bundles.js';
 // ─── Components ──────────────────────────────────────────────────────────────
@@ -45,6 +47,7 @@ export { default as Collection } from './components/Collection.svelte';
 export { default as Node } from './components/Node.svelte';
 export { default as DownloadURL } from './components/DownloadURL.svelte';
 export { default as UploadTask } from './components/UploadTask.svelte';
+export { default as NetworkStatus } from './components/NetworkStatus.svelte';
 // ─── Types ───────────────────────────────────────────────────────────────────
 export * from './types/index.js';
 // ─── Utilities ───────────────────────────────────────────────────────────────

package/dist/services/network.svelte.d.ts

@@ -0,0 +1,71 @@
+import { NetworkError } from '../types/network.js';
+/**
+ * Reactive network/offline status store.
+ *
+ * Tracks browser connectivity, Firestore sync state, and pending writes.
+ * Provides manual control to go offline/online.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { firekitNetwork } from 'svelte-firekit';
+ * </script>
+ *
+ * {#if !firekitNetwork.online}
+ *   <p>You're offline. Changes will sync when reconnected.</p>
+ * {/if}
+ *
+ * {#if firekitNetwork.hasPendingWrites}
+ *   <p>Saving...</p>
+ * {:else}
+ *   <p>All changes saved</p>
+ * {/if}
+ * ```
+ */
+declare class FirekitNetwork {
+    private static instance;
+    private _online;
+    private _synced;
+    private _hasPendingWrites;
+    private _initialized;
+    private _error;
+    private _firestoreEnabled;
+    private _listening;
+    private _db;
+    private _syncUnsub;
+    private _onlineHandler;
+    private _offlineHandler;
+    private constructor();
+    static getInstance(): FirekitNetwork;
+    private ensureListening;
+    /**
+     * Called by FirebaseApp or lazily on first getter access.
+     * Safe to call multiple times.
+     */
+    initialize(): void;
+    /** Whether the browser has network connectivity. */
+    get online(): boolean;
+    /** Whether all Firestore snapshots are in sync with the server. */
+    get synced(): boolean;
+    /** Whether there are unconfirmed Firestore writes. */
+    get hasPendingWrites(): boolean;
+    /** Whether the network store has been initialized. */
+    get initialized(): boolean;
+    /** Last error from network operations. */
+    get error(): NetworkError | null;
+    /** Whether Firestore network is currently enabled. */
+    get firestoreEnabled(): boolean;
+    /**
+     * Call this when you perform a Firestore write to track pending state.
+     * Uses `waitForPendingWrites` to automatically clear when the write is acknowledged.
+     */
+    trackWrite(): void;
+    /** Enables Firestore network access (reconnects to server). */
+    goOnline(): Promise<void>;
+    /** Disables Firestore network access (forces offline mode). */
+    goOffline(): Promise<void>;
+    clearError(): void;
+    dispose(): void;
+}
+export declare const firekitNetwork: FirekitNetwork;
+export {};

package/dist/services/network.svelte.js

@@ -0,0 +1,167 @@
+import { onSnapshotsInSync, enableNetwork, disableNetwork, waitForPendingWrites } from 'firebase/firestore';
+import { firebaseService } from '../firebase.js';
+import { NetworkError, NetworkErrorCode } from '../types/network.js';
+/**
+ * Reactive network/offline status store.
+ *
+ * Tracks browser connectivity, Firestore sync state, and pending writes.
+ * Provides manual control to go offline/online.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { firekitNetwork } from 'svelte-firekit';
+ * </script>
+ *
+ * {#if !firekitNetwork.online}
+ *   <p>You're offline. Changes will sync when reconnected.</p>
+ * {/if}
+ *
+ * {#if firekitNetwork.hasPendingWrites}
+ *   <p>Saving...</p>
+ * {:else}
+ *   <p>All changes saved</p>
+ * {/if}
+ * ```
+ */
+class FirekitNetwork {
+    static instance;
+    // ── Reactive state ──────────────────────────────────────────────────────
+    _online = $state(typeof navigator !== 'undefined' ? navigator.onLine : true);
+    _synced = $state(true);
+    _hasPendingWrites = $state(false);
+    _initialized = $state(false);
+    _error = $state(null);
+    _firestoreEnabled = $state(true);
+    // ── Internal ────────────────────────────────────────────────────────────
+    _listening = false;
+    _db = null;
+    _syncUnsub = null;
+    _onlineHandler = null;
+    _offlineHandler = null;
+    constructor() { }
+    static getInstance() {
+        if (!FirekitNetwork.instance) {
+            FirekitNetwork.instance = new FirekitNetwork();
+        }
+        return FirekitNetwork.instance;
+    }
+    ensureListening() {
+        if (this._listening || typeof window === 'undefined')
+            return;
+        try {
+            const db = firebaseService.getDbInstance();
+            if (!db)
+                return;
+            this._listening = true;
+            // Browser online/offline events
+            this._onlineHandler = () => { this._online = true; };
+            this._offlineHandler = () => { this._online = false; };
+            window.addEventListener('online', this._onlineHandler);
+            window.addEventListener('offline', this._offlineHandler);
+            // Firestore sync state — fires when all active listeners are caught up
+            this._syncUnsub = onSnapshotsInSync(db, () => {
+                this._synced = true;
+                this._hasPendingWrites = false;
+            });
+            this._db = db;
+            this._initialized = true;
+        }
+        catch {
+            // Firestore not configured yet — will retry on next getter access
+        }
+    }
+    /**
+     * Called by FirebaseApp or lazily on first getter access.
+     * Safe to call multiple times.
+     */
+    initialize() {
+        this.ensureListening();
+    }
+    // ── Public getters (reactive) ───────────────────────────────────────────
+    /** Whether the browser has network connectivity. */
+    get online() { this.ensureListening(); return this._online; }
+    /** Whether all Firestore snapshots are in sync with the server. */
+    get synced() { this.ensureListening(); return this._synced; }
+    /** Whether there are unconfirmed Firestore writes. */
+    get hasPendingWrites() { this.ensureListening(); return this._hasPendingWrites; }
+    /** Whether the network store has been initialized. */
+    get initialized() { return this._initialized; }
+    /** Last error from network operations. */
+    get error() { return this._error; }
+    /** Whether Firestore network is currently enabled. */
+    get firestoreEnabled() { return this._firestoreEnabled; }
+    // ── Methods ─────────────────────────────────────────────────────────────
+    /**
+     * Call this when you perform a Firestore write to track pending state.
+     * Uses `waitForPendingWrites` to automatically clear when the write is acknowledged.
+     */
+    trackWrite() {
+        this._hasPendingWrites = true;
+        this._synced = false;
+        if (this._db) {
+            waitForPendingWrites(this._db)
+                .then(() => {
+                this._hasPendingWrites = false;
+                this._synced = true;
+            })
+                .catch(() => {
+                // Firestore may have been disabled
+            });
+        }
+    }
+    /** Enables Firestore network access (reconnects to server). */
+    async goOnline() {
+        try {
+            const db = firebaseService.getDbInstance();
+            if (!db)
+                throw new NetworkError(NetworkErrorCode.FIRESTORE_UNAVAILABLE, 'Firestore is not available.');
+            await enableNetwork(db);
+            this._firestoreEnabled = true;
+            this._error = null;
+        }
+        catch (err) {
+            if (err instanceof NetworkError)
+                throw err;
+            const error = new NetworkError(NetworkErrorCode.ENABLE_NETWORK_FAILED, 'Failed to enable network.', err);
+            this._error = error;
+            throw error;
+        }
+    }
+    /** Disables Firestore network access (forces offline mode). */
+    async goOffline() {
+        try {
+            const db = firebaseService.getDbInstance();
+            if (!db)
+                throw new NetworkError(NetworkErrorCode.FIRESTORE_UNAVAILABLE, 'Firestore is not available.');
+            await disableNetwork(db);
+            this._firestoreEnabled = false;
+            this._error = null;
+        }
+        catch (err) {
+            if (err instanceof NetworkError)
+                throw err;
+            const error = new NetworkError(NetworkErrorCode.DISABLE_NETWORK_FAILED, 'Failed to disable network.', err);
+            this._error = error;
+            throw error;
+        }
+    }
+    clearError() {
+        this._error = null;
+    }
+    dispose() {
+        this._listening = false;
+        this._syncUnsub?.();
+        this._syncUnsub = null;
+        if (this._onlineHandler) {
+            window.removeEventListener('online', this._onlineHandler);
+            this._onlineHandler = null;
+        }
+        if (this._offlineHandler) {
+            window.removeEventListener('offline', this._offlineHandler);
+            this._offlineHandler = null;
+        }
+        this._initialized = false;
+    }
+}
+export const firekitNetwork = FirekitNetwork.getInstance();

package/dist/types/index.d.ts

@@ -5,3 +5,5 @@ export * from './collection.js';
 export * from './mutations.js';
 export * from './presence.js';
 export * from './analytics.js';
+export * from './storage.js';
+export * from './network.js';

package/dist/types/index.js

@@ -5,3 +5,5 @@ export * from './collection.js';
 export * from './mutations.js';
 export * from './presence.js';
 export * from './analytics.js';
+export * from './storage.js';
+export * from './network.js';

package/dist/types/network.d.ts

@@ -0,0 +1,10 @@
+export declare enum NetworkErrorCode {
+    FIRESTORE_UNAVAILABLE = "network/firestore-unavailable",
+    ENABLE_NETWORK_FAILED = "network/enable-network-failed",
+    DISABLE_NETWORK_FAILED = "network/disable-network-failed"
+}
+export declare class NetworkError extends Error {
+    code: NetworkErrorCode;
+    originalError?: unknown | undefined;
+    constructor(code: NetworkErrorCode, message: string, originalError?: unknown | undefined);
+}

package/dist/types/network.js

@@ -0,0 +1,16 @@
+export var NetworkErrorCode;
+(function (NetworkErrorCode) {
+    NetworkErrorCode["FIRESTORE_UNAVAILABLE"] = "network/firestore-unavailable";
+    NetworkErrorCode["ENABLE_NETWORK_FAILED"] = "network/enable-network-failed";
+    NetworkErrorCode["DISABLE_NETWORK_FAILED"] = "network/disable-network-failed";
+})(NetworkErrorCode || (NetworkErrorCode = {}));
+export class NetworkError extends Error {
+    code;
+    originalError;
+    constructor(code, message, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = 'NetworkError';
+    }
+}

package/dist/types/storage.d.ts

@@ -0,0 +1,34 @@
+export interface FileValidationOptions {
+    /** Maximum file size in bytes. */
+    maxSize?: number;
+    /** Minimum file size in bytes. */
+    minSize?: number;
+    /** Allowed MIME types or extensions. Supports wildcards like `'image/*'` and extensions like `'.jpg'`. */
+    accept?: string[];
+    /** Maximum image width in pixels. Only checked for image files. */
+    maxWidth?: number;
+    /** Maximum image height in pixels. Only checked for image files. */
+    maxHeight?: number;
+    /** Minimum image width in pixels. Only checked for image files. */
+    minWidth?: number;
+    /** Minimum image height in pixels. Only checked for image files. */
+    minHeight?: number;
+}
+export declare enum FileValidationErrorCode {
+    FILE_TOO_LARGE = "validation/file-too-large",
+    FILE_TOO_SMALL = "validation/file-too-small",
+    INVALID_MIME_TYPE = "validation/invalid-mime-type",
+    IMAGE_TOO_WIDE = "validation/image-too-wide",
+    IMAGE_TOO_TALL = "validation/image-too-tall",
+    IMAGE_TOO_NARROW = "validation/image-too-narrow",
+    IMAGE_TOO_SHORT = "validation/image-too-short",
+    DIMENSION_CHECK_FAILED = "validation/dimension-check-failed"
+}
+export interface FileValidationError {
+    code: FileValidationErrorCode;
+    message: string;
+}
+export interface FileValidationResult {
+    valid: boolean;
+    errors: FileValidationError[];
+}

package/dist/types/storage.js

@@ -0,0 +1,11 @@
+export var FileValidationErrorCode;
+(function (FileValidationErrorCode) {
+    FileValidationErrorCode["FILE_TOO_LARGE"] = "validation/file-too-large";
+    FileValidationErrorCode["FILE_TOO_SMALL"] = "validation/file-too-small";
+    FileValidationErrorCode["INVALID_MIME_TYPE"] = "validation/invalid-mime-type";
+    FileValidationErrorCode["IMAGE_TOO_WIDE"] = "validation/image-too-wide";
+    FileValidationErrorCode["IMAGE_TOO_TALL"] = "validation/image-too-tall";
+    FileValidationErrorCode["IMAGE_TOO_NARROW"] = "validation/image-too-narrow";
+    FileValidationErrorCode["IMAGE_TOO_SHORT"] = "validation/image-too-short";
+    FileValidationErrorCode["DIMENSION_CHECK_FAILED"] = "validation/dimension-check-failed";
+})(FileValidationErrorCode || (FileValidationErrorCode = {}));

package/dist/utils/index.d.ts

@@ -2,3 +2,4 @@ export * from './errors.js';
 export * from './providers.js';
 export * from './user.js';
 export * from './firestore.js';
+export * from './validation.js';

package/dist/utils/index.js

@@ -2,3 +2,4 @@ export * from './errors.js';
 export * from './providers.js';
 export * from './user.js';
 export * from './firestore.js';
+export * from './validation.js';

package/dist/utils/validation.d.ts

@@ -0,0 +1,20 @@
+import { type FileValidationOptions, type FileValidationResult } from '../types/storage.js';
+/**
+ * Validates a File against the given options.
+ * Returns a result with `valid: true` if all checks pass, or `valid: false` with an array of errors.
+ *
+ * @example
+ * ```ts
+ * const result = await validateFile(file, {
+ *   maxSize: 5 * 1024 * 1024,
+ *   accept: ['image/png', 'image/jpeg', '.webp'],
+ *   maxWidth: 2048,
+ *   maxHeight: 2048
+ * });
+ *
+ * if (!result.valid) {
+ *   console.log(result.errors);
+ * }
+ * ```
+ */
+export declare function validateFile(file: File, options: FileValidationOptions): Promise<FileValidationResult>;

package/dist/utils/validation.js

@@ -0,0 +1,147 @@
+import { FileValidationErrorCode } from '../types/storage.js';
+/** Common extension-to-MIME mappings for the `accept` option. */
+const EXT_TO_MIME = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.bmp': 'image/bmp',
+    '.ico': 'image/x-icon',
+    '.avif': 'image/avif',
+    '.pdf': 'application/pdf',
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.ogg': 'audio/ogg',
+    '.json': 'application/json',
+    '.csv': 'text/csv',
+    '.txt': 'text/plain',
+    '.zip': 'application/zip'
+};
+function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function matchesMime(fileType, fileName, pattern) {
+    // Extension pattern: '.jpg'
+    if (pattern.startsWith('.')) {
+        const expectedMime = EXT_TO_MIME[pattern.toLowerCase()];
+        if (expectedMime)
+            return fileType === expectedMime;
+        // Fallback: check the file name extension
+        return fileName.toLowerCase().endsWith(pattern.toLowerCase());
+    }
+    // Wildcard MIME: 'image/*'
+    if (pattern.endsWith('/*')) {
+        const prefix = pattern.slice(0, -1); // 'image/'
+        return fileType.startsWith(prefix);
+    }
+    // Exact MIME: 'image/png'
+    return fileType === pattern;
+}
+function getImageDimensions(file) {
+    return new Promise((resolve, reject) => {
+        const url = URL.createObjectURL(file);
+        const img = new Image();
+        img.onload = () => {
+            URL.revokeObjectURL(url);
+            resolve({ width: img.naturalWidth, height: img.naturalHeight });
+        };
+        img.onerror = () => {
+            URL.revokeObjectURL(url);
+            reject(new Error('Failed to load image for dimension check.'));
+        };
+        img.src = url;
+    });
+}
+/**
+ * Validates a File against the given options.
+ * Returns a result with `valid: true` if all checks pass, or `valid: false` with an array of errors.
+ *
+ * @example
+ * ```ts
+ * const result = await validateFile(file, {
+ *   maxSize: 5 * 1024 * 1024,
+ *   accept: ['image/png', 'image/jpeg', '.webp'],
+ *   maxWidth: 2048,
+ *   maxHeight: 2048
+ * });
+ *
+ * if (!result.valid) {
+ *   console.log(result.errors);
+ * }
+ * ```
+ */
+export async function validateFile(file, options) {
+    const errors = [];
+    // ── Size checks ──────────────────────────────────────────────────────────
+    if (options.maxSize !== undefined && file.size > options.maxSize) {
+        errors.push({
+            code: FileValidationErrorCode.FILE_TOO_LARGE,
+            message: `File size ${formatBytes(file.size)} exceeds maximum ${formatBytes(options.maxSize)}.`
+        });
+    }
+    if (options.minSize !== undefined && file.size < options.minSize) {
+        errors.push({
+            code: FileValidationErrorCode.FILE_TOO_SMALL,
+            message: `File size ${formatBytes(file.size)} is below minimum ${formatBytes(options.minSize)}.`
+        });
+    }
+    // ── MIME type check ──────────────────────────────────────────────────────
+    if (options.accept && options.accept.length > 0) {
+        const accepted = options.accept.some((pattern) => matchesMime(file.type, file.name, pattern));
+        if (!accepted) {
+            errors.push({
+                code: FileValidationErrorCode.INVALID_MIME_TYPE,
+                message: `File type "${file.type || 'unknown'}" is not accepted. Allowed: ${options.accept.join(', ')}.`
+            });
+        }
+    }
+    // ── Image dimension checks ───────────────────────────────────────────────
+    const needsDimensions = options.maxWidth !== undefined ||
+        options.maxHeight !== undefined ||
+        options.minWidth !== undefined ||
+        options.minHeight !== undefined;
+    if (needsDimensions && file.type.startsWith('image/')) {
+        try {
+            const { width, height } = await getImageDimensions(file);
+            if (options.maxWidth !== undefined && width > options.maxWidth) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_WIDE,
+                    message: `Image width ${width}px exceeds maximum ${options.maxWidth}px.`
+                });
+            }
+            if (options.maxHeight !== undefined && height > options.maxHeight) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_TALL,
+                    message: `Image height ${height}px exceeds maximum ${options.maxHeight}px.`
+                });
+            }
+            if (options.minWidth !== undefined && width < options.minWidth) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_NARROW,
+                    message: `Image width ${width}px is below minimum ${options.minWidth}px.`
+                });
+            }
+            if (options.minHeight !== undefined && height < options.minHeight) {
+                errors.push({
+                    code: FileValidationErrorCode.IMAGE_TOO_SHORT,
+                    message: `Image height ${height}px is below minimum ${options.minHeight}px.`
+                });
+            }
+        }
+        catch {
+            errors.push({
+                code: FileValidationErrorCode.DIMENSION_CHECK_FAILED,
+                message: 'Could not read image dimensions for validation.'
+            });
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "svelte-firekit",
-	"version": "0.2.5",
+	"version": "0.2.6",
 	"description": "A Svelte library for Firebase integration",
 	"license": "MIT",
 	"author": "Giovani Rodriguez",