@pilotiq/pilotiq 0.24.1 → 0.24.3

package/src/notifications/dispatchNotificationAction.test.ts

@@ -1,341 +0,0 @@
-/**
- * Tests for the notification-action dispatcher. Exercises the auth /
- * lookup chain end-to-end against a fake orm adapter — the route
- * layer that mounts this is exercised separately via integration
- * tests against the rudder router.
- */
-import { describe, it, beforeEach, afterEach } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { Pilotiq } from '../Pilotiq.js'
-import { Notification } from './Notification.js'
-import { Action } from '../actions/Action.js'
-import { _setTestAdapter, persist } from './database.js'
-import { dispatchNotificationAction } from './dispatchNotificationAction.js'
-
-// ─── Fake ORM adapter (mirror of database.test.ts) ─────────
-
-interface Row { [k: string]: unknown }
-interface FakeStore { rows: Row[] }
-
-function makeFakeAdapter() {
-  const store: FakeStore = { rows: [] }
-  const buildQB = (_table: string) => {
-    const filters: Array<(r: Row) => boolean> = []
-    let order: { column: string; dir: 'ASC' | 'DESC' } | null = null
-    const apply = () => {
-      let out = store.rows.slice()
-      for (const f of filters) out = out.filter(f)
-      if (order) {
-        const { column, dir } = order
-        out.sort((a, b) => {
-          const av = (a[column] ?? '') as string
-          const bv = (b[column] ?? '') as string
-          const cmp = av < bv ? -1 : av > bv ? 1 : 0
-          return dir === 'DESC' ? -cmp : cmp
-        })
-      }
-      return out
-    }
-    const qb: any = {
-      where: (col: string, value: unknown) => {
-        filters.push(r => r[col] === value)
-        return qb
-      },
-      orderBy: (col: string, dir: 'ASC' | 'DESC' = 'ASC') => {
-        order = { column: col, dir }
-        return qb
-      },
-      paginate: async (_p: number, perPage = 25) => {
-        const out = apply()
-        return { data: out.slice(0, perPage), total: out.length }
-      },
-      count:     async () => apply().length,
-      updateAll: async (data: Row) => {
-        const matching = apply()
-        for (const r of matching) for (const k of Object.keys(data)) r[k] = data[k]
-        return matching.length
-      },
-      create: async (data: Row) => {
-        store.rows.push({ ...data })
-        return { ...data }
-      },
-    }
-    return qb
-  }
-  return { adapter: { query: <T>(t: string) => buildQB(t) }, store }
-}
-
-let fake = makeFakeAdapter()
-
-beforeEach(() => {
-  fake = makeFakeAdapter()
-  _setTestAdapter(fake.adapter)
-})
-
-afterEach(() => {
-  _setTestAdapter(undefined)
-})
-
-async function seedRowWithActions(opts: {
-  notifiableId: string
-  actions:      Action[]
-}): Promise<string> {
-  const n = Notification.make('Test').actions(opts.actions)
-  const data = n.toDatabase() as Parameters<typeof persist>[0]['data']
-  const { id } = await persist({
-    notifiableType: 'users',
-    notifiableId:   opts.notifiableId,
-    data,
-  })
-  return id
-}
-
-describe('dispatchNotificationAction — auth / lookup chain', () => {
-  it('401 when no user resolves', async () => {
-    const result = await dispatchNotificationAction(Pilotiq.make('admin'), {
-      notificationId: 'whatever',
-      actionName:     'view',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           null,
-    })
-    assert.equal(result.ok, false)
-    assert.equal(result.ok === false && result.status, 401)
-  })
-
-  it('404 when notification id does not exist', async () => {
-    const result = await dispatchNotificationAction(Pilotiq.make('admin'), {
-      notificationId: 'no-such-row',
-      actionName:     'view',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, false)
-    assert.equal(result.ok === false && result.status, 404)
-  })
-
-  it('404 when the action name is not on the row', async () => {
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('view').url('/p/123')],
-    })
-    const result = await dispatchNotificationAction(Pilotiq.make('admin'), {
-      notificationId: id,
-      actionName:     'nope',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, false)
-    assert.equal(result.ok === false && result.status, 404)
-  })
-
-  it('404 when the matched action is not handler-mode', async () => {
-    // url-mode actions don't dispatch through this route — clients
-    // navigate the href directly. A request hitting the dispatch
-    // endpoint for a url-mode action is malformed; 404 closes the door.
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('view').url('/p/123')],
-    })
-    const result = await dispatchNotificationAction(Pilotiq.make('admin'), {
-      notificationId: id,
-      actionName:     'view',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, false)
-    assert.equal(result.ok === false && result.status, 404)
-  })
-
-  it('404 when the registry has no handler for the stored name', async () => {
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('archive').handler('archive-project').payload({ projectId: 1 })],
-    })
-    const panel = Pilotiq.make('admin')  // no notificationHandlers registered
-    const result = await dispatchNotificationAction(panel, {
-      notificationId: id,
-      actionName:     'archive',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, false)
-    assert.equal(result.ok === false && result.status, 404)
-  })
-})
-
-describe('dispatchNotificationAction — handler dispatch', () => {
-  it('runs the registered handler with the stored payload', async () => {
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('archive').handler('archive-project').payload({ projectId: 42 })],
-    })
-    let seen: unknown = null
-    const panel = Pilotiq.make('admin').notificationHandlers({
-      'archive-project': async (ctx) => {
-        seen = { user: ctx.user, payload: ctx.payload, notificationId: ctx.notificationId }
-        return { notify: { id: 'x', type: 'success', title: 'Archived' } }
-      },
-    })
-    const result = await dispatchNotificationAction(panel, {
-      notificationId: id,
-      actionName:     'archive',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, true)
-    assert.deepEqual(seen, {
-      user:           { id: 1 },
-      payload:        { projectId: 42 },
-      notificationId: id,
-    })
-    assert.equal(result.ok === true && result.notifications?.[0]?.title, 'Archived')
-  })
-
-  it('flips read_at when the stored action carries markAsRead', async () => {
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('archive').handler('archive-project').markAsRead()],
-    })
-    const panel = Pilotiq.make('admin').notificationHandlers({
-      'archive-project': async () => undefined,
-    })
-    // Pre-condition: row is unread.
-    assert.equal(fake.store.rows[0]?.['read_at'], null)
-
-    const result = await dispatchNotificationAction(panel, {
-      notificationId: id,
-      actionName:     'archive',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, true)
-    assert.equal(result.ok === true && result.markedAsRead, true)
-    // Row was actually flipped — defensive in depth.
-    assert.notEqual(fake.store.rows[0]?.['read_at'], null)
-  })
-
-  it('does not flip read_at when the stored action lacks markAsRead', async () => {
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('archive').handler('archive-project')],
-    })
-    const panel = Pilotiq.make('admin').notificationHandlers({
-      'archive-project': async () => undefined,
-    })
-    const result = await dispatchNotificationAction(panel, {
-      notificationId: id,
-      actionName:     'archive',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, true)
-    assert.equal(result.ok === true && result.markedAsRead, undefined)
-    assert.equal(fake.store.rows[0]?.['read_at'], null)
-  })
-
-  it('forwards a redirect from the handler', async () => {
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('go').handler('go')],
-    })
-    const panel = Pilotiq.make('admin').notificationHandlers({
-      go: async () => ({ redirect: '/somewhere' }),
-    })
-    const result = await dispatchNotificationAction(panel, {
-      notificationId: id,
-      actionName:     'go',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok === true && result.redirect, '/somewhere')
-  })
-
-  it('500 when the handler throws', async () => {
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('boom').handler('boom')],
-    })
-    const panel = Pilotiq.make('admin').notificationHandlers({
-      boom: async () => { throw new Error('bang') },
-    })
-    const result = await dispatchNotificationAction(panel, {
-      notificationId: id,
-      actionName:     'boom',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.equal(result.ok, false)
-    assert.equal(result.ok === false && result.status, 500)
-    assert.match(result.ok === false ? result.error : '', /bang/)
-  })
-
-  it('rejects payload-injection — payload reads from the stored row only', async () => {
-    // The route doesn't accept a request body in v1. The dispatcher
-    // takes payload exclusively from `action.payload` on the stored row,
-    // so even a tampered Pilotiq config can't sneak extra keys in.
-    const id = await seedRowWithActions({
-      notifiableId: '1',
-      actions: [Action.make('check').handler('check').payload({ a: 1 })],
-    })
-    let received: Record<string, unknown> = {}
-    const panel = Pilotiq.make('admin').notificationHandlers({
-      check: async (ctx) => { received = ctx.payload; return undefined },
-    })
-    await dispatchNotificationAction(panel, {
-      notificationId: id,
-      actionName:     'check',
-      notifiableType: 'users',
-      notifiableId:   '1',
-      user:           { id: 1 },
-    })
-    assert.deepEqual(received, { a: 1 })
-  })
-})
-
-describe('Pilotiq.notificationHandlers registry', () => {
-  it('rejects URL-unsafe handler names at registration', () => {
-    assert.throws(
-      () => Pilotiq.make('admin').notificationHandlers({ 'bad name with spaces': async () => undefined }),
-      /URL-safe key/,
-    )
-    assert.throws(
-      () => Pilotiq.make('admin').notificationHandlers({ '': async () => undefined }),
-      /URL-safe key/,
-    )
-    assert.throws(
-      () => Pilotiq.make('admin').notificationHandlers({ 'with/slash': async () => undefined }),
-      /URL-safe key/,
-    )
-  })
-
-  it('accepts alphanumeric + dash + underscore', () => {
-    Pilotiq.make('admin').notificationHandlers({
-      'archive-project': async () => undefined,
-      'mark_done':       async () => undefined,
-      'X1':              async () => undefined,
-    })
-  })
-
-  it('subsequent calls merge — later keys override earlier', () => {
-    let which: string = ''
-    const panel = Pilotiq.make('admin')
-      .notificationHandlers({ 'a': async () => { which = 'first';  return undefined } })
-      .notificationHandlers({ 'a': async () => { which = 'second'; return undefined } })
-    const fn = panel.getNotificationHandler('a')
-    assert.ok(fn)
-    void fn!({ user: null, payload: {}, notificationId: 'x' })
-    // synchronous resolution since the handler closures don't await anything
-    assert.equal(which, 'second')
-  })
-})

package/src/notifications/dispatchNotificationAction.ts

@@ -1,142 +0,0 @@
-/**
- * Server-side dispatcher for `Notification.actions([Action…])` slots
- * that target a registered handler by name. Mounted by `routes.ts` at
- * `POST {base}/_notifications/:id/_action/:actionName`.
- *
- * Auth/lookup chain (each step returns the next-status code on miss):
- *   401  → no resolved user
- *   404  → row doesn't exist OR `notifiable_id !== user.id`
- *   404  → stored row's `data.actions` doesn't contain `actionName`
- *   404  → stored action's `handler` field isn't a string (closures
- *          should already be filtered at `sendToDatabase` — defend in
- *          depth)
- *   404  → no registry entry under that handler name
- *   200  → handler ran cleanly; result echoes back as
- *          `{ ok, redirect?, notifications?, download? }`
- *   500  → handler threw — caught and wrapped
- *
- * The handler reads `payload` exclusively from the stored row, never
- * from the request body, so a tampered client can't inject extra
- * payload keys.
- */
-
-import type { Pilotiq } from '../Pilotiq.js'
-import type {
-  NotificationActionContext,
-  NotificationActionResult,
-} from './types.js'
-import type { NotificationMeta } from './Notification.js'
-import { findOneForUser, markAsRead } from './database.js'
-
-export interface DispatchNotificationActionInput {
-  notificationId: string
-  actionName:     string
-  notifiableType: string
-  notifiableId:   string
-  user:           unknown
-  request?:       unknown
-}
-
-export interface DispatchNotificationActionSuccess {
-  ok:             true
-  redirect?:      string
-  notifications?: NotificationMeta[]
-  /** When the matched action carried `markAsRead: true`, the route
-   *  flipped `read_at` server-side. Mirrored back so the bell client
-   *  can update its optimistic state without an extra round-trip. */
-  markedAsRead?:  boolean
-}
-
-export interface DispatchNotificationActionFailure {
-  ok:     false
-  status: 401 | 404 | 500
-  error:  string
-}
-
-export type DispatchNotificationActionResult =
-  | DispatchNotificationActionSuccess
-  | DispatchNotificationActionFailure
-
-export async function dispatchNotificationAction(
-  pilotiq: Pilotiq,
-  input:   DispatchNotificationActionInput,
-): Promise<DispatchNotificationActionResult> {
-  if (input.user === null || input.user === undefined) {
-    return { ok: false, status: 401, error: 'Not authenticated' }
-  }
-
-  const row = await findOneForUser(input.notificationId, {
-    notifiableType: input.notifiableType,
-    notifiableId:   input.notifiableId,
-  })
-  if (!row) return { ok: false, status: 404, error: 'Notification not found' }
-
-  const action = row.actions?.find(a => a.name === input.actionName)
-  if (!action) return { ok: false, status: 404, error: 'Action not found on notification' }
-
-  // Closures don't survive serialization — if a stored action carries
-  // anything other than a string handler, treat it as a tampered row
-  // (or one written by an older code path) and refuse to dispatch.
-  if (typeof action.handler !== 'string') {
-    return {
-      ok:     false,
-      status: 404,
-      error:  'Action does not target a registered handler (use Pilotiq.notificationHandlers).',
-    }
-  }
-
-  const handler = pilotiq.getNotificationHandler(action.handler)
-  if (!handler) {
-    return {
-      ok:     false,
-      status: 404,
-      error:  `No notification handler registered for "${action.handler}".`,
-    }
-  }
-
-  const ctx: NotificationActionContext = {
-    user:           input.user,
-    payload:        action.payload ?? {},
-    notificationId: input.notificationId,
-  }
-  if (input.request !== undefined) ctx.request = input.request
-
-  let result: NotificationActionResult | undefined
-  try {
-    result = await handler(ctx)
-  } catch (e) {
-    return {
-      ok:     false,
-      status: 500,
-      error:  e instanceof Error ? e.message : 'Notification handler threw',
-    }
-  }
-
-  // Side-effect: flip `read_at` when the stored action opted in.
-  // Server-side authoritative — handler dispatch is one round-trip,
-  // not two, and tampered clients can't suppress the mark.
-  let markedAsRead = false
-  if (action.markAsRead) {
-    markedAsRead = await markAsRead(input.notificationId, {
-      notifiableType: input.notifiableType,
-      notifiableId:   input.notifiableId,
-    })
-  }
-
-  const success: DispatchNotificationActionSuccess = { ok: true }
-  if (result && typeof result === 'object') {
-    if (typeof result.redirect === 'string') success.redirect = result.redirect
-    if (result.notify !== undefined) {
-      const notifs = Array.isArray(result.notify) ? result.notify : [result.notify]
-      const valid  = notifs.filter(
-        (n): n is NotificationMeta => Boolean(n) && typeof n === 'object' && typeof (n as NotificationMeta).title === 'string',
-      )
-      if (valid.length > 0) success.notifications = valid
-    }
-    // download envelope (parallel to dispatchAction) — wired through
-    // the route layer when present; v1 doesn't surface it here to keep
-    // the wire shape narrow. Add when a consumer asks.
-  }
-  if (markedAsRead) success.markedAsRead = true
-  return success
-}

package/src/notifications/flash.test.ts

@@ -1,89 +0,0 @@
-import { describe, it } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { flashNotifications, consumeFlashedNotifications } from './flash.js'
-import type { NotificationMeta } from './Notification.js'
-
-/**
- * Minimal SessionInstance stand-in: just a key/value flash store with the
- * "current request reads previous request's stash" semantics. Mirrors the
- * `flash / getFlash` shape from `@rudderjs/session` without importing it
- * (pilotiq doesn't peer-depend on session — it's optional in the host).
- */
-function makeSession() {
-  let prev: Record<string, unknown> = {}
-  let next: Record<string, unknown> = {}
-  return {
-    flash(key: string, value: unknown) { next[key] = value },
-    getFlash<T>(key: string, fallback?: T): T | undefined {
-      return (key in prev ? prev[key] : fallback) as T | undefined
-    },
-    /** Test helper: simulate the redirect happening — current next becomes
-     *  next request's prev. */
-    advance() { prev = next; next = {} },
-  }
-}
-
-const meta = (title: string): NotificationMeta => ({
-  id:    `n-${title}`,
-  type:  'success',
-  title,
-})
-
-describe('flashNotifications / consumeFlashedNotifications', () => {
-  it('roundtrip: flash on one request, consume on the next', () => {
-    const session = makeSession()
-    const req = { session }
-    flashNotifications(req, [meta('Saved')])
-    session.advance()
-    const got = consumeFlashedNotifications(req)
-    assert.equal(got.length, 1)
-    assert.equal(got[0]!.title, 'Saved')
-  })
-
-  it('empty array no-ops (does not stash an empty key that overwrites a prior flash)', () => {
-    const session = makeSession()
-    const req = { session }
-    flashNotifications(req, [meta('Saved')])
-    flashNotifications(req, [])           // should not clobber
-    session.advance()
-    const got = consumeFlashedNotifications(req)
-    assert.equal(got.length, 1)
-    assert.equal(got[0]!.title, 'Saved')
-  })
-
-  it('undefined notifications no-op', () => {
-    const session = makeSession()
-    const req = { session }
-    flashNotifications(req, undefined)
-    session.advance()
-    assert.deepEqual(consumeFlashedNotifications(req), [])
-  })
-
-  it('missing session: writes are silently dropped, reads return []', () => {
-    const req = {}                         // no session at all
-    assert.doesNotThrow(() => flashNotifications(req, [meta('Saved')]))
-    assert.deepEqual(consumeFlashedNotifications(req), [])
-  })
-
-  it('undefined req: both helpers no-op', () => {
-    assert.doesNotThrow(() => flashNotifications(undefined, [meta('Saved')]))
-    assert.deepEqual(consumeFlashedNotifications(undefined), [])
-  })
-
-  it('multiple notifications survive the roundtrip in order', () => {
-    const session = makeSession()
-    const req = { session }
-    flashNotifications(req, [meta('first'), meta('second'), meta('third')])
-    session.advance()
-    const got = consumeFlashedNotifications(req)
-    assert.deepEqual(got.map(n => n.title), ['first', 'second', 'third'])
-  })
-
-  it('consume after no flash returns []', () => {
-    const session = makeSession()
-    const req = { session }
-    session.advance()
-    assert.deepEqual(consumeFlashedNotifications(req), [])
-  })
-})

package/src/notifications/flash.ts

@@ -1,71 +0,0 @@
-/**
- * Bridge between the form/action lifecycle (which produces
- * `NotificationMeta[]` on success) and the next request's render (which
- * needs them in `viewProps.notifications` so the `Toaster` can fire).
- *
- * Sits on top of `@rudderjs/session`'s built-in flash primitive — see
- * `SessionInstance.flash / getFlash`. We don't ship our own storage; we
- * only namespace the key (`pilotiq:notifications`) and shape the value.
- *
- * If the host app hasn't installed `@rudderjs/session`, `req.session` is
- * undefined; both helpers no-op silently rather than throwing — losing
- * notifications on the 303 path is the same status quo as before flash
- * landed, so an opt-out is the correct fallback.
- */
-import type { NotificationMeta } from './Notification.js'
-
-const FLASH_KEY = 'pilotiq:notifications'
-
-interface FlashCapableSession {
-  flash(key: string, value: unknown): void
-  getFlash<T>(key: string, fallback?: T): T | undefined
-}
-
-/**
- * Pull a `FlashCapableSession` off any request-like object. `AppRequest`
- * doesn't declare `session` in `@rudderjs/contracts` directly — the field
- * is added via module augmentation in `@rudderjs/session`, which pilotiq
- * doesn't peer-depend on (sessions are optional in the host). We duck-type
- * at runtime so the helpers compile against unaugmented `AppRequest` and
- * still find a real `SessionInstance` when one's mounted.
- */
-function getSession(req: unknown): FlashCapableSession | undefined {
-  if (!req || typeof req !== 'object') return undefined
-  const session = (req as { session?: unknown }).session
-  if (!session || typeof session !== 'object') return undefined
-  const s = session as Record<string, unknown>
-  if (typeof s['flash'] !== 'function' || typeof s['getFlash'] !== 'function') return undefined
-  return session as FlashCapableSession
-}
-
-/**
- * Stash notifications on the session for the next request to consume.
- * Called from POST handlers right before `res.redirect(..., 303)`.
- *
- * Invariant: call at most once per response. The underlying
- * `session.flash(key, value)` overwrites any previously flashed value
- * under the same key, so coalescing across multiple calls would silently
- * lose the earlier batch.
- *
- * No-ops silently when the host app hasn't installed `@rudderjs/session`.
- */
-export function flashNotifications(
-  req:           unknown,
-  notifications: ReadonlyArray<NotificationMeta> | undefined,
-): void {
-  if (!notifications || notifications.length === 0) return
-  const session = getSession(req)
-  if (!session) return
-  session.flash(FLASH_KEY, [...notifications])
-}
-
-/**
- * Read & clear the flashed notifications (consume-once semantics — the
- * session driver clears the previous-request flash slot on save). Returns
- * an empty array when there's nothing flashed or no session is installed.
- */
-export function consumeFlashedNotifications(req: unknown): NotificationMeta[] {
-  const session = getSession(req)
-  if (!session) return []
-  return session.getFlash<NotificationMeta[]>(FLASH_KEY) ?? []
-}

package/src/notifications/index.ts

@@ -1,45 +0,0 @@
-export {
-  Notification,
-  type NotificationType,
-  type NotificationMeta,
-  _resetNotificationIdSeq,
-} from './Notification.js'
-
-export {
-  resolveSavedNotification,
-  type SavedNotificationMode,
-} from './resolveSavedNotification.js'
-
-export {
-  flashNotifications,
-  consumeFlashedNotifications,
-} from './flash.js'
-
-export type { Notifiable } from './types.js'
-
-export {
-  listForUser,
-  unreadCount,
-  findOneForUser as findDatabaseNotificationForUser,
-  markAsRead,
-  markAsUnread,
-  markAllAsRead,
-  persist as persistDatabaseNotification,
-  type DatabaseNotificationMeta,
-  type ListOptions    as DatabaseNotificationListOptions,
-  type ListResult     as DatabaseNotificationListResult,
-} from './database.js'
-
-export type {
-  NotificationActionMeta,
-  NotificationActionHandler,
-  NotificationActionContext,
-  NotificationActionResult,
-} from './types.js'
-
-export {
-  push as pushBroadcastNotification,
-  notificationChannel,
-  NOTIFICATION_CREATED_EVENT,
-  type PushOptions as PushBroadcastOptions,
-} from './broadcast.js'