Skip to main content

Firebase Service Documentation

Overview​

The Firebase service provides a comprehensive set of utilities for interacting with Firebase services in the Ring platform. It includes authentication, Firestore database operations, storage management, and real-time notifications.

Services​

Authentication​

  • User authentication with email/password
  • Social authentication (Google, GitHub)
  • Session management
  • Role-based access control

Firestore Database​

  • Real-time data synchronization
  • CRUD operations for entities and opportunities
  • Query optimization
  • Data validation and security rules

Storage​

  • File upload and management
  • Image optimization
  • Access control
  • CDN integration

Cloud Messaging (FCM)​

  • Real-time push notifications
  • Multi-device support
  • Background message handling
  • Notification delivery tracking
  • Token management
  • Custom notification types:
    • Chat messages
    • Opportunity updates
    • News articles
    • Entity notifications
    • System announcements

Usage​

Authentication​

import { auth } from '@/services/firebase';

// Sign in with email/password
await auth.signInWithEmailAndPassword(email, password);

// Sign in with Google
await auth.signInWithGoogle();

Firestore​

import { db } from '@/services/firebase';

// Get document
const doc = await db.collection('entities').doc(id).get();

// Query collection
const query = await db.collection('opportunities')
  .where('status', '==', 'active')
  .get();

Storage​

import { storage } from '@/services/firebase';

// Upload file
const ref = storage.ref(`images/${filename}`);
await ref.put(file);

// Get download URL
const url = await ref.getDownloadURL();

Cloud Messaging​

import { fcm } from '@/services/firebase';

// Register device token
await fcm.registerToken(token);

// Send notification
await fcm.sendNotification({
  title: 'New Message',
  body: 'You have a new message',
  data: {
    type: 'chat',
    chatId: '123'
  }
});

Configuration​

The Firebase service is configured through environment variables:

NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=

Security​

  • All Firebase services are protected by security rules
  • Authentication is required for sensitive operations
  • Data validation is performed on both client and server
  • Rate limiting is implemented for API calls

Error Handling​

The Firebase service includes comprehensive error handling:

try {
  await fcm.sendNotification(/* ... */);
} catch (error) {
  if (error instanceof FirebaseError) {
    // Handle Firebase-specific errors
    console.error('Firebase error:', error.code, error.message);
  } else {
    // Handle other errors
    console.error('Unexpected error:', error);
  }
}

Testing​

The Firebase service includes test utilities:

import { testUtils } from '@/services/firebase';

// Mock Firebase services
testUtils.mockFirebase();

// Test FCM functionality
await testUtils.testFCMNotification();

Contributing​

When adding new Firebase features:

  1. Update this documentation
  2. Add appropriate TypeScript types
  3. Include error handling
  4. Add test coverage
  5. Update security rules