@meith/plugin-kit 0.1.0

package/src/runtime.ts

@@ -0,0 +1,187 @@
+
+export interface PluginGrantRow {
+  readonly groupKey: string
+  readonly expiresAt: Date
+}
+
+export interface PluginGrants {
+  grant(input: {
+    readonly userId: number
+    readonly groupKey: string
+    readonly until: Date
+    readonly reason: string
+  }): Promise<void>
+
+  extend(input: {
+    readonly userId: number
+    readonly groupKey: string
+    readonly until: Date
+  }): Promise<void>
+
+  revoke(input: {
+    readonly userId: number
+    readonly groupKey: string
+    readonly reason: string
+  }): Promise<void>
+
+  list(userId: number): Promise<readonly PluginGrantRow[]>
+}
+
+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 }
+}
+
+export interface PluginData {
+  query<T extends Record<string, unknown> = Record<string, unknown>>(
+    text: string,
+    params?: readonly unknown[],
+  ): Promise<readonly T[]>
+
+  one<T extends Record<string, unknown> = Record<string, unknown>>(
+    text: string,
+    params?: readonly unknown[],
+  ): Promise<T | null>
+
+  tx<T>(work: (data: PluginData) => Promise<T>): Promise<T>
+}
+
+export function unavailablePluginData(reason: string): PluginData {
+  const refuse = async (): Promise<never> => {
+    throw new Error(`Plugin data access is unavailable: ${reason}`)
+  }
+  return { query: refuse, one: refuse, tx: refuse }
+}
+
+export interface PluginUserRef {
+  readonly userId: number
+  readonly username: string
+}
+
+export interface PluginUsers {
+  byUsername(username: string): Promise<PluginUserRef | null>
+  byId(userId: number): Promise<PluginUserRef | null>
+}
+
+export function unavailablePluginUsers(reason: string): PluginUsers {
+  const refuse = async (): Promise<never> => {
+    throw new Error(`Plugin user lookup is unavailable: ${reason}`)
+  }
+  return { byUsername: refuse, byId: refuse }
+}
+
+export interface PluginNotify {
+  send(input: {
+    readonly userId: number
+    readonly kind: string
+    readonly subject: string
+    readonly body?: string | undefined
+    readonly href?: string | undefined
+    readonly dedupeKey?: string | undefined
+  }): Promise<void>
+}
+
+export function unavailablePluginNotify(reason: string): PluginNotify {
+  const refuse = async (): Promise<never> => {
+    throw new Error(`Plugin notifications are unavailable: ${reason}`)
+  }
+  return { send: refuse }
+}
+
+const MAX_NOTIFY_SUBJECT = 200
+const MAX_NOTIFY_BODY = 2_000
+
+export interface PluginNotifyKindInput {
+  readonly key: string
+  readonly title: string
+  readonly description: string
+  readonly emailByDefault?: boolean | undefined
+}
+
+export interface PluginNotificationKindSpec {
+  readonly id: string
+  readonly title: string
+  readonly description: string
+  readonly audience: 'member'
+  readonly emailByDefault: boolean
+  readonly emailConfigurable: true
+}
+
+export interface PluginNotifyBackend {
+  raise(input: {
+    readonly userId: number
+    readonly kind: string
+    readonly data: Readonly<Record<string, string>>
+    readonly href?: string | null
+    readonly dedupeKey?: string | null
+  }): Promise<unknown>
+}
+
+export function pluginNotificationKindSpecs(
+  pluginKey: string,
+  kinds: readonly PluginNotifyKindInput[],
+): readonly PluginNotificationKindSpec[] {
+  return kinds.map((kind) => ({
+    id: `plugin.${pluginKey}.${kind.key}`,
+    title: kind.title,
+    description: kind.description,
+    audience: 'member',
+    emailByDefault: kind.emailByDefault ?? true,
+    emailConfigurable: true,
+  }))
+}
+
+export function pluginNotify(
+  pluginKey: string,
+  kinds: readonly PluginNotifyKindInput[],
+  backend: PluginNotifyBackend,
+): PluginNotify {
+  const declared = new Set(kinds.map((kind) => kind.key))
+
+  return {
+    async send(input) {
+      if (!declared.has(input.kind)) {
+        throw new Error(
+          `plugin "${pluginKey}": notification kind "${input.kind}" is not declared. ` +
+            'A kind must be in the plugin definition — that is what puts it on the ' +
+            'member’s preferences screen.',
+        )
+      }
+      if (!Number.isSafeInteger(input.userId) || input.userId <= 0) {
+        throw new Error(`plugin "${pluginKey}": a notification needs a real user id.`)
+      }
+
+      const subject = input.subject.trim()
+      if (subject === '' || subject.length > MAX_NOTIFY_SUBJECT) {
+        throw new Error(
+          `plugin "${pluginKey}": a notification subject is 1 to ${MAX_NOTIFY_SUBJECT} characters.`,
+        )
+      }
+
+      const body = (input.body ?? '').trim()
+      if (body.length > MAX_NOTIFY_BODY) {
+        throw new Error(
+          `plugin "${pluginKey}": a notification body caps at ${MAX_NOTIFY_BODY} characters — ` +
+            'link to a page for anything longer.',
+        )
+      }
+
+      if (input.href !== undefined && (!input.href.startsWith('/') || input.href.startsWith('//'))) {
+        throw new Error(
+          `plugin "${pluginKey}": a notification links within the board — the href must ` +
+            'start with a single "/".',
+        )
+      }
+
+      await backend.raise({
+        userId: input.userId,
+        kind: `plugin.${pluginKey}.${input.kind}`,
+        data: body === '' ? { subject } : { subject, body },
+        href: input.href ?? null,
+        dedupeKey: input.dedupeKey ?? null,
+      })
+    },
+  }
+}

package/src/settings.ts

@@ -0,0 +1,131 @@
+import type { PluginDefinition, PluginSetting, PluginSettingType } from './plugin'
+
+export type PluginSettingValue = string | number | boolean
+
+export type PluginEnvReader = (name: string) => string | undefined
+
+export type PluginSettingSource = 'environment' | 'board' | 'default'
+
+export interface ResolvedPluginSetting {
+  readonly setting: PluginSetting
+  readonly value: PluginSettingValue
+  readonly source: PluginSettingSource
+  readonly problem: string | null
+}
+
+export function pluginSettingType(setting: PluginSetting): PluginSettingType {
+  if (setting.type !== undefined) return setting.type
+  if (typeof setting.default === 'boolean') return 'boolean'
+  if (typeof setting.default === 'number') return 'number'
+  return 'string'
+}
+
+const ENABLED_SUFFIX = '_enabled'
+
+export function pluginEnabledKey(pluginKey: string): string {
+  return `plugin.${pluginKey}.${ENABLED_SUFFIX}`
+}
+
+export function serialisePluginSetting(value: PluginSettingValue): string {
+  if (typeof value === 'boolean') return value ? '1' : '0'
+  return String(value)
+}
+
+export function parsePluginSetting(
+  setting: PluginSetting,
+  raw: string,
+): PluginSettingValue | null {
+  if (typeof setting.default === 'boolean') {
+    if (raw === '1' || raw === 'true') return true
+    if (raw === '0' || raw === 'false') return false
+    return null
+  }
+
+  if (typeof setting.default === 'number') {
+    if (raw.trim() === '') return null
+    const parsed = Number(raw)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+
+  return raw
+}
+
+function resolveOne(
+  plugin: PluginDefinition,
+  setting: PluginSetting,
+  overrides: ReadonlyMap<string, string>,
+  env: PluginEnvReader | undefined,
+): ResolvedPluginSetting {
+  const type = pluginSettingType(setting)
+
+  const fromEnv = setting.env === undefined ? undefined : env?.(setting.env)
+  const stored = overrides.get(`plugin.${plugin.key}.${setting.key}`)
+
+  let value: PluginSettingValue | null = null
+  let source: PluginSettingSource = 'default'
+
+  if (fromEnv !== undefined && fromEnv.trim() !== '') {
+    value = parsePluginSetting(setting, fromEnv)
+    source = 'environment'
+  }
+  if (value === null && stored !== undefined) {
+    value = parsePluginSetting(setting, stored)
+    if (value !== null) source = 'board'
+  }
+  if (value === null) {
+    value = setting.default
+    source = 'default'
+  }
+
+  if (type === 'select' && !(setting.options ?? []).some((option) => option.value === value)) {
+    value = setting.default
+    source = 'default'
+  }
+
+  const problem =
+    setting.required === true && (value === '' || value === null)
+      ? setting.env === undefined
+        ? `“${setting.label}” is required and not set.`
+        : `“${setting.label}” is required — set it here or with ${setting.env}.`
+      : null
+
+  return { setting, value, source, problem }
+}
+
+export function resolvePluginSettings(
+  plugin: PluginDefinition,
+  overrides: ReadonlyMap<string, string>,
+  env?: PluginEnvReader,
+): Readonly<Record<string, PluginSettingValue>> {
+  const resolved: Record<string, PluginSettingValue> = {}
+
+  for (const setting of plugin.settings ?? []) {
+    resolved[setting.key] = resolveOne(plugin, setting, overrides, env).value
+  }
+
+  return resolved
+}
+
+export function resolvePluginSettingDetails(
+  plugin: PluginDefinition,
+  overrides: ReadonlyMap<string, string>,
+  env?: PluginEnvReader,
+): readonly ResolvedPluginSetting[] {
+  return (plugin.settings ?? []).map((setting) => resolveOne(plugin, setting, overrides, env))
+}
+
+export function operatorDisabledPlugins(
+  overrides: ReadonlyMap<string, string>,
+): readonly string[] {
+  const disabled: string[] = []
+
+  for (const [key, value] of overrides) {
+    if (!key.startsWith('plugin.') || !key.endsWith(`.${ENABLED_SUFFIX}`)) continue
+    if (value !== '0') continue
+
+    const pluginKey = key.slice('plugin.'.length, -`.${ENABLED_SUFFIX}`.length)
+    if (pluginKey !== '' && !pluginKey.includes('.')) disabled.push(pluginKey)
+  }
+
+  return disabled.sort()
+}