@juliendu11/adonis-js-push-notification

AdonisJS Push Notification

Add support for sending push notifications via the Firebase Cloud Messaging API.

Installation

Install the package from npm using the following command:

// FOR ADONISJS 6
npm i @juliendu11/adonis-js-push-notification

// FOR ADONISJS 7
npm i @juliendu11/adonis-js-push-notification@next

then run configuration command:

node ace configure @juliendu11/adonis-js-push-notification

Configuration

The configuration file is located at config/push_notification.ts. You can set your Firebase server key and other options there.

Name	Description	Required
clientEmail*	For the iss and sub fields, in order to obtain an authentication token from oauth2.googleapis.com	Required
privateKey*	Your private signing key to sign the token	Required
projectId*	The project ID corresponding to your Firebase/Google project	Required
stubUrl	If you want to stub Firebase with another external service, which is useful during the development phase to view notifications, I've created a dashboard for that here.	Optional

* can find this information in the service account file, which you can find in the Google console or Firebase.

How to use

You can use the PushNotification service in your controllers or services by directly using the service, like this:

import pushNotification from '@juliendu11/adonis-js-push-notification/services/main'

@inject()
export default class NotificationService {

  async send() {
    await pushNotification.sendToToken(<TOKEN>, <FcmNotification>, <FcmData>)
  }
}

or by injecting it via the AdonisJS container:

const pushNotification = await this.app.container.make('pushNotification')
await pushNotification.sendToToken(<TOKEN>, <FcmNotification>, <FcmData>)

or

@inject()
export default class NotificationController {
  constructor(protected pushNotification: PushNotification) {}
}

Methods

The PushNotification service provides the following methods:

Name	Description
sendToToken	Sends a message to an FCM push token
sendToTopic	Send a message to a topic (Topic name)
sendRaw	Basic method used by sendToToken and sendToTopic

Error handling

When a send fails (sendToToken, sendToTopic, sendRaw), the promise rejects with a FCMSendException (exported from the package entrypoint):

import { FCMSendException } from '@juliendu11/adonis-js-push-notification'
import pushNotification from '@juliendu11/adonis-js-push-notification/services/main'

try {
  await pushNotification.sendToToken(<TOKEN>, <FcmNotification>, <FcmData>)
} catch (error) {
  if (error instanceof FCMSendException) {
    console.log(error.httpStatus) // HTTP status code returned by FCM, e.g. 404
    console.log(error.fcmErrorCode) // FCM error code, e.g. 'UNREGISTERED'
    console.log(error.responseBody) // Raw parsed JSON error body returned by FCM
  }
}

fcmErrorCode is parsed from the FCM v1 API response (error.details[].errorCode) and can be undefined if FCM didn't return a structured error body. Possible values, per the FCM error reference:

Code	Meaning	What to do
UNREGISTERED	The token is no longer valid (app uninstalled, token rotated, etc.)	Stop using this token and remove/flag it in your database — it will never work again.
INVALID_ARGUMENT	The request is malformed (bad token format, invalid message fields, etc.)	Check the token format and message payload; can also happen on a code bug, not always the token's fault.
SENDER_ID_MISMATCH	The token was registered to a different Firebase project/sender than the one you're using	Check your projectId/credentials configuration before assuming the token is dead.
QUOTA_EXCEEDED	You're sending too many messages too fast	Back off and retry later; do not treat the token as dead.
UNAVAILABLE	FCM is temporarily unavailable	Retry later with backoff; do not treat the token as dead.
INTERNAL	Internal error on FCM's side	Retry later; do not treat the token as dead.
THIRD_PARTY_AUTH_ERROR	APNs certificate/auth issue (iOS only)	Check your APNs configuration.
UNSPECIFIED_ERROR	Unknown error	Log and investigate.

Only UNREGISTERED reliably means the token itself is permanently dead — the other codes are either transient or configuration issues and should not be used to decide whether to delete a token.

Info

• FCM Google API Doc