@adula/kit 0.2.0-alpha.4 → 1.2.0

package/build/src/commands/doctor.js

@@ -2,9 +2,12 @@ import { lstat, readFile, readdir, realpath } from 'node:fs/promises';
 import { isAbsolute, join, relative } from 'node:path';
 import { KIT_VERSION } from '../version.js';
 import { agentAssets, managedRules, digest } from './agent_assets.js';
+import { columnName } from '../resource/define_resource.js';
 // The deployment volume and backup scripts share this application-relative path.
 const UPLOADS_PATH = 'storage/uploads';
 const UPLOADS_WARNING_BYTES = 5_000_000_000;
+/** An event the worker has not published within this age suggests that no worker runs. */
+const OUTBOX_STALE_MS = 60_000;
 async function assertContained(root, path) {
     const resolved = relative(await realpath(root), await realpath(path));
     if (resolved === '..' ||
@@ -259,3 +262,114 @@ export async function diagnose(root, settings, production, env, now = Date.now()
         findings.push(...(await diagnoseUi(root)));
     return findings;
 }
+/** The columns and indexes createResourceTable derives from a definition, one entry each. */
+function tableShape(resource) {
+    const shape = new Map();
+    for (const flag of ['scoped', 'version', 'submittable', 'customFields'])
+        if (resource[flag])
+            shape.set(flag, flag);
+    for (const [key, field] of Object.entries(resource.fields)) {
+        if (field.type === 'hasMany')
+            continue;
+        const column = field.column ?? columnName(key);
+        const traits = [
+            field.type === 'belongsTo' ? `belongsTo ${field.resource}` : field.type,
+            ...(field.required || field.sequence ? ['required'] : []),
+            ...(field.unique ? ['unique'] : []),
+            ...(field.searchable ? ['searchable'] : []),
+        ];
+        shape.set(column, `${column} (${traits.join(', ')})`);
+    }
+    return shape;
+}
+/**
+ * A generated create-migration embeds the definition as it was at scaffold time. While it is
+ * still pending, compare that snapshot with the current resource so the table matches (#20).
+ */
+export function diagnoseResourceSnapshots(pending, resource) {
+    const drift = [];
+    for (const { file, source } of pending) {
+        const embedded = /createResourceTable\([^,]+,\s*(\{[\s\S]*\})\s*\)\s*\}/.exec(source)?.[1];
+        if (!embedded)
+            continue;
+        let snapshot;
+        try {
+            snapshot = JSON.parse(embedded);
+        }
+        catch {
+            continue;
+        }
+        const current = resource(snapshot.name);
+        if (!current)
+            continue;
+        const [before, after] = [tableShape(snapshot), tableShape(current)];
+        const changed = [...new Set([...before.keys(), ...after.keys()])]
+            .filter((key) => before.get(key) !== after.get(key))
+            .map((key) => after.get(key) ?? `without ${before.get(key)}`);
+        if (changed.length)
+            drift.push(`${file} (${snapshot.name}): ${changed.join('; ')}`);
+    }
+    return {
+        check: 'resources.snapshots',
+        status: drift.length ? 'warn' : 'pass',
+        message: drift.length
+            ? `Pending create-migrations differ from their resource definitions; run node ace adula:resource:snapshot <name> (or update the embedded definition) before migration:run: ${drift.join(' | ')}`
+            : 'Pending resource migrations match their definitions',
+    };
+}
+/**
+ * Workflow recipients address roles by their stable key, or for compatibility by
+ * their editable display name. List references that match no role, and those that
+ * only match a display name, which a rename in the roles screen would break (#25).
+ */
+export function diagnoseWorkflowRoles(workflows, roles) {
+    const keys = new Set(roles.flatMap((role) => (typeof role === 'string' || !role.key ? [] : [role.key])));
+    const names = new Set(roles.map((role) => (typeof role === 'string' ? role : role.name)));
+    const missing = [];
+    const byName = [];
+    for (const workflow of workflows)
+        for (const [key, step] of Object.entries(workflow.steps)) {
+            const to = step.type === 'approval' ? step.assignees : step.type === 'notify' ? step.to : null;
+            if (!to || typeof to !== 'object' || !('role' in to) || keys.has(to.role))
+                continue;
+            const reference = `${workflow.name}@${workflow.version}.${key} → "${to.role}"`;
+            if (names.has(to.role))
+                byName.push(reference);
+            else
+                missing.push(reference);
+        }
+    // Plain name lists (older hosts) cannot tell keys from names; only missing roles matter.
+    const keyed = roles.some((role) => typeof role !== 'string');
+    const messages = [
+        ...(missing.length
+            ? [
+                `Workflow steps address roles that match no role key or name; approvals there fail: ${missing.join(', ')}`,
+            ]
+            : []),
+        ...(keyed && byName.length
+            ? [
+                `Workflow steps address roles by display name; give each role a key and address it by key so renaming cannot detach approvers: ${byName.join(', ')}`,
+            ]
+            : []),
+    ];
+    return {
+        check: 'workflows.roles',
+        status: messages.length ? 'warn' : 'pass',
+        message: messages.length
+            ? messages.join(' | ')
+            : 'Every role addressed by a workflow step exists',
+    };
+}
+/** Events wait in the outbox until a worker publishes them; a stale backlog means none runs (#50). */
+export function diagnoseOutbox(health) {
+    const { backlog, oldestAgeMs } = health.outbox;
+    const worker = health.heartbeats.worker.healthy ? 'running' : 'not running (no recent heartbeat)';
+    const stale = backlog > 0 && oldestAgeMs !== null && oldestAgeMs >= OUTBOX_STALE_MS;
+    return {
+        check: 'events.outbox',
+        status: stale ? 'warn' : 'pass',
+        message: stale
+            ? `${backlog} unpublished events, the oldest ${Math.round(oldestAgeMs / 1000)} s old; the worker is ${worker}. Listeners run only while \`node ace adula:worker\` runs`
+            : `No outbox event is older than ${OUTBOX_STALE_MS / 1000} s; the worker is ${worker}`,
+    };
+}

package/build/src/commands/gap_report.d.ts

@@ -1,8 +1,56 @@
+export declare const KIT_ISSUES_URL = "https://github.com/adulash/adula-kit/issues";
+/**
+ * KIT_GAPS.md entry fields, in the order of the kit's gap issue form
+ * (.github/ISSUE_TEMPLATE/gap.yml). `id` is the form field id used to prefill it.
+ */
+export declare const GAP_FIELDS: readonly [{
+    readonly label: "Package";
+    readonly id: "package";
+    readonly required: true;
+}, {
+    readonly label: "Needed by";
+    readonly id: "needed";
+    readonly required: true;
+}, {
+    readonly label: "Tried";
+    readonly id: "tried";
+    readonly required: true;
+}, {
+    readonly label: "Blocked because";
+    readonly id: "blocked";
+    readonly required: true;
+}, {
+    readonly label: "Proposed kit change";
+    readonly id: "proposal";
+    readonly required: true;
+}, {
+    readonly label: "Reproduction";
+    readonly id: "reproduction";
+    readonly required: true;
+}, {
+    readonly label: "Acceptance";
+    readonly id: "acceptance";
+    readonly required: true;
+}, {
+    readonly label: "Workaround";
+    readonly id: "workaround";
+    readonly required: false;
+}];
+export declare const GAPS_TEMPLATE = "# Kit gaps\n\nRecord each limitation of the kit as one entry. Describe the kit capability, not this\nproject: reproduce it on a new application from create-app. Run `node ace adula:gaps report`\nto open the kit's gap form prefilled, then write the issue number in `Issue:`.\n\n<!--\n## GAP-001 \u2014 Short title naming the kit capability\nPackage: @adula/kit 1.0.0\nNeeded by: the kit capability that is missing, stated without project details\nTried: the kit extension points tried\nBlocked because: why none of them works\nProposed kit change: the API, option or fix the kit should offer\nReproduction: steps on a new application from create-app\nAcceptance: the test that proves the gap is closed\nWorkaround: none, or what the project does meanwhile\nIssue:\n-->\n";
+export interface GapEntry {
+    title: string;
+    fields: Record<string, string>;
+    issue: string;
+    missing: string[];
+    url?: string;
+}
 /**
  * Prepares KIT_GAPS.md for sharing with the kit maintainers: e-mails, URLs and
- * IPv4 addresses are masked, and gap titles are listed for a quick review.
+ * IPv4 addresses are masked, gap titles are listed for a quick review, and each
+ * unreported gap gets a link that opens the kit's gap form prefilled. Nothing is sent.
  */
-export declare function gapReport(content: string): {
+export declare function gapReport(content: string, issuesUrl?: string): {
     masked: string;
     titles: string[];
+    gaps: GapEntry[];
 };

package/build/src/commands/gap_report.js

@@ -1,12 +1,110 @@
+export const KIT_ISSUES_URL = 'https://github.com/adulash/adula-kit/issues';
+/**
+ * KIT_GAPS.md entry fields, in the order of the kit's gap issue form
+ * (.github/ISSUE_TEMPLATE/gap.yml). `id` is the form field id used to prefill it.
+ */
+export const GAP_FIELDS = [
+    { label: 'Package', id: 'package', required: true },
+    { label: 'Needed by', id: 'needed', required: true },
+    { label: 'Tried', id: 'tried', required: true },
+    { label: 'Blocked because', id: 'blocked', required: true },
+    { label: 'Proposed kit change', id: 'proposal', required: true },
+    { label: 'Reproduction', id: 'reproduction', required: true },
+    { label: 'Acceptance', id: 'acceptance', required: true },
+    { label: 'Workaround', id: 'workaround', required: false },
+];
+export const GAPS_TEMPLATE = `# Kit gaps
+
+Record each limitation of the kit as one entry. Describe the kit capability, not this
+project: reproduce it on a new application from create-app. Run \`node ace adula:gaps report\`
+to open the kit's gap form prefilled, then write the issue number in \`Issue:\`.
+
+<!--
+## GAP-001 — Short title naming the kit capability
+Package: @adula/kit 1.0.0
+Needed by: the kit capability that is missing, stated without project details
+Tried: the kit extension points tried
+Blocked because: why none of them works
+Proposed kit change: the API, option or fix the kit should offer
+Reproduction: steps on a new application from create-app
+Acceptance: the test that proves the gap is closed
+Workaround: none, or what the project does meanwhile
+Issue:
+-->
+`;
+/** Longest value put in one prefilled field; GitHub rejects very long URLs. */
+const FIELD_LIMIT = 1500;
+const labels = [...GAP_FIELDS.map((field) => field.label), 'Issue'];
+const fieldLine = new RegExp(`^(${labels.join('|')}):\\s*(.*)$`);
+function parseGaps(masked) {
+    const gaps = [];
+    let current;
+    let field;
+    let comment = false;
+    for (const line of masked.split(/\r?\n/)) {
+        if (line.trim().startsWith('<!--'))
+            comment = true;
+        if (comment) {
+            if (line.includes('-->'))
+                comment = false;
+            continue;
+        }
+        const heading = line.match(/^## (GAP-\d+.*)$/);
+        if (heading) {
+            current = { title: heading[1].trim(), fields: {}, issue: '', missing: [] };
+            gaps.push(current);
+            field = undefined;
+            continue;
+        }
+        if (!current)
+            continue;
+        if (line.startsWith('#')) {
+            current = undefined;
+            continue;
+        }
+        const match = line.match(fieldLine);
+        if (match) {
+            field = match[1];
+            if (field === 'Issue')
+                current.issue = match[2].trim();
+            else
+                current.fields[field] = match[2].trim();
+        }
+        else if (field && field !== 'Issue') {
+            current.fields[field] = `${current.fields[field]}\n${line}`.trim();
+        }
+    }
+    return gaps;
+}
+function clip(value) {
+    return value.length > FIELD_LIMIT
+        ? `${value.slice(0, FIELD_LIMIT)}\n… (shortened; copy the rest from the masked report)`
+        : value;
+}
 /**
  * Prepares KIT_GAPS.md for sharing with the kit maintainers: e-mails, URLs and
- * IPv4 addresses are masked, and gap titles are listed for a quick review.
+ * IPv4 addresses are masked, gap titles are listed for a quick review, and each
+ * unreported gap gets a link that opens the kit's gap form prefilled. Nothing is sent.
  */
-export function gapReport(content) {
+export function gapReport(content, issuesUrl = KIT_ISSUES_URL) {
     const masked = content
         .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, '<email>')
         .replace(/https?:\/\/[^\s)]+/g, '<url>')
         .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, '<ip>');
-    const titles = (masked.match(/^## GAP-\d+.*$/gm) ?? []).map((title) => title.replace(/^## /, ''));
-    return { masked, titles };
+    const gaps = parseGaps(masked);
+    for (const gap of gaps) {
+        gap.missing = GAP_FIELDS.filter((field) => field.required && !gap.fields[field.label]).map((field) => field.label);
+        if (gap.issue)
+            continue;
+        const url = new URL(`${issuesUrl}/new`);
+        url.searchParams.set('template', 'gap.yml');
+        url.searchParams.set('title', gap.title.replace(/^GAP-\d+\s*[—–-]?\s*/, ''));
+        for (const field of GAP_FIELDS) {
+            const value = gap.fields[field.label];
+            if (value)
+                url.searchParams.set(field.id, clip(value));
+        }
+        gap.url = url.toString();
+    }
+    return { masked, titles: gaps.map((gap) => gap.title), gaps };
 }

package/build/src/commands/generator.js

@@ -1,7 +1,7 @@
 import { mkdir, readFile, writeFile, access, glob } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { identifier } from '../resource/define_resource.js';
-import { appendMarkedItem } from './source_markers.js';
+import { appendMarkedItem, moduleSource } from './source_markers.js';
 export async function generateResource(root, name, module) {
     identifier(name);
     identifier(module);
@@ -10,7 +10,7 @@ export async function generateResource(root, name, module) {
     const base = resolve(root, 'app/modules', module);
     const title = name.replace(/_/g, ' ');
     const relative = `app/modules/${module}`;
-    const resourceSource = `import { defineResource } from '@adula/kit'\nimport Model from '#modules/${module}/models/${name}'\nimport { validator } from '#modules/${module}/validators/${name}'\n\nexport default defineResource({\n  name: '${name}', label: { ar: '${title}', en: '${title}' }, model: Model, scoped: true,\n  fields: { title: { type: 'string', label: { ar: 'العنوان', en: 'Title' }, required: true, searchable: true } },\n  list: ['title'], form: ['title'], show: ['title'],\n  actions: ['view', 'create', 'update', 'delete'], validator,\n})\n`;
+    const resourceSource = `import { defineResource } from '@adula/kit'\nimport Model from '#modules/${module}/models/${name}'\nimport { validator } from '#modules/${module}/validators/${name}'\n\nexport default defineResource({\n  name: '${name}', label: { ar: '${title}', en: '${title}' },\n  recordLabel: { ar: '${title}', en: '${title}' }, model: Model, scoped: true,\n  fields: { title: { type: 'string', label: { ar: 'العنوان', en: 'Title' }, required: true, searchable: true } },\n  list: ['title'], form: ['title'], show: ['title'],\n  actions: ['view', 'create', 'update', 'delete'], validator,\n})\n`;
     const migration = {
         name,
         scoped: true,
@@ -39,7 +39,7 @@ export async function generateResource(root, name, module) {
     catch (error) {
         if (error.code !== 'ENOENT')
             throw error;
-        current = `// adula:imports\nexport default { name: '${module}', label: { ar: '${module}', en: '${module}' }, dependsOn: [], resources: [/* adula:resources */] }\n`;
+        current = moduleSource(module);
     }
     if (!current.includes('// adula:imports') || !current.includes('/* adula:resources */'))
         throw new Error('Module registration markers are missing; no files were changed');

package/build/src/commands/snapshot.d.ts

@@ -0,0 +1,28 @@
+import type { Resource } from '../resource/types.js';
+/**
+ * The part of a resource definition createResourceTable reads, as a generated
+ * create-migration embeds it. Labels are kept so the migration stays readable.
+ */
+export declare function resourceSnapshot(resource: Pick<Resource, 'name' | 'scoped' | 'version' | 'submittable' | 'customFields' | 'fields'>): {
+    fields: {
+        [k: string]: {
+            sequence?: string | undefined;
+            searchable?: boolean | undefined;
+            unique?: boolean | undefined;
+            required?: boolean | undefined;
+            column?: string | undefined;
+            resource?: string | undefined;
+            type: "string" | "boolean" | "text" | "integer" | "money" | "date" | "datetime" | "json" | "attachment" | "belongsTo" | "user" | "hasMany" | "lookup";
+            label: import("../resource/types.js").Label;
+        };
+    };
+    customFields?: boolean | undefined;
+    submittable?: boolean | undefined;
+    version?: boolean | undefined;
+    name: string;
+    scoped: boolean;
+};
+/** The resource name embedded in a generated create-migration, if the source is one. */
+export declare function embeddedResource(source: string): string | undefined;
+/** Replaces the embedded definition of a generated create-migration (#20). */
+export declare function rewriteResourceSnapshot(source: string, snapshot: ReturnType<typeof resourceSnapshot>): string;

package/build/src/commands/snapshot.js

@@ -0,0 +1,48 @@
+const EMBEDDED = /(createResourceTable\([^,]+,\s*)(\{[\s\S]*\})(\s*\)\s*\})/;
+/**
+ * The part of a resource definition createResourceTable reads, as a generated
+ * create-migration embeds it. Labels are kept so the migration stays readable.
+ */
+export function resourceSnapshot(resource) {
+    return {
+        name: resource.name,
+        scoped: resource.scoped,
+        ...(resource.version ? { version: true } : {}),
+        ...(resource.submittable ? { submittable: true } : {}),
+        ...(resource.customFields ? { customFields: true } : {}),
+        fields: Object.fromEntries(Object.entries(resource.fields)
+            .filter(([, field]) => field.type !== 'hasMany')
+            .map(([key, field]) => [
+            key,
+            {
+                type: field.type,
+                label: field.label,
+                ...(field.type === 'belongsTo' ? { resource: field.resource } : {}),
+                ...(field.column ? { column: field.column } : {}),
+                ...(field.required ? { required: true } : {}),
+                ...(field.unique ? { unique: true } : {}),
+                ...(field.searchable ? { searchable: true } : {}),
+                ...(field.sequence ? { sequence: field.sequence } : {}),
+            },
+        ])),
+    };
+}
+/** The resource name embedded in a generated create-migration, if the source is one. */
+export function embeddedResource(source) {
+    const embedded = EMBEDDED.exec(source)?.[2];
+    if (!embedded)
+        return undefined;
+    try {
+        const parsed = JSON.parse(embedded);
+        return typeof parsed?.name === 'string' ? parsed.name : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Replaces the embedded definition of a generated create-migration (#20). */
+export function rewriteResourceSnapshot(source, snapshot) {
+    if (embeddedResource(source) !== snapshot.name)
+        throw new Error(`The migration does not embed the ${snapshot.name} definition`);
+    return source.replace(EMBEDDED, (_, before, _old, after) => `${before}${JSON.stringify(snapshot, null, 2)}${after}`);
+}

package/build/src/commands/source_markers.d.ts

@@ -1,2 +1,11 @@
-/** Append to a marked literal array, including when the last item has no trailing comma. */
+/**
+ * Append to a marked literal array and rewrite it in the multi-line form Prettier keeps stable:
+ * one item per line with a trailing comma and the marker last. Single-line arrays written by
+ * earlier generators (`[a, /* marker *\/]`, `[a /* marker *\/]`) are normalized the same way.
+ */
 export declare function appendMarkedItem(source: string, marker: string, expression: string): string;
+/** A new module definition, already in the project's Prettier layout. */
+export declare function moduleSource(name: string, options?: {
+    reference?: boolean;
+    typed?: boolean;
+}): string;

package/build/src/commands/source_markers.js

@@ -1,9 +1,41 @@
-/** Append to a marked literal array, including when the last item has no trailing comma. */
+/**
+ * Append to a marked literal array and rewrite it in the multi-line form Prettier keeps stable:
+ * one item per line with a trailing comma and the marker last. Single-line arrays written by
+ * earlier generators (`[a, /* marker *\/]`, `[a /* marker *\/]`) are normalized the same way.
+ */
 export function appendMarkedItem(source, marker, expression) {
     const offset = source.indexOf(marker);
     if (offset < 0 || source.indexOf(marker, offset + marker.length) >= 0)
         throw new Error(`Expected one registration marker: ${marker}`);
-    const before = source.slice(0, offset).trimEnd();
-    const separator = /[\[,]$/.test(before) ? '' : ', ';
-    return source.replace(marker, `${separator}${expression}, ${marker}`);
+    const open = source.lastIndexOf('[', offset);
+    const close = source.indexOf(']', offset + marker.length);
+    if (open < 0 || close < 0)
+        throw new Error(`Registration marker ${marker} must be inside an array`);
+    const listed = source.slice(open + 1, offset);
+    if (/[()[\]{}'"`]|\/\/|\/\*/.test(listed) || source.slice(offset + marker.length, close).trim())
+        throw new Error(`Registration list around ${marker} is not a plain list; add ${expression} by hand`);
+    const items = listed
+        .split(',')
+        .map((item) => item.trim())
+        .filter(Boolean);
+    const lineStart = source.lastIndexOf('\n', open) + 1;
+    const indent = /^[ \t]*/.exec(source.slice(lineStart, open))[0];
+    const inner = `${indent}  `;
+    const lines = [...items, expression].map((item) => `${inner}${item},\n`).join('');
+    return `${source.slice(0, open)}[\n${lines}${inner}${marker}\n${indent}]${source.slice(close + 1)}`;
+}
+/** A new module definition, already in the project's Prettier layout. */
+export function moduleSource(name, options = {}) {
+    return [
+        ...(options.typed ? ["import type { Module } from '@adula/kit'"] : []),
+        '// adula:imports',
+        'export default {',
+        `  name: '${name}',`,
+        `  label: { ar: '${name}', en: '${name}' },`,
+        ...(options.reference === undefined ? [] : [`  reference: ${options.reference},`]),
+        '  dependsOn: [],',
+        '  resources: [/* adula:resources */],',
+        `}${options.typed ? ' satisfies Module' : ''}`,
+        '',
+    ].join('\n');
 }

package/build/src/core/administration_guard.js

@@ -1,4 +1,5 @@
 import { buildAbility } from '../auth/ability.js';
+import { resolveActorConditions } from '../auth/conditions.js';
 import { KitError } from '../admin/errors.js';
 /** Same CASL decision as the admin middleware, with fresh rows inside the transaction. */
 async function administrators(db) {
@@ -16,7 +17,8 @@ async function administrators(db) {
             subject: row.subject,
             action: row.action,
             inverted: row.inverted,
-            conditions: row.conditions ?? undefined,
+            // Only subject 'all' is read here, so no field accepts the placeholder.
+            conditions: resolveActorConditions(row.conditions ?? undefined, Number(row.user_id), () => false),
             fields: row.fields ?? undefined,
         });
         users.set(row.user_id, rules);

package/build/src/core/message_templates.d.ts

@@ -0,0 +1,83 @@
+import type { Knex } from 'knex';
+import { type NotificationTarget } from '../services/settings.js';
+export type TemplateDefinition = {
+    label: string;
+    subject: string;
+    body: string;
+    /** Variables available as {{name}}; unknown placeholders are refused on edit. */
+    variables: string[];
+    /** Whether notifications from this template are also delivered by e-mail. */
+    mail: boolean;
+};
+export type MessageTemplate = TemplateDefinition & {
+    key: string;
+    customized: boolean;
+    updatedAt: string | null;
+};
+export type RenderedMessage = {
+    subject: string;
+    body: string;
+    mail: boolean;
+};
+/**
+ * Package-owned defaults. Projects edit wording in the message_templates table;
+ * an upgrade can change a default without overwriting a project's edit.
+ */
+export declare const DEFAULT_TEMPLATES: Record<string, TemplateDefinition>;
+export declare function renderTemplate(text: string, variables: Record<string, unknown>): string;
+/** Message templates: package defaults plus per-deployment overrides edited by administrators. */
+export declare class MessageTemplates {
+    private db;
+    private definitions;
+    constructor(db: Knex, definitions?: Record<string, TemplateDefinition>);
+    list(): Promise<MessageTemplate[]>;
+    render(key: string, variables: Record<string, unknown>, db?: Knex): Promise<RenderedMessage>;
+    update(key: string, input: {
+        subject: unknown;
+        body: unknown;
+        mail?: unknown;
+    }, actorId: number): Promise<void>;
+    reset(key: string): Promise<void>;
+    /** Example output with sample values, for the editor preview. */
+    preview(key: string, input: {
+        subject: string;
+        body: string;
+    }): {
+        subject: string;
+        body: string;
+    };
+    private definition;
+}
+/**
+ * Inserts a templated notification in the caller's transaction. Templates with
+ * mail enabled mark the row for the mail delivery worker (deliverNotificationMail).
+ */
+export declare function notifyWithTemplate(db: Knex, userId: number, key: string, variables: Record<string, unknown>, templates?: MessageTemplates, target?: NotificationTarget | null): Promise<void>;
+export type MailSender = (message: {
+    to: string;
+    name: string | null;
+    subject: string;
+    text: string;
+    /** The record the notification is about; build an absolute link from the application URL. */
+    target?: NotificationTarget | null;
+}) => Promise<void>;
+/**
+ * Delivers pending notification e-mails. Rows are claimed with SKIP LOCKED so
+ * several workers never send the same message; failures are retried three times.
+ */
+export declare function deliverNotificationMail(db: Knex, send: MailSender, limit?: number): Promise<{
+    sent: number;
+    failed: number;
+}>;
+export type NotificationSignal = {
+    userId: number;
+    id: number;
+};
+/**
+ * Holds one database connection that LISTENs for committed notifications and
+ * calls onSignal for each. Reconnects after connection loss. Returns a stop function.
+ */
+export declare function listenForNotifications(db: Knex, onSignal: (signal: NotificationSignal) => void, options?: {
+    retryMs?: number;
+    onError?: (error: unknown) => void;
+}): () => Promise<void>;