@crvouga/mockingbird-service-fcm

Local emulators. Real API contracts. Part of Mockingbird.

Stateful emulator of the Firebase Cloud Messaging HTTP v1 send API (POST /v1/projects/{project_id}/messages:send), the call firebase-admin makes. Projects, access tokens, and registration tokens are fixtures. There is no FCM sandbox. This package is status: "wip".

• Operation coverage: SUPPORT.md
• The contract (openapi.yaml) is hand-authored from the FCM REST reference and firebase-admin 12.7.0 / 13.5.0.

Install

npm install -D @crvouga/mockingbird-service-fcm

ESM only. Node >= 22 or Bun >= 1.2. No native dependencies. Serve it with npx mockingbird-fcm serve, createServer from ./server (Node), or createRuntime with any Fetch server.

Usage

firebase-admin hardcodes https://fcm.googleapis.com. Point it at the emulator with createAdminTransport (an https.Agent that dials the emulator) and call enableLegacyHttpTransport() so multicast sends honor that agent. send is already HTTP/1.1. The fixture project is demo-project, the fixture device token is fixture-device-token, and any bearer is accepted until you turn on strict.

import { deleteApp, initializeApp } from "firebase-admin/app"
import { getMessaging } from "firebase-admin/messaging"
import { createServer } from "@crvouga/mockingbird-service-fcm/server"
import { createAdminTransport } from "@crvouga/mockingbird-service-fcm/admin"

// Test setup: the emulator, plus a credential and an agent that reach it.
const fcm = await createServer()
const transport = await createAdminTransport({ origin: fcm.url, token: "fixture-token" })

// The application's firebase-admin app. Only its credential and httpAgent change.
const app = initializeApp({
  projectId: "demo-project",
  credential: transport.credential,
  httpAgent: transport.agent,
})
const messaging = getMessaging(app)
messaging.enableLegacyHttpTransport()
const name = await messaging.send({
  token: "fixture-device-token",
  notification: { title: "Hello", body: "World" },
})
// name → "projects/demo-project/messages/<id>"

// Test control: every message the emulator accepted.
const outbox = await (await fetch(`${fcm.url}/__admin/outbox`)).json()
void outbox

await deleteApp(app)
await transport.close()
await fcm.close()

Routes

Admin

Logical message time is clockOffsetMs plus the process-wide runtime clock. POST /__admin/clock still moves every namespace. Records, faults, outboxes, inboxes, and message ids are per namespace.

Presets

POST /__admin/faults {"preset": "<name>"}. Each one targets SendMessage:

Namespaces

x-mockingbird-namespace, a /__admin/ns/<name>/ prefix, or PUT /__admin/credentials (bearer → namespace). A bearer listed in settings.credentials authorizes only that project. strict: true rejects bearers that are not listed. Webhooks: none. The device inbox is a test control, not a callback.

SDK error codes

firebase-admin maps error.details[].errorCode when @type is type.googleapis.com/google.firebase.fcm.v1.FcmError, otherwise error.status. Two mappings differ from a naive reading of the error-code names, and the emulator follows firebase-admin 12.7.0 and 13.5.0:

• A JSON 401 with status UNAUTHENTICATED and no FcmError details becomes messaging/third-party-auth-error. messaging/authentication-error is what the SDK uses for a non-JSON 401.
• FcmError DEADLINE_EXCEEDED is not in the messaging map, so the SDK reports messaging/unknown-error. UNAVAILABLE is messaging/server-unavailable.

INVALID_ARGUMENT, SENDER_ID_MISMATCH, QUOTA_EXCEEDED, UNAVAILABLE, and INTERNAL map to messaging/invalid-argument, messaging/mismatched-credential, messaging/message-rate-exceeded, messaging/server-unavailable, and messaging/internal-error. Status PERMISSION_DENIED (a bearer for another project) is also messaging/mismatched-credential.

Deliberately not modelled

• Firebase Auth, Firestore, Realtime Database, Hosting, Remote Config, Analytics, and client installation APIs.
• Topic and condition sends, and topic subscription management.
• APNs and Android transport, real devices, app callbacks, notification rendering, badges, and sounds.
• Production quotas and Google's unpublished retry schedule. The Admin SDK's own retry (503, ECONNRESET, ETIMEDOUT) is left to the SDK.

API

Part of mockingbird.