@cosmicdrift/kumiko-bundled-features 0.399.0 → 0.400.0

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;

package/dist/documents/pending-file-guard.js

@@ -0,0 +1,29 @@
+import { createEntityExecutor, createSystemUser, SYSTEM_ROLE, SYSTEM_USER_ID, } from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError } from "@cosmicdrift/kumiko-framework/errors";
+import { FILE_REF_ENTITY_NAME, fileRefEntity } from "@cosmicdrift/kumiko-framework/files";
+import { DOCUMENT_ENTITY } from "./constants.js";
+const fileRefs = createEntityExecutor(FILE_REF_ENTITY_NAME, fileRefEntity).executor;
+// One live document per file (unique on tenant + file): a member who names a colleague's pending
+// upload would block the colleague's own later save of that file, because capture could no longer
+// create its document. Files a job made (system uploader) and files already bound to a record stay
+// allowed; for the latter the readGate's file-owner check covers it.
+export const rejectForeignPendingFile = async (changes, ctx) => {
+    const file = changes["file"];
+    if (typeof file !== "string" || file === ctx.previous["file"])
+        return changes;
+    if (ctx.user.roles.includes(SYSTEM_ROLE))
+        return changes;
+    const ref = await fileRefs.detail({ id: file }, createSystemUser(ctx.user.tenantId), ctx.db);
+    // skip: a missing file is rejected by the framework's own file-reference check
+    if (ref === null)
+        return changes;
+    const uploader = ref["insertedById"];
+    const unbound = ref["entityId"] === null || ref["entityId"] === undefined;
+    if (unbound &&
+        typeof uploader === "string" &&
+        uploader !== ctx.user.id &&
+        uploader !== SYSTEM_USER_ID) {
+        throw new NotFoundError(DOCUMENT_ENTITY, file);
+    }
+    return changes;
+};

package/dist/documents/queries/expiry-overview.query.d.ts

@@ -0,0 +1,10 @@
+import { type AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createExpiryOverviewQuery(access: AccessRule, expiringWithinDays: number): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"expiry-overview", import("zod").ZodObject<{
+    entityType: import("zod").ZodOptional<import("zod").ZodString>;
+    entityId: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>, {
+    expired: number;
+    expiring: number;
+    valid: number;
+    none: number;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/documents/queries/expiry-overview.query.js

@@ -0,0 +1,41 @@
+import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { expiryWindow } from "../expiry.js";
+import { expiryOverviewPayloadSchema } from "../schemas.js";
+import { linkedDocumentIds, listDocuments } from "./list-page.js";
+// Counts come from the document list itself (totalCount), so they follow the same read gate
+// as the rows a user can open.
+export function createExpiryOverviewQuery(access, expiringWithinDays) {
+    return defineQueryHandler({
+        name: "expiry-overview",
+        schema: expiryOverviewPayloadSchema,
+        access,
+        liveEntities: ["filed-document", "filed-document-link"],
+        description: "Counts the documents the caller can read by validity: expired, expiring within the configured window, valid beyond it and without an expiry date; optionally for one record only.",
+        handler: async (query, ctx) => {
+            const payload = query.payload;
+            const { today, horizon } = expiryWindow(ctx, expiringWithinDays);
+            const scope = [];
+            if (payload.entityType !== undefined && payload.entityId !== undefined) {
+                const ids = await linkedDocumentIds(ctx, {
+                    entityType: payload.entityType,
+                    entityId: payload.entityId,
+                });
+                if (ids.length === 0)
+                    return { expired: 0, expiring: 0, valid: 0, none: 0 };
+                scope.push({ field: "id", op: "in", value: ids });
+            }
+            const count = async (extra) => (await listDocuments(ctx, { limit: 1, totalCount: true, filters: [...scope, ...extra] }))
+                .total ?? 0;
+            const [all, expired, expiring, valid] = await Promise.all([
+                count([]),
+                count([{ field: "validUntil", op: "lt", value: today }]),
+                count([
+                    { field: "validUntil", op: "gte", value: today },
+                    { field: "validUntil", op: "lte", value: horizon },
+                ]),
+                count([{ field: "validUntil", op: "gt", value: horizon }]),
+            ]);
+            return { expired, expiring, valid, none: all - expired - expiring - valid };
+        },
+    });
+}

package/dist/documents/queries/for-record.query.d.ts

@@ -0,0 +1,90 @@
+import { type AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+export declare function createForRecordQuery(access: AccessRule, linkTargets: readonly string[]): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"for-record", import("zod").ZodObject<{
+    entityType: import("zod").ZodString;
+    entityId: import("zod").ZodString;
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    offset: import("zod").ZodOptional<import("zod").ZodNumber>;
+    search: import("zod").ZodOptional<import("zod").ZodString>;
+    sort: import("zod").ZodOptional<import("zod").ZodString>;
+    sortDirection: import("zod").ZodOptional<import("zod").ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    totalCount: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    filter: import("zod").ZodOptional<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>;
+    filters: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>>;
+}, import("zod/v4/core").$strip>, {
+    rows: Record<string, unknown>[];
+    nextCursor?: string | null | undefined;
+    total?: number | undefined;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+export declare function forTypeQueryName(entityType: string): string;
+export declare function forTypeQueryQn(entityType: string): string;
+export declare function createForTypeQuery(access: AccessRule, linkTargets: readonly string[], entityType: string): import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<string, import("zod").ZodObject<{
+    limit: import("zod").ZodOptional<import("zod").ZodNumber>;
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    offset: import("zod").ZodOptional<import("zod").ZodNumber>;
+    search: import("zod").ZodOptional<import("zod").ZodString>;
+    sort: import("zod").ZodOptional<import("zod").ZodString>;
+    sortDirection: import("zod").ZodOptional<import("zod").ZodEnum<{
+        asc: "asc";
+        desc: "desc";
+    }>>;
+    totalCount: import("zod").ZodOptional<import("zod").ZodBoolean>;
+    filter: import("zod").ZodOptional<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>;
+    filters: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        field: import("zod").ZodString;
+        op: import("zod").ZodEnum<{
+            eq: "eq";
+            gt: "gt";
+            gte: "gte";
+            in: "in";
+            lt: "lt";
+            lte: "lte";
+            ne: "ne";
+        }>;
+        value: import("zod").ZodUnknown;
+    }, import("zod/v4/core").$strip>>>;
+    id: import("zod").ZodString;
+}, import("zod/v4/core").$strip>, {
+    rows: Record<string, unknown>[];
+    nextCursor?: string | null | undefined;
+    total?: number | undefined;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/documents/queries/for-record.query.js

@@ -0,0 +1,54 @@
+import { defineQueryHandler, toKebab, } from "@cosmicdrift/kumiko-framework/engine";
+import { DocumentsQueries } from "../constants.js";
+import { forRecordPayloadSchema } from "../schemas.js";
+import { linkedDocumentIds, listDocuments } from "./list-page.js";
+const EMPTY_PAGE = { rows: [], nextCursor: null, total: 0 };
+const LIVE_ENTITIES = ["filed-document", "filed-document-link"];
+async function documentsOfRecord(ctx, linkTargets, payload) {
+    const { entityType, entityId, filter, filters, ...paging } = payload;
+    if (!linkTargets.includes(entityType))
+        return EMPTY_PAGE;
+    const ids = await linkedDocumentIds(ctx, { entityType, entityId });
+    if (ids.length === 0)
+        return EMPTY_PAGE;
+    return listDocuments(ctx, {
+        ...paging,
+        filters: [
+            { field: "id", op: "in", value: ids },
+            ...(filter !== undefined ? [filter] : []),
+            ...(filters ?? []),
+        ],
+    });
+}
+export function createForRecordQuery(access, linkTargets) {
+    return defineQueryHandler({
+        name: "for-record",
+        schema: forRecordPayloadSchema,
+        access,
+        liveEntities: LIVE_ENTITIES,
+        description: "Lists the documents linked to one record, paged and filterable like the document list; a record the caller cannot read, or a type that takes no documents, yields an empty page.",
+        handler: async (query, ctx) => documentsOfRecord(ctx, linkTargets, query.payload),
+    });
+}
+export function forTypeQueryName(entityType) {
+    return `for-${toKebab(entityType)}`;
+}
+export function forTypeQueryQn(entityType) {
+    return `${DocumentsQueries.forRecord.replace(/for-record$/, "")}${forTypeQueryName(entityType)}`;
+}
+// A relatedList tab sends only the parent id, so the host type is fixed per query.
+export function createForTypeQuery(access, linkTargets, entityType) {
+    return defineQueryHandler({
+        name: forTypeQueryName(entityType),
+        schema: forRecordPayloadSchema.omit({ entityType: true, entityId: true }).extend({
+            id: forRecordPayloadSchema.shape.entityId,
+        }),
+        access,
+        liveEntities: LIVE_ENTITIES,
+        description: `Lists the documents linked to one ${entityType} record by its id, paged and filterable like the document list; it feeds the documents tab on the ${entityType} screen.`,
+        handler: async (query, ctx) => {
+            const { id, ...rest } = query.payload;
+            return documentsOfRecord(ctx, linkTargets, { ...rest, entityType, entityId: id });
+        },
+    });
+}

package/dist/documents/queries/list-page.d.ts

@@ -0,0 +1,19 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+declare const pageSchema: z.ZodObject<{
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    nextCursor: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    total: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ListPage = z.infer<typeof pageSchema>;
+export type ListFilter = {
+    readonly field: string;
+    readonly op: string;
+    readonly value: unknown;
+};
+export declare function listDocuments(ctx: Pick<HandlerContext, "dispatch">, payload: Record<string, unknown>): Promise<ListPage>;
+export declare function linkedDocumentIds(ctx: Pick<HandlerContext, "dispatch">, target: {
+    readonly entityType: string;
+    readonly entityId: string;
+}): Promise<string[]>;
+export {};