@adula/kit 0.2.0-alpha.4 → 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.d.ts

@@ -0,0 +1,39 @@
+import { type Actor } from '../auth/ability.js';
+import type { ResourceRegistry } from '../resource/registry.js';
+type Schema = Record<string, unknown>;
+/**
+ * OpenAPI 3.1 description of the resource API, generated from the registry. When
+ * an actor is given, only resources and actions it may use are described.
+ */
+export declare function openApiDocument(registry: ResourceRegistry, options: {
+    title: string;
+    version: string;
+    serverUrl: string;
+    basePath?: string;
+    /** Describe only what this actor may use (row conditions still apply at runtime). */
+    actor?: Actor;
+}): {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+    };
+    servers: {
+        url: string;
+    }[];
+    security: {
+        bearer: never[];
+    }[];
+    paths: Record<string, Schema>;
+    components: {
+        schemas: Record<string, Schema>;
+        securitySchemes: {
+            bearer: {
+                type: string;
+                scheme: string;
+                description: string;
+            };
+        };
+    };
+};
+export {};

package/build/src/integrations/openapi.js

@@ -0,0 +1,323 @@
+import { buildAbility } from '../auth/ability.js';
+function fieldSchema(field, mode, registry) {
+    const description = field.label.ar;
+    switch (field.type) {
+        case 'integer':
+            return { type: 'integer', description };
+        case 'money':
+            return {
+                type: 'string',
+                pattern: '^-?\\d+$',
+                description: `${description} (minor units as a decimal string)`,
+            };
+        case 'boolean':
+            return { type: 'boolean', description };
+        case 'date':
+            return { type: 'string', format: 'date', description };
+        case 'datetime':
+            return { type: 'string', format: 'date-time', description };
+        case 'json':
+            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':
+            return mode === 'write'
+                ? { type: 'integer', description: `${description} (id returned by POST /attachments)` }
+                : {
+                    type: 'object',
+                    description,
+                    properties: {
+                        id: { type: 'integer' },
+                        name: { type: 'string' },
+                        size: { type: 'integer' },
+                        mimeType: { type: 'string' },
+                    },
+                };
+        case 'hasMany': {
+            const child = registry.get(field.resource);
+            return {
+                type: 'array',
+                maxItems: 100,
+                description,
+                items: { $ref: `#/components/schemas/${child.name}_input` },
+            };
+        }
+        default:
+            return { type: 'string', description };
+    }
+}
+function nullable(schema, required) {
+    if (required)
+        return schema;
+    if (typeof schema.type === 'string')
+        return { ...schema, type: [schema.type, 'null'] };
+    return schema;
+}
+function schemas(resource, registry) {
+    const readKeys = (resource.serialize ?? [...new Set([...resource.list, ...resource.show])]).filter((key) => resource.fields[key]?.type !== 'hasMany');
+    const read = {
+        type: 'object',
+        description: `${resource.label.ar}. Fields the caller may not read are omitted.`,
+        properties: {
+            id: { type: 'integer' },
+            ...Object.fromEntries(readKeys.map((key) => [
+                key,
+                nullable(fieldSchema(resource.fields[key], 'read', registry), false),
+            ])),
+            ...(resource.version ? { version: { type: 'integer' } } : {}),
+            ...(resource.submittable
+                ? {
+                    docStatus: {
+                        type: 'integer',
+                        enum: [0, 1, 2],
+                        description: '0 draft, 1 submitted, 2 cancelled',
+                    },
+                }
+                : {}),
+            ...(resource.scoped ? { orgUnitId: { type: 'integer' } } : {}),
+        },
+        required: ['id'],
+    };
+    const writable = resource.form.filter((key) => !resource.fields[key].sequence);
+    const input = {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            ...Object.fromEntries(writable.map((key) => [
+                key,
+                nullable(fieldSchema(resource.fields[key], 'write', registry), Boolean(resource.fields[key].required)),
+            ])),
+            ...(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 && !resource.scope ? ['orgUnitId'] : []),
+        ],
+    };
+    return { read, input };
+}
+const error = {
+    description: 'Error',
+    content: {
+        'application/json': {
+            schema: {
+                type: 'object',
+                properties: {
+                    error: {
+                        type: 'object',
+                        properties: { code: { type: 'string' }, message: { type: 'string' } },
+                    },
+                },
+            },
+        },
+    },
+};
+/**
+ * OpenAPI 3.1 description of the resource API, generated from the registry. When
+ * an actor is given, only resources and actions it may use are described.
+ */
+export function openApiDocument(registry, options) {
+    const base = options.basePath ?? '/api/v1';
+    const paths = {};
+    const components = {};
+    const children = new Set(registry
+        .all()
+        .flatMap((resource) => Object.values(resource.fields).flatMap((field) => field.type === 'hasMany' ? [field.resource] : [])));
+    for (const resource of registry.all()) {
+        const ability = options.actor ? buildAbility(options.actor.rules, registry.all()) : undefined;
+        const allowed = new Set(resource.actions.filter((action) => !ability || ability.can(action, resource.name)));
+        if (ability && !allowed.has('view'))
+            continue;
+        const { read, input } = schemas(resource, registry);
+        components[resource.name] = read;
+        components[`${resource.name}_input`] = input;
+        if (children.has(resource.name))
+            continue;
+        const ref = { $ref: `#/components/schemas/${resource.name}` };
+        const inputRef = { $ref: `#/components/schemas/${resource.name}_input` };
+        const tag = resource.label.en;
+        const one = (description) => ({
+            description,
+            content: { 'application/json': { schema: { type: 'object', properties: { data: ref } } } },
+        });
+        const idParam = { name: 'id', in: 'path', required: true, schema: { type: 'integer' } };
+        const collection = {};
+        const item = {};
+        if (allowed.has('view')) {
+            collection.get = {
+                tags: [tag],
+                summary: `List ${resource.label.en}`,
+                parameters: [
+                    { name: 'limit', in: 'query', schema: { type: 'integer', maximum: 100 } },
+                    { name: 'cursor', in: 'query', schema: { type: 'string' } },
+                    { name: 'search', in: 'query', schema: { type: 'string' } },
+                    { name: 'sort', in: 'query', schema: { type: 'string' } },
+                    { name: 'direction', in: 'query', schema: { enum: ['asc', 'desc'] } },
+                    { name: 'tag', in: 'query', schema: { type: 'string' } },
+                ],
+                responses: {
+                    200: {
+                        description: 'Keyset page',
+                        content: {
+                            'application/json': {
+                                schema: {
+                                    type: 'object',
+                                    properties: {
+                                        data: { type: 'array', items: ref },
+                                        meta: {
+                                            type: 'object',
+                                            properties: {
+                                                limit: { type: 'integer' },
+                                                nextCursor: { type: ['string', 'null'] },
+                                                estimatedTotal: { type: 'integer' },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                    403: error,
+                },
+            };
+            item.get = {
+                tags: [tag],
+                summary: `Show one ${resource.label.en} record`,
+                parameters: [idParam],
+                responses: { 200: one('Record'), 403: error, 404: error },
+            };
+        }
+        if (allowed.has('create'))
+            collection.post = {
+                tags: [tag],
+                summary: `Create ${resource.label.en}`,
+                requestBody: { required: true, content: { 'application/json': { schema: inputRef } } },
+                responses: { 201: one('Created'), 403: error, 409: error, 422: error },
+            };
+        if (allowed.has('update'))
+            item.patch = {
+                tags: [tag],
+                summary: `Update ${resource.label.en}`,
+                parameters: [idParam],
+                requestBody: { required: true, content: { 'application/json': { schema: inputRef } } },
+                responses: { 200: one('Updated'), 403: error, 404: error, 409: error, 422: error },
+            };
+        if (allowed.has('delete'))
+            item.delete = {
+                tags: [tag],
+                summary: `Soft-delete ${resource.label.en}`,
+                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)
+            paths[`${base}/resources/${resource.name}/{id}`] = item;
+        for (const action of ['submit', 'cancel'])
+            if (resource.submittable && allowed.has(action))
+                paths[`${base}/resources/${resource.name}/{id}/${action}`] = {
+                    post: {
+                        tags: [tag],
+                        summary: `${action === 'submit' ? 'Submit' : 'Cancel'} ${resource.label.en}`,
+                        parameters: [idParam],
+                        requestBody: {
+                            content: {
+                                'application/json': {
+                                    schema: { type: 'object', properties: { version: { type: 'integer' } } },
+                                },
+                            },
+                        },
+                        responses: { 200: one('Transitioned'), 403: error, 404: error, 409: error },
+                    },
+                };
+    }
+    return {
+        openapi: '3.1.0',
+        info: { title: options.title, version: options.version },
+        servers: [{ url: options.serverUrl }],
+        security: [{ bearer: [] }],
+        paths,
+        components: {
+            schemas: components,
+            securitySchemes: {
+                bearer: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    description: 'Personal API token. Read tokens are limited to GET requests.',
+                },
+            },
+        },
+    };
+}

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

@@ -0,0 +1,37 @@
+import type { ResourceDescription } from '../admin/presentation.js';
+import type { SerializedRecord } from '../resource/types.js';
+export type PrintIdentity = {
+    name: string;
+    logoUrl?: string | null;
+};
+export type PrintInput = {
+    identity: PrintIdentity;
+    resource: ResourceDescription;
+    record: SerializedRecord;
+    related?: Record<string, SerializedRecord[]>;
+    lookups?: Record<string, {
+        value: string;
+        label: string;
+    }[]>;
+    children?: Record<string, {
+        rows: SerializedRecord[];
+        fields: ResourceDescription['fields'];
+    }>;
+    printedBy: string;
+    printedAt?: Date;
+};
+/**
+ * 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 declare function renderPrintHtml(input: PrintInput): string;
+/**
+ * Converts printable HTML to PDF with an optional Gotenberg service
+ * (POST /forms/chromium/convert/html). Without it, pages use the browser's print.
+ */
+export declare function htmlToPdf(html: string, options: {
+    gotenbergUrl: string;
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+}): Promise<Buffer<ArrayBuffer>>;