@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

package/packages/bundled-features/src/template-resolver/web/use-content-write.ts

@@ -0,0 +1,81 @@
+import { dispatcherErrorText, useDispatcher, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { DispatcherError } from "@cosmicdrift/kumiko-renderer/headless";
+import { useCallback, useState } from "react";
+import { isTenantOverrideDeniedError } from "./tenant-override.ts";
+
+export type TenantScopedWrite = {
+  readonly response: ContentWriteResponse;
+  /** The override the write was accepted with; undefined after a denied override fell back to the session tenant. */
+  readonly tenantIdOverride: string | undefined;
+};
+
+export type ContentWriteResponse = {
+  readonly slug: string;
+  readonly locale: string;
+  readonly isNew: boolean;
+};
+
+type Translate = (key: string, params?: Readonly<Record<string, unknown>>) => string;
+
+// A validation failure names the offending field with its own message; prefer that over the generic one.
+function writeErrorText(error: DispatcherError, t: Translate): string {
+  const issue = error.details?.fields?.[0];
+  if (issue !== undefined) {
+    const translated = t(issue.i18nKey, issue.params);
+    if (translated !== issue.i18nKey) return translated;
+  }
+  return dispatcherErrorText(error, t) || t("template-resolver.editor.saveFailed");
+}
+
+// Dispatches a content set and keeps the submit state; `write` resolves to the response,
+// or null after the failure text has been set in `error`.
+export function useContentWrite() {
+  const dispatcher = useDispatcher();
+  const t = useTranslation();
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const writeScoped = async (
+    handler: string,
+    payload: Readonly<Record<string, unknown>>,
+    requestedOverride: string | undefined,
+  ): Promise<TenantScopedWrite | null> => {
+    setSubmitting(true);
+    setError(null);
+    try {
+      let tenantIdOverride = requestedOverride;
+      let result = await dispatcher.write<ContentWriteResponse>(handler, {
+        ...payload,
+        ...(tenantIdOverride !== undefined && { tenantIdOverride }),
+      });
+      if (
+        !result.isSuccess &&
+        tenantIdOverride !== undefined &&
+        isTenantOverrideDeniedError(result.error)
+      ) {
+        tenantIdOverride = undefined;
+        result = await dispatcher.write<ContentWriteResponse>(handler, payload);
+      }
+      if (result.isSuccess) return { response: result.data, tenantIdOverride };
+      setError(writeErrorText(result.error, t));
+      return null;
+    } catch (e) {
+      // Network blip / dispatcher throw — otherwise submitting stays true and
+      // the save button is locked forever with no feedback.
+      setError(e instanceof Error ? e.message : t("template-resolver.editor.networkError"));
+      return null;
+    } finally {
+      setSubmitting(false);
+    }
+  };
+
+  const write = async (
+    handler: string,
+    payload: Readonly<Record<string, unknown>>,
+  ): Promise<ContentWriteResponse | null> =>
+    (await writeScoped(handler, payload, undefined))?.response ?? null;
+
+  const clearError = useCallback(() => setError(null), []);
+
+  return { submitting, error, clearError, write, writeScoped };
+}

package/packages/bundled-features/src/template-resolver/web/use-text-block-editor.ts

@@ -0,0 +1,127 @@
+import type { TargetRef } from "@cosmicdrift/kumiko-framework/engine";
+import { useQuery, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useEffect, useState } from "react";
+import { refreshTree, TEXT_BLOCK_TREE_KEY } from "./content-tree-provider.ts";
+import { convertLegacyVariableText } from "./legacy-variable-text.ts";
+import {
+  collectionHandlerName,
+  collectionQueryName,
+  TemplateResolverHandlers,
+  TemplateResolverQueries,
+} from "./qualified-names.ts";
+import { useCollectionEditorContext } from "./use-collection-editor-context.ts";
+import { useContentWrite } from "./use-content-write.ts";
+
+type TextBlock = {
+  readonly slug: string;
+  readonly locale: string;
+  readonly title: string | null;
+  readonly content: string | null;
+  readonly contentFormat: string;
+  readonly folder: string | null;
+  readonly modifiedAt: string | null;
+};
+
+type EditTargetArgs = {
+  slug?: string;
+  locale?: string;
+  collectionId?: string;
+  tenantIdOverride?: string;
+};
+
+export function useTextBlockEditor(target: TargetRef) {
+  // @cast-boundary visual-tree-args — TargetRef.args is erased to
+  // Record<string, unknown>; the resolver knows the action shape (see the
+  // treeActions.edit definition in feature.ts) and de-erases per action, the
+  // same way event payloads do. Optional chaining absorbs missing fields so a
+  // hand-edited URL cannot crash the editor.
+  const args = target.args as EditTargetArgs | undefined;
+  const slug = args?.slug ?? "";
+  const locale = args?.locale ?? "";
+  const tenantIdOverride = args?.tenantIdOverride;
+  // Which collection the node came from. Absent → the public text-block pair,
+  // which is what the hand-wired content tree uses.
+  const collectionId = args?.collectionId;
+
+  const t = useTranslation();
+  const editorContext = useCollectionEditorContext(collectionId);
+  const { contentFormat, canWrite } = editorContext;
+  const { submitting, error: saveError, clearError, write } = useContentWrite();
+
+  // Same split as the tree provider: a node without a collection reads through
+  // the public by-slug, a collection node through that collection's handlers.
+  const readQuery =
+    collectionId === undefined
+      ? TemplateResolverQueries.bySlug
+      : collectionQueryName(collectionId, "item");
+  const writeHandler =
+    collectionId === undefined ? TemplateResolverHandlers.set : collectionHandlerName(collectionId);
+  const {
+    data: loaded,
+    loading,
+    error: loadError,
+  } = useQuery<TextBlock | null>(
+    readQuery,
+    { slug, locale, ...(tenantIdOverride !== undefined && { tenantIdOverride }) },
+    { enabled: slug !== "" && locale !== "" },
+  );
+
+  const [title, setTitle] = useState("");
+  const [content, setContent] = useState("");
+  const [savedMsg, setSavedMsg] = useState<string | null>(null);
+
+  // Sync loaded data into the form state. loaded === null means the block does
+  // not exist yet — empty form for the create flow.
+  // kumiko-lint-ignore no-raw-hooks not yet converted to the framework hook set
+  useEffect(() => {
+    // skip: keep the form untouched until the query settles
+    if (loading) return;
+    const loadedContent = loaded?.content ?? "";
+    setTitle(loaded?.title ?? "");
+    setContent(
+      contentFormat === "document" ? convertLegacyVariableText(loadedContent) : loadedContent,
+    );
+    clearError();
+    setSavedMsg(null);
+  }, [loading, loaded, contentFormat, clearError]);
+
+  const save = async (): Promise<void> => {
+    setSavedMsg(null);
+    const response = await write(writeHandler, {
+      slug,
+      locale,
+      title,
+      content: content.length > 0 ? content : null,
+      folder: loaded?.folder ?? null,
+      // A collection derives its storage format on the server; the public set keeps what was saved.
+      ...(collectionId === undefined &&
+        loaded?.contentFormat !== undefined && { contentFormat: loaded.contentFormat }),
+      ...(tenantIdOverride !== undefined && { tenantIdOverride }),
+    });
+    // skip: useContentWrite already set the failure text
+    if (response === null) return;
+    refreshTree(collectionId ?? TEXT_BLOCK_TREE_KEY);
+    setSavedMsg(
+      response.isNew ? t("template-resolver.editor.created") : t("template-resolver.editor.saved"),
+    );
+  };
+
+  return {
+    slug,
+    locale,
+    editorContext,
+    canWrite,
+    loading,
+    loadError,
+    submitting,
+    saveError,
+    savedMsg,
+    disabled: submitting || loading || !canWrite,
+    saveLabelKey: submitting ? "template-resolver.editor.saving" : "template-resolver.editor.save",
+    title,
+    setTitle,
+    content,
+    setContent,
+    save,
+  };
+}

package/packages/bundled-features/src/tier-engine/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.395.0",
+    "type": "fix",
+    "title": "The tier resolver no longer keeps tier writes made before its build",
+    "detail": "A tier write that ran before build() cached a feature set without the always-on features, and a later build() left that entry in place, so the tenant got feature_disabled instead of the default fallback. build() now starts from an empty cache and writes before it are not cached."
+  },
   {
     "version": "0.392.0",
     "type": "fix",

package/packages/bundled-features/src/tier-engine/feature.ts

@@ -337,6 +337,7 @@ export function createTierEngineFeature<
       // reload result is applied only while its ticket is still the tenant's latest.
       let ticketCounter = 0;
       const latestTicket = new Map<TenantId, number>();
+      let isBuilt = false;
       const takeTicket = (tenantId: TenantId): number => {
         ticketCounter += 1;
         latestTicket.set(tenantId, ticketCounter);
@@ -370,7 +371,9 @@ export function createTierEngineFeature<
       // bus and re-read the row.
       const applyAssignment = (tenantId: TenantId, tier: string): void => {
         takeTicket(tenantId);
-        cache.set(tenantId, mergeAlwaysOn(alwaysOnHolder.set, featuresForTier(tierMap, tier)));
+        // Before build() the always-on set is empty; a cached entry would outlive into the next build.
+        if (isBuilt)
+          cache.set(tenantId, mergeAlwaysOn(alwaysOnHolder.set, featuresForTier(tierMap, tier)));
         publishAssignmentChange(tenantId);
       };
       onTierAssigned.fn = applyAssignment;
@@ -516,6 +519,11 @@ export function createTierEngineFeature<
             if (feature.toggleableDefault === undefined) computedAlwaysOn.add(feature.name);
           }
           alwaysOnHolder.set = computedAlwaysOn;
+          // One feature instance can serve several stacks in a process; rebuild state from this DB only.
+          // Safe vs. "never clear-then-refill": no request reaches this resolver before build() returns.
+          cache.clear();
+          latestTicket.clear();
+          isBuilt = true;
 
           // Pre-load all existing assignments into the cache. SaaS apps typically
           // have <100k tenants, so a single-pass scan is acceptable. The scaling

package/packages/bundled-features/src/user-data-rights-defaults/hooks/file-ref.userdata-hook.ts

@@ -177,7 +177,8 @@ function isPersonalFileRow(registry: Registry, row: Record<string, unknown>): bo
   if (row["entityId"] === null && resolveActionFormFileField(registry, entityType, fieldName)) {
     return true;
   }
-  const fieldDef = registry.getEntity(entityType)?.fields[fieldName];
+  const entity = registry.getEntity(entityType) ?? registry.getReadModelEntity(entityType);
+  const fieldDef = entity?.fields[fieldName];
   return isPersonalPiiField(fieldDef);
 }
 

package/samples/apps/use-all-bundled/e2e-billing-gallery/gallery-constants.ts

@@ -19,3 +19,7 @@ export const GALLERY_MOR_PRICE_IDS = {
   starter: "price_gallery_mor_starter",
   pro: "price_gallery_mor_pro",
 };
+
+// Set by the docs gallery config: net catalog prices with a "plus VAT" note and a gross recurring
+// price in the plan-switch preview. The German review gallery runs without it and stays unchanged.
+export const GALLERY_DOCS_VARIANT_ENV = "GALLERY_DOCS_VARIANT";

package/samples/apps/use-all-bundled/e2e-billing-gallery/gallery-features.ts

@@ -20,6 +20,7 @@ import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import {
+  GALLERY_DOCS_VARIANT_ENV,
   GALLERY_MOR_PRICE_IDS,
   GALLERY_MOR_PROVIDER,
   GALLERY_OPERATOR_EMAIL,
@@ -29,6 +30,8 @@ import {
   GALLERY_TERMS_SLUG,
 } from "./gallery-constants";
 
+const isDocsVariant = process.env[GALLERY_DOCS_VARIANT_ENV] === "1";
+
 export const galleryMailTransport = createInMemoryTransport();
 
 // The merchant-of-record mock is only offered to tenants the spec opts in, so
@@ -93,6 +96,7 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
       tierLabelKey: (tier) => `gallery-screens:plan.${tier}.label`,
       benefits: (tier) => [{ labelKey: `gallery-screens:plan.${tier}.benefit` }],
       resolveCurrentTier,
+      ...(isDocsVariant && { priceNoteKey: "gallery-screens:plan.price-note" }),
       viewRoles: ["TenantAdmin", "SystemAdmin"],
       successPath: GALLERY_PLAN_PATH,
       cancelPath: GALLERY_PLAN_PATH,
@@ -115,12 +119,12 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
         },
         [GALLERY_MOR_PROVIDER]: {
           checkoutNote: {
-            de: "Verkäufer ist Dodo Payments · Rechnung und USt von Dodo Payments",
-            en: "Sold by Dodo Payments · invoice and VAT from Dodo Payments",
+            de: "Verkäufer ist Paddle · Rechnung und USt von Paddle",
+            en: "Sold by Paddle · invoice and VAT from Paddle",
           },
           vatNote: {
-            de: "Rechnung und Umsatzsteuer stellt Dodo Payments als Merchant of Record.",
-            en: "Dodo Payments, as merchant of record, issues the invoice and charges the VAT.",
+            de: "Rechnung und Umsatzsteuer stellt Paddle als Merchant of Record.",
+            en: "Paddle, as merchant of record, issues the invoice and charges the VAT.",
           },
         },
       },
@@ -164,7 +168,7 @@ const galleryProviderPlugin: SubscriptionProviderPlugin = {
 // consent id fails, so a successful switch in the spec proves the consent went
 // through.
 const galleryMorProviderPlugin: SubscriptionProviderPlugin = {
-  displayName: "Dodo Payments",
+  displayName: "Paddle",
   isBillingEnabled: async (ctx) => morEnabledTenants.has(ctx.user.tenantId),
   verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody),
   priceToTier: {
@@ -184,6 +188,7 @@ const galleryMorProviderPlugin: SubscriptionProviderPlugin = {
     tax: 106,
     currency: "eur",
     credit: 333,
+    ...(isDocsVariant && { recurringAmount: 2368, recurringTax: 378 }),
     effectiveAt: "2027-01-15T00:00:00Z",
   }),
   applyPlanSwitch: async (_ctx, options) => {
@@ -218,6 +223,7 @@ export const galleryScreensFeature: FeatureDefinition = defineFeature("gallery-s
   r.translations({
     keys: {
       "gallery:nav.billing": { de: "Abrechnung", en: "Billing" },
+      "gallery-screens:plan.price-note": { de: "zzgl. USt.", en: "plus VAT" },
       "gallery-screens:plan.free.label": { de: "Free", en: "Free" },
       "gallery-screens:plan.starter.label": { de: "Starter", en: "Starter" },
       "gallery-screens:plan.pro.label": { de: "Pro", en: "Pro" },

package/samples/apps/use-all-bundled/e2e-billing-gallery/server.ts

@@ -30,11 +30,11 @@ const port = Number.parseInt(process.env["PORT"] ?? "4196", 10);
 
 const BILLING_FEATURE = "billing-foundation";
 const EMAIL_FEATURE = "channel-email";
-// The stock app mounts the real Mollie and Dodo providers; the gallery's
+// The stock app mounts the real Mollie and Paddle providers; the gallery's
 // provider choice is the two mocks, which never call out.
 const REAL_PROVIDER_FEATURES: ReadonlySet<string> = new Set([
   "subscription-mollie",
-  "subscription-dodo",
+  "subscription-paddle",
 ]);
 
 const features = [

package/samples/apps/use-all-bundled/feature-manifest.json

@@ -316,7 +316,7 @@
     },
     {
       "name": "billing-foundation",
-      "description": "Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-dodo` unless you are writing a new payment provider.",
+      "description": "Plugin host for subscription billing. Manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. `createBillingFoundationFeature({ baseUrl, catalog })` additionally derives a `billing-foundation:query:billing-plans` query, `start-plan-checkout`/`switch-plan` write-handlers, a `plan-switch-preview` query and a dormant billing-plans dashboard screen/panel from the catalog. Several providers can be mounted at once: new checkouts are offered by every enabled provider (enabled means keys set and billingLive on, or simply mounted for plugins without `isBillingEnabled`), the customer picks one in the plan panel and `start-plan-checkout` takes a `providerName`. An existing subscription stays with the provider that stored it, so the plan list and every switch follow that provider. A plan switch is either hosted (`createPlanSwitchSession` answers a url) or in-app (`previewPlanSwitch` shows the proration, `applyPlanSwitch` runs after the customer confirms; `switch-plan` then answers `{ applied: true }` and records the consent). `consumerProtection.providerTexts` overrides the checkout note and the VAT note per provider. Also ships `billing-foundation:write:sync-subscription` (pulls a provider plugin's live subscription state via `retrieveSubscription` and appends drift as a `subscription.updated` event, which catches changes made on the provider's own dashboard that never reached us as a webhook) and the `sync-subscriptions` job (manual-trigger + runOnBoot, perTenant) that dispatches it. Low-level building block: use `subscription-stripe`, `subscription-mollie` or `subscription-paddle` unless you are writing a new payment provider.",
       "toggleableDefault": null,
       "requires": [
         "tenant-lifecycle",
@@ -1421,9 +1421,15 @@
       "configKeys": [],
       "secrets": [],
       "writeHandlers": [
+        "inbound-mail-foundation:write:acknowledge-quarantine",
+        "inbound-mail-foundation:write:attach-message-content",
         "inbound-mail-foundation:write:connect-account",
         "inbound-mail-foundation:write:disconnect-account",
         "inbound-mail-foundation:write:ingest-message",
+        "inbound-mail-foundation:write:mark-credential-stored",
+        "inbound-mail-foundation:write:reactivate-account",
+        "inbound-mail-foundation:write:retry-quarantined-message",
+        "inbound-mail-foundation:write:set-trusted-authserv-id",
         "inbound-mail-foundation:write:update-account"
       ],
       "uiHints": {
@@ -1434,7 +1440,7 @@
     },
     {
       "name": "inbound-provider-imap",
-      "description": "Registers the `\"imap\"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a mailbox through the \"Connect mailbox\" form on the mail accounts list (`connect-mailbox` checks the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.",
+      "description": "Registers the `\"imap\"` provider for `inbound-mail-foundation` using imapflow — password/app-password auth covers classic IMAP hosts without any OAuth (plus an XOAUTH2 fallback consuming an access token from the secret slot). Incremental sync via a UIDVALIDITY:lastUid cursor (UIDVALIDITY change triggers a cursor-invalid full resync), initial backfill bounded by the foundation backfill window, and live push via IMAP IDLE for the watch supervisor. Tenant admins connect a shared mailbox through the \"Connect mailbox\" form on the mail accounts list and members a personal one through the same form on \"My mail accounts\" (`connect-mailbox` and `connect-my-mailbox` check the IMAP login and the SMTP login of the outgoing server first, then creates the account and its credential secret in one transaction; `reconnect-mailbox` does the same check for an existing mailbox with a sign-in error and overwrites its credential secret); programmatic setups store the per-account connection JSON (host/port/secure/user/password, plus smtpHost/smtpPort for sending) in the account credential secret slot before the first sync. Implements the provider `send`: `sendMailFromAccount` sends over the SMTP server of the mailbox itself (implicit TLS, same login) with the mailbox address as From and stores a copy in its sent folder.",
       "toggleableDefault": null,
       "requires": [
         "inbound-mail-foundation",
@@ -1454,6 +1460,7 @@
       "secrets": [],
       "writeHandlers": [
         "inbound-provider-imap:write:connect-mailbox",
+        "inbound-provider-imap:write:connect-my-mailbox",
         "inbound-provider-imap:write:reconnect-mailbox"
       ],
       "uiHints": {
@@ -1786,7 +1793,7 @@
     },
     {
       "name": "managed-pages",
-      "description": "Tenant-editable, server-rendered public pages with per-tenant branding. Stores one Markdown `page` per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.",
+      "description": "Tenant-editable, server-rendered public pages with per-tenant branding. Stores one `page` (Markdown or editor-document HTML body, per `bodyFormat`) per `(tenantId, slug, lang)` in the `read_pages` entity table with a `published` gate plus `description`/`ogImage` SEO meta. Registers an anonymous `GET {basePath}/:slug` route that resolves the tenant from the request Host via the app-supplied `resolveApexTenant`, serves only published pages (drafts → 404), renders Markdown through the hardened `page-render` core and document bodies through the template-resolver document sanitizer, and isolates per-tenant content with `Vary: Host`. Ships TenantAdmin/SystemAdmin admin screens (`entityList` + `entityEdit`) backed by convention CRUD handlers (`managed-pages:write:page:{create,update,delete}`, `managed-pages:query:page:{list,detail}`); the app wires nav/workspace onto `managed-pages:screen:page-list`. Also exposes `managed-pages:query:by-tenant-published` (anonymous, SQL-filtered on `published`) for sitemap/discovery consumers such as the `seo` feature. Branding (via `config`, scope tenant): `branding-{title,description,site-url,accent-color,logo-url,layout-preset,custom-css}` keys with write-time validation (hex color, https URLs), a `configEdit` self-service screen (`managed-pages:screen:branding-settings`), and a `managed-pages:query:branding` read that the render path applies as scoped `:root` CSS vars + a logo/title header. Also exposes `managed-pages:write:set` (idempotent slug-keyed upsert, SystemAdmin cross-tenant via `tenantIdOverride`) as a provisioning API. Requires `config` + `anonymousAccess` wired at app bootstrap.",
       "toggleableDefault": null,
       "adoptsBundledLists": true,
       "requires": [
@@ -2505,8 +2512,34 @@
       }
     },
     {
-      "name": "subscription-dodo",
-      "description": "Dodo Payments provider plugin for `billing-foundation`. Dodo acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key and webhook secret from system config keys with `backing:\"secrets\"` (envelope-encrypted in the secrets store under the system tenant), plus a `billingLive` master switch and an `environment` key (test | live). `environment` is its own key because Dodo serves test and live mode from different API hosts and a live key must never hit the test host or the other way round; `billingLive` only decides whether checkouts are offered at all. All four are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionDodoFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env to secrets bridge fallbacks (`DODO_PAYMENTS_API_KEY`, `DODO_PAYMENTS_WEBHOOK_KEY`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true. Webhooks arrive at `/api/subscription/webhook/dodo` and are verified per the Standard Webhooks spec (HMAC-SHA256 over id, timestamp and the raw body, 5 minute tolerance); events for products outside `priceToTier` or without tenant metadata are dropped. Implements hosted checkout, customer portal, cancel and resume, `retrievePrices` (10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `plan_changed` webhook to move the tier. A plan switch in Dodo requires all plan products to belong to one Product Collection.",
+      "name": "subscription-mollie",
+      "description": "Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` — the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType=\"first\"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.",
+      "toggleableDefault": null,
+      "requires": [
+        "billing-foundation"
+      ],
+      "optionalRequires": [],
+      "configReads": [],
+      "exposesApis": [],
+      "usesApis": [],
+      "extensionsUsed": [
+        {
+          "extensionName": "subscriptionProvider",
+          "entityName": "mollie"
+        }
+      ],
+      "configKeys": [],
+      "secrets": [],
+      "writeHandlers": [],
+      "uiHints": {
+        "displayLabel": "Billing · Mollie",
+        "category": "billing",
+        "recommended": false
+      }
+    },
+    {
+      "name": "subscription-paddle",
+      "description": "Paddle Billing provider plugin for `billing-foundation`. Paddle acts as merchant of record: it sells to the customer and issues invoice and VAT, so the consumer-protection texts for this provider come from `consumerProtection.providerTexts`. Reads its API key, webhook secret and tenant binding key from system config keys with `backing:\"secrets\"` (envelope-encrypted in the secrets store under the system tenant), the public Paddle.js `client-token`, a `billingLive` master switch and an `environment` key (sandbox | live). `environment` is its own key because Paddle serves sandbox and live from different API hosts and a live key must never hit the sandbox host or the other way round; `billingLive` only decides whether checkouts are offered at all. All of them are runtime config, so keys rotate and prod goes live without a redeploy, and the `mask` on each derives the sysadmin settings screen and nav. Mount via `createSubscriptionPaddleFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret`/`tenantBindingKey`/`clientToken` options are env to config bridge fallbacks (`PADDLE_API_KEY`, `PADDLE_WEBHOOK_SECRET`, `PADDLE_TENANT_BINDING_KEY`, `PADDLE_CLIENT_TOKEN`). The plugin always mounts; `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, and billing counts as enabled only with API key and binding key present. Webhooks arrive at `/webhooks/subscription/paddle` when mounted through the server-runtime `billing.paddle` boot option, or at `/api/subscription/webhook/paddle` when `createSubscriptionWebhookRoute` is mounted by hand and are verified with the `Paddle-Signature` header (HMAC-SHA256 over `ts:rawBody` keyed with the raw secret, any `h1` may match, 5 minute tolerance). Paddle.js can open checkouts with arbitrary `customData` from the browser, so `custom_data.tenantId` is only trusted together with `tenantBinding`, an HMAC of the tenant id under the binding key; events without a valid binding, for prices outside `priceToTier` or without a tenant are dropped. Rotating the binding key makes the webhooks of existing subscriptions fail that check until they are re-bound. Paddle has no hosted checkout page, so the feature serves the Default Payment Link itself at `/billing/paddle-checkout` (the Default Payment Link in the Paddle dashboard must point to `<APP_BASE_URL>/billing/paddle-checkout`; it is the only source, because checkouts are created without a `checkout.url`). Create subscription prices in the Paddle catalog with quantity minimum and maximum 1; for one-off packs set the quantity limits on purpose, because the payment event carries `quantity` and the app has to multiply its credits by it: an anonymous page with its own CSP that loads Paddle.js from cdn.paddle.com, the one external script this framework allows, and opens the overlay for the transaction. Implements checkout, customer portal, cancel and resume, `retrievePrices` (batched, 10-minute TTL cache), `retrieveSubscription` for the sync job, and an in-app plan switch: `previewPlanSwitch` shows the proration before the customer confirms, `applyPlanSwitch` changes the plan without a hosted page and waits for the `subscription.updated` webhook to move the tier.",
       "toggleableDefault": null,
       "requires": [
         "billing-foundation",
@@ -2520,13 +2553,13 @@
       "extensionsUsed": [
         {
           "extensionName": "subscriptionProvider",
-          "entityName": "dodo"
+          "entityName": "paddle"
         }
       ],
       "configKeys": [
         {
           "key": "api-key",
-          "qualifiedName": "subscription-dodo:config:api-key",
+          "qualifiedName": "subscription-paddle:config:api-key",
           "type": "text",
           "scope": "system",
           "default": null,
@@ -2547,7 +2580,7 @@
         },
         {
           "key": "billing-live",
-          "qualifiedName": "subscription-dodo:config:billing-live",
+          "qualifiedName": "subscription-paddle:config:billing-live",
           "type": "boolean",
           "scope": "system",
           "default": false,
@@ -2567,17 +2600,38 @@
             "SystemAdmin"
           ]
         },
+        {
+          "key": "client-token",
+          "qualifiedName": "subscription-paddle:config:client-token",
+          "type": "text",
+          "scope": "system",
+          "default": null,
+          "encrypted": false,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
+        },
         {
           "key": "environment",
-          "qualifiedName": "subscription-dodo:config:environment",
+          "qualifiedName": "subscription-paddle:config:environment",
           "type": "select",
           "scope": "system",
-          "default": "test",
+          "default": "sandbox",
           "encrypted": false,
           "computed": false,
           "validated": false,
           "options": [
-            "test",
+            "sandbox",
             "live"
           ],
           "bounds": null,
@@ -2592,8 +2646,8 @@
           ]
         },
         {
-          "key": "webhook-secret",
-          "qualifiedName": "subscription-dodo:config:webhook-secret",
+          "key": "tenant-binding-key",
+          "qualifiedName": "subscription-paddle:config:tenant-binding-key",
           "type": "text",
           "scope": "system",
           "default": null,
@@ -2611,38 +2665,33 @@
             "Admin",
             "SystemAdmin"
           ]
-        }
-      ],
-      "secrets": [],
-      "writeHandlers": [],
-      "uiHints": {
-        "displayLabel": "Billing · Dodo Payments",
-        "category": "billing",
-        "recommended": false
-      }
-    },
-    {
-      "name": "subscription-mollie",
-      "description": "Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` — the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType=\"first\"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.",
-      "toggleableDefault": null,
-      "requires": [
-        "billing-foundation"
-      ],
-      "optionalRequires": [],
-      "configReads": [],
-      "exposesApis": [],
-      "usesApis": [],
-      "extensionsUsed": [
+        },
         {
-          "extensionName": "subscriptionProvider",
-          "entityName": "mollie"
+          "key": "webhook-secret",
+          "qualifiedName": "subscription-paddle:config:webhook-secret",
+          "type": "text",
+          "scope": "system",
+          "default": null,
+          "encrypted": true,
+          "computed": false,
+          "validated": false,
+          "options": null,
+          "bounds": null,
+          "pattern": null,
+          "writeRoles": [
+            "SystemAdmin"
+          ],
+          "readRoles": [
+            "TenantAdmin",
+            "Admin",
+            "SystemAdmin"
+          ]
         }
       ],
-      "configKeys": [],
       "secrets": [],
       "writeHandlers": [],
       "uiHints": {
-        "displayLabel": "Billing · Mollie",
+        "displayLabel": "Billing · Paddle",
         "category": "billing",
         "recommended": false
       }
@@ -2775,7 +2824,7 @@
     },
     {
       "name": "template-resolver",
-      "description": "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).\n\nReading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away.\n\nEditing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: \"mail\", slug: \"status-update\", access: { roles: [\"TenantAdmin\"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host's roles. The same list decides delivery: a tenant override is served (mail, PDF, layouts, text blocks) only while its template is listed in tenantEditable; otherwise the system version is served. A locked override stays stored, a SystemAdmin sees it in the overview marked as not delivered, and listing the template makes it effective again. Tenant rows of a collection mounted with `access` are always served. A collection mounted without `access` is SystemAdmin only.\n\nText an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.\n\nHow a collection is edited follows from `contentFormat`: `plain` gives a text area, `rich` a small WYSIWYG (bold, italic, headings, lists, links), `markdown` a text area that stores markdown text (same insertable chips as `plain`). All three offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).\n\nA collection is tenant-wide by default. With `ownership: \"user\"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.\n\n`validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only.\n\n`preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address.\n\nImages used by a template (`<img data-resource=\"logo\">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: \"attachment\"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
+      "description": "Every piece of editable text lives here, in one entity: mail bodies, notification texts, PDF document templates, AI prompts and plain text blocks. What a record is used for is the `kind` (`notification`, `mail`, `mail-layout`, `document-pdf`, `pdf-layout`, `ai-prompt`, `text-block`, `snippet`, `image-snapshot`).\n\nReading is one call — `ctx.templateResolver.resolveTemplate({ tenantId, slug, kind, locale })`. It walks four levels: tenant+locale, system+locale, tenant+fallback-locale, system+fallback-locale. A tenant overrides a system default by simply having its own record; no application code changes. Writing programmatically goes through the `upsertSystem`, `upsertTenant`, `publish` and `archive` write handlers; a SystemAdmin retires or restores a system default with `publishSystem` and `archiveSystem`, and a tenant drops its override with `resetToSystem`. Saving a draft over an active template keeps the active version served and stores the edit beside it (column `draft`); `publish` makes it the served version, `discardDraft` / `discardDraftSystem` throws it away.\n\nEditing templates is for SystemAdmin only. A TenantAdmin edits only the templates the app unlocks at the mount site, `createTemplateResolverFeature({ tenantEditable: [{ kind: \"mail\", slug: \"status-update\", access: { roles: [\"TenantAdmin\"] } }] })`, and every write handler enforces that on the server (override, draft, publish, archive, reset, copy-locale, import, resources, `set`). Each entry carries the `access` roles allowed to edit it, because a bundled feature cannot know the host's roles. The same list decides delivery: a tenant override is served (mail, PDF, layouts, text blocks) only while its template is listed in tenantEditable; otherwise the system version is served. A locked override stays stored, a SystemAdmin sees it in the overview marked as not delivered, and listing the template makes it effective again. Tenant rows of a collection mounted with `access` are always served. A collection mounted without `access` is SystemAdmin only.\n\nText an editor should be able to change belongs in a collection, declared at mount: `createTemplateResolverFeature({ collections: [{ id, kind, access: { roles }, nav }] })`. It appears in the navigation, and `access` is part of the mount because a bundled feature cannot know the host's roles. Each collection gets its own `<id>-list` / `<id>-item` / `<id>-set` handlers, so the dispatcher enforces the separation.\n\nHow a collection is edited follows from `contentFormat`: `plain` gives a text area that stores text, `document` a WYSIWYG document editor that stores sanitized HTML (bold, italic, headings, lists, links, variable chips). Both offer the collection's `variableSchema` as insertable chips and a preview rendered with sample data — an editor sees what `{{firstName}}` becomes without sending a mail. An app can register its own editor for a format; the last `clientFeature` that registers a format wins (a conflict logs a warning).\n\nA collection is tenant-wide by default. With `ownership: \"user\"` every user keeps their own entries — mail signatures being the obvious case. Those rows live in the separate `user-content-entry` entity and count as user data, so mounting one also requires the `template-resolver-user-data` feature and a migration on the app side.\n\n`validate` dry-runs the write pipeline for a draft (sanitizer, layout rules, placeholders) and reports what the template uses and misses. `export-bundle` / `import-bundle` (and `import-bundle-system`) move one template with all locales and resource files between tenants or environments; `copy-locale` starts a translation from an existing locale. Layouts are structured: a mail or PDF layout is `data-header` / `data-content` / `data-signature` / `data-footer` regions, and mjml layout source is system-only.\n\n`preview` renders a draft (or the stored template) with sample values taken from the `example` of each declared variable, through the same gates and the same mail renderer as a real send, and returns subject, html, `displayHtml` (the html with cid images as data URIs for an editor), text, attachments (inline images and files) and `checks` (images resolved, plain text present, size under 10 MiB, required placeholders used); nothing is saved or sent. `send-test` mails that rendering to the calling user's own address only, subject prefixed with `[TEST]`, at most 10 per user and hour; it needs `delivery`, `channel-email` and `renderer-mail-html` to be mounted. `send-test-status` tells an editor beforehand whether that send can work for the caller (`canSend`, else `reason` `no_channel` or `no_address`), never returning the address.\n\nImages used by a template (`<img data-resource=\"logo\">`) are uploaded with `resourceUpload`, which re-encodes them, stores a file and links it under the key; `resourceRemove` unlinks it. `linkedResources` is written only through these two handlers. With `purpose: \"attachment\"` and a `fileName`, `resourceUpload` stores a PDF, PNG or JPEG as a file attachment of a mail template (original bytes, at most 10) that the mail renderer attaches after the inline images. `resourceLinkPdf` instead links a `document-pdf` template under a key: every mail sent from the template then carries that PDF, rendered at send time with the mail's own variables and locale, under a file name pattern such as `invoice-{{number}}.pdf`; files and linked PDFs share the limit of 10.\n\nReplaces the former `text-content` feature; its blocks now live here as kind `text-block`.",
       "toggleableDefault": null,
       "requires": [],
       "optionalRequires": [],

package/samples/apps/use-all-bundled/kumiko/migrations/0056_inbound-mail-quarantine-retry.rebuild.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "tables": ["read_inbound_messages"]
+}