@pilotiq/pilotiq 0.1.0

package/src/notifications/database.ts

@@ -0,0 +1,398 @@
+/**
+ * Database-backed notifications — server-side store helpers.
+ *
+ * Pilotiq doesn't ship a Prisma model; we read/write the
+ * `notification` table that `@rudderjs/notification`'s
+ * `NotificationProvider` publishes (`prisma/schema/notification.prisma`).
+ * Apps that want bell-icon notifications add `NotificationProvider` to
+ * their providers list and run `prisma generate`/`db push`; pilotiq
+ * then queries the same table via `@rudderjs/orm`'s `ModelRegistry`
+ * adapter so the wire shape matches what
+ * `Notifier.send(user, new MyNotification())` already writes.
+ *
+ * `@rudderjs/orm` is a runtime soft-import — pilotiq has no hard
+ * dependency on it. When the host app hasn't installed orm (or no
+ * adapter is registered), every helper resolves to a clean
+ * "store unavailable" sentinel rather than throwing.
+ */
+
+import type { NotificationMeta, NotificationType } from './Notification.js'
+import type { NotificationActionMeta } from './types.js'
+
+/** Wire shape returned by the list endpoint to the bell client. */
+export interface DatabaseNotificationMeta {
+  /** Stable PK from the `notification.id` column. */
+  id:        string
+  /** Unix-ms timestamp the row was created. */
+  createdAt: number
+  /** ISO `read_at` timestamp; absent when unread. */
+  readAt?:   string
+  /** Display title — read from the `data` JSON `title` key. */
+  title:     string
+  /** Optional supporting text. */
+  body?:     string
+  /** Optional UI tint. Mirrors the transient toast types so the bell can
+   *  share badge styling with the toaster. */
+  type?:     NotificationType
+  /** Optional icon (registry name). */
+  icon?:     string
+  /** Optional click-through URL. When set, clicking the row navigates
+   *  there + marks the notification as read. */
+  url?:      string
+  /** Optional action strip rendered below the body. Round-trips
+   *  verbatim through the `data.actions` JSON column (`Notification`
+   *  emits the slim wire shape; `rowToMeta` validates each entry and
+   *  drops malformed ones with a `console.warn` rather than failing
+   *  the dropdown). */
+  actions?:  NotificationActionMeta[]
+}
+
+/** Raw row shape on the `notification` table — matches the schema
+ *  shipped by `@rudderjs/notification`. The `data` column is a
+ *  JSON-encoded string blob. */
+interface NotificationRow {
+  id:              string
+  notifiable_id:   string
+  notifiable_type: string
+  type:            string
+  data:            string | Record<string, unknown>
+  read_at:         string | null
+  created_at:      string
+  updated_at:      string
+}
+
+/** Minimal query surface we use against the orm adapter. */
+interface QB {
+  where(column: string, value: unknown): QB
+  where(column: string, op: string, value: unknown): QB
+  orderBy(column: string, dir?: 'ASC' | 'DESC'): QB
+  paginate(page: number, perPage?: number): Promise<{ data: unknown[]; total: number }>
+  get?(): Promise<unknown[]>
+  count?(): Promise<number>
+  update?(data: Record<string, unknown>): Promise<unknown>
+  updateAll?(data: Record<string, unknown>): Promise<number>
+  create?(data: Record<string, unknown>): Promise<unknown>
+}
+
+/** Test-injected adapter override; `null` falls back to dynamic import. */
+let _testAdapter: { query: <T>(table: string) => QB } | null | 'unset' = 'unset'
+
+/** Soft-resolved orm adapter. `null` when no orm adapter is registered.
+ *
+ *  Prefers the rudder service container (`app().make('db')`) — the
+ *  orm-prisma / orm-drizzle providers register the adapter as a
+ *  globalThis-rooted singleton there, so this resolution path survives
+ *  the Vite SSR module-cache duplication that breaks shared singletons
+ *  in raw ES module land. Falls back to `ModelRegistry.get()` for
+ *  setups that wired the adapter directly.
+ *
+ *  Both modules are imported indirectly so TypeScript doesn't try to
+ *  resolve them at type-check time — pilotiq doesn't peer-depend on
+ *  `@rudderjs/orm` or `@rudderjs/core` (the bell-icon is opt-in).
+ */
+async function adapter(): Promise<{ query: <T>(table: string) => QB } | null> {
+  if (_testAdapter !== 'unset') return _testAdapter
+  const fromContainer = await resolveFromContainer()
+  if (fromContainer) return fromContainer
+  return resolveFromOrmModule()
+}
+
+async function resolveFromContainer(): Promise<{ query: <T>(table: string) => QB } | null> {
+  const moduleName = '@rudderjs/core'
+  try {
+    const mod = await import(/* @vite-ignore */ moduleName) as {
+      app?: () => { make(key: string): unknown }
+    }
+    if (!mod.app) return null
+    const adapter = mod.app().make('db')
+    if (!adapter || typeof adapter !== 'object') return null
+    if (typeof (adapter as { query?: unknown }).query !== 'function') return null
+    return adapter as { query: <T>(table: string) => QB }
+  } catch {
+    return null
+  }
+}
+
+async function resolveFromOrmModule(): Promise<{ query: <T>(table: string) => QB } | null> {
+  const moduleName = '@rudderjs/orm'
+  try {
+    const mod = await import(/* @vite-ignore */ moduleName) as {
+      ModelRegistry?: { get(): { query: <T>(table: string) => QB } | null }
+    }
+    return mod.ModelRegistry?.get() ?? null
+  } catch {
+    return null
+  }
+}
+
+/** Notification-table row JSON-decoded `data` payload. We always store
+ *  pilotiq's `NotificationMeta` shape; rows written by
+ *  `@rudderjs/notification.Notifier.send(...)` may carry arbitrary
+ *  application keys — we surface what we can recognize and ignore the rest. */
+function parseRowData(raw: string | Record<string, unknown>): Record<string, unknown> {
+  if (typeof raw !== 'string') return raw
+  try { return JSON.parse(raw) as Record<string, unknown> }
+  catch { return {} }
+}
+
+function rowToMeta(row: NotificationRow): DatabaseNotificationMeta {
+  const data = parseRowData(row.data)
+  const meta: DatabaseNotificationMeta = {
+    id:        row.id,
+    createdAt: Date.parse(row.created_at) || Date.now(),
+    title:     typeof data['title'] === 'string' ? (data['title'] as string) : '',
+  }
+  if (row.read_at) meta.readAt = row.read_at
+  if (typeof data['body'] === 'string') meta.body = data['body'] as string
+  if (typeof data['icon'] === 'string') meta.icon = data['icon'] as string
+  if (typeof data['url']  === 'string') meta.url  = data['url']  as string
+  if (
+    data['type'] === 'info' || data['type'] === 'success' ||
+    data['type'] === 'warning' || data['type'] === 'error'
+  ) {
+    meta.type = data['type']
+  }
+  const actions = parseStoredActions(data['actions'])
+  if (actions.length > 0) meta.actions = actions
+  return meta
+}
+
+/**
+ * Validate the stored action array shape — the `data.actions` column
+ * is end-user controllable through the `Notification` builder, so we
+ * defend in depth: malformed entries are dropped with a warning rather
+ * than crashing the bell dropdown render.
+ *
+ * Required: `name: string`, `label: string`, exactly one of `url` /
+ * `post` / `handler` set to a string.
+ */
+function parseStoredActions(raw: unknown): NotificationActionMeta[] {
+  if (!Array.isArray(raw)) return []
+  const out: NotificationActionMeta[] = []
+  for (const entry of raw) {
+    if (!entry || typeof entry !== 'object') continue
+    const e = entry as Record<string, unknown>
+    if (typeof e['name']  !== 'string' || !e['name'])  { warnDrop(e, 'missing name'); continue }
+    if (typeof e['label'] !== 'string' || !e['label']) { warnDrop(e, 'missing label'); continue }
+    const url     = typeof e['url']     === 'string' ? e['url']     as string : undefined
+    const post    = typeof e['post']    === 'string' ? e['post']    as string : undefined
+    const handler = typeof e['handler'] === 'string' ? e['handler'] as string : undefined
+    const dispatchModes = [url, post, handler].filter(v => v !== undefined).length
+    if (dispatchModes !== 1) { warnDrop(e, 'must set exactly one of url/post/handler'); continue }
+
+    const action: NotificationActionMeta = { name: e['name'] as string, label: e['label'] as string }
+    if (url     !== undefined) action.url     = url
+    if (post    !== undefined) action.post    = post
+    if (handler !== undefined) action.handler = handler
+    if (e['payload'] && typeof e['payload'] === 'object' && !Array.isArray(e['payload'])) {
+      action.payload = e['payload'] as Record<string, unknown>
+    }
+    if (typeof e['color']    === 'string') action.color    = e['color']    as never
+    if (typeof e['icon']     === 'string') action.icon     = e['icon']     as string
+    if (e['outlined']        === true)     action.outlined = true
+    if (typeof e['size']     === 'string') action.size     = e['size']     as never
+    if (e['openUrlInNewTab'] === true)     action.openUrlInNewTab = true
+    if (e['markAsRead']      === true)     action.markAsRead      = true
+    out.push(action)
+  }
+  return out
+}
+
+function warnDrop(entry: Record<string, unknown>, reason: string): void {
+  // Only warn in non-production — keep the bell quiet on prod where
+  // a dropped row is preferable to console spam.
+  if (typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'production') return
+
+  console.warn(
+    `[Pilotiq] notification action dropped: ${reason}. Entry:`,
+    entry,
+  )
+}
+
+export interface ListOptions {
+  /** `notifiable_type` column value. */
+  notifiableType: string
+  /** `notifiable_id` column value (typically the user's id). */
+  notifiableId:   string
+  /** Hard cap on rows returned. Default 25. */
+  limit?:         number
+  /** When true, only rows with `read_at IS NULL` are returned. */
+  unreadOnly?:    boolean
+}
+
+export interface ListResult {
+  notifications: DatabaseNotificationMeta[]
+  unreadCount:   number
+}
+
+/**
+ * Fetch the latest notifications for a notifiable + the unread count.
+ * Returns `{ notifications: [], unreadCount: 0 }` when no orm adapter is
+ * registered — apps without a database stay quiet rather than 500.
+ */
+export async function listForUser(opts: ListOptions): Promise<ListResult> {
+  const adp = await adapter()
+  if (!adp) return { notifications: [], unreadCount: 0 }
+
+  const limit = opts.limit ?? 25
+  let q: QB = adp.query<NotificationRow>('notification')
+    .where('notifiable_type', opts.notifiableType)
+    .where('notifiable_id',   opts.notifiableId)
+  if (opts.unreadOnly) q = q.where('read_at', null)
+  q = q.orderBy('created_at', 'DESC')
+
+  const [page, count] = await Promise.all([
+    q.paginate(1, limit),
+    unreadCount({ notifiableType: opts.notifiableType, notifiableId: opts.notifiableId }),
+  ])
+  const rows = (page.data as NotificationRow[]).map(rowToMeta)
+  return { notifications: rows, unreadCount: count }
+}
+
+/**
+ * Fetch a single row by id, scoped to the notifiable. Returns
+ * `undefined` when no row matches (already-deleted / wrong owner /
+ * store unavailable). Used by the notification action route to look
+ * up the stored `data.actions` array before dispatching.
+ */
+export async function findOneForUser(
+  id: string,
+  opts: { notifiableType: string; notifiableId: string },
+): Promise<DatabaseNotificationMeta | undefined> {
+  const adp = await adapter()
+  if (!adp) return undefined
+  const q = adp.query<NotificationRow>('notification')
+    .where('notifiable_type', opts.notifiableType)
+    .where('notifiable_id',   opts.notifiableId)
+    .where('id',              id)
+  const page = await q.paginate(1, 1)
+  const row = (page.data as NotificationRow[])[0]
+  if (!row) return undefined
+  return rowToMeta(row)
+}
+
+/** Count rows with `read_at IS NULL` for the notifiable. */
+export async function unreadCount(opts: {
+  notifiableType: string
+  notifiableId:   string
+}): Promise<number> {
+  const adp = await adapter()
+  if (!adp) return 0
+  const q = adp.query<NotificationRow>('notification')
+    .where('notifiable_type', opts.notifiableType)
+    .where('notifiable_id',   opts.notifiableId)
+    .where('read_at', null)
+  // Cheap path when the adapter implements `count()`; fall back to
+  // paginate(1,1).total which both Prisma and Drizzle adapters support.
+  if (q.count) return q.count()
+  const page = await q.paginate(1, 1)
+  return page.total
+}
+
+/**
+ * Mark a single notification row as read. Always scoped to
+ * `notifiableId` so a tampered POST can't mark another user's row.
+ *
+ * Returns `true` when a row was updated, `false` when no row matched
+ * (already-deleted / wrong owner / store unavailable).
+ */
+export async function markAsRead(
+  id: string,
+  opts: { notifiableType: string; notifiableId: string },
+): Promise<boolean> {
+  const adp = await adapter()
+  if (!adp) return false
+  const q = adp.query<NotificationRow>('notification')
+    .where('notifiable_type', opts.notifiableType)
+    .where('notifiable_id',   opts.notifiableId)
+    .where('id',              id)
+  if (!q.updateAll) return false
+  const n = await q.updateAll({ read_at: new Date().toISOString() })
+  return n > 0
+}
+
+/** Mark a row unread again — used by the bell's "mark unread" affordance. */
+export async function markAsUnread(
+  id: string,
+  opts: { notifiableType: string; notifiableId: string },
+): Promise<boolean> {
+  const adp = await adapter()
+  if (!adp) return false
+  const q = adp.query<NotificationRow>('notification')
+    .where('notifiable_type', opts.notifiableType)
+    .where('notifiable_id',   opts.notifiableId)
+    .where('id',              id)
+  if (!q.updateAll) return false
+  const n = await q.updateAll({ read_at: null })
+  return n > 0
+}
+
+/** Mark every unread notification for the notifiable as read. */
+export async function markAllAsRead(opts: {
+  notifiableType: string
+  notifiableId:   string
+}): Promise<number> {
+  const adp = await adapter()
+  if (!adp) return 0
+  const q = adp.query<NotificationRow>('notification')
+    .where('notifiable_type', opts.notifiableType)
+    .where('notifiable_id',   opts.notifiableId)
+    .where('read_at', null)
+  if (!q.updateAll) return 0
+  return q.updateAll({ read_at: new Date().toISOString() })
+}
+
+/**
+ * Insert a notification row directly. Powers
+ * `Notification.make(...).sendToDatabase(recipient)`. Throws when the
+ * orm adapter isn't registered — the caller has explicitly asked to
+ * persist, so silent no-op would hide a real config error.
+ */
+export async function persist(opts: {
+  notifiableType: string
+  notifiableId:   string
+  type?:          string
+  data:           NotificationMeta & Record<string, unknown>
+}): Promise<{ id: string }> {
+  const adp = await adapter()
+  if (!adp) {
+    throw new Error(
+      '[Pilotiq] sendToDatabase() called but no @rudderjs/orm adapter is registered. ' +
+      'Add a database provider (orm-prisma / orm-drizzle) to your providers list, ' +
+      "or call .sendToDatabase() only when the orm is wired up.",
+    )
+  }
+  const q = adp.query<NotificationRow>('notification')
+  if (!q.create) {
+    throw new Error('[Pilotiq] orm adapter does not support `query.create()`.')
+  }
+  const id = `pn_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
+  const now = new Date().toISOString()
+  await q.create({
+    id,
+    notifiable_id:   opts.notifiableId,
+    notifiable_type: opts.notifiableType,
+    type:            opts.type ?? 'PilotiqNotification',
+    data:            JSON.stringify(opts.data),
+    read_at:         null,
+    created_at:      now,
+    updated_at:      now,
+  })
+  return { id }
+}
+
+/** @internal — test seam. Inject a fake adapter (or `null` to mimic
+ *  "store unavailable"). Pass `undefined` to clear and fall back to the
+ *  dynamic `@rudderjs/orm` import. Tests should clear in `afterEach`. */
+export function _setTestAdapter(
+  adp: { query: <T>(table: string) => QB } | null | undefined,
+): void {
+  _testAdapter = adp === undefined ? 'unset' : adp
+}
+
+/** @internal — exposed for tests; lets a unit test inject a fake
+ *  ModelRegistry without monkey-patching dynamic-import. */
+export const _internal = {
+  parseRowData,
+  rowToMeta,
+}

package/src/notifications/databaseNotifications.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Builder + panelInfo() integration tests for
+ * `Pilotiq.databaseNotifications()`. The transport layer (the
+ * `_notifications` route family) is exercised via the storage tests +
+ * `database.test.ts`; here we lock down the wire shape consumers
+ * actually depend on.
+ */
+import { describe, it } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Pilotiq } from '../Pilotiq.js'
+import { panelInfo } from '../pageData.js'
+
+describe('Pilotiq.databaseNotifications() — builder', () => {
+  it('opt-out by default — cfg.databaseNotifications is undefined', () => {
+    const cfg = Pilotiq.make('admin').getConfig()
+    assert.equal(cfg.databaseNotifications, undefined)
+  })
+
+  it('toggle without options enables with defaults', () => {
+    const cfg = Pilotiq.make('admin').databaseNotifications().getConfig()
+    assert.equal(cfg.databaseNotifications?.enabled, true)
+    assert.equal(cfg.databaseNotifications?.position, undefined)
+    assert.equal(cfg.databaseNotifications?.polling,  undefined)
+  })
+
+  it('options round-trip', () => {
+    const cfg = Pilotiq.make('admin').databaseNotifications({
+      position:   'sidebar',
+      polling:    10,
+      pageSize:   50,
+      badgeColor: 'success',
+      trigger:    { icon: 'bell', label: 'Inbox' },
+    }).getConfig()
+    assert.equal(cfg.databaseNotifications?.position,   'sidebar')
+    assert.equal(cfg.databaseNotifications?.polling,    10)
+    assert.equal(cfg.databaseNotifications?.pageSize,   50)
+    assert.equal(cfg.databaseNotifications?.badgeColor, 'success')
+    assert.equal(cfg.databaseNotifications?.trigger?.icon, 'bell')
+  })
+
+  it('null polling round-trips (disable auto-poll)', () => {
+    const cfg = Pilotiq.make('admin').databaseNotifications({ polling: null }).getConfig()
+    assert.equal(cfg.databaseNotifications?.polling, null)
+  })
+
+  it('databaseNotificationsPolling sugar updates the slot', () => {
+    const cfg = Pilotiq.make('admin')
+      .databaseNotifications()
+      .databaseNotificationsPolling(120)
+      .getConfig()
+    assert.equal(cfg.databaseNotifications?.polling, 120)
+  })
+
+  it('databaseNotificationsPolling is a no-op when not enabled', () => {
+    const cfg = Pilotiq.make('admin').databaseNotificationsPolling(5).getConfig()
+    assert.equal(cfg.databaseNotifications, undefined)
+  })
+
+  it('databaseNotificationsPosition sugar updates the slot', () => {
+    const cfg = Pilotiq.make('admin')
+      .databaseNotifications()
+      .databaseNotificationsPosition('sidebar')
+      .getConfig()
+    assert.equal(cfg.databaseNotifications?.position, 'sidebar')
+  })
+})
+
+describe('panelInfo() — databaseNotifications meta', () => {
+  it('absent when never opted in', async () => {
+    const panel = await panelInfo(Pilotiq.make('admin'))
+    assert.equal((panel as Record<string, unknown>)['databaseNotifications'], undefined)
+  })
+
+  it('absent when no user resolves', async () => {
+    const p = Pilotiq.make('admin').databaseNotifications()
+    const panel = await panelInfo(p)
+    assert.equal((panel as Record<string, unknown>)['databaseNotifications'], undefined)
+  })
+
+  it('present with resolver + defaults', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ id: 1, name: 'Sue' }))
+      .databaseNotifications()
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.ok(dn, 'databaseNotifications is present')
+    assert.equal(dn.position,   'topbar')
+    assert.equal(dn.polling,    30)
+    assert.equal(dn.pageSize,   25)
+    assert.equal(dn.badgeColor, 'primary')
+    assert.equal(dn.listUrl,    '/admin/_notifications')
+    assert.equal(dn.readAllUrl, '/admin/_notifications/read-all')
+    assert.equal(dn.readUrl,    '/admin/_notifications/:id/read')
+    assert.equal(dn.unreadUrl,  '/admin/_notifications/:id/unread')
+    assert.equal(dn.actionUrl,  '/admin/_notifications/:id/_action/:actionName')
+  })
+
+  it('honors custom path for URL building', async () => {
+    const p = Pilotiq.make('admin')
+      .path('/dashboard')
+      .user(() => ({ id: 1 }))
+      .databaseNotifications()
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.equal(dn.listUrl, '/dashboard/_notifications')
+  })
+
+  it('null polling round-trips to the wire', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ id: 1 }))
+      .databaseNotifications({ polling: null })
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.equal(dn.polling, null)
+  })
+
+  it('per-call options override defaults', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ id: 1 }))
+      .databaseNotifications({
+        position:   'sidebar',
+        polling:    5,
+        pageSize:   10,
+        badgeColor: 'warning',
+      })
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.equal(dn.position,   'sidebar')
+    assert.equal(dn.polling,    5)
+    assert.equal(dn.pageSize,   10)
+    assert.equal(dn.badgeColor, 'warning')
+  })
+
+  it('trigger overrides ride through to the wire', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ id: 1 }))
+      .databaseNotifications({ trigger: { icon: 'bell', label: 'Inbox' } })
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.deepEqual(dn.trigger, { icon: 'bell', label: 'Inbox' })
+  })
+})
+
+describe('panelInfo() — broadcast (Phase 2)', () => {
+  it('absent when broadcast wasn\'t enabled', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ id: 1 }))
+      .databaseNotifications()
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.equal(dn.broadcast, undefined)
+  })
+
+  it('present when databaseNotificationsBroadcast() is called', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ id: 42 }))
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.ok(dn.broadcast, 'broadcast meta is present')
+    assert.equal(dn.broadcast.channel, 'private-pilotiq-notifications.42')
+    assert.equal(dn.broadcast.event,   'notification.created')
+    assert.equal(dn.broadcast.wsUrl,   '')  // empty -> client falls back to same-origin
+  })
+
+  it('honors a custom wsUrl', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ id: 'u-1' }))
+      .databaseNotifications({ broadcast: { wsUrl: 'wss://x.test/ws' } })
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.equal(dn.broadcast.wsUrl,   'wss://x.test/ws')
+    assert.equal(dn.broadcast.channel, 'private-pilotiq-notifications.u-1')
+  })
+
+  it('absent when user has no id (channel cannot be scoped)', async () => {
+    const p = Pilotiq.make('admin')
+      .user(() => ({ name: 'Anonymous' }) as unknown as { id: string })
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    const panel = await panelInfo(p)
+    const dn = (panel as any).databaseNotifications
+    assert.equal(dn?.broadcast, undefined)
+  })
+})