@cosmicdrift/kumiko-samples 0.343.0 → 0.345.0

package/packages/bundled-features/src/billing-foundation/web/index.ts

@@ -13,11 +13,23 @@ export {
   type SubscriptionStatus,
   SubscriptionStatuses,
 } from "../constants.js";
+export {
+  CONSENT_LOCALES,
+  type ConsentLocale,
+  resolveConsentLocale,
+} from "../consumer-protection/consent-locale.js";
 export type {
   BillingPlanBenefit,
   BillingPlanCatalog,
   BillingPlansResult,
   BillingPlanView,
+  LegalLinkSet,
 } from "../types.js";
 export { BillingPlansPanel } from "./billing-plans-panel.js";
+export {
+  CheckoutConsentDialog,
+  type CheckoutConsentDialogProps,
+  type CheckoutConsentPayload,
+  CONSENT_TEXT_OUTDATED_CODE,
+} from "./checkout-consent-dialog.js";
 export { type BillingFoundationClientOptions, billingFoundationClient } from "./client-plugin.js";

package/packages/bundled-features/src/legal-pages/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.344.0",
+    "type": "improvement",
+    "title": "Optional title heading on legal pages",
+    "detail": "`LegalPageRoute` has an optional `titleHeading` flag. When `true`, the page body starts with an `<h1>` holding the escaped page title. The default (`false`) leaves the body unchanged."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/legal-pages/constants.ts

@@ -10,6 +10,8 @@ export type LegalPageRoute = {
   readonly slug: string;
   readonly lang: string;
   readonly titleFallback: string;
+  /** Prepend the page title as `<h1>` to the rendered body. Default false. */
+  readonly titleHeading?: boolean;
 };
 
 // Shape of one boot-check-required block — the type behind

package/packages/bundled-features/src/legal-pages/feature.ts

@@ -4,6 +4,7 @@ import {
   type FeatureDefinition,
   SYSTEM_TENANT_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { escapeHtml } from "@cosmicdrift/kumiko-headless";
 import {
   cachedSecurePageResponse,
   type PublicPageWrapLayout,
@@ -87,7 +88,7 @@ export type LegalPagesOptions = {
 
 export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDefinition {
   const wrapLayout = opts.wrapLayout ?? wrapInLayout;
-  const routes = opts.routes ?? LEGAL_ROUTES;
+  const routes: readonly LegalPageRoute[] = opts.routes ?? LEGAL_ROUTES;
   const requiredBlocks = opts.requiredBlocks ?? LEGAL_REQUIRED_BLOCKS;
   validateRoutes(routes);
   if (opts.routes !== undefined && opts.routes.length > 0 && opts.requiredBlocks === undefined) {
@@ -172,9 +173,13 @@ export function createLegalPagesFeature(opts: LegalPagesOptions = {}): FeatureDe
             });
           }
 
+          const title = data.title || route.titleFallback;
+          const renderedBody = renderMarkdownToHtml(data.content);
           const html = wrapLayout({
-            title: data.title || route.titleFallback,
-            bodyHtml: renderMarkdownToHtml(data.content),
+            title,
+            bodyHtml: route.titleHeading
+              ? `<h1>${escapeHtml(title)}</h1>${renderedBody}`
+              : renderedBody,
             lang: route.lang,
             slug: route.slug,
           });

package/packages/bundled-features/src/renderer-simple/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.344.0",
+    "type": "improvement",
+    "title": "Heading and Markdown sections in the simple mail renderer",
+    "detail": "`createSimpleRenderer` accepts two more section kinds: `{ heading: string }` (rendered as an escaped `<h2>`) and `{ markdown: string }` (rendered with the hardened Markdown renderer; raw HTML is escaped and unsafe link targets are replaced by `#`). Existing section kinds render as before."
+  },
   {
     "version": "0.341.0",
     "type": "improvement",

package/packages/bundled-features/src/renderer-simple/simple-renderer.ts

@@ -1,5 +1,6 @@
 import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
 import type { NotificationRenderer } from "../delivery/index.js";
+import { renderSafeMarkdown } from "../page-render/index.js";
 
 export type MailBranding = {
   /** Shown as text when there is no logo, and as the logo alt text. */
@@ -141,6 +142,8 @@ function renderBrandingFooter(
 
 type Section =
   | { readonly text: string }
+  | { readonly heading: string }
+  | { readonly markdown: string }
   | { readonly button: { readonly label: string; readonly url: string } };
 
 type EmailTemplateData = {
@@ -157,6 +160,13 @@ function renderSection(section: Section, primaryColor: string): string {
   if ("text" in section) {
     return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
   }
+  if ("heading" in section) {
+    return `<h2 style="margin:24px 0 12px;color:#111;font-size:16px;font-weight:600">${escapeHtml(section.heading)}</h2>`;
+  }
+  if ("markdown" in section) {
+    const markdownHtml = renderSafeMarkdown(section.markdown);
+    return `<div style="color:#333;font-size:14px;line-height:1.5">${markdownHtml}</div>`;
+  }
   if ("button" in section) {
     return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:${escapeHtmlAttr(primaryColor)};color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
   }

package/packages/bundled-features/src/step-dispatcher/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.345.0",
+    "type": "improvement",
+    "title": "Webhook sends carry an Idempotency-Key header that is stable across redeliveries",
+    "detail": "Webhook sends carry an Idempotency-Key header\nEvery `r.step.webhook.send` request now has `Idempotency-Key: <dispatch stream id>`. The value stays the same when the same dispatch request is delivered again, so receivers can deduplicate. An explicit `Idempotency-Key` in `headers` (any casing) takes precedence."
+  },
   {
     "version": "0.335.0",
     "type": "fix",

package/packages/bundled-features/src/step-dispatcher/feature.ts

@@ -193,7 +193,7 @@ function buildDispatchSpec(
 export function createStepDispatcherFeature(): FeatureDefinition {
   return defineFeature("step-dispatcher", (r) => {
     r.describe(
-      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.",
+      "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.",
     );
     r.secretNamespace("webhook-auth", WEBHOOK_AUTH_SECRET_NAMESPACE_OPTIONS);
     r.uiHints({
@@ -270,6 +270,7 @@ export function createStepDispatcherFeature(): FeatureDefinition {
                   tenantId: event.tenantId,
                   userId: event.metadata.userId || SYSTEM_USER_ID,
                   secrets: ctx.secrets,
+                  idempotencyKey: event.aggregateId,
                 })
               : await performMailDispatch(dispatchSpec.spec);
           if (result.ok) {

package/packages/bundled-features/src/step-dispatcher/webhook-runner.ts

@@ -114,6 +114,7 @@ export type WebhookDispatchDeps = {
   readonly tenantId: TenantId;
   readonly userId: string;
   readonly secrets: SecretsContext | undefined;
+  readonly idempotencyKey: string;
 };
 
 // Never includes the secret name or value — spec.auth.secret is a
@@ -121,11 +122,20 @@ export type WebhookDispatchDeps = {
 // dispatch-failed event, so it stays generic.
 const WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR = "webhook auth secret is not available";
 
+export const WEBHOOK_IDEMPOTENCY_KEY_HEADER = "idempotency-key";
+
+function hasIdempotencyKeyHeader(headers: Readonly<Record<string, string>>): boolean {
+  return Object.keys(headers).some((name) => name.toLowerCase() === WEBHOOK_IDEMPOTENCY_KEY_HEADER);
+}
+
 async function buildWebhookHeaders(
   spec: WebhookSpec,
   deps: WebhookDispatchDeps,
 ): Promise<{ ok: true; headers: Record<string, string> } | { ok: false; error: string }> {
   const headers: Record<string, string> = { "content-type": "application/json", ...spec.headers };
+  if (!hasIdempotencyKeyHeader(headers)) {
+    headers[WEBHOOK_IDEMPOTENCY_KEY_HEADER] = deps.idempotencyKey;
+  }
   if (!spec.auth) return { ok: true, headers };
   if (!deps.secrets) return { ok: false, error: WEBHOOK_AUTH_SECRET_UNAVAILABLE_ERROR };
   // A throwing get (corrupt envelope, rotated key, KMS error) must become a

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

@@ -69,8 +69,8 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
     baseUrl,
     catalog: {
       plans: ["starter", "pro"],
-      tierLabelKey: (tier) => `gallery.plan.${tier}.label`,
-      benefits: (tier) => [{ labelKey: `gallery.plan.${tier}.benefit` }],
+      tierLabelKey: (tier) => `gallery-screens:plan.${tier}.label`,
+      benefits: (tier) => [{ labelKey: `gallery-screens:plan.${tier}.benefit` }],
       resolveCurrentTier,
       viewRoles: ["TenantAdmin", "SystemAdmin"],
       successPath: GALLERY_PLAN_PATH,
@@ -83,9 +83,8 @@ export function createGalleryBillingFeature(baseUrl: string): FeatureDefinition
       operatorEmail: GALLERY_OPERATOR_EMAIL,
       terminationScope: "platform",
       legalLinks: {
-        terms: "/legal/terms",
-        withdrawal: "/legal/withdrawal",
-        privacy: "/legal/privacy",
+        de: { terms: "/legal/terms", withdrawal: "/legal/withdrawal", privacy: "/legal/privacy" },
+        en: { terms: "/legal/terms", withdrawal: "/legal/withdrawal", privacy: "/legal/privacy" },
       },
     },
   });
@@ -140,12 +139,12 @@ export const galleryScreensFeature: FeatureDefinition = defineFeature("gallery-s
   r.translations({
     keys: {
       "gallery:nav.billing": { de: "Abrechnung", en: "Billing" },
-      "gallery.plan.free.label": { de: "Free", en: "Free" },
-      "gallery.plan.starter.label": { de: "Starter", en: "Starter" },
-      "gallery.plan.pro.label": { de: "Pro", en: "Pro" },
-      "gallery.plan.starter.benefit": { de: "Für kleine Teams", en: "For small teams" },
-      "gallery.plan.pro.benefit": { de: "Für wachsende Teams", en: "For growing teams" },
-      "gallery.plan.free.benefit": { de: "Zum Ausprobieren", en: "To try things out" },
+      "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" },
+      "gallery-screens:plan.starter.benefit": { de: "Für kleine Teams", en: "For small teams" },
+      "gallery-screens:plan.pro.benefit": { de: "Für wachsende Teams", en: "For growing teams" },
+      "gallery-screens:plan.free.benefit": { de: "Zum Ausprobieren", en: "To try things out" },
     },
   });
   return {};

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

@@ -42,8 +42,8 @@ const features = [
 ];
 
 const TERMS_TEXT: Readonly<Record<string, string>> = {
-  de: "## Allgemeine Geschäftsbedingungen\n\nDiese Bedingungen gelten für alle Verträge über die Plattform.",
-  en: "## Terms and conditions\n\nThese terms apply to every contract concluded through the platform.",
+  de: "Diese Bedingungen gelten für alle Verträge über die Plattform.",
+  en: "These terms apply to every contract concluded through the platform.",
 };
 
 const seedTerms: SeedFn = async (stack) => {

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

@@ -127,6 +127,7 @@
         "auth-email-password:write:reset-password",
         "auth-email-password:write:signup-confirm",
         "auth-email-password:write:signup-request",
+        "auth-email-password:write:switch-tenant-mfa-gate",
         "auth-email-password:write:system-invite-create",
         "auth-email-password:write:verify-email"
       ],
@@ -2301,7 +2302,7 @@
     },
     {
       "name": "step-dispatcher",
-      "description": "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`.",
+      "description": "Internal system feature that drains deferred Tier-2 side-effects (currently `webhook.send` and `mail.send`) after their originating transaction commits. Listens via `r.multiStreamProjection` on the `kumiko:system:step.dispatch-requested` system event, performs the actual HTTP or mail delivery, then appends `kumiko:system:step.dispatched` or `kumiko:system:step.dispatch-failed` back onto the same stream so the outcome is recorded in the event log without a separate status table. Mount this feature explicitly via `createStepDispatcherFeature()` in your app's feature list alongside any features that use `r.step.webhook.send` or `r.step.mail.send`. Requires the `secrets` feature (`createSecretsFeature()`) to be mounted — `webhook.send` auth resolves per-tenant through it, under `step-dispatcher:webhook-auth.<name>`. Every `webhook.send` request carries `Idempotency-Key: <dispatch stream id>`, stable across redeliveries of the same dispatch request; an explicit `Idempotency-Key` in `headers` takes precedence.",
       "toggleableDefault": null,
       "requires": [
         "secrets"

package/samples/recipes/i18n/README.md

@@ -13,7 +13,7 @@ A translation value can be a CLDR plural-forms object instead of a plain
 string. `other` is required; the rest (`zero`/`one`/`two`/`few`/`many`) only
 exist where the locale's grammar needs them:
 
-```ts
+```ts illustration
 "greeting.unread_count": {
   de: { one: "{count} ungelesene Nachricht", other: "{count} ungelesene Nachrichten" },
   en: { one: "{count} unread message", other: "{count} unread messages" },

package/samples/recipes/rate-limiting/README.md

@@ -12,7 +12,7 @@ End-to-end rate limiting: L1 global-IP + L2 auth + L3 handler opt-in.
 A public write handler that mails an address typed by the caller is also limited per
 address, so rotating IPs does not help against mail flooding. Declare it next to `rateLimit`:
 
-```ts
+```ts illustration
 r.writeHandler({
   // ...
   access: { roles: ["anonymous"] },

package/samples/recipes/webhook-step/README.md

@@ -16,7 +16,7 @@ never a process-wide env var. The `secrets` feature must be mounted
 (`createSecretsFeature()` + a `MasterKeyProvider`) alongside
 `step-dispatcher`. Set the secret per tenant before dispatching:
 
-```ts
+```ts illustration
 await stack.http.writeOk(
   "secrets:write:set",
   { key: "step-dispatcher:webhook-auth.incident-hook", value: "<token>" },
@@ -33,6 +33,13 @@ Never combine `auth.secret` with a caller-controlled `url`: the caller would
 receive the secret as the `Authorization` header. `incident:open-authenticated`
 therefore posts to a fixed URL.
 
+## Idempotency-Key
+
+Every webhook request carries `Idempotency-Key: <dispatch stream id>`. The
+value is the same when the same dispatch request is delivered again, so a
+receiver can deduplicate redelivered calls. An `Idempotency-Key` set explicitly in
+`headers` (any casing) wins.
+
 ## Source
 
 Feature entry point: `src/feature.ts`.