Packages · Push

`@notifkit/provider-fcm`

The push transport, over Firebase Cloud Messaging — which reaches Android directly and iOS through APNs.

npm install @notifkit/provider-fcm

import { FcmTransport } from "@notifkit/provider-fcm";

new FcmTransport({
  // The whole service-account JSON as a string, not a path to it.
  serviceAccountJson: process.env.FIREBASE_SERVICE_ACCOUNT!,
});

Options

Option	Required	Notes
`serviceAccountJson`	yes	The service-account JSON, stringified. Parsed lazily on the first send.
`logger`	no	Failures are logged at `warn` with the FCM error code.
`limits`	no	Defaults to `{ limit: 1000, windowSeconds: 60 }` — a longer window than the email transport's.

The Firebase app is initialised once, lazily, under the name notifkit. The name matters: it keeps this app separate from one your own code may already have initialised in the same process. Because initialisation is deferred to the first send, an invalid service account surfaces as a failed delivery rather than a crash at boot.

Which template keys it reads

Template key	Lands as
`subject`	`notification.title`
`text` or `body`	`notification.body`
`html` or `htmlBody`	`data.htmlBody`, for the app to render itself

data also carries taskId and eventId, so a tap handler can report back against the message it came from. On Android, a send of critical or high priority becomes android.priority: "high"; everything else is normal. The APNs payload is sent with sound: "default" and badge: 1.

dead tokens clean themselves up

Three FCM error codes — registration-token-not-registered, invalid-registration-token and invalid-argument — are reported to the engine as invalidToken. That deactivates the contact, so the token is skipped on every future send, and the message moves on to its fallback chain rather than being retried against an address that will never work again.

push resolves its destination late

Unlike email, a push token is resolved at send time rather than during enrichment, so a token invalidated a moment ago is not used. The consequence for you is that destination can be absent on the payload when the recipient has no token on record — which is reported as a failure, never quietly substituted with the user id.