@adula/kit 0.2.0-alpha.3 → 1.0.0

package/build/src/integrations/print.js

@@ -0,0 +1,123 @@
+const escape = (value) => value
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+function text(field, value, input) {
+    if (value === null || value === undefined || value === '')
+        return '—';
+    switch (field.type) {
+        case 'boolean':
+            return value ? 'نعم' : 'لا';
+        case 'money': {
+            // Same presentation as the UI: Latin digits, grouped, two minor digits.
+            if (!/^-?\d+$/.test(String(value)))
+                return String(value);
+            const minor = BigInt(String(value));
+            const abs = minor < 0n ? -minor : minor;
+            return `${minor < 0n ? '-' : ''}${new Intl.NumberFormat('ar-u-nu-latn').format(abs / 100n)}.${String(abs % 100n).padStart(2, '0')}`;
+        }
+        case 'lookup':
+            return (input.lookups?.[field.key]?.find((option) => option.value === value)?.label ?? String(value));
+        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;
+            return label === null || label === undefined ? `#${String(value)}` : String(label);
+        }
+        case 'attachment':
+            return typeof value === 'object' && !Array.isArray(value) && value.name
+                ? String(value.name)
+                : 'مرفق';
+        case 'datetime':
+            return new Date(String(value)).toLocaleString('ar-u-nu-latn-ca-gregory', { timeZone: 'UTC' });
+        case 'json':
+            return JSON.stringify(value);
+        default:
+            return String(value);
+    }
+}
+/**
+ * The generic printable view of one record: RTL A4 HTML, every value escaped.
+ * Only fields already serialized for the caller are printed, so printing can
+ * never reveal more than the detail page.
+ */
+export function renderPrintHtml(input) {
+    const printedAt = input.printedAt ?? new Date();
+    const fields = input.resource.fields.filter((field) => input.resource.show.includes(field.key) &&
+        field.type !== 'hasMany' &&
+        field.key in input.record);
+    const status = input.resource.submittable && typeof input.record.docStatus === 'number'
+        ? ['مسودة', 'معتمد', 'ملغي'][input.record.docStatus]
+        : null;
+    const rows = fields
+        .map((field) => `<tr><th scope="row">${escape(field.label.ar)}</th><td>${escape(text(field, input.record[field.key], input))}</td></tr>`)
+        .join('');
+    const children = Object.entries(input.children ?? {})
+        .map(([key, group]) => {
+        const label = input.resource.fields.find((field) => field.key === key)?.label.ar ?? key;
+        const columns = group.fields.filter((field) => field.type !== 'hasMany');
+        return `<section><h2>${escape(label)}</h2><table class="lines"><thead><tr>${columns
+            .map((column) => `<th scope="col">${escape(column.label.ar)}</th>`)
+            .join('')}</tr></thead><tbody>${group.rows
+            .map((row) => `<tr>${columns.map((column) => `<td>${escape(text(column, row[column.key], input))}</td>`).join('')}</tr>`)
+            .join('')}</tbody></table></section>`;
+    })
+        .join('');
+    const logo = input.identity.logoUrl
+        ? `<img class="logo" src="${escape(input.identity.logoUrl)}" alt="">`
+        : '';
+    return `<!doctype html>
+<html lang="ar" dir="rtl">
+<head>
+<meta charset="utf-8">
+<title>${escape(input.resource.label)} #${escape(String(input.record.id))}</title>
+<style>
+@page { size: A4; margin: 18mm 16mm; }
+* { box-sizing: border-box; }
+body { font-family: "Noto Sans Arabic", "Segoe UI", Tahoma, sans-serif; color: #1c1917; font-size: 12pt; margin: 0; }
+header { display: flex; align-items: center; justify-content: space-between; border-bottom: 2px solid #1c1917; padding-bottom: 8mm; margin-bottom: 8mm; }
+header h1 { font-size: 18pt; margin: 0; }
+header p { margin: 2mm 0 0; color: #57534e; font-size: 10pt; }
+.logo { max-height: 18mm; max-width: 50mm; }
+table { width: 100%; border-collapse: collapse; }
+th, td { text-align: start; padding: 2.5mm 3mm; border-bottom: 1px solid #e7e5e4; vertical-align: top; }
+.fields th { width: 35%; color: #57534e; font-weight: 600; }
+.lines thead th { background: #f5f5f4; font-size: 10pt; }
+h2 { font-size: 13pt; margin: 8mm 0 3mm; }
+.status { display: inline-block; border: 1px solid #1c1917; border-radius: 3mm; padding: 1mm 3mm; font-size: 10pt; }
+footer { margin-top: 10mm; color: #78716c; font-size: 9pt; }
+@media screen { body { max-width: 210mm; margin: 10mm auto; padding: 0 10mm; } }
+</style>
+</head>
+<body>
+<header>
+<div>
+<h1>${escape(input.resource.label)} #${escape(String(input.record.id))}</h1>
+<p>${escape(input.identity.name)}</p>
+</div>
+<div>${status ? `<span class="status">${escape(status)}</span>` : ''}${logo}</div>
+</header>
+<table class="fields"><tbody>${rows}</tbody></table>
+${children}
+<footer>طُبع بواسطة ${escape(input.printedBy)} في ${escape(printedAt.toISOString().slice(0, 16).replace('T', ' '))} UTC</footer>
+</body>
+</html>`;
+}
+/**
+ * Converts printable HTML to PDF with an optional Gotenberg service
+ * (POST /forms/chromium/convert/html). Without it, pages use the browser's print.
+ */
+export async function htmlToPdf(html, options) {
+    const form = new FormData();
+    form.append('files', new Blob([html], { type: 'text/html' }), 'index.html');
+    form.append('printBackground', 'true');
+    form.append('preferCssPageSize', 'true');
+    const response = await (options.fetch ?? fetch)(`${options.gotenbergUrl.replace(/\/$/, '')}/forms/chromium/convert/html`, { method: 'POST', body: form, signal: AbortSignal.timeout(options.timeoutMs ?? 30000) });
+    if (!response.ok)
+        throw new Error(`PDF conversion failed with HTTP ${response.status}`);
+    const bytes = Buffer.from(await response.arrayBuffer());
+    if (!bytes.subarray(0, 5).equals(Buffer.from('%PDF-')))
+        throw new Error('PDF conversion returned a non-PDF response');
+    return bytes;
+}

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

@@ -0,0 +1,98 @@
+import type { Knex } from 'knex';
+import type { ResourceRegistry } from '../resource/registry.js';
+import type { Listener } from '../events/outbox.js';
+/** Seals webhook secrets at rest; hosts pass their framework encryption service. */
+export type SecretBox = {
+    seal(value: string): string;
+    open(value: string): string | null;
+};
+export type Webhook = {
+    id: number;
+    name: string;
+    url: string;
+    events: string[];
+    active: boolean;
+    createdAt: string;
+    lastDeliveryAt: string | null;
+    failing: number;
+};
+export type WebhookDelivery = {
+    id: string;
+    event: string;
+    status: 'pending' | 'delivered' | 'failed';
+    attempts: number;
+    lastStatus: number | null;
+    lastError: string | null;
+    createdAt: string;
+    deliveredAt: string | null;
+    nextAttemptAt: string | null;
+};
+export type WebhookOptions = {
+    /** Allow http:// and private or loopback addresses (development and tests only). */
+    allowPrivateTargets?: boolean;
+    /** Hostname resolution; replaceable in tests. */
+    resolve?: (host: string) => Promise<string[]>;
+};
+export type HttpPoster = (url: string, init: {
+    headers: Record<string, string>;
+    body: string;
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+}>;
+export declare const WEBHOOK_MAX_ATTEMPTS: number;
+/** Signature receivers verify: hex HMAC-SHA256 over `${timestamp}.${body}`. */
+export declare function signWebhook(secret: string, timestamp: string, body: string): string;
+/**
+ * Outgoing webhooks: administrators subscribe HTTPS endpoints to domain events.
+ * Deliveries are queued exactly once per event inside the listener transaction,
+ * signed with a per-webhook secret and retried with backoff by the worker.
+ * Payloads carry the event envelope only, never record fields.
+ */
+export declare class Webhooks {
+    private db;
+    private registry;
+    private secrets;
+    private options;
+    constructor(db: Knex, registry: ResourceRegistry, secrets: SecretBox, options?: WebhookOptions);
+    /** Events a webhook may subscribe to, derived from the registry. */
+    events(): {
+        key: string;
+        resource: string;
+        verb: string;
+    }[];
+    list(): Promise<Webhook[]>;
+    /** Creates a webhook and returns its signing secret once; it is never shown again. */
+    create(actorId: number, input: {
+        name: unknown;
+        url: unknown;
+        events: unknown;
+    }): Promise<{
+        webhook: Webhook;
+        secret: string;
+    }>;
+    update(id: number, input: {
+        name: unknown;
+        url: unknown;
+        events: unknown;
+        active?: unknown;
+    }): Promise<void>;
+    remove(id: number): Promise<void>;
+    deliveries(id: number, limit?: number): Promise<WebhookDelivery[]>;
+    /** Puts a failed delivery back in the queue for an immediate attempt. */
+    retry(deliveryId: string): Promise<void>;
+    /** Catch-all listener that queues one delivery per matching active webhook. */
+    listener(): Listener;
+    /**
+     * Sends due deliveries. Each row is claimed with SKIP LOCKED; a crash after the
+     * HTTP call may repeat a delivery, so receivers deduplicate on X-Adula-Delivery.
+     */
+    deliver(post: HttpPoster, limit?: number): Promise<{
+        delivered: number;
+        failed: number;
+    }>;
+    private validate;
+    /** Refuses non-HTTPS URLs and hosts resolving to private addresses (SSRF). */
+    private assertTarget;
+    private present;
+}

package/build/src/integrations/webhooks.js

@@ -0,0 +1,298 @@
+import { createHmac, randomBytes, randomUUID } from 'node:crypto';
+import { lookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+import { KitError } from '../admin/errors.js';
+import { notifyWithTemplate } from '../core/message_templates.js';
+const EVENT_VERBS = ['created', 'updated', 'deleted', 'submitted', 'cancelled', 'amended'];
+const BACKOFF_MINUTES = [1, 5, 30, 120, 720];
+export const WEBHOOK_MAX_ATTEMPTS = BACKOFF_MINUTES.length + 1;
+const NAME_LIMIT = 100;
+/** Signature receivers verify: hex HMAC-SHA256 over `${timestamp}.${body}`. */
+export function signWebhook(secret, timestamp, body) {
+    return createHmac('sha256', secret).update(`${timestamp}.${body}`).digest('hex');
+}
+function privateAddress(address) {
+    if (isIP(address) === 6) {
+        const lower = address.toLowerCase();
+        if (lower.startsWith('::ffff:'))
+            return privateAddress(lower.slice(7));
+        return (lower === '::1' ||
+            lower === '::' ||
+            lower.startsWith('fc') ||
+            lower.startsWith('fd') ||
+            lower.startsWith('fe8') ||
+            lower.startsWith('fe9') ||
+            lower.startsWith('fea') ||
+            lower.startsWith('feb'));
+    }
+    const [a, b] = address.split('.').map(Number);
+    return (a === 10 ||
+        a === 127 ||
+        a === 0 ||
+        (a === 169 && b === 254) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        a >= 224);
+}
+/**
+ * Outgoing webhooks: administrators subscribe HTTPS endpoints to domain events.
+ * Deliveries are queued exactly once per event inside the listener transaction,
+ * signed with a per-webhook secret and retried with backoff by the worker.
+ * Payloads carry the event envelope only, never record fields.
+ */
+export class Webhooks {
+    db;
+    registry;
+    secrets;
+    options;
+    constructor(db, registry, secrets, options = {}) {
+        this.db = db;
+        this.registry = registry;
+        this.secrets = secrets;
+        this.options = options;
+    }
+    /** Events a webhook may subscribe to, derived from the registry. */
+    events() {
+        return this.registry.all().flatMap((resource) => EVENT_VERBS.filter((verb) => !['submitted', 'cancelled', 'amended'].includes(verb) || Boolean(resource.submittable)).map((verb) => ({
+            key: `${this.registry.owner(resource.name)}.${resource.name}.${verb}`,
+            resource: resource.label.ar,
+            verb,
+        })));
+    }
+    async list() {
+        const rows = await this.db('webhooks').orderBy('id');
+        return rows.map((row) => this.present(row));
+    }
+    /** Creates a webhook and returns its signing secret once; it is never shown again. */
+    async create(actorId, input) {
+        const values = await this.validate(input);
+        const secret = randomBytes(32).toString('base64url');
+        const [row] = await this.db('webhooks')
+            .insert({ ...values, secret: this.secrets.seal(secret), created_by: actorId })
+            .returning('*');
+        return { webhook: this.present(row), secret };
+    }
+    async update(id, input) {
+        const values = await this.validate(input);
+        const updated = await this.db('webhooks')
+            .where('id', id)
+            .update({ ...values, active: input.active !== false, updated_at: this.db.fn.now() });
+        if (!updated)
+            throw new KitError(404, 'E_WEBHOOK_NOT_FOUND', 'الـWebhook غير موجود');
+    }
+    async remove(id) {
+        const removed = await this.db('webhooks').where('id', id).del();
+        if (!removed)
+            throw new KitError(404, 'E_WEBHOOK_NOT_FOUND', 'الـWebhook غير موجود');
+    }
+    async deliveries(id, limit = 50) {
+        if (!(await this.db('webhooks').where('id', id).first('id')))
+            throw new KitError(404, 'E_WEBHOOK_NOT_FOUND', 'الـWebhook غير موجود');
+        const rows = await this.db('webhook_deliveries')
+            .where('webhook_id', id)
+            .orderBy('created_at', 'desc')
+            .limit(Math.min(100, Math.max(1, limit)));
+        return rows.map((row) => ({
+            id: String(row.id),
+            event: String(row.event),
+            status: row.status,
+            attempts: Number(row.attempts),
+            lastStatus: row.last_status === null ? null : Number(row.last_status),
+            lastError: row.last_error === null ? null : String(row.last_error),
+            createdAt: new Date(row.created_at).toISOString(),
+            deliveredAt: row.delivered_at ? new Date(row.delivered_at).toISOString() : null,
+            nextAttemptAt: row.status === 'pending' ? new Date(row.next_attempt_at).toISOString() : null,
+        }));
+    }
+    /** Puts a failed delivery back in the queue for an immediate attempt. */
+    async retry(deliveryId) {
+        const updated = await this.db('webhook_deliveries')
+            .where({ id: deliveryId, status: 'failed' })
+            .update({ status: 'pending', attempts: 0, next_attempt_at: this.db.fn.now() });
+        if (!updated)
+            throw new KitError(404, 'E_DELIVERY_NOT_FOUND', 'لا توجد محاولة فاشلة بهذا المعرّف');
+    }
+    /** Catch-all listener that queues one delivery per matching active webhook. */
+    listener() {
+        return {
+            name: 'kit.webhooks',
+            event: '*',
+            handle: async (event, trx) => {
+                const hooks = await trx('webhooks')
+                    .where('active', true)
+                    .whereRaw('events @> ?::jsonb', [JSON.stringify([event.event])])
+                    .select('id');
+                if (!hooks.length)
+                    return;
+                const payload = {
+                    id: event.id,
+                    event: event.event,
+                    resource: event.payload.resource ?? null,
+                    recordId: event.payload.id ?? null,
+                    actorId: event.payload.actorId ?? null,
+                    occurredAt: new Date().toISOString(),
+                };
+                await trx('webhook_deliveries')
+                    .insert(hooks.map((hook) => ({
+                    id: randomUUID(),
+                    webhook_id: hook.id,
+                    event_id: event.id,
+                    event: event.event,
+                    payload: JSON.stringify(payload),
+                })))
+                    .onConflict(['webhook_id', 'event_id'])
+                    .ignore();
+            },
+        };
+    }
+    /**
+     * Sends due deliveries. Each row is claimed with SKIP LOCKED; a crash after the
+     * HTTP call may repeat a delivery, so receivers deduplicate on X-Adula-Delivery.
+     */
+    async deliver(post, limit = 20) {
+        const claimed = await this.db.transaction(async (trx) => {
+            const rows = await trx('webhook_deliveries as d')
+                .join('webhooks as w', 'w.id', 'd.webhook_id')
+                .where('d.status', 'pending')
+                .where('d.next_attempt_at', '<=', trx.fn.now())
+                .where('w.active', true)
+                .orderBy('d.next_attempt_at')
+                .limit(limit)
+                .forUpdate('d')
+                .skipLocked()
+                .select('d.*', 'w.url', 'w.secret', 'w.name', 'w.created_by');
+            // Lease the rows so a parallel worker skips them while HTTP calls run.
+            if (rows.length)
+                await trx('webhook_deliveries')
+                    .whereIn('id', rows.map((row) => row.id))
+                    .update({ next_attempt_at: trx.raw("now() + interval '2 minutes'") });
+            return rows;
+        });
+        let delivered = 0;
+        let failed = 0;
+        for (const row of claimed) {
+            const body = JSON.stringify(row.payload);
+            const timestamp = String(Math.floor(Date.now() / 1000));
+            const attempts = Number(row.attempts) + 1;
+            let status = null;
+            let error = null;
+            try {
+                const secret = this.secrets.open(String(row.secret));
+                if (!secret)
+                    throw new Error('Webhook secret cannot be opened with the current key');
+                await this.assertTarget(String(row.url));
+                const response = await post(String(row.url), {
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'User-Agent': 'adula-kit-webhooks',
+                        'X-Adula-Event': String(row.event),
+                        'X-Adula-Delivery': String(row.id),
+                        'X-Adula-Timestamp': timestamp,
+                        'X-Adula-Signature': `sha256=${signWebhook(secret, timestamp, body)}`,
+                    },
+                    body,
+                    signal: AbortSignal.timeout(10000),
+                });
+                status = response.status;
+                if (status < 200 || status >= 300)
+                    error = `HTTP ${status}`;
+            }
+            catch (caught) {
+                error = String(caught?.message ?? caught).slice(0, 500);
+            }
+            if (!error) {
+                await this.db('webhook_deliveries').where('id', row.id).update({
+                    status: 'delivered',
+                    attempts,
+                    last_status: status,
+                    last_error: null,
+                    delivered_at: this.db.fn.now(),
+                });
+                await this.db('webhooks')
+                    .where('id', row.webhook_id)
+                    .update({ failing: 0, last_delivery_at: this.db.fn.now() });
+                delivered++;
+                continue;
+            }
+            failed++;
+            const exhausted = attempts >= WEBHOOK_MAX_ATTEMPTS;
+            await this.db.transaction(async (trx) => {
+                await trx('webhook_deliveries')
+                    .where('id', row.id)
+                    .update({
+                    status: exhausted ? 'failed' : 'pending',
+                    attempts,
+                    last_status: status,
+                    last_error: error,
+                    next_attempt_at: exhausted
+                        ? trx.fn.now()
+                        : trx.raw(`now() + interval '${BACKOFF_MINUTES[attempts - 1]} minutes'`),
+                });
+                if (exhausted) {
+                    await trx('webhooks').where('id', row.webhook_id).increment('failing', 1);
+                    if (row.created_by)
+                        await notifyWithTemplate(trx, Number(row.created_by), 'webhook.failed', {
+                            name: row.name,
+                            event: row.event,
+                            error,
+                        });
+                }
+            });
+        }
+        return { delivered, failed };
+    }
+    async validate(input) {
+        const name = typeof input.name === 'string' ? input.name.trim() : '';
+        if (!name || name.length > NAME_LIMIT)
+            throw new KitError(422, 'E_WEBHOOK_NAME', 'الاسم مطلوب ولا يتجاوز 100 حرف');
+        const url = typeof input.url === 'string' ? input.url.trim() : '';
+        await this.assertTarget(url);
+        const known = new Set(this.events().map((event) => event.key));
+        if (!Array.isArray(input.events) ||
+            !input.events.length ||
+            input.events.length > 100 ||
+            !input.events.every((event) => typeof event === 'string' && known.has(event)))
+            throw new KitError(422, 'E_WEBHOOK_EVENTS', 'اختر حدثاً واحداً على الأقل من الأحداث المعروفة');
+        return { name, url, events: JSON.stringify([...new Set(input.events)]) };
+    }
+    /** Refuses non-HTTPS URLs and hosts resolving to private addresses (SSRF). */
+    async assertTarget(value) {
+        let url;
+        try {
+            url = new URL(value);
+        }
+        catch {
+            throw new KitError(422, 'E_WEBHOOK_URL', 'عنوان URL غير صالح');
+        }
+        const allowPrivate = this.options.allowPrivateTargets === true;
+        if (url.protocol !== 'https:' && !(allowPrivate && url.protocol === 'http:'))
+            throw new KitError(422, 'E_WEBHOOK_URL', 'يجب أن يبدأ العنوان بـ https://');
+        if (url.username || url.password || value.length > 2000)
+            throw new KitError(422, 'E_WEBHOOK_URL', 'عنوان URL غير مسموح');
+        if (allowPrivate)
+            return;
+        const host = url.hostname.replace(/^\[|\]$/g, '');
+        const addresses = isIP(host)
+            ? [host]
+            : await (this.options.resolve ??
+                (async (name) => {
+                    const entries = await lookup(name, { all: true });
+                    return entries.map((entry) => entry.address);
+                }))(host).catch(() => []);
+        if (!addresses.length || addresses.some(privateAddress))
+            throw new KitError(422, 'E_WEBHOOK_URL', 'لا يُسمح بعناوين الشبكة الداخلية');
+    }
+    present(row) {
+        return {
+            id: Number(row.id),
+            name: String(row.name),
+            url: String(row.url),
+            events: Array.isArray(row.events) ? row.events.map(String) : [],
+            active: Boolean(row.active),
+            createdAt: new Date(row.created_at).toISOString(),
+            lastDeliveryAt: row.last_delivery_at ? new Date(row.last_delivery_at).toISOString() : null,
+            failing: Number(row.failing ?? 0),
+        };
+    }
+}

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

@@ -1,4 +1,5 @@
 import type { Field, Resource, ResourceInput } from './types.js';
 export declare function identifier(value: string): string;
+/** camelCase field key → snake_case column; validated once and memoized (hot in row mapping). */
 export declare function columnName(name: string): string;
 export declare function defineResource<const F extends Record<string, Field>>(input: ResourceInput<F>): ResourceInput<F> & Resource;

package/build/src/resource/define_resource.js

@@ -3,8 +3,16 @@ export function identifier(value) {
         throw new Error(`Unsafe SQL identifier: ${value}`);
     return value;
 }
+const columns = new Map();
+/** camelCase field key → snake_case column; validated once and memoized (hot in row mapping). */
 export function columnName(name) {
-    return identifier(name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`));
+    const cached = columns.get(name);
+    if (cached !== undefined)
+        return cached;
+    const column = identifier(name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`));
+    if (columns.size < 10000)
+        columns.set(name, column);
+    return column;
 }
 export function defineResource(input) {
     identifier(input.name);

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

@@ -6,4 +6,6 @@ export declare class ResourceRegistry {
     all(): Resource[];
     owner(name: string): string;
     modules(): Module[];
+    /** Workflow definitions declared by registered modules, validated against their resources. */
+    workflows(): import("../workflows/define_workflow.ts").WorkflowDefinition[];
 }

package/build/src/resource/registry.js

@@ -56,4 +56,13 @@ export class ResourceRegistry {
     modules() {
         return [...this.#modules.values()];
     }
+    /** Workflow definitions declared by registered modules, validated against their resources. */
+    workflows() {
+        return this.modules().flatMap((module) => {
+            for (const workflow of module.workflows ?? [])
+                if (this.owner(workflow.resource) !== module.name)
+                    throw new Error(`Workflow ${workflow.name} must belong to the module of ${workflow.resource}`);
+            return [...(module.workflows ?? [])];
+        });
+    }
 }

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

@@ -1,5 +1,6 @@
 import type { Knex } from 'knex';
 import type { LucidModel } from '@adonisjs/lucid/types/model';
+import type { WorkflowDefinition } from '../workflows/define_workflow.js';
 export type Label = {
     ar: string;
     en: string;
@@ -22,7 +23,16 @@ export type Field = {
     permissionLevel?: number;
     sequence?: string;
 } & ({
-    type: 'string' | 'text' | 'integer' | 'money' | 'boolean' | 'date' | 'datetime' | 'json' | 'attachment';
+    type: 'string' | 'text' | 'integer' | 'money' | 'boolean' | 'date' | 'datetime' | 'json';
+} | {
+    type: 'attachment';
+    /**
+     * Lower-case file extensions accepted for upload, or 'any'. Defaults to
+     * DEFAULT_ATTACHMENT_EXTENSIONS (documents, images and archives).
+     */
+    accept?: string[] | 'any';
+    /** Upload size limit such as '5mb'. Defaults to '20mb'. */
+    maxSize?: string;
 } | {
     type: 'belongsTo';
     resource: string;
@@ -69,6 +79,8 @@ export type Module = {
     label: Label;
     dependsOn: readonly string[];
     resources: readonly Resource[];
+    /** Versioned workflows of this module's submittable resources (phase 4). */
+    workflows?: readonly WorkflowDefinition[];
 };
 export type ResourceInput<F extends Record<string, Field>> = Omit<Resource, 'fields' | 'list' | 'form' | 'show' | 'hidden' | 'serialize'> & {
     fields: F;