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

package/src/modules/channel_expo/index.ts

@@ -0,0 +1,6 @@
+export const metadata = {
+  id: 'channel_expo',
+  title: 'Expo Push Channel',
+  description:
+    'Deliver mobile push to Expo apps via the Expo push service. Registers a `push` ChannelAdapter (providerKey `expo`) into the Communications Hub; consumed by the push_notifications delivery strategy.',
+}

package/src/modules/channel_expo/integration.ts

@@ -0,0 +1,48 @@
+import {
+  type IntegrationBundle,
+  type IntegrationDefinition,
+} from '@open-mercato/shared/modules/integrations/types'
+
+export const integration: IntegrationDefinition = {
+  id: 'channel_expo',
+  title: 'Expo Push',
+  description:
+    'Deliver mobile push to Expo apps via the Expo push service (ExponentPushToken). Provider for the push_notifications channel.',
+  category: 'communication',
+  hub: 'communication_channels',
+  providerKey: 'expo',
+  icon: 'expo',
+  docsUrl: 'https://docs.expo.dev/push-notifications/sending-notifications/',
+  package: '@open-mercato/channel-expo',
+  version: '0.1.0',
+  author: 'Open Mercato Team',
+  company: 'Open Mercato',
+  license: 'MIT',
+  tags: ['push', 'expo', 'react-native', 'communication'],
+  apiVersions: [
+    {
+      id: 'v1',
+      label: 'Expo Push API',
+      status: 'stable',
+      default: true,
+      changelog: 'Expo push service via expo-server-sdk (ExponentPushToken delivery).',
+    },
+  ],
+  credentials: {
+    fields: [
+      {
+        key: 'accessToken',
+        label: 'Expo Access Token (optional)',
+        type: 'secret',
+        required: false,
+        helpText:
+          'Only required when Expo enhanced push security is enabled for the project. Expo dashboard -> Account -> Access Tokens. Stored encrypted at rest.',
+      },
+    ],
+  },
+  healthCheck: { service: 'channelExpoHealthCheck' },
+}
+
+export const integrations: IntegrationDefinition[] = [integration]
+export const bundles: IntegrationBundle[] = []
+export const bundle: IntegrationBundle | undefined = undefined

package/src/modules/channel_expo/lib/__tests__/adapter-instance-cache.test.ts

@@ -0,0 +1,65 @@
+import { getExpoChannelAdapter } from '../adapter'
+import type { SendMessageInput } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+
+// Drive the REAL default client factory (no setExpoClientFactory override) so the module-level
+// instance cache in getExpoInstance is exercised. Mock the SDK so each `new Expo(...)` is countable.
+let constructionCount = 0
+
+jest.mock('expo-server-sdk', () => {
+  class FakeExpo {
+    constructor(_options: { accessToken?: string }) {
+      constructionCount += 1
+    }
+    static isExpoPushToken(): boolean {
+      return true
+    }
+    async sendPushNotificationsAsync(): Promise<Array<{ status: string; id: string }>> {
+      return [{ status: 'ok', id: 'ticket' }]
+    }
+  }
+  return { Expo: FakeExpo }
+})
+
+function buildInputForToken(accessToken: string): SendMessageInput {
+  return {
+    content: {
+      text: 'Body text',
+      bodyFormat: 'text',
+      raw: { title: 'Hello', body: 'Body text', data: { type: 'orders.shipped', notificationId: 'n1' } },
+    },
+    credentials: { accessToken },
+    scope: { tenantId: 't1', organizationId: 'o1' },
+    metadata: { pushToken: 'ExponentPushToken[abc]', platform: 'ios' },
+  }
+}
+
+describe('ExpoChannelAdapter default instance cache', () => {
+  const INSTANCE_CACHE_MAX = 32
+
+  it('bounds the cache with an LRU: reuses cached instances, evicts the oldest past the cap', async () => {
+    const adapter = getExpoChannelAdapter()
+
+    // Fill the cache to its cap with distinct access tokens (distinct cache key → distinct instance).
+    for (let index = 0; index < INSTANCE_CACHE_MAX; index += 1) {
+      const result = await adapter.sendMessage(buildInputForToken(`token-${index}`))
+      expect(result.status).toBe('sent')
+    }
+    expect(constructionCount).toBe(INSTANCE_CACHE_MAX)
+
+    // Re-sending with a token already cached reuses its instance — no new construction.
+    await adapter.sendMessage(buildInputForToken('token-5'))
+    expect(constructionCount).toBe(INSTANCE_CACHE_MAX)
+
+    // The (cap + 1)-th distinct token exceeds the bound and evicts the oldest entry (token-0).
+    await adapter.sendMessage(buildInputForToken('token-overflow'))
+    expect(constructionCount).toBe(INSTANCE_CACHE_MAX + 1)
+
+    // token-0 was evicted, so using it again re-constructs a fresh instance...
+    await adapter.sendMessage(buildInputForToken('token-0'))
+    expect(constructionCount).toBe(INSTANCE_CACHE_MAX + 2)
+
+    // ...while a token still resident in the cache is served without re-construction.
+    await adapter.sendMessage(buildInputForToken('token-overflow'))
+    expect(constructionCount).toBe(INSTANCE_CACHE_MAX + 2)
+  })
+})

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

@@ -0,0 +1,211 @@
+import {
+  getExpoChannelAdapter,
+  setExpoClientFactory,
+  type ExpoClientLike,
+  type ExpoPushReceipt,
+  type ExpoPushTicket,
+} from '../adapter'
+import type { SendMessageInput } from '@open-mercato/core/modules/communication_channels/lib/adapter'
+
+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: {},
+    scope: { tenantId: 't1', organizationId: 'o1' },
+    metadata: { pushToken: 'ExponentPushToken[abc]', platform: 'ios' },
+    ...overrides,
+  }
+}
+
+function buildClient(ticket: ExpoPushTicket, validToken = true): { client: ExpoClientLike; send: jest.Mock } {
+  const send = jest.fn(async () => [ticket])
+  const client: ExpoClientLike = { isExpoPushToken: () => validToken, send, getReceipts: async () => ({}) }
+  return { client, send }
+}
+
+function buildReceiptClient(receipts: Record<string, ExpoPushReceipt>): {
+  client: ExpoClientLike
+  getReceipts: jest.Mock
+} {
+  const getReceipts = jest.fn(async (ticketIds: string[]) => {
+    const out: Record<string, ExpoPushReceipt> = {}
+    for (const id of ticketIds) if (receipts[id]) out[id] = receipts[id]
+    return out
+  })
+  const client: ExpoClientLike = { isExpoPushToken: () => true, send: jest.fn(async () => []), getReceipts }
+  return { client, getReceipts }
+}
+
+afterEach(() => setExpoClientFactory(null))
+
+describe('ExpoChannelAdapter', () => {
+  it('sends a push and returns the ticket id', async () => {
+    const { client, send } = buildClient({ status: 'ok', id: 'ticket-1' })
+    setExpoClientFactory(() => client)
+
+    const result = await getExpoChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('sent')
+    expect(result.externalMessageId).toBe('ticket-1')
+    const messages = send.mock.calls[0][0]
+    expect(messages[0]).toMatchObject({
+      to: 'ExponentPushToken[abc]',
+      title: 'Hello',
+      body: 'Body text',
+      sound: 'default',
+    })
+    expect(messages[0].data).toEqual({ type: 'orders.shipped', notificationId: 'n1' })
+  })
+
+  it('sends a data-only content-available message when silent', async () => {
+    const { client, send } = buildClient({ status: 'ok', id: 'ticket-silent' })
+    setExpoClientFactory(() => client)
+
+    const result = await getExpoChannelAdapter().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][0]
+    expect(message).toEqual({ to: 'ExponentPushToken[abc]', data: { type: 'sync.data.updated' }, _contentAvailable: true })
+    expect(message.title).toBeUndefined()
+    expect(message.body).toBeUndefined()
+  })
+
+  it('applies push options (sound/badge/priority/channel/image/body)', async () => {
+    const { client, send } = buildClient({ status: 'ok', id: 'ticket-opts' })
+    setExpoClientFactory(() => client)
+
+    await getExpoChannelAdapter().sendMessage(
+      buildInput({
+        content: {
+          raw: {
+            title: 'Hello',
+            body: 'Body text',
+            data: {},
+            options: {
+              sound: 'chime.caf',
+              badge: 5,
+              priority: 'high',
+              channelId: 'orders',
+              image: 'https://cdn/x.png',
+              body: 'override body',
+            },
+          },
+        },
+      }),
+    )
+
+    expect(send.mock.calls[0][0][0]).toMatchObject({
+      to: 'ExponentPushToken[abc]',
+      title: 'Hello',
+      body: 'override body',
+      sound: 'chime.caf',
+      badge: 5,
+      priority: 'high',
+      channelId: 'orders',
+      richContent: { image: 'https://cdn/x.png' },
+    })
+  })
+
+  it('fails fast when the push token is missing', async () => {
+    const result = await getExpoChannelAdapter().sendMessage(buildInput({ metadata: { platform: 'ios' } }))
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('missing_push_token')
+  })
+
+  it('maps a malformed Expo token to the device_unregistered sentinel', async () => {
+    const { client, send } = buildClient({ status: 'ok' }, false)
+    setExpoClientFactory(() => client)
+
+    const result = await getExpoChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('device_unregistered')
+    expect(result.metadata?.unregistered).toBe(true)
+    expect(send).not.toHaveBeenCalled()
+  })
+
+  it('maps a DeviceNotRegistered ticket to the device_unregistered sentinel', async () => {
+    const { client } = buildClient({ status: 'error', message: 'gone', details: { error: 'DeviceNotRegistered' } })
+    setExpoClientFactory(() => client)
+
+    const result = await getExpoChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('device_unregistered')
+    expect(result.metadata?.unregistered).toBe(true)
+  })
+
+  it('treats other ticket errors as transient failures', async () => {
+    const { client } = buildClient({ status: 'error', message: 'MessageRateExceeded', details: { error: 'MessageRateExceeded' } })
+    setExpoClientFactory(() => client)
+
+    const result = await getExpoChannelAdapter().sendMessage(buildInput())
+
+    expect(result.status).toBe('failed')
+    expect(result.error).toBe('MessageRateExceeded')
+    expect(result.metadata?.unregistered).toBeUndefined()
+  })
+})
+
+describe('ExpoChannelAdapter.checkReceipts', () => {
+  it('flags a DeviceNotRegistered receipt as unregistered (the async "app uninstalled" case)', async () => {
+    const { client, getReceipts } = buildReceiptClient({
+      'ticket-dead': { status: 'error', message: 'gone', details: { error: 'DeviceNotRegistered' } },
+    })
+    setExpoClientFactory(() => client)
+
+    const outcomes = await getExpoChannelAdapter().checkReceipts(['ticket-dead'], {})
+
+    expect(getReceipts).toHaveBeenCalledWith(['ticket-dead'])
+    expect(outcomes).toEqual([{ ticketId: 'ticket-dead', unregistered: true }])
+  })
+
+  it('resolves an ok receipt without killing the token', async () => {
+    const { client } = buildReceiptClient({ 'ticket-ok': { status: 'ok' } })
+    setExpoClientFactory(() => client)
+
+    const outcomes = await getExpoChannelAdapter().checkReceipts(['ticket-ok'], {})
+
+    expect(outcomes).toEqual([{ ticketId: 'ticket-ok', unregistered: false }])
+  })
+
+  it('treats MessageRateExceeded as transient (receipt resolved, token kept)', async () => {
+    const { client } = buildReceiptClient({
+      'ticket-rate': { status: 'error', details: { error: 'MessageRateExceeded' } },
+    })
+    setExpoClientFactory(() => client)
+
+    const outcomes = await getExpoChannelAdapter().checkReceipts(['ticket-rate'], {})
+
+    expect(outcomes).toEqual([{ ticketId: 'ticket-rate', unregistered: false }])
+  })
+
+  it('omits tickets whose receipt is not ready yet (re-checked on a later sweep)', async () => {
+    const { client } = buildReceiptClient({
+      'ticket-ready': { status: 'ok' },
+    })
+    setExpoClientFactory(() => client)
+
+    const outcomes = await getExpoChannelAdapter().checkReceipts(['ticket-ready', 'ticket-pending'], {})
+
+    expect(outcomes).toEqual([{ ticketId: 'ticket-ready', unregistered: false }])
+  })
+
+  it('short-circuits with no network call when there are no usable ticket ids', async () => {
+    const { client, getReceipts } = buildReceiptClient({})
+    setExpoClientFactory(() => client)
+
+    const outcomes = await getExpoChannelAdapter().checkReceipts(['', ''], {})
+
+    expect(outcomes).toEqual([])
+    expect(getReceipts).not.toHaveBeenCalled()
+  })
+})

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

@@ -0,0 +1,18 @@
+import { expoCredentialsSchema } from '../credentials'
+
+describe('expoCredentialsSchema', () => {
+  it('accepts credentials with an access token', () => {
+    const parsed = expoCredentialsSchema.safeParse({ accessToken: 'expo-access-token' })
+    expect(parsed.success).toBe(true)
+  })
+
+  it('accepts credentials without the optional access token', () => {
+    const parsed = expoCredentialsSchema.safeParse({})
+    expect(parsed.success).toBe(true)
+  })
+
+  it('rejects malformed input', () => {
+    expect(expoCredentialsSchema.safeParse({ accessToken: 123 }).success).toBe(false)
+    expect(expoCredentialsSchema.safeParse('not-an-object').success).toBe(false)
+  })
+})

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

@@ -0,0 +1,94 @@
+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 { getExpoChannelAdapter, setExpoClientFactory } from '../adapter'
+import { ensureExpoFakeProviderInstalled } from '../fake-provider'
+
+/**
+ * Drives the REAL Expo adapter against the fake client, the same way `di.ts` installs it.
+ *
+ * Expo is the only two-phase provider: an `unregistered` token is ACCEPTED at send time and only
+ * reported dead later, by the receipt. That asymmetry is what TC-PUSH-008 exercises end-to-end, and what
+ * the ticket-id encoding below makes work across processes.
+ */
+function buildInput(pushToken: string): SendMessageInput {
+  return {
+    content: {
+      text: 'Body text',
+      bodyFormat: 'text',
+      raw: { title: 'Hello', body: 'Body text', data: { type: 'orders.shipped' }, options: { sound: 'chime.caf' } },
+    },
+    credentials: { accessToken: 'om-fake-expo-token' },
+    scope: { tenantId: 't1', organizationId: 'o1' },
+    metadata: { pushToken, platform: 'android' },
+  }
+}
+
+let tempDir: string
+
+beforeAll(() => {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'om-expo-fake-'))
+  process.env.QUEUE_BASE_DIR = tempDir
+  process.env.OM_PUSH_FAKE_PROVIDERS = '1'
+  ensureExpoFakeProviderInstalled()
+})
+
+afterAll(() => {
+  setExpoClientFactory(null)
+  delete process.env.OM_PUSH_FAKE_PROVIDERS
+  delete process.env.QUEUE_BASE_DIR
+  fs.rmSync(tempDir, { recursive: true, force: true })
+})
+
+beforeEach(() => {
+  clearFakePushLog()
+})
+
+describe('Expo fake provider', () => {
+  it('sends through the real adapter and records the native message', async () => {
+    const result = await getExpoChannelAdapter().sendMessage(buildInput('expo-token-ABCDEF12'))
+    expect(result.status).toBe('sent')
+    expect(result.externalMessageId).toBeTruthy()
+
+    const recorded = findFakePush('expo', 'ABCDEF12')
+    expect(recorded?.native).toMatchObject({
+      to: 'expo-token-ABCDEF12',
+      title: 'Hello',
+      body: 'Body text',
+      sound: 'chime.caf',
+    })
+  })
+
+  it('accepts an unregistered token at send time — Expo only reports it in the receipt', async () => {
+    const result = await getExpoChannelAdapter().sendMessage(buildInput('expo-unregistered-token-99'))
+    expect(result.status).toBe('sent')
+    expect(result.externalMessageId).toBeTruthy()
+  })
+
+  it('reports DeviceNotRegistered for that ticket when the receipt is polled', async () => {
+    const sent = await getExpoChannelAdapter().sendMessage(buildInput('expo-unregistered-token-99'))
+    const outcomes = await getExpoChannelAdapter().checkReceipts!([sent.externalMessageId], {
+      accessToken: 'om-fake-expo-token',
+    })
+    expect(outcomes).toEqual([{ ticketId: sent.externalMessageId, unregistered: true }])
+  })
+
+  it('reports a healthy ticket as still registered', async () => {
+    const sent = await getExpoChannelAdapter().sendMessage(buildInput('expo-token-ABCDEF12'))
+    const outcomes = await getExpoChannelAdapter().checkReceipts!([sent.externalMessageId], {
+      accessToken: 'om-fake-expo-token',
+    })
+    expect(outcomes).toEqual([{ ticketId: sent.externalMessageId, unregistered: false }])
+  })
+
+  it('treats a fail token as a retryable error, not a token verdict', async () => {
+    const result = await getExpoChannelAdapter().sendMessage(buildInput('expo-fail-token-77'))
+    expect(result.status).toBe('failed')
+    expect(result.error).not.toBe('device_unregistered')
+  })
+})

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

@@ -0,0 +1,77 @@
+import type { PushEnvelope } from '@open-mercato/core/modules/communication_channels/lib/push-envelope'
+import { buildExpoMessage } from '../adapter'
+
+/**
+ * Golden assertions pinning the Expo push message we build against Expo's published reference.
+ *
+ * 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 *Expo's* schema is
+ * out of reach of any fake and stays a manual live-key check.
+ *
+ * Reference: https://docs.expo.dev/push-notifications/sending-notifications/#message-request-format
+ * `_contentAvailable` (data-only iOS background wake-up):
+ *   https://docs.expo.dev/push-notifications/sending-notifications/#formats
+ *
+ * Written as exact `toEqual` fixtures rather than snapshots: a snapshot would re-record drift on
+ * `--updateSnapshot` instead of failing.
+ */
+const TOKEN = 'ExponentPushToken[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('buildExpoMessage — golden payloads', () => {
+  it('visible notification matches the reference shape', () => {
+    expect(buildExpoMessage(TOKEN, envelope())).toEqual({
+      to: TOKEN,
+      title: 'Order shipped',
+      body: 'Your order #42 is on its way',
+      data: { type: 'orders.shipped', notificationId: 'n1' },
+      sound: 'default',
+    })
+  })
+
+  it('silent notification is data-only with _contentAvailable and no user-facing copy', () => {
+    expect(buildExpoMessage(TOKEN, envelope({ silent: true }))).toEqual({
+      to: TOKEN,
+      data: { type: 'orders.shipped', notificationId: 'n1' },
+      _contentAvailable: true,
+    })
+  })
+
+  it('full pushOptions map onto the message', () => {
+    expect(
+      buildExpoMessage(
+        TOKEN,
+        envelope({
+          options: {
+            sound: 'chime.caf',
+            badge: 7,
+            image: 'https://cdn.example.com/hero.png',
+            priority: 'high',
+            channelId: 'orders',
+            body: 'Overridden push body',
+          },
+        }),
+      ),
+    ).toEqual({
+      to: TOKEN,
+      title: 'Order shipped',
+      body: 'Overridden push body',
+      data: { type: 'orders.shipped', notificationId: 'n1' },
+      sound: 'chime.caf',
+      badge: 7,
+      priority: 'high',
+      channelId: 'orders',
+      richContent: { image: 'https://cdn.example.com/hero.png' },
+    })
+  })
+})