svelte-firekit 0.0.20 → 0.0.22

package/README.md

@@ -1,58 +1,221 @@
-# create-svelte
-
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
-
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
-
-## Creating a project
-
-If you're seeing this, you've probably already done this step. Congrats!
-
+---
+slug: docs
+title: Welcome to Svelte Firekit
+description: a comprehensive library integrating SvelteKit and Firebase for building robust micro SaaS applications.
+---
+ 
+## Introduction to Svelte Firekit
+ 
+Svelte Firekit is a powerful Firebase toolkit for SvelteKit applications, providing a comprehensive set of utilities, stores, and components for seamless Firebase integration. Whether you're building a micro SaaS, web application, or any Firebase-powered project, Svelte Firekit streamlines your development process.
+ 
+## Installation
+ 
 ```bash
-# create a new project in the current directory
-npx sv create
-
-# create a new project in my-app
-npx sv create my-app
-```
-
-## Developing
-
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
-
-```bash
-npm run dev
-
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
-```
-
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
-
-## Building
-
-To build your library:
-
-```bash
-npm run package
+npm install firebase svelte-firekit
 ```
-
-To create a production version of your showcase app:
-
-```bash
-npm run build
-```
-
-You can preview the production build with `npm run preview`.
-
-> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
-
-## Publishing
-
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
-
-To publish your library to [npm](https://www.npmjs.com):
-
-```bash
-npm publish
+ 
+## Configuration
+ 
+Svelte Firekit automatically manages your Firebase configuration through environment variables. Create a `.env` file in your project root with the following variables:
+ 
+```env
+PUBLIC_FIREBASE_API_KEY=your_api_key
+PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
+PUBLIC_FIREBASE_PROJECT_ID=your_project_id
+PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
+PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_messaging_sender_id
+PUBLIC_FIREBASE_APP_ID=your_app_id
+PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id
+```
+ 
+The configuration is automatically handled by Firekit - no manual setup required. If any required environment variables are missing, Firekit will throw a helpful error indicating which variables need to be set.
+ 
+## Usage Example
+ 
+Here's a simple example showing how to display the current user's name:
+ 
+```svelte
+<script>
+  import { firekitUser } from 'svelte-firekit';
+</script>
+ 
+Hello {firekitUser.displayName}
+```
+ 
+The `firekitUser` store provides access to the current user's information and authentication state.
+ 
+## Core Features
+ 
+### 🔥 Firebase Integration
+- Zero-config Firebase setup through environment variables
+- Automatic initialization and app management
+- Built-in error handling and connection state management
+- Type-safe configuration management
+ 
+### 🔐 Authentication
+- Complete authentication system with built-in components
+- Support for multiple authentication providers:
+  - Email/Password
+  - Google
+  - GitHub
+  - Custom providers
+- User state management and persistence through `firekitUser` store
+ 
+### 📚 Firestore Integration
+- Reactive data stores for real-time updates
+- Simplified CRUD operations
+- Batch operations and transactions
+- Type-safe document references
+- Automatic data serialization/deserialization
+ 
+### 📦 Storage Management
+- File upload and download utilities
+- Progress tracking and status updates
+- Storage security rules helpers
+- Image optimization utilities
+ 
+### ⚡ Server-Side Rendering
+- Full SSR compatibility
+- Hydration support
+- Server-side data fetching
+- SEO-friendly rendering
+ 
+### 🎯 Type Safety
+- Built with TypeScript
+- Complete type definitions
+- Intelligent autocomplete
+- Runtime type checking
+- Type-safe Firestore operations
+ 
+## Why Svelte Firekit?
+ 
+- **Zero Configuration**: Automatic Firebase setup through environment variables
+- **Type Safety**: Full TypeScript support with built-in type checking
+- **Rapid Development**: Get your Firebase-powered SvelteKit application up and running in minutes
+- **Best Practices**: Built following Firebase and SvelteKit best practices
+- **Production Ready**: Battle-tested in production environments
+- **Active Community**: Regular updates and active community support
+- **Extensible**: Easy to customize and extend for your specific needs
+ 
+## Next Steps
+ 
+- Check out our [Getting Started](/getting-started) guide
+- Explore the [API Reference](/api)
+- View [Examples](/examples)
+- Join our [Community](/community)
+ 
+## Contributing
+ 
+We welcome contributions! Please see our [Contributing Guide](/contributing) for more details.
+ 
+## License
+ 
+Svelte Firekit is released under the MIT License. See the [LICENSE](/license) file for more details.
+ 
+# Authentication
+ 
+Svelte Firekit provides a comprehensive authentication system through the `firekitAuth` singleton, offering various authentication methods and user management features.
+ 
+## Basic Usage
+ 
+```typescript
+import { firekitAuth } from 'svelte-firekit';
+```
+ 
+## Authentication Methods
+ 
+### Google Authentication
+ 
+```typescript
+await firekitAuth.signInWithGoogle();
+```
+ 
+### Email/Password Authentication
+ 
+```typescript
+// Sign in
+await firekitAuth.signInWithEmail(email, password);
+ 
+// Register
+await firekitAuth.registerWithEmail(email, password, displayName);
+ 
+// Sign out
+await firekitAuth.logOut();
+```
+ 
+## User Management
+ 
+### Password Management
+ 
+```typescript
+// Send password reset email
+await firekitAuth.sendPasswordReset(email);
+ 
+// Update password (requires reauthentication)
+await firekitAuth.updateUserPassword(newPassword, currentPassword);
+```
+ 
+### Profile Management
+ 
+```typescript
+// Update user profile
+await firekitAuth.updateUserProfile({
+  displayName: "New Name",
+  photoURL: "https://example.com/photo.jpg"
+});
+```
+ 
+### Email Verification
+ 
+```typescript
+// Send verification email
+await firekitAuth.sendEmailVerificationToUser();
+```
+ 
+### Account Deletion
+ 
+```typescript
+// Delete user account
+await firekitAuth.deleteUserAccount();
+```
+ 
+## Automatic Firestore Integration
+ 
+The authentication system automatically maintains a user document in Firestore with the following information:
+- User ID
+- Email
+- Email verification status
+- Display name
+- Photo URL
+- Authentication provider information
+- Anonymous status
+ 
+## Error Handling
+ 
+All methods include proper error handling and return appropriate error messages. For example, password updates will return:
+ 
+```typescript
+{
+  success: boolean;
+  message: string;
+  code?: string; // In case of errors
+}
 ```
+ 
+## Features
+ 
+- 🔐 Multiple authentication providers
+- 📝 Automatic user profile management
+- 🔄 Password reset and update functionality
+- ✉️ Email verification
+- 🗑️ Account deletion
+- 🔄 Reauthentication support
+- 📚 Automatic Firestore user document management
+- ⚡ Type-safe operations
+ 
+## Important Notes
+ 
+1. User data is automatically synchronized with Firestore
+2. Password updates require current password verification
+3. Account deletion removes both authentication and Firestore data
+4. All operations are fully typed for TypeScript support 

package/dist/auth/auth.d.ts

@@ -1,20 +1,87 @@
+/**
+ * @module FirekitAuth
+ */
+/**
+ * Manages Firebase authentication operations including sign-in, registration, and profile management.
+ * @class
+ * @example
+ * ```typescript
+ * // Sign in with Google
+ * await firekitAuth.signInWithGoogle();
+ *
+ * // Register new user
+ * await firekitAuth.registerWithEmail("user@example.com", "password123", "John Doe");
+ * ```
+ */
 declare class FirekitAuth {
     private static instance;
     private auth;
     private firestore;
     private constructor();
+    /**
+     * Gets singleton instance of FirekitAuth
+     * @returns {FirekitAuth} The FirekitAuth instance
+     */
     static getInstance(): FirekitAuth;
+    /**
+     * Initiates Google sign-in popup and updates user data in Firestore
+     * @throws {Error} If sign-in fails
+     */
     signInWithGoogle(): Promise<void>;
+    /**
+     * Signs in user with email and password
+     * @param {string} email User's email
+     * @param {string} password User's password
+     * @throws {Error} If sign-in fails
+     */
     signInWithEmail(email: string, password: string): Promise<void>;
+    /**
+     * Registers new user with email and password
+     * @param {string} email User's email
+     * @param {string} password User's password
+     * @param {string} displayName User's display name
+     * @throws {Error} If registration fails
+     */
     registerWithEmail(email: string, password: string, displayName: string): Promise<void>;
+    /**
+     * Updates user data in Firestore
+     * @param {User} user Firebase user object
+     * @private
+     */
     private updateUserInFirestore;
+    /**
+     * Signs out current user
+     * @throws {Error} If sign-out fails
+     */
     logOut(): Promise<void>;
+    /**
+     * Sends password reset email
+     * @param {string} email User's email
+     * @throws {Error} If sending reset email fails
+     */
     sendPasswordReset(email: string): Promise<void>;
+    /**
+     * Sends email verification to current user
+     * @throws {Error} If sending verification fails
+     */
     sendEmailVerificationToUser(): Promise<void>;
+    /**
+     * Updates user profile data
+     * @param {Object} profile Profile update data
+     * @param {string} [profile.displayName] New display name
+     * @param {string} [profile.photoURL] New photo URL
+     * @throws {Error} If update fails
+     */
     updateUserProfile(profile: {
         displayName?: string;
         photoURL?: string;
     }): Promise<void>;
+    /**
+     * Updates user password with reauthentication
+     * @param {string} newPassword New password
+     * @param {string} currentPassword Current password for reauthentication
+     * @returns {Promise<{success: boolean, message: string, code?: string}>} Update result
+     */
     updateUserPassword(newPassword: string, currentPassword: string): Promise<{
         success: boolean;
         message: string;
@@ -24,11 +91,27 @@ declare class FirekitAuth {
         code: any;
         message: string;
     }>;
-    reauthenticateUser(currentPassword: string): Promise<void>;
+    /**
+     * Reauthenticates current user
+     * @param {string} currentPassword Current password
+     * @throws {Error} If reauthentication fails
+     * @private
+     */
+    private reauthenticateUser;
+    /**
+     * Deletes user account and associated data
+     * @returns {Promise<{success: boolean, message: string}>} Deletion result
+     * @throws {Error} If deletion fails
+     */
     deleteUserAccount(): Promise<{
         success: boolean;
         message: string;
     }>;
 }
+/**
+ * Pre-initialized singleton instance of FirekitAuth
+ * @const
+ * @type {FirekitAuth}
+ */
 export declare const firekitAuth: FirekitAuth;
 export {};

package/dist/auth/auth.js

@@ -1,28 +1,63 @@
+/**
+ * @module FirekitAuth
+ */
 import { GoogleAuthProvider, sendPasswordResetEmail, signInWithEmailAndPassword, signInWithPopup, signOut, createUserWithEmailAndPassword, sendEmailVerification, updateProfile, updatePassword, EmailAuthProvider, reauthenticateWithCredential, } from 'firebase/auth';
-import { doc, getDoc, setDoc, Timestamp } from 'firebase/firestore';
+import { doc, setDoc } from 'firebase/firestore';
 import { firebaseService } from '../firebase.js';
 import { firekitDocMutations } from '../firestore/document-mutations.svelte.js';
-import { get, ref, set, update } from 'firebase/database';
+/**
+ * Manages Firebase authentication operations including sign-in, registration, and profile management.
+ * @class
+ * @example
+ * ```typescript
+ * // Sign in with Google
+ * await firekitAuth.signInWithGoogle();
+ *
+ * // Register new user
+ * await firekitAuth.registerWithEmail("user@example.com", "password123", "John Doe");
+ * ```
+ */
 class FirekitAuth {
     static instance;
     auth = firebaseService.getAuthInstance();
     firestore = firebaseService.getDbInstance();
     constructor() { }
+    /**
+     * Gets singleton instance of FirekitAuth
+     * @returns {FirekitAuth} The FirekitAuth instance
+     */
     static getInstance() {
         if (!FirekitAuth.instance) {
             FirekitAuth.instance = new FirekitAuth();
         }
         return FirekitAuth.instance;
     }
+    /**
+     * Initiates Google sign-in popup and updates user data in Firestore
+     * @throws {Error} If sign-in fails
+     */
     async signInWithGoogle() {
         const provider = new GoogleAuthProvider();
         const result = await signInWithPopup(this.auth, provider);
         await this.updateUserInFirestore(result.user);
     }
+    /**
+     * Signs in user with email and password
+     * @param {string} email User's email
+     * @param {string} password User's password
+     * @throws {Error} If sign-in fails
+     */
     async signInWithEmail(email, password) {
         const result = await signInWithEmailAndPassword(this.auth, email, password);
         await this.updateUserInFirestore(result.user);
     }
+    /**
+     * Registers new user with email and password
+     * @param {string} email User's email
+     * @param {string} password User's password
+     * @param {string} displayName User's display name
+     * @throws {Error} If registration fails
+     */
     async registerWithEmail(email, password, displayName) {
         const result = await createUserWithEmailAndPassword(this.auth, email, password);
         const user = result.user;
@@ -32,6 +67,11 @@ class FirekitAuth {
             await sendEmailVerification(user);
         }
     }
+    /**
+     * Updates user data in Firestore
+     * @param {User} user Firebase user object
+     * @private
+     */
     async updateUserInFirestore(user) {
         const ref = doc(this.firestore, 'users', user.uid);
         const userData = {
@@ -46,23 +86,49 @@ class FirekitAuth {
         };
         await setDoc(ref, userData, { merge: true });
     }
+    /**
+     * Signs out current user
+     * @throws {Error} If sign-out fails
+     */
     async logOut() {
         await signOut(this.auth);
     }
+    /**
+     * Sends password reset email
+     * @param {string} email User's email
+     * @throws {Error} If sending reset email fails
+     */
     async sendPasswordReset(email) {
         await sendPasswordResetEmail(this.auth, email);
     }
+    /**
+     * Sends email verification to current user
+     * @throws {Error} If sending verification fails
+     */
     async sendEmailVerificationToUser() {
         if (this.auth.currentUser) {
             await sendEmailVerification(this.auth.currentUser);
         }
     }
+    /**
+     * Updates user profile data
+     * @param {Object} profile Profile update data
+     * @param {string} [profile.displayName] New display name
+     * @param {string} [profile.photoURL] New photo URL
+     * @throws {Error} If update fails
+     */
     async updateUserProfile(profile) {
         if (this.auth.currentUser) {
             await updateProfile(this.auth.currentUser, profile);
             await this.updateUserInFirestore(this.auth.currentUser);
         }
     }
+    /**
+     * Updates user password with reauthentication
+     * @param {string} newPassword New password
+     * @param {string} currentPassword Current password for reauthentication
+     * @returns {Promise<{success: boolean, message: string, code?: string}>} Update result
+     */
     async updateUserPassword(newPassword, currentPassword) {
         if (!this.auth.currentUser) {
             throw new Error('No authenticated user found.');
@@ -76,9 +142,19 @@ class FirekitAuth {
             if (error.code === 'auth/wrong-password') {
                 return { success: false, code: error.code, message: 'Reauthentication failed: incorrect password.' };
             }
-            return { success: false, code: error.code || 'unknown_error', message: `Failed to update password: ${error.message || 'Unknown error occurred.'}` };
+            return {
+                success: false,
+                code: error.code || 'unknown_error',
+                message: `Failed to update password: ${error.message || 'Unknown error occurred.'}`
+            };
         }
     }
+    /**
+     * Reauthenticates current user
+     * @param {string} currentPassword Current password
+     * @throws {Error} If reauthentication fails
+     * @private
+     */
     async reauthenticateUser(currentPassword) {
         if (!this.auth.currentUser || !this.auth.currentUser.email) {
             throw new Error('No authenticated user or email unavailable.');
@@ -91,6 +167,11 @@ class FirekitAuth {
             throw new Error(`Reauthentication failed: ${error.message || 'Unknown error occurred.'}`);
         }
     }
+    /**
+     * Deletes user account and associated data
+     * @returns {Promise<{success: boolean, message: string}>} Deletion result
+     * @throws {Error} If deletion fails
+     */
     async deleteUserAccount() {
         if (!this.auth.currentUser) {
             throw new Error('No authenticated user found.');
@@ -105,4 +186,9 @@ class FirekitAuth {
         }
     }
 }
+/**
+ * Pre-initialized singleton instance of FirekitAuth
+ * @const
+ * @type {FirekitAuth}
+ */
 export const firekitAuth = FirekitAuth.getInstance();

package/dist/auth/presence.svelte.d.ts

@@ -1,23 +1,43 @@
+/**
+ * Geolocation configuration options
+ */
 interface GeolocationConfig {
+    /** Whether geolocation tracking is enabled */
     enabled: boolean;
+    /** Type of geolocation service to use */
     type: 'browser' | 'ip' | 'custom';
+    /** Custom function for retrieving geolocation */
     customGeolocationFn?: () => Promise<{
         latitude: number;
         longitude: number;
     }>;
+    /** URL for IP-based geolocation service */
     ipServiceUrl?: string;
+    /** Whether user consent is required for location tracking */
     requireConsent?: boolean;
 }
+/**
+ * Presence service configuration options
+ */
 interface PresenceConfig {
+    /** Geolocation settings */
     geolocation?: GeolocationConfig;
+    /** Session timeout in milliseconds */
     sessionTTL?: number;
+    /** Presence update interval in milliseconds */
     updateInterval?: number;
 }
+/**
+ * Location data structure
+ */
 interface Location {
     latitude: number | null;
     longitude: number | null;
     lastUpdated: string | null;
 }
+/**
+ * Session data structure
+ */
 interface SessionData {
     uid: string;
     userId: string;
@@ -27,6 +47,9 @@ interface SessionData {
     lastSeen: string;
     location?: Location;
 }
+/**
+ * Presence event structure
+ */
 type PresenceEvent = {
     type: 'status_change' | 'error' | 'init' | 'disconnect' | 'location_update';
     data?: any;
@@ -34,6 +57,23 @@ type PresenceEvent = {
     timestamp: number;
 };
 type PresenceEventCallback = (event: PresenceEvent) => void;
+/**
+ * Manages real-time user presence tracking with optional geolocation support
+ * @class
+ * @example
+ * ```typescript
+ * // Initialize presence tracking
+ * await presenceService.initialize(currentUser, {
+ *   geolocation: { enabled: true, type: 'browser' },
+ *   sessionTTL: 30 * 60 * 1000
+ * });
+ *
+ * // Listen for presence events
+ * presenceService.addEventListener((event) => {
+ *   console.log(event.type, event.data);
+ * });
+ * ```
+ */
 declare class PresenceService {
     private static instance;
     private connectedListener;
@@ -50,24 +90,49 @@ declare class PresenceService {
     private _error;
     private constructor();
     static getInstance(): PresenceService;
+    /** Get current session data */
     get currentSession(): SessionData | null;
+    /** Get all active sessions */
     get sessions(): SessionData[];
+    /** Get current presence status */
     get status(): "online" | "offline" | "away";
+    /** Get loading state */
     get loading(): boolean;
+    /** Get error state */
     get error(): Error | null;
+    /** Check if service is initialized */
     get isInitialized(): boolean;
+    /** Check if location consent is granted */
     get hasLocationConsent(): boolean;
+    /**
+ * Initialize presence tracking
+ * @param {any} user Current user object
+ * @param {PresenceConfig} config Optional configuration
+ * @throws {Error} If initialization fails
+ */
     private initializePresence;
     private setupVisibilityListener;
     private getDeviceInfo;
+    /**
+    * Request location tracking consent
+    * @returns {Promise<boolean>} Whether consent was granted
+    */
     requestLocationConsent(): Promise<boolean>;
     private getLocation;
     initialize(user: any, config?: PresenceConfig): Promise<void>;
     private setPresence;
     private startLocationWatcher;
     private stopLocationWatcher;
+    /**
+      * Add presence event listener
+      * @param {Function} callback Event callback function
+      * @returns {Function} Cleanup function to remove listener
+      */
     addEventListener(callback: PresenceEventCallback): () => boolean;
     private emitEvent;
+    /**
+         * Cleanup presence tracking
+         */
     dispose(): void;
 }
 export declare const presenceService: PresenceService;