@open-mercato/channel-fcm 0.6.8-develop.6985.1.fb93574faa

package/src/modules/channel_fcm/lib/__tests__/message-golden.test.ts

@@ -0,0 +1,98 @@
+import type { PushEnvelope } from '@open-mercato/core/modules/communication_channels/lib/push-envelope'
+import { buildFcmMessage } from '../adapter'
+
+/**
+ * Golden assertions pinning the FCM message we build against Google's published reference shape.
+ *
+ * These are the only tests that catch serialization drift in *our* builder: the integration fakes
+ * replace the SDK client, so nothing else ever validates the message body. Drift in *Google's* schema
+ * is out of reach of any fake and stays a manual live-key check.
+ *
+ * Reference: https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#Message
+ * APNs headers within FCM: https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#ApnsConfig
+ *
+ * Written as exact `toEqual` fixtures rather than snapshots: a snapshot would re-record drift on
+ * `--updateSnapshot` instead of failing.
+ */
+const TOKEN = 'device-token-abcdef12'
+
+function envelope(overrides: Partial<PushEnvelope> = {}): PushEnvelope {
+  return {
+    title: 'Order shipped',
+    body: 'Your order #42 is on its way',
+    data: { type: 'orders.shipped', notificationId: 'n1' },
+    options: {},
+    silent: false,
+    ...overrides,
+  }
+}
+
+describe('buildFcmMessage — golden payloads', () => {
+  it('visible notification matches the reference shape', () => {
+    expect(buildFcmMessage(TOKEN, envelope())).toEqual({
+      token: TOKEN,
+      notification: {
+        title: 'Order shipped',
+        body: 'Your order #42 is on its way',
+      },
+      data: { type: 'orders.shipped', notificationId: 'n1' },
+      android: {
+        notification: { sound: 'default' },
+      },
+      apns: {
+        headers: { 'apns-priority': '10' },
+        payload: { aps: { sound: 'default' } },
+      },
+    })
+  })
+
+  it('silent notification is data-only with content-available and a background push type', () => {
+    expect(buildFcmMessage(TOKEN, envelope({ silent: true }))).toEqual({
+      token: TOKEN,
+      data: { type: 'orders.shipped', notificationId: 'n1' },
+      android: { priority: 'high' },
+      apns: {
+        headers: { 'apns-push-type': 'background', 'apns-priority': '5' },
+        payload: { aps: { 'content-available': 1 } },
+      },
+    })
+  })
+
+  it('full pushOptions map onto each platform', () => {
+    const message = buildFcmMessage(
+      TOKEN,
+      envelope({
+        options: {
+          sound: 'chime.caf',
+          badge: 7,
+          image: 'https://cdn.example.com/hero.png',
+          priority: 'normal',
+          channelId: 'orders',
+          body: 'Overridden push body',
+        },
+      }),
+    )
+
+    expect(message).toEqual({
+      token: TOKEN,
+      notification: {
+        title: 'Order shipped',
+        body: 'Overridden push body',
+        imageUrl: 'https://cdn.example.com/hero.png',
+      },
+      data: { type: 'orders.shipped', notificationId: 'n1' },
+      android: {
+        priority: 'normal',
+        notification: {
+          sound: 'chime.caf',
+          channelId: 'orders',
+          imageUrl: 'https://cdn.example.com/hero.png',
+        },
+      },
+      apns: {
+        headers: { 'apns-priority': '5' },
+        payload: { aps: { sound: 'chime.caf', badge: 7 } },
+      },
+    })
+  })
+})

package/src/modules/channel_fcm/lib/adapter.ts

@@ -0,0 +1,238 @@
+import { createHash } from 'node:crypto'
+import type {
+  SendMessageInput,
+  SendMessageResult,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  BasePushChannelAdapter,
+  deviceUnregisteredResult,
+  MISSING_PUSH_TOKEN_RESULT,
+  readPushToken,
+} from '@open-mercato/core/modules/communication_channels/lib/push-adapter'
+import { createRefCountedClientCache } from '@open-mercato/core/modules/communication_channels/lib/refcounted-client-cache'
+import { readPushEnvelope, resolvePushBody, type PushEnvelope } from '@open-mercato/core/modules/communication_channels/lib/push-envelope'
+import {
+  fcmCredentialsSchema,
+  parseFcmServiceAccount,
+  type FcmServiceAccount,
+} from './credentials'
+
+/**
+ * FCM error codes that mean the device *token* is permanently invalid. Mapped to
+ * the uniform `device_unregistered` sentinel so the push worker soft-deletes the
+ * device (identical contract across fcm/apns/expo — see push-stub-adapter).
+ *
+ * Deliberately excludes `messaging/invalid-argument`: FCM v1 returns it for ANY
+ * malformed request field (oversized payload, bad data key, bad notification
+ * field), not just a bad token — treating it as unregistered would let a single
+ * payload-shape bug progressively soft-delete every targeted device tenant-wide.
+ * It falls through to the generic retryable `failed` path instead.
+ */
+const PERMANENT_FCM_ERROR_CODES = new Set([
+  'messaging/registration-token-not-registered',
+  'messaging/invalid-registration-token',
+])
+
+type FirebaseMessaging = {
+  send(message: Record<string, unknown>): Promise<string>
+}
+
+/**
+ * Pluggable messaging factory so tests can inject a fake without importing
+ * firebase-admin. Production path lazily loads firebase-admin and caches one app
+ * per service-account hash (re-initializing per send is wasteful and
+ * firebase-admin throws on duplicate app names).
+ */
+export type FcmMessagingFactory = (serviceAccount: FcmServiceAccount) => FirebaseMessaging
+
+let messagingFactory: FcmMessagingFactory | null = null
+
+/** Test-only seam to swap the firebase-admin messaging factory. */
+export function setFcmMessagingFactory(factory: FcmMessagingFactory | null): void {
+  messagingFactory = factory
+}
+
+function cacheKeyForServiceAccount(serviceAccount: FcmServiceAccount): string {
+  const hash = createHash('sha256')
+    .update(`${serviceAccount.projectId}:${serviceAccount.clientEmail}:${serviceAccount.privateKey}`)
+    .digest('hex')
+    .slice(0, 16)
+  return `om-fcm-${hash}`
+}
+
+type FcmAppLike = {
+  name?: string
+  /**
+   * firebase-admin's App exposes async `delete()`, which stops the background
+   * OAuth token-refresh timer bound to the service-account credential and drops
+   * the app from the SDK's registry.
+   */
+  delete(): Promise<void>
+}
+
+/**
+ * Bounds the number of live firebase-admin apps cached at once. Each app holds a
+ * service-account OAuth credential with a background token-refresh timer, so an
+ * unbounded cache would leak an app (and its timer) every time a tenant rotates
+ * their service account (the hash changes → a new app, while the stale app never
+ * gets deleted). LRU-evicting the least-recently used app and calling `delete()`
+ * keeps the app and timer count bounded. Disposal is fenced on in-flight sends: an
+ * evicted app is deleted only once its last concurrent `send` releases (see
+ * refcounted-client-cache), so eviction never tears an app out from under a send.
+ */
+const APP_CACHE_MAX = 32
+const appCache = createRefCountedClientCache<FcmAppLike>({
+  max: APP_CACHE_MAX,
+  dispose: (app) => {
+    void app.delete().catch(() => {})
+  },
+})
+
+// firebase-admin registers every app by name in a process-global registry and throws on a duplicate
+// name. Cache keys are per-credential-identity (a rotated service account churns keys in and out), so a
+// stable name-per-credential would let a re-created entry reuse — via getApps() — an app a still-in-flight
+// evicted entry is about to delete(). A monotonic suffix makes every initialized app name unique, so each
+// cache entry owns exactly one app and disposing an evicted app can never affect a live one.
+let appInitSeq = 0
+
+async function createFirebaseApp(serviceAccount: FcmServiceAccount, appName: string): Promise<FcmAppLike> {
+  const { initializeApp, cert } = await import('firebase-admin/app')
+  return initializeApp(
+    {
+      credential: cert({
+        projectId: serviceAccount.projectId,
+        clientEmail: serviceAccount.clientEmail,
+        privateKey: serviceAccount.privateKey,
+      }),
+    },
+    appName,
+  ) as unknown as FcmAppLike
+}
+
+/**
+ * Build the firebase-admin message from the push envelope, branching on
+ * `envelope.silent` (data-only content-available wake-up) and applying the
+ * recognized `pushOptions` (sound/badge/image/priority/channelId) per platform.
+ */
+export function buildFcmMessage(token: string, envelope: PushEnvelope): Record<string, unknown> {
+  const { options, silent } = envelope
+  const apnsPriority = options.priority === 'normal' ? '5' : '10'
+
+  if (silent) {
+    return {
+      token,
+      data: envelope.data,
+      android: { priority: 'high' },
+      apns: {
+        headers: { 'apns-push-type': 'background', 'apns-priority': '5' },
+        payload: { aps: { 'content-available': 1 } },
+      },
+    }
+  }
+
+  const body = resolvePushBody(envelope)
+  const sound = options.sound ?? 'default'
+  const androidNotification: Record<string, unknown> = { sound }
+  if (options.channelId) androidNotification.channelId = options.channelId
+  if (options.image) androidNotification.imageUrl = options.image
+  const aps: Record<string, unknown> = { sound }
+  if (typeof options.badge === 'number') aps.badge = options.badge
+
+  return {
+    token,
+    notification: {
+      title: envelope.title,
+      body,
+      ...(options.image ? { imageUrl: options.image } : {}),
+    },
+    data: envelope.data,
+    android: {
+      ...(options.priority ? { priority: options.priority } : {}),
+      notification: androidNotification,
+    },
+    apns: {
+      headers: { 'apns-priority': apnsPriority },
+      payload: { aps },
+    },
+  }
+}
+
+class FcmChannelAdapter extends BasePushChannelAdapter {
+  readonly providerKey = 'fcm'
+  protected readonly credentialsSchema = fcmCredentialsSchema
+
+  async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {
+    const token = readPushToken(input)
+    if (!token) return MISSING_PUSH_TOKEN_RESULT
+
+    const parsedCredentials = fcmCredentialsSchema.safeParse(input.credentials)
+    if (!parsedCredentials.success) {
+      return { externalMessageId: '', status: 'failed', error: 'invalid_fcm_credentials' }
+    }
+
+    const envelope = readPushEnvelope(input.content)
+    let serviceAccount: FcmServiceAccount
+    try {
+      serviceAccount = parseFcmServiceAccount(parsedCredentials.data)
+    } catch (err) {
+      return { externalMessageId: '', status: 'failed', error: err instanceof Error ? err.message : String(err) }
+    }
+    const message = buildFcmMessage(token, envelope)
+
+    // Test seam: an injected factory bypasses the app cache entirely.
+    if (messagingFactory) {
+      let messaging: FirebaseMessaging
+      try {
+        messaging = messagingFactory(serviceAccount)
+      } catch (err) {
+        return { externalMessageId: '', status: 'failed', error: err instanceof Error ? err.message : String(err) }
+      }
+      return this.performSend(messaging, message)
+    }
+
+    // Production path: borrow a cached firebase-admin app for the duration of the send. Holding the
+    // lease keeps an evicted app alive until the send completes (release() in finally).
+    const cacheKey = cacheKeyForServiceAccount(serviceAccount)
+    let lease
+    try {
+      appInitSeq += 1
+      const appName = `${cacheKey}-${appInitSeq}`
+      lease = await appCache.acquire(cacheKey, () => createFirebaseApp(serviceAccount, appName))
+    } catch (err) {
+      return { externalMessageId: '', status: 'failed', error: err instanceof Error ? err.message : String(err) }
+    }
+    try {
+      const { getMessaging } = await import('firebase-admin/messaging')
+      const messaging = getMessaging(lease.client as never) as unknown as FirebaseMessaging
+      return await this.performSend(messaging, message)
+    } catch (err) {
+      return { externalMessageId: '', status: 'failed', error: err instanceof Error ? err.message : String(err) }
+    } finally {
+      lease.release()
+    }
+  }
+
+  private async performSend(
+    messaging: FirebaseMessaging,
+    message: Record<string, unknown>,
+  ): Promise<SendMessageResult> {
+    try {
+      const externalMessageId = await messaging.send(message)
+      return { externalMessageId, status: 'sent' }
+    } catch (err) {
+      const code = typeof (err as { code?: unknown }).code === 'string' ? (err as { code: string }).code : undefined
+      const errorMessage = err instanceof Error ? err.message : String(err)
+      if (code && PERMANENT_FCM_ERROR_CODES.has(code)) {
+        return deviceUnregisteredResult({ code })
+      }
+      return { externalMessageId: '', status: 'failed', error: errorMessage }
+    }
+  }
+}
+
+let cachedAdapter: FcmChannelAdapter | null = null
+
+export function getFcmChannelAdapter(): FcmChannelAdapter {
+  if (!cachedAdapter) cachedAdapter = new FcmChannelAdapter()
+  return cachedAdapter
+}

package/src/modules/channel_fcm/lib/credentials.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod'
+import {
+  PUSH_CREDENTIAL_ERROR_INVALID_JSON,
+  PUSH_CREDENTIAL_ERROR_MISSING_FIELDS,
+  PUSH_CREDENTIAL_ERROR_REQUIRED,
+} from '@open-mercato/core/modules/communication_channels/lib/push-credential-errors'
+
+/**
+ * Firebase service account shape (camelCase) used to mint FCM credentials.
+ * Source JSON from the Firebase console uses snake_case keys, normalized by
+ * {@link parseFcmServiceAccount}.
+ */
+export const fcmServiceAccountSchema = z
+  .object({
+    projectId: z.string().min(1, 'project_id missing'),
+    clientEmail: z.string().min(1, 'client_email missing'),
+    privateKey: z.string().min(1, 'private_key missing'),
+  })
+  .passthrough()
+
+export type FcmServiceAccount = z.infer<typeof fcmServiceAccountSchema>
+
+function normalizeServiceAccount(raw: Record<string, unknown>): FcmServiceAccount {
+  return fcmServiceAccountSchema.parse({
+    projectId: raw.projectId ?? raw.project_id,
+    clientEmail: raw.clientEmail ?? raw.client_email,
+    privateKey: raw.privateKey ?? raw.private_key,
+  })
+}
+
+/**
+ * Tenant-level FCM credentials persisted on `IntegrationCredentials` for provider
+ * `channel_fcm`. `serviceAccountJson` is the full Firebase service-account JSON
+ * (stored encrypted at rest); `appName` is an optional label for the cached
+ * firebase-admin app.
+ */
+export const fcmCredentialsSchema = z
+  .object({
+    serviceAccountJson: z.string().min(1, PUSH_CREDENTIAL_ERROR_REQUIRED),
+    appName: z.string().optional(),
+  })
+  .passthrough()
+  .superRefine((value, ctx) => {
+    // Two distinct failures, two distinct codes. Never interpolate the caught
+    // error: a `normalizeServiceAccount` rejection is a ZodError whose
+    // `.message` is a JSON dump of the issue array, which used to reach the
+    // operator verbatim through `fieldErrors`.
+    let parsed: Record<string, unknown>
+    try {
+      parsed = JSON.parse(value.serviceAccountJson) as Record<string, unknown>
+    } catch {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['serviceAccountJson'],
+        message: PUSH_CREDENTIAL_ERROR_INVALID_JSON,
+      })
+      return
+    }
+    const account = fcmServiceAccountSchema.safeParse({
+      projectId: parsed.projectId ?? parsed.project_id,
+      clientEmail: parsed.clientEmail ?? parsed.client_email,
+      privateKey: parsed.privateKey ?? parsed.private_key,
+    })
+    if (!account.success) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['serviceAccountJson'],
+        message: PUSH_CREDENTIAL_ERROR_MISSING_FIELDS,
+      })
+    }
+  })
+
+export type FcmCredentials = z.infer<typeof fcmCredentialsSchema>
+
+/** Parse and normalize the service account out of validated credentials. Throws on malformed JSON. */
+export function parseFcmServiceAccount(credentials: FcmCredentials): FcmServiceAccount {
+  const parsed = JSON.parse(credentials.serviceAccountJson) as Record<string, unknown>
+  return normalizeServiceAccount(parsed)
+}

package/src/modules/channel_fcm/lib/fake-provider.ts

@@ -0,0 +1,46 @@
+import {
+  isPushFakeProvidersEnabled,
+  recordFakePush,
+  warnPushFakeProvidersActive,
+} from '@open-mercato/core/modules/push_notifications/lib/fake-provider-recorder'
+import { setFcmMessagingFactory } from './adapter'
+
+/**
+ * Network-free `firebase-admin` messaging client used ONLY by integration tests.
+ *
+ * Swaps the SDK client behind the adapter's existing seam, so every line of the real adapter still
+ * runs — message construction, credential parsing, client caching, and the
+ * `messaging/registration-token-not-registered` → `device_unregistered` mapping. The adapter itself is
+ * never replaced (unlike `push_stub`), and is never re-registered: `registerChannelAdapter` throws on a
+ * duplicate provider key.
+ *
+ * Token sentinels match `push_stub`'s convention (see push-stub-adapter.ts):
+ *   - token containing `unregistered` → FCM's native permanent-token error code
+ *   - token containing `fail`         → a retryable error (no `code`, so the adapter retries)
+ *   - otherwise                        → success
+ *
+ * Production safety: never installed at module import; no-op unless `OM_PUSH_FAKE_PROVIDERS` is set.
+ */
+function fakeSendError(message: string, code?: string): Error {
+  const error = new Error(message)
+  if (code) Object.assign(error, { code })
+  return error
+}
+
+export function ensureFcmFakeProviderInstalled(): void {
+  if (!isPushFakeProvidersEnabled()) return
+  warnPushFakeProvidersActive('fcm')
+  setFcmMessagingFactory(() => ({
+    async send(message: Record<string, unknown>): Promise<string> {
+      const token = typeof message.token === 'string' ? message.token : ''
+      recordFakePush('fcm', token, message)
+      if (token.includes('unregistered')) {
+        throw fakeSendError('fake fcm token not registered', 'messaging/registration-token-not-registered')
+      }
+      if (token.includes('fail')) {
+        throw fakeSendError('fake fcm transient failure')
+      }
+      return `fcm-fake-${token.slice(-8) || 'token'}`
+    },
+  }))
+}

package/src/modules/channel_fcm/lib/health.ts

@@ -0,0 +1,13 @@
+import { makePushClientConfigHealthCheck } from '@open-mercato/core/modules/push_notifications/lib/push-health'
+import { fcmCredentialsSchema } from './credentials'
+
+/**
+ * Liveness probe for the FCM integration. The hub passes the tenant-scoped
+ * credentials (the service-account JSON), so the probe just confirms they are
+ * present and parse into a valid service account — no network call. Per-device
+ * token validity surfaces on delivery (`device_unregistered` soft-deletes).
+ */
+export const channelFcmHealthCheck = makePushClientConfigHealthCheck({
+  schema: fcmCredentialsSchema,
+  providerLabel: 'FCM',
+})

package/src/modules/channel_fcm/setup.ts

@@ -0,0 +1,34 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+import {
+  hasChannelAdapter,
+  registerChannelAdapter,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter-registry-singleton'
+import { getFcmChannelAdapter } from './lib/adapter'
+
+/**
+ * Register the FCM `ChannelAdapter` once per process at import time. The registry
+ * is process-wide; we guard with `hasChannelAdapter` to silence the duplicate
+ * error on dev-mode HMR + repeated test imports.
+ *
+ * Provider credentials (the Firebase service account) are persisted per tenant via
+ * the standard `IntegrationCredentials` flow for the `channel_fcm` provider; this
+ * module never preconfigures credentials from env.
+ */
+function ensureFcmAdapterRegistered(): void {
+  if (hasChannelAdapter('fcm')) return
+  registerChannelAdapter(getFcmChannelAdapter())
+}
+
+ensureFcmAdapterRegistered()
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    superadmin: ['channel_fcm.view', 'channel_fcm.configure'],
+    admin: ['channel_fcm.view', 'channel_fcm.configure'],
+  },
+  async onTenantCreated() {
+    ensureFcmAdapterRegistered()
+  },
+}
+
+export default setup