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

package/src/modules/push_notifications/lib/push-stub-adapter.ts

@@ -0,0 +1,80 @@
+import { z } from 'zod'
+import type {
+  SendMessageInput,
+  SendMessageResult,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter'
+import {
+  BasePushChannelAdapter,
+  deviceUnregisteredResult,
+  readPushToken,
+} from '@open-mercato/core/modules/communication_channels/lib/push-adapter'
+import { readPushEnvelope } from '@open-mercato/core/modules/communication_channels/lib/push-envelope'
+import {
+  hasChannelAdapter,
+  registerChannelAdapter,
+} from '@open-mercato/core/modules/communication_channels/lib/adapter-registry-singleton'
+
+/**
+ * In-process, network-free `push` channel adapter used ONLY by tests.
+ *
+ * Real provider adapters (FCM/APNs/Expo) land in Phase 4 as separate channel packages. Phase 3 ships
+ * this stub so the strategy → delivery-row → worker → `sendMessage` chain is exercisable end-to-end.
+ *
+ * Token sentinels let a test drive each worker branch deterministically:
+ *   - a token containing `unregistered` → the uniform `unregistered` shape (worker soft-deletes the device)
+ *   - a token containing `fail`         → a retryable failure (worker retries then marks `failed`)
+ *   - otherwise                          → `sent`
+ *
+ * Production safety: never registered at module import. The integration harness calls
+ * {@link ensurePushStubAdapterRegistered}, gated by `OM_ENABLE_PUSH_STUB_ADAPTER`.
+ */
+export const PUSH_STUB_PROVIDER_KEY = 'push_stub'
+export const PUSH_STUB_ENV = 'OM_ENABLE_PUSH_STUB_ADAPTER'
+
+export function isPushStubEnabled(): boolean {
+  const raw = process.env[PUSH_STUB_ENV]
+  if (typeof raw !== 'string') return false
+  return ['1', 'true', 'yes', 'on'].includes(raw.trim().toLowerCase())
+}
+
+class PushStubChannelAdapter extends BasePushChannelAdapter {
+  readonly providerKey = PUSH_STUB_PROVIDER_KEY
+  protected readonly credentialsSchema = z.object({}).passthrough()
+
+  async sendMessage(input: SendMessageInput): Promise<SendMessageResult> {
+    const token = readPushToken(input) ?? ''
+    if (token.includes('unregistered')) {
+      return deviceUnregisteredResult({ stub: true })
+    }
+    if (token.includes('fail')) {
+      return { externalMessageId: '', status: 'failed', error: 'push_stub_forced_failure', metadata: { stub: true } }
+    }
+    // Surface the resolved envelope (silent flag, custom data, mapped options) so
+    // integration tests can assert what the worker handed the adapter per delivery.
+    const envelope = readPushEnvelope(input.content)
+    return {
+      externalMessageId: `push-stub-${token.slice(-8) || 'token'}`,
+      status: 'sent',
+      metadata: {
+        stub: true,
+        silent: envelope.silent,
+        data: envelope.data,
+        options: envelope.options,
+      },
+    }
+  }
+}
+
+let cachedPushStubAdapter: PushStubChannelAdapter | null = null
+
+export function getPushStubAdapter(): PushStubChannelAdapter {
+  if (!cachedPushStubAdapter) cachedPushStubAdapter = new PushStubChannelAdapter()
+  return cachedPushStubAdapter
+}
+
+/** Register the push stub adapter once, ONLY when the test env flag is set. No-op otherwise. */
+export function ensurePushStubAdapterRegistered(): void {
+  if (!isPushStubEnabled()) return
+  if (hasChannelAdapter(PUSH_STUB_PROVIDER_KEY)) return
+  registerChannelAdapter(getPushStubAdapter())
+}

package/src/modules/push_notifications/lib/queue.ts

@@ -0,0 +1,74 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { createModuleQueue, type Queue } from '@open-mercato/queue'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('push_notifications')
+
+export interface PushDeliveryJob {
+  deliveryId: string
+  tenantId: string
+  organizationId: string | null
+}
+
+export const PUSH_DELIVERIES_QUEUE = 'push-deliveries'
+// Scheduler-driven tick that recovers rows stranded in `sending` by a crashed worker (see
+// lib/push-reaper.ts). The `@open-mercato/scheduler` interval entry registered in setup.ts enqueues
+// one tick per tenant onto this queue; the reclaim-stuck worker processes it.
+export const PUSH_STUCK_RECLAIM_QUEUE = 'push-stuck-reclaim'
+
+const queues = new Map<string, Queue<PushDeliveryJob>>()
+const LOCAL_WORKER_PROMISE_KEY = '__openMercatoPushLocalWorkerPromise__'
+
+export function getPushQueue(queueName: string = PUSH_DELIVERIES_QUEUE): Queue<PushDeliveryJob> {
+  const existing = queues.get(queueName)
+  if (existing) return existing
+
+  const concurrency = Math.max(1, Number.parseInt(process.env.PUSH_QUEUE_CONCURRENCY ?? '8', 10) || 8)
+  const created = createModuleQueue<PushDeliveryJob>(queueName, { concurrency })
+
+  queues.set(queueName, created)
+  return created
+}
+
+// In local (dev/test) queue mode jobs are processed in-process. In async mode the
+// auto-discovered `workers/send-push.worker.ts` handles them, so this is a no-op there.
+async function ensureLocalPushQueueWorkerStarted(): Promise<void> {
+  if (process.env.QUEUE_STRATEGY === 'async') return
+
+  const globalStore = globalThis as typeof globalThis & {
+    [LOCAL_WORKER_PROMISE_KEY]?: Promise<void>
+  }
+
+  if (globalStore[LOCAL_WORKER_PROMISE_KEY]) {
+    await globalStore[LOCAL_WORKER_PROMISE_KEY]
+    return
+  }
+
+  globalStore[LOCAL_WORKER_PROMISE_KEY] = (async () => {
+    const queue = getPushQueue()
+
+    await queue.process(async (job) => {
+      const [{ createRequestContainer }, { processPushDeliveryJob }] = await Promise.all([
+        import('@open-mercato/shared/lib/di/container'),
+        import('./push-delivery'),
+      ])
+
+      const container = await createRequestContainer()
+      const em = (container.resolve('em') as EntityManager).fork()
+      await processPushDeliveryJob(em, job.payload, (name) => container.resolve(name))
+    })
+  })().catch((error) => {
+    delete globalStore[LOCAL_WORKER_PROMISE_KEY]
+    logger.error('Failed to start local delivery worker', { error })
+    throw error
+  })
+
+  await globalStore[LOCAL_WORKER_PROMISE_KEY]
+}
+
+export async function enqueuePushDelivery(job: PushDeliveryJob, delayMs?: number): Promise<string> {
+  const queue = getPushQueue()
+  const jobId = await queue.enqueue(job, delayMs && delayMs > 0 ? { delayMs } : undefined)
+  await ensureLocalPushQueueWorkerStarted()
+  return jobId
+}

package/src/modules/push_notifications/lib/reclaim-window.ts

@@ -0,0 +1,16 @@
+// Single source of truth for the stuck-reclaim window. The reaper uses it to decide when a `sending`
+// row is abandoned; the send path uses it to bound a single provider send so a hung call can never
+// outlive the window (which would let the reaper reclaim the row mid-send). Keeping both on one resolver
+// guarantees the send timeout stays below the reclaim threshold — see push-delivery.ts.
+//
+// A floor of MIN_STUCK_MINUTES is enforced: `0` (the old "reclaim on the next tick") is UNSAFE because
+// `cutoff = now` matches an actively-`sending` row whose `updated_at` was stamped at claim, re-opening
+// an in-flight send. Sub-floor / negative / non-numeric values fall back to the default.
+export const DEFAULT_STUCK_MINUTES = 5
+export const MIN_STUCK_MINUTES = 1
+
+export function resolveStuckThresholdMs(): number {
+  const raw = Number.parseInt(process.env.OM_PUSH_STUCK_RECLAIM_MINUTES ?? '', 10)
+  const minutes = Number.isFinite(raw) && raw >= MIN_STUCK_MINUTES ? raw : DEFAULT_STUCK_MINUTES
+  return minutes * 60 * 1000
+}

package/src/modules/push_notifications/lib/send-custom-push.ts

@@ -0,0 +1,100 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+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 { ADMIN_CUSTOM_MESSAGE_TYPE, ADMIN_CUSTOM_SILENT_TYPE } from '../notifications'
+import { fanOutPushDeliveries } from './push-fanout'
+
+type Resolve = <T = unknown>(name: string) => T
+
+export interface SendCustomPushArgs {
+  /** Scoped DI resolver (e.g. an API route's request container `resolve`). */
+  resolve: Resolve
+  tenantId: string
+  userId: string
+  organizationId?: string | null
+  /** Restrict delivery to one of the user's devices (`UserDevice.id`). Omit to send to all. */
+  deviceId?: string
+  /** Literal, already-authored push title (free text — not an i18n key, so not translated). */
+  title: string
+  /** Optional literal push body. */
+  body?: string | null
+  /** Arbitrary app-readable key/values delivered in the push data payload. */
+  data?: Record<string, string>
+  /** Optional per-provider push customization (sound, badge, priority, …). */
+  pushOptions?: PushOptions
+  /**
+   * When true, deliver as a **silent** data-only content-available wake-up (no visible banner)
+   * instead of a visible alert. Defaults to false (visible).
+   */
+  silent?: boolean
+  /**
+   * Registered notification type to label the delivery with. Defaults to the admin custom-message
+   * type (visible) or the admin custom-silent type when `silent` is set. Its `silent` flag MUST
+   * match the requested mode.
+   */
+  type?: string
+}
+
+/**
+ * Deliver an admin-composed, one-off push to all of a user's push-capable devices — **visible**
+ * (literal title/body banner) or **silent** (`silent: true` — a data-only content-available wake-up
+ * with no banner).
+ *
+ * A direct fan-out (no in-app `Notification` row, no email, no per-channel preference check). The
+ * `type` MUST be registered and its `silent` flag MUST match the requested mode. Because the copy is
+ * literal free text, it is delivered verbatim (no per-device locale translation). The actual provider
+ * send happens in the `send-push` worker; the returned `enqueued` is the number of per-device jobs.
+ *
+ * Note: delivery here is forced by the direct fan-out itself — this path never consults the
+ * preference service, so the type's `nonOptOut: true` is not load-bearing on this route (it matters
+ * only if that type is ever routed through the normal preference-gated `notificationService.create()`
+ * strategy).
+ */
+export async function sendCustomPush(args: SendCustomPushArgs): Promise<{ enqueued: number }> {
+  const {
+    resolve,
+    tenantId,
+    userId,
+    organizationId = null,
+    deviceId,
+    title,
+    body = null,
+    data,
+    pushOptions,
+    silent = false,
+    type = silent ? ADMIN_CUSTOM_SILENT_TYPE : ADMIN_CUSTOM_MESSAGE_TYPE,
+  } = args
+
+  const definition = getNotificationType(type)
+  if (!definition) {
+    throw new Error(`[internal] sendCustomPush: notification type "${type}" is not registered`)
+  }
+  if ((definition.silent === true) !== silent) {
+    throw new Error(`[internal] sendCustomPush: type "${type}" silent=${definition.silent === true} does not match requested silent=${silent}`)
+  }
+
+  const em = resolve('em') as EntityManager
+
+  return fanOutPushDeliveries({
+    em,
+    resolve,
+    scope: { tenantId, organizationId },
+    userId,
+    userDeviceId: deviceId,
+    notificationId: null,
+    notificationTypeId: type,
+    payload: {
+      title,
+      body,
+      data: { ...(data ?? {}), type },
+      options: pushOptions,
+      silent,
+    },
+  })
+}
+
+export interface PushNotificationService {
+  sendCustomPush(args: SendCustomPushArgs): Promise<{ enqueued: number }>
+}
+
+export const pushNotificationService: PushNotificationService = { sendCustomPush }

package/src/modules/push_notifications/migrations/.snapshot-open-mercato.json

@@ -0,0 +1,386 @@
+{
+  "name": "public",
+  "namespaces": [
+    "public"
+  ],
+  "tables": [
+    {
+      "name": "push_notification_deliveries",
+      "schema": "public",
+      "columns": {
+        "attempts": {
+          "name": "attempts",
+          "type": "int",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "0",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "integer"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": true,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "gen_random_uuid()",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "last_error": {
+          "name": "last_error",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
+        "notification_id": {
+          "name": "notification_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "notification_type_id": {
+          "name": "notification_type_id",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
+        "organization_id": {
+          "name": "organization_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "payload": {
+          "name": "payload",
+          "type": "jsonb",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "json"
+        },
+        "provider": {
+          "name": "provider",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
+        "provider_response": {
+          "name": "provider_response",
+          "type": "jsonb",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "json"
+        },
+        "sent_at": {
+          "name": "sent_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "next_retry_at": {
+          "name": "next_retry_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": true,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "silent": {
+          "name": "silent",
+          "type": "boolean",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "false",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "boolean"
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "'pending'",
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
+        "tenant_id": {
+          "name": "tenant_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "token_snapshot": {
+          "name": "token_snapshot",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamptz(6)",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": 6,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "datetime"
+        },
+        "user_device_id": {
+          "name": "user_device_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "uuid",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": null,
+          "comment": null,
+          "collation": null,
+          "enumItems": [],
+          "mappedType": "uuid"
+        }
+      },
+      "indexes": [
+        {
+          "columnNames": [
+            "notification_id"
+          ],
+          "composite": false,
+          "constraint": false,
+          "keyName": "push_notification_deliveries_notification_idx",
+          "primary": false,
+          "unique": false
+        },
+        {
+          "columnNames": [],
+          "composite": false,
+          "constraint": false,
+          "keyName": "push_notification_deliveries_notif_device_unique",
+          "primary": false,
+          "unique": false,
+          "expression": "create unique index \"push_notification_deliveries_notif_device_unique\" on \"push_notification_deliveries\" (\"notification_id\", \"user_device_id\") where \"notification_id\" is not null"
+        },
+        {
+          "columnNames": [
+            "id"
+          ],
+          "composite": false,
+          "constraint": true,
+          "keyName": "push_notification_deliveries_pkey",
+          "primary": true,
+          "unique": true
+        },
+        {
+          "columnNames": [
+            "tenant_id",
+            "status",
+            "created_at"
+          ],
+          "composite": true,
+          "constraint": false,
+          "keyName": "push_notification_deliveries_tenant_status_idx",
+          "primary": false,
+          "unique": false
+        }
+      ],
+      "checks": [],
+      "triggers": [],
+      "foreignKeys": {},
+      "comment": null
+    }
+  ],
+  "views": [],
+  "nativeEnums": {}
+}

package/src/modules/push_notifications/migrations/Migration20260625150049_push_notifications.ts

@@ -0,0 +1,16 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260625150049_push_notifications extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "push_notification_deliveries" ("id" uuid not null default gen_random_uuid(), "tenant_id" uuid not null, "organization_id" uuid null, "notification_id" uuid null, "notification_type_id" text not null, "user_device_id" uuid not null, "user_id" uuid not null, "provider" text not null, "token_snapshot" text not null, "status" text not null default 'pending', "attempts" int not null default 0, "last_error" text null, "payload" jsonb not null, "provider_response" jsonb null, "created_at" timestamptz not null, "sent_at" timestamptz null, "next_retry_at" timestamptz null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "push_notification_deliveries_notification_idx" on "push_notification_deliveries" ("notification_id");`);
+    this.addSql(`create index "push_notification_deliveries_tenant_status_idx" on "push_notification_deliveries" ("tenant_id", "status", "created_at");`);
+    this.addSql(`create unique index "push_notification_deliveries_notif_device_unique" on "push_notification_deliveries" ("notification_id", "user_device_id") where "notification_id" is not null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "push_notification_deliveries" cascade;`);
+  }
+
+}

package/src/modules/push_notifications/migrations/Migration20260626120000_push_notifications_silent.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260626120000_push_notifications_silent extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "push_notification_deliveries" add column "silent" boolean not null default false;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "push_notification_deliveries" drop column "silent";`);
+  }
+
+}