@adula/kit 0.2.0-alpha.4 → 1.0.0

package/build/src/core/message_templates.js

@@ -0,0 +1,288 @@
+import { KitError } from '../admin/errors.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)) {
+    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,
+    });
+}
+/**
+ * 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', '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),
+                });
+                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/database/schema.d.ts

@@ -5,3 +5,21 @@ export declare function createCoreSchema(db: Knex): Promise<void>;
 export declare function createAttachmentsSchema(db: Knex): Promise<void>;
 export declare function createSavedViewsSchema(db: Knex): Promise<void>;
 export declare function createResourceTable(db: Knex, resource: Pick<Resource, 'name' | 'scoped' | 'version' | 'submittable' | 'customFields' | 'fields'>): Promise<void>;
+/** Record collaboration (phase 3): comments with mentions, followers, tags and field history. */
+export declare function createCollaborationSchema(db: Knex): Promise<void>;
+/** Work assigned to a user on a record; approval steps of workflows reuse it (phase 4). */
+export declare function createAssignmentsSchema(db: Knex): Promise<void>;
+/**
+ * Message templates, notification e-mail delivery state and the realtime signal.
+ * The trigger's NOTIFY is delivered only when the inserting transaction commits.
+ */
+export declare function createMessagingSchema(db: Knex): Promise<void>;
+/** Outgoing webhooks and their delivery log (exactly one row per webhook and event). */
+export declare function createWebhooksSchema(db: Knex): Promise<void>;
+/** CSV import batches: parsed rows, column mapping, progress and per-row errors. */
+export declare function createImportsSchema(db: Knex): Promise<void>;
+/**
+ * Workflow engine state (phase 4): the submission envelope rows gain execution
+ * columns, and every transition is appended to workflow_events.
+ */
+export declare function createWorkflowSchema(db: Knex): Promise<void>;

package/build/src/database/schema.js

@@ -246,3 +246,195 @@ export async function createResourceTable(db, resource) {
         await db.raw('CREATE INDEX ?? ON ?? USING gin(search_vector)', [`${table}_search_gin`, table]);
     }
 }
+/** Record collaboration (phase 3): comments with mentions, followers, tags and field history. */
+export async function createCollaborationSchema(db) {
+    await db.schema.createTable('comments', (t) => {
+        t.bigIncrements('id');
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.integer('author_id').notNullable().references('id').inTable('users').onDelete('RESTRICT');
+        t.text('body').notNullable();
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('edited_at', { useTz: true });
+        t.timestamp('deleted_at', { useTz: true });
+        t.index(['resource', 'record_id', 'id']);
+    });
+    await db.schema.createTable('comment_mentions', (t) => {
+        t.bigInteger('comment_id')
+            .notNullable()
+            .references('id')
+            .inTable('comments')
+            .onDelete('CASCADE');
+        t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+        t.primary(['comment_id', 'user_id']);
+        t.index(['user_id']);
+    });
+    await db.schema.createTable('followers', (t) => {
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.primary(['resource', 'record_id', 'user_id']);
+        t.index(['user_id']);
+    });
+    await db.schema.createTable('tags', (t) => {
+        t.increments('id');
+        t.string('name', 60).notNullable().unique();
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+    });
+    await db.schema.createTable('taggables', (t) => {
+        t.integer('tag_id').notNullable().references('id').inTable('tags').onDelete('CASCADE');
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.primary(['tag_id', 'resource', 'record_id']);
+        t.index(['resource', 'record_id']);
+    });
+    await db.schema.createTable('field_changes', (t) => {
+        t.bigIncrements('id');
+        t.bigInteger('activity_id')
+            .notNullable()
+            .references('id')
+            .inTable('activities')
+            .onDelete('CASCADE')
+            .index();
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.string('field').notNullable();
+        t.jsonb('before');
+        t.jsonb('after');
+        t.index(['resource', 'record_id', 'id']);
+    });
+}
+/** Work assigned to a user on a record; approval steps of workflows reuse it (phase 4). */
+export async function createAssignmentsSchema(db) {
+    await db.schema.createTable('assignments', (t) => {
+        t.bigIncrements('id');
+        t.string('resource').notNullable();
+        t.integer('record_id').notNullable();
+        t.integer('assignee_id').notNullable().references('id').inTable('users').onDelete('RESTRICT');
+        t.integer('assigned_by').references('id').inTable('users').onDelete('RESTRICT');
+        t.string('kind', 20).notNullable().defaultTo('task');
+        t.string('title', 200).notNullable();
+        t.text('note');
+        t.date('due_on');
+        t.string('status', 20).notNullable().defaultTo('open');
+        t.uuid('workflow_run_id');
+        t.string('workflow_step', 100);
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('completed_at', { useTz: true });
+        t.integer('completed_by').references('id').inTable('users').onDelete('RESTRICT');
+        t.string('outcome', 20);
+        t.index(['assignee_id', 'status', 'id']);
+        t.index(['resource', 'record_id']);
+        t.index(['workflow_run_id']);
+    });
+}
+/**
+ * Message templates, notification e-mail delivery state and the realtime signal.
+ * The trigger's NOTIFY is delivered only when the inserting transaction commits.
+ */
+export async function createMessagingSchema(db) {
+    await db.schema.createTable('message_templates', (t) => {
+        t.string('key', 100).primary();
+        t.string('subject', 255).notNullable();
+        t.text('body').notNullable();
+        t.boolean('mail').notNullable().defaultTo(false);
+        t.integer('updated_by').references('id').inTable('users').onDelete('SET NULL');
+        t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+    });
+    await db.schema.alterTable('notifications', (t) => {
+        t.string('template_key', 100);
+        t.string('mail_state', 20);
+        t.integer('mail_attempts').notNullable().defaultTo(0);
+        t.string('mail_error', 500);
+        t.timestamp('mailed_at', { useTz: true });
+    });
+    await db.raw("CREATE INDEX notifications_mail_pending ON notifications (id) WHERE mail_state = 'pending'");
+    await db.raw(`CREATE FUNCTION kit_notification_signal() RETURNS trigger LANGUAGE plpgsql AS $$ BEGIN PERFORM pg_notify('kit_notifications', json_build_object('userId', NEW.user_id, 'id', NEW.id)::text); RETURN NULL; END $$`);
+    await db.raw('CREATE TRIGGER kit_notification_signal AFTER INSERT ON notifications FOR EACH ROW EXECUTE FUNCTION kit_notification_signal()');
+}
+/** Outgoing webhooks and their delivery log (exactly one row per webhook and event). */
+export async function createWebhooksSchema(db) {
+    await db.schema.createTable('webhooks', (t) => {
+        t.increments('id');
+        t.string('name', 100).notNullable();
+        t.string('url', 2000).notNullable();
+        t.text('secret').notNullable();
+        t.jsonb('events').notNullable();
+        t.boolean('active').notNullable().defaultTo(true);
+        t.integer('failing').notNullable().defaultTo(0);
+        t.integer('created_by').references('id').inTable('users').onDelete('SET NULL');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('last_delivery_at', { useTz: true });
+    });
+    await db.raw('CREATE INDEX webhooks_events_gin ON webhooks USING gin(events)');
+    await db.schema.createTable('webhook_deliveries', (t) => {
+        t.uuid('id').primary();
+        t.integer('webhook_id').notNullable().references('id').inTable('webhooks').onDelete('CASCADE');
+        t.uuid('event_id').notNullable();
+        t.string('event').notNullable();
+        t.jsonb('payload').notNullable();
+        t.string('status', 20).notNullable().defaultTo('pending');
+        t.integer('attempts').notNullable().defaultTo(0);
+        t.integer('last_status');
+        t.string('last_error', 500);
+        t.timestamp('next_attempt_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('delivered_at', { useTz: true });
+        t.unique(['webhook_id', 'event_id']);
+        t.index(['webhook_id', 'created_at']);
+    });
+    await db.raw("CREATE INDEX webhook_deliveries_due ON webhook_deliveries (next_attempt_at) WHERE status = 'pending'");
+}
+/** CSV import batches: parsed rows, column mapping, progress and per-row errors. */
+export async function createImportsSchema(db) {
+    await db.schema.createTable('import_batches', (t) => {
+        t.increments('id');
+        t.string('resource').notNullable();
+        t.integer('user_id').notNullable().references('id').inTable('users').onDelete('CASCADE');
+        t.string('file_name', 200).notNullable();
+        t.string('status', 20).notNullable();
+        t.jsonb('headers').notNullable();
+        t.jsonb('mapping').notNullable();
+        t.jsonb('rows').notNullable();
+        t.integer('total').notNullable();
+        t.integer('processed').notNullable().defaultTo(0);
+        t.integer('created').notNullable().defaultTo(0);
+        t.integer('failed').notNullable().defaultTo(0);
+        t.jsonb('errors').notNullable().defaultTo('[]');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('started_at', { useTz: true });
+        t.timestamp('finished_at', { useTz: true });
+        t.index(['user_id', 'id']);
+        t.index(['status']);
+    });
+}
+/**
+ * Workflow engine state (phase 4): the submission envelope rows gain execution
+ * columns, and every transition is appended to workflow_events.
+ */
+export async function createWorkflowSchema(db) {
+    await db.schema.alterTable('workflow_runs', (t) => {
+        t.string('current_step', 100);
+        t.timestamp('wake_at', { useTz: true });
+        t.integer('attempts').notNullable().defaultTo(0);
+        t.string('last_error', 1000);
+        t.string('outcome', 30);
+        t.integer('started_by').references('id').inTable('users').onDelete('SET NULL');
+        t.timestamp('updated_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.timestamp('completed_at', { useTz: true });
+        t.index(['resource', 'record_id']);
+    });
+    await db.raw("CREATE INDEX workflow_runs_due ON workflow_runs (wake_at) WHERE status = 'running'");
+    await db.schema.createTable('workflow_events', (t) => {
+        t.bigIncrements('id');
+        t.uuid('run_id').notNullable().references('id').inTable('workflow_runs').onDelete('CASCADE');
+        t.string('step', 100);
+        t.string('event', 50).notNullable();
+        t.integer('actor_id').references('id').inTable('users').onDelete('SET NULL');
+        t.jsonb('detail').notNullable().defaultTo('{}');
+        t.timestamp('created_at', { useTz: true }).notNullable().defaultTo(db.fn.now());
+        t.index(['run_id', 'id']);
+    });
+}

package/build/src/events/outbox.d.ts

@@ -6,6 +6,7 @@ export type DomainEvent = {
 };
 export type Listener = {
     name: string;
+    /** The exact event name, or '*' for a catch-all listener (for example webhooks). */
     event: string;
     handle(event: DomainEvent, trx: Knex.Transaction): Promise<void>;
 };

package/build/src/events/outbox.js

@@ -17,7 +17,7 @@ export async function publishOutbox(db, jobs, limit = 100) {
     });
 }
 export async function consumeEvent(db, listener, event) {
-    if (listener.event !== event.event)
+    if (listener.event !== '*' && listener.event !== event.event)
         return false;
     return db.transaction(async (trx) => {
         const inserted = await trx('processed_events')

package/build/src/events/record_mutation.d.ts

@@ -1,5 +1,10 @@
 import type { Knex } from 'knex';
 import type { Action } from '../resource/types.js';
+export type FieldChange = {
+    field: string;
+    before: unknown;
+    after: unknown;
+};
 /** Infrastructure writes for a module-owned mutation, inside its existing transaction. */
 export declare function recordMutation(trx: Knex.Transaction, mutation: {
     module: string;
@@ -10,4 +15,6 @@ export declare function recordMutation(trx: Knex.Transaction, mutation: {
     impersonatorId?: number;
     action: Action;
     fields: string[];
+    /** Before/after values of the changed fields; read back per viewer's field access. */
+    changes?: FieldChange[];
 }): Promise<void>;

package/build/src/events/record_mutation.js

@@ -19,7 +19,8 @@ export async function recordMutation(trx, mutation) {
         actorId: mutation.actorId,
         ...(mutation.impersonatorId ? { impersonatorId: mutation.impersonatorId } : {}),
     };
-    await trx('activities').insert({
+    const [activity] = await trx('activities')
+        .insert({
         resource: mutation.resource,
         record_id: mutation.id,
         actor_id: mutation.actorId,
@@ -28,7 +29,17 @@ export async function recordMutation(trx, mutation) {
             fields: mutation.fields,
             ...(mutation.impersonatorId ? { impersonatedBy: mutation.impersonatorId } : {}),
         }),
-    });
+    })
+        .returning('id');
+    if (mutation.changes?.length)
+        await trx('field_changes').insert(mutation.changes.map((change) => ({
+            activity_id: activity.id,
+            resource: mutation.resource,
+            record_id: mutation.id,
+            field: change.field,
+            before: JSON.stringify(change.before ?? null),
+            after: JSON.stringify(change.after ?? null),
+        })));
     await trx('outbox').insert({
         id: eventId,
         event,

package/build/src/integrations/imports.d.ts

@@ -0,0 +1,74 @@
+import type { Knex } from 'knex';
+import type { Actor } from '../auth/ability.js';
+import type { ResourceService } from '../admin/resource_service.js';
+import type { ResourceRegistry } from '../resource/registry.js';
+import type { Field } from '../resource/types.js';
+export type ImportStatus = 'mapping' | 'queued' | 'running' | 'done' | 'failed';
+export type ImportTarget = {
+    key: string;
+    label: string;
+    type: string;
+    required: boolean;
+};
+export type ImportBatch = {
+    id: number;
+    resource: string;
+    resourceLabel: string;
+    fileName: string;
+    status: ImportStatus;
+    headers: string[];
+    mapping: Record<string, string>;
+    sample: string[][];
+    total: number;
+    processed: number;
+    created: number;
+    failed: number;
+    errors: {
+        row: number;
+        message: string;
+    }[];
+    createdAt: string;
+    finishedAt: string | null;
+    targets: ImportTarget[];
+};
+export type ActorSource = {
+    load(id: number): Promise<Actor>;
+};
+export declare const IMPORT_ROW_LIMIT = 5000;
+/** Converts one CSV cell to the field's stored representation, or throws a readable error. */
+export declare function importCell(field: Field, raw: string, lookups: Map<string, string>): unknown;
+/**
+ * CSV imports in batches: the upload is parsed and stored, the user maps columns
+ * to writable fields, and a worker saves each row through ResourceService with
+ * the importing user's current permissions. Row failures never stop the batch.
+ */
+export declare class ImportBatches {
+    private db;
+    private registry;
+    private resources;
+    private actors;
+    constructor(db: Knex, registry: ResourceRegistry, resources: ResourceService, actors: ActorSource);
+    /** Writable, importable fields for this actor. */
+    targets(name: string, actor: Actor): ImportTarget[];
+    create(name: string, actor: Actor, input: {
+        fileName: unknown;
+        content: unknown;
+    }): Promise<ImportBatch>;
+    show(id: unknown, actor: Actor): Promise<ImportBatch>;
+    list(actor: Actor): Promise<ImportBatch[]>;
+    /** Stores the column mapping and queues the batch for the worker. */
+    start(id: unknown, actor: Actor, mapping: unknown): Promise<ImportBatch>;
+    /**
+     * Worker step: claims one queued or running batch and imports up to `chunk`
+     * rows. Progress is committed per row, so a crash resumes after the last one.
+     */
+    process(chunk?: number): Promise<{
+        id: number;
+        processed: number;
+        created: number;
+        failed: number;
+    } | null>;
+    private safeTargets;
+    private owned;
+    private present;
+}