@cosmicdrift/kumiko-bundled-features 0.398.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/consumer-protection/consent-text.js

@@ -17,12 +17,12 @@ export const CONSENT_TEXTS = {
 };
 const DOCUMENTS_ACKNOWLEDGEMENT_TEXTS = {
     de: {
-        withRefund: "Ich habe die AGB, die Erstattungsrichtlinie und die Datenschutzerklärung gelesen. Mit den AGB und der Erstattungsrichtlinie bin ich einverstanden.",
-        withoutRefund: "Ich habe die AGB und die Datenschutzerklärung gelesen. Mit den AGB bin ich einverstanden.",
+        withRefund: "Ich habe die AGB und die Erstattungsrichtlinie gelesen und bin mit ihnen einverstanden.",
+        withoutRefund: "Ich habe die AGB gelesen und bin mit ihnen einverstanden.",
     },
     en: {
-        withRefund: "I have read the Terms, the Refund Policy and the Privacy Policy, and I agree to the Terms and the Refund Policy.",
-        withoutRefund: "I have read the Terms and the Privacy Policy, and I agree to the Terms.",
+        withRefund: "I have read and agree to the Terms and the Refund Policy.",
+        withoutRefund: "I have read and agree to the Terms.",
     },
 };
 export function legalLinksPerLocale(legalLinks) {

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/channel-in-app/constants.js

@@ -1,9 +1,4 @@
-export const CHANNEL_IN_APP_FEATURE = "channel-in-app";
-export const InAppHandlers = {
-    markRead: "channel-in-app:write:mark-read",
-    markAllRead: "channel-in-app:write:mark-all-read",
-};
-export const InAppQueries = {
-    inbox: "channel-in-app:query:inbox",
-    unreadCount: "channel-in-app:query:unread-count",
-};
+import { IN_APP_NOTIFICATION_FEATURE, IN_APP_NOTIFICATION_QUERIES, IN_APP_NOTIFICATION_WRITES, } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+export const CHANNEL_IN_APP_FEATURE = IN_APP_NOTIFICATION_FEATURE;
+export const InAppHandlers = IN_APP_NOTIFICATION_WRITES;
+export const InAppQueries = IN_APP_NOTIFICATION_QUERIES;

package/dist/channel-in-app/feature.js

@@ -8,7 +8,7 @@ import { inAppChannel } from "./in-app-channel.js";
 import { inAppMessagesTableMeta } from "./tables.js";
 export function createChannelInAppFeature() {
     return defineFeature("channel-in-app", (r) => {
-        r.describe("Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.");
+        r.describe("Persists notifications to an in-app inbox table so users can page through them via `queries.inbox` (cursor, total, parsed `target`) and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. A notification links to a screen when `data.target` is set with `inAppTarget(screenId, entityId?)`. The renderer shell shows a bell with a live unread badge whenever this feature is mounted. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.");
         r.uiHints({
             displayLabel: "In-App Inbox",
             category: "notifications",

package/dist/channel-in-app/handlers/inbox.query.d.ts

@@ -2,6 +2,9 @@ import * as z from "zod";
 export declare const inboxQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"inbox", z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
     unreadOnly: z.ZodDefault<z.ZodBoolean>;
+    cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
-    rows: readonly any[];
+    rows: any[];
+    nextCursor: string | null;
+    total: number;
 }, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/channel-in-app/handlers/inbox.query.js

@@ -1,12 +1,15 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { parseStoredNotificationData, targetOfNotificationData } from "../in-app-target.js";
 import { inAppMessagesTable } from "../tables.js";
+const SERIAL_ID_PATTERN = /^\d{1,15}$/;
 export const inboxQuery = defineQueryHandler({
     name: "inbox",
     schema: z.object({
         limit: z.number().min(1).max(100).default(50),
         unreadOnly: z.boolean().default(false),
+        cursor: z.string().regex(SERIAL_ID_PATTERN).optional(),
     }),
     access: {
         openToAll: {
@@ -14,15 +17,27 @@ export const inboxQuery = defineQueryHandler({
                 "inAppMessagesTable by the caller's own id",
         },
     },
-    description: "Lists the calling user's own in-app notification messages newest-first, optionally only the unread ones; use it to show or inspect a user's notification inbox.",
+    description: "Lists the calling user's own in-app notification messages newest-first with a parsed navigation target, optionally only the unread ones. Pass the returned nextCursor as cursor for the next page; total counts all matching messages, not just the page. Use it to show or inspect a user's notification inbox.",
     handler: async (query, ctx) => {
-        const where = { userId: query.user.id };
-        if (query.payload.unreadOnly)
-            where["isRead"] = false;
-        const rows = await selectMany(ctx.db, inAppMessagesTable, where, {
-            limit: query.payload.limit,
-            orderBy: { col: "createdAt", direction: "desc" },
+        const { limit, unreadOnly, cursor } = query.payload;
+        const ownMessages = { userId: query.user.id };
+        if (unreadOnly)
+            ownMessages["isRead"] = false;
+        const pageWhere = cursor === undefined ? ownMessages : { ...ownMessages, id: { lt: Number(cursor) } };
+        // One extra row tells whether another page exists without a second query.
+        const fetched = await selectMany(ctx.db, inAppMessagesTable, pageWhere, {
+            limit: limit + 1,
+            orderBy: { col: "id", direction: "desc" },
         });
-        return { rows };
+        const page = fetched.slice(0, limit);
+        const lastRow = page[page.length - 1];
+        const nextCursor = fetched.length > limit && lastRow ? String(lastRow["id"]) : null;
+        const [totalRow] = await ctx.db.aggregate(inAppMessagesTable, { measure: { fn: "count" } }, ownMessages);
+        const rows = page.map((row) => {
+            const storedData = row["data"];
+            const data = parseStoredNotificationData(typeof storedData === "string" ? storedData : null);
+            return { ...row, target: targetOfNotificationData(data) };
+        });
+        return { rows, nextCursor, total: totalRow?.value ?? 0 };
     },
 });

package/dist/channel-in-app/handlers/unread-count.query.js

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.js";
@@ -13,13 +12,7 @@ export const unreadCountQuery = defineQueryHandler({
     },
     description: "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
     handler: async (query, ctx) => {
-        // The query helpers in db/query.ts have no aggregate helper, so selectMany returns all matching
-        // rows and count() runs in JS. This is acceptable because unread counts are low-cardinality and
-        // user-scoped, with at most a few hundred rows; use raw .unsafe() with COUNT(*) if that grows.
-        const rows = await selectMany(ctx.db, inAppMessagesTable, {
-            userId: query.user.id,
-            isRead: false,
-        });
-        return { count: rows.length };
+        const [countRow] = await ctx.db.aggregate(inAppMessagesTable, { measure: { fn: "count" } }, { userId: query.user.id, isRead: false });
+        return { count: countRow?.value ?? 0 };
     },
 });

package/dist/channel-in-app/in-app-channel.js

@@ -1,5 +1,9 @@
 import { tenantChannel } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { IN_APP_NOTIFICATION_DELIVERED_EVENT } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+import { targetOfNotificationData } from "./in-app-target.js";
 import { inAppMessagesTable } from "./tables.js";
+const log = createFallbackLogger("channel-in-app");
 export const inAppChannel = {
     name: "inApp",
     mode: "inline",
@@ -10,24 +14,32 @@ export const inAppChannel = {
     async send(address, message, ctx) {
         // address is the user-id string after the ES migration — keep it as-is.
         const userId = address;
+        // A malformed target drops only the link, never the notification.
+        const target = targetOfNotificationData(message.data);
+        const storedData = message.data === undefined
+            ? null
+            : JSON.stringify({ ...message.data, target: target ?? undefined });
         const row = await ctx.db.insertOne(inAppMessagesTable, {
             userId,
             notificationType: message.notificationType,
             title: message.title,
             body: message.body ?? null,
-            data: message.data ? JSON.stringify(message.data) : null,
+            data: storedData,
         });
         if (ctx.sseBroker) {
-            await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
-                type: "channel-in-app:event:delivered",
-                data: {
-                    id: row?.id,
-                    userId,
-                    notificationType: message.notificationType,
-                    title: message.title,
-                    body: message.body,
-                },
-            });
+            // The row is stored, so a failing push (e.g. Redis down) must not turn the delivery into
+            // a failure that gets retried and stored twice. Clients fetch the inbox on reconnect.
+            try {
+                await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
+                    type: IN_APP_NOTIFICATION_DELIVERED_EVENT,
+                    data: { id: row?.id, userId, notificationType: message.notificationType },
+                });
+            }
+            catch (error) {
+                log.warn("in-app SSE push failed; the notification is stored", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
         }
         return { status: "sent", address };
     },

package/dist/channel-in-app/in-app-target.d.ts

@@ -0,0 +1,5 @@
+import type { InAppNotificationTarget } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+export declare function inAppTarget(screenId: string, entityId?: string): InAppNotificationTarget;
+export declare function parseInAppTarget(value: unknown): InAppNotificationTarget | null;
+export declare function targetOfNotificationData(data: unknown): InAppNotificationTarget | null;
+export declare function parseStoredNotificationData(stored: string | null): unknown;

package/dist/channel-in-app/in-app-target.js

@@ -0,0 +1,34 @@
+import * as z from "zod";
+const SCREEN_ID_PATTERN = /^[^\s:]+:screen:[^\s:]+$/;
+const targetSchema = z.object({
+    screenId: z.string().regex(SCREEN_ID_PATTERN),
+    entityId: z.string().min(1).optional(),
+});
+export function inAppTarget(screenId, entityId) {
+    return entityId === undefined ? { screenId } : { screenId, entityId };
+}
+// Returns null for anything that is not a well-formed target, so a malformed `data.target`
+// drops only the link and never the notification.
+export function parseInAppTarget(value) {
+    const parsed = targetSchema.safeParse(value);
+    if (!parsed.success)
+        return null;
+    const { screenId, entityId } = parsed.data;
+    return inAppTarget(screenId, entityId);
+}
+// Reads `target` out of the stored notification data (a JSON string) or out of a raw data object.
+export function targetOfNotificationData(data) {
+    if (typeof data !== "object" || data === null || !("target" in data))
+        return null;
+    return parseInAppTarget(data.target);
+}
+export function parseStoredNotificationData(stored) {
+    if (stored === null)
+        return null;
+    try {
+        return JSON.parse(stored);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/channel-in-app/index.d.ts

@@ -1,4 +1,5 @@
 export { CHANNEL_IN_APP_FEATURE, InAppHandlers, InAppQueries } from "./constants.ts";
 export { createChannelInAppFeature } from "./feature.ts";
 export { inAppChannel } from "./in-app-channel.ts";
+export { inAppTarget } from "./in-app-target.ts";
 export { inAppMessagesTable } from "./tables.ts";

package/dist/channel-in-app/index.js

@@ -1,4 +1,5 @@
 export { CHANNEL_IN_APP_FEATURE, InAppHandlers, InAppQueries } from "./constants.js";
 export { createChannelInAppFeature } from "./feature.js";
 export { inAppChannel } from "./in-app-channel.js";
+export { inAppTarget } from "./in-app-target.js";
 export { inAppMessagesTable } from "./tables.js";

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