npm package: @mrcuongnt/fcm-node-receiver
Description: A module to subscribe to GCM/FCM and receive notifications within a node process. v2 is compatible with the latest FCM registration endpoints.
Author: javajuice1337
Latest version: 2.2.6

> [!WARNING]
> This library is based on reverse‑engineering legacy GCM/FCM protocols and is **not actively maintained**.  
> It is provided for reference/experimentation only and may stop working if Google/Firebase change their internals.

## fcm-node-receiver

**Repository**: `git@github.com:cuongdev/fcm-node-receiver.git`

**Goal**: receive push notifications sent via Firebase Cloud Messaging (FCM) inside a Node.js process by emulating a device client and using the latest known FCM registration endpoints.

The original [push-receiver](https://github.com/MatthieuLemoine/push-receiver) FCM registration endpoint was [deprecated and removed as of June 20, 2024](https://firebase.google.com/support/faq#fcm-depr-features).  
This project uses the newer Firebase Installation + FCM registration APIs where possible, but still depends on undocumented behaviour which may break over time.

### When should I use `fcm-node-receiver`?

- **Receive** push notifications in a Node.js process (e.g. for bots, bridges, or background workers).
- Communicate with a Node.js server through Firebase Cloud Messaging infrastructure.

### When should I not use `fcm-node-receiver`?

- You only need to **send** notifications → use official Firebase Admin SDK / client SDKs instead.
- Your app runs on an officially supported FCM platform (Android, iOS, Web) → use the official clients instead of emulating a Node client.

### Install

```bash
npm install --save fcm-node-receiver
```

### Requirements

- Node v8+ (async/await support).
- Firebase `apiKey`, `appID`, and `projectID` to receive notifications.

### Basic usage

```javascript
const { register, listen } = require('fcm-node-receiver');

// Firebase config
const config = {
  firebase: {
    apiKey: 'XXxxXxX0x0x-Xxxx0-X0Xxxxx_0xxXx_XX0xXxX',
    appID: '1:000000000000:android:xxx0xxxx0000x000xxx000',
    projectID: 'the-app-name',
  },
  vapidKey: '', // optional
};

// First time
// Register to FCM and obtain credentials
const credentials = await register(config); // Call once and persist the credentials somewhere
storeCredentials(credentials);
const fcmToken = credentials.fcm.token; // Use this token to send notifications via FCM
sendTokenToBackendOrWhatever(fcmToken);

// Next times (reuse stored credentials)
const savedCredentials = getSavedCredentials(); // Load from file/db/...
// persistentIds is the list of notification ids received, to avoid replaying old notifications.
const persistentIds = getPersistentIds() || [];
await listen({ ...savedCredentials, persistentIds }, onNotification);

// Called on new notification
function onNotification({ notification, persistentId }) {
  // Persist the new persistentId
  updatePersistentIds([...persistentIds, persistentId]);
  // Handle the notification payload
  display(notification);
}
```

### Test notification (HTTP v1)

To test, you can use the `scripts/send/index.js` script in this repo, which uses the **FCM HTTP v1** send endpoint.
You need a Firebase service account JSON file and the FCM registration token as arguments:

```bash
node scripts/send \
  --serviceAccountPath="/path/to/serviceAccount.json" \
  --token="<FCM_TOKEN>" \
  --projectId="<FIREBASE_PROJECT_ID>"
```

The `projectId` argument is optional if `project_id` is present in the service account JSON.

### Acknowledgements

- [push-receiver](https://github.com/MatthieuLemoine/push-receiver) for the original implementation.
- [Aracna FCM](https://github.com/queelag/fcm) for the latest FCM registration endpoints.