@sadikkhan02/adapter-fcm

Mobile & Web Push notification adapter for NotifyKit using Firebase Cloud Messaging (FCM).

This package delivers push notifications across Android, iOS (APNs through FCM), and Web browsers via Google Firebase Cloud Messaging v1 API. It conforms to the PushProvider contract, stringifies non-string data payloads, and handles token invalidation gracefully.

Installation

npm install @sadikkhan02/notifykit @sadikkhan02/adapter-fcm firebase-admin

Note: firebase-admin is declared as an external peer dependency to allow consumers control over SDK version pinning, Google Cloud environment authentication, and Firebase App pooling.

Configuration & Credentials

FCM requires Google Cloud service account credentials with the Firebase Cloud Messaging API Admin role.

Environment Variables

Precedence Order

The adapter resolves service account credentials in the following order:

1. Direct serviceAccount parameter in new FcmPushProvider({ serviceAccount: ... }) (object, JSON string, or file path)
2. process.env.FCM_SERVICE_ACCOUNT_JSON
3. process.env.GOOGLE_APPLICATION_CREDENTIALS
4. Pre-initialized Firebase app or messaging client injected in options

Usage

import { createNotifier } from '@sadikkhan02/notifykit';
import { FcmPushProvider } from '@sadikkhan02/adapter-fcm';

const pushProvider = new FcmPushProvider({
  // Can be an object, JSON string, or file path:
  serviceAccount: process.env.FCM_SERVICE_ACCOUNT_JSON,
});

const notifier = createNotifier({
  providers: {
    push: {
      type: 'fcm',
      adapter: pushProvider,
    },
  },
});

// Register push notification template
notifier.registerTemplate('new-message', '{{sender}} sent you a new message: {{preview}}');

// Enqueue push notification (returns immediately with jobId)
const { jobId } = await notifier.notify({
  to: { pushToken: 'fcm_device_registration_token_xyz...' },
  channels: ['push'],
  template: 'new-message',
  data: {
    sender: 'Sarah',
    preview: 'Hey, are you free for a call?',
    // Data values are automatically stringified for FCM compliance
    conversationId: 'conv_123',
  },
});

// Start processing push queue
notifier.startWorker({ channels: ['push'], concurrency: 20 });

Error Classification & DLQ Routing

FCM error codes are categorized cleanly between transient network/server glitches and permanent token invalidations:

Automatic Private Key Sanitization

All error logs and provider results automatically strip private keys (BEGIN PRIVATE KEY), bearer tokens, and client secrets.

License

MIT