@pilotiq/pilotiq 0.1.0

package/src/notifications/registerBroadcastAuth.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Boot-time broadcast auth registration — unit tests. Uses the
+ * `_setTestBroadcastAuth` seam to inject a fake `@rudderjs/broadcast`
+ * module so we can capture the (pattern, callback) pair pilotiq registers
+ * and assert the auth callback's gating logic.
+ */
+import { describe, it, afterEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Pilotiq } from '../Pilotiq.js'
+import {
+  registerBroadcastAuth,
+  _setTestBroadcastAuth,
+} from './registerBroadcastAuth.js'
+
+type AuthCallback = (
+  req: { headers: Record<string, string | string[] | undefined>; url: string; token?: string },
+  channel: string,
+) => Promise<boolean | Record<string, unknown>>
+
+function makeFakeBroadcast() {
+  const registrations: { pattern: string; callback: AuthCallback }[] = []
+  return {
+    registrations,
+    mod: {
+      registerAuth(pattern: string, callback: AuthCallback) {
+        registrations.push({ pattern, callback })
+      },
+    },
+  }
+}
+
+describe('registerBroadcastAuth()', () => {
+  afterEach(() => _setTestBroadcastAuth(undefined))
+
+  it('no-ops when databaseNotifications() wasn\'t called', async () => {
+    const fake = makeFakeBroadcast()
+    _setTestBroadcastAuth(fake.mod)
+    await registerBroadcastAuth(Pilotiq.make('a'))
+    assert.equal(fake.registrations.length, 0)
+  })
+
+  it('no-ops when broadcast wasn\'t enabled', async () => {
+    const fake = makeFakeBroadcast()
+    _setTestBroadcastAuth(fake.mod)
+    const p = Pilotiq.make('a').databaseNotifications()
+    await registerBroadcastAuth(p)
+    assert.equal(fake.registrations.length, 0)
+  })
+
+  it('no-ops when @rudderjs/broadcast is unavailable', async () => {
+    _setTestBroadcastAuth(null)
+    const p = Pilotiq.make('a')
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    await registerBroadcastAuth(p)
+    // No throw == soft-fail OK
+  })
+
+  it('registers the private-pilotiq-notifications.* pattern', async () => {
+    const fake = makeFakeBroadcast()
+    _setTestBroadcastAuth(fake.mod)
+    const p = Pilotiq.make('a')
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    await registerBroadcastAuth(p)
+    assert.equal(fake.registrations.length, 1)
+    assert.equal(fake.registrations[0]!.pattern, 'private-pilotiq-notifications.*')
+  })
+
+  it('auth callback returns true when the user.id matches the channel id', async () => {
+    const fake = makeFakeBroadcast()
+    _setTestBroadcastAuth(fake.mod)
+    const p = Pilotiq.make('a')
+      .user(() => ({ id: 42, name: 'Sue' }))
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    await registerBroadcastAuth(p)
+    const cb = fake.registrations[0]!.callback
+    const result = await cb(
+      { headers: {}, url: '/ws' },
+      'private-pilotiq-notifications.42',
+    )
+    assert.equal(result, true)
+  })
+
+  it('auth callback returns false on user-id mismatch', async () => {
+    const fake = makeFakeBroadcast()
+    _setTestBroadcastAuth(fake.mod)
+    const p = Pilotiq.make('a')
+      .user(() => ({ id: 42 }))
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    await registerBroadcastAuth(p)
+    const cb = fake.registrations[0]!.callback
+    const result = await cb(
+      { headers: {}, url: '/ws' },
+      'private-pilotiq-notifications.7',
+    )
+    assert.equal(result, false)
+  })
+
+  it('auth callback returns false when no user resolves', async () => {
+    const fake = makeFakeBroadcast()
+    _setTestBroadcastAuth(fake.mod)
+    const p = Pilotiq.make('a')
+      .user(() => null)
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    await registerBroadcastAuth(p)
+    const cb = fake.registrations[0]!.callback
+    const result = await cb(
+      { headers: {}, url: '/ws' },
+      'private-pilotiq-notifications.42',
+    )
+    assert.equal(result, false)
+  })
+
+  it('auth callback returns false when channel name is malformed', async () => {
+    const fake = makeFakeBroadcast()
+    _setTestBroadcastAuth(fake.mod)
+    const p = Pilotiq.make('a')
+      .user(() => ({ id: 1 }))
+      .databaseNotifications()
+      .databaseNotificationsBroadcast()
+    await registerBroadcastAuth(p)
+    const cb = fake.registrations[0]!.callback
+    const result = await cb(
+      { headers: {}, url: '/ws' },
+      'private-other-thing.1',
+    )
+    assert.equal(result, false)
+  })
+})

package/src/notifications/registerBroadcastAuth.ts

@@ -0,0 +1,100 @@
+/**
+ * Broadcast auth-callback registration. Runs once at panel boot when
+ * `Pilotiq.databaseNotifications({ broadcast: true })` is set; gates
+ * subscriptions to `private-pilotiq-notifications.${userId}` on the
+ * current user resolving to `userId`.
+ *
+ * Idempotent — calling twice for the same panel only registers once
+ * (the broadcast auth registry stores by pattern, so re-registration
+ * would just overwrite with the same callback). The pattern is namespaced
+ * by panel base-path so two panels in one app don't fight over the same
+ * registration slot.
+ *
+ * `@rudderjs/broadcast` is soft-imported via variable-string indirection
+ * so pilotiq stays zero-dep on broadcast — apps that don't enable
+ * broadcast don't need the package installed.
+ */
+
+import type { Pilotiq } from '../Pilotiq.js'
+
+/** Mirror of `@rudderjs/broadcast`'s `BroadcastAuthRequest` — copied to
+ *  avoid a hard import dependency. We use a structural subset; broadcast
+ *  passes the full object through but we only consume `headers` + `url`. */
+interface BroadcastAuthRequest {
+  headers: Record<string, string | string[] | undefined>
+  url:     string
+  token?:  string
+}
+
+interface BroadcastModule {
+  registerAuth?(
+    pattern:  string,
+    callback: (req: BroadcastAuthRequest, channel: string) => Promise<boolean | Record<string, unknown>>,
+  ): void
+}
+
+let _testModule: BroadcastModule | null | 'unset' = 'unset'
+
+/** Register the auth callback for `private-pilotiq-notifications.*`.
+ *  Soft-fails when `@rudderjs/broadcast` isn't installed.
+ *
+ *  The auth callback receives a synthetic request — the WebSocket
+ *  upgrade carries cookies / Authorization headers but lacks the rudder
+ *  request shape pilotiq's user resolver expects. We pass the original
+ *  upgrade headers + url through under the same `req` key the resolver
+ *  reads from; apps using `@rudderjs/auth` see cookies and resolve as
+ *  usual. Apps that need the raw Hono context can read it from the
+ *  `headers` object. */
+export async function registerBroadcastAuth(pilotiq: Pilotiq): Promise<void> {
+  const cfg = pilotiq.getConfig()
+  if (!cfg.databaseNotifications?.enabled) return
+  if (!cfg.databaseNotifications.broadcast)  return
+
+  const mod = await loadBroadcast()
+  if (!mod?.registerAuth) return
+
+  // Pattern matches every `private-pilotiq-notifications.<id>` channel.
+  // Wildcard `*` is the broadcast package's single-segment match — fine
+  // for numeric / uuid-style ids.
+  mod.registerAuth('private-pilotiq-notifications.*', async (req, channel) => {
+    const expectedId = parseChannelUserId(channel)
+    if (expectedId === null) return false
+    // Pilotiq's user resolver takes "the request" and returns a user
+    // object. The broadcast upgrade-req carries headers but not the full
+    // rudder request shape — apps using `@rudderjs/auth` read from
+    // `req.headers.cookie` so this works for the common case. For custom
+    // resolvers that read deeper request state, register your own
+    // callback before pilotiq's via `Broadcast.channel(...)`.
+    const user = await pilotiq.resolveUser(req)
+    if (!user || typeof user !== 'object') return false
+    const id = (user as { id?: unknown }).id
+    if (id === undefined || id === null) return false
+    return String(id) === expectedId
+  })
+}
+
+function parseChannelUserId(channel: string): string | null {
+  const prefix = 'private-pilotiq-notifications.'
+  if (!channel.startsWith(prefix)) return null
+  const id = channel.slice(prefix.length)
+  return id === '' ? null : id
+}
+
+async function loadBroadcast(): Promise<BroadcastModule | null> {
+  if (_testModule !== 'unset') return _testModule
+  const moduleName = '@rudderjs/broadcast'
+  try {
+    const mod = await import(/* @vite-ignore */ moduleName) as Partial<BroadcastModule>
+    if (typeof mod.registerAuth !== 'function') return null
+    return mod as BroadcastModule
+  } catch {
+    return null
+  }
+}
+
+/** @internal — test seam; injects a fake `@rudderjs/broadcast` module
+ *  so we can assert the pattern + callback shape without spinning up a
+ *  real WebSocket server. */
+export function _setTestBroadcastAuth(mod: BroadcastModule | null | undefined): void {
+  _testModule = mod === undefined ? 'unset' : mod
+}

package/src/notifications/resolveSavedNotification.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { Form } from '../elements/Form.js'
+import { Notification, _resetNotificationIdSeq } from './Notification.js'
+import { resolveSavedNotification } from './resolveSavedNotification.js'
+
+describe('resolveSavedNotification', () => {
+  beforeEach(() => _resetNotificationIdSeq())
+
+  it('returns null when nothing is configured', () => {
+    const form = Form.make<{ id: number }>()
+    const got = resolveSavedNotification(form, 'create', { id: 1 }, { values: {} })
+    assert.equal(got, null)
+  })
+
+  it('disableSavedNotification beats every other spec', () => {
+    const form = Form.make<{ id: number }>()
+      .savedNotification('Saved')
+      .createdNotification('Created')
+      .disableSavedNotification()
+    const got = resolveSavedNotification(form, 'create', { id: 1 }, { values: {} })
+    assert.equal(got, null)
+  })
+
+  it('string spec produces a success notification with that title', () => {
+    const form = Form.make<{ id: number }>().savedNotification('Saved')
+    const got = resolveSavedNotification(form, 'update', { id: 1 }, { values: {} })
+    assert.ok(got)
+    assert.equal(got!.type, 'success')
+    assert.equal(got!.title, 'Saved')
+  })
+
+  it('mode-specific createdNotification wins over savedNotification in create mode', () => {
+    const form = Form.make<{ id: number }>()
+      .savedNotification('Saved')
+      .createdNotification('Created')
+    const got = resolveSavedNotification(form, 'create', { id: 1 }, { values: {} })
+    assert.equal(got!.title, 'Created')
+  })
+
+  it('createdNotification does NOT apply in update mode (falls back to shared)', () => {
+    const form = Form.make<{ id: number }>()
+      .savedNotification('Saved')
+      .createdNotification('Created')
+    const got = resolveSavedNotification(form, 'update', { id: 1 }, { values: {} })
+    assert.equal(got!.title, 'Saved')
+  })
+
+  it('null mode-spec suppresses the toast for that mode but not the other', () => {
+    const form = Form.make<{ id: number }>()
+      .savedNotification('Saved')
+      .createdNotification(null)
+    const create = resolveSavedNotification(form, 'create', { id: 1 }, { values: {} })
+    const update = resolveSavedNotification(form, 'update', { id: 1 }, { values: {} })
+    assert.equal(create, null)
+    assert.equal(update!.title, 'Saved')
+  })
+
+  it('function spec receives record + ctx and is recursively resolved', () => {
+    const form = Form.make<{ id: number; name: string }>()
+      .savedNotification((record) => `Saved #${record.id}`)
+    const got = resolveSavedNotification(form, 'update', { id: 7, name: 'a' }, { values: {} })
+    assert.equal(got!.title, 'Saved #7')
+  })
+
+  it('Notification builder spec passes through to meta', () => {
+    const form = Form.make<{ id: number }>()
+      .savedNotification(Notification.make('Done').warning().body('details'))
+    const got = resolveSavedNotification(form, 'update', { id: 1 }, { values: {} })
+    assert.equal(got!.type, 'warning')
+    assert.equal(got!.title, 'Done')
+    assert.equal(got!.body, 'details')
+  })
+
+  it('NotificationMeta object spec passes through unchanged', () => {
+    const meta = { id: 'fixed', type: 'info' as const, title: 'Note' }
+    const form = Form.make<{ id: number }>().savedNotification(meta)
+    const got = resolveSavedNotification(form, 'update', { id: 1 }, { values: {} })
+    assert.deepEqual(got, meta)
+  })
+})

package/src/notifications/resolveSavedNotification.ts

@@ -0,0 +1,59 @@
+/**
+ * Resolve the saved-notification spec on a `Form` into a concrete
+ * `NotificationMeta`, or `null` when notifications are explicitly
+ * disabled. Used by `dispatchFormSubmit` to attach the success toast to
+ * its result.
+ *
+ * Resolution order:
+ *   1. If the form has `disableSavedNotification()` → null.
+ *   2. Mode-specific spec (`createdNotification` for create) wins over
+ *      generic `savedNotification` when set.
+ *   3. `null` spec returns null (explicitly suppress the toast for that
+ *      mode while keeping the generic fallback for the other mode).
+ *   4. String spec → success toast with that title.
+ *   5. Function spec → invoked with `(record, ctx)` and re-resolved.
+ *   6. `Notification` builder or `NotificationMeta` → passes through.
+ */
+import { Notification, type NotificationMeta } from './Notification.js'
+import type { Form, FormContext, SavedNotificationHandler } from '../elements/Form.js'
+
+export type SavedNotificationMode = 'create' | 'update'
+
+export function resolveSavedNotification<R>(
+  form:    Form<R>,
+  mode:    SavedNotificationMode,
+  record:  R,
+  ctx:     FormContext<R>,
+): NotificationMeta | null {
+  if (form.isSavedNotificationDisabled()) return null
+
+  const modeSpec    = mode === 'create' ? form.getCreatedNotification() : undefined
+  const sharedSpec  = form.getSavedNotification()
+  const spec        = modeSpec !== undefined ? modeSpec : sharedSpec
+
+  if (spec === undefined) return null
+  return resolveSpec(spec, record, ctx)
+}
+
+function resolveSpec<R>(
+  spec:   SavedNotificationHandler<R>,
+  record: R,
+  ctx:    FormContext<R>,
+): NotificationMeta | null {
+  if (spec === null) return null
+
+  if (typeof spec === 'function') {
+    const next = spec(record, ctx)
+    return next === null ? null : resolveSpec(next as SavedNotificationHandler<R>, record, ctx)
+  }
+
+  if (typeof spec === 'string') {
+    return Notification.make(spec).success().toMeta()
+  }
+
+  if (spec instanceof Notification) {
+    return spec.toMeta()
+  }
+
+  return spec
+}

package/src/notifications/types.ts

@@ -0,0 +1,93 @@
+import type { ActionColor, ActionSize, DownloadEnvelope } from '../actions/Action.js'
+import type { NotificationMeta } from './Notification.js'
+
+/**
+ * Minimal notifiable contract used by `Notification.sendToDatabase()`
+ * and the bell-icon endpoints. Mirrors the shape `@rudderjs/notification`
+ * already publishes — `id` (string or number) is the only required
+ * field. We coerce to string when writing the `notifiable_id` column so
+ * mixed `number`/`string` ids stay consistent on disk.
+ */
+export interface Notifiable {
+  readonly id:     string | number
+  readonly email?: string
+  readonly name?:  string
+}
+
+/**
+ * Slim wire shape emitted by `Notification.actions([Action…])`. Same
+ * format on the transient toast meta, the persisted database row's
+ * `data.actions` JSON, and the `_notifications` list endpoint — so the
+ * bell client and the toaster can share render code.
+ *
+ * Exactly one of `url` / `post` / `handler` is set. The serializer in
+ * `Notification.ts` enforces mutual exclusion at config time and rejects
+ * Action features that don't make sense in a notification context
+ * (modal-form, submit, bulk placement) with a clear error.
+ */
+export interface NotificationActionMeta {
+  /** Stable name; used as the registry key for handler dispatch and
+   *  as the action identifier the route's URL carries. */
+  name:               string
+  label:              string
+  /** Click navigates here. */
+  url?:               string
+  /** Click submits a `<form method="post" action="…">`. */
+  post?:              string
+  /** Registry key — looked up via `Pilotiq.notificationHandlers({…})`
+   *  at request time. The matching handler runs server-side; the bell
+   *  client renders a button that POSTs to the notification action
+   *  endpoint. */
+  handler?:           string
+  /** Per-fire context the handler receives on `ctx.payload`. JSON-only
+   *  (`Date`/`Map`/etc don't survive — stringify them yourself). Stored
+   *  alongside the action when the row is persisted. */
+  payload?:           Record<string, unknown>
+  color?:             ActionColor
+  icon?:              string
+  outlined?:          boolean
+  size?:              ActionSize
+  openUrlInNewTab?:   boolean
+  /**
+   * When set, firing this action also flips the notification's
+   * `read_at` column. Url/post variants fire the read POST as a
+   * client-side side-effect; handler dispatch handles it server-side
+   * inside the action route so the round-trip is one request.
+   */
+  markAsRead?:        boolean
+}
+
+/**
+ * Server-side handler signature for `Pilotiq.notificationHandlers({…})`
+ * registry entries. Mirrors the `ActionHandler` from
+ * `dispatchAction` minus row context (notifications don't carry one),
+ * plus `payload` (the per-fire context the action carried) and
+ * `notificationId` (the row the click came from).
+ */
+export type NotificationActionHandler = (
+  ctx: NotificationActionContext,
+) => Promise<NotificationActionResult | undefined> | NotificationActionResult | undefined
+
+export interface NotificationActionContext {
+  /** Resolved by `pilotiq.resolveUser(req)` before the route fires.
+   *  Always present — the route gates on auth before reaching the
+   *  registry. */
+  user:           unknown
+  /** Per-fire context the action carried. Empty object when the action
+   *  was created without `.payload({…})`. */
+  payload:        Record<string, unknown>
+  /** Database row id this click came from. */
+  notificationId: string
+  /** Raw request — same opaque shape that flows into Resource action
+   *  handlers, in case a handler needs cookies / headers. */
+  request?:       unknown
+}
+
+export interface NotificationActionResult {
+  /** SPA-navigate after the handler completes. */
+  redirect?: string
+  /** Toast(s) to flash after the handler completes. */
+  notify?:   NotificationMeta | NotificationMeta[]
+  /** File-download envelope (parallel to dispatchAction). */
+  download?: DownloadEnvelope
+}

package/src/orm/m2mAccessor.ts

@@ -0,0 +1,66 @@
+/**
+ * The M2M pivot-mutation surface exposed by `@rudderjs/orm`. Returned
+ * from per-relation accessor methods installed on parent prototypes
+ * (e.g. `user.roles()` → `{ attach, detach, sync }`).
+ *
+ * Each method is optional in the structural type because some test
+ * doubles only stub the subset they exercise — `resolveM2MAccessor`
+ * gates on `attach || detach` being callable to filter unrelated
+ * shapes (e.g. a deferred QB Proxy from `parent.related()`).
+ */
+export interface M2MAccessor {
+  attach?(input:      unknown): Promise<void>
+  detach?(input?:     unknown): Promise<unknown>
+  sync?(desiredIds:   ReadonlyArray<string | number>): Promise<unknown>
+  /**
+   * Update extras on an existing pivot row without touching either side
+   * of the relation. Returns the number of rows updated (0 when no
+   * matching pivot exists). Optional on the structural shape; pilotiq's
+   * `Repeater.relationship.pivotColumns([…])` pipeline gates on its
+   * presence and throws a clear error when missing (rudder ORM ships
+   * it from `feat(orm): pivot-extras read/update + per-id sync` —
+   * see `~/Projects/rudder/docs/plans/2026-05-06-belongs-to-many-pivot-extras.md`).
+   */
+  updatePivot?(relatedId: string | number, data: Record<string, unknown>): Promise<number>
+}
+
+/**
+ * Resolve the M2M pivot-mutation accessor for `parent[rel]`. Two
+ * shapes are supported, in this order:
+ *
+ *   1. `parent[rel]()` — the real `@rudderjs/orm` shape installed by
+ *      `_installBelongsToManyMethods` / `_installMorphPivotMethods`
+ *      (e.g. `post.tags()` returns `{ attach, detach, sync }`).
+ *   2. `parent.related(rel)` — legacy / test-double shape that returns
+ *      the accessor directly. Kept so existing pilotiq tests built
+ *      around `parent.related(...)` mocks keep passing.
+ *
+ * Returns `undefined` when neither shape exposes a callable `attach`
+ * AND a callable `detach` — caller should surface a clear error
+ * (different copy depending on whether they're inside an Action handler
+ * or a `Repeater.relationship` save).
+ *
+ * Note `parent.related(rel)` returns a deferred-QB Proxy in the real
+ * ORM, NOT an attach/detach accessor — see
+ * `feedback_m2m_accessor_shape.md`. The shape-1 instance-method form is
+ * the canonical lookup; the related() fallback is purely a test-mock
+ * affordance.
+ */
+export function resolveM2MAccessor(parent: unknown, rel: string): M2MAccessor | undefined {
+  if (!parent || typeof parent !== 'object') return undefined
+  // Shape 1: parent[rel]() — real ORM. Prototype-installed method.
+  const inst = (parent as Record<string, unknown>)[rel]
+  if (typeof inst === 'function') {
+    try {
+      const out = (inst as () => unknown).call(parent) as M2MAccessor | undefined
+      if (out && (typeof out.attach === 'function' || typeof out.detach === 'function')) return out
+    } catch { /* fall through to legacy shape */ }
+  }
+  // Shape 2: parent.related(rel) — legacy / test-mock shape.
+  const relatedFn = (parent as { related?: (n: string) => unknown }).related
+  if (typeof relatedFn === 'function') {
+    const out = relatedFn.call(parent, rel) as M2MAccessor | undefined
+    if (out && (typeof out.attach === 'function' || typeof out.detach === 'function')) return out
+  }
+  return undefined
+}