npm.io
1.2.0 • Published 12h ago

@anh.votuan/fcm-http-v1

Licence
MIT
Version
1.2.0
Deps
3
Size
66 kB
Vulns
10
Weekly
0

@anh.votuan/fcm-http-v1

Receive Firebase Cloud Messaging (FCM) push notifications in a Node.js or Electron process, the way Chrome does: the process registers as a Web Push receiver, keeps a connection to mtalk.google.com and decrypts every message.

Uses the current Firebase Installations / FCM Registrations endpoints (the legacy fcm/send + server key flow was shut down by Google in June 2024).

  • Node.js >= 10 (Electron >= 4)
  • Web Push payloads in aesgcm and aes128gcm (RFC 8291)
  • No HTTP library: Node built-ins only; honours HTTPS_PROXY / HTTP_PROXY / NO_PROXY for the registration requests

Install

npm install @anh.votuan/fcm-http-v1

Usage

const { register, listen } = require('@anh.votuan/fcm-http-v1');

const config = {
  firebase: {
    apiKey: '<web api key>',
    appID: '<web app id>',
    projectID: '<project id>',
  },
  vapidKey: '', // optional
};

async function start(storage) {
  // Register once and keep the credentials: registering again creates a new
  // FCM token, and the server only knows the token you sent it.
  let credentials = await storage.get('credentials');
  if (!credentials) {
    credentials = await register(config);
    await storage.set('credentials', credentials);
  }
  sendTokenToYourBackend(credentials.fcm.token);

  // Pass the ids already received, or they are delivered again on connect.
  const persistentIds = (await storage.get('persistentIds')) || [];

  const client = await listen(
    Object.assign({}, credentials, { persistentIds }),
    ({ notification, persistentId }) => {
      persistentIds.push(persistentId);
      storage.set('persistentIds', persistentIds);
      console.log(notification.notification, notification.data);
    }
  );

  client.on('connect', () => console.log('connected'));
  client.on('disconnect', () => console.log('disconnected, reconnecting'));
  return client; // client.destroy() to stop
}

API

register(config) → Promise<credentials>

Checks in with Google as a new Chrome instance, creates a Firebase installation and registers it with FCM. credentials.fcm.token is the token your server sends to. Persist the whole object.

listen(credentials, onNotification) → Promise<Client>

Validates the credentials, connects in the background and reconnects on its own. onNotification({ notification, persistentId }) receives the decrypted FCM message (notification.notification, notification.data, ...).

Client

EventEmitter returned by listen().

Event Payload
EVENTS.NOTIFICATION_RECEIVED ('ON_NOTIFICATION_RECEIVED') { notification, persistentId }
EVENTS.CONNECT ('connect') —
EVENTS.DISCONNECT ('disconnect') —

client.destroy() closes the connection and stops reconnecting.

A message that cannot be decrypted is dropped with a warning; the following ones are still delivered.

Electron packaging

protobufjs cannot read .proto files from inside app.asar. In a packaged app the library looks for them in resources/app.asar.unpacked/dist/ first, then next to its sources. Copy them there at build time, e.g. with copy-webpack-plugin:

new CopyWebpackPlugin([
  { from: 'node_modules/@anh.votuan/fcm-http-v1/src/mcs.proto', to: 'mcs.proto' },
  {
    from: 'node_modules/@anh.votuan/fcm-http-v1/src/gcm/checkin.proto',
    to: 'checkin.proto',
  },
  {
    from: 'node_modules/@anh.votuan/fcm-http-v1/src/gcm/android_checkin.proto',
    to: 'android_checkin.proto',
  },
]);

and unpack them ("asarUnpack": ["dist/*.proto"] with electron-builder).

Debugging

DEBUG=fcm-http-v1 node app.js

prints proto loading, socket errors and the MCS wire protocol.

Try it

npm run register -- --apiKey=<key> --appID=<app id> --projectID=<project id>
npm run listen

register saves the credentials to storage.json (git-ignored); listen uses them and records the received persistent ids.

Development

npm install
npm run check   # eslint + prettier --check + jest

src must stay compatible with Node 10 and webpack 3 (acorn 5): ESLint parses it as ES2017 (no object spread, ?., ??), and http_ece is pinned to 1.1.x (1.2 needs Node >= 15.7 for base64url).

Documentation

License

MIT

Keywords