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

package/src/modules/channel_fcm/__integration__/TC-CHANNEL-PUSH-002.spec.ts

@@ -0,0 +1,64 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/authFixtures'
+import { apiRequest } from '@open-mercato/core/helpers/integration/api'
+import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
+
+/**
+ * TC-CHANNEL-PUSH-002 — tenant-wide connect route for push providers.
+ *
+ * Push providers (FCM/APNs/Expo) declare `channelScope: 'tenant'` so their channel
+ * is created once per tenant with `user_id = NULL` and serves every user's devices.
+ * They connect through the dedicated admin route
+ * `POST /api/communication_channels/channels/connect/tenant-credentials`
+ * (feature `communication_channels.connect_tenant_channel`), NOT the per-user route.
+ *
+ * These assertions are network-free and self-contained: with empty/invalid input the
+ * flow never creates a channel or credential row, so there is nothing to clean up.
+ * The read side (fan-out + delivery) is already user-agnostic — it resolves a push
+ * channel by `{ tenantId, channelType: 'push' }` with no `user_id` filter and reads
+ * credentials at `channel.userId ?? null` — which is what makes one tenant channel
+ * serve the whole tenant; that path is covered network-free by
+ * `push_notifications/lib/__tests__/push-delivery.test.ts`.
+ */
+test.describe('TC-CHANNEL-PUSH-002: tenant-wide push connect route', () => {
+  test('reaches the registered FCM adapter and rejects missing credentials (422)', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/channels/connect/tenant-credentials',
+      {
+        token,
+        // Missing serviceAccountJson → the adapter's validateCredentials rejects it,
+        // so the flow never creates a tenant channel (no side effect / no cleanup).
+        data: { providerKey: 'fcm', displayName: 'FCM — tenant connect', credentials: {} },
+      },
+    )
+    expect(response.status(), 'route should not 5xx').toBeLessThan(500)
+    // 422 proves: authenticated, the caller HAS connect_tenant_channel, the provider
+    // is tenant-scoped (else 400), and the registered FCM adapter's validateCredentials
+    // ran and rejected the empty credentials.
+    expect(response.status()).toBe(422)
+    const body = await readJsonSafe<{ error?: string; fieldErrors?: Record<string, string> }>(response)
+    expect(body?.fieldErrors ?? body?.error).toBeTruthy()
+  })
+
+  test('rejects a per-user provider on the tenant route (400)', async ({ request }) => {
+    const token = await getAuthToken(request)
+    const response = await apiRequest(
+      request,
+      'POST',
+      '/api/communication_channels/channels/connect/tenant-credentials',
+      {
+        token,
+        // IMAP is a per-user provider (no channelScope) — an admin must not be able
+        // to force it into a shared tenant-wide channel through this route.
+        data: { providerKey: 'imap', displayName: 'IMAP — should be rejected', credentials: {} },
+      },
+    )
+    expect(response.status(), 'route should not 5xx').toBeLessThan(500)
+    expect(response.status()).toBe(400)
+    const body = await readJsonSafe<{ code?: string }>(response)
+    expect(body?.code).toBe('provider_not_tenant_scoped')
+  })
+})

package/src/modules/channel_fcm/__integration__/TC-CHANNEL-PUSH-005.meta.ts

@@ -0,0 +1,3 @@
+export const integrationMeta = {
+  requiredEnvVars: ['OM_PUSH_FAKE_PROVIDERS'],
+}

package/src/modules/channel_fcm/__integration__/TC-CHANNEL-PUSH-005.spec.ts

@@ -0,0 +1,88 @@
+import { expect, test } from '@playwright/test'
+import { getAuthToken } from '@open-mercato/core/helpers/integration/api'
+import { getTokenScope } from '@open-mercato/core/helpers/integration/generalFixtures'
+import { createNotificationFixture } from '@open-mercato/core/helpers/integration/notificationsFixtures'
+import { drainIntegrationQueue } from '@open-mercato/core/helpers/integration/queue'
+import {
+  connectFakePushChannel,
+  deleteChannelIfExists,
+  deleteDeliveriesForDevice,
+  deleteFakePushDevice,
+  expectNativeMessage,
+  makeFakePushToken,
+  readLatestDelivery,
+  registerFakePushDevice,
+} from '@open-mercato/core/helpers/integration/pushFake'
+
+/**
+ * TC-CHANNEL-PUSH-005 — the REAL FCM adapter, end-to-end, without live credentials.
+ *
+ * `push_stub` replaces the whole adapter, so TC-PUSH-003 never executes a line of `channel-fcm`. Here
+ * only the `firebase-admin` client is faked (`OM_PUSH_FAKE_PROVIDERS`), so the adapter's own credential
+ * parsing, client caching, and `buildFcmMessage` all run: connect a tenant channel through the real
+ * credential-connect route → register a device routed to `fcm` → `POST /api/notifications` → drain
+ * `events` (fan-out) then `push-deliveries` (worker) → the delivery row reaches `sent` AND the
+ * provider-native message the adapter handed the SDK is asserted.
+ */
+const PROVIDER = 'fcm'
+
+test.describe('TC-CHANNEL-PUSH-005: real FCM adapter reaches sent with a correct native message', () => {
+  test('delivers a visible notification and maps pushOptions onto the FCM message', async ({ request }) => {
+    // Budgeted explicitly rather than via `test.slow()` (which only triples the config's 20s budget).
+    // NOTE: this does not fix the current CI failure — `POST /api/notifications` hangs >30s in the
+    // channel-package shard, so the test dies on `apiRequest`'s own 30s timeout. See the spec changelog.
+    test.setTimeout(120_000)
+    const adminToken = await getAuthToken(request, 'admin')
+    const { tenantId, organizationId, userId } = getTokenScope(adminToken)
+    // Run-unique: the sink is append-only and is not truncated on the reused-environment path.
+    const { pushToken, tokenTail } = makeFakePushToken(PROVIDER)
+    const startedAt = new Date().toISOString()
+
+    let channelId: string | null = null
+    let userDeviceId: string | null = null
+    try {
+      channelId = await connectFakePushChannel(request, adminToken, PROVIDER, 'TC-CHANNEL-PUSH-005 FCM')
+      userDeviceId = await registerFakePushDevice(
+        request,
+        adminToken,
+        PROVIDER,
+        pushToken,
+        `qa-tc-channel-push-005-${Date.now()}`,
+      )
+
+      await createNotificationFixture(request, adminToken, {
+          recipientUserId: userId,
+          type: 'admin.custom_message',
+          title: 'Order shipped',
+          body: 'Your order is on its way',
+          data: { probe: 'tc-channel-push-005' },
+          pushOptions: { channelId: 'orders', badge: 3, sound: 'chime.caf' },
+        })
+
+      await drainIntegrationQueue('events')
+      await drainIntegrationQueue('push-deliveries')
+
+      await expect
+        .poll(async () => (await readLatestDelivery(tenantId, userDeviceId as string))?.status ?? null, {
+          timeout: 30_000,
+        })
+        .toBe('sent')
+
+      const row = await readLatestDelivery(tenantId, userDeviceId as string)
+      expect(row?.provider).toBe(PROVIDER)
+      expect(row?.token_snapshot).toBe(tokenTail)
+      expect(row?.organization_id).toBe(organizationId ?? null)
+
+      // The message firebase-admin would have transmitted — proof the real adapter, not a stub, ran.
+      const native = await expectNativeMessage(PROVIDER, tokenTail, startedAt)
+      expect(native.token).toBe(pushToken)
+      expect(native.notification).toMatchObject({ title: 'Order shipped', body: 'Your order is on its way' })
+      expect(native.android).toMatchObject({ notification: { channelId: 'orders', sound: 'chime.caf' } })
+      expect(native.apns).toMatchObject({ payload: { aps: { badge: 3, sound: 'chime.caf' } } })
+    } finally {
+      await deleteDeliveriesForDevice(userDeviceId)
+      await deleteFakePushDevice(request, adminToken, userDeviceId)
+      await deleteChannelIfExists(request, adminToken, channelId)
+    }
+  })
+})

package/src/modules/channel_fcm/acl.ts

@@ -0,0 +1,6 @@
+export const features = [
+  { id: 'channel_fcm.view', title: 'View FCM channel configuration', module: 'channel_fcm' },
+  { id: 'channel_fcm.configure', title: 'Configure FCM credentials', module: 'channel_fcm' },
+]
+
+export default features

package/src/modules/channel_fcm/di.ts

@@ -0,0 +1,27 @@
+import { asValue } from 'awilix'
+import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import {
+  hasChannelAdapter,
+  registerChannelAdapter,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter-registry-singleton'
+import { getFcmChannelAdapter } from './lib/adapter'
+import { ensureFcmFakeProviderInstalled } from './lib/fake-provider'
+import { channelFcmHealthCheck } from './lib/health'
+
+export function register(container: AppContainer): void {
+  // Test-only: swap firebase-admin for a network-free fake when `OM_PUSH_FAKE_PROVIDERS` is set
+  // (no-op in production), so integration specs exercise this adapter end-to-end. Swaps the SDK
+  // client only — the adapter below stays registered. See lib/fake-provider.ts.
+  ensureFcmFakeProviderInstalled()
+
+  if (!hasChannelAdapter('fcm')) {
+    registerChannelAdapter(getFcmChannelAdapter())
+  }
+  container.register({
+    channelFcmAdapter: asValue(getFcmChannelAdapter()),
+    // Registered under the exact service name declared in `integration.ts`
+    // (`healthCheck.service`); without it the hub's resolve throws and the
+    // channel reports permanently 'unhealthy'.
+    channelFcmHealthCheck: asValue(channelFcmHealthCheck),
+  })
+}

package/src/modules/channel_fcm/index.ts

@@ -0,0 +1,6 @@
+export const metadata = {
+  id: 'channel_fcm',
+  title: 'Firebase Cloud Messaging Channel',
+  description:
+    'Deliver mobile push to Android/iOS devices via Firebase Cloud Messaging. Registers a `push` ChannelAdapter (providerKey `fcm`) into the Communications Hub; consumed by the push_notifications delivery strategy.',
+}

package/src/modules/channel_fcm/integration.ts

@@ -0,0 +1,55 @@
+import {
+  type IntegrationBundle,
+  type IntegrationDefinition,
+} from '@open-mercato/shared/modules/integrations/types'
+
+export const integration: IntegrationDefinition = {
+  id: 'channel_fcm',
+  title: 'Firebase Cloud Messaging',
+  description:
+    'Deliver mobile push to Android (and iOS via FCM) devices using Firebase Cloud Messaging. Provider for the push_notifications channel.',
+  category: 'communication',
+  hub: 'communication_channels',
+  providerKey: 'fcm',
+  icon: 'firebase',
+  docsUrl: 'https://firebase.google.com/docs/cloud-messaging',
+  package: '@open-mercato/channel-fcm',
+  version: '0.1.0',
+  author: 'Open Mercato Team',
+  company: 'Open Mercato',
+  license: 'MIT',
+  tags: ['push', 'fcm', 'firebase', 'android', 'communication'],
+  apiVersions: [
+    {
+      id: 'v1',
+      label: 'FCM HTTP v1',
+      status: 'stable',
+      default: true,
+      changelog: 'Firebase Cloud Messaging HTTP v1 via firebase-admin (service-account auth).',
+    },
+  ],
+  credentials: {
+    fields: [
+      {
+        key: 'serviceAccountJson',
+        label: 'Service Account JSON',
+        type: 'secret',
+        required: true,
+        helpText:
+          'Firebase Console -> Project Settings -> Service Accounts -> Generate New Private Key. Paste the full JSON. Stored encrypted at rest.',
+      },
+      {
+        key: 'appName',
+        label: 'App Name (optional)',
+        type: 'text',
+        required: false,
+        helpText: 'Optional label for the Firebase app instance. Leave blank to auto-derive.',
+      },
+    ],
+  },
+  healthCheck: { service: 'channelFcmHealthCheck' },
+}
+
+export const integrations: IntegrationDefinition[] = [integration]
+export const bundles: IntegrationBundle[] = []
+export const bundle: IntegrationBundle | undefined = undefined

package/src/modules/channel_fcm/lib/__tests__/adapter-app-cache.test.ts

@@ -0,0 +1,84 @@
+import { getFcmChannelAdapter } from '../adapter'
+import type { SendMessageInput } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+
+type FakeApp = { name: string; delete: jest.Mock<Promise<void>, []> }
+
+const mockApps: FakeApp[] = []
+const mockDeletedNames: string[] = []
+
+jest.mock('firebase-admin/app', () => ({
+  cert: jest.fn((config: unknown) => ({ __cert: config })),
+  getApps: jest.fn(() => mockApps),
+  initializeApp: jest.fn((_options: unknown, name: string) => {
+    const app: FakeApp = {
+      name,
+      delete: jest.fn(async () => {
+        mockDeletedNames.push(name)
+        const index = mockApps.indexOf(app)
+        if (index >= 0) mockApps.splice(index, 1)
+      }),
+    }
+    mockApps.push(app)
+    return app
+  }),
+}))
+
+jest.mock('firebase-admin/messaging', () => ({
+  getMessaging: jest.fn(() => ({ send: jest.fn(async () => 'projects/demo/messages/1') })),
+}))
+
+function buildInputForPrivateKey(privateKey: string): SendMessageInput {
+  const serviceAccountJson = JSON.stringify({
+    project_id: 'demo-project',
+    client_email: 'svc@demo-project.iam.gserviceaccount.com',
+    private_key: privateKey,
+  })
+  return {
+    content: {
+      text: 'Body text',
+      bodyFormat: 'text',
+      raw: { title: 'Hello', body: 'Body text', data: { type: 'orders.shipped' } },
+    },
+    credentials: { serviceAccountJson },
+    scope: { tenantId: 't1', organizationId: 'o1' },
+    metadata: { pushToken: 'device-token-abc', platform: 'android' },
+  }
+}
+
+describe('FcmChannelAdapter default app cache', () => {
+  const APP_CACHE_MAX = 32
+
+  it('LRU-evicts the least-recently used app and calls app.delete() once the cap is exceeded', async () => {
+    const adapter = getFcmChannelAdapter()
+
+    // Fill the cache to its cap with distinct service accounts (distinct key hash → distinct app).
+    for (let index = 0; index < APP_CACHE_MAX; index += 1) {
+      const result = await adapter.sendMessage(buildInputForPrivateKey(`key-${index}`))
+      expect(result.status).toBe('sent')
+    }
+
+    expect(mockApps).toHaveLength(APP_CACHE_MAX)
+    expect(mockDeletedNames).toHaveLength(0)
+
+    // The (cap + 1)-th distinct account exceeds the bound and evicts the oldest app.
+    const overflow = await adapter.sendMessage(buildInputForPrivateKey('key-overflow'))
+    expect(overflow.status).toBe('sent')
+
+    expect(mockDeletedNames).toHaveLength(1)
+    expect(mockApps).toHaveLength(APP_CACHE_MAX)
+  })
+
+  it('reuses the cached app for repeated sends with the same service account (no new init, no delete)', async () => {
+    const before = mockApps.length
+    const deletesBefore = mockDeletedNames.length
+
+    const first = await getFcmChannelAdapter().sendMessage(buildInputForPrivateKey('key-overflow'))
+    const second = await getFcmChannelAdapter().sendMessage(buildInputForPrivateKey('key-overflow'))
+
+    expect(first.status).toBe('sent')
+    expect(second.status).toBe('sent')
+    // Same account → same cache entry; no additional app initialized, none evicted.
+    expect(mockApps.length).toBe(before)
+    expect(mockDeletedNames.length).toBe(deletesBefore)
+  })
+})

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

@@ -0,0 +1,176 @@
+import { getFcmChannelAdapter, setFcmMessagingFactory, type FcmMessagingFactory } from '../adapter'
+import type { SendMessageInput } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+
+const serviceAccountJson = JSON.stringify({
+  project_id: 'demo-project',
+  client_email: 'svc@demo-project.iam.gserviceaccount.com',
+  private_key: '-----BEGIN PRIVATE KEY-----\nMIIfake\n-----END PRIVATE KEY-----\n',
+})
+
+function buildInput(overrides?: Partial<SendMessageInput>): SendMessageInput {
+  return {
+    content: {
+      text: 'Body text',
+      bodyFormat: 'text',
+      raw: { title: 'Hello', body: 'Body text', data: { type: 'orders.shipped', notificationId: 'n1' } },
+    },
+    credentials: { serviceAccountJson },
+    scope: { tenantId: 't1', organizationId: 'o1' },
+    metadata: { pushToken: 'device-token-abc', platform: 'android' },
+    ...overrides,
+  }
+}
+
+afterEach(() => setFcmMessagingFactory(null))
+
+describe('FcmChannelAdapter', () => {
+  it('sends a notification and returns the provider message id', async () => {
+    const send = jest.fn().mockResolvedValue('projects/demo/messages/123')
+    const factory: FcmMessagingFactory = () => ({ send })
+    setFcmMessagingFactory(factory)
+
+    const result = await getFcmChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('sent')
+    expect(result.externalMessageId).toBe('projects/demo/messages/123')
+    expect(send).toHaveBeenCalledTimes(1)
+    const message = send.mock.calls[0][0]
+    expect(message.token).toBe('device-token-abc')
+    expect(message.notification).toEqual({ title: 'Hello', body: 'Body text' })
+    expect(message.data).toEqual({ type: 'orders.shipped', notificationId: 'n1' })
+  })
+
+  it('sends a data-only content-available message when the envelope is silent', async () => {
+    const send = jest.fn().mockResolvedValue('projects/demo/messages/silent')
+    setFcmMessagingFactory(() => ({ send }))
+
+    const result = await getFcmChannelAdapter().sendMessage(
+      buildInput({
+        content: { raw: { title: '', body: '', data: { type: 'sync.data.updated' }, silent: true } },
+      }),
+    )
+
+    expect(result.status).toBe('sent')
+    const message = send.mock.calls[0][0]
+    expect(message.notification).toBeUndefined()
+    expect(message.data).toEqual({ type: 'sync.data.updated' })
+    expect(message.apns.payload.aps['content-available']).toBe(1)
+    expect(message.apns.headers['apns-push-type']).toBe('background')
+  })
+
+  it('applies push options (sound/badge/image/priority/channel/body) to the native message', async () => {
+    const send = jest.fn().mockResolvedValue('projects/demo/messages/opts')
+    setFcmMessagingFactory(() => ({ send }))
+
+    await getFcmChannelAdapter().sendMessage(
+      buildInput({
+        content: {
+          raw: {
+            title: 'Hello',
+            body: 'Body text',
+            data: {},
+            options: {
+              sound: 'chime.caf',
+              badge: 3,
+              image: 'https://cdn/x.png',
+              priority: 'normal',
+              channelId: 'orders',
+              body: 'override body',
+            },
+          },
+        },
+      }),
+    )
+
+    const message = send.mock.calls[0][0]
+    expect(message.notification).toEqual({ title: 'Hello', body: 'override body', imageUrl: 'https://cdn/x.png' })
+    expect(message.android.priority).toBe('normal')
+    expect(message.android.notification).toEqual({ sound: 'chime.caf', channelId: 'orders', imageUrl: 'https://cdn/x.png' })
+    expect(message.apns.headers['apns-priority']).toBe('5')
+    expect(message.apns.payload.aps).toEqual({ sound: 'chime.caf', badge: 3 })
+  })
+
+  it('fails fast when the push token is missing', async () => {
+    const result = await getFcmChannelAdapter().sendMessage(buildInput({ metadata: { platform: 'android' } }))
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('missing_push_token')
+  })
+
+  it('rejects invalid credentials without attempting a send', async () => {
+    const send = jest.fn()
+    setFcmMessagingFactory(() => ({ send }))
+    const result = await getFcmChannelAdapter().sendMessage(buildInput({ credentials: {} }))
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('invalid_fcm_credentials')
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  it.each([
+    'messaging/registration-token-not-registered',
+    'messaging/invalid-registration-token',
+  ])('maps the permanent token error %s to the uniform device_unregistered sentinel', async (code) => {
+    const send = jest.fn().mockRejectedValue(
+      Object.assign(new Error('Requested entity was not found.'), { code }),
+    )
+    setFcmMessagingFactory(() => ({ send }))
+
+    const result = await getFcmChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('device_unregistered')
+    expect(result.metadata?.unregistered).toBe(true)
+  })
+
+  it('treats messaging/invalid-argument as a transient failure, NOT device_unregistered', async () => {
+    // invalid-argument fires for any malformed request field, not just a bad token — mapping it to
+    // device_unregistered would let a payload bug soft-delete devices tenant-wide.
+    const send = jest.fn().mockRejectedValue(
+      Object.assign(new Error('Invalid value at data.foo'), { code: 'messaging/invalid-argument' }),
+    )
+    setFcmMessagingFactory(() => ({ send }))
+
+    const result = await getFcmChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('failed')
+    expect(result.error).not.toBe('device_unregistered')
+    expect(result.metadata?.unregistered).toBeUndefined()
+  })
+
+  it('preserves the real error message when the messaging factory throws (transient init faults must not masquerade as bad credentials)', async () => {
+    setFcmMessagingFactory(() => {
+      throw new Error('failed to initialize firebase-admin app')
+    })
+    const result = await getFcmChannelAdapter().sendMessage(buildInput())
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('failed to initialize firebase-admin app')
+  })
+
+  it('validateCredentials accepts a well-formed service account', async () => {
+    const result = await getFcmChannelAdapter().validateCredentials({ credentials: { serviceAccountJson } })
+    expect(result.ok).toBe(true)
+  })
+
+  it('validateCredentials rejects malformed credentials with a populated errors map', async () => {
+    const result = await getFcmChannelAdapter().validateCredentials({ credentials: {} })
+    expect(result.ok).toBe(false)
+    expect(result.errors && Object.keys(result.errors).length).toBeGreaterThan(0)
+  })
+
+  it('treats other errors as transient (retryable) failures', async () => {
+    const send = jest.fn().mockRejectedValue(
+      Object.assign(new Error('temporarily unavailable'), { code: 'messaging/server-unavailable' }),
+    )
+    setFcmMessagingFactory(() => ({ send }))
+
+    const result = await getFcmChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('temporarily unavailable')
+    expect(result.metadata?.unregistered).toBeUndefined()
+  })
+
+  it('convertOutbound passes the body through unchanged', async () => {
+    const converted = await getFcmChannelAdapter().convertOutbound({ body: 'Hi', bodyFormat: 'text' })
+    expect(converted.content).toEqual({ text: 'Hi', bodyFormat: 'text' })
+  })
+})

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

@@ -0,0 +1,36 @@
+import { fcmCredentialsSchema, parseFcmServiceAccount } from '../credentials'
+
+const validJson = JSON.stringify({
+  project_id: 'demo-project',
+  client_email: 'svc@demo-project.iam.gserviceaccount.com',
+  private_key: '-----BEGIN PRIVATE KEY-----\nfake\n-----END PRIVATE KEY-----\n',
+})
+
+describe('fcmCredentialsSchema', () => {
+  it('accepts a well-formed service account JSON', () => {
+    const parsed = fcmCredentialsSchema.safeParse({ serviceAccountJson: validJson })
+    expect(parsed.success).toBe(true)
+  })
+
+  it('rejects missing service account JSON', () => {
+    const parsed = fcmCredentialsSchema.safeParse({})
+    expect(parsed.success).toBe(false)
+  })
+
+  it('rejects malformed JSON', () => {
+    const parsed = fcmCredentialsSchema.safeParse({ serviceAccountJson: '{not json' })
+    expect(parsed.success).toBe(false)
+  })
+
+  it('rejects JSON missing required service-account fields', () => {
+    const parsed = fcmCredentialsSchema.safeParse({ serviceAccountJson: JSON.stringify({ project_id: 'x' }) })
+    expect(parsed.success).toBe(false)
+  })
+
+  it('normalizes snake_case service account into camelCase', () => {
+    const account = parseFcmServiceAccount({ serviceAccountJson: validJson })
+    expect(account.projectId).toBe('demo-project')
+    expect(account.clientEmail).toBe('svc@demo-project.iam.gserviceaccount.com')
+    expect(account.privateKey).toContain('BEGIN PRIVATE KEY')
+  })
+})

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

@@ -0,0 +1,96 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import type { SendMessageInput } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  clearFakePushLog,
+  findFakePush,
+} from '@open-mercato/core/modules/push_notifications/lib/fake-provider-recorder'
+import { getFcmChannelAdapter, setFcmMessagingFactory } from '../adapter'
+import { ensureFcmFakeProviderInstalled } from '../fake-provider'
+
+/**
+ * Drives the REAL FCM adapter against the fake SDK client, the same way `di.ts` installs it. Guards the
+ * integration specs' assumptions in-process: the token sentinels, the native-message recording, and the
+ * `messaging/registration-token-not-registered` → `device_unregistered` mapping.
+ */
+const serviceAccountJson = JSON.stringify({
+  project_id: 'om-fake-project',
+  client_email: 'fake@om-fake-project.iam.gserviceaccount.com',
+  private_key: '-----BEGIN PRIVATE KEY-----\nom-fake-key\n-----END PRIVATE KEY-----\n',
+})
+
+function buildInput(pushToken: string): SendMessageInput {
+  return {
+    content: {
+      text: 'Body text',
+      bodyFormat: 'text',
+      raw: { title: 'Hello', body: 'Body text', data: { type: 'orders.shipped' }, options: { badge: 2 } },
+    },
+    credentials: { serviceAccountJson },
+    scope: { tenantId: 't1', organizationId: 'o1' },
+    metadata: { pushToken, platform: 'android' },
+  }
+}
+
+let tempDir: string
+
+beforeAll(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'om-fcm-fake-'))
+  process.env.QUEUE_BASE_DIR = tempDir
+  process.env.OM_PUSH_FAKE_PROVIDERS = '1'
+  ensureFcmFakeProviderInstalled()
+})
+
+afterAll(() => {
+  setFcmMessagingFactory(null)
+  delete process.env.OM_PUSH_FAKE_PROVIDERS
+  delete process.env.QUEUE_BASE_DIR
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+  clearFakePushLog()
+})
+
+describe('FCM fake provider', () => {
+  it('installs nothing when the env flag is unset, so production never reaches the fake', async () => {
+    setFcmMessagingFactory(null)
+    delete process.env.OM_PUSH_FAKE_PROVIDERS
+    ensureFcmFakeProviderInstalled()
+
+    // Re-enable the flag WITHOUT re-installing, so the recorder is armed. Any recording now could only
+    // come from a fake the flag-less `ensure...()` above wrongly installed. The adapter instead falls
+    // through to firebase-admin, which cannot initialize with these credentials.
+    process.env.OM_PUSH_FAKE_PROVIDERS = '1'
+    await getFcmChannelAdapter()
+      .sendMessage(buildInput('device-token-INERT001'))
+      .catch(() => undefined)
+    expect(findFakePush('fcm', 'INERT001')).toBeUndefined()
+
+    ensureFcmFakeProviderInstalled()
+  })
+
+  it('sends through the real adapter and records the native message', async () => {
+    const result = await getFcmChannelAdapter().sendMessage(buildInput('device-token-ABCDEF12'))
+    expect(result.status).toBe('sent')
+
+    const recorded = findFakePush('fcm', 'ABCDEF12')
+    expect(recorded).toBeTruthy()
+    expect(recorded?.native.token).toBe('device-token-ABCDEF12')
+    expect(recorded?.native.notification).toMatchObject({ title: 'Hello', body: 'Body text' })
+    expect(recorded?.native.apns).toMatchObject({ payload: { aps: { badge: 2 } } })
+  })
+
+  it('maps an unregistered token to the device_unregistered sentinel', async () => {
+    const result = await getFcmChannelAdapter().sendMessage(buildInput('device-unregistered-token-99'))
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('device_unregistered')
+  })
+
+  it('treats a fail token as a retryable error, not a token verdict', async () => {
+    const result = await getFcmChannelAdapter().sendMessage(buildInput('device-fail-token-77'))
+    expect(result.status).toBe('failed')
+    expect(result.error).not.toBe('device_unregistered')
+  })
+})