Event Occurs (e.g., new booking)
         ↓
createNotification() called
         ↓
    ┌────┴────┐
    ↓         ↓
Firestore   FCM Push
Document    Notification
Created     Sent
    ↓         ↓
In-App      Device
Center      Wakes Up
    ↓         ↓
User sees   User taps
in app      notification
            ↓
        App opens to
        booking detail

// types/models/users.ts
export interface BaseUserInfo {
  // ... other fields ...
  fcmTokens?: {
    [deviceId: string]: {
      token: string;
      platform: "ios" | "android" | "web";
      deviceId: string;
      createdAt: number;
      lastUsed: number;
    };
  };
}

// firebase/server/notifications.ts
import { sendPushNotification } from "./fcm";

export async function createNotification<T extends NotificationTypeEnum>(
  { userId, type, data }: { userId: string; type: T; data: NotificationDataMap[T] }
) {
  // 1. Create Firestore notification document
  const notificationId = await createFirestoreNotification(...);

  // 2. Send FCM push notification (non-blocking)
  sendPushNotification(userId, type, data, notificationId).catch(console.error);

  return notificationId;
}

await sendPushNotification(
  userId,
  NotificationTypeEnum.NEW_BOOKING_REQUEST,
  { bookingId: "123", clientName: "John Doe" },
  notificationId,
);

await sendPushNotificationToMultipleUsers(
  userIds,
  NotificationTypeEnum.NEW_FEATURE,
  (userId) => ({ featureName: "Dark Mode" }),
  (userId) => notificationIdMap[userId],
);

const payload = buildNotificationPayload(
  NotificationTypeEnum.BOOKING_CONFIRMED,
  { bookingId: "123", artistName: "Jane Smith" },
);
// Returns: { title: "Booking Confirmed", body: "Jane Smith confirmed your booking", ... }

POST /api/notifications/register-fcm-token
Body: {
  token: string,
  deviceId: string,
  platform: "ios" | "android" | "web"
}

POST / api / notifications / remove - fcm - token;
Body: {
  deviceId: string;
}

POST / api / notifications / update - fcm - token - usage;
Body: {
  deviceId: string;
}

import { useRegisterFCMToken } from "@/hooks/notifications/useFCMTokenRegistration";

// Manual registration
const { mutate: registerToken } = useRegisterFCMToken();

registerToken({
  token: "fcm_token_from_device",
  deviceId: "unique_device_id",
  platform: "ios",
});

import { useFCMTokenAutoRegistration } from "@/hooks/notifications/useFCMTokenRegistration";

// In your React Native app
function App() {
  const [fcmToken, setFcmToken] = useState(null);
  const [deviceId, setDeviceId] = useState(null);

  // Auto-registers and manages token lifecycle
  const { isRegistered, isRegistering, error } = useFCMTokenAutoRegistration(
    fcmToken,
    deviceId,
    Platform.OS,
  );

  // ... rest of app
}

import * as Notifications from 'expo-notifications';
import * as Device from 'expo-device';
import { Platform } from 'react-native';
import { useRegisterFCMToken } from '@/hooks/notifications/useFCMTokenRegistration';

// 1. Request permissions
async function registerForPushNotifications() {
  if (!Device.isDevice) {
    console.log('Must use physical device for push notifications');
    return null;
  }

  // Check/request permissions
  const { status: existingStatus } = await Notifications.getPermissionsAsync();
  let finalStatus = existingStatus;

  if (existingStatus !== 'granted') {
    const { status } = await Notifications.requestPermissionsAsync();
    finalStatus = status;
  }

  if (finalStatus !== 'granted') {
    console.log('Permission not granted for push notifications');
    return null;
  }

  // Get token
  const token = (await Notifications.getExpoPushTokenAsync()).data;

  // For Android, set notification channel
  if (Platform.OS === 'android') {
    Notifications.setNotificationChannelAsync('default', {
      name: 'default',
      importance: Notifications.AndroidImportance.MAX,
      vibrationPattern: [0, 250, 250, 250],
      lightColor: '#FF231F7C',
    });
  }

  return token;
}

// 2. Use in your app
function App() {
  const { mutate: registerToken } = useRegisterFCMToken();

  useEffect(() => {
    registerForPushNotifications().then(token => {
      if (token) {
        registerToken({
          token,
          deviceId: Device.deviceId,
          platform: Platform.OS,
        });
      }
    });
  }, []);

  // 3. Handle notification taps
  useEffect(() => {
    const subscription = Notifications.addNotificationResponseReceivedListener(response => {
      const data = response.notification.request.content.data;

      // Navigate based on notification data
      if (data.screen === 'booking' && data.bookingId) {
        navigation.navigate('BookingDetail', { id: data.bookingId });
      }
    });

    return () => subscription.remove();
  }, []);

  return <YourApp />;
}

{
  "notification": {
    "title": "New Booking Request",
    "body": "John Doe sent you a booking request"
  },
  "data": {
    "notificationId": "firestore_notification_id",
    "type": "NEW_BOOKING_REQUEST",
    "bookingId": "123",
    "clientName": "John Doe",
    "screen": "booking"
  },
  "android": {
    "priority": "high",
    "notification": {
      "channelId": "default",
      "sound": "default"
    }
  },
  "apns": {
    "payload": {
      "aps": {
        "sound": "default",
        "badge": 1
      }
    }
  }
}

// In sendPushNotification.ts
if (response.failureCount > 0) {
  const failedTokens = /* ... extract failed tokens ... */;
  await cleanupInvalidTokens(userId, failedTokens);
}

const { mutate: removeToken } = useRemoveFCMToken();

// On logout
function handleLogout() {
  removeToken(deviceId);
  // ... rest of logout logic
}