@meith/plugin-kit 0.31.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/plugin-kit",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "description": "The SDK for writing a Meith plugin: typed manifests, hooks, routes, pages and migrations.",
   "license": "MIT",
   "repository": {
@@ -20,8 +20,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@meith/core": "^0.31.0",
-    "@meith/theme-kit": "^0.31.0"
+    "@meith/core": "^0.32.0",
+    "@meith/theme-kit": "^0.32.0"
   },
   "peerDependencies": {
     "react": "^19.2.0"

package/src/host.ts

@@ -5,11 +5,12 @@ import type { HookContext, HookValue } from './payloads'
 import type {
   HookRegistration,
   HookRuntime,
-  PluginContribution,
   PluginDefinition,
+  PluginRegionContribution,
   PluginRuntimeContext,
+  ThreadRowBadgesContribution,
 } from './plugin'
-import type { PluginRegion, PluginRegionContext } from './regions'
+import type { PluginRegion, PluginRegionContext, ThreadRowBadgesContext } from './regions'
 
 export interface HostLogger {
   readonly warn: (message: string, detail: Record<string, unknown>) => void
@@ -83,8 +84,13 @@ export class PluginHost {
   readonly #entries = new Map<HookName, Entry[]>()
   readonly #contributions = new Map<
     PluginRegion,
-    { pluginKey: string; priority: number; contribution: PluginContribution }[]
+    { pluginKey: string; priority: number; render: PluginRegionContribution['render'] }[]
   >()
+  readonly #badgeContributions: {
+    pluginKey: string
+    priority: number
+    render: ThreadRowBadgesContribution['render']
+  }[] = []
   readonly #stats = new Map<string, Stats>()
   readonly #logger: HostLogger
   readonly #failureThreshold: number
@@ -140,11 +146,20 @@ export class PluginHost {
       }
 
       for (const contribution of plugin.contributions ?? []) {
+        if (contribution.region === 'threadrow.badges') {
+          this.#badgeContributions.push({
+            pluginKey: plugin.key,
+            priority: contribution.priority ?? DEFAULT_PRIORITY,
+            render: contribution.render,
+          })
+          continue
+        }
+
         const list = this.#contributions.get(contribution.region) ?? []
         list.push({
           pluginKey: plugin.key,
           priority: contribution.priority ?? DEFAULT_PRIORITY,
-          contribution,
+          render: contribution.render,
         })
         this.#contributions.set(contribution.region, list)
       }
@@ -159,6 +174,7 @@ export class PluginHost {
 
     for (const list of this.#entries.values()) list.sort(byPriorityThenKey)
     for (const list of this.#contributions.values()) list.sort(byPriorityThenKey)
+    this.#badgeContributions.sort(byPriorityThenKey)
   }
 
   async applyFilter<K extends HookName>(
@@ -219,7 +235,7 @@ export class PluginHost {
 
       const started = this.#now()
       try {
-        const node = await entry.contribution.render({
+        const node = await entry.render({
           ...context,
           runtime: this.#runtimeFor(entry.pluginKey),
         })
@@ -232,6 +248,35 @@ export class PluginHost {
     return nodes
   }
 
+  async renderThreadRowBadges(
+    context: Omit<ThreadRowBadgesContext, 'runtime'>,
+  ): Promise<ReadonlyMap<number, readonly { key: string; node: ReactNode }[]>> {
+    const byThread = new Map<number, { key: string; node: ReactNode }[]>()
+    if (this.#badgeContributions.length === 0) return byThread
+
+    for (const entry of this.#badgeContributions) {
+      if (!this.#isEnabled(entry.pluginKey)) continue
+
+      const started = this.#now()
+      try {
+        const badges = await entry.render({
+          ...context,
+          runtime: this.#runtimeFor(entry.pluginKey),
+        })
+        this.#record(entry.pluginKey, 'threadrow.badges', this.#now() - started)
+        for (const [threadId, node] of badges) {
+          if (node === null || node === undefined) continue
+          const list = byThread.get(threadId) ?? []
+          list.push({ key: entry.pluginKey, node })
+          byThread.set(threadId, list)
+        }
+      } catch (error) {
+        this.#fail(entry.pluginKey, 'threadrow.badges', error)
+      }
+    }
+    return byThread
+  }
+
   health(): readonly PluginHealth[] {
     return [...this.#stats.entries()]
       .map(([key, stats]) => ({

package/src/index.ts

@@ -53,18 +53,21 @@ export {
   type PluginContribution,
   type PluginDefinition,
   type PluginHooks,
+  type PluginIntervalTask,
   type PluginMigration,
   type PluginNavigationAudience,
   type PluginNavigationItem,
   type PluginNotificationKind,
   type PluginPageAccess,
   type PluginPageContext,
+  type PluginRegionContribution,
   type PluginRequest,
   type PluginResponse,
   type PluginRoute,
   type PluginRouteAccess,
   type PluginRouteRateLimit,
   type PluginRuntimeContext,
+  type PluginScheduledTask,
   type PluginSetting,
   type PluginSettingType,
   type PluginTask,
@@ -76,8 +79,11 @@ export {
   pluginPagePath,
   pluginRoutePath,
   pluginSettingKey,
+  pluginStaffPagePath,
   pluginTablePrefix,
   pluginTaskId,
+  type ThreadRowBadges,
+  type ThreadRowBadgesContribution,
 } from './plugin'
 export {
   createRouteRateLimiter,
@@ -91,6 +97,8 @@ export {
   type PluginRegionContext,
   REGION_NAMES,
   type RegionSpec,
+  type ThreadRowBadgeSubject,
+  type ThreadRowBadgesContext,
 } from './regions'
 export {
   renderingSignature,

package/src/navigation.ts

@@ -3,6 +3,7 @@ import {
   type PluginNavigationAudience,
   pluginNavigationKey,
   pluginPagePath,
+  pluginStaffPagePath,
 } from './plugin'
 
 export interface PluginNavigationPlacement {
@@ -21,7 +22,9 @@ export function pluginNavigationPlacements(
   return plugins.flatMap((plugin) =>
     (plugin.navigation ?? []).map((item) => ({
       key: pluginNavigationKey(plugin.key, item.key),
-      href: pluginPagePath(plugin.key, item.path),
+      href: ((plugin.pages ?? []).find((page) => page.path === item.path)?.access === 'staff'
+        ? pluginStaffPagePath
+        : pluginPagePath)(plugin.key, item.path),
       audience: item.audience ?? ('all' as const),
       parentKey: item.under === undefined ? null : pluginNavigationKey(plugin.key, item.under),
       label: item.label,

package/src/plugin.ts

@@ -2,11 +2,17 @@ export type { HookRuntime, PluginRuntimeContext } from './runtime'
 
 import type { ReactNode } from 'react'
 
+import { CADENCE_REFERENCE, nextRun, parseCron } from '@meith/core'
 import type { Translator } from '@meith/theme-kit'
 
 import { type HOOKS, type HookName, isHookName } from './hooks'
 import type { HookContext, HookValue } from './payloads'
-import { isPluginRegion, type PluginRegion, type PluginRegionContext } from './regions'
+import {
+  isPluginRegion,
+  type PluginRegion,
+  type PluginRegionContext,
+  type ThreadRowBadgesContext,
+} from './regions'
 import type { HookRuntime, PluginRuntimeContext } from './runtime'
 
 export type FilterHandler<K extends HookName> = (
@@ -61,12 +67,23 @@ export interface PluginMigration {
   readonly statements: readonly string[]
 }
 
-export interface PluginTask {
+interface PluginTaskBase {
   readonly id: string
-  readonly intervalSeconds: number
   readonly run: (context: PluginRuntimeContext) => Promise<void> | void
 }
 
+export interface PluginIntervalTask extends PluginTaskBase {
+  readonly intervalSeconds: number
+  readonly schedule?: undefined
+}
+
+export interface PluginScheduledTask extends PluginTaskBase {
+  readonly schedule: string
+  readonly intervalSeconds?: undefined
+}
+
+export type PluginTask = PluginIntervalTask | PluginScheduledTask
+
 export interface PluginAdminPage {
   readonly path: string
   readonly title: string
@@ -75,12 +92,22 @@ export interface PluginAdminPage {
   readonly render: (context: PluginAdminPageContext) => ReactNode | Promise<ReactNode>
 }
 
-export interface PluginContribution {
-  readonly region: PluginRegion
+export interface PluginRegionContribution {
+  readonly region: Exclude<PluginRegion, 'threadrow.badges'>
   readonly priority?: number | undefined
   readonly render: (context: PluginRegionContext) => ReactNode | Promise<ReactNode>
 }
 
+export type ThreadRowBadges = ReadonlyMap<number, ReactNode>
+
+export interface ThreadRowBadgesContribution {
+  readonly region: 'threadrow.badges'
+  readonly priority?: number | undefined
+  readonly render: (context: ThreadRowBadgesContext) => ThreadRowBadges | Promise<ThreadRowBadges>
+}
+
+export type PluginContribution = PluginRegionContribution | ThreadRowBadgesContribution
+
 export interface PluginViewer {
   readonly userId: number | null
   readonly isGuest: boolean
@@ -108,8 +135,8 @@ export type PluginResponse =
     }
   | { readonly kind: 'redirect'; readonly to: string }
 
-export type PluginRouteAccess = 'anonymous' | 'member' | 'admin'
-export type PluginPageAccess = 'anonymous' | 'member'
+export type PluginRouteAccess = 'anonymous' | 'member' | 'staff' | 'admin'
+export type PluginPageAccess = 'anonymous' | 'member' | 'staff'
 
 export interface PluginRouteRateLimit {
   readonly limit: number
@@ -438,7 +465,24 @@ export function definePlugin(plugin: PluginDefinition): PluginDefinition {
         `${where}: task id "${task.id}" must be lower-case letters, digits and hyphens.`,
       )
     }
-    if (!Number.isInteger(task.intervalSeconds) || task.intervalSeconds < 60) {
+
+    const hasInterval = task.intervalSeconds !== undefined
+    const hasSchedule = task.schedule !== undefined
+    if (hasInterval === hasSchedule) {
+      throw new Error(
+        `${where}: task "${task.id}" must set exactly one of intervalSeconds (a fixed cadence) ` +
+          'or schedule (a five-field cron expression evaluated in UTC).',
+      )
+    }
+
+    if (task.schedule !== undefined) {
+      try {
+        nextRun(parseCron(task.schedule), CADENCE_REFERENCE)
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error)
+        throw new Error(`${where}: task "${task.id}" ${detail}.`)
+      }
+    } else if (!Number.isInteger(task.intervalSeconds) || task.intervalSeconds < 60) {
       throw new Error(
         `${where}: task "${task.id}" has an interval of ${task.intervalSeconds}s. The tick ` +
           'is minute-granular at best on a serverless platform; anything under 60s is a ' +
@@ -487,9 +531,14 @@ export function definePlugin(plugin: PluginDefinition): PluginDefinition {
     if (route.method !== 'GET' && route.method !== 'POST') {
       throw new Error(`${where}: route "${route.path}" method must be GET or POST.`)
     }
-    if (route.access !== 'anonymous' && route.access !== 'member' && route.access !== 'admin') {
+    if (
+      route.access !== 'anonymous' &&
+      route.access !== 'member' &&
+      route.access !== 'staff' &&
+      route.access !== 'admin'
+    ) {
       throw new Error(
-        `${where}: route "${route.path}" access must be "anonymous", "member" or "admin".`,
+        `${where}: route "${route.path}" access must be "anonymous", "member", "staff" or "admin".`,
       )
     }
     if (typeof route.handler !== 'function') {
@@ -539,8 +588,10 @@ export function definePlugin(plugin: PluginDefinition): PluginDefinition {
     if (page.title.trim() === '') {
       throw new Error(`${where}: the page at "${page.path}" needs a title.`)
     }
-    if (page.access !== 'anonymous' && page.access !== 'member') {
-      throw new Error(`${where}: page "${page.path}" access must be "anonymous" or "member".`)
+    if (page.access !== 'anonymous' && page.access !== 'member' && page.access !== 'staff') {
+      throw new Error(
+        `${where}: page "${page.path}" access must be "anonymous", "member" or "staff".`,
+      )
     }
     if (typeof page.render !== 'function') {
       throw new Error(`${where}: page "${page.path}" needs a render function.`)
@@ -674,6 +725,10 @@ export function pluginPagePath(pluginKey: string, path: string): string {
   return `/plugins/${pluginKey}${path === '' ? '' : `/${path}`}`
 }
 
+export function pluginStaffPagePath(pluginKey: string, path: string): string {
+  return `/modcp/plugins/${pluginKey}${path === '' ? '' : `/${path}`}`
+}
+
 export function pluginNavigationKey(pluginKey: string, itemKey: string): string {
   return `plugin.${pluginKey}.${itemKey}`
 }

package/src/regions.ts

@@ -1,3 +1,5 @@
+import type { Translator } from '@meith/theme-kit'
+
 import type { HookRuntime } from './runtime'
 
 export interface RegionSpec {
@@ -8,35 +10,50 @@ export interface RegionSpec {
 export const PLUGIN_REGIONS = {
   'header.notice': {
     purpose: 'Directly below the board header, above the page body. Board-wide notices.',
-    context: 'The viewer.',
+    context: 'The viewer, with the reader’s locale and a translator.',
   },
   'index.footer': {
     purpose: 'The bottom of the board index, below the statistics block.',
-    context: 'The viewer.',
+    context: 'The viewer, with the reader’s locale and a translator.',
   },
   'postbit.badges': {
     purpose:
       'Beside a post author’s name. Runs once per post on every thread page — the ' +
       'most expensive region on the board, and the one to keep trivial.',
-    context: 'The viewer, the post id and the author id.',
+    context:
+      'The viewer, the post id and the author id, with the reader’s locale and a translator.',
   },
   'postbit.footer': {
     purpose: 'Below a post body, above its actions.',
-    context: 'The viewer, the post id and the author id.',
+    context:
+      'The viewer, the post id and the author id, with the reader’s locale and a translator.',
+  },
+  'threadrow.badges': {
+    purpose:
+      'Beside a thread’s title in a listing, to mark threads across a forum page. A ' +
+      'batch region: unlike every other region it runs once per page, not once per ' +
+      'row — a listing of twenty threads is one call, returning a badge per thread ' +
+      'id — because a forum page is on a tight budget and a per-row region there is ' +
+      'twenty calls before the page has drawn a thing.',
+    context:
+      'The viewer and the page’s visible threads, each as a thread id and its author ' +
+      'id, with the reader’s locale and a translator.',
   },
   'thread.header': {
     purpose:
       'Above the first post of a thread, below its title. Runs once per thread page, ' +
       'so unlike postbit.* it can afford to read from the plugin’s own tables.',
-    context: 'The viewer, the thread id and the thread author’s id.',
+    context:
+      'The viewer, the thread id and the thread author’s id, with the reader’s locale and ' +
+      'a translator.',
   },
   'profile.panel': {
     purpose: 'A panel on a member’s profile, below the standard fields.',
-    context: 'The viewer and the profile’s member id.',
+    context: 'The viewer and the profile’s member id, with the reader’s locale and a translator.',
   },
   'admin.dashboard': {
     purpose: 'A card on the admin dashboard. Only rendered for administrators.',
-    context: 'The viewer.',
+    context: 'The viewer, with the reader’s locale and a translator.',
   },
 } as const satisfies Readonly<Record<string, RegionSpec>>
 
@@ -53,5 +70,20 @@ export interface PluginRegionContext {
   readonly viewer: { readonly userId: number | null; readonly isGuest: boolean }
   readonly subjectId: number | null
   readonly authorId: number | null
+  readonly locale: string
+  readonly t: Translator
+  readonly runtime: HookRuntime
+}
+
+export interface ThreadRowBadgeSubject {
+  readonly threadId: number
+  readonly authorId: number | null
+}
+
+export interface ThreadRowBadgesContext {
+  readonly viewer: { readonly userId: number | null; readonly isGuest: boolean }
+  readonly threads: readonly ThreadRowBadgeSubject[]
+  readonly locale: string
+  readonly t: Translator
   readonly runtime: HookRuntime
 }

package/src/runtime.ts

@@ -25,13 +25,15 @@ export interface PluginGrants {
   }): Promise<void>
 
   list(userId: number): Promise<readonly PluginGrantRow[]>
+
+  holds(userId: number, groupKey: string): Promise<boolean>
 }
 
 export function unavailablePluginGrants(reason: string): PluginGrants {
   const refuse = async (): Promise<never> => {
     throw new Error(`Plugin grants are unavailable: ${reason}`)
   }
-  return { grant: refuse, extend: refuse, revoke: refuse, list: refuse }
+  return { grant: refuse, extend: refuse, revoke: refuse, list: refuse, holds: refuse }
 }
 
 export interface PluginData {