@cosmicdrift/kumiko-bundled-features 0.399.0 → 0.400.0

package/dist/auth-mfa/schema/user-mfa.d.ts

@@ -21,7 +21,7 @@ export declare const userMfaEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly lastUsedAt: {
@@ -37,7 +37,7 @@ export declare const userMfaEntity: import("@cosmicdrift/kumiko-types/fields").E
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: false;
     };
 }, "tenant">;
@@ -64,7 +64,7 @@ export declare const userMfaTable: import("@cosmicdrift/kumiko-framework/db").En
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly lastUsedAt: {
@@ -80,7 +80,7 @@ export declare const userMfaTable: import("@cosmicdrift/kumiko-framework/db").En
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: false;
     };
 }, "tenant">>;

package/dist/billing-foundation/entities.d.ts

@@ -27,7 +27,7 @@ export declare const subscriptionEntity: import("@cosmicdrift/kumiko-types/field
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly cancelAt: {
@@ -43,7 +43,7 @@ export declare const subscriptionEntity: import("@cosmicdrift/kumiko-types/field
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: false;
     };
 }, "tenant">;

package/dist/billing-foundation/projection.d.ts

@@ -28,7 +28,7 @@ export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-f
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly cancelAt: {
@@ -44,7 +44,7 @@ export declare const subscriptionsProjectionTable: import("@cosmicdrift/kumiko-f
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: false;
     };
 }, "tenant">>;

package/dist/cap-counter/entity.d.ts

@@ -12,7 +12,7 @@ export declare const capCounterEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly sensitive?: boolean;
         readonly default?: number;
         readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly periodStart: {
@@ -28,7 +28,7 @@ export declare const capCounterEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly lastSoftWarnedAt: {
@@ -44,7 +44,7 @@ export declare const capCounterEntity: import("@cosmicdrift/kumiko-types/fields"
         readonly min?: string;
         readonly max?: string;
         readonly locale?: string;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: false;
     };
 }, "tenant">;

package/dist/compliance-profiles/schema/profile-selection.d.ts

@@ -21,7 +21,7 @@ export declare const tenantComplianceProfileEntity: import("@cosmicdrift/kumiko-
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
         readonly optionsAvailabilityQuery?: string;
         readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<"de-hr-dsgvo-hgb" | "eu-dsgvo" | "minimal-no-region" | "swiss-dsg">[] | undefined;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly override: import("@cosmicdrift/kumiko-types/fields").EntityLongTextFieldDef & {
@@ -51,7 +51,7 @@ export declare const tenantComplianceProfileTable: import("@cosmicdrift/kumiko-f
         readonly optionsQueryPayload?: import("@cosmicdrift/kumiko-types/fields").OptionsQueryPayload;
         readonly optionsAvailabilityQuery?: string;
         readonly conditionalOptions?: readonly import("@cosmicdrift/kumiko-types/fields").SelectConditionalOptions<"de-hr-dsgvo-hgb" | "eu-dsgvo" | "minimal-no-region" | "swiss-dsg">[] | undefined;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly override: import("@cosmicdrift/kumiko-types/fields").EntityLongTextFieldDef & {

package/dist/custom-fields/entity.d.ts

@@ -8,11 +8,31 @@ export declare const fieldDefinitionEntity: import("@cosmicdrift/kumiko-types/fi
     readonly type: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
-    readonly required: import("@cosmicdrift/kumiko-types/fields").BooleanFieldDef & {
+    readonly required: {
+        readonly type: "boolean";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly sortNulls?: import("@cosmicdrift/kumiko-types/fields").SortNulls;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly default?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+    } & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
         default: boolean;
     };
-    readonly searchable: import("@cosmicdrift/kumiko-types/fields").BooleanFieldDef & {
+    readonly searchable: {
+        readonly type: "boolean";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly sortNulls?: import("@cosmicdrift/kumiko-types/fields").SortNulls;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly default?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+    } & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
         default: boolean;
     };
@@ -33,7 +53,7 @@ export declare const fieldDefinitionEntity: import("@cosmicdrift/kumiko-types/fi
             readonly field: string;
         };
         readonly grouping?: boolean;
-    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & {
+    } & import("@cosmicdrift/kumiko-types/fields").ResolvedPiiFlags & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: true;
     };
     readonly serializedField: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {

package/dist/delivery/tables.d.ts

@@ -11,7 +11,17 @@ export declare const notificationPreferenceEntity: import("@cosmicdrift/kumiko-t
     readonly channel: import("@cosmicdrift/kumiko-types/fields").EntityTextFieldDef & {
         required: true;
     };
-    readonly enabled: import("@cosmicdrift/kumiko-types/fields").BooleanFieldDef & {
+    readonly enabled: {
+        readonly type: "boolean";
+        readonly description?: string;
+        readonly required?: boolean;
+        readonly sortable?: boolean;
+        readonly sortNulls?: import("@cosmicdrift/kumiko-types/fields").SortNulls;
+        readonly filterable?: boolean;
+        readonly sensitive?: boolean;
+        readonly default?: boolean;
+        readonly access?: import("@cosmicdrift/kumiko-types/fields").FieldAccess;
+    } & import("@cosmicdrift/kumiko-types/fields").FieldStateConditions & {
         required: false;
         default: boolean;
     };

package/dist/documents/aggregate-id.d.ts

@@ -0,0 +1,2 @@
+export declare function documentIdForFile(tenantId: string, fileRefId: string): string;
+export declare function documentLinkAggregateId(tenantId: string, documentId: string, entityType: string, entityId: string): string;

package/dist/documents/aggregate-id.js

@@ -0,0 +1,12 @@
+import { v5 as uuidv5 } from "uuid";
+// Frozen: changing a namespace re-keys every derived stream and breaks replay.
+const DOCUMENT_FOR_FILE_NAMESPACE = "6d2f7e41-3c58-4b0a-9e17-5a4c8d1b2f93";
+const DOCUMENT_LINK_NAMESPACE = "b83a1c6e-9f20-4d57-a1e4-7c0d52f68b19";
+// @wrapper-known uuid-domain
+export function documentIdForFile(tenantId, fileRefId) {
+    return uuidv5(`${tenantId}|${fileRefId}`, DOCUMENT_FOR_FILE_NAMESPACE);
+}
+// @wrapper-known uuid-domain
+export function documentLinkAggregateId(tenantId, documentId, entityType, entityId) {
+    return uuidv5(`${tenantId}|${documentId}|${entityType}|${entityId}`, DOCUMENT_LINK_NAMESPACE);
+}

package/dist/documents/capture.d.ts

@@ -0,0 +1,14 @@
+import { type FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import type { BootCheckContext } from "@cosmicdrift/kumiko-types/feature";
+import type { DOCUMENTS_FEATURE_NAME } from "./constants.ts";
+import { type LinkTarget } from "./ensure-link.ts";
+import type { DocumentExecutors } from "./executor.ts";
+export type DocumentCaptureRule = {
+    readonly entity: string;
+    readonly field: string;
+    readonly category: string;
+    readonly title?: (row: Readonly<Record<string, unknown>>) => string;
+    readonly links?: (row: Readonly<Record<string, unknown>>) => readonly LinkTarget[];
+};
+export declare function registerCapture(r: FeatureRegistrar<typeof DOCUMENTS_FEATURE_NAME>, executors: DocumentExecutors, rules: readonly DocumentCaptureRule[], linkTargets: readonly string[]): void;
+export declare function validateCaptureRules({ features }: BootCheckContext, rules: readonly DocumentCaptureRule[], categories: readonly string[], linkTargets: readonly string[]): void;

package/dist/documents/capture.js

@@ -0,0 +1,65 @@
+import { createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { documentIdForFile } from "./aggregate-id.js";
+import { ensureDocumentLink } from "./ensure-link.js";
+const MAX_TITLE_LENGTH = 200;
+async function captureFile(executors, rule, linkTargets, saved, fileRefId, user, db) {
+    const id = documentIdForFile(user.tenantId, fileRefId);
+    // The title never defaults to the file name, which can carry personal data.
+    const title = (rule.title?.(saved.data) ?? rule.category).slice(0, MAX_TITLE_LENGTH);
+    const created = await executors.document.create({ id, title, category: rule.category, file: fileRefId }, user, db);
+    // version_conflict: the stream exists already, so the file was captured before (and a document
+    // deleted since stays deleted).
+    if (!created.isSuccess && created.error.code !== "version_conflict") {
+        throw new Error(`documents capture failed for ${rule.entity}.${rule.field}: ${created.error.code}`);
+    }
+    // The gate hides rows from a caller without the registry; existence is the system user's question.
+    const live = await executors.document.detail({ id }, createSystemUser(user.tenantId), db);
+    // skip: the document was deleted after an earlier capture and stays deleted
+    if (live === null)
+        return;
+    const targets = [
+        { entityType: rule.entity, entityId: saved.id },
+        // Trusted: derived from the saved row, see DocumentCaptureRule.links.
+        ...(rule.links?.(saved.data) ?? []),
+    ].filter((target) => linkTargets.includes(target.entityType));
+    for (const target of targets) {
+        const linked = await ensureDocumentLink(executors, user, db, id, target);
+        if (!linked.isSuccess) {
+            throw new Error(`documents capture failed to link ${target.entityType}: ${linked.error.code}`);
+        }
+    }
+}
+export function registerCapture(r, executors, rules, linkTargets) {
+    for (const rule of rules) {
+        r.hook({
+            type: "postSave",
+            target: { allOf: rule.entity },
+            handler: async (result, ctx) => {
+                const value = result.changes[rule.field] ?? (result.isNew ? result.data[rule.field] : undefined);
+                // skip: the file field was not part of this save
+                if (typeof value !== "string")
+                    return;
+                await captureFile(executors, rule, linkTargets, { id: String(result.id), data: result.data }, value, ctx.user, ctx.db);
+            },
+        });
+    }
+}
+export function validateCaptureRules({ features }, rules, categories, linkTargets) {
+    for (const rule of rules) {
+        const label = `documents capture ${rule.entity}.${rule.field}`;
+        if (!categories.includes(rule.category)) {
+            throw new Error(`${label}: category "${rule.category}" is not in the configured categories.`);
+        }
+        const entity = features.map((f) => f.entities?.[rule.entity]).find((e) => e !== undefined);
+        if (entity === undefined)
+            throw new Error(`${label}: entity "${rule.entity}" is not registered.`);
+        const field = entity.fields[rule.field];
+        if (field?.type !== "file" && field?.type !== "image") {
+            throw new Error(`${label}: the field must be a single file or image field.`);
+        }
+    }
+    const unknownTarget = linkTargets.find((name) => !features.some((f) => f.entities?.[name] !== undefined));
+    if (unknownTarget !== undefined) {
+        throw new Error(`documents linkTargets: entity "${unknownTarget}" is not registered.`);
+    }
+}

package/dist/documents/constants.d.ts

@@ -0,0 +1,23 @@
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+export declare const DOCUMENTS_FEATURE_NAME = "documents";
+export declare const DOCUMENT_ENTITY = "filed-document";
+export declare const DOCUMENT_LINK_ENTITY = "filed-document-link";
+export declare const DEFAULT_DOCUMENT_ACCESS: AccessRule;
+export declare const DEFAULT_ADMIN_ROLES: readonly string[];
+export declare const DEFAULT_EXPIRING_WITHIN_DAYS = 30;
+export declare const DOCUMENTS_LIST_SCREEN_ID = "list";
+export declare const DocumentsHandlers: {
+    readonly link: "documents:write:link";
+    readonly unlink: "documents:write:unlink";
+    readonly import: "documents:write:import";
+};
+export declare const DocumentsQueries: {
+    readonly list: "documents:query:filed-document:list";
+    readonly detail: "documents:query:filed-document:detail";
+    readonly forRecord: "documents:query:for-record";
+    readonly expiryOverview: "documents:query:expiry-overview";
+    readonly overview: "documents:query:overview";
+};
+export declare const EXPIRY_STATES: readonly ["expired", "expiring", "valid", "none"];
+export type ExpiryState = (typeof EXPIRY_STATES)[number];
+export declare const EXPIRING_FACET_VALUE = "expiring";

package/dist/documents/constants.js

@@ -0,0 +1,21 @@
+export const DOCUMENTS_FEATURE_NAME = "documents";
+export const DOCUMENT_ENTITY = "filed-document";
+export const DOCUMENT_LINK_ENTITY = "filed-document-link";
+export const DEFAULT_DOCUMENT_ACCESS = { roles: ["TenantAdmin", "TenantMember"] };
+export const DEFAULT_ADMIN_ROLES = ["TenantAdmin", "SystemAdmin"];
+export const DEFAULT_EXPIRING_WITHIN_DAYS = 30;
+export const DOCUMENTS_LIST_SCREEN_ID = "list";
+export const DocumentsHandlers = {
+    link: "documents:write:link",
+    unlink: "documents:write:unlink",
+    import: "documents:write:import",
+};
+export const DocumentsQueries = {
+    list: "documents:query:filed-document:list",
+    detail: "documents:query:filed-document:detail",
+    forRecord: "documents:query:for-record",
+    expiryOverview: "documents:query:expiry-overview",
+    overview: "documents:query:overview",
+};
+export const EXPIRY_STATES = ["expired", "expiring", "valid", "none"];
+export const EXPIRING_FACET_VALUE = "expiring";

package/dist/documents/ensure-link.d.ts

@@ -0,0 +1,17 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import type { DocumentExecutors } from "./executor.ts";
+export type LinkTarget = {
+    readonly entityType: string;
+    readonly entityId: string;
+};
+export declare function ensureDocumentLink(executors: DocumentExecutors, user: SessionUser, db: TenantDb, documentId: string, target: LinkTarget): Promise<import("@cosmicdrift/kumiko-types/write-error-info-types").WriteFailure | {
+    readonly isSuccess: true;
+    readonly data: import("@cosmicdrift/kumiko-types/hooks").SaveContext;
+    readonly lifecycle?: import("@cosmicdrift/kumiko-types/hooks").LifecycleResult;
+} | {
+    isSuccess: true;
+    data: {
+        id: string;
+    };
+}>;

package/dist/documents/ensure-link.js

@@ -0,0 +1,20 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { documentLinkAggregateId } from "./aggregate-id.js";
+// The link id is deterministic, so a removed link is restored rather than recreated and a
+// concurrent first create converges on the row the winner wrote.
+export async function ensureDocumentLink(executors, user, db, documentId, target) {
+    const id = documentLinkAggregateId(user.tenantId, documentId, target.entityType, target.entityId);
+    const restored = await executors.link.restore({ id }, user, db);
+    if (restored.isSuccess)
+        return restored;
+    const alreadyLive = isPlainObject(restored.error.details) && restored.error.details["reason"] === "not_deleted";
+    if (alreadyLive)
+        return { isSuccess: true, data: { id } };
+    if (restored.error.code !== "not_found")
+        return restored;
+    const created = await executors.link.create({ id, documentId, entityType: target.entityType, entityId: target.entityId }, user, db);
+    if (created.isSuccess || created.error.code === "version_conflict") {
+        return { isSuccess: true, data: { id } };
+    }
+    return created;
+}

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;
+};