@pilotiq/pilotiq 0.23.1 → 0.24.2

package/src/notifications/registerBroadcastAuth.test.ts

@@ -1,134 +0,0 @@
-/**
- * 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

@@ -1,100 +0,0 @@
-/**
- * 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

@@ -1,82 +0,0 @@
-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

@@ -1,59 +0,0 @@
-/**
- * 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

@@ -1,93 +0,0 @@
-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

@@ -1,66 +0,0 @@
-/**
- * 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
-}