@cosmicdrift/kumiko-bundled-features 0.398.0 → 0.400.0

package/dist/documents/entity.d.ts

@@ -0,0 +1,76 @@
+import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export type DocumentEntityOptions = {
+    readonly categories: readonly [string, ...string[]];
+    readonly adminRoles: readonly string[];
+    readonly readAccess?: NonNullable<EntityDefinition["access"]>["read"];
+    readonly retention?: EntityDefinition["retention"];
+};
+export declare function createDocumentEntity(options: DocumentEntityOptions): EntityDefinition<{
+    readonly title: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: true;
+    };
+    readonly category: {
+        readonly type: "select";
+        readonly description?: string;
+        readonly options: readonly [string, ...string[]];
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly sortNulls?: import("@cosmicdrift/kumiko-types/fields").SortNulls;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly default?: string | undefined;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly display?: "radio" | "dropdown";
+        readonly optionTones?: {
+            readonly [x: string]: "accent" | "bad" | "critical" | "neutral" | "ok" | "warn" | undefined;
+        } | undefined;
+        readonly optionsQuery?: string;
+        readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
+        readonly optionsAvailabilityQuery?: string;
+        readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<string>[] | undefined;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
+        required: true;
+    };
+    readonly issuedAt: {
+        readonly type: "date";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly sortNulls?: import("@cosmicdrift/kumiko-types/fields").SortNulls;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly min?: string;
+        readonly max?: string;
+        readonly locale?: string;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
+        required: false;
+    };
+    readonly validUntil: {
+        readonly type: "date";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly sortNulls?: import("@cosmicdrift/kumiko-types/fields").SortNulls;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+        readonly min?: string;
+        readonly max?: string;
+        readonly locale?: string;
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
+        required: false;
+    };
+    readonly file: import("@cosmicdrift/kumiko-types/fields").FileFieldDef;
+}, "tenant">;
+export declare function createDocumentLinkEntity(linkTargets: readonly string[]): EntityDefinition<{
+    readonly documentId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: true;
+    };
+    readonly entityType: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: true;
+    };
+    readonly entityId: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
+        required: true;
+    };
+}, "tenant">;

package/dist/documents/entity.js

@@ -0,0 +1,84 @@
+import { sql } from "@cosmicdrift/kumiko-framework/db";
+import { createDateField, createEntity, createFileField, createSelectField, createTextField, SYSTEM_ROLE, } from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENT_LINK_ENTITY } from "./constants.js";
+// Readable only through a link to a host the viewer can read, and only when the file's owner is
+// readable too (see EntityDefinition.readGate); readAccess narrows further.
+export function createDocumentEntity(options) {
+    return createEntity({
+        table: "read_filed_documents",
+        softDelete: true,
+        description: "A filed document: title, category, issue and expiry dates and one file. It is visible only through its links to other records and the owner of its file; the file may stay owned by the record it came from.",
+        // The system user passes the gate; the capture and import checks run as it and would
+        // otherwise miss a document that readAccess hides.
+        ...(options.readAccess !== undefined && {
+            access: { read: { ...options.readAccess, [SYSTEM_ROLE]: "all" } },
+        }),
+        ...(options.retention !== undefined && { retention: options.retention }),
+        readGate: {
+            anyLink: { entity: DOCUMENT_LINK_ENTITY, field: "documentId" },
+            fileOwner: { field: "file" },
+            linkExemptRoles: options.adminRoles,
+        },
+        fields: {
+            title: createTextField({
+                required: true,
+                maxLength: 200,
+                sortable: true,
+                searchable: true,
+                personal: false,
+                reason: "document_title",
+            }),
+            category: createSelectField({
+                options: options.categories,
+                required: true,
+                filterable: true,
+                sortable: true,
+            }),
+            issuedAt: createDateField({ sortable: true }),
+            validUntil: createDateField({ sortable: true, filterable: true }),
+            // Filed business documents belong to the tenant, not to one person.
+            file: createFileField({ required: true, personal: false, reason: "is_business_data" }),
+        },
+        // One live document per file; a deleted one releases the file.
+        indexes: [
+            {
+                columns: ["tenantId", "file"],
+                unique: true,
+                name: "read_filed_documents_file_unique",
+                where: sql `"is_deleted" = false`,
+            },
+        ],
+    });
+}
+export function createDocumentLinkEntity(linkTargets) {
+    return createEntity({
+        table: "read_filed_document_links",
+        softDelete: true,
+        description: "The join row recording that one document belongs to one record, addressed by documentId, entityType and entityId, with exactly one row per triple. A document is visible to whoever can read at least one of its linked records.",
+        parentRef: {
+            entityTypeField: "entityType",
+            entityIdField: "entityId",
+            allowedTypes: linkTargets,
+        },
+        fields: {
+            documentId: createTextField({
+                required: true,
+                maxLength: 64,
+                personal: false,
+                reason: "technical_reference",
+            }),
+            entityType: createTextField({
+                required: true,
+                maxLength: 64,
+                personal: false,
+                reason: "technical_reference",
+            }),
+            entityId: createTextField({
+                required: true,
+                maxLength: 128,
+                personal: false,
+                reason: "technical_reference",
+            }),
+        },
+    });
+}

package/dist/documents/executor.d.ts

@@ -0,0 +1,6 @@
+import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createDocumentExecutors(documentEntity: EntityDefinition, linkEntity: EntityDefinition): {
+    document: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<Record<string, unknown>>;
+    link: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor<Record<string, unknown>>;
+};
+export type DocumentExecutors = ReturnType<typeof createDocumentExecutors>;

package/dist/documents/executor.js

@@ -0,0 +1,8 @@
+import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
+import { DOCUMENT_ENTITY, DOCUMENT_LINK_ENTITY } from "./constants.js";
+export function createDocumentExecutors(documentEntity, linkEntity) {
+    return {
+        document: createEntityExecutor(DOCUMENT_ENTITY, documentEntity).executor,
+        link: createEntityExecutor(DOCUMENT_LINK_ENTITY, linkEntity).executor,
+    };
+}

package/dist/documents/expiry.d.ts

@@ -0,0 +1,9 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { ExpiryState } from "./constants.ts";
+export type ExpiryWindow = {
+    readonly today: string;
+    /** Last day (inclusive) that still counts as "expiring". */
+    readonly horizon: string;
+};
+export declare function expiryWindow(ctx: Pick<HandlerContext, "tz">, expiringWithinDays: number): ExpiryWindow;
+export declare function expiryStateOf(validUntil: unknown, window: ExpiryWindow): ExpiryState;

package/dist/documents/expiry.js

@@ -0,0 +1,20 @@
+// One definition of the boundaries for the counts and for the per-row state, so the
+// overview column and the expiry-overview buckets cannot drift apart.
+export function expiryWindow(ctx, expiringWithinDays) {
+    const today = ctx.tz.today(ctx.tz.tenant);
+    return { today: today.toString(), horizon: today.add({ days: expiringWithinDays }).toString() };
+}
+// In-process dispatch hands back the date as a PlainDate, the wire form is an ISO string.
+// ISO dates compare correctly as strings; a missing date is "none", not "valid".
+export function expiryStateOf(validUntil, window) {
+    const day = validUntil instanceof Temporal.PlainDate
+        ? validUntil.toString()
+        : typeof validUntil === "string"
+            ? validUntil.slice(0, 10)
+            : "";
+    if (day === "")
+        return "none";
+    if (day < window.today)
+        return "expired";
+    return day <= window.horizon ? "expiring" : "valid";
+}

package/dist/documents/feature.d.ts

@@ -0,0 +1,33 @@
+import { type AccessRule, type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { type DocumentCaptureRule } from "./capture.ts";
+export type DocumentsFeatureOptions = {
+    /** Allowed document categories; they become the options of the category field. */
+    readonly categories: readonly [string, ...string[]];
+    /** Entities a document can be linked to. Each needs an update handler, which linking requires. */
+    readonly linkTargets: readonly [string, ...string[]];
+    /** Files saved into these fields become documents automatically. */
+    readonly capture?: readonly DocumentCaptureRule[];
+    /** Retention of the document rows, in the entity's own retention vocabulary. */
+    readonly retention?: EntityDefinition["retention"];
+    /** Row-level read rule on the document, AND-ed with the link and file-owner gate. */
+    readonly readAccess?: NonNullable<EntityDefinition["access"]>["read"];
+    /**
+     * Who may use the document handlers. One rule applies to read, write and delete; the split form
+     * sets them apart. Default TenantAdmin and TenantMember; a missing delete follows write.
+     */
+    readonly access?: AccessRule | DocumentsAccess;
+    /** Roles that see every document of their tenant whose file owner they can read, without a link. */
+    readonly adminRoles?: readonly string[];
+    /** Window of the "expiring" bucket in expiry-overview. Default 30 days. */
+    readonly expiringWithinDays?: number;
+};
+export type DocumentsAccess = {
+    /** Lists, detail, for-record, the overviews and the list screen. */
+    readonly read?: AccessRule;
+    /** Create, update, link and unlink. */
+    readonly write?: AccessRule;
+    readonly delete?: AccessRule;
+};
+export declare function createDocumentsFeature(opts: DocumentsFeatureOptions): import("@cosmicdrift/kumiko-types/feature").FeatureDefinition & {
+    readonly exports: void;
+};

package/dist/documents/feature.js

@@ -0,0 +1,111 @@
+// documents — filed documents (title, category, validity, one file) that become visible on other
+// records through link rows. A document is readable only through a record the viewer can read,
+// and only while the owner of its file is readable too (EntityDefinition.readGate). Documents
+// come from capture rules (a file saved into a configured field) or from the system-only import.
+import { defineEntityCreateHandler, defineEntityDeleteHandler, defineEntityDetailHandler, defineEntityListHandler, defineEntityUpdateHandler, defineFeature, } from "@cosmicdrift/kumiko-framework/engine";
+import { registerCapture, validateCaptureRules } from "./capture.js";
+import { DEFAULT_ADMIN_ROLES, DEFAULT_DOCUMENT_ACCESS, DEFAULT_EXPIRING_WITHIN_DAYS, DOCUMENT_ENTITY, DOCUMENT_LINK_ENTITY, DOCUMENTS_FEATURE_NAME, } from "./constants.js";
+import { createDocumentEntity, createDocumentLinkEntity } from "./entity.js";
+import { createDocumentExecutors } from "./executor.js";
+import { createImportDocumentHandler } from "./handlers/import.write.js";
+import { createLinkDocumentHandler, createUnlinkDocumentHandler } from "./handlers/link.write.js";
+import { DOCUMENTS_FEATURE_I18N } from "./i18n.js";
+import { rejectForeignPendingFile } from "./pending-file-guard.js";
+import { createExpiryOverviewQuery } from "./queries/expiry-overview.query.js";
+import { createForRecordQuery, createForTypeQuery } from "./queries/for-record.query.js";
+import { createOverviewQuery } from "./queries/overview.query.js";
+import { createDocumentListScreen } from "./screens.js";
+import { createDocumentWriteGuard } from "./write-guard.js";
+function isAccessRule(access) {
+    return "roles" in access || "openToAll" in access;
+}
+function resolveAccess(access) {
+    if (access === undefined) {
+        return {
+            read: DEFAULT_DOCUMENT_ACCESS,
+            write: DEFAULT_DOCUMENT_ACCESS,
+            delete: DEFAULT_DOCUMENT_ACCESS,
+        };
+    }
+    if (isAccessRule(access))
+        return { read: access, write: access, delete: access };
+    const write = access.write ?? DEFAULT_DOCUMENT_ACCESS;
+    return { read: access.read ?? DEFAULT_DOCUMENT_ACCESS, write, delete: access.delete ?? write };
+}
+function categoryOptionLabels(categories) {
+    return Object.fromEntries(categories.map((category) => [
+        `documents:entity:filed-document:field:category:option:${category}`,
+        { en: category, de: category },
+    ]));
+}
+function registerDocuments(r, opts) {
+    const access = resolveAccess(opts.access);
+    const linkTargets = opts.linkTargets;
+    const documentEntity = createDocumentEntity({
+        categories: opts.categories,
+        adminRoles: opts.adminRoles ?? DEFAULT_ADMIN_ROLES,
+        ...(opts.readAccess !== undefined && { readAccess: opts.readAccess }),
+        ...(opts.retention !== undefined && { retention: opts.retention }),
+    });
+    const linkEntity = createDocumentLinkEntity(linkTargets);
+    const executors = createDocumentExecutors(documentEntity, linkEntity);
+    r.requires({ features: ["files"] });
+    r.adoptsBundledLists();
+    r.describe("Filed documents with title, category, issue and expiry date and one file, shown on the records they are linked to. A document is visible only through a linked record the viewer can read, and only while the record that owns its file is readable too, so linking never widens access to the file. Documents arrive through capture rules (a file saved into a configured field) or through the system-only import for migrations, which keeps the caller's id, refuses an id another record already uses, and stamps createdAt with the import time (issuedAt carries the business date; the event store does not backdate); users link, unlink, edit and delete them. Read a record's documents with for-record, count expired and expiring ones with expiry-overview, list them with an expiry state and an expiring filter with overview (the documents list screen), and add the documents tab to a record screen with documentsTab().");
+    r.uiHints({ displayLabel: "Documents", category: "data", recommended: false });
+    r.entity({ name: DOCUMENT_ENTITY, ...documentEntity });
+    r.entity({ name: DOCUMENT_LINK_ENTITY, ...linkEntity });
+    r.writeHandler(defineEntityCreateHandler(DOCUMENT_ENTITY, documentEntity, {
+        access: access.write,
+        description: "Files a new document from an uploaded file; it stays invisible to everyone but the admin roles until it is linked to a record.",
+    }));
+    const writeGuard = createDocumentWriteGuard(executors, opts.adminRoles ?? DEFAULT_ADMIN_ROLES);
+    r.writeHandler(defineEntityUpdateHandler(DOCUMENT_ENTITY, documentEntity, {
+        access: access.write,
+        description: "Edits a document's title, category and dates from the entity-edit envelope; it does not change what the document is linked to.",
+    }));
+    r.writeHandler(defineEntityDeleteHandler(DOCUMENT_ENTITY, documentEntity, {
+        access: access.delete,
+        description: "Deletes a document so it disappears from every record it was linked to; the file itself stays with its owner.",
+        agent: { risk: "high" },
+    }));
+    r.hook({ type: "preSave", target: "filed-document:create", handler: rejectForeignPendingFile });
+    r.hook({ type: "preSave", target: "filed-document:update", handler: rejectForeignPendingFile });
+    r.hook({ type: "preSave", target: "filed-document:update", handler: writeGuard.beforeUpdate });
+    r.hook({ type: "preDelete", target: "filed-document:delete", handler: writeGuard.beforeDelete });
+    r.writeHandler(createLinkDocumentHandler({ access: access.write, executors, linkTargets }));
+    r.writeHandler(createUnlinkDocumentHandler({ access: access.write, executors, linkTargets }));
+    r.writeHandler(createImportDocumentHandler({ executors, categories: opts.categories, linkTargets }));
+    r.queryHandler(defineEntityListHandler(DOCUMENT_ENTITY, documentEntity, {
+        access: access.read,
+        description: "Lists the documents the caller can read, filterable by category and validity date; use for-record to list one record's documents.",
+    }));
+    r.queryHandler(defineEntityDetailHandler(DOCUMENT_ENTITY, documentEntity, {
+        access: access.read,
+        description: "Reads one document the caller can read, with its file reference and dates.",
+    }));
+    r.queryHandler(defineEntityListHandler(DOCUMENT_LINK_ENTITY, linkEntity, {
+        access: access.read,
+        description: "Lists the document-to-record link rows whose record the caller can read; filter on entityId for one record's links.",
+    }));
+    r.queryHandler(createForRecordQuery(access.read, linkTargets));
+    for (const entityType of linkTargets) {
+        r.queryHandler(createForTypeQuery(access.read, linkTargets, entityType));
+    }
+    const expiringWithinDays = opts.expiringWithinDays ?? DEFAULT_EXPIRING_WITHIN_DAYS;
+    r.queryHandler(createExpiryOverviewQuery(access.read, expiringWithinDays));
+    r.queryHandler(createOverviewQuery(access.read, expiringWithinDays));
+    const capture = opts.capture ?? [];
+    registerCapture(r, executors, capture, linkTargets);
+    r.bootCheck((ctx) => validateCaptureRules(ctx, capture, opts.categories, linkTargets));
+    r.screen(createDocumentListScreen(access.read, opts.categories));
+    r.translations({
+        keys: { ...DOCUMENTS_FEATURE_I18N, ...categoryOptionLabels(opts.categories) },
+    });
+}
+export function createDocumentsFeature(opts) {
+    if (opts.expiringWithinDays !== undefined && opts.expiringWithinDays < 0) {
+        throw new Error("createDocumentsFeature({ expiringWithinDays }) must not be negative.");
+    }
+    return defineFeature(DOCUMENTS_FEATURE_NAME, (r) => registerDocuments(r, opts));
+}

package/dist/documents/handlers/import.write.d.ts

@@ -0,0 +1,23 @@
+import type { DocumentExecutors } from "../executor.ts";
+type ImportArgs = {
+    readonly executors: DocumentExecutors;
+    readonly categories: readonly string[];
+    readonly linkTargets: readonly string[];
+};
+export declare function createImportDocumentHandler(args: ImportArgs): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"import", import("zod").ZodObject<{
+    id: import("zod").ZodUUID;
+    title: import("zod").ZodString;
+    category: import("zod").ZodString;
+    issuedAt: import("zod").ZodOptional<import("zod").ZodISODate>;
+    validUntil: import("zod").ZodOptional<import("zod").ZodISODate>;
+    fileRefId: import("zod").ZodUUID;
+    links: import("zod").ZodArray<import("zod").ZodObject<{
+        entityType: import("zod").ZodString;
+        entityId: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>;
+    deleted: import("zod").ZodOptional<import("zod").ZodBoolean>;
+}, import("zod/v4/core").$strip>, {
+    id: string;
+    entity: string;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;
+export {};

package/dist/documents/handlers/import.write.js

@@ -0,0 +1,104 @@
+import { createEntityExecutor, defineWriteHandler, SYSTEM_ROLE, } from "@cosmicdrift/kumiko-framework/engine";
+import { ConflictError, NotFoundError, ValidationError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
+import { FILE_REF_ENTITY_NAME } from "@cosmicdrift/kumiko-framework/files";
+import { DOCUMENT_ENTITY } from "../constants.js";
+import { ensureDocumentLink } from "../ensure-link.js";
+import { importDocumentPayloadSchema } from "../schemas.js";
+async function fileRefExists(registry, fileRefId, user, db) {
+    const entity = registry.getEntity(FILE_REF_ENTITY_NAME);
+    if (entity === undefined)
+        return false;
+    const row = await createEntityExecutor(FILE_REF_ENTITY_NAME, entity).executor.detail({ id: fileRefId }, user, db);
+    return row !== null;
+}
+// The stream, not the projected row: a row-level readAccess can hide a document from the system
+// user, and a deleted document still has its stream.
+async function streamTypeOf(events, id) {
+    const [first] = await events.load(id, { atVersion: 1 });
+    return first?.aggregateType;
+}
+// undefined: the document exists now, created here or by an earlier run of the same import.
+async function createUnlessImported(executors, events, payload, user, db) {
+    const existingType = await streamTypeOf(events, payload.id);
+    if (existingType === undefined) {
+        const created = await executors.document.create({
+            id: payload.id,
+            title: payload.title,
+            category: payload.category,
+            file: payload.fileRefId,
+            ...(payload.issuedAt !== undefined && { issuedAt: payload.issuedAt }),
+            ...(payload.validUntil !== undefined && { validUntil: payload.validUntil }),
+        }, user, db);
+        if (created.isSuccess)
+            return undefined;
+        if (created.error.code !== "version_conflict")
+            return created;
+    }
+    // Stream ids are unique per tenant across aggregate types: an existing stream is the retry of
+    // this import only when it is a document, otherwise linking would point at nothing.
+    const streamType = existingType ?? (await streamTypeOf(events, payload.id));
+    if (streamType === DOCUMENT_ENTITY)
+        return undefined;
+    return writeFailure(new ConflictError({
+        message: `documents import: id ${payload.id} belongs to another record`,
+        i18nKey: "documents.errors.import-id-taken",
+        details: { id: payload.id },
+    }));
+}
+// For one-off migrations run as a job: the caller picks the document id, so a re-run converges
+// on the same document instead of duplicating it. Never callable by a user.
+export function createImportDocumentHandler(args) {
+    const { executors, categories, linkTargets } = args;
+    return defineWriteHandler({
+        name: "import",
+        schema: importDocumentPayloadSchema,
+        access: { roles: [SYSTEM_ROLE] },
+        agent: { expose: false },
+        description: "Creates a document with a caller-chosen id from an existing file, links it to the given records and optionally leaves it deleted; a repeat call with the same id changes nothing, and an id already used by another record fails. The document's createdAt is the time of the import; issuedAt carries the business date. Reserved for the system user, meant for data migrations.",
+        handler: async (event, ctx) => {
+            const payload = event.payload;
+            if (!categories.includes(payload.category)) {
+                return writeFailure(new ValidationError({
+                    fields: [
+                        {
+                            path: "category",
+                            code: "unknown_category",
+                            i18nKey: "documents.errors.unknown-category",
+                            params: { category: payload.category },
+                        },
+                    ],
+                }));
+            }
+            const badTarget = payload.links.find((link) => !linkTargets.includes(link.entityType));
+            if (badTarget !== undefined) {
+                return writeFailure(new ValidationError({
+                    fields: [
+                        {
+                            path: "links",
+                            code: "unknown_link_target",
+                            i18nKey: "documents.errors.unknown-link-target",
+                            params: { entityType: badTarget.entityType },
+                        },
+                    ],
+                }));
+            }
+            if (!(await fileRefExists(ctx.registry, payload.fileRefId, event.user, ctx.db))) {
+                return writeFailure(new NotFoundError(FILE_REF_ENTITY_NAME, payload.fileRefId));
+            }
+            const notImported = await createUnlessImported(executors, ctx.events, payload, event.user, ctx.db);
+            if (notImported !== undefined)
+                return notImported;
+            for (const link of payload.links) {
+                const linked = await ensureDocumentLink(executors, event.user, ctx.db, payload.id, link);
+                if (!linked.isSuccess)
+                    return linked;
+            }
+            if (payload.deleted === true) {
+                const removed = await executors.document.delete({ id: payload.id }, event.user, ctx.db);
+                if (!removed.isSuccess && removed.error.code !== "not_found")
+                    return removed;
+            }
+            return { isSuccess: true, data: { id: payload.id, entity: DOCUMENT_ENTITY } };
+        },
+    });
+}

package/dist/documents/handlers/link.write.d.ts

@@ -0,0 +1,18 @@
+import { type AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+import type { DocumentExecutors } from "../executor.ts";
+type LinkHandlerArgs = {
+    readonly access: AccessRule;
+    readonly executors: DocumentExecutors;
+    readonly linkTargets: readonly string[];
+};
+export declare function createLinkDocumentHandler(args: LinkHandlerArgs): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"link", import("zod").ZodObject<{
+    documentId: import("zod").ZodUUID;
+    entityType: import("zod").ZodString;
+    entityId: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, unknown, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;
+export declare function createUnlinkDocumentHandler(args: LinkHandlerArgs): import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"unlink", import("zod").ZodObject<{
+    documentId: import("zod").ZodUUID;
+    entityType: import("zod").ZodString;
+    entityId: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, unknown, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined, undefined>;
+export {};

package/dist/documents/handlers/link.write.js

@@ -0,0 +1,61 @@
+import { defineWriteHandler, parentVisibilityFor, } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { documentLinkAggregateId } from "../aggregate-id.js";
+import { DOCUMENT_ENTITY } from "../constants.js";
+import { ensureDocumentLink } from "../ensure-link.js";
+import { documentLinkPayloadSchema } from "../schemas.js";
+import { canWriteLinkTarget } from "../target-write-check.js";
+// Unreadable document, foreign target type and unwritable target answer alike (not found), so
+// the call is no probe for what exists.
+export function createLinkDocumentHandler(args) {
+    const { access, executors, linkTargets } = args;
+    return defineWriteHandler({
+        name: "link",
+        schema: documentLinkPayloadSchema,
+        access,
+        description: "Makes a document visible on another record by linking it to that record; the caller must be able to read the document and edit the record.",
+        handler: async (event, ctx) => {
+            const payload = event.payload;
+            const notFound = () => writeFailure(new NotFoundError(DOCUMENT_ENTITY, payload.documentId));
+            if (!linkTargets.includes(payload.entityType))
+                return notFound();
+            const document = await executors.document.detail({ id: payload.documentId }, event.user, ctx.db, {
+                parentVisibility: parentVisibilityFor(ctx, event.user),
+            });
+            if (document === null)
+                return notFound();
+            if (!(await canWriteLinkTarget(ctx.registry, payload.entityType, payload.entityId, event.user, ctx.db))) {
+                return notFound();
+            }
+            return ensureDocumentLink(executors, event.user, ctx.db, payload.documentId, payload);
+        },
+    });
+}
+export function createUnlinkDocumentHandler(args) {
+    const { access, executors, linkTargets } = args;
+    return defineWriteHandler({
+        name: "unlink",
+        schema: documentLinkPayloadSchema,
+        access,
+        description: "Removes a document from a record it was linked to, reporting success when no link existed; the document and its file stay.",
+        handler: async (event, ctx) => {
+            const payload = event.payload;
+            const notFound = () => writeFailure(new NotFoundError(DOCUMENT_ENTITY, payload.documentId));
+            if (!linkTargets.includes(payload.entityType))
+                return notFound();
+            const document = await executors.document.detail({ id: payload.documentId }, event.user, ctx.db, {
+                parentVisibility: parentVisibilityFor(ctx, event.user),
+            });
+            if (document === null)
+                return notFound();
+            if (!(await canWriteLinkTarget(ctx.registry, payload.entityType, payload.entityId, event.user, ctx.db))) {
+                return notFound();
+            }
+            const id = documentLinkAggregateId(event.user.tenantId, payload.documentId, payload.entityType, payload.entityId);
+            const existing = await executors.link.detail({ id }, event.user, ctx.db);
+            if (existing === null)
+                return { isSuccess: true, data: { id } };
+            return executors.link.delete({ id }, event.user, ctx.db);
+        },
+    });
+}

package/dist/documents/i18n.d.ts

@@ -0,0 +1,6 @@
+type LocalizedString = {
+    readonly en: string;
+    readonly de: string;
+};
+export declare const DOCUMENTS_FEATURE_I18N: Readonly<Record<string, LocalizedString>>;
+export {};

package/dist/documents/i18n.js

@@ -0,0 +1,33 @@
+export const DOCUMENTS_FEATURE_I18N = {
+    "documents:feature.label": { en: "Documents", de: "Dokumente" },
+    "screen:list.title": { en: "Documents", de: "Dokumente" },
+    "documents:tab.title": { en: "Documents", de: "Dokumente" },
+    "documents:overview.expired": { en: "Expired documents", de: "Abgelaufene Dokumente" },
+    "documents:overview.expiring": { en: "Documents expiring soon", de: "Bald ablaufende Dokumente" },
+    "documents:entity:filed-document:field:title": { en: "Title", de: "Titel" },
+    "documents:entity:filed-document:field:category": { en: "Category", de: "Kategorie" },
+    "documents:entity:filed-document:field:issuedAt": { en: "Issued", de: "Ausgestellt" },
+    "documents:entity:filed-document:field:validUntil": { en: "Valid until", de: "Gültig bis" },
+    "documents:entity:filed-document:field:file": { en: "File", de: "Datei" },
+    "documents:list.facet.expiry": { en: "Expiry", de: "Ablauf" },
+    "documents:list.facet.expiring": {
+        en: "Expired or expiring soon",
+        de: "Abgelaufen oder bald ablaufend",
+    },
+    "documents:list.expiry.expired": { en: "Expired", de: "Abgelaufen" },
+    "documents:list.expiry.expiring": { en: "Expiring soon", de: "Läuft bald ab" },
+    "documents:list.expiry.valid": { en: "Valid", de: "Gültig" },
+    "documents:list.expiry.none": { en: "No expiry date", de: "Ohne Ablaufdatum" },
+    "documents.errors.unknown-category": {
+        en: "Unknown document category",
+        de: "Unbekannte Dokumentenkategorie",
+    },
+    "documents.errors.unknown-link-target": {
+        en: "This record type takes no documents",
+        de: "Diesem Datensatztyp lassen sich keine Dokumente zuordnen",
+    },
+    "documents.errors.import-id-taken": {
+        en: "This id already belongs to another record",
+        de: "Diese ID gehört bereits zu einem anderen Datensatz",
+    },
+};

package/dist/documents/index.d.ts

@@ -0,0 +1,7 @@
+export { documentIdForFile, documentLinkAggregateId } from "./aggregate-id.ts";
+export type { DocumentCaptureRule } from "./capture.ts";
+export { DEFAULT_ADMIN_ROLES, DEFAULT_DOCUMENT_ACCESS, DOCUMENT_ENTITY, DOCUMENT_LINK_ENTITY, DOCUMENTS_FEATURE_NAME, DOCUMENTS_LIST_SCREEN_ID, DocumentsHandlers, DocumentsQueries, EXPIRY_STATES, type ExpiryState, } from "./constants.ts";
+export { createDocumentsFeature, type DocumentsAccess, type DocumentsFeatureOptions, } from "./feature.ts";
+export { forTypeQueryQn } from "./queries/for-record.query.ts";
+export { DOCUMENT_COLUMNS } from "./screens.ts";
+export { documentExpiryPanels, documentsTab } from "./tab.ts";

package/dist/documents/index.js

@@ -0,0 +1,6 @@
+export { documentIdForFile, documentLinkAggregateId } from "./aggregate-id.js";
+export { DEFAULT_ADMIN_ROLES, DEFAULT_DOCUMENT_ACCESS, DOCUMENT_ENTITY, DOCUMENT_LINK_ENTITY, DOCUMENTS_FEATURE_NAME, DOCUMENTS_LIST_SCREEN_ID, DocumentsHandlers, DocumentsQueries, EXPIRY_STATES, } from "./constants.js";
+export { createDocumentsFeature, } from "./feature.js";
+export { forTypeQueryQn } from "./queries/for-record.query.js";
+export { DOCUMENT_COLUMNS } from "./screens.js";
+export { documentExpiryPanels, documentsTab } from "./tab.js";

package/dist/documents/pending-file-guard.d.ts

@@ -0,0 +1,2 @@
+import { type PreSaveHookFn } from "@cosmicdrift/kumiko-framework/engine";
+export declare const rejectForeignPendingFile: PreSaveHookFn;