# @anh.votuan/fcm-http-v1

> Receive Firebase Cloud Messaging (FCM) push notifications in a Node.js / Electron process, using the FCM HTTP v1 registration endpoints.

Latest version **1.2.0** (published 2026-11-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install @anh.votuan/fcm-http-v1
pnpm add @anh.votuan/fcm-http-v1
yarn add @anh.votuan/fcm-http-v1
bun add @anh.votuan/fcm-http-v1
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2026-11-19 |
| First published | 2024-09-12 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=10 |
| Dependencies | 3 |
| Unpacked size | 65.7 KB |
| Known vulnerabilities | 0 (+10 in 1 direct dependencies) |
| Install scripts | no |
| Author | anhvt |
| Maintainers | anh.votuan |
| Keywords | push, fcm, gcm, firebase, notifications, node, electron, receiver |

## Links

- npm: https://www.npmjs.com/package/@anh.votuan/fcm-http-v1
- Repository: https://github.com/tuananh-vo/fcm-http-v1
- Homepage: https://github.com/tuananh-vo/fcm-http-v1#readme
- Issues: https://github.com/tuananh-vo/fcm-http-v1/issues
- npm.io page: https://npm.io/package/@anh.votuan/fcm-http-v1

## Dependencies (3)

- [long](https://npm.io/package/long.md) ^3.2.0
- [http_ece](https://npm.io/package/http_ece.md) ~1.1.0
- [protobufjs](https://npm.io/package/protobufjs.md) ^6.8.0

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.2.0 (latest) — 2026-11-19
- 1.0.17 — 2024-09-16
- 1.0.16 — 2024-09-16
- 1.0.15 — 2024-09-16
- 1.0.14 — 2024-09-16
- 1.0.13 — 2024-09-13
- 1.0.12 — 2024-09-13
- 1.0.11 — 2024-09-13
- 1.0.10 — 2024-09-13
- 1.0.9 — 2024-09-13
- 1.0.8 — 2024-09-13
- 1.0.7 — 2024-09-13
- 1.0.6 — 2024-09-13
- 1.0.5 — 2024-09-13
- 1.0.4 — 2024-09-13
- … 4 more at https://npm.io/package/@anh.votuan/fcm-http-v1/versions

## README

# @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

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

## Usage

```js
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`:

```js
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

```bash
DEBUG=fcm-http-v1 node app.js
```

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

## Try it

```bash
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

```bash
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

- [docs/USAGE.md](docs/USAGE.md) — usage guide (Vietnamese)
- [docs/CHANGES_1.2.0.md](docs/CHANGES_1.2.0.md) — 1.2.0: built-in HTTP client instead of `request`
- [docs/CHANGES_1.1.0.md](docs/CHANGES_1.1.0.md) — 1.1.0: refactor, behaviour compatibility
- [docs/KNOWN_ISSUES.md](docs/KNOWN_ISSUES.md) — known issues and technical debt
- [docs/PUBLISHING.md](docs/PUBLISHING.md) — release and publishing security checklist
- [CHANGELOG.md](CHANGELOG.md)

## License

MIT

---
_Source: https://npm.io/package/@anh.votuan/fcm-http-v1 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
