svelte-firekit 0.1.9 → 0.2.0

package/dist/services/remote-config.svelte.js

@@ -0,0 +1,204 @@
+import { getRemoteConfig, fetchAndActivate, fetchConfig, activate, getValue, getString, getBoolean, getNumber, getAll, onConfigUpdate, isSupported, setLogLevel } from 'firebase/remote-config';
+import { firebaseService } from '../firebase.js';
+function getApp() {
+    const app = firebaseService.getFirebaseApp();
+    if (!app)
+        throw new Error('Firebase app is not initialized.');
+    return app;
+}
+/**
+ * Reactive Firebase Remote Config service.
+ *
+ * Fetches and activates remote configuration values, exposes them reactively,
+ * and optionally subscribes to real-time config updates.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitRemoteConfig } from 'svelte-firekit';
+ *
+ *   const rc = firekitRemoteConfig({
+ *     defaults: { welcomeMessage: 'Hello!', featureEnabled: false },
+ *     minimumFetchIntervalMs: 3600_000
+ *   });
+ *   await rc.fetchAndActivate();
+ * </script>
+ * <p>{rc.getString('welcomeMessage')}</p>
+ * ```
+ */
+export class FirekitRemoteConfig {
+    _loading = $state(false);
+    _error = $state(null);
+    _lastFetchTime = $state(null);
+    _activated = $state(false);
+    /** Bumped whenever config is activated, so derived reads stay reactive. */
+    _version = $state(0);
+    _rc = null;
+    _unsubscribe = null;
+    _options;
+    constructor(options = {}) {
+        this._options = options;
+        this._init();
+    }
+    get loading() { return this._loading; }
+    get error() { return this._error; }
+    get activated() { return this._activated; }
+    get lastFetchTime() { return this._lastFetchTime; }
+    async _init() {
+        if (typeof window === 'undefined')
+            return;
+        try {
+            const supported = await isSupported();
+            if (!supported)
+                return;
+            const app = getApp();
+            this._rc = getRemoteConfig(app);
+            if (this._options.minimumFetchIntervalMs !== undefined) {
+                this._rc.settings.minimumFetchIntervalMillis = this._options.minimumFetchIntervalMs;
+            }
+            if (this._options.fetchTimeoutMs !== undefined) {
+                this._rc.settings.fetchTimeoutMillis = this._options.fetchTimeoutMs;
+            }
+            if (this._options.defaults) {
+                this._rc.defaultConfig = this._options.defaults;
+            }
+            if (this._options.logLevel) {
+                setLogLevel(this._rc, this._options.logLevel);
+            }
+            if (this._options.autoFetch !== false) {
+                await this.fetchAndActivate();
+            }
+            if (this._options.realtime) {
+                this._subscribeToUpdates();
+            }
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    _subscribeToUpdates() {
+        if (!this._rc)
+            return;
+        this._unsubscribe = onConfigUpdate(this._rc, {
+            next: async () => {
+                try {
+                    await activate(this._rc);
+                    this._version++;
+                    this._activated = true;
+                }
+                catch (err) {
+                    this._error = err instanceof Error ? err : new Error(String(err));
+                }
+            },
+            error: (err) => {
+                this._error = err instanceof Error ? err : new Error(String(err));
+            },
+            complete: () => { }
+        });
+    }
+    // ── Fetch / activate ──────────────────────────────────────────────────────
+    /** Fetches fresh config from the server and activates it. */
+    async fetchAndActivate() {
+        if (!this._rc)
+            return false;
+        this._loading = true;
+        this._error = null;
+        try {
+            const changed = await fetchAndActivate(this._rc);
+            this._activated = true;
+            this._lastFetchTime = new Date();
+            this._version++;
+            return changed;
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+            return false;
+        }
+        finally {
+            this._loading = false;
+        }
+    }
+    /** Fetches config without activating. */
+    async fetch() {
+        if (!this._rc)
+            return;
+        this._loading = true;
+        this._error = null;
+        try {
+            await fetchConfig(this._rc);
+            this._lastFetchTime = new Date();
+        }
+        catch (err) {
+            this._error = err instanceof Error ? err : new Error(String(err));
+        }
+        finally {
+            this._loading = false;
+        }
+    }
+    /** Activates the last fetched config. */
+    async activate() {
+        if (!this._rc)
+            return false;
+        const changed = await activate(this._rc);
+        if (changed) {
+            this._activated = true;
+            this._version++;
+        }
+        return changed;
+    }
+    // ── Value accessors ───────────────────────────────────────────────────────
+    /** Returns a string config value. Uses default if not set. */
+    getString(key, defaultValue = '') {
+        void this._version; // reactive dependency — ensures re-evaluation when config is activated // reactive dependency
+        if (!this._rc)
+            return defaultValue;
+        return getString(this._rc, key) || defaultValue;
+    }
+    /** Returns a boolean config value. */
+    getBoolean(key, defaultValue = false) {
+        void this._version; // reactive dependency — ensures re-evaluation when config is activated
+        if (!this._rc)
+            return defaultValue;
+        try {
+            return getBoolean(this._rc, key);
+        }
+        catch {
+            return defaultValue;
+        }
+    }
+    /** Returns a number config value. */
+    getNumber(key, defaultValue = 0) {
+        void this._version; // reactive dependency — ensures re-evaluation when config is activated
+        if (!this._rc)
+            return defaultValue;
+        try {
+            return getNumber(this._rc, key);
+        }
+        catch {
+            return defaultValue;
+        }
+    }
+    /** Returns the raw Value object for a key. */
+    getValue(key) {
+        void this._version; // reactive dependency — ensures re-evaluation when config is activated
+        if (!this._rc)
+            return null;
+        return getValue(this._rc, key);
+    }
+    /** Returns all config key-value pairs as a plain object. */
+    getAll() {
+        void this._version; // reactive dependency — ensures re-evaluation when config is activated
+        if (!this._rc)
+            return {};
+        return getAll(this._rc);
+    }
+    /** Stops the real-time config update listener. */
+    dispose() {
+        this._unsubscribe?.();
+        this._unsubscribe = null;
+    }
+}
+/** Creates a reactive Remote Config instance. */
+export function firekitRemoteConfig(options) {
+    return new FirekitRemoteConfig(options);
+}

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

@@ -1,257 +1,130 @@
+import { type StorageReference, type UploadTaskSnapshot, type FullMetadata, type UploadMetadata, type SettableMetadata } from 'firebase/storage';
 /**
- * @fileoverview FirekitStorage - Optimized Firebase Storage management for Svelte applications
- * @module FirekitStorage
- * @version 1.0.0
- */
-import { type StorageReference, type UploadTaskSnapshot } from 'firebase/storage';
-/**
- * Manages Firebase Storage download URL fetching with reactive state
- * @class
+ * Fetches and exposes a Firebase Storage download URL reactively.
  *
  * @example
- * ```typescript
- * // Get download URL for image
- * const imageUrl = firekitDownloadUrl('images/photo.jpg');
- *
- * // Access reactive state
- * if (imageUrl.loading) {
- *   console.log('Loading URL...');
- * } else if (imageUrl.url) {
- *   console.log('Download URL:', imageUrl.url);
- * }
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitDownloadUrl } from 'svelte-firekit';
+ *   const img = firekitDownloadUrl('images/avatar.jpg');
+ * </script>
+ * {#if img.url}<img src={img.url} alt="avatar" />{/if}
  * ```
  */
-declare class FirekitDownloadUrl {
-    /** Current download URL */
+export declare class FirekitDownloadUrl {
     private _url;
-    /** Loading state */
     private _loading;
-    /** Error state */
     private _error;
-    /** Storage reference */
-    private storageRef;
-    /**
-     * Creates a download URL fetcher
-     * @param {string} path Storage path to file
-     *
-     * @example
-     * ```typescript
-     * const url = new FirekitDownloadUrl('documents/file.pdf');
-     * ```
-     */
+    private _storageRef;
+    private _path;
     constructor(path: string);
-    /**
-     * Initializes download URL fetching
-     * @private
-     * @param {string} path Storage path
-     */
-    private initializeDownload;
-    /** Gets current download URL */
     get url(): string | null;
-    /** Gets loading state */
     get loading(): boolean;
-    /** Gets error state */
     get error(): Error | null;
-    /**
-     * Refreshes download URL
-     * Useful when file content has changed
-     *
-     * @example
-     * ```typescript
-     * // Refresh URL after file update
-     * await uploadNewVersion();
-     * imageUrl.refresh();
-     * ```
-     */
-    refresh(): void;
+    private _init;
+    /** Re-fetches the download URL (useful after replacing a file). */
+    refresh(): Promise<void>;
 }
 /**
- * Manages Firebase Storage directory listing with reactive state
- * @class
+ * Lists files and sub-folders at a Storage path reactively.
  *
  * @example
- * ```typescript
- * // List contents of images directory
- * const imagesList = firekitStorageList('images');
- *
- * // Access items and folders
- * console.log('Files:', imagesList.items);
- * console.log('Folders:', imagesList.prefixes);
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitStorageList } from 'svelte-firekit';
+ *   const dir = firekitStorageList('uploads/2024');
+ * </script>
+ * {#each dir.items as item}<p>{item.name}</p>{/each}
  * ```
  */
-declare class FirekitStorageList {
-    /** List of files in directory */
+export declare class FirekitStorageList {
     private _items;
-    /** List of subdirectories */
     private _prefixes;
-    /** Loading state */
     private _loading;
-    /** Error state */
     private _error;
-    /** Storage reference */
-    private storageRef;
-    /**
-     * Creates a storage directory lister
-     * @param {string} path Storage directory path
-     *
-     * @example
-     * ```typescript
-     * const list = new FirekitStorageList('uploads/2024');
-     * ```
-     */
+    private _storageRef;
+    private _path;
     constructor(path: string);
-    /**
-     * Initializes directory listing
-     * @private
-     * @param {string} path Storage directory path
-     */
-    private initializeList;
-    /** Gets list of files */
     get items(): StorageReference[];
-    /** Gets list of subdirectories */
     get prefixes(): StorageReference[];
-    /** Gets loading state */
     get loading(): boolean;
-    /** Gets error state */
     get error(): Error | null;
-    /**
-     * Refreshes directory listing
-     * Useful when directory contents have changed
-     *
-     * @example
-     * ```typescript
-     * // Refresh after upload
-     * await uploadFile('images/new.jpg');
-     * imagesList.refresh();
-     * ```
-     */
-    refresh(): void;
+    private _init;
+    /** Re-lists the directory (useful after uploads/deletes). */
+    refresh(): Promise<void>;
 }
+export type UploadState = 'idle' | 'running' | 'paused' | 'success' | 'canceled' | 'error';
 /**
- * Manages Firebase Storage upload operations with reactive state and progress tracking
- * @class
+ * Manages a resumable Firebase Storage upload with reactive progress.
  *
  * @example
- * ```typescript
- * // Create upload task
- * const upload = firekitUploadTask('images/photo.jpg', file);
- *
- * // Monitor progress
- * console.log(`Upload progress: ${upload.progress}%`);
- *
- * // Control upload
- * upload.pause();
- * upload.resume();
- * upload.cancel();
+ * ```svelte
+ * <script lang="ts">
+ *   import { firekitUploadTask } from 'svelte-firekit';
+ *   let file: File;
+ *   $: task = file ? firekitUploadTask('uploads/' + file.name, file) : null;
+ * </script>
+ * {#if task}
+ *   <progress value={task.progress} max={100} />
+ *   {#if task.downloadURL}<img src={task.downloadURL} />{/if}
+ * {/if}
  * ```
  */
-declare class FirekitUploadTask {
-    /** Upload progress percentage */
+export declare class FirekitUploadTask {
     private _progress;
-    /** Error state */
+    private _downloadURL;
     private _error;
-    /** Current upload snapshot */
+    private _state;
+    private _bytesTransferred;
+    private _totalBytes;
     private _snapshot;
-    /** Download URL of uploaded file */
-    private _downloadURL;
-    /** Upload completion state */
-    private _completed;
-    /** Upload task reference */
-    private uploadTask;
-    /** Storage reference */
-    private storageRef;
-    /**
-     * Creates an upload task
-     * @param {string} path Storage path for upload
-     * @param {File} file File to upload
-     *
-     * @example
-     * ```typescript
-     * const task = new FirekitUploadTask('documents/report.pdf', file);
-     * ```
-     */
-    constructor(path: string, file: File);
-    /**
-     * Initializes file upload
-     * @private
-     * @param {string} path Storage path
-     * @param {File} file File to upload
-     */
-    private initializeUpload;
-    /** Pauses upload */
-    pause(): void;
-    /** Resumes upload */
-    resume(): void;
-    /** Cancels upload */
-    cancel(): void;
-    /** Gets upload progress percentage */
+    readonly completed: boolean;
+    readonly canceled: boolean;
+    readonly failed: boolean;
+    readonly active: boolean;
+    private _task;
+    private _storageRef;
+    constructor(path: string, file: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata);
     get progress(): number;
-    /** Gets error state */
+    get downloadURL(): string | null;
     get error(): Error | null;
-    /** Gets current upload snapshot */
+    get state(): UploadState;
+    get bytesTransferred(): number;
+    get totalBytes(): number;
     get snapshot(): UploadTaskSnapshot | null;
-    /** Gets download URL */
-    get downloadURL(): string | null;
-    /** Gets completion state */
-    get completed(): boolean;
+    private _init;
+    /** Pauses the upload. */
+    pause(): void;
+    /** Resumes a paused upload. */
+    resume(): void;
+    /** Cancels the upload. */
+    cancel(): void;
 }
 /**
- * Creates a download URL fetcher
- * @param {string} path Storage path to file
- * @returns {FirekitDownloadUrl} Download URL fetcher instance
- *
- * @example
- * ```typescript
- * const imageUrl = firekitDownloadUrl('images/profile.jpg');
- *
- * // Use in template
- * {#if imageUrl.loading}
- *   <p>Loading...</p>
- * {:else if imageUrl.url}
- *   <img src={imageUrl.url} alt="Profile" />
- * {/if}
- * ```
+ * Deletes a file from Firebase Storage.
  */
-export declare function firekitDownloadUrl(path: string): FirekitDownloadUrl;
+export declare function deleteFile(path: string): Promise<void>;
 /**
- * Creates a storage directory lister
- * @param {string} path Storage directory path
- * @returns {FirekitStorageList} Storage list instance
- *
- * @example
- * ```typescript
- * const documents = firekitStorageList('documents');
- *
- * // Use in template
- * {#if documents.loading}
- *   <p>Loading...</p>
- * {:else}
- *   <ul>
- *     {#each documents.items as item}
- *       <li>{item.name}</li>
- *     {/each}
- *   </ul>
- * {/if}
- * ```
+ * Fetches metadata for a file in Firebase Storage.
  */
-export declare function firekitStorageList(path: string): FirekitStorageList;
+export declare function getFileMetadata(path: string): Promise<FullMetadata>;
 /**
- * Creates an upload task
- * @param {string} path Storage path for upload
- * @param {File} file File to upload
- * @returns {FirekitUploadTask} Upload task instance
+ * Updates metadata for a file in Firebase Storage.
+ * Only fields provided in `metadata` are changed; omitted fields are left as-is.
  *
  * @example
- * ```typescript
- * const uploadTask = firekitUploadTask('images/profile.jpg', imageFile);
- *
- * // Template usage
- * {#if !uploadTask.completed}
- *   <progress value={uploadTask.progress} max="100" />
- * {:else}
- *   <img src={uploadTask.downloadURL} alt="Uploaded file" />
- * {/if}
+ * ```ts
+ * await updateFileMetadata('images/avatar.jpg', {
+ *   contentType: 'image/webp',
+ *   customMetadata: { uploadedBy: 'uid123' }
+ * });
  * ```
  */
-export declare function firekitUploadTask(path: string, file: File): FirekitUploadTask;
-export {};
+export declare function updateFileMetadata(path: string, metadata: SettableMetadata): Promise<FullMetadata>;
+export type { SettableMetadata };
+/** Creates a reactive download URL fetcher. */
+export declare function firekitDownloadUrl(path: string): FirekitDownloadUrl;
+/** Creates a reactive Storage directory listing. */
+export declare function firekitStorageList(path: string): FirekitStorageList;
+/** Creates a reactive resumable upload task. */
+export declare function firekitUploadTask(path: string, file: Blob | Uint8Array | ArrayBuffer, metadata?: UploadMetadata): FirekitUploadTask;