@adula/kit 1.0.0 → 1.2.0

package/build/src/integrations/inbound_webhooks.js

@@ -0,0 +1,276 @@
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { KitError } from '../admin/errors.js';
+/** Inbound payloads above this size are refused before verification. */
+export const INBOUND_BODY_LIMIT = 1024 * 1024;
+/** Stored deliveries older than this are removed by pruneDeliveries(). */
+export const INBOUND_RETENTION_DAYS = 90;
+const HEADER = /^[a-z0-9][a-z0-9-]{0,99}$/;
+const KEY = /^[a-z][a-z0-9_]{0,59}$/;
+/** The domain event an inbound delivery raises: inbound.<source>.<event>. */
+export function inboundEventName(source, event) {
+    const safe = event
+        .toLowerCase()
+        .replace(/[^a-z0-9_]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .slice(0, 60) || 'received';
+    return `inbound.${source}.${safe}`;
+}
+/**
+ * Signed inbound webhooks (#30). Administrators create a source per sender (for example
+ * a Git host) and give it the generated secret. POST /webhooks/in/<key> verifies an
+ * HMAC over the raw body in constant time (X-Hub-Signature-256 by default), stores each
+ * delivery once by the sender's delivery id and raises inbound.<key>.<event> through the
+ * outbox, so module listeners run idempotently with retries and a delivery history.
+ */
+export class InboundWebhooks {
+    db;
+    secrets;
+    constructor(db, secrets) {
+        this.db = db;
+        this.secrets = secrets;
+    }
+    async list() {
+        const rows = await this.db('inbound_sources').orderBy('id');
+        return rows.map((row) => this.present(row));
+    }
+    /** Creates a source and returns its secret once; it is never shown again. */
+    async create(actorId, input) {
+        const values = this.validate(input, true);
+        if (await this.db('inbound_sources').where('key', values.key).first('id'))
+            throw new KitError(409, 'E_INBOUND_KEY', 'يوجد مصدر بهذا المفتاح');
+        const secret = randomBytes(32).toString('base64url');
+        const [row] = await this.db('inbound_sources')
+            .insert({ ...values, secret: this.secrets.seal(secret), created_by: actorId })
+            .returning('*');
+        return { source: this.present(row), secret };
+    }
+    /**
+     * Updates the fields given (name, algorithm, headers, body deduplication, state); fields
+     * left out keep their stored values. The key and secret stay.
+     */
+    async update(id, input) {
+        const row = await this.db('inbound_sources').where('id', id).first();
+        if (!row)
+            throw new KitError(404, 'E_INBOUND_NOT_FOUND', 'المصدر غير موجود');
+        const given = (value) => value !== undefined && value !== null;
+        const algorithm = given(input.algorithm) ? input.algorithm : row.algorithm;
+        // A new algorithm without a new prefix keeps a default prefix in step with it.
+        const prefix = given(input.signaturePrefix)
+            ? input.signaturePrefix
+            : given(input.algorithm) && row.signature_prefix === `${row.algorithm}=`
+                ? `${String(algorithm)}=`
+                : row.signature_prefix;
+        const values = this.validate({
+            name: given(input.name) ? input.name : row.name,
+            algorithm,
+            signaturePrefix: prefix,
+            signatureHeader: given(input.signatureHeader)
+                ? input.signatureHeader
+                : row.signature_header,
+            eventHeader: given(input.eventHeader) ? input.eventHeader : row.event_header,
+            deliveryHeader: given(input.deliveryHeader) ? input.deliveryHeader : row.delivery_header,
+            dedupeBody: given(input.dedupeBody) ? input.dedupeBody : row.dedupe_body,
+        }, false);
+        delete values.key;
+        if (given(input.active) && typeof input.active !== 'boolean')
+            throw new KitError(422, 'E_INBOUND_ACTIVE', 'حالة الاستقبال يجب أن تكون صحيحاً أو خطأ');
+        await this.db('inbound_sources')
+            .where('id', id)
+            .update({
+            ...values,
+            active: typeof input.active === 'boolean' ? input.active : row.active,
+            updated_at: this.db.fn.now(),
+        });
+    }
+    /** Issues a new secret; the old one stops verifying at once. */
+    async rotate(id) {
+        const secret = randomBytes(32).toString('base64url');
+        const updated = await this.db('inbound_sources')
+            .where('id', id)
+            .update({ secret: this.secrets.seal(secret), updated_at: this.db.fn.now() });
+        if (!updated)
+            throw new KitError(404, 'E_INBOUND_NOT_FOUND', 'المصدر غير موجود');
+        return secret;
+    }
+    async remove(id) {
+        const removed = await this.db('inbound_sources').where('id', id).del();
+        if (!removed)
+            throw new KitError(404, 'E_INBOUND_NOT_FOUND', 'المصدر غير موجود');
+    }
+    /**
+     * Verifies and records one delivery. Unknown or inactive sources and bad signatures
+     * are refused without storing anything; a repeated delivery id is acknowledged once.
+     */
+    async receive(key, request) {
+        const body = Buffer.isBuffer(request.body) ? request.body : Buffer.from(request.body ?? '');
+        if (body.length > INBOUND_BODY_LIMIT)
+            throw new KitError(413, 'E_INBOUND_TOO_LARGE', 'Payload too large');
+        const source = typeof key === 'string' && KEY.test(key)
+            ? await this.db('inbound_sources').where({ key, active: true }).first()
+            : undefined;
+        if (!source)
+            throw new KitError(404, 'E_INBOUND_NOT_FOUND', 'Unknown webhook source');
+        const header = (name) => {
+            const value = request.headers[name.toLowerCase()];
+            return Array.isArray(value) ? value[0] : value;
+        };
+        // GitHub offers form-encoded deliveries by default; only the JSON body is supported.
+        const contentType = (header('content-type') ?? '').toLowerCase();
+        if (contentType && !contentType.startsWith('application/json'))
+            throw new KitError(415, 'E_INBOUND_CONTENT_TYPE', 'Set the webhook content type to application/json');
+        const secret = this.secrets.open(String(source.secret));
+        const signature = header(source.signature_header) ?? '';
+        const expected = `${source.signature_prefix}${createHmac(source.algorithm, secret ?? randomBytes(32))
+            .update(body)
+            .digest('hex')}`;
+        const given = Buffer.from(signature);
+        const wanted = Buffer.from(expected);
+        if (!secret || given.length !== wanted.length || !timingSafeEqual(given, wanted))
+            throw new KitError(401, 'E_INBOUND_SIGNATURE', 'Invalid signature');
+        let payload;
+        try {
+            payload = JSON.parse(body.toString('utf8') || 'null');
+        }
+        catch {
+            throw new KitError(400, 'E_INBOUND_BODY', 'The body must be JSON');
+        }
+        const eventName = (header(source.event_header) ?? 'received').slice(0, 100);
+        // Senders without a delivery id are deduplicated by the body itself.
+        const deliveryId = (header(source.delivery_header) ?? `sha256:${createHash('sha256').update(body).digest('hex')}`).slice(0, 200);
+        const event = inboundEventName(String(source.key), eventName);
+        return this.db.transaction(async (trx) => {
+            const eventId = randomUUID();
+            const [stored] = await trx('inbound_deliveries')
+                .insert({
+                id: randomUUID(),
+                source_id: source.id,
+                delivery_id: deliveryId,
+                // Senders sign the body only: a captured body replayed with another delivery id or
+                // event header is refused while the source deduplicates bodies (the default).
+                body_key: source.dedupe_body ? createHash('sha256').update(body).digest('hex') : null,
+                event: eventName,
+                payload: JSON.stringify(payload),
+                event_id: eventId,
+            })
+                // Either the delivery id or the body key already seen for this source.
+                .onConflict()
+                .ignore()
+                .returning('id');
+            if (!stored)
+                return { delivery: deliveryId, event, duplicate: true };
+            await trx('inbound_sources').where('id', source.id).update({ last_received_at: trx.fn.now() });
+            await trx('outbox').insert({
+                id: eventId,
+                event,
+                payload: JSON.stringify(this.envelope(source.key, deliveryId, eventName, payload)),
+            });
+            return { delivery: deliveryId, event, duplicate: false };
+        });
+    }
+    async deliveries(sourceId, limit = 50) {
+        const source = await this.db('inbound_sources').where('id', sourceId).first('key');
+        if (!source)
+            throw new KitError(404, 'E_INBOUND_NOT_FOUND', 'المصدر غير موجود');
+        const rows = await this.db('inbound_deliveries')
+            .where('source_id', sourceId)
+            .orderBy('received_at', 'desc')
+            .limit(Math.min(100, Math.max(1, limit)));
+        return rows.map((row) => ({
+            id: String(row.id),
+            deliveryId: String(row.delivery_id),
+            event: String(row.event),
+            eventName: inboundEventName(String(source.key), String(row.event)),
+            dispatches: Number(row.dispatches),
+            receivedAt: new Date(row.received_at).toISOString(),
+        }));
+    }
+    /**
+     * Raises a stored delivery again as a new domain event, for listeners that failed or
+     * were added later. Listeners must be idempotent on the delivery id.
+     */
+    async redispatch(deliveryId) {
+        if (typeof deliveryId !== 'string' ||
+            !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(deliveryId))
+            throw new KitError(404, 'E_INBOUND_DELIVERY_NOT_FOUND', 'الاستلام غير موجود');
+        return this.db.transaction(async (trx) => {
+            const row = await trx('inbound_deliveries as d')
+                .join('inbound_sources as s', 's.id', 'd.source_id')
+                .where('d.id', deliveryId)
+                .forUpdate('d')
+                .first('d.*', 's.key');
+            if (!row)
+                throw new KitError(404, 'E_INBOUND_DELIVERY_NOT_FOUND', 'الاستلام غير موجود');
+            const eventId = randomUUID();
+            await trx('outbox').insert({
+                id: eventId,
+                event: inboundEventName(String(row.key), String(row.event)),
+                payload: JSON.stringify(this.envelope(String(row.key), String(row.delivery_id), String(row.event), row.payload)),
+            });
+            await trx('inbound_deliveries')
+                .where('id', row.id)
+                .update({ event_id: eventId, dispatches: Number(row.dispatches) + 1 });
+        });
+    }
+    /** Removes stored deliveries older than the retention period (90 days by default). */
+    async pruneDeliveries(days = INBOUND_RETENTION_DAYS) {
+        if (!Number.isSafeInteger(days) || days < 1)
+            throw new KitError(422, 'E_INBOUND_RETENTION', 'Retention must be at least one day');
+        return this.db('inbound_deliveries')
+            .where('received_at', '<', this.db.raw(`now() - (? * interval '1 day')`, [days]))
+            .delete();
+    }
+    envelope(source, delivery, event, body) {
+        return { source, delivery, event, body };
+    }
+    validate(input, creating) {
+        const text = (value) => (typeof value === 'string' ? value.trim() : '');
+        const key = text(input.key);
+        if (creating && !KEY.test(key))
+            throw new KitError(422, 'E_INBOUND_KEY', 'المفتاح حروف إنجليزية صغيرة وأرقام وشرطة سفلية ويبدأ بحرف (مثل github)');
+        const name = text(input.name);
+        if (!name || name.length > 100)
+            throw new KitError(422, 'E_INBOUND_NAME', 'الاسم مطلوب ولا يتجاوز 100 حرف');
+        const algorithm = input.algorithm === undefined ? 'sha256' : input.algorithm;
+        if (algorithm !== 'sha256' && algorithm !== 'sha512')
+            throw new KitError(422, 'E_INBOUND_ALGORITHM', 'الخوارزمية sha256 أو sha512');
+        const headerValue = (value, fallback) => {
+            const header = value === undefined || value === '' ? fallback : text(value).toLowerCase();
+            if (!HEADER.test(header))
+                throw new KitError(422, 'E_INBOUND_HEADER', `اسم ترويسة غير صالح: ${String(value)}`);
+            return header;
+        };
+        const dedupeBody = input.dedupeBody === undefined ? true : input.dedupeBody;
+        if (typeof dedupeBody !== 'boolean')
+            throw new KitError(422, 'E_INBOUND_DEDUPE', 'منع تكرار المحتوى يجب أن يكون صحيحاً أو خطأ');
+        const prefix = input.signaturePrefix === undefined ? `${algorithm}=` : text(input.signaturePrefix);
+        if (prefix.length > 20 || /[^\x21-\x7e]/.test(prefix))
+            throw new KitError(422, 'E_INBOUND_HEADER', 'بادئة التوقيع غير صالحة');
+        return {
+            key,
+            name,
+            algorithm,
+            signature_header: headerValue(input.signatureHeader, `x-hub-signature-${algorithm === 'sha256' ? '256' : '512'}`),
+            signature_prefix: prefix,
+            event_header: headerValue(input.eventHeader, 'x-github-event'),
+            delivery_header: headerValue(input.deliveryHeader, 'x-github-delivery'),
+            dedupe_body: dedupeBody,
+        };
+    }
+    present(row) {
+        return {
+            id: Number(row.id),
+            key: String(row.key),
+            name: String(row.name),
+            algorithm: row.algorithm,
+            signatureHeader: String(row.signature_header),
+            signaturePrefix: String(row.signature_prefix),
+            eventHeader: String(row.event_header),
+            deliveryHeader: String(row.delivery_header),
+            dedupeBody: Boolean(row.dedupe_body),
+            active: Boolean(row.active),
+            createdAt: new Date(row.created_at).toISOString(),
+            lastReceivedAt: row.last_received_at ? new Date(row.last_received_at).toISOString() : null,
+            path: `/webhooks/in/${row.key}`,
+        };
+    }
+}

package/build/src/integrations/openapi.js

@@ -20,6 +20,8 @@ function fieldSchema(field, mode, registry) {
             return { description };
         case 'belongsTo':
             return { type: 'integer', description: `${description} → ${field.resource}` };
+        case 'user':
+            return { type: 'integer', description: `${description} → user id (related: id, fullName)` };
         case 'lookup':
             return { type: 'string', description: `${description} (lookup group ${field.group})` };
         case 'attachment':
@@ -89,14 +91,14 @@ function schemas(resource, registry) {
                 key,
                 nullable(fieldSchema(resource.fields[key], 'write', registry), Boolean(resource.fields[key].required)),
             ])),
-            ...(resource.scoped ? { orgUnitId: { type: 'integer' } } : {}),
+            ...(resource.scoped && !resource.scope ? { orgUnitId: { type: 'integer' } } : {}),
             ...(resource.version
                 ? { version: { type: 'integer', description: 'Required on update (optimistic locking)' } }
                 : {}),
         },
         required: [
             ...writable.filter((key) => resource.fields[key].required),
-            ...(resource.scoped ? ['orgUnitId'] : []),
+            ...(resource.scoped && !resource.scope ? ['orgUnitId'] : []),
         ],
     };
     return { read, input };
@@ -214,6 +216,71 @@ export function openApiDocument(registry, options) {
                 parameters: [idParam],
                 responses: { 200: one('Deleted'), 403: error, 404: error, 409: error },
             };
+        if (allowed.has('view'))
+            paths[`${base}/resources/${resource.name}/aggregate`] = {
+                get: {
+                    tags: [tag],
+                    summary: `Count and total ${resource.label.en} by group`,
+                    description: 'Only records the token may view are counted; grouped, totalled and filtered fields must be readable without conditions.',
+                    parameters: [
+                        {
+                            name: 'groupBy',
+                            in: 'query',
+                            description: 'Up to three comma-separated fields',
+                            schema: { type: 'string' },
+                        },
+                        {
+                            name: 'sum',
+                            in: 'query',
+                            description: 'Comma-separated integer or money fields',
+                            schema: { type: 'string' },
+                        },
+                        {
+                            name: 'where',
+                            in: 'query',
+                            description: 'JSON conditions ($eq, $ne, $in, $lt, $gt, $like)',
+                            schema: { type: 'string' },
+                        },
+                        { name: 'search', in: 'query', schema: { type: 'string' } },
+                    ],
+                    responses: {
+                        200: {
+                            description: 'Groups (at most 1000)',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        properties: {
+                                            data: {
+                                                type: 'object',
+                                                properties: {
+                                                    truncated: { type: 'boolean' },
+                                                    rows: {
+                                                        type: 'array',
+                                                        items: {
+                                                            type: 'object',
+                                                            properties: {
+                                                                group: { type: 'object' },
+                                                                count: { type: 'integer' },
+                                                                sum: {
+                                                                    type: 'object',
+                                                                    additionalProperties: { type: ['string', 'null'] },
+                                                                },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        403: error,
+                        422: error,
+                    },
+                },
+            };
         if (Object.keys(collection).length)
             paths[`${base}/resources/${resource.name}`] = collection;
         if (Object.keys(item).length)

package/build/src/integrations/print.js

@@ -20,6 +20,7 @@ function text(field, value, input) {
         }
         case 'lookup':
             return (input.lookups?.[field.key]?.find((option) => option.value === value)?.label ?? String(value));
+        case 'user':
         case 'belongsTo': {
             const related = input.related?.[field.key]?.find((row) => row.id === value);
             const label = related ? Object.entries(related).find(([key]) => key !== 'id')?.[1] : null;

package/build/src/resource/define_resource.js

@@ -1,3 +1,4 @@
+import { assertTitle } from '../admin/record_title.js';
 export function identifier(value) {
     if (!/^[a-z][a-z0-9_]*$/.test(value))
         throw new Error(`Unsafe SQL identifier: ${value}`);
@@ -20,6 +21,9 @@ export function defineResource(input) {
         throw new Error(`${input.name}: scoped must be explicit`);
     if (!input.label.ar || !input.label.en)
         throw new Error('Bilingual labels are required');
+    for (const optional of [input.recordLabel, input.createLabel])
+        if (optional && (!optional.ar || !optional.en))
+            throw new Error(`${input.name}: recordLabel and createLabel need Arabic and English`);
     for (const [key, field] of Object.entries(input.fields)) {
         columnName(key);
         identifier(field.column ?? columnName(key));
@@ -50,6 +54,14 @@ export function defineResource(input) {
             if (!(key in input.fields))
                 throw new Error(`Unknown field: ${key}`);
     }
+    if (input.scope) {
+        const parent = input.fields[input.scope.from];
+        if (!input.scoped)
+            throw new Error(`${input.name}: scope.from requires scoped: true`);
+        if (parent?.type !== 'belongsTo' || !parent.required)
+            throw new Error(`${input.name}: scope.from must name a required belongsTo field`);
+    }
+    assertTitle(input);
     if (!input.submittable && input.actions.some((a) => ['submit', 'cancel', 'amend'].includes(a)))
         throw new Error('Document actions require submittable');
     return Object.freeze({ ...input, version: input.version ?? input.submittable ?? false });

package/build/src/resource/registry.d.ts

@@ -3,6 +3,7 @@ export declare class ResourceRegistry {
     #private;
     register(modules: readonly Module[]): this;
     get(name: string): Resource;
+    has(name: string): boolean;
     all(): Resource[];
     owner(name: string): string;
     modules(): Module[];

package/build/src/resource/registry.js

@@ -20,7 +20,37 @@ export class ResourceRegistry {
                 next.#owners.set(resource.name, module.name);
             }
         }
+        const lookupKeys = new Set();
+        const roleKeys = new Set();
+        for (const module of next.#modules.values()) {
+            for (const [group, rows] of Object.entries(module.lookups ?? {})) {
+                identifier(group);
+                for (const row of rows) {
+                    if (typeof row.key !== 'string' || !row.key.trim() || row.key.length > 255)
+                        throw new Error(`Module ${module.name}: invalid lookup key in ${group}`);
+                    if (!row.label?.ar || !row.label?.en)
+                        throw new Error(`Module ${module.name}: lookup ${group}.${row.key} needs bilingual labels`);
+                    if (lookupKeys.has(`${group}\u0000${row.key}`))
+                        throw new Error(`Duplicate lookup: ${group}.${row.key}`);
+                    lookupKeys.add(`${group}\u0000${row.key}`);
+                }
+            }
+            for (const role of module.defaultRoles ?? []) {
+                if (!/^[a-z][a-z0-9_]{0,99}$/.test(role.key))
+                    throw new Error(`Module ${module.name}: invalid role key ${role.key}`);
+                if (roleKeys.has(role.key))
+                    throw new Error(`Duplicate default role: ${role.key}`);
+                if (!role.name?.trim())
+                    throw new Error(`Module ${module.name}: role ${role.key} needs a name`);
+                roleKeys.add(role.key);
+            }
+        }
         for (const resource of next.all()) {
+            if (resource.scope) {
+                const field = resource.fields[resource.scope.from];
+                if (field.type === 'belongsTo' && !next.get(field.resource).scoped)
+                    throw new Error(`${resource.name}: scope.from must reference a scoped resource`);
+            }
             for (const field of Object.values(resource.fields)) {
                 if (field.type !== 'belongsTo' && field.type !== 'hasMany')
                     continue;
@@ -46,6 +76,9 @@ export class ResourceRegistry {
             throw new Error(`Unknown resource: ${name}`);
         return resource;
     }
+    has(name) {
+        return this.#resources.has(name);
+    }
     all() {
         return [...this.#resources.values()];
     }

package/build/src/resource/types.d.ts

@@ -1,6 +1,7 @@
 import type { Knex } from 'knex';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
 import type { WorkflowDefinition } from '../workflows/define_workflow.js';
+import type { Conditions } from '../auth/conditions.js';
 export type Label = {
     ar: string;
     en: string;
@@ -36,6 +37,13 @@ export type Field = {
 } | {
     type: 'belongsTo';
     resource: string;
+}
+/**
+ * A user of this deployment (foreign key to users). Choices are active members of
+ * the record's organization unit or its ancestors; readers see only the display name.
+ */
+ | {
+    type: 'user';
 } | {
     type: 'hasMany';
     resource: string;
@@ -47,9 +55,26 @@ export type Field = {
 });
 export type Resource = {
     name: string;
+    /** The list heading, usually plural (for example «الحسابات»). */
     label: Label;
+    /**
+     * The singular record noun (for example «حساب»). Generated pages say «إضافة حساب»
+     * instead of the generic «إضافة سجل».
+     */
+    recordLabel?: Label;
+    /** Full create-button text when «إضافة <recordLabel>» does not fit (for example «مهمة جديدة»). */
+    createLabel?: Label;
     model: LucidModel;
     scoped: boolean;
+    /**
+     * The organization unit of a scoped record follows a required belongsTo parent, for
+     * example a clinic follows its facility. The unit is copied from the parent before
+     * authorization, the actor must be able to view the parent, and the form has no unit
+     * picker. `ResourceService.rehome` moves the children after the parent moves.
+     */
+    scope?: {
+        from: string;
+    };
     submittable?: boolean;
     version?: boolean;
     customFields?: boolean;
@@ -59,6 +84,12 @@ export type Resource = {
     show: readonly string[];
     serialize?: readonly string[];
     hidden?: readonly string[];
+    /**
+     * Fields that name a record wherever it is referenced: relation cells and pickers,
+     * "My tasks" and the approvals inbox. Joined with « · ». Defaults to the first
+     * sequence field and the first text field in `list`.
+     */
+    title?: readonly string[];
     actions: readonly Action[];
     validator: {
         validate(data: unknown): Promise<RecordData>;
@@ -73,6 +104,27 @@ export type HookContext = {
     userId: number;
     action: Action;
 };
+/** A changeable list value a module needs before its records can be saved. */
+export type ModuleLookup = {
+    key: string;
+    label: Label;
+    sort?: number;
+};
+/** A role a module ships; its rules go through the same validation as the roles screen. */
+export type ModuleRole = {
+    /** Stable key that workflows address ({ role: key }); see roles.key. */
+    key: string;
+    /** Arabic display name; administrators may rename it later. */
+    name: string;
+    permissionLevel?: number;
+    rules: readonly {
+        subject: string;
+        action: string;
+        inverted?: boolean;
+        conditions?: Conditions | null;
+        fields?: string[] | null;
+    }[];
+};
 export type Module = {
     name: string;
     reference?: boolean;
@@ -81,12 +133,23 @@ export type Module = {
     resources: readonly Resource[];
     /** Versioned workflows of this module's submittable resources (phase 4). */
     workflows?: readonly WorkflowDefinition[];
+    /**
+     * Lookup rows by group. adula:install inserts missing rows and never changes or
+     * removes existing ones, so administrator edits survive upgrades.
+     */
+    lookups?: Readonly<Record<string, readonly ModuleLookup[]>>;
+    /**
+     * Roles created by adula:install when no role has their key yet. An existing role
+     * is never modified, so administrators own every role after installation.
+     */
+    defaultRoles?: readonly ModuleRole[];
 };
-export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize'> & {
+export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize' | 'title'> & {
     fields: F;
     list: readonly (keyof F & string)[];
     form: readonly (keyof F & string)[];
     show: readonly (keyof F & string)[];
     hidden?: readonly (keyof F & string)[];
     serialize?: readonly (keyof F & string)[];
+    title?: readonly (keyof F & string)[];
 };

package/build/src/resource/values.js

@@ -48,8 +48,9 @@ export function fieldValue(field, value) {
         }
         case 'integer':
         case 'belongsTo':
+        case 'user':
             if (!Number.isInteger(value) ||
-                Number(value) < (field.type === 'belongsTo' ? 1 : -2147483648) ||
+                Number(value) < (field.type === 'integer' ? -2147483648 : 1) ||
                 Number(value) > 2147483647)
                 throw new Error('Expected a PostgreSQL integer');
             return value;

package/build/src/services/settings.d.ts

@@ -6,4 +6,16 @@ export declare class Settings {
     set(key: string, value: unknown, scope?: string, scopeId?: string): Promise<void>;
 }
 export declare function sequence(trx: Knex.Transaction, key: string): Promise<string>;
-export declare function notify(db: Knex, userId: number, title: string, body: string): Promise<void>;
+/** The record a notification is about; opening the notification opens the record. */
+export type NotificationTarget = {
+    resource: string;
+    recordId: number;
+};
+export declare function targetColumns(target?: NotificationTarget | null): {
+    resource?: undefined;
+    record_id?: undefined;
+} | {
+    resource: string;
+    record_id: number;
+};
+export declare function notify(db: Knex, userId: number, title: string, body: string, target?: NotificationTarget | null): Promise<void>;

package/build/src/services/settings.js

@@ -18,6 +18,13 @@ export async function sequence(trx, key) {
     const result = await trx.raw('INSERT INTO sequences (key,value) VALUES (?,1) ON CONFLICT (key) DO UPDATE SET value=sequences.value+1 RETURNING value', [key]);
     return `${key}-${String(result.rows[0].value).padStart(6, '0')}`;
 }
-export async function notify(db, userId, title, body) {
-    await db('notifications').insert({ user_id: userId, title, body });
+export function targetColumns(target) {
+    if (!target)
+        return {};
+    if (!/^[a-z][a-z0-9_]*$/.test(target.resource) || !Number.isSafeInteger(target.recordId))
+        throw new Error('Invalid notification target');
+    return { resource: target.resource, record_id: target.recordId };
+}
+export async function notify(db, userId, title, body, target) {
+    await db('notifications').insert({ user_id: userId, title, body, ...targetColumns(target) });
 }