@cosmicdrift/kumiko-samples 0.400.0 → 0.401.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.400.0",
+  "version": "0.401.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.400.0",
+  "version": "0.401.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

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

@@ -10,16 +10,20 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { DOCUMENT_LINK_ENTITY } from "./constants.ts";
 
+export type DocumentLinkReadMode = "anyLink" | "allLinks";
+
 export type DocumentEntityOptions = {
   readonly categories: readonly [string, ...string[]];
   readonly adminRoles: readonly string[];
   readonly readAccess?: NonNullable<EntityDefinition["access"]>["read"];
+  readonly linkReadMode?: DocumentLinkReadMode;
   readonly retention?: EntityDefinition["retention"];
 };
 
 // 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: DocumentEntityOptions) {
+  const documentLink = { entity: DOCUMENT_LINK_ENTITY, field: "documentId" };
   return createEntity({
     table: "read_filed_documents",
     softDelete: true,
@@ -32,7 +36,9 @@ export function createDocumentEntity(options: DocumentEntityOptions) {
     }),
     ...(options.retention !== undefined && { retention: options.retention }),
     readGate: {
-      anyLink: { entity: DOCUMENT_LINK_ENTITY, field: "documentId" },
+      ...(options.linkReadMode === "allLinks"
+        ? { allLinks: documentLink }
+        : { anyLink: documentLink }),
       fileOwner: { field: "file" },
       linkExemptRoles: options.adminRoles,
     },

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

@@ -23,7 +23,11 @@ import {
   DOCUMENT_LINK_ENTITY,
   DOCUMENTS_FEATURE_NAME,
 } from "./constants.ts";
-import { createDocumentEntity, createDocumentLinkEntity } from "./entity.ts";
+import {
+  createDocumentEntity,
+  createDocumentLinkEntity,
+  type DocumentLinkReadMode,
+} from "./entity.ts";
 import { createDocumentExecutors } from "./executor.ts";
 import { createImportDocumentHandler } from "./handlers/import.write.ts";
 import { createLinkDocumentHandler, createUnlinkDocumentHandler } from "./handlers/link.write.ts";
@@ -38,14 +42,23 @@ import { createDocumentWriteGuard } from "./write-guard.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. */
+  /** Entities a document can be linked to. Linking needs write access to the target: its update handler, or its entity write roles when it has none. */
   readonly linkTargets: readonly [string, ...string[]];
+  /** Display label per category (de, en); a category without one shows its raw value. */
+  readonly categoryLabels?: Readonly<Record<string, { readonly de: string; readonly en: 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"];
+  /**
+   * "anyLink" (default): one readable linked record shows the document. "allLinks": the viewer
+   * must read every record it is linked to, so a link to a shared record (a contact) does not
+   * open a document that also hangs off a record of another team. The file-owner check applies
+   * either way.
+   */
+  readonly linkReadMode?: DocumentLinkReadMode;
   /**
    * 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.
@@ -84,11 +97,14 @@ function resolveAccess(access: AccessRule | DocumentsAccess | undefined): Resolv
   return { read: access.read ?? DEFAULT_DOCUMENT_ACCESS, write, delete: access.delete ?? write };
 }
 
-function categoryOptionLabels(categories: readonly string[]) {
+function categoryOptionLabels(
+  categories: readonly string[],
+  labels: DocumentsFeatureOptions["categoryLabels"],
+) {
   return Object.fromEntries(
     categories.map((category) => [
       `documents:entity:filed-document:field:category:option:${category}`,
-      { en: category, de: category },
+      labels?.[category] ?? { en: category, de: category },
     ]),
   );
 }
@@ -103,6 +119,7 @@ function registerDocuments(
     categories: opts.categories,
     adminRoles: opts.adminRoles ?? DEFAULT_ADMIN_ROLES,
     ...(opts.readAccess !== undefined && { readAccess: opts.readAccess }),
+    ...(opts.linkReadMode !== undefined && { linkReadMode: opts.linkReadMode }),
     ...(opts.retention !== undefined && { retention: opts.retention }),
   });
   const linkEntity = createDocumentLinkEntity(linkTargets);
@@ -123,6 +140,7 @@ function registerDocuments(
       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.",
+      agent: { risk: "mid" },
     }),
   );
   const writeGuard = createDocumentWriteGuard(executors, opts.adminRoles ?? DEFAULT_ADMIN_ROLES);
@@ -131,6 +149,7 @@ function registerDocuments(
       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.",
+      agent: { risk: "mid" },
     }),
   );
   r.writeHandler(
@@ -185,7 +204,10 @@ function registerDocuments(
 
   r.screen(createDocumentListScreen(access.read, opts.categories));
   r.translations({
-    keys: { ...DOCUMENTS_FEATURE_I18N, ...categoryOptionLabels(opts.categories) },
+    keys: {
+      ...DOCUMENTS_FEATURE_I18N,
+      ...categoryOptionLabels(opts.categories, opts.categoryLabels),
+    },
   });
 }
 
@@ -193,5 +215,12 @@ export function createDocumentsFeature(opts: DocumentsFeatureOptions) {
   if (opts.expiringWithinDays !== undefined && opts.expiringWithinDays < 0) {
     throw new Error("createDocumentsFeature({ expiringWithinDays }) must not be negative.");
   }
+  for (const category of Object.keys(opts.categoryLabels ?? {})) {
+    if (!opts.categories.includes(category)) {
+      throw new Error(
+        `createDocumentsFeature({ categoryLabels }) names "${category}", which is not in categories.`,
+      );
+    }
+  }
   return defineFeature(DOCUMENTS_FEATURE_NAME, (r) => registerDocuments(r, opts));
 }

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

@@ -97,7 +97,7 @@ export function createImportDocumentHandler(args: ImportArgs) {
     name: "import",
     schema: importDocumentPayloadSchema,
     access: { roles: [SYSTEM_ROLE] },
-    agent: { expose: false },
+    agent: { expose: false, risk: "high" },
     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) => {

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

@@ -26,6 +26,7 @@ export function createLinkDocumentHandler(args: LinkHandlerArgs) {
     name: "link",
     schema: documentLinkPayloadSchema,
     access,
+    agent: { risk: "mid" },
     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>> => {
@@ -63,6 +64,7 @@ export function createUnlinkDocumentHandler(args: LinkHandlerArgs) {
     name: "unlink",
     schema: documentLinkPayloadSchema,
     access,
+    agent: { risk: "mid" },
     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>> => {

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

@@ -20,6 +20,20 @@ export const DOCUMENTS_FEATURE_I18N: Readonly<Record<string, LocalizedString>> =
   "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:write:link:title": {
+    en: "Link document to record",
+    de: "Dokument mit Datensatz verknüpfen",
+  },
+  "documents:write:link:field:documentId": { en: "Document", de: "Dokument" },
+  "documents:write:link:field:entityType": { en: "Record type", de: "Datensatztyp" },
+  "documents:write:link:field:entityId": { en: "Record", de: "Datensatz" },
+  "documents:write:unlink:title": {
+    en: "Remove document from record",
+    de: "Dokument von Datensatz lösen",
+  },
+  "documents:write:unlink:field:documentId": { en: "Document", de: "Dokument" },
+  "documents:write:unlink:field:entityType": { en: "Record type", de: "Datensatztyp" },
+  "documents:write:unlink:field:entityId": { en: "Record", de: "Datensatz" },
   "documents.errors.unknown-category": {
     en: "Unknown document category",
     de: "Unbekannte Dokumentenkategorie",

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

@@ -12,6 +12,7 @@ export {
   EXPIRY_STATES,
   type ExpiryState,
 } from "./constants.ts";
+export type { DocumentLinkReadMode } from "./entity.ts";
 export {
   createDocumentsFeature,
   type DocumentsAccess,

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

@@ -1,6 +1,6 @@
 import type { EditRelatedListSection } from "@cosmicdrift/kumiko-framework/engine";
 import type { DashboardStatPanel } from "@cosmicdrift/kumiko-framework/ui-types";
-import { DocumentsQueries } from "./constants.ts";
+import { DOCUMENT_ENTITY, DOCUMENTS_FEATURE_NAME, DocumentsQueries } from "./constants.ts";
 import { forTypeQueryQn } from "./queries/for-record.query.ts";
 
 // "Documents" tab for the edit screen of a link target. The tab id is the same on every screen,
@@ -11,7 +11,7 @@ export function documentsTab(entityType: string): EditRelatedListSection {
     kind: "relatedList",
     title: "documents:tab.title",
     query: forTypeQueryQn(entityType),
-    entity: "documents:document",
+    entity: `${DOCUMENTS_FEATURE_NAME}:${DOCUMENT_ENTITY}`,
     columns: [
       { field: "title", sortable: true },
       { field: "category", sortable: true },

package/packages/bundled-features/src/documents/target-write-check.ts

@@ -18,8 +18,10 @@ function updateHandlerAccessOf(registry: Registry, entityType: string) {
 }
 
 // Linking a document changes what readers of the target see, so it needs what saving the target
-// needs: read visibility, the entity's update handler and its row-level write rule. A target that
-// is not visible answers like a missing one.
+// needs: read visibility, a write gate and its row-level write rule. The gate is the entity's
+// update handler; an entity saved only through custom handlers has none, so its declared write
+// roles stand in, and without either the target stays unlinkable. A target that is not visible
+// answers like a missing one.
 export async function canWriteLinkTarget(
   registry: Registry,
   entityType: string,
@@ -31,7 +33,11 @@ export async function canWriteLinkTarget(
   const entity = registry.getEntity(entityType);
   if (entity === undefined) return false;
   const updateAccess = updateHandlerAccessOf(registry, entityType);
-  if (updateAccess === undefined || !hasAccess(user, updateAccess)) return false;
+  if (updateAccess !== undefined) {
+    if (!hasAccess(user, updateAccess)) return false;
+  } else if (!hasAccess(user, { roles: Object.keys(entity.access?.write ?? {}) })) {
+    return false;
+  }
   const row = await createEntityExecutor(entityType, entity).executor.detail(
     { id: entityId },
     user,

package/packages/bundled-features/src/managed-pages/screens/branding-screen.ts

@@ -65,7 +65,7 @@ export function createBrandingSettingsScreen(opts: {
         reason: "is_business_data",
       }),
       logoFile: createImageField({
-        accept: ["image/png", "image/jpeg", "image/webp"],
+        accept: ["png", "jpg", "jpeg", "webp"],
         personal: false,
         reason: "is_business_data",
       }),

package/packages/bundled-features/src/user-data-rights/web/i18n.ts

@@ -21,6 +21,10 @@ export const USER_DATA_RIGHTS_I18N: Readonly<Record<string, LocalizedString>> =
   },
   "user-data-rights:entity:export-job:field:userId": { en: "User" },
   "user-data-rights:entity:export-job:field:status": { en: "Status" },
+  "user-data-rights:entity:export-job:field:status:option:pending": { en: "Pending" },
+  "user-data-rights:entity:export-job:field:status:option:running": { en: "Running" },
+  "user-data-rights:entity:export-job:field:status:option:done": { en: "Done" },
+  "user-data-rights:entity:export-job:field:status:option:failed": { en: "Failed" },
   "user-data-rights:entity:export-job:field:requestedAt": { en: "Requested" },
   "user-data-rights:entity:export-job:field:completedAt": { en: "Completed" },
   "user-data-rights:entity:export-job:field:expiresAt": { en: "Expires" },

package/samples/recipes/relations/src/feature.ts

@@ -1,5 +1,10 @@
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
-import { createEntity, createTextField, defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  createEntity,
+  createReferenceField,
+  createTextField,
+  defineFeature,
+} from "@cosmicdrift/kumiko-framework/engine";
 
 export const teamEntity = createEntity({
   table: "read_sample_teams",
@@ -12,7 +17,12 @@ export const memberEntity = createEntity({
   table: "read_sample_members",
   fields: {
     name: createTextField({ personal: { of: "id" }, find: "none", required: true }),
-    teamId: createTextField({ personal: false, reason: "is_system_identifier", required: true }),
+    teamId: createReferenceField({
+      entity: "team",
+      personal: false,
+      reason: "is_system_identifier",
+      required: true,
+    }),
     role: createTextField({ personal: false, reason: "is_business_data" }),
   },
 });
@@ -21,7 +31,7 @@ export const taskEntity = createEntity({
   table: "read_sample_member_tasks",
   fields: {
     title: createTextField({ personal: false, reason: "is_business_data", required: true }),
-    memberId: createTextField({ personal: "ref", required: true }),
+    memberId: createReferenceField({ entity: "member", personal: "ref", required: true }),
   },
 });