svelte-firekit 0.0.25 → 0.1.1

package/dist/types/presence.d.ts

@@ -0,0 +1,282 @@
+/**
+ * @fileoverview Presence types and interfaces for FirekitPresence
+ * @module PresenceTypes
+ * @version 1.0.0
+ */
+/**
+ * Geolocation configuration options
+ */
+export 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;
+    /** High accuracy GPS tracking */
+    enableHighAccuracy?: boolean;
+    /** Location timeout in milliseconds */
+    timeout?: number;
+    /** Maximum age of cached location in milliseconds */
+    maximumAge?: number;
+}
+/**
+ * Presence service configuration options
+ */
+export interface PresenceConfig {
+    /** Geolocation settings */
+    geolocation?: GeolocationConfig;
+    /** Session timeout in milliseconds (default: 30 minutes) */
+    sessionTTL?: number;
+    /** Presence update interval in milliseconds (default: 1 minute) */
+    updateInterval?: number;
+    /** Custom user metadata to track */
+    customMetadata?: Record<string, any>;
+    /** Whether to track device information */
+    trackDeviceInfo?: boolean;
+    /** Custom session collection path in Firebase */
+    sessionPath?: string;
+    /** Whether to enable automatic status detection based on page visibility */
+    enableAutoStatusDetection?: boolean;
+}
+/**
+ * Location data structure
+ */
+export interface Location {
+    latitude: number;
+    longitude: number;
+    accuracy?: number;
+    altitude?: number;
+    altitudeAccuracy?: number;
+    heading?: number;
+    speed?: number;
+    lastUpdated: string;
+    source: 'browser' | 'ip' | 'custom';
+}
+/**
+ * Device information structure
+ */
+export interface DeviceInfo {
+    id: string;
+    type: 'desktop' | 'mobile' | 'tablet' | 'unknown';
+    browser: string;
+    browserVersion: string;
+    os: string;
+    osVersion: string;
+    userAgent: string;
+    screenResolution?: string;
+    timezone?: string;
+}
+/**
+ * Session data structure
+ */
+export interface SessionData {
+    id: string;
+    userId: string;
+    status: 'online' | 'offline' | 'away' | 'busy' | 'invisible';
+    createdAt: string;
+    lastSeen: string;
+    location?: Location;
+    device?: DeviceInfo;
+    metadata?: Record<string, any>;
+    connectionType?: 'wifi' | 'cellular' | 'ethernet' | 'unknown';
+    lastActivity?: string;
+}
+/**
+ * User presence summary
+ */
+export interface UserPresence {
+    userId: string;
+    status: SessionData['status'];
+    lastSeen: string;
+    sessionCount: number;
+    activeDevices: string[];
+    primarySession?: SessionData;
+    location?: Location;
+}
+/**
+ * Presence statistics
+ */
+export interface PresenceStats {
+    totalSessions: number;
+    onlineSessions: number;
+    awaySessions: number;
+    offlineSessions: number;
+    uniqueDevices: number;
+    averageSessionDuration: number;
+    lastActivity: string;
+}
+/**
+ * Presence event types
+ */
+export type PresenceEventType = 'status_change' | 'session_created' | 'session_updated' | 'session_expired' | 'location_update' | 'location_error' | 'error' | 'init' | 'disconnect' | 'reconnect' | 'consent_requested' | 'consent_granted' | 'consent_denied' | 'device_detected' | 'visibility_change';
+/**
+ * Presence event structure
+ */
+export interface PresenceEvent {
+    type: PresenceEventType;
+    data?: any;
+    error?: Error;
+    timestamp: number;
+    sessionId?: string;
+    userId?: string;
+}
+/**
+ * Presence event callback function type
+ */
+export type PresenceEventCallback = (event: PresenceEvent) => void;
+/**
+ * Geolocation provider interface
+ */
+export interface GeolocationProvider {
+    getCurrentLocation(): Promise<Location | null>;
+    watchPosition?(callback: (location: Location | null) => void): number;
+    clearWatch?(watchId: number): void;
+    requestPermission?(): Promise<boolean>;
+}
+/**
+ * Session storage interface
+ */
+export interface SessionStorage {
+    saveSession(userId: string, session: SessionData): Promise<void>;
+    loadSessions(userId: string): Promise<SessionData[]>;
+    deleteSession(userId: string, sessionId: string): Promise<void>;
+    cleanupExpiredSessions(userId: string, ttl: number): Promise<void>;
+}
+/**
+ * Presence service interface
+ */
+export interface PresenceService {
+    initialize(user: any, config?: PresenceConfig): Promise<void>;
+    setPresence(status: SessionData['status']): Promise<void>;
+    getCurrentSession(): SessionData | null;
+    getAllSessions(): SessionData[];
+    getPresenceStats(): PresenceStats;
+    addEventListener(callback: PresenceEventCallback): () => void;
+    dispose(): Promise<void>;
+}
+/**
+ * Connection info structure
+ */
+export interface ConnectionInfo {
+    effectiveType?: 'slow-2g' | '2g' | '3g' | '4g';
+    type?: 'bluetooth' | 'cellular' | 'ethernet' | 'none' | 'wifi' | 'wimax' | 'other' | 'unknown';
+    downlink?: number;
+    rtt?: number;
+    saveData?: boolean;
+}
+/**
+ * Browser capability detection
+ */
+export interface BrowserCapabilities {
+    geolocation: boolean;
+    notifications: boolean;
+    serviceWorker: boolean;
+    indexedDB: boolean;
+    webRTC: boolean;
+    websockets: boolean;
+    localStorage: boolean;
+}
+/**
+ * Presence filter options
+ */
+export interface PresenceFilter {
+    status?: SessionData['status'][];
+    deviceTypes?: DeviceInfo['type'][];
+    timeRange?: {
+        start: string;
+        end: string;
+    };
+    hasLocation?: boolean;
+    activeOnly?: boolean;
+}
+/**
+ * Bulk presence update
+ */
+export interface BulkPresenceUpdate {
+    userId: string;
+    updates: Partial<SessionData>[];
+    timestamp: string;
+}
+/**
+ * Presence query options
+ */
+export interface PresenceQueryOptions {
+    limit?: number;
+    orderBy?: 'lastSeen' | 'createdAt' | 'status';
+    direction?: 'asc' | 'desc';
+    filter?: PresenceFilter;
+    includeExpired?: boolean;
+}
+/**
+ * Custom presence status
+ */
+export interface CustomPresenceStatus {
+    key: string;
+    label: string;
+    color?: string;
+    icon?: string;
+    priority?: number;
+    autoDetect?: boolean;
+}
+/**
+ * Presence analytics data
+ */
+export interface PresenceAnalytics {
+    userId: string;
+    dailyActiveTime: number;
+    weeklyActiveTime: number;
+    monthlyActiveTime: number;
+    mostActiveDevice: string;
+    mostActiveHour: number;
+    averageSessionLength: number;
+    locationHistory: Location[];
+    statusHistory: Array<{
+        status: SessionData['status'];
+        timestamp: string;
+        duration: number;
+    }>;
+}
+/**
+ * Error types for presence service
+ */
+export declare enum PresenceErrorCode {
+    INITIALIZATION_FAILED = "presence/initialization-failed",
+    USER_NOT_AUTHENTICATED = "presence/user-not-authenticated",
+    GEOLOCATION_DENIED = "presence/geolocation-denied",
+    GEOLOCATION_UNAVAILABLE = "presence/geolocation-unavailable",
+    GEOLOCATION_TIMEOUT = "presence/geolocation-timeout",
+    DATABASE_ERROR = "presence/database-error",
+    SESSION_EXPIRED = "presence/session-expired",
+    INVALID_CONFIG = "presence/invalid-config",
+    BROWSER_NOT_SUPPORTED = "presence/browser-not-supported",
+    NETWORK_ERROR = "presence/network-error",
+    PERMISSION_DENIED = "presence/permission-denied"
+}
+/**
+ * Custom presence error class
+ */
+export declare class PresenceError extends Error {
+    code: PresenceErrorCode;
+    originalError?: any | undefined;
+    constructor(code: PresenceErrorCode, message: string, originalError?: any | undefined);
+    /**
+     * Get user-friendly error message
+     */
+    getFriendlyMessage(): string;
+    /**
+     * Check if error is retryable
+     */
+    isRetryable(): boolean;
+    /**
+     * Check if error requires user action
+     */
+    requiresUserAction(): boolean;
+}

package/dist/types/presence.js

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview Presence types and interfaces for FirekitPresence
+ * @module PresenceTypes
+ * @version 1.0.0
+ */
+/**
+ * Error types for presence service
+ */
+export var PresenceErrorCode;
+(function (PresenceErrorCode) {
+    PresenceErrorCode["INITIALIZATION_FAILED"] = "presence/initialization-failed";
+    PresenceErrorCode["USER_NOT_AUTHENTICATED"] = "presence/user-not-authenticated";
+    PresenceErrorCode["GEOLOCATION_DENIED"] = "presence/geolocation-denied";
+    PresenceErrorCode["GEOLOCATION_UNAVAILABLE"] = "presence/geolocation-unavailable";
+    PresenceErrorCode["GEOLOCATION_TIMEOUT"] = "presence/geolocation-timeout";
+    PresenceErrorCode["DATABASE_ERROR"] = "presence/database-error";
+    PresenceErrorCode["SESSION_EXPIRED"] = "presence/session-expired";
+    PresenceErrorCode["INVALID_CONFIG"] = "presence/invalid-config";
+    PresenceErrorCode["BROWSER_NOT_SUPPORTED"] = "presence/browser-not-supported";
+    PresenceErrorCode["NETWORK_ERROR"] = "presence/network-error";
+    PresenceErrorCode["PERMISSION_DENIED"] = "presence/permission-denied";
+})(PresenceErrorCode || (PresenceErrorCode = {}));
+/**
+ * Custom presence error class
+ */
+export class PresenceError extends Error {
+    code;
+    originalError;
+    constructor(code, message, originalError) {
+        super(message);
+        this.code = code;
+        this.originalError = originalError;
+        this.name = 'PresenceError';
+    }
+    /**
+     * Get user-friendly error message
+     */
+    getFriendlyMessage() {
+        switch (this.code) {
+            case PresenceErrorCode.GEOLOCATION_DENIED:
+                return 'Location access was denied. Please enable location services to use this feature.';
+            case PresenceErrorCode.GEOLOCATION_UNAVAILABLE:
+                return 'Location services are not available on this device.';
+            case PresenceErrorCode.GEOLOCATION_TIMEOUT:
+                return 'Location request timed out. Please try again.';
+            case PresenceErrorCode.USER_NOT_AUTHENTICATED:
+                return 'Please sign in to use presence features.';
+            case PresenceErrorCode.NETWORK_ERROR:
+                return 'Network connection error. Please check your internet connection.';
+            case PresenceErrorCode.BROWSER_NOT_SUPPORTED:
+                return 'Your browser does not support all required features.';
+            case PresenceErrorCode.SESSION_EXPIRED:
+                return 'Your session has expired. Please refresh the page.';
+            default:
+                return this.message || 'An unknown error occurred.';
+        }
+    }
+    /**
+     * Check if error is retryable
+     */
+    isRetryable() {
+        const retryableCodes = [
+            PresenceErrorCode.NETWORK_ERROR,
+            PresenceErrorCode.GEOLOCATION_TIMEOUT,
+            PresenceErrorCode.DATABASE_ERROR
+        ];
+        return retryableCodes.includes(this.code);
+    }
+    /**
+     * Check if error requires user action
+     */
+    requiresUserAction() {
+        const userActionCodes = [
+            PresenceErrorCode.GEOLOCATION_DENIED,
+            PresenceErrorCode.USER_NOT_AUTHENTICATED,
+            PresenceErrorCode.PERMISSION_DENIED
+        ];
+        return userActionCodes.includes(this.code);
+    }
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,21 @@
+import { FirekitAuthError } from '../types/auth.js';
+/**
+ * Creates a standardized FirekitAuthError with context
+ * @param {any} error Original error object
+ * @param {string} context Context of the operation that failed
+ * @returns {FirekitAuthError} Standardized error object
+ */
+export declare function createAuthError(error: any, context: string): FirekitAuthError;
+/**
+ * Validates that a current user exists and returns the user
+ * @param {any} auth Firebase auth instance
+ * @returns {any} Current Firebase user
+ * @throws {FirekitAuthError} If no authenticated user found
+ */
+export declare function validateCurrentUser(auth: any): any;
+/**
+ * Handles Firebase authentication errors and throws FirekitAuthError with friendly message
+ * @param {any} error Original Firebase error
+ * @returns {never} Never returns, always throws
+ */
+export declare function handleAuthError(error: any): never;

package/dist/utils/errors.js

@@ -0,0 +1,35 @@
+import { FirekitAuthError, AuthErrorCode } from '../types/auth.js';
+/**
+ * Creates a standardized FirekitAuthError with context
+ * @param {any} error Original error object
+ * @param {string} context Context of the operation that failed
+ * @returns {FirekitAuthError} Standardized error object
+ */
+export function createAuthError(error, context) {
+    const code = error.code;
+    return new FirekitAuthError(code || `${context}-failed`, `Failed to ${context}: ${error.message}`);
+}
+/**
+ * Validates that a current user exists and returns the user
+ * @param {any} auth Firebase auth instance
+ * @returns {any} Current Firebase user
+ * @throws {FirekitAuthError} If no authenticated user found
+ */
+export function validateCurrentUser(auth) {
+    const user = auth.currentUser;
+    if (!user) {
+        throw new FirekitAuthError(AuthErrorCode.USER_NOT_FOUND, 'No authenticated user found.');
+    }
+    return user;
+}
+/**
+ * Handles Firebase authentication errors and throws FirekitAuthError with friendly message
+ * @param {any} error Original Firebase error
+ * @returns {never} Never returns, always throws
+ */
+export function handleAuthError(error) {
+    const code = error.code;
+    const firekitError = new FirekitAuthError(code, error.message, error);
+    // Use the existing getFriendlyMessage method from FirekitAuthError
+    throw new FirekitAuthError(code, firekitError.getFriendlyMessage(), error);
+}

package/dist/utils/firestore.d.ts

@@ -0,0 +1,9 @@
+import type { Firestore } from 'firebase/firestore';
+import type { User } from 'firebase/auth';
+/**
+ * Updates user data in Firestore with comprehensive profile information
+ * @param {Firestore} firestore Firestore instance
+ * @param {User} user Firebase user object
+ * @returns {Promise<void>} Promise that resolves when update completes
+ */
+export declare function updateUserInFirestore(firestore: Firestore, user: User): Promise<void>;

package/dist/utils/firestore.js

@@ -0,0 +1,33 @@
+import { doc, setDoc, serverTimestamp } from 'firebase/firestore';
+/**
+ * Updates user data in Firestore with comprehensive profile information
+ * @param {Firestore} firestore Firestore instance
+ * @param {User} user Firebase user object
+ * @returns {Promise<void>} Promise that resolves when update completes
+ */
+export async function updateUserInFirestore(firestore, user) {
+    try {
+        const userRef = doc(firestore, 'users', user.uid);
+        const userData = {
+            uid: user.uid,
+            email: user.email,
+            emailVerified: user.emailVerified,
+            displayName: user.displayName,
+            photoURL: user.photoURL,
+            phoneNumber: user.phoneNumber,
+            isAnonymous: user.isAnonymous,
+            providerId: user.providerId,
+            providerData: user.providerData,
+            metadata: {
+                creationTime: user.metadata.creationTime,
+                lastSignInTime: user.metadata.lastSignInTime
+            },
+            lastUpdated: serverTimestamp()
+        };
+        await setDoc(userRef, userData, { merge: true });
+    }
+    catch (error) {
+        console.error('Failed to update user in Firestore:', error);
+        // Don't throw here to avoid blocking auth operations
+    }
+}

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export { mapFirebaseUserToProfile } from './user.js';
+export { updateUserInFirestore } from './firestore.js';
+export { createAuthError, validateCurrentUser, handleAuthError } from './errors.js';
+export { createGoogleProvider, createFacebookProvider, createAppleProvider } from './providers.js';

package/dist/utils/index.js

@@ -0,0 +1,8 @@
+// User utilities
+export { mapFirebaseUserToProfile } from './user.js';
+// Firestore utilities
+export { updateUserInFirestore } from './firestore.js';
+// Error handling utilities
+export { createAuthError, validateCurrentUser, handleAuthError } from './errors.js';
+// Provider utilities
+export { createGoogleProvider, createFacebookProvider, createAppleProvider } from './providers.js';

package/dist/utils/providers.d.ts

@@ -0,0 +1,16 @@
+import { GoogleAuthProvider, FacebookAuthProvider, OAuthProvider } from 'firebase/auth';
+/**
+ * Creates a configured Google Auth provider
+ * @returns {GoogleAuthProvider} Configured Google provider
+ */
+export declare function createGoogleProvider(): GoogleAuthProvider;
+/**
+ * Creates a configured Facebook Auth provider
+ * @returns {FacebookAuthProvider} Configured Facebook provider
+ */
+export declare function createFacebookProvider(): FacebookAuthProvider;
+/**
+ * Creates a configured Apple Auth provider
+ * @returns {OAuthProvider} Configured Apple provider
+ */
+export declare function createAppleProvider(): OAuthProvider;

package/dist/utils/providers.js

@@ -0,0 +1,30 @@
+import { GoogleAuthProvider, FacebookAuthProvider, OAuthProvider } from 'firebase/auth';
+/**
+ * Creates a configured Google Auth provider
+ * @returns {GoogleAuthProvider} Configured Google provider
+ */
+export function createGoogleProvider() {
+    const provider = new GoogleAuthProvider();
+    provider.addScope('email');
+    provider.addScope('profile');
+    return provider;
+}
+/**
+ * Creates a configured Facebook Auth provider
+ * @returns {FacebookAuthProvider} Configured Facebook provider
+ */
+export function createFacebookProvider() {
+    const provider = new FacebookAuthProvider();
+    provider.addScope('email');
+    return provider;
+}
+/**
+ * Creates a configured Apple Auth provider
+ * @returns {OAuthProvider} Configured Apple provider
+ */
+export function createAppleProvider() {
+    const provider = new OAuthProvider('apple.com');
+    provider.addScope('email');
+    provider.addScope('name');
+    return provider;
+}

package/dist/utils/user.d.ts

@@ -0,0 +1,8 @@
+import type { User } from 'firebase/auth';
+import type { UserProfile } from '../types/auth.js';
+/**
+ * Maps Firebase User to UserProfile interface
+ * @param {User} user Firebase user object
+ * @returns {UserProfile} Mapped user profile
+ */
+export declare function mapFirebaseUserToProfile(user: User): UserProfile;

package/dist/utils/user.js

@@ -0,0 +1,29 @@
+/**
+ * Maps Firebase User to UserProfile interface
+ * @param {User} user Firebase user object
+ * @returns {UserProfile} Mapped user profile
+ */
+export function mapFirebaseUserToProfile(user) {
+    return {
+        uid: user.uid,
+        email: user.email,
+        displayName: user.displayName,
+        photoURL: user.photoURL,
+        phoneNumber: user.phoneNumber,
+        emailVerified: user.emailVerified,
+        isAnonymous: user.isAnonymous,
+        providerId: user.providerId,
+        metadata: {
+            creationTime: user.metadata.creationTime,
+            lastSignInTime: user.metadata.lastSignInTime
+        },
+        providerData: user.providerData.map((provider) => ({
+            providerId: provider.providerId,
+            uid: provider.uid,
+            displayName: provider.displayName,
+            email: provider.email,
+            phoneNumber: provider.phoneNumber,
+            photoURL: provider.photoURL
+        }))
+    };
+}