@adula/kit 0.2.0-alpha.4 → 1.2.0

package/build/src/core/message_templates.js

@@ -0,0 +1,293 @@
+import { KitError } from '../admin/errors.js';
+import { targetColumns } from '../services/settings.js';
+/**
+ * Package-owned defaults. Projects edit wording in the message_templates table;
+ * an upgrade can change a default without overwriting a project's edit.
+ */
+export const DEFAULT_TEMPLATES = {
+    'comment.mentioned': {
+        label: 'إشارة في تعليق',
+        subject: 'أشار إليك {{author}}',
+        body: 'في {{resource}} #{{id}}: {{excerpt}}',
+        variables: ['author', 'resource', 'id', 'excerpt'],
+        mail: true,
+    },
+    'comment.created': {
+        label: 'تعليق على سجل تتابعه',
+        subject: 'تعليق جديد على {{resource}} #{{id}}',
+        body: '{{author}}: {{excerpt}}',
+        variables: ['author', 'resource', 'id', 'excerpt'],
+        mail: false,
+    },
+    'record.changed': {
+        label: 'تغيير سجل تتابعه',
+        subject: '{{change}} {{resource}} #{{id}}',
+        body: 'سجل تتابعه تغيّر.',
+        variables: ['change', 'resource', 'id'],
+        mail: false,
+    },
+    'assignment.created': {
+        label: 'مهمة جديدة',
+        subject: 'مهمة جديدة مسندة إليك',
+        body: '{{title}} — {{resource}} #{{id}}',
+        variables: ['title', 'resource', 'id', 'due'],
+        mail: true,
+    },
+    'assignment.approval': {
+        label: 'طلب موافقة',
+        subject: 'موافقة مطلوبة منك',
+        body: '{{title}} — {{resource}} #{{id}}',
+        variables: ['title', 'resource', 'id', 'due'],
+        mail: true,
+    },
+    'assignment.done': {
+        label: 'إنجاز مهمة أسندتها',
+        subject: 'أُنجزت مهمة أسندتها',
+        body: '{{title}} — {{resource}} #{{id}}',
+        variables: ['title', 'resource', 'id'],
+        mail: false,
+    },
+    'assignment.cancelled': {
+        label: 'إلغاء مهمة مسندة إليك',
+        subject: 'أُلغيت مهمة مسندة إليك',
+        body: '{{title}} — {{resource}} #{{id}}',
+        variables: ['title', 'resource', 'id'],
+        mail: false,
+    },
+    'workflow.decided': {
+        label: 'نتيجة تدفق عمل',
+        subject: '{{outcome}}: {{resource}} #{{id}}',
+        body: '{{workflow}} — {{step}}',
+        variables: ['outcome', 'resource', 'id', 'workflow', 'step'],
+        mail: true,
+    },
+    'workflow.failed': {
+        label: 'فشل خطوة تدفق',
+        subject: 'فشلت خطوة في تدفق {{workflow}}',
+        body: '{{resource}} #{{id}} — {{error}}',
+        variables: ['workflow', 'resource', 'id', 'error'],
+        mail: true,
+    },
+    'webhook.failed': {
+        label: 'تعطل Webhook',
+        subject: 'تعذّر تسليم Webhook: {{name}}',
+        body: '{{event}} — {{error}}',
+        variables: ['name', 'event', 'error'],
+        mail: true,
+    },
+    'import.finished': {
+        label: 'اكتمال استيراد',
+        subject: 'اكتمل استيراد {{resource}}',
+        body: 'نجح {{created}} صفاً، وفشل {{failed}}.',
+        variables: ['resource', 'created', 'failed'],
+        mail: false,
+    },
+};
+const PLACEHOLDER = /\{\{\s*([a-zA-Z][a-zA-Z0-9_]*)\s*\}\}/g;
+const SUBJECT_LIMIT = 200;
+const BODY_LIMIT = 4000;
+export function renderTemplate(text, variables) {
+    return text.replace(PLACEHOLDER, (_, name) => {
+        const value = variables[name];
+        return value === null || value === undefined ? '' : String(value);
+    });
+}
+/** Message templates: package defaults plus per-deployment overrides edited by administrators. */
+export class MessageTemplates {
+    db;
+    definitions;
+    constructor(db, definitions = DEFAULT_TEMPLATES) {
+        this.db = db;
+        this.definitions = definitions;
+    }
+    async list() {
+        const rows = await this.db('message_templates').select('*');
+        const overrides = new Map(rows.map((row) => [String(row.key), row]));
+        return Object.entries(this.definitions).map(([key, definition]) => {
+            const row = overrides.get(key);
+            return {
+                key,
+                ...definition,
+                subject: row ? String(row.subject) : definition.subject,
+                body: row ? String(row.body) : definition.body,
+                mail: row ? Boolean(row.mail) : definition.mail,
+                customized: Boolean(row),
+                updatedAt: row ? new Date(row.updated_at).toISOString() : null,
+            };
+        });
+    }
+    async render(key, variables, db = this.db) {
+        const definition = this.definition(key);
+        const row = await db('message_templates').where('key', key).first();
+        return {
+            subject: renderTemplate(row ? String(row.subject) : definition.subject, variables).slice(0, 255),
+            body: renderTemplate(row ? String(row.body) : definition.body, variables),
+            mail: row ? Boolean(row.mail) : definition.mail,
+        };
+    }
+    async update(key, input, actorId) {
+        const definition = this.definition(key);
+        const subject = typeof input.subject === 'string' ? input.subject.trim() : '';
+        const body = typeof input.body === 'string' ? input.body.trim() : '';
+        if (!subject || subject.length > SUBJECT_LIMIT)
+            throw new KitError(422, 'E_TEMPLATE_SUBJECT', 'العنوان مطلوب ولا يتجاوز 200 حرف');
+        if (!body || body.length > BODY_LIMIT)
+            throw new KitError(422, 'E_TEMPLATE_BODY', 'نص الرسالة مطلوب ولا يتجاوز 4000 حرف');
+        for (const text of [subject, body])
+            for (const [, name] of text.matchAll(PLACEHOLDER))
+                if (!definition.variables.includes(name))
+                    throw new KitError(422, 'E_TEMPLATE_VARIABLE', `متغير غير معروف في القالب: ${name}`);
+        const mail = input.mail === undefined ? definition.mail : input.mail === true;
+        await this.db('message_templates')
+            .insert({ key, subject, body, mail, updated_by: actorId, updated_at: this.db.fn.now() })
+            .onConflict('key')
+            .merge(['subject', 'body', 'mail', 'updated_by', 'updated_at']);
+    }
+    async reset(key) {
+        this.definition(key);
+        await this.db('message_templates').where('key', key).del();
+    }
+    /** Example output with sample values, for the editor preview. */
+    preview(key, input) {
+        const definition = this.definition(key);
+        const sample = Object.fromEntries(definition.variables.map((name) => [name, `‹${name}›`]));
+        return {
+            subject: renderTemplate(input.subject, sample),
+            body: renderTemplate(input.body, sample),
+        };
+    }
+    definition(key) {
+        const definition = Object.hasOwn(this.definitions, key) ? this.definitions[key] : undefined;
+        if (!definition)
+            throw new KitError(404, 'E_TEMPLATE_NOT_FOUND', 'القالب غير موجود');
+        return definition;
+    }
+}
+/**
+ * Inserts a templated notification in the caller's transaction. Templates with
+ * mail enabled mark the row for the mail delivery worker (deliverNotificationMail).
+ */
+export async function notifyWithTemplate(db, userId, key, variables, templates = new MessageTemplates(db), target) {
+    const message = await templates.render(key, variables, db);
+    await db('notifications').insert({
+        user_id: userId,
+        title: message.subject,
+        body: message.body,
+        template_key: key,
+        mail_state: message.mail ? 'pending' : null,
+        ...targetColumns(target),
+    });
+}
+/**
+ * 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 async function deliverNotificationMail(db, send, limit = 50) {
+    let sent = 0;
+    let failed = 0;
+    await db.transaction(async (trx) => {
+        const rows = await trx('notifications as n')
+            .join('users as u', 'u.id', 'n.user_id')
+            .where('n.mail_state', 'pending')
+            .orderBy('n.id')
+            .limit(limit)
+            .forUpdate('n')
+            .skipLocked()
+            .select('n.id', 'n.title', 'n.body', 'n.mail_attempts', 'n.resource', 'n.record_id', 'u.email', 'u.full_name', 'u.disabled_at');
+        for (const row of rows) {
+            if (row.disabled_at) {
+                await trx('notifications').where('id', row.id).update({ mail_state: 'skipped' });
+                continue;
+            }
+            try {
+                await send({
+                    to: String(row.email),
+                    name: row.full_name ? String(row.full_name) : null,
+                    subject: String(row.title),
+                    text: String(row.body),
+                    target: row.resource && row.record_id !== null
+                        ? { resource: String(row.resource), recordId: Number(row.record_id) }
+                        : null,
+                });
+                await trx('notifications')
+                    .where('id', row.id)
+                    .update({ mail_state: 'sent', mailed_at: trx.fn.now() });
+                sent++;
+            }
+            catch (error) {
+                const attempts = Number(row.mail_attempts ?? 0) + 1;
+                await trx('notifications')
+                    .where('id', row.id)
+                    .update({
+                    mail_state: attempts >= 3 ? 'failed' : 'pending',
+                    mail_attempts: attempts,
+                    mail_error: String(error.message ?? error).slice(0, 500),
+                });
+                failed++;
+            }
+        }
+    });
+    return { sent, failed };
+}
+/**
+ * Holds one database connection that LISTENs for committed notifications and
+ * calls onSignal for each. Reconnects after connection loss. Returns a stop function.
+ */
+export function listenForNotifications(db, onSignal, options = {}) {
+    let stopped = false;
+    let connection;
+    let timer;
+    const connect = async () => {
+        try {
+            connection = await db.client.acquireConnection();
+            connection.on('notification', (message) => {
+                if (message.channel !== 'kit_notifications' || !message.payload)
+                    return;
+                try {
+                    const parsed = JSON.parse(message.payload);
+                    if (Number.isSafeInteger(parsed.userId) && Number.isSafeInteger(parsed.id))
+                        onSignal({ userId: parsed.userId, id: parsed.id });
+                }
+                catch (error) {
+                    options.onError?.(error);
+                }
+            });
+            connection.once('error', (error) => {
+                options.onError?.(error);
+                void reconnect();
+            });
+            await connection.query('LISTEN kit_notifications');
+        }
+        catch (error) {
+            options.onError?.(error);
+            void reconnect();
+        }
+    };
+    const release = async () => {
+        const current = connection;
+        connection = undefined;
+        if (!current)
+            return;
+        current.removeAllListeners('notification');
+        try {
+            await current.query('UNLISTEN *');
+        }
+        catch { }
+        // A broken connection is destroyed rather than returned to the pool.
+        await db.client.releaseConnection(current).catch(() => { });
+    };
+    const reconnect = async () => {
+        await release();
+        if (stopped)
+            return;
+        timer = setTimeout(() => void connect(), options.retryMs ?? 2000);
+        timer.unref?.();
+    };
+    void connect();
+    return async () => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+        await release();
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+export type ModuleSeedResult = {
+    /** Lookup rows inserted now; rows that already existed are left as they are. */
+    lookups: number;
+    created: string[];
+    adopted: string[];
+    kept: string[];
+};
+/**
+ * Applies the lookups and default roles declared by registered modules. It is
+ * idempotent and additive: existing lookup rows and roles are never changed, so
+ * administrator edits survive every later installation (adula:install runs it).
+ */
+export declare function seedModules(db: Knex, registry: ResourceRegistry, actorId: number): Promise<ModuleSeedResult>;

package/build/src/core/module_seed.js

@@ -0,0 +1,31 @@
+import { RolesAdmin } from './roles.js';
+/**
+ * Applies the lookups and default roles declared by registered modules. It is
+ * idempotent and additive: existing lookup rows and roles are never changed, so
+ * administrator edits survive every later installation (adula:install runs it).
+ */
+export async function seedModules(db, registry, actorId) {
+    return db.transaction(async (trx) => {
+        await trx.raw('SELECT pg_advisory_xact_lock(717012)');
+        let lookups = 0;
+        for (const module of registry.modules())
+            for (const [group, rows] of Object.entries(module.lookups ?? {}))
+                for (const [index, row] of rows.entries()) {
+                    const inserted = await trx('lookups')
+                        .insert({
+                        group,
+                        key: row.key,
+                        label_ar: row.label.ar,
+                        label_en: row.label.en,
+                        sort: row.sort ?? index,
+                        active: true,
+                    })
+                        .onConflict(['group', 'key'])
+                        .ignore()
+                        .returning('id');
+                    lookups += inserted.length;
+                }
+        const roles = await new RolesAdmin(trx, registry).ensureDefaults(actorId, registry.modules().flatMap((module) => [...(module.defaultRoles ?? [])]));
+        return { lookups, ...roles };
+    });
+}

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

@@ -1,10 +1,20 @@
 import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
 export type Notification = {
     id: number;
     title: string;
     body: string;
     readAt: string | null;
     createdAt: string;
+    /**
+     * The record the notification is about, while its resource is still registered.
+     * The record page authorizes the reader when the link is opened.
+     */
+    target: {
+        resource: string;
+        recordId: number;
+        href: string;
+    } | null;
 };
 export type NotificationPage = {
     data: Notification[];
@@ -13,13 +23,20 @@ export type NotificationPage = {
 };
 export declare class NotificationsAdmin {
     private db;
-    constructor(db: Knex);
+    /** Without a registry, stored targets are returned as they are. */
+    private registry?;
+    constructor(db: Knex, 
+    /** Without a registry, stored targets are returned as they are. */
+    registry?: Pick<ResourceRegistry, "has"> | undefined);
+    private target;
     /** Unread first, newest first; the cursor remembers which of the two segments it is in. */
     list(userId: number, options?: {
         cursor?: string;
         limit?: number;
     }): Promise<NotificationPage>;
     markRead(userId: number, id: number): Promise<void>;
+    /** Marks the notification read and returns where it points (null without a target). */
+    open(userId: number, id: number): Promise<string | null>;
     markAllRead(userId: number): Promise<number>;
     unreadCount(userId: number): Promise<number>;
 }

package/build/src/core/notifications.js

@@ -2,8 +2,21 @@ import { KitError } from '../admin/errors.js';
 import { pageLimit } from './activity.js';
 export class NotificationsAdmin {
     db;
-    constructor(db) {
+    registry;
+    constructor(db, 
+    /** Without a registry, stored targets are returned as they are. */
+    registry) {
         this.db = db;
+        this.registry = registry;
+    }
+    target(row) {
+        if (!row.resource || row.record_id === null || row.record_id === undefined)
+            return null;
+        const resource = String(row.resource);
+        if (this.registry && !this.registry.has(resource))
+            return null;
+        const recordId = Number(row.record_id);
+        return { resource, recordId, href: `/resources/${resource}/${recordId}` };
     }
     /** Unread first, newest first; the cursor remembers which of the two segments it is in. */
     async list(userId, options = {}) {
@@ -34,6 +47,7 @@ export class NotificationsAdmin {
                 body: row.body,
                 readAt: row.read_at ? new Date(row.read_at).toISOString() : null,
                 createdAt: new Date(row.created_at).toISOString(),
+                target: this.target(row),
             })),
             nextCursor: rows.length > limit ? `${last.read_at ? 'r' : 'u'}:${last.id}` : null,
             unread: await this.unreadCount(userId),
@@ -48,6 +62,18 @@ export class NotificationsAdmin {
             .whereNull('read_at')
             .update({ read_at: this.db.fn.now() });
     }
+    /** Marks the notification read and returns where it points (null without a target). */
+    async open(userId, id) {
+        const row = await this.db('notifications').where({ id, user_id: userId }).first();
+        if (!row)
+            throw new KitError(404, 'E_NOTIFICATION_NOT_FOUND', 'الإشعار غير موجود');
+        if (!row.read_at)
+            await this.db('notifications')
+                .where({ id, user_id: userId })
+                .whereNull('read_at')
+                .update({ read_at: this.db.fn.now() });
+        return this.target(row)?.href ?? null;
+    }
     async markAllRead(userId) {
         return this.db('notifications')
             .where('user_id', userId)

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

@@ -1,9 +1,14 @@
 import type { Knex } from 'knex';
 import type { ResourceRegistry } from '../resource/registry.js';
-import type { Label } from '../resource/types.js';
+import type { Label, ModuleRole } from '../resource/types.js';
 import type { Conditions } from '../auth/conditions.js';
 export type RoleSummary = {
     id: number;
+    /**
+     * Stable identifier addressed by workflows and module defaults. The display name
+     * can change freely; the key is set once.
+     */
+    key: string | null;
     name: string;
     permissionLevel: number;
     rules: number;
@@ -32,6 +37,8 @@ export type MatrixField = {
     label: Label;
     type: string;
     conditionable: boolean;
+    /** Accepts the current user ("$actor.id") as a condition value: user fields, createdBy, updatedBy. */
+    actor?: boolean;
 };
 export type MatrixSubject = {
     name: string;
@@ -46,6 +53,8 @@ export type RoleMatrix = {
     subjects: MatrixSubject[];
 };
 export declare const ALL_SUBJECT_LABEL: Label;
+/** A role key: lower-case letters, digits and underscores, starting with a letter. */
+export declare function roleKey(value: unknown): string;
 export declare class RolesAdmin {
     private db;
     private registry;
@@ -54,12 +63,19 @@ export declare class RolesAdmin {
     get(id: number): Promise<RoleDetail>;
     create(actorId: number, input: {
         name: string;
+        key?: string | null;
         permissionLevel?: number;
     }): Promise<{
         id: number;
+        key: string | null;
         name: string;
         permissionLevel: number;
     }>;
+    /**
+     * Gives a role its stable key. A key is set once: workflows and module defaults
+     * depend on it, so changing it would silently detach them.
+     */
+    setKey(actorId: number, id: number, value: string): Promise<void>;
     rename(actorId: number, id: number, value: string): Promise<void>;
     setPermissionLevel(actorId: number, id: number, value: number): Promise<void>;
     delete(actorId: number, id: number): Promise<void>;
@@ -67,6 +83,16 @@ export declare class RolesAdmin {
     matrix(): RoleMatrix;
     setRule(actorId: number, roleId: number, input: RuleInput): Promise<RoleRule>;
     removeRule(actorId: number, roleId: number, ruleId: number): Promise<void>;
+    /**
+     * Creates module default roles that no role holds the key of yet, with their rules
+     * validated exactly like setRule. Existing roles are never modified. A keyless role
+     * with the same display name is adopted by receiving the key, rules untouched.
+     */
+    ensureDefaults(actorId: number, roles: readonly ModuleRole[]): Promise<{
+        created: string[];
+        adopted: string[];
+        kept: string[];
+    }>;
     private validateRule;
     private find;
 }