Firebase Cloud Messaging (FCM)

FCM (Firebase Cloud Messaging) is a built-in Norq push provider. It builds requests for the POST https://fcm.googleapis.com/v1/projects/{projectId}/messages:send endpoint (HTTP v1 API).

Configuration

providers:
  fcm:
    config:
      projectId: my-firebase-project
      serviceAccount: ${FCM_SERVICE_ACCOUNT_JSON}
      # OR a file path:
      # serviceAccount: ./secrets/fcm-service-account.json
      # OR inline JSON literal (not recommended for production):
      # serviceAccount: |
      #   {"type":"service_account","project_id":"...","private_key":"..."}
routing:
  push: fcm
  # OR per-platform:
  # push:
  #   ios: fcm
  #   android: fcm
  #   web: fcm

projectId and serviceAccount are both required. The serviceAccount field accepts the three secret value forms: ${ENV_VAR}, file path, or inline literal.

Legacy `serverKey` is rejected

Google retired the legacy server-key auth on 2024-06-20. If Norq detects a serverKey: field in the config, it errors with provider/fcm-legacy-server-key and refuses to register the provider. You must migrate to a service-account JSON.

Environment-variable fallback

If providers.fcm is not declared, Norq registers FCM when these env vars are set:

Var	Required
`NORQ_FCM_PROJECT_ID`	yes
`NORQ_FCM_SERVICE_ACCOUNT`	yes

NORQ_FCM_SERVICE_ACCOUNT accepts the same three forms as the config field (env-var ref, file path, inline JSON).

Capabilities

Channels: push (ios + android + web).
Batching: none. FCM HTTP v1 is one message per request; the SDK iterates tokens and calls prepare_send per token.
Per-platform overrides: the push template’s ios:, android:, and web: frontmatter blocks compile into the matching apns, android, and webpush blocks of the FCM request body.
Priority: android.priority must be high or normal (lowercase — FCM v1 is case-sensitive).
TTL: android.ttl is emitted as a duration string ("<seconds>s").

CLI cannot deliver

The norq CLI binary cannot send via FCM — Google’s HTTP v1 API requires an OAuth2 access token minted from the service-account JWT, and the CLI does not bundle the OAuth2 exchange. Calling norq send while routed to FCM short-circuits with provider/cli-oauth2-not-supported. SDKs (Node, Python, Go, Java, Ruby) handle the OAuth2 exchange in-process and deliver normally.

Request shape

Body: application/json. Top-level shape:

{
  "message": {
    "token": "<device-token>",
    "notification": { "title": "...", "body": "..." },
    "android": { "priority": "high", "ttl": "3600s" },
    "apns":    { "payload": { "aps": { ... } } },
    "webpush": { "notification": { ... } }
  }
}

Auth: Authorization: Bearer <oauth2-access-token>. Norq emits Auth::OAuth2GoogleSA { service_account_json } and the SDK exchanges the JWT for an access token via Google’s OAuth2 endpoint before each batch.
Endpoint: POST https://fcm.googleapis.com/v1/projects/{projectId}/messages:send
Success: 200. Norq extracts the FCM message name from $.name.
Retry: defaults — 429 + 5xx, 2 retries, 500ms backoff.