@cosmicdrift/kumiko-samples 0.399.0 → 0.400.0

package/packages/bundled-features/src/documents/handlers/import.write.ts

@@ -0,0 +1,157 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntityExecutor,
+  defineWriteHandler,
+  type HandlerEvents,
+  type SessionUser,
+  SYSTEM_ROLE,
+  type WriteHandlerDef,
+} from "@cosmicdrift/kumiko-framework/engine";
+import {
+  ConflictError,
+  NotFoundError,
+  ValidationError,
+  type WriteFailure,
+  writeFailure,
+} from "@cosmicdrift/kumiko-framework/errors";
+import { FILE_REF_ENTITY_NAME } from "@cosmicdrift/kumiko-framework/files";
+import { DOCUMENT_ENTITY } from "../constants.ts";
+import { ensureDocumentLink } from "../ensure-link.ts";
+import type { DocumentExecutors } from "../executor.ts";
+import { type ImportDocumentPayload, importDocumentPayloadSchema } from "../schemas.ts";
+
+type ImportArgs = {
+  readonly executors: DocumentExecutors;
+  readonly categories: readonly string[];
+  readonly linkTargets: readonly string[];
+};
+
+async function fileRefExists(
+  registry: Parameters<WriteHandlerDef["handler"]>[1]["registry"],
+  fileRefId: string,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<boolean> {
+  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;
+}
+
+type StreamLoader = Pick<HandlerEvents, "load">;
+
+// 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: StreamLoader, id: string): Promise<string | undefined> {
+  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: DocumentExecutors,
+  events: StreamLoader,
+  payload: ImportDocumentPayload,
+  user: SessionUser,
+  db: TenantDb,
+): Promise<WriteFailure | undefined> {
+  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: ImportArgs) {
+  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 as const, data: { id: payload.id, entity: DOCUMENT_ENTITY } };
+    },
+  });
+}

package/packages/bundled-features/src/documents/handlers/link.write.ts

@@ -0,0 +1,103 @@
+import {
+  type AccessRule,
+  defineWriteHandler,
+  parentVisibilityFor,
+  type WriteResult,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { NotFoundError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { documentLinkAggregateId } from "../aggregate-id.ts";
+import { DOCUMENT_ENTITY } from "../constants.ts";
+import { ensureDocumentLink } from "../ensure-link.ts";
+import type { DocumentExecutors } from "../executor.ts";
+import { documentLinkPayloadSchema } from "../schemas.ts";
+import { canWriteLinkTarget } from "../target-write-check.ts";
+
+type LinkHandlerArgs = {
+  readonly access: AccessRule;
+  readonly executors: DocumentExecutors;
+  readonly linkTargets: readonly string[];
+};
+
+// 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: LinkHandlerArgs) {
+  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): Promise<WriteResult<unknown>> => {
+      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: LinkHandlerArgs) {
+  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): Promise<WriteResult<unknown>> => {
+      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 as const, data: { id } };
+      return executors.link.delete({ id }, event.user, ctx.db);
+    },
+  });
+}

package/packages/bundled-features/src/documents/i18n.ts

@@ -0,0 +1,35 @@
+type LocalizedString = { readonly en: string; readonly de: string };
+
+export const DOCUMENTS_FEATURE_I18N: Readonly<Record<string, LocalizedString>> = {
+  "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/packages/bundled-features/src/documents/index.ts

@@ -0,0 +1,22 @@
+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/packages/bundled-features/src/documents/pending-file-guard.ts

@@ -0,0 +1,36 @@
+import {
+  createEntityExecutor,
+  createSystemUser,
+  type PreSaveHookFn,
+  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.ts";
+
+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: PreSaveHookFn = 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/packages/bundled-features/src/documents/queries/expiry-overview.query.ts

@@ -0,0 +1,46 @@
+import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { expiryWindow } from "../expiry.ts";
+import { expiryOverviewPayloadSchema } from "../schemas.ts";
+import { linkedDocumentIds, listDocuments } from "./list-page.ts";
+
+type Filter = { readonly field: string; readonly op: string; readonly value: unknown };
+
+// 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: AccessRule, expiringWithinDays: number) {
+  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: Filter[] = [];
+      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: Filter[]) =>
+        (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/packages/bundled-features/src/documents/queries/for-record.query.ts

@@ -0,0 +1,74 @@
+import {
+  type AccessRule,
+  defineQueryHandler,
+  type HandlerContext,
+  toKebab,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { DocumentsQueries } from "../constants.ts";
+import { type ForRecordPayload, forRecordPayloadSchema } from "../schemas.ts";
+import { linkedDocumentIds, listDocuments } from "./list-page.ts";
+
+const EMPTY_PAGE = { rows: [], nextCursor: null, total: 0 };
+const LIVE_ENTITIES = ["filed-document", "filed-document-link"];
+
+type Dispatching = Pick<HandlerContext, "dispatch">;
+
+async function documentsOfRecord(
+  ctx: Dispatching,
+  linkTargets: readonly string[],
+  payload: ForRecordPayload,
+) {
+  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: AccessRule, linkTargets: readonly string[]) {
+  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: string): string {
+  return `for-${toKebab(entityType)}`;
+}
+
+export function forTypeQueryQn(entityType: string): string {
+  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: AccessRule,
+  linkTargets: readonly string[],
+  entityType: string,
+) {
+  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/packages/bundled-features/src/documents/queries/list-page.ts

@@ -0,0 +1,51 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { DocumentsQueries } from "../constants.ts";
+
+const LINK_LIST = "documents:query:filed-document-link:list";
+const LINK_PAGE_SIZE = 200;
+
+const pageSchema = z.object({
+  rows: z.array(z.record(z.string(), z.unknown())),
+  nextCursor: z.string().nullable().optional(),
+  total: z.number().optional(),
+});
+export type ListPage = z.infer<typeof pageSchema>;
+
+export type ListFilter = { readonly field: string; readonly op: string; readonly value: unknown };
+
+export async function listDocuments(
+  ctx: Pick<HandlerContext, "dispatch">,
+  payload: Record<string, unknown>,
+): Promise<ListPage> {
+  return pageSchema.parse(await ctx.dispatch.query(DocumentsQueries.list, payload));
+}
+
+// Goes through the link list, so a record the caller cannot read yields no ids (the link's
+// parentRef gate), and a document is then fetched through the document list, which applies the
+// document's own read gate again.
+export async function linkedDocumentIds(
+  ctx: Pick<HandlerContext, "dispatch">,
+  target: { readonly entityType: string; readonly entityId: string },
+): Promise<string[]> {
+  const ids: string[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = pageSchema.parse(
+      await ctx.dispatch.query(LINK_LIST, {
+        filters: [
+          { field: "entityType", op: "eq", value: target.entityType },
+          { field: "entityId", op: "eq", value: target.entityId },
+        ],
+        limit: LINK_PAGE_SIZE,
+        ...(cursor !== undefined && { cursor }),
+      }),
+    );
+    for (const row of page.rows) {
+      const documentId = row["documentId"];
+      if (typeof documentId === "string") ids.push(documentId);
+    }
+    cursor = page.nextCursor ?? undefined;
+  } while (cursor !== undefined);
+  return ids;
+}

package/packages/bundled-features/src/documents/queries/overview.query.ts

@@ -0,0 +1,45 @@
+import { type AccessRule, defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { EXPIRING_FACET_VALUE } from "../constants.ts";
+import { expiryStateOf, expiryWindow } from "../expiry.ts";
+import { overviewPayloadSchema } from "../schemas.ts";
+import { type ListFilter, listDocuments } from "./list-page.ts";
+
+const EXPIRY_FILTER_FIELD = "expiry";
+
+// The "expiring" facet is a moving date window, which a facet on a stored field cannot
+// express; it becomes a validUntil bound here, expired documents included. A document
+// without a date never matches it.
+function toDocumentFilters(filters: readonly ListFilter[], horizon: string): readonly ListFilter[] {
+  return filters.flatMap((clause): ListFilter[] => {
+    if (clause.field !== EXPIRY_FILTER_FIELD) return [clause];
+    const wantsExpiring =
+      Array.isArray(clause.value) && clause.value.includes(EXPIRING_FACET_VALUE);
+    return wantsExpiring ? [{ field: "validUntil", op: "lte", value: horizon }] : [];
+  });
+}
+
+export function createOverviewQuery(access: AccessRule, expiringWithinDays: number) {
+  return defineQueryHandler({
+    name: "overview",
+    schema: overviewPayloadSchema,
+    access,
+    liveEntities: ["filed-document", "filed-document-link"],
+    description:
+      "Lists the documents the caller can read with an expiry state per row (expired, expiring, valid, none); the expiring filter returns expired and soon-expiring documents. Powers the documents list screen.",
+    handler: async (query, ctx) => {
+      const { filters, ...paging } = query.payload;
+      const window = expiryWindow(ctx, expiringWithinDays);
+      const page = await listDocuments(ctx, {
+        ...paging,
+        filters: toDocumentFilters(filters ?? [], window.horizon),
+      });
+      return {
+        ...page,
+        rows: page.rows.map((row) => ({
+          ...row,
+          expiry: expiryStateOf(row["validUntil"], window),
+        })),
+      };
+    },
+  });
+}

package/packages/bundled-features/src/documents/schemas.ts

@@ -0,0 +1,66 @@
+import * as z from "zod";
+
+export const documentLinkPayloadSchema = z.object({
+  documentId: z.uuid(),
+  entityType: z.string().min(1).max(64),
+  entityId: z.string().min(1).max(128),
+});
+export type DocumentLinkPayload = z.infer<typeof documentLinkPayloadSchema>;
+
+const isoDate = z.iso.date();
+
+export const importDocumentPayloadSchema = z.object({
+  id: z.uuid(),
+  title: z.string().trim().min(1).max(200),
+  category: z.string().min(1),
+  issuedAt: isoDate.optional(),
+  validUntil: isoDate.optional(),
+  fileRefId: z.uuid(),
+  links: z.array(
+    z.object({ entityType: z.string().min(1).max(64), entityId: z.string().min(1).max(128) }),
+  ),
+  deleted: z.boolean().optional(),
+});
+export type ImportDocumentPayload = z.infer<typeof importDocumentPayloadSchema>;
+
+export const forRecordPayloadSchema = z.object({
+  entityType: z.string().min(1).max(64),
+  entityId: z.string().min(1).max(128),
+  limit: z.number().int().nonnegative().max(200).optional(),
+  cursor: z.string().optional(),
+  offset: z.number().int().nonnegative().optional(),
+  search: z.string().optional(),
+  sort: z.string().optional(),
+  sortDirection: z.enum(["asc", "desc"]).optional(),
+  totalCount: z.boolean().optional(),
+  filter: z
+    .object({
+      field: z.string(),
+      op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+      value: z.unknown(),
+    })
+    .optional(),
+  filters: z
+    .array(
+      z.object({
+        field: z.string(),
+        op: z.enum(["eq", "ne", "lt", "gt", "lte", "gte", "in"]),
+        value: z.unknown(),
+      }),
+    )
+    .optional(),
+});
+export type ForRecordPayload = z.infer<typeof forRecordPayloadSchema>;
+
+export const overviewPayloadSchema = forRecordPayloadSchema.omit({
+  entityType: true,
+  entityId: true,
+  filter: true,
+});
+export type OverviewPayload = z.infer<typeof overviewPayloadSchema>;
+
+export const expiryOverviewPayloadSchema = z.object({
+  entityType: z.string().min(1).max(64).optional(),
+  entityId: z.string().min(1).max(128).optional(),
+});
+export type ExpiryOverviewPayload = z.infer<typeof expiryOverviewPayloadSchema>;