@open-mercato/core 0.6.8-develop.6983.1.e4f794099e → 0.6.8-develop.6985.1.fb93574faa

package/src/modules/push_notifications/i18n/pl.json

@@ -0,0 +1,79 @@
+{
+  "push_notifications.deliveries.columns.attempts": "Próby",
+  "push_notifications.deliveries.columns.created": "Utworzono",
+  "push_notifications.deliveries.columns.provider": "Dostawca",
+  "push_notifications.deliveries.columns.sent": "Wysłano",
+  "push_notifications.deliveries.columns.status": "Status",
+  "push_notifications.deliveries.columns.type": "Typ",
+  "push_notifications.deliveries.columns.user": "Użytkownik",
+  "push_notifications.deliveries.detail.device": "Urządzenie",
+  "push_notifications.deliveries.detail.lastError": "Ostatni błąd",
+  "push_notifications.deliveries.detail.loading": "Wczytywanie dostarczenia…",
+  "push_notifications.deliveries.detail.nextRetry": "Następna próba",
+  "push_notifications.deliveries.detail.pageTitle": "Dostarczenie push",
+  "push_notifications.deliveries.detail.payload": "Payload",
+  "push_notifications.deliveries.detail.providerResponse": "Odpowiedź dostawcy",
+  "push_notifications.deliveries.detail.tokenSnapshot": "Token (ostatnie 8)",
+  "push_notifications.deliveries.empty": "Brak dostarczeń push",
+  "push_notifications.deliveries.error.loadFailed": "Nie udało się wczytać dostarczeń push",
+  "push_notifications.deliveries.filters.created": "Utworzono",
+  "push_notifications.deliveries.filters.from": "Od",
+  "push_notifications.deliveries.filters.to": "Do",
+  "push_notifications.deliveries.noValue": "—",
+  "push_notifications.deliveries.pageTitle": "Dostarczenia push",
+  "push_notifications.deliveries.status.expired": "Wygasłe",
+  "push_notifications.deliveries.status.failed": "Nieudane",
+  "push_notifications.deliveries.status.pending": "Oczekujące",
+  "push_notifications.deliveries.status.sending": "Wysyłanie",
+  "push_notifications.deliveries.status.sent": "Wysłane",
+  "push_notifications.deliveries.status.skipped": "Pominięte",
+  "push_notifications.deliveries.title": "Dostarczenia push",
+  "push_notifications.errors.forbidden": "Brak dostępu",
+  "push_notifications.errors.invalid_id": "Nieprawidłowy identyfikator dostarczenia",
+  "push_notifications.errors.invalid_payload": "Nieprawidłowe żądanie",
+  "push_notifications.errors.not_found": "Nie znaleziono dostarczenia",
+  "push_notifications.errors.send_failed": "Nie udało się wysłać powiadomienia push",
+  "push_notifications.errors.server_error": "Coś poszło nie tak",
+  "push_notifications.errors.unauthorized": "Brak autoryzacji",
+  "push_notifications.send.badge": "Liczba na odznace",
+  "push_notifications.send.body": "Treść",
+  "push_notifications.send.channelId": "ID kanału Android",
+  "push_notifications.send.data": "Dane (własne klucze/wartości)",
+  "push_notifications.send.dataAdd": "Dodaj pole",
+  "push_notifications.send.dataEmpty": "Brak własnych danych.",
+  "push_notifications.send.dataHint": "Dostarczane w payloadzie push — odczytuje je Twoja aplikacja. Dla cichego push to całość danych.",
+  "push_notifications.send.dataKey": "klucz",
+  "push_notifications.send.dataRemove": "Usuń pole",
+  "push_notifications.send.dataValue": "wartość",
+  "push_notifications.send.device": "Urządzenie",
+  "push_notifications.send.deviceAll": "Wszystkie urządzenia",
+  "push_notifications.send.deviceHint": "Wyślij na to konkretne urządzenie lub na wszystkie urządzenia odbiorcy.",
+  "push_notifications.send.deviceNone": "Ten odbiorca nie ma urządzeń obsługujących push",
+  "push_notifications.send.deviceSelectUserFirst": "Najpierw wybierz odbiorcę",
+  "push_notifications.send.image": "URL obrazu",
+  "push_notifications.send.message": "Wiadomość",
+  "push_notifications.send.mode": "Dostarczenie",
+  "push_notifications.send.modeHint": "Widoczne pokazuje baner; ciche to dane w tle bez baneru.",
+  "push_notifications.send.modeSilent": "Ciche (w tle)",
+  "push_notifications.send.modeVisible": "Widoczne",
+  "push_notifications.send.options": "Opcje push",
+  "push_notifications.send.optionsHint": "Opcjonalne ustawienia dostawcy. Dźwięk/odznaka/obraz dotyczą powiadomień widocznych.",
+  "push_notifications.send.pageTitle": "Wyślij push",
+  "push_notifications.send.priority": "Priorytet",
+  "push_notifications.send.priorityDefault": "Domyślny",
+  "push_notifications.send.priorityHigh": "Wysoki",
+  "push_notifications.send.priorityNormal": "Normalny",
+  "push_notifications.send.sound": "Dźwięk",
+  "push_notifications.send.submit": "Wyślij push",
+  "push_notifications.send.success": "Push zakolejkowany do wysłania",
+  "push_notifications.send.title": "Tytuł",
+  "push_notifications.send.userId": "Odbiorca",
+  "push_notifications.send.userIdHint": "Wyszukaj po nazwie lub e-mailu — push trafi na jego urządzenia.",
+  "push_notifications.types.admin_custom_message.body": "Masz nową wiadomość.",
+  "push_notifications.types.admin_custom_message.label": "Wiadomość administratora",
+  "push_notifications.types.admin_custom_message.title": "Wiadomość administratora",
+  "push_notifications.types.admin_custom_silent.body": "Aktualizacja w tle.",
+  "push_notifications.types.admin_custom_silent.label": "Ciche powiadomienie administratora",
+  "push_notifications.types.admin_custom_silent.title": "Ciche powiadomienie",
+  "push_notifications.warnings.no_matching_devices_in_scope": "Żadne urządzenie odbiorcy obsługujące powiadomienia push nie pasowało do wybranego zakresu, więc nic nie wysłano."
+}

package/src/modules/push_notifications/index.ts

@@ -0,0 +1,15 @@
+import type { ModuleInfo } from '@open-mercato/shared/modules/registry'
+
+export const metadata: ModuleInfo = {
+  name: 'push_notifications',
+  title: 'Push Notifications',
+  version: '0.1.0',
+  description:
+    'Push delivery rails: a `push` notification delivery strategy that fans out to registered devices and sends through the communication_channels hub.',
+  author: 'Open Mercato Team',
+  license: 'MIT',
+  requires: ['auth', 'devices', 'notifications', 'communication_channels', 'integrations'],
+  ejectable: true,
+}
+
+export { features } from './acl'

package/src/modules/push_notifications/lib/fake-provider-recorder.ts

@@ -0,0 +1,154 @@
+import { randomBytes } from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('push_notifications')
+
+/**
+ * Test-only sink recording the **provider-native** message each push adapter handed its SDK client.
+ *
+ * The `channel-{fcm,apns,expo}` fakes replace the SDK *client*, not the adapter — so the real adapter
+ * builds the native message, but nothing persists it: no adapter returns `metadata` on success, and
+ * APNs deliberately reports an empty `externalMessageId` (its value reaches the admin-exposed
+ * `provider_response`, which must never carry token material). The message is therefore written here,
+ * out of band.
+ *
+ * **Why a file and not an in-memory recorder.** The adapter does not run in the spec's process, and
+ * *which* process it runs in is not fixed: the send happens in the Next.js app server (which may
+ * process the job inline), in a drain child that `drainIntegrationQueue` spawns whenever
+ * `OM_TEST_APP_ROOT` is set, or — only in the monorepo path — in the Playwright process itself. A
+ * module-level array would live in whichever of those three ran the adapter, and the spec could read it
+ * in just one. The queue already crosses exactly these boundaries through `QUEUE_BASE_DIR`, so the sink
+ * rides the same directory rather than inventing a second IPC channel.
+ *
+ * Production safety: every entry point is a no-op unless `OM_PUSH_FAKE_PROVIDERS` is set. Mirrors
+ * `ensurePushStubAdapterRegistered()` in ./push-stub-adapter.ts.
+ */
+export const PUSH_FAKE_PROVIDERS_ENV = 'OM_PUSH_FAKE_PROVIDERS'
+
+const LOG_FILE_NAME = 'push-fake-messages.jsonl'
+
+export type FakePushProvider = 'fcm' | 'apns' | 'expo'
+
+export type FakePushEntry = {
+  provider: FakePushProvider
+  tokenTail: string
+  native: Record<string, unknown>
+  at: string
+}
+
+export function isPushFakeProvidersEnabled(): boolean {
+  return parseBooleanToken(process.env[PUSH_FAKE_PROVIDERS_ENV]) === true
+}
+
+const warnedFakeProviders = new Set<FakePushProvider>()
+
+/**
+ * Loudly flag — exactly once per provider per process — that a push adapter is running against the
+ * network-free fake instead of the real SDK. `OM_PUSH_FAKE_PROVIDERS` is a test-harness flag, and a
+ * legitimate-but-misplaced `=1` (e.g. a staging env block promoted to prod) would otherwise report
+ * every push as `sent` with no delivery, no log line, and no admin signal for days. This warn plus the
+ * `degraded` health status (see `makePushClientConfigHealthCheck`) make that misconfiguration visible.
+ */
+export function warnPushFakeProvidersActive(provider: FakePushProvider): void {
+  if (!isPushFakeProvidersEnabled() || warnedFakeProviders.has(provider)) return
+  warnedFakeProviders.add(provider)
+  logger.warn(
+    `${provider} push adapter is running in FAKE mode (${PUSH_FAKE_PROVIDERS_ENV} is set): messages are recorded, NOT delivered. This must never be set in production.`,
+    { provider, env: PUSH_FAKE_PROVIDERS_ENV },
+  )
+}
+
+/**
+ * The one place the queue base dir is resolved. The worker process, the drain child, and the spec must
+ * all agree, so every caller goes through this: `QUEUE_BASE_DIR` when set (the harness always sets it,
+ * and `drainIntegrationQueue` propagates it to its child), else `<appRoot>/.mercato/queue`.
+ *
+ * In the app/worker process `cwd` IS the app root. The Playwright process runs from the repo root, so
+ * `helpers/integration/pushFake` sets `QUEUE_BASE_DIR` before anything reads it — this fallback is never
+ * reached there.
+ */
+export function resolveQueueBaseDir(): string {
+  const explicit = process.env.QUEUE_BASE_DIR?.trim()
+  if (explicit) return explicit
+  return path.resolve(process.env.OM_TEST_APP_ROOT?.trim() || process.cwd(), '.mercato/queue')
+}
+
+export function resolveFakePushLogPath(): string {
+  return path.join(resolveQueueBaseDir(), LOG_FILE_NAME)
+}
+
+/** Token tail used to key entries — never the raw token (mirrors `token_snapshot` on the delivery row). */
+export function pushTokenTail(token: string): string {
+  return token.slice(-8)
+}
+
+/**
+ * An 8-char token tail unique to this run.
+ *
+ * The sink is append-only and is NOT truncated between runs on the reused-environment path
+ * (`tryReuseExistingEnvironment` does not wipe `QUEUE_BASE_DIR`, unlike the fresh path). A compile-time
+ * constant tail would therefore let a *previous* run's entry satisfy an assertion before this run's
+ * worker had written anything — a false pass. Uniqueness also isolates specs running in parallel.
+ */
+export function uniquePushTokenTail(): string {
+  return randomBytes(4).toString('hex').toUpperCase()
+}
+
+export function recordFakePush(provider: FakePushProvider, token: string, native: Record<string, unknown>): void {
+  if (!isPushFakeProvidersEnabled()) return
+  const entry: FakePushEntry = {
+    provider,
+    tokenTail: pushTokenTail(token),
+    native,
+    at: new Date().toISOString(),
+  }
+  const filePath = resolveFakePushLogPath()
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  // A single `O_APPEND` write of one short line — concurrent deliveries interleave by line, not within one.
+  fs.appendFileSync(filePath, `${JSON.stringify(entry)}\n`, 'utf8')
+}
+
+function parseEntry(line: string): FakePushEntry | null {
+  try {
+    return JSON.parse(line) as FakePushEntry
+  } catch {
+    // A reader can observe a line the writer has not finished appending. Skipping it lets the caller
+    // poll again; throwing would permanently fail the enclosing `expect.poll`.
+    return null
+  }
+}
+
+export function readFakePushLog(): FakePushEntry[] {
+  const filePath = resolveFakePushLogPath()
+  if (!fs.existsSync(filePath)) return []
+  return fs
+    .readFileSync(filePath, 'utf8')
+    .split('\n')
+    .filter((line) => line.trim().length > 0)
+    .map(parseEntry)
+    .filter((entry): entry is FakePushEntry => entry !== null)
+}
+
+/**
+ * Find the message a spec's own device produced. `tokenTail` should come from
+ * {@link uniquePushTokenTail}; `sinceIso` additionally rejects entries predating the caller, so a stale
+ * sink can never satisfy an assertion.
+ */
+export function findFakePush(
+  provider: FakePushProvider,
+  tokenTail: string,
+  sinceIso?: string,
+): FakePushEntry | undefined {
+  return readFakePushLog()
+    .filter((entry) => entry.provider === provider && entry.tokenTail === tokenTail)
+    .filter((entry) => !sinceIso || entry.at >= sinceIso)
+    .pop()
+}
+
+export function clearFakePushLog(): void {
+  const filePath = resolveFakePushLogPath()
+  if (fs.existsSync(filePath)) fs.rmSync(filePath)
+}

package/src/modules/push_notifications/lib/push-delivery-strategy.ts

@@ -0,0 +1,90 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { NotificationDeliveryStrategy } from '@open-mercato/core/modules/notifications/lib/deliveryStrategies'
+import { getNotificationType } from '@open-mercato/core/modules/notifications/lib/notification-type-registry'
+import type { PushOptions } from '@open-mercato/core/modules/communication_channels/lib/push-envelope'
+import type { NotificationCopySource } from '@open-mercato/core/modules/notifications/lib/notificationCopy'
+import { fanOutPushDeliveries, PUSH_CHANNEL, type PushFanoutPayload } from './push-fanout'
+
+export { PUSH_CHANNEL } from './push-fanout'
+
+/**
+ * `push` notification delivery strategy.
+ *
+ * Registered into the notifications strategy seam (see notifications.delivery-strategies.ts).
+ * Runs inside the persistent `notifications:deliver` subscriber for every created notification.
+ * It only enqueues fast work — the actual provider send (with retry/backoff) happens in the
+ * `send-push` worker, so a slow/unavailable provider never blocks notification creation.
+ *
+ * Whether a push is silent (content-available wake-up) is a property of the registered
+ * notification TYPE (`NotificationTypeDefinition.silent`), never a per-call flag. `silent`
+ * controls only HOW the device is notified (background wake-up vs visible alert); it does not
+ * imply the push is non-opt-out. Silent types still respect the recipient's per-channel
+ * preference unless the type is `nonOptOut` — to force a silent push, mark the type
+ * `nonOptOut: true`. A silent push is therefore just a notification created through the normal
+ * `notificationService.create()` flow whose type is `silent: true`; there is no separate helper.
+ *
+ * The shared device/channel fan-out lives in {@link fanOutPushDeliveries}.
+ */
+export const mobilePushDeliveryStrategy: NotificationDeliveryStrategy = {
+  id: PUSH_CHANNEL,
+  label: 'Mobile push',
+  // Attempt push whenever a tenant has a push channel configured; the fan-out short-circuits
+  // (no rows, no enqueue) when push is not set up for the tenant/recipient.
+  defaultEnabled: true,
+  async deliver(ctx) {
+    const { notification } = ctx
+    const tenantId = notification.tenantId
+    const userId = notification.recipientUserId
+    const organizationId = notification.organizationId ?? null
+
+    // Skip unknown types (the catalogue is the source of truth for what can notify a user).
+    const type = getNotificationType(notification.type)
+    if (!type) return
+
+    const em = ctx.resolve('em') as EntityManager
+    const silent = type.silent === true
+
+    // Per-channel opt-out / `nonOptOut` is enforced once, upstream, at create time: the dispatcher
+    // only invokes this strategy when `push ∈ notification.channels` (the resolved target snapshot).
+    // `silent` still controls delivery STYLE only (content-available wake-up vs visible alert).
+
+    // App-readable data payload: caller-supplied custom fields plus the system identifiers.
+    const data: Record<string, string> = { ...(notification.data ?? {}) }
+    data.notificationId = notification.id
+    data.type = notification.type
+    if (notification.linkHref) data.linkHref = notification.linkHref
+
+    const payload: PushFanoutPayload = {
+      data,
+      options: (notification.pushOptions ?? undefined) as PushOptions | undefined,
+      silent,
+    }
+
+    // For visible notifications, hand the raw copy down so the fan-out can translate title/body per
+    // device locale. `ctx.title`/`ctx.body` are already resolved in the default locale and serve as
+    // the fallback. Silent pushes carry no user-facing copy, so they skip translation entirely.
+    const copy: NotificationCopySource | undefined = silent
+      ? undefined
+      : {
+          titleKey: notification.titleKey ?? null,
+          bodyKey: notification.bodyKey ?? null,
+          titleVariables: notification.titleVariables ?? null,
+          bodyVariables: notification.bodyVariables ?? null,
+          title: ctx.title,
+          body: ctx.body,
+        }
+
+    await fanOutPushDeliveries({
+      em,
+      resolve: ctx.resolve,
+      scope: { tenantId, organizationId },
+      userId,
+      notificationId: notification.id,
+      notificationTypeId: notification.type,
+      payload,
+      copy,
+    })
+  },
+}
+
+export default mobilePushDeliveryStrategy