@cosmicdrift/kumiko-samples 0.377.0 → 0.378.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.377.0",
+  "version": "0.378.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": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

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

package/packages/bundled-features/src/cap-counter/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "fix",
+    "title": "Stock caps are atomic under parallel writes",
+    "detail": "withStockCap now takes a transaction-scoped advisory lock per tenant and cap, so concurrent creates cannot both pass the check and exceed the cap."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "withStockCap no longer widens the handler's grants",
+    "detail": "withStockCap serialises through TenantDb.advisoryXactLock instead of ctx.db.unsafeRaw(), so wrapped handlers no longer receive an implicit unsafeRaw grant."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/cap-counter/stock-cap-guard.ts

@@ -24,6 +24,10 @@ export type CapLimitContext = {
   readonly config?: ConfigAccessor;
 };
 
+// pg_advisory_xact_lock namespace (int4): 'scap' as ASCII, disjoint from the
+// framework's other fixed advisory-lock keys.
+const STOCK_CAP_LOCK_NAMESPACE = 0x73636170;
+
 // What the cap guards need from a write handler's ctx.
 export type CapGuardContext = CapLimitContext & { readonly db: TenantDb };
 
@@ -53,6 +57,7 @@ export function createStockCapGuard<TCaps>(
     spec: StockCapSpec<TCaps>,
     context: CapLimitContext = {},
   ): Promise<WriteFailure | null> {
+    // Lock-free on its own: a direct call outside withStockCap is not atomic.
     const caps = await resolveTierCaps(db, context);
     const current = await db.count(spec.table, { ...spec.where, tenantId: db.tenantId });
     const { state, limit } = enforceStockCap({
@@ -73,6 +78,10 @@ export function createStockCapGuard<TCaps>(
     return {
       ...handler,
       handler: async (event, ctx) => {
+        // ctx.db is the handler's transaction, so the xact lock releases with its commit or
+        // rollback. A handler wrapped in several caps must list them in the same order
+        // everywhere; Postgres aborts one side of an inverse order with a deadlock error.
+        await ctx.db.advisoryXactLock(STOCK_CAP_LOCK_NAMESPACE, spec.code);
         const failure = await checkStockCap(ctx.db, spec, { config: ctx.config });
         return failure ?? handler.handler(event, ctx);
       },

package/packages/bundled-features/src/config/web/i18n.ts

@@ -34,6 +34,7 @@ export const defaultTranslations: TranslationsByLocale = {
     "config.settings.extensionSelectorHint":
       "Choose a provider. Its settings appear below and are saved together with it.",
     "config.settings.provider": "Provider",
+    "config.settings.provider.platformDefault": "Platform default",
     "config.settings.audience.system":
       "Applies to every tenant unless a tenant sets its own value.",
     "config.settings.audience.tenant":

package/packages/bundled-features/src/inbound-mail-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "fix",
+    "title": "Mailbox list accepts the screen's limit",
+    "detail": "account:list accepted an empty payload only, so the projectionList screen's limit was rejected. It now takes limit up to MAX_LIST_LIMIT and returns the visible mailboxes ordered by id."
+  },
   {
     "version": "0.377.0",
     "type": "improvement",

package/packages/bundled-features/src/inbound-mail-foundation/handlers/list-accounts.query.ts

@@ -11,13 +11,16 @@ import {
   configuredPiiSubjectKms,
   decryptPiiFieldValues,
 } from "@cosmicdrift/kumiko-framework/crypto";
-import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { MAX_LIST_LIMIT, type QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { MAIL_ACCOUNT_PII_FIELDS } from "../entities.ts";
 import { mailAccountsProjectionTable } from "../projection.ts";
 import { isVisibleToCaller } from "./scope-visibility.ts";
 
-const listAccountsSchema = z.object({}).strict();
+// The projectionList screen always sends `limit`; unknown keys stay rejected.
+const listAccountsSchema = z
+  .object({ limit: z.number().int().min(1).max(MAX_LIST_LIMIT).default(MAX_LIST_LIMIT) })
+  .strict();
 
 export const listAccountsQuery: QueryHandlerDef = {
   name: "account:list",
@@ -25,11 +28,15 @@ export const listAccountsQuery: QueryHandlerDef = {
   access: { roles: ["SystemAdmin", "TenantAdmin", "User"] },
   description:
     "Lists the connected mailboxes of the caller's tenant with the mailbox address decrypted, hiding personal mailboxes the caller neither owns nor administers; use it for the mail connect and settings views.",
-  handler: async (_query, ctx) => {
+  handler: async (query, ctx) => {
+    const { limit } = listAccountsSchema.parse(query.payload);
     const allRows = await ctx.db.selectMany(mailAccountsProjectionTable, {
       tenantId: ctx.user.tenantId,
     });
-    const rows = allRows.filter((row) => isVisibleToCaller(row, ctx.user));
+    const rows = allRows
+      .filter((row) => isVisibleToCaller(row, ctx.user))
+      .sort((a, b) => String(a["id"]).localeCompare(String(b["id"])))
+      .slice(0, limit);
     const piiKms = configuredPiiSubjectKms();
     if (!piiKms) return { rows };
     const decryptedRows = await Promise.all(

package/packages/bundled-features/src/mail-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Email sending offers a platform default and an own SMTP server",
+    "detail": "The provider field is labelled \"Send via\" with the options \"Platform sending (default)\" (empty, saved as \"\") and \"Own SMTP server\"; the SMTP fields show only while the own server is picked."
+  },
   {
     "version": "0.370.0",
     "type": "breaking",

package/packages/bundled-features/src/mail-foundation/i18n.ts

@@ -1,8 +1,9 @@
 export const MAIL_FOUNDATION_I18N = {
   "screen:mail-foundation-tenant.title": { en: "Email sending" },
   "mail-foundation.settings": { en: "Email sending" },
-  "mail-foundation.provider": { en: "Own mail server" },
+  "mail-foundation.provider": { en: "Send via" },
   "mail-foundation.provider.description": {
-    en: "Without one, the platform sends the mails. Reset the choice to go back to that.",
+    en: "Choose who sends your emails. The platform default needs no settings of your own.",
   },
+  "mail-foundation.provider.platformDefault": { en: "Platform sending (default)" },
 } as const;

package/packages/bundled-features/src/mail-transport-smtp/i18n.ts

@@ -1,6 +1,6 @@
 export const MAIL_TRANSPORT_SMTP_I18N = {
   // Also the option label of mail-foundation's provider select.
-  "mail-transport-smtp.settings": { en: "SMTP server" },
+  "mail-transport-smtp.settings": { en: "Own SMTP server" },
   "mail-transport-smtp.settings.secrets": { en: "SMTP sign-in" },
   "mail-transport-smtp.settings.description": {
     en: "The connection details come from your mail provider, for example Brevo, Postmark, Amazon SES or your own server.",

package/packages/bundled-features/src/template-resolver/changes.json

@@ -1,4 +1,24 @@
 [
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "Document PDFs embed the images of a record",
+    "detail": "A template variable of type images (templateVariable.images()) holds FileRef ids of the record. The new Images block (div[data-images], PDF templates only, rejected for mail kinds) renders them as data-URI images in the real PDF render. Only files of the rendering tenant are read, only png, jpeg, gif and webp, at most 24 images and 20 MB per document; missing, foreign, oversized or non-image ids are dropped silently. Previews and draft PDFs never read files and show one placeholder box per block. An images variable never renders as inline text. i18n keys template-resolver.documentEditor.images, template-resolver.documentEditor.imagesVariable and templateResolver.errors.document.imagesBlockPdfOnly ship in de, es, fr and it.",
+    "migration": "Declare a template variable with type `images`, place the Images block, and pass FileRef ids of the record in `variables`. Images resolve only in the real PDF render, previews show placeholders. The ids must come from the record on the server, never from client input: a resolved id is read for the whole tenant without an entity access check."
+  },
+  {
+    "version": "0.378.0",
+    "type": "breaking",
+    "title": "Template editing is SystemAdmin-only unless the app unlocks it",
+    "detail": "Every tenant write handler, the overview and resource upload accept SystemAdmin only, plus the roles of the tenantEditable entries. A write on a template that is not unlocked fails with templateNotTenantEditable. The test send follows the same rule. For a non-SystemAdmin an unknown template id answers 403 like a locked one, so the response does not reveal whether it exists. Collections without an access rule default to SystemAdmin.",
+    "migration": "Where TenantAdmins must keep editing a template, pass tenantEditable to createTemplateResolverFeature, for example tenantEditable: [{ kind: \"mail\", slug: \"billing:notify:invoice-issued\", access: { roles: [\"TenantAdmin\"] } }]. Give template collections an explicit access rule if tenants should manage them."
+  },
+  {
+    "version": "0.378.0",
+    "type": "improvement",
+    "title": "send-test-status query for the template test mail",
+    "detail": "template-resolver:query:send-test-status answers whether a test mail can be sent (canSend) and, if not, why (no_channel or no_address), so clients can disable the action instead of failing on send."
+  },
   {
     "version": "0.377.0",
     "type": "improvement",

package/packages/bundled-features/src/template-resolver/compile-document-body.ts

@@ -78,10 +78,15 @@ function valueExpression(
   return `{{${path}}}`;
 }
 
+// Never interpolated as text: its value is a list of file ids.
+function isImagesVariable(def: TemplateVariableDef | undefined): boolean {
+  return def?.type === "images";
+}
+
 function rewriteVariable(element: ScanElement, state: CompileState): void {
   const name = element.getAttribute("data-variable") ?? "";
   const replacement = element.ownerDocument.createTextNode(
-    isDocumentReferenceName(name)
+    isDocumentReferenceName(name) && !isImagesVariable(pathAndDef(name, element, state)[1])
       ? marker(
           state,
           valueExpression(
@@ -131,6 +136,8 @@ function wrapVariableOnlyBlock(block: ScanElement, state: CompileState): void {
   // skip: a line with static content or several placeholders stays as it is
   if (name === null) return;
   const [path, def] = pathAndDef(name, block, state);
+  // skip: images blocks are rewritten by rewriteImagesBlock
+  if (isImagesVariable(def)) return;
   const host =
     def?.type === "richText" && block.tagName === "P" ? richTextBlockHost(block, state) : block;
   const document = host.ownerDocument;
@@ -158,8 +165,8 @@ function rewriteLink(element: ScanElement, state: CompileState): void {
   if (isDocumentPlaceholderHref(href)) {
     const name = href.slice(2, -2);
     if (isDocumentReferenceName(name)) {
-      const [path] = pathAndDef(name, element, state);
-      element.setAttribute("href", marker(state, `{{link ${path}}}`));
+      const [path, def] = pathAndDef(name, element, state);
+      element.setAttribute("href", isImagesVariable(def) ? "#" : marker(state, `{{link ${path}}}`));
     } else {
       element.setAttribute("href", "#");
     }
@@ -225,8 +232,14 @@ export type CompileDocumentBodyOptions = {
   readonly headingAsInlineStyle?: boolean;
   // Bar color of reached stages in a steps block; ignored unless it is a #rrggbb hex.
   readonly stepsColor?: string;
+  // Data URIs of the record's images for the images block bound to `variable`.
+  readonly recordImagesSrc?: (variable: string) => readonly string[];
+  // Previews and drafts never read the record's files; each images block shows one neutral box.
+  readonly recordImagesPlaceholder?: boolean;
 };
 
+const IMAGES_PLACEHOLDER_STYLE = "height:96px;margin:8px 0;border-radius:4px;background:#e5e7eb";
+
 const MAIL_BUTTON_STYLE =
   "display:inline-block;padding:10px 20px;border-radius:6px;background-color:#1f5468;color:#ffffff;font-weight:600;text-decoration:none";
 
@@ -258,6 +271,48 @@ export function collectDocumentResourceKeys(html: string): readonly string[] {
   });
 }
 
+// Unique valid names of the images blocks in document order.
+export function collectDocumentImageVariables(html: string): readonly string[] {
+  return withParsedDocument(html, (root) => {
+    const names = new Set<string>();
+    for (const element of Array.from(root.querySelectorAll("div[data-images]"))) {
+      const name = element.getAttribute("data-images") ?? "";
+      if (isDocumentReferenceName(name)) names.add(name);
+    }
+    return [...names];
+  });
+}
+
+function rewriteImagesBlock(
+  element: ScanElement,
+  state: CompileState,
+  options: CompileDocumentBodyOptions,
+): void {
+  const name = element.getAttribute("data-images") ?? "";
+  const declared =
+    isDocumentReferenceName(name) && isImagesVariable(ownVariable(state.variables, name));
+  if (!declared) {
+    element.remove();
+    // skip: an images block bound to anything but a declared images variable renders nothing
+    return;
+  }
+  const document = element.ownerDocument;
+  element.removeAttribute("data-images");
+  if (options.recordImagesPlaceholder === true) {
+    element.setAttribute("class", "kumiko-doc-image-placeholder");
+    element.setAttribute("style", IMAGES_PLACEHOLDER_STYLE);
+    // skip: preview and drafts never resolve record images
+    return;
+  }
+  element.setAttribute("class", "kumiko-doc-images");
+  for (const src of options.recordImagesSrc?.(name) ?? []) {
+    const image = document.createElement("img");
+    image.setAttribute("src", src);
+    image.setAttribute("alt", "");
+    element.append(image);
+  }
+}
+
 export function toResourceDataUri(contentType: string, bytes: Uint8Array): string {
   if (!isResourceImageContentType(contentType)) {
     throw new Error(`resource content type "${contentType}" cannot be embedded as an image`);
@@ -374,6 +429,9 @@ export function compileDocumentBodyToHandlebars(
         color: options.stepsColor,
       });
     }
+    for (const element of Array.from(root.querySelectorAll("div[data-images]"))) {
+      rewriteImagesBlock(element, state, options);
+    }
     for (const block of Array.from(root.querySelectorAll(`[${DOCUMENT_CONDITION_ATTRIBUTE}]`))) {
       rewriteConditionalBlock(block, state);
     }

package/packages/bundled-features/src/template-resolver/constants.ts

@@ -99,3 +99,6 @@ export { SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 // Default-Locale wenn Tenant keinen eigenen Default konfiguriert. Resolver
 // fällt darauf zurück wenn requested locale + tenant-default fehlen.
 export const FALLBACK_LOCALE = "de";
+
+// A collection mounted without `access` is maintained by the platform only; TenantAdmin access is an explicit mount decision.
+export const DEFAULT_COLLECTION_ACCESS = { roles: ["SystemAdmin"] } as const;

package/packages/bundled-features/src/template-resolver/document-blocks.ts

@@ -7,7 +7,8 @@ export type DocumentToolbarBlock =
   | "repeat"
   | "pageBreak"
   | "align"
-  | "steps";
+  | "steps"
+  | "images";
 
 export const MAIL_DOCUMENT_BLOCKS = [
   "image",
@@ -25,6 +26,7 @@ export const PDF_DOCUMENT_BLOCKS = [
   "divider",
   "repeat",
   "steps",
+  "images",
   "pageBreak",
 ] as const satisfies readonly DocumentToolbarBlock[];
 

package/packages/bundled-features/src/template-resolver/document-images.ts

@@ -0,0 +1,29 @@
+// @runtime client
+// The record's photos: a block bound to an `images` variable whose FileRef ids the
+// app passes at render time. Universal like document-schema.ts.
+import { Node } from "@tiptap/core";
+
+export function createDocumentImagesNode(isReferenceName: (value: string) => boolean) {
+  return Node.create({
+    name: "images",
+    group: "block",
+    atom: true,
+    addAttributes() {
+      return { variable: { default: null } };
+    },
+    parseHTML() {
+      return [
+        {
+          tag: "div[data-images]",
+          getAttrs: (element) => {
+            const variable = element.getAttribute("data-images");
+            return variable !== null && isReferenceName(variable) ? { variable } : false;
+          },
+        },
+      ];
+    },
+    renderHTML({ node }) {
+      return ["div", { "data-images": node.attrs["variable"] }];
+    },
+  });
+}

package/packages/bundled-features/src/template-resolver/document-sanitizer.ts

@@ -26,6 +26,7 @@ export type DocumentViolationCode =
   | "invalid_reference_name"
   | "embedded_content"
   | "unsafe_attribute_value"
+  | "images_block_pdf_only"
   | "button_href_not_placeholder"
   | "document_requires_html_format"
   | "layout_requires_mjml_format"
@@ -143,6 +144,7 @@ const REFERENCE_ATTRIBUTES: ReadonlyArray<readonly [string, (value: string) => b
   [DOCUMENT_CONDITION_ATTRIBUTE, isDocumentReferenceName],
   ["data-resource", isDocumentResourceKey],
   ["data-steps", isDocumentReferenceName],
+  ["data-images", isDocumentReferenceName],
   ["data-step", isDocumentStepKey],
 ];
 
@@ -313,6 +315,36 @@ function requiredFormatViolation(
   return null;
 }
 
+const IMAGES_BLOCK_KIND = "document-pdf";
+
+// The node is part of the shared document model, so a mail body would keep it after the
+// rebuild; only a PDF resolves the record's images.
+function imagesBlockViolation(input: {
+  readonly kind: string;
+  readonly contentFormat: ContentFormat;
+  readonly content: string | null;
+}): DocumentViolation | null {
+  if (
+    input.kind === IMAGES_BLOCK_KIND ||
+    !isSanitizedHtmlKind(input.kind) ||
+    input.contentFormat !== "html" ||
+    input.content === null
+  ) {
+    return null;
+  }
+  const hasImagesBlock = withParsedDocument(
+    input.content,
+    (body) => body.querySelector("div[data-images]") !== null,
+  );
+  return hasImagesBlock
+    ? violation(
+        "images_block_pdf_only",
+        input.kind,
+        `Record images blocks are only allowed in templates of kind ${IMAGES_BLOCK_KIND}`,
+      )
+    : null;
+}
+
 export function sanitizeTemplateBody(input: {
   readonly kind: string;
   readonly contentFormat: ContentFormat;
@@ -320,6 +352,8 @@ export function sanitizeTemplateBody(input: {
 }): SanitizeBodyResult {
   const formatViolation = requiredFormatViolation(input.kind, input.contentFormat);
   if (formatViolation !== null) return { ok: false, violations: [formatViolation] };
+  const imagesViolation = imagesBlockViolation(input);
+  if (imagesViolation !== null) return { ok: false, violations: [imagesViolation] };
   if (
     !isSanitizedHtmlKind(input.kind) ||
     input.contentFormat !== "html" ||
@@ -340,6 +374,7 @@ const VIOLATION_I18N_KEYS: Readonly<Record<DocumentViolationCode, string>> = {
   invalid_reference_name: "templateResolver.errors.document.invalidReferenceName",
   embedded_content: "templateResolver.errors.document.embeddedContent",
   unsafe_attribute_value: "templateResolver.errors.document.unsafeAttributeValue",
+  images_block_pdf_only: "templateResolver.errors.document.imagesBlockPdfOnly",
   button_href_not_placeholder: "templateResolver.errors.document.buttonHrefNotPlaceholder",
   document_requires_html_format: "templateResolver.errors.document.documentRequiresHtmlFormat",
   layout_requires_mjml_format: "templateResolver.errors.document.layoutRequiresMjmlFormat",

package/packages/bundled-features/src/template-resolver/document-schema.ts

@@ -8,6 +8,7 @@ import { Extension, type Extensions, Node } from "@tiptap/core";
 import { Link } from "@tiptap/extension-link";
 import { Table, TableCell, TableHeader, TableRow } from "@tiptap/extension-table";
 import StarterKit from "@tiptap/starter-kit";
+import { createDocumentImagesNode } from "./document-images.ts";
 import { createDocumentStepsNode } from "./document-steps.ts";
 
 const PLACEHOLDER_HREF = /^\{\{(.+)\}\}$/;
@@ -73,6 +74,7 @@ export const DOCUMENT_NODE_NAMES = [
   "divider",
   "pageBreak",
   "steps",
+  "images",
 ] as const;
 
 export const DocumentVariable = Node.create({
@@ -184,6 +186,8 @@ export const DocumentPageBreak = Node.create({
 
 export const DocumentSteps = createDocumentStepsNode(isDocumentReferenceName);
 
+export const DocumentImages = createDocumentImagesNode(isDocumentReferenceName);
+
 // A repeat row is a table row carrying `each`: prosemirror-tables requires
 // the tableRow node type, so a separate node type is not an option.
 export const DocumentTableRow = TableRow.extend({
@@ -378,6 +382,7 @@ export const documentExtensions: Extensions = [
   DocumentDivider,
   DocumentPageBreak,
   DocumentSteps,
+  DocumentImages,
   DocumentTextAlign,
   DocumentTextSize,
   DocumentCondition,