@umituz/react-native-firebase 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Ümit UZ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,215 @@
+# @umituz/react-native-firebase
+
+Domain-Driven Design Firebase client for React Native apps with type-safe operations and singleton pattern.
+
+Built with **SOLID**, **DRY**, and **KISS** principles.
+
+## Installation
+
+```bash
+npm install @umituz/react-native-firebase
+```
+
+## Peer Dependencies
+
+- `firebase` >= 11.0.0
+- `react` >= 18.2.0
+- `react-native` >= 0.74.0
+- `@react-native-async-storage/async-storage` >= 1.21.0
+
+## Features
+
+- ✅ Domain-Driven Design (DDD) architecture
+- ✅ SOLID principles (Single Responsibility, Open/Closed, etc.)
+- ✅ DRY (Don't Repeat Yourself)
+- ✅ KISS (Keep It Simple, Stupid)
+- ✅ Singleton pattern for single client instance
+- ✅ Type-safe Firebase operations
+- ✅ Platform-specific initialization (Web vs Native)
+- ✅ **Security**: No .env reading - configuration must be provided by app
+- ✅ Works with Expo and React Native CLI
+
+## Important: Configuration
+
+**This package does NOT read from .env files for security reasons.** You must provide configuration from your application code.
+
+### Why?
+
+- **Security**: Prevents accidental exposure of credentials
+- **Flexibility**: Works with any configuration source (Constants, config files, etc.)
+- **Multi-app support**: Same package can be used across hundreds of apps with different configs
+
+## Usage
+
+### 1. Initialize Firebase Client
+
+Initialize the client early in your app (e.g., in `App.tsx` or `index.js`):
+
+```typescript
+import { initializeFirebase } from '@umituz/react-native-firebase';
+import Constants from 'expo-constants';
+
+// Get configuration from your app's config source
+const config = {
+  apiKey: Constants.expoConfig?.extra?.firebaseApiKey || process.env.EXPO_PUBLIC_FIREBASE_API_KEY!,
+  authDomain: Constants.expoConfig?.extra?.firebaseAuthDomain || process.env.EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN!,
+  projectId: Constants.expoConfig?.extra?.firebaseProjectId || process.env.EXPO_PUBLIC_FIREBASE_PROJECT_ID!,
+  storageBucket: Constants.expoConfig?.extra?.firebaseStorageBucket,
+  messagingSenderId: Constants.expoConfig?.extra?.firebaseMessagingSenderId,
+  appId: Constants.expoConfig?.extra?.firebaseAppId,
+};
+
+// Initialize
+const app = initializeFirebase(config);
+
+if (!app) {
+  console.error('Failed to initialize Firebase');
+}
+```
+
+### 2. Use Firebase Services
+
+#### Direct Access
+
+```typescript
+import { getFirebaseApp, getFirebaseAuth, getFirestore } from '@umituz/react-native-firebase';
+
+// Get instances
+const app = getFirebaseApp();
+const auth = getFirebaseAuth();
+const db = getFirestore();
+
+// Use Firebase features
+import { signInWithEmailAndPassword } from 'firebase/auth';
+import { collection, getDocs } from 'firebase/firestore';
+
+// Sign in
+await signInWithEmailAndPassword(auth, email, password);
+
+// Query Firestore
+const querySnapshot = await getDocs(collection(db, 'users'));
+```
+
+### 3. Error Handling
+
+```typescript
+import {
+  getFirebaseApp,
+  FirebaseInitializationError,
+  FirebaseConfigurationError,
+} from '@umituz/react-native-firebase';
+
+try {
+  const app = getFirebaseApp();
+  // Use app
+} catch (error) {
+  if (error instanceof FirebaseInitializationError) {
+    console.error('Firebase not initialized:', error.message);
+  } else if (error instanceof FirebaseConfigurationError) {
+    console.error('Invalid configuration:', error.message);
+  }
+}
+```
+
+### 4. Check Initialization Status
+
+```typescript
+import {
+  isFirebaseInitialized,
+  getFirebaseInitializationError,
+} from '@umituz/react-native-firebase';
+
+if (isFirebaseInitialized()) {
+  console.log('Firebase is ready');
+} else {
+  const error = getFirebaseInitializationError();
+  console.error('Initialization error:', error);
+}
+```
+
+## Architecture
+
+### SOLID Principles
+
+- **Single Responsibility**: Each class has one clear purpose
+  - `FirebaseConfigValidator`: Only validates configuration
+  - `FirebaseAppInitializer`: Only initializes Firebase App
+  - `FirebaseAuthInitializer`: Only initializes Auth
+  - `FirebaseFirestoreInitializer`: Only initializes Firestore
+  - `FirebaseClient`: Only orchestrates initialization
+
+- **Open/Closed**: Extensible through configuration, closed for modification
+
+- **Dependency Inversion**: Depends on abstractions (interfaces), not concrete implementations
+
+### DRY (Don't Repeat Yourself)
+
+- Shared initialization logic extracted to specialized classes
+- No code duplication across platforms
+
+### KISS (Keep It Simple, Stupid)
+
+- Simple, focused classes
+- Clear responsibilities
+- Easy to understand and maintain
+
+## API
+
+### Functions
+
+- `initializeFirebase(config)`: Initialize Firebase client with configuration
+- `getFirebaseApp()`: Get Firebase app instance (throws if not initialized)
+- `getFirebaseAuth()`: Get Firebase Auth instance (throws if not initialized)
+- `getFirestore()`: Get Firestore instance (throws if not initialized)
+- `isFirebaseInitialized()`: Check if client is initialized
+- `getFirebaseInitializationError()`: Get initialization error if any
+- `resetFirebaseClient()`: Reset client instance (useful for testing)
+
+### Types
+
+- `FirebaseConfig`: Configuration interface
+- `FirebaseApp`: Firebase app type
+- `Auth`: Firebase Auth type
+- `Firestore`: Firestore type
+
+### Errors
+
+- `FirebaseError`: Base error class
+- `FirebaseInitializationError`: Initialization errors
+- `FirebaseConfigurationError`: Configuration errors
+- `FirebaseAuthError`: Authentication errors
+- `FirebaseFirestoreError`: Firestore errors
+
+## Integration with Expo
+
+For Expo apps, configure in `app.config.js`:
+
+```javascript
+module.exports = () => {
+  return {
+    expo: {
+      // ... other config
+      extra: {
+        firebaseApiKey: process.env.EXPO_PUBLIC_FIREBASE_API_KEY,
+        firebaseAuthDomain: process.env.EXPO_PUBLIC_FIREBASE_AUTH_DOMAIN,
+        firebaseProjectId: process.env.EXPO_PUBLIC_FIREBASE_PROJECT_ID,
+        firebaseStorageBucket: process.env.EXPO_PUBLIC_FIREBASE_STORAGE_BUCKET,
+        firebaseMessagingSenderId: process.env.EXPO_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
+        firebaseAppId: process.env.EXPO_PUBLIC_FIREBASE_APP_ID,
+      },
+    },
+  };
+};
+```
+
+## Security Best Practices
+
+1. **Never commit credentials**: Use environment variables or secure config files
+2. **Use proper Firebase security rules**: Configure Firestore and Storage rules
+3. **Implement RLS**: Use Firebase security rules for data protection
+4. **Clear user data on logout**: Always clear user data on logout (GDPR compliance)
+
+## License
+
+MIT
+

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@umituz/react-native-firebase",
+  "version": "1.0.0",
+  "description": "Domain-Driven Design Firebase client for React Native apps with type-safe operations and singleton pattern",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "version:patch": "npm version patch -m 'chore: release v%s'",
+    "version:minor": "npm version minor -m 'chore: release v%s'",
+    "version:major": "npm version major -m 'chore: release v%s'"
+  },
+  "keywords": [
+    "react-native",
+    "firebase",
+    "firestore",
+    "authentication",
+    "analytics",
+    "crashlytics",
+    "ddd",
+    "domain-driven-design",
+    "type-safe",
+    "singleton",
+    "solid",
+    "dry",
+    "kiss"
+  ],
+  "author": "Ümit UZ <umit@umituz.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/umituz/react-native-firebase.git"
+  },
+  "peerDependencies": {
+    "firebase": ">=11.0.0",
+    "@react-native-async-storage/async-storage": ">=1.21.0",
+    "react": ">=18.2.0",
+    "react-native": ">=0.74.0"
+  },
+  "devDependencies": {
+    "firebase": "^11.10.0",
+    "@react-native-async-storage/async-storage": "^1.24.0",
+    "@types/react": "^18.2.45",
+    "@types/react-native": "^0.73.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.3.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}
+

package/src/application/ports/IFirebaseClient.ts

@@ -0,0 +1,51 @@
+/**
+ * Firebase Client Port (Interface)
+ *
+ * Domain-Driven Design: Application layer port for Firebase client
+ * Defines the contract for Firebase client operations
+ */
+
+import type { FirebaseApp } from 'firebase/app';
+import type { Auth } from 'firebase/auth';
+import type { Firestore } from 'firebase/firestore';
+
+/**
+ * Firebase Client Interface
+ * Defines the contract for Firebase client operations
+ */
+export interface IFirebaseClient {
+  /**
+   * Get the Firebase app instance
+   * @throws {FirebaseInitializationError} If client is not initialized
+   */
+  getApp(): FirebaseApp;
+
+  /**
+   * Get the Firebase Auth instance
+   * @throws {FirebaseInitializationError} If client is not initialized
+   */
+  getAuth(): Auth;
+
+  /**
+   * Get the Firestore instance
+   * @throws {FirebaseInitializationError} If client is not initialized
+   */
+  getFirestore(): Firestore;
+
+  /**
+   * Check if client is initialized
+   */
+  isInitialized(): boolean;
+
+  /**
+   * Get initialization error if any
+   */
+  getInitializationError(): string | null;
+
+  /**
+   * Reset the client instance
+   * Useful for testing
+   */
+  reset(): void;
+}
+

package/src/domain/errors/FirebaseError.ts

@@ -0,0 +1,93 @@
+/**
+ * Firebase Domain Errors
+ *
+ * Domain-Driven Design: Error types for Firebase operations
+ */
+
+/**
+ * Base Firebase Error
+ */
+export class FirebaseError extends Error {
+  constructor(
+    message: string,
+    public readonly code?: string,
+    public readonly originalError?: unknown
+  ) {
+    super(message);
+    this.name = 'FirebaseError';
+    Object.setPrototypeOf(this, FirebaseError.prototype);
+  }
+}
+
+/**
+ * Initialization Error
+ * Thrown when Firebase client fails to initialize
+ */
+export class FirebaseInitializationError extends FirebaseError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, 'INITIALIZATION_ERROR', originalError);
+    this.name = 'FirebaseInitializationError';
+    Object.setPrototypeOf(this, FirebaseInitializationError.prototype);
+  }
+}
+
+/**
+ * Configuration Error
+ * Thrown when required configuration is missing or invalid
+ */
+export class FirebaseConfigurationError extends FirebaseError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, 'CONFIGURATION_ERROR', originalError);
+    this.name = 'FirebaseConfigurationError';
+    Object.setPrototypeOf(this, FirebaseConfigurationError.prototype);
+  }
+}
+
+/**
+ * Analytics Error
+ * Thrown when analytics operations fail
+ */
+export class FirebaseAnalyticsError extends FirebaseError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, 'ANALYTICS_ERROR', originalError);
+    this.name = 'FirebaseAnalyticsError';
+    Object.setPrototypeOf(this, FirebaseAnalyticsError.prototype);
+  }
+}
+
+/**
+ * Crashlytics Error
+ * Thrown when crashlytics operations fail
+ */
+export class FirebaseCrashlyticsError extends FirebaseError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, 'CRASHLYTICS_ERROR', originalError);
+    this.name = 'FirebaseCrashlyticsError';
+    Object.setPrototypeOf(this, FirebaseCrashlyticsError.prototype);
+  }
+}
+
+/**
+ * Auth Error
+ * Thrown when authentication operations fail
+ */
+export class FirebaseAuthError extends FirebaseError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, 'AUTH_ERROR', originalError);
+    this.name = 'FirebaseAuthError';
+    Object.setPrototypeOf(this, FirebaseAuthError.prototype);
+  }
+}
+
+/**
+ * Firestore Error
+ * Thrown when Firestore operations fail
+ */
+export class FirebaseFirestoreError extends FirebaseError {
+  constructor(message: string, originalError?: unknown) {
+    super(message, 'FIRESTORE_ERROR', originalError);
+    this.name = 'FirebaseFirestoreError';
+    Object.setPrototypeOf(this, FirebaseFirestoreError.prototype);
+  }
+}
+

package/src/domain/value-objects/FirebaseConfig.ts

@@ -0,0 +1,54 @@
+/**
+ * Firebase Configuration Value Object
+ *
+ * Domain-Driven Design: Value object for Firebase configuration
+ */
+
+/**
+ * Firebase Configuration
+ * Required configuration for initializing Firebase client
+ */
+export interface FirebaseConfig {
+  /**
+   * Firebase API Key
+   */
+  apiKey: string;
+
+  /**
+   * Firebase Auth Domain
+   */
+  authDomain: string;
+
+  /**
+   * Firebase Project ID
+   */
+  projectId: string;
+
+  /**
+   * Firebase Storage Bucket
+   */
+  storageBucket?: string;
+
+  /**
+   * Firebase Messaging Sender ID
+   */
+  messagingSenderId?: string;
+
+  /**
+   * Firebase App ID
+   */
+  appId?: string;
+
+  /**
+   * Optional: Custom storage adapter for Auth persistence
+   * If not provided, AsyncStorage will be used for React Native
+   */
+  authStorage?: {
+    getItem: (key: string) => Promise<string | null>;
+    setItem: (key: string, value: string) => Promise<void>;
+    removeItem: (key: string) => Promise<void>;
+  };
+}
+
+// Validation moved to FirebaseConfigValidator class (SOLID: Single Responsibility)
+

package/src/index.ts

@@ -0,0 +1,61 @@
+/**
+ * React Native Firebase - Public API
+ *
+ * Domain-Driven Design (DDD) Architecture
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all Firebase operations.
+ * ALL imports from the Firebase package MUST go through this file.
+ *
+ * Architecture:
+ * - domain: Entities, value objects, errors (business logic)
+ * - application: Ports (interfaces)
+ * - infrastructure: Firebase client implementation
+ * - presentation: Hooks (React integration)
+ *
+ * Usage:
+ *   import { initializeFirebase, getFirebaseApp, useFirebase } from '@umituz/react-native-firebase';
+ */
+
+// =============================================================================
+// DOMAIN LAYER - Business Logic
+// =============================================================================
+
+export {
+  FirebaseError,
+  FirebaseInitializationError,
+  FirebaseConfigurationError,
+  FirebaseAnalyticsError,
+  FirebaseCrashlyticsError,
+  FirebaseAuthError,
+  FirebaseFirestoreError,
+} from './domain/errors/FirebaseError';
+
+export type { FirebaseConfig } from './domain/value-objects/FirebaseConfig';
+
+// =============================================================================
+// APPLICATION LAYER - Ports
+// =============================================================================
+
+export type { IFirebaseClient } from './application/ports/IFirebaseClient';
+
+// =============================================================================
+// INFRASTRUCTURE LAYER - Implementation
+// =============================================================================
+
+export {
+  initializeFirebase,
+  getFirebaseApp,
+  getFirebaseAuth,
+  getFirestore,
+  isFirebaseInitialized,
+  getFirebaseInitializationError,
+  resetFirebaseClient,
+  firebaseClient,
+} from './infrastructure/config/FirebaseClient';
+
+export type {
+  FirebaseApp,
+  Auth,
+  Firestore,
+} from './infrastructure/config/FirebaseClient';
+

package/src/infrastructure/config/FirebaseClient.ts

@@ -0,0 +1,242 @@
+/**
+ * Firebase Client - Infrastructure Layer
+ *
+ * Domain-Driven Design: Infrastructure implementation of Firebase client
+ * Singleton pattern for managing Firebase client instance
+ *
+ * IMPORTANT: This package does NOT read from .env files.
+ * Configuration must be provided by the application.
+ *
+ * SOLID Principles:
+ * - Single Responsibility: Only orchestrates initialization, delegates to specialized classes
+ * - Open/Closed: Extensible through configuration, closed for modification
+ * - Dependency Inversion: Depends on abstractions (interfaces), not concrete implementations
+ */
+
+import type { FirebaseApp } from 'firebase/app';
+import type { Auth } from 'firebase/auth';
+import type { Firestore } from 'firebase/firestore';
+import type { FirebaseConfig } from '../../domain/value-objects/FirebaseConfig';
+import { FirebaseInitializationError } from '../../domain/errors/FirebaseError';
+import type { IFirebaseClient } from '../../application/ports/IFirebaseClient';
+import { FirebaseConfigValidator } from './validators/FirebaseConfigValidator';
+import { FirebaseAppInitializer } from './initializers/FirebaseAppInitializer';
+import { FirebaseAuthInitializer } from './initializers/FirebaseAuthInitializer';
+import { FirebaseFirestoreInitializer } from './initializers/FirebaseFirestoreInitializer';
+
+/**
+ * Firebase Client Singleton
+ * Orchestrates Firebase initialization using specialized initializers
+ */
+class FirebaseClientSingleton implements IFirebaseClient {
+  private static instance: FirebaseClientSingleton | null = null;
+  private app: FirebaseApp | null = null;
+  private auth: Auth | null = null;
+  private db: Firestore | null = null;
+  private initializationError: string | null = null;
+
+  private constructor() {
+    // Private constructor to enforce singleton pattern
+  }
+
+  /**
+   * Get singleton instance
+   */
+  static getInstance(): FirebaseClientSingleton {
+    if (!FirebaseClientSingleton.instance) {
+      FirebaseClientSingleton.instance = new FirebaseClientSingleton();
+    }
+    return FirebaseClientSingleton.instance;
+  }
+
+  /**
+   * Initialize Firebase client with configuration
+   * Configuration must be provided by the application (not from .env)
+   *
+   * @param config - Firebase configuration
+   * @returns Firebase app instance or null if initialization fails
+   */
+  initialize(config: FirebaseConfig): FirebaseApp | null {
+    // Return existing instance if already initialized
+    if (this.app) {
+      return this.app;
+    }
+
+    // Don't retry if initialization already failed
+    if (this.initializationError) {
+      return null;
+    }
+
+    try {
+      // Validate configuration
+      FirebaseConfigValidator.validate(config);
+
+      // Initialize Firebase App
+      this.app = FirebaseAppInitializer.initialize(config);
+
+      // Initialize Auth
+      this.auth = FirebaseAuthInitializer.initialize(this.app, config);
+
+      // Initialize Firestore
+      this.db = FirebaseFirestoreInitializer.initialize(this.app);
+
+      return this.app;
+    } catch (error) {
+      this.initializationError =
+        error instanceof Error
+          ? error.message
+          : 'Failed to initialize Firebase client';
+      return null;
+    }
+  }
+
+  /**
+   * Get the Firebase app instance
+   * @throws {FirebaseInitializationError} If client is not initialized
+   */
+  getApp(): FirebaseApp {
+    if (!this.app) {
+      const errorMsg =
+        this.initializationError ||
+        'Firebase client not initialized. Call initialize() first with configuration.';
+      throw new FirebaseInitializationError(errorMsg);
+    }
+    return this.app;
+  }
+
+  /**
+   * Get the Firebase Auth instance
+   * @throws {FirebaseInitializationError} If client is not initialized
+   */
+  getAuth(): Auth {
+    if (!this.auth) {
+      const errorMsg =
+        this.initializationError ||
+        'Firebase client not initialized. Call initialize() first with configuration.';
+      throw new FirebaseInitializationError(errorMsg);
+    }
+    return this.auth;
+  }
+
+  /**
+   * Get the Firestore instance
+   * @throws {FirebaseInitializationError} If client is not initialized
+   */
+  getFirestore(): Firestore {
+    if (!this.db) {
+      const errorMsg =
+        this.initializationError ||
+        'Firebase client not initialized. Call initialize() first with configuration.';
+      throw new FirebaseInitializationError(errorMsg);
+    }
+    return this.db;
+  }
+
+  /**
+   * Check if client is initialized
+   */
+  isInitialized(): boolean {
+    return this.app !== null;
+  }
+
+  /**
+   * Get initialization error if any
+   */
+  getInitializationError(): string | null {
+    return this.initializationError;
+  }
+
+  /**
+   * Reset the client instance
+   * Useful for testing
+   */
+  reset(): void {
+    this.app = null;
+    this.auth = null;
+    this.db = null;
+    this.initializationError = null;
+  }
+}
+
+/**
+ * Singleton instance
+ */
+export const firebaseClient = FirebaseClientSingleton.getInstance();
+
+/**
+ * Initialize Firebase client
+ * This is the main entry point for applications
+ *
+ * @param config - Firebase configuration (must be provided by app, not from .env)
+ * @returns Firebase app instance or null if initialization fails
+ *
+ * @example
+ * ```typescript
+ * import { initializeFirebase } from '@umituz/react-native-firebase';
+ *
+ * const config = {
+ *   apiKey: 'your-api-key',
+ *   authDomain: 'your-project.firebaseapp.com',
+ *   projectId: 'your-project-id',
+ * };
+ *
+ * const app = initializeFirebase(config);
+ * ```
+ */
+export function initializeFirebase(
+  config: FirebaseConfig
+): FirebaseApp | null {
+  return firebaseClient.initialize(config);
+}
+
+/**
+ * Get Firebase app instance
+ * @throws {FirebaseInitializationError} If client is not initialized
+ */
+export function getFirebaseApp(): FirebaseApp {
+  return firebaseClient.getApp();
+}
+
+/**
+ * Get Firebase Auth instance
+ * @throws {FirebaseInitializationError} If client is not initialized
+ */
+export function getFirebaseAuth(): Auth {
+  return firebaseClient.getAuth();
+}
+
+/**
+ * Get Firestore instance
+ * @throws {FirebaseInitializationError} If client is not initialized
+ */
+export function getFirestore(): Firestore {
+  return firebaseClient.getFirestore();
+}
+
+/**
+ * Check if Firebase client is initialized
+ */
+export function isFirebaseInitialized(): boolean {
+  return firebaseClient.isInitialized();
+}
+
+/**
+ * Get initialization error if any
+ */
+export function getFirebaseInitializationError(): string | null {
+  return firebaseClient.getInitializationError();
+}
+
+/**
+ * Reset Firebase client instance
+ * Useful for testing
+ */
+export function resetFirebaseClient(): void {
+  firebaseClient.reset();
+}
+
+// Export types
+export type { FirebaseApp } from 'firebase/app';
+export type { Auth } from 'firebase/auth';
+export type { Firestore } from 'firebase/firestore';
+export type { FirebaseConfig } from '../../domain/value-objects/FirebaseConfig';

package/src/infrastructure/config/initializers/FirebaseAppInitializer.ts

@@ -0,0 +1,46 @@
+/**
+ * Firebase App Initializer
+ *
+ * Single Responsibility: Initialize Firebase App instance
+ */
+
+import { initializeApp, getApps, FirebaseApp } from 'firebase/app';
+import type { FirebaseConfig } from '../../../domain/value-objects/FirebaseConfig';
+import { FirebaseInitializationError } from '../../../domain/errors/FirebaseError';
+
+/**
+ * Initializes Firebase App
+ */
+export class FirebaseAppInitializer {
+  /**
+   * Initialize or get existing Firebase App
+   */
+  static initialize(config: FirebaseConfig): FirebaseApp {
+    // Return existing app if already initialized
+    const existingApps = getApps();
+    if (existingApps.length > 0) {
+      return existingApps[0];
+    }
+
+    try {
+      const firebaseConfig = {
+        apiKey: config.apiKey,
+        authDomain: config.authDomain,
+        projectId: config.projectId,
+        storageBucket: config.storageBucket,
+        messagingSenderId: config.messagingSenderId,
+        appId: config.appId,
+      };
+
+      return initializeApp(firebaseConfig);
+    } catch (error) {
+      throw new FirebaseInitializationError(
+        `Failed to initialize Firebase App: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`,
+        error
+      );
+    }
+  }
+}
+

package/src/infrastructure/config/initializers/FirebaseAuthInitializer.ts

@@ -0,0 +1,68 @@
+/**
+ * Firebase Auth Initializer
+ *
+ * Single Responsibility: Initialize Firebase Auth instance
+ */
+
+import { initializeAuth, getAuth } from 'firebase/auth';
+import type { Auth } from 'firebase/auth';
+import { Platform } from 'react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import type { FirebaseApp } from 'firebase/app';
+import type { FirebaseConfig } from '../../../domain/value-objects/FirebaseConfig';
+
+/**
+ * Initializes Firebase Auth
+ */
+export class FirebaseAuthInitializer {
+  /**
+   * Initialize Firebase Auth with platform-specific persistence
+   */
+  static initialize(app: FirebaseApp, config: FirebaseConfig): Auth {
+    try {
+      if (Platform.OS === 'web') {
+        return getAuth(app);
+      }
+
+      // Try React Native persistence
+      return this.initializeWithPersistence(app, config);
+    } catch (error: any) {
+      // If already initialized, get existing instance
+      if (error.code === 'auth/already-initialized') {
+        return getAuth(app);
+      }
+
+      /* eslint-disable-next-line no-console */
+      if (__DEV__) console.warn('Firebase Auth initialization error:', error);
+      return getAuth(app);
+    }
+  }
+
+  private static initializeWithPersistence(
+    app: FirebaseApp,
+    config: FirebaseConfig
+  ): Auth {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const authModule = require('firebase/auth');
+      const getReactNativePersistence = authModule.getReactNativePersistence;
+
+      if (!getReactNativePersistence) {
+        return getAuth(app);
+      }
+
+      const storage = config.authStorage || {
+        getItem: (key: string) => AsyncStorage.getItem(key),
+        setItem: (key: string, value: string) => AsyncStorage.setItem(key, value),
+        removeItem: (key: string) => AsyncStorage.removeItem(key),
+      };
+
+      return initializeAuth(app, {
+        persistence: getReactNativePersistence(storage),
+      });
+    } catch {
+      return getAuth(app);
+    }
+  }
+}
+

package/src/infrastructure/config/initializers/FirebaseFirestoreInitializer.ts

@@ -0,0 +1,54 @@
+/**
+ * Firebase Firestore Initializer
+ *
+ * Single Responsibility: Initialize Firestore instance
+ */
+
+import {
+  getFirestore,
+  initializeFirestore,
+  persistentLocalCache,
+} from 'firebase/firestore';
+import type { Firestore } from 'firebase/firestore';
+import { Platform } from 'react-native';
+import type { FirebaseApp } from 'firebase/app';
+
+/**
+ * Initializes Firestore
+ */
+export class FirebaseFirestoreInitializer {
+  /**
+   * Initialize Firestore with platform-specific cache configuration
+   */
+  static initialize(app: FirebaseApp): Firestore {
+    if (Platform.OS === 'web') {
+      return this.initializeForWeb(app);
+    }
+
+    // React Native: Use default persistence
+    return getFirestore(app);
+  }
+
+  private static initializeForWeb(app: FirebaseApp): Firestore {
+    try {
+      return initializeFirestore(app, {
+        localCache: persistentLocalCache(),
+      });
+    } catch (error: any) {
+      // If already initialized, get existing instance
+      if (error.code === 'failed-precondition') {
+        /* eslint-disable-next-line no-console */
+        if (__DEV__)
+          console.warn(
+            'Firestore already initialized, using existing instance'
+          );
+        return getFirestore(app);
+      }
+
+      /* eslint-disable-next-line no-console */
+      if (__DEV__) console.warn('Firestore initialization error:', error);
+      return getFirestore(app);
+    }
+  }
+}
+

package/src/infrastructure/config/validators/FirebaseConfigValidator.ts

@@ -0,0 +1,51 @@
+/**
+ * Firebase Configuration Validator
+ *
+ * Single Responsibility: Validates Firebase configuration
+ */
+
+import type { FirebaseConfig } from '../../../domain/value-objects/FirebaseConfig';
+import { FirebaseConfigurationError } from '../../../domain/errors/FirebaseError';
+
+/**
+ * Validates Firebase configuration
+ */
+export class FirebaseConfigValidator {
+  /**
+   * Validate Firebase configuration
+   * @throws {FirebaseConfigurationError} If configuration is invalid
+   */
+  static validate(config: FirebaseConfig): void {
+    if (!config.apiKey || typeof config.apiKey !== 'string') {
+      throw new FirebaseConfigurationError(
+        'Firebase API Key is required and must be a string'
+      );
+    }
+
+    if (!config.authDomain || typeof config.authDomain !== 'string') {
+      throw new FirebaseConfigurationError(
+        'Firebase Auth Domain is required and must be a string'
+      );
+    }
+
+    if (!config.projectId || typeof config.projectId !== 'string') {
+      throw new FirebaseConfigurationError(
+        'Firebase Project ID is required and must be a string'
+      );
+    }
+
+    if (config.apiKey.trim().length === 0) {
+      throw new FirebaseConfigurationError('Firebase API Key cannot be empty');
+    }
+
+    if (
+      config.apiKey.includes('your_firebase_api_key') ||
+      config.projectId.includes('your-project-id')
+    ) {
+      throw new FirebaseConfigurationError(
+        'Please replace placeholder values with actual Firebase credentials'
+      );
+    }
+  }
+}
+