@cosmicdrift/kumiko-samples 0.397.0 → 0.399.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.397.0",
+  "version": "0.399.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.397.0",
+  "version": "0.399.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>",
@@ -179,10 +179,10 @@
     "@types/qrcode": "^1.5.5",
     "clsx": "^2.1.1",
     "happy-dom": "^21.0.4",
-    "hono": "^4.13.1",
+    "hono": "^4.13.14",
     "imapflow": "^1.7.8",
     "ioredis": "^5.10.1",
-    "jose": "^6.2.3",
+    "jose": "^6.2.13",
     "lucide-react": "^1.14.0",
     "mailparser": "^3.12.4",
     "marked": "^18.0.3",
@@ -752,7 +752,7 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@testing-library/user-event": "^14.6.1",
+    "@testing-library/user-event": "^14.6.8",
     "@cosmicdrift/kumiko-locale-de": "workspace:*",
     "@cosmicdrift/kumiko-locale-es": "workspace:*",
     "@cosmicdrift/kumiko-locale-fr": "workspace:*",

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

@@ -1,4 +1,16 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Shorter documents checkbox text in the consent box",
+    "detail": "With `consumerProtection.documentsAcknowledgement: true` the checkbox now reads \"I have read and agree to the Terms and the Refund Policy.\" (de: \"Ich habe die AGB und die Erstattungsrichtlinie gelesen und bin mit ihnen einverstanden.\"), or without a refund link only the terms. The privacy policy stays a link. The text is part of `consentTextVersion`, so apps with the option on get a new version hash; consents recorded earlier keep their stored version."
+  },
+  {
+    "version": "0.398.0",
+    "type": "improvement",
+    "title": "Consent box takes a refund policy link and an optional documents checkbox",
+    "detail": "`legalLinks.refund` is rendered next to the other links in the checkout and plan-switch dialogs. `consumerProtection.documentsAcknowledgement: true` adds a required first checkbox whose text depends on whether a refund link is set for the locale. The text joins `consentTextVersion` only when the option is on, `start-plan-checkout`, `create-checkout-session` and `switch-plan` then reject a consent without `documentsAcknowledged: true` with 422 `consent_required`, and the recorded consent stores the flag. Without the option nothing changes, including the version. New i18n key `billing-foundation.consent.link.refund`."
+  },
   {
     "version": "0.394.0",
     "type": "improvement",

package/packages/bundled-features/src/billing-foundation/consumer-protection/consent-gate.ts

@@ -20,7 +20,12 @@ import {
   SUBSCRIPTION_AGGREGATE_TYPE,
 } from "../events.ts";
 import type { ConsumerProtectionOptions, ProviderPrice } from "../types.ts";
-import { consentTextVersion, resolveConsentLocale, submitMessageFor } from "./consent-text.ts";
+import {
+  consentTextVersion,
+  documentsAcknowledgementTextFor,
+  resolveConsentLocale,
+  submitMessageFor,
+} from "./consent-text.ts";
 
 export type CheckoutMode = "subscription" | "payment";
 
@@ -30,6 +35,7 @@ export const consentPayloadSchema = z
   .object({
     earlyPerformanceRequested: z.boolean(),
     withdrawalLossAcknowledged: z.boolean(),
+    documentsAcknowledged: z.boolean().optional(),
     consentTextVersion: z.string().min(1).max(64),
     locale: z.string().min(2).max(35),
   })
@@ -42,6 +48,7 @@ export type PreparedConsent = {
   readonly locale: string;
   readonly submitMessage: string;
   readonly consentTextVersion: string;
+  readonly documentsAcknowledged: boolean;
   readonly termsHash: string;
   readonly termsTemplateVersion: number;
 };
@@ -88,14 +95,20 @@ export async function prepareConsent(
   consent: ConsentPayload | undefined,
   mode: CheckoutMode,
 ): Promise<PreparedConsent> {
-  if (!consent?.earlyPerformanceRequested || !consent.withdrawalLossAcknowledged) {
+  const documentsRequired = options.documentsAcknowledgement === true;
+  if (
+    !consent?.earlyPerformanceRequested ||
+    !consent.withdrawalLossAcknowledged ||
+    (documentsRequired && consent.documentsAcknowledged !== true)
+  ) {
     throw new UnprocessableError("consent_required", {
       i18nKey: "billing-foundation.errors.consentRequired",
-      message: "billing-foundation: both consent flags must be true to start a checkout",
+      message: "billing-foundation: all consent flags must be true to start a checkout",
     });
   }
   const locale = resolveConsentLocale(consent.locale);
-  if (consent.consentTextVersion !== consentTextVersion(locale)) {
+  const documentsText = documentsAcknowledgementTextFor(options, locale);
+  if (consent.consentTextVersion !== consentTextVersion(locale, documentsText)) {
     throw new UnprocessableError("consent_text_outdated", {
       i18nKey: "billing-foundation.errors.consentTextOutdated",
       message: `billing-foundation: consent text version "${consent.consentTextVersion}" is not current for locale "${locale}"`,
@@ -128,6 +141,7 @@ export async function prepareConsent(
     locale,
     submitMessage: submitMessageFor(locale, mode),
     consentTextVersion: consent.consentTextVersion,
+    documentsAcknowledged: documentsRequired,
     termsHash: createHash("sha256").update(terms.content).digest("hex"),
     termsTemplateVersion: terms.version,
   };
@@ -160,6 +174,7 @@ export async function recordConsent(
     interval: details.price?.interval ?? null,
     intervalCount: details.price?.intervalCount ?? null,
     consentTextVersion: prepared.consentTextVersion,
+    ...(prepared.documentsAcknowledged && { documentsAcknowledged: true }),
     termsHash: prepared.termsHash,
     termsTemplateVersion: prepared.termsTemplateVersion,
     locale: prepared.locale,

package/packages/bundled-features/src/billing-foundation/consumer-protection/consent-text.ts

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { type ConsumerProtectionOptions, isLegalLinkSet, type LegalLinkSet } from "../types.ts";
 import type { ConsentLocale } from "../web/consumer-protection/consent-locale.ts";
 
 export {
@@ -39,14 +40,50 @@ export const CONSENT_TEXTS: Readonly<Record<ConsentLocale, ConsentTexts>> = {
   },
 };
 
+const DOCUMENTS_ACKNOWLEDGEMENT_TEXTS: Readonly<
+  Record<ConsentLocale, { readonly withRefund: string; readonly withoutRefund: string }>
+> = {
+  de: {
+    withRefund:
+      "Ich habe die AGB und die Erstattungsrichtlinie gelesen und bin mit ihnen einverstanden.",
+    withoutRefund: "Ich habe die AGB gelesen und bin mit ihnen einverstanden.",
+  },
+  en: {
+    withRefund: "I have read and agree to the Terms and the Refund Policy.",
+    withoutRefund: "I have read and agree to the Terms.",
+  },
+};
+
+export function legalLinksPerLocale(
+  legalLinks: ConsumerProtectionOptions["legalLinks"],
+): Readonly<Record<ConsentLocale, LegalLinkSet>> {
+  return isLegalLinkSet(legalLinks) ? { de: legalLinks, en: legalLinks } : legalLinks;
+}
+
+/** The documents checkbox text for a locale, or undefined when the app did not
+ *  opt in. The variant follows whether that locale has a refund link. */
+export function documentsAcknowledgementTextFor(
+  options: ConsumerProtectionOptions,
+  locale: ConsentLocale,
+): string | undefined {
+  if (!options.documentsAcknowledgement) return undefined;
+  const texts = DOCUMENTS_ACKNOWLEDGEMENT_TEXTS[locale];
+  return legalLinksPerLocale(options.legalLinks)[locale].refund !== undefined
+    ? texts.withRefund
+    : texts.withoutRefund;
+}
+
 const CONSENT_TEXT_VERSION_LENGTH = 16;
 
-export function consentTextVersion(locale: ConsentLocale): string {
+// The documents text joins the hash only when shown, so apps without the opt-in keep their version.
+export function consentTextVersion(
+  locale: ConsentLocale,
+  documentsAcknowledgementText?: string,
+): string {
   const { earlyPerformance, withdrawalLoss } = CONSENT_TEXTS[locale];
-  return createHash("sha256")
-    .update(`${earlyPerformance}\n${withdrawalLoss}`)
-    .digest("hex")
-    .slice(0, CONSENT_TEXT_VERSION_LENGTH);
+  const hash = createHash("sha256").update(`${earlyPerformance}\n${withdrawalLoss}`);
+  if (documentsAcknowledgementText !== undefined) hash.update(`\n${documentsAcknowledgementText}`);
+  return hash.digest("hex").slice(0, CONSENT_TEXT_VERSION_LENGTH);
 }
 
 export function submitMessageFor(locale: ConsentLocale, mode: "subscription" | "payment"): string {

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -139,6 +139,7 @@ export const checkoutConsentRecordedPayloadSchema = z.object({
   interval: z.string().nullable(),
   intervalCount: z.number().nullable(),
   consentTextVersion: z.string().min(1).max(64),
+  documentsAcknowledged: z.boolean().optional(),
   termsHash: z.string().length(64),
   termsTemplateVersion: z.number(),
   locale: z.string().min(2).max(35),

package/packages/bundled-features/src/billing-foundation/handlers/billing-plans.query.ts

@@ -13,6 +13,8 @@ import {
   type CONSENT_LOCALES,
   CONSENT_TEXTS,
   consentTextVersion,
+  documentsAcknowledgementTextFor,
+  legalLinksPerLocale,
 } from "../consumer-protection/consent-text.ts";
 import {
   type BillingPlansBase,
@@ -21,14 +23,12 @@ import {
   type ProviderPlanViews,
   toBillingPlansResult,
 } from "../plan-catalog.ts";
-import {
-  type BillingPlanCatalog,
-  type BillingPlansResult,
-  type BillingProviderView,
-  type ConsumerProtectionOptions,
-  isLegalLinkSet,
-  type LegalLinkSet,
-  type ResolvedBillingFoundationOptions,
+import type {
+  BillingPlanCatalog,
+  BillingPlansResult,
+  BillingProviderView,
+  ConsumerProtectionOptions,
+  ResolvedBillingFoundationOptions,
 } from "../types.ts";
 
 const billingPlansSchema = z.object({}).strict();
@@ -52,8 +52,8 @@ export function createBillingPlansQuery(
         ...result,
         consumerProtection: {
           consentTexts: {
-            de: consentTextView("de"),
-            en: consentTextView("en"),
+            de: consentTextView(consumerProtection, "de"),
+            en: consentTextView(consumerProtection, "en"),
           },
           legalLinks: legalLinksPerLocale(consumerProtection.legalLinks),
         },
@@ -116,13 +116,16 @@ async function providerView(
   };
 }
 
-function legalLinksPerLocale(
-  legalLinks: ConsumerProtectionOptions["legalLinks"],
-): Readonly<Record<(typeof CONSENT_LOCALES)[number], LegalLinkSet>> {
-  return isLegalLinkSet(legalLinks) ? { de: legalLinks, en: legalLinks } : legalLinks;
-}
-
-function consentTextView(locale: (typeof CONSENT_LOCALES)[number]) {
+function consentTextView(
+  consumerProtection: ConsumerProtectionOptions,
+  locale: (typeof CONSENT_LOCALES)[number],
+) {
   const { earlyPerformance, withdrawalLoss } = CONSENT_TEXTS[locale];
-  return { earlyPerformance, withdrawalLoss, consentTextVersion: consentTextVersion(locale) };
+  const documentsAcknowledgement = documentsAcknowledgementTextFor(consumerProtection, locale);
+  return {
+    earlyPerformance,
+    withdrawalLoss,
+    ...(documentsAcknowledgement !== undefined && { documentsAcknowledgement }),
+    consentTextVersion: consentTextVersion(locale, documentsAcknowledgement),
+  };
 }

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

@@ -83,6 +83,7 @@ export const BILLING_FOUNDATION_I18N: Readonly<Record<string, LocalizedString>>
   "billing-foundation.consent.link.terms": { en: "Terms" },
   "billing-foundation.consent.link.withdrawal": { en: "Withdrawal policy" },
   "billing-foundation.consent.link.privacy": { en: "Privacy policy" },
+  "billing-foundation.consent.link.refund": { en: "Refund policy" },
   "billing-foundation.consent.order": { en: "Order with obligation to pay" },
   "billing-foundation.plans.priceFrom": { en: "from" },
   "billing-foundation.consent.chooseProvider": { en: "Payment provider" },

package/packages/bundled-features/src/billing-foundation/types.ts

@@ -459,6 +459,8 @@ export type LegalLinkSet = {
   readonly terms: string;
   readonly withdrawal: string;
   readonly privacy: string;
+  /** Link to the refund policy; shown next to the other links when set. */
+  readonly refund?: string;
 };
 
 export function isLegalLinkSet(
@@ -510,6 +512,9 @@ export type ConsumerProtectionOptions = {
   /** Root-relative paths or absolute https URLs. One set for every locale, or
    *  one set per consent locale (`de` and `en` required). */
   readonly legalLinks: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>;
+  /** Adds a required first checkbox "documents read and accepted" (terms, privacy,
+   *  and the refund policy when `legalLinks.refund` is set). Off by default. */
+  readonly documentsAcknowledgement?: boolean;
 };
 
 export type OneOffCheckoutRequest = {
@@ -621,6 +626,8 @@ export type BillingPlansResult = {
         {
           readonly earlyPerformance: string;
           readonly withdrawalLoss: string;
+          /** Present only when `documentsAcknowledgement` is on. */
+          readonly documentsAcknowledgement?: string;
           readonly consentTextVersion: string;
         }
       >

package/packages/bundled-features/src/billing-foundation/validate-options.ts

@@ -96,7 +96,9 @@ function validatePerLocaleLegalLinks(
 
 function validateLegalLinkSet(set: LegalLinkSet, path: string): void {
   for (const [key, link] of Object.entries(set)) {
-    if (!isRootRelativeOrHttpsUrl(link)) {
+    // skip: refund is optional
+    if (key === "refund" && link === undefined) continue;
+    if (typeof link !== "string" || !isRootRelativeOrHttpsUrl(link)) {
       throw new Error(
         `createBillingFoundationFeature: consumerProtection.${path}.${key} "${link}" must be a root-relative path ("/..." not "//") or an absolute https URL.`,
       );

package/packages/bundled-features/src/billing-foundation/web/checkout-consent-dialog.tsx

@@ -3,6 +3,7 @@ import type { WriteResult } from "@cosmicdrift/kumiko-renderer/headless";
 import { ChoiceCards } from "@cosmicdrift/kumiko-renderer/web";
 import { type ReactNode, useState } from "react";
 import type { BillingPlansResult } from "../types.ts";
+import { ConsentCheckboxes, ConsentLinks, useConsentFieldState } from "./consent-fields.tsx";
 import { resolveConsentLocale } from "./consumer-protection/consent-locale.ts";
 
 export const CONSENT_TEXT_OUTDATED_CODE = "consent_text_outdated";
@@ -12,6 +13,7 @@ type ConsumerProtectionView = NonNullable<BillingPlansResult["consumerProtection
 export type CheckoutConsentPayload = {
   readonly earlyPerformanceRequested: true;
   readonly withdrawalLossAcknowledged: true;
+  readonly documentsAcknowledged?: true;
   readonly consentTextVersion: string;
   readonly locale: string;
 };
@@ -60,36 +62,25 @@ export function CheckoutConsentDialog({
 }: CheckoutConsentDialogProps): ReactNode {
   const t = useTranslation();
   const uiLocale = useLocale().locale();
-  const { Modal, Text, Field, Input, Button, Link, Banner } = usePrimitives();
-  const [earlyPerformance, setEarlyPerformance] = useState(false);
-  const [withdrawalLoss, setWithdrawalLoss] = useState(false);
+  const { Modal, Text, Button, Banner } = usePrimitives();
   const [submitting, setSubmitting] = useState(false);
   const [errorText, setErrorText] = useState<string | null>(null);
 
   const consentLocale = resolveConsentLocale(uiLocale);
   const texts = consumerProtection?.consentTexts[consentLocale];
   const legalLinks = consumerProtection?.legalLinks[consentLocale];
-  const consentGiven = consumerProtection === undefined || (earlyPerformance && withdrawalLoss);
+  const consentFields = useConsentFieldState(texts);
+  const consentGiven = consumerProtection === undefined || consentFields.allGiven;
 
   async function order(): Promise<void> {
     setSubmitting(true);
     setErrorText(null);
-    const result = await onOrder(
-      texts === undefined
-        ? undefined
-        : {
-            earlyPerformanceRequested: true,
-            withdrawalLossAcknowledged: true,
-            consentTextVersion: texts.consentTextVersion,
-            locale: consentLocale,
-          },
-    );
+    const result = await onOrder(consentFields.buildPayload(consentLocale));
     if (result.isSuccess) return;
     setSubmitting(false);
     setErrorText(t(result.error.i18nKey, result.error.i18nParams));
     if (result.error.code === CONSENT_TEXT_OUTDATED_CODE) {
-      setEarlyPerformance(false);
-      setWithdrawalLoss(false);
+      consentFields.reset();
       onConsentTextOutdated();
     }
   }
@@ -135,42 +126,14 @@ export function CheckoutConsentDialog({
             </Text>
           )}
         </div>
-        {legalLinks !== undefined && (
-          <div className="flex flex-wrap gap-4">
-            <Link href={legalLinks.terms} target="_blank">
-              {t("billing-foundation.consent.link.terms")}
-            </Link>
-            <Link href={legalLinks.withdrawal} target="_blank">
-              {t("billing-foundation.consent.link.withdrawal")}
-            </Link>
-            <Link href={legalLinks.privacy} target="_blank">
-              {t("billing-foundation.consent.link.privacy")}
-            </Link>
-          </div>
-        )}
+        {legalLinks !== undefined && <ConsentLinks legalLinks={legalLinks} />}
         {texts !== undefined && (
-          <>
-            <Field id="consent-early-performance" label={texts.earlyPerformance} layout="inline">
-              <Input
-                kind="boolean"
-                id="consent-early-performance"
-                name="consent-early-performance"
-                value={earlyPerformance}
-                onChange={setEarlyPerformance}
-                disabled={submitting}
-              />
-            </Field>
-            <Field id="consent-withdrawal-loss" label={texts.withdrawalLoss} layout="inline">
-              <Input
-                kind="boolean"
-                id="consent-withdrawal-loss"
-                name="consent-withdrawal-loss"
-                value={withdrawalLoss}
-                onChange={setWithdrawalLoss}
-                disabled={submitting}
-              />
-            </Field>
-          </>
+          <ConsentCheckboxes
+            idPrefix="consent"
+            texts={texts}
+            state={consentFields}
+            disabled={submitting}
+          />
         )}
         {errorText !== null && (
           <Banner variant="error" testId="checkout-consent-error">

package/packages/bundled-features/src/billing-foundation/web/consent-fields.tsx

@@ -0,0 +1,111 @@
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { type ReactNode, useState } from "react";
+import type { BillingPlansResult, LegalLinkSet } from "../types.ts";
+import type { CheckoutConsentPayload } from "./checkout-consent-dialog.tsx";
+
+type ConsumerProtectionView = NonNullable<BillingPlansResult["consumerProtection"]>;
+export type ConsentTextView = ConsumerProtectionView["consentTexts"]["de"];
+
+export type ConsentChecks = {
+  readonly documentsAcknowledged: boolean;
+  readonly earlyPerformance: boolean;
+  readonly withdrawalLoss: boolean;
+};
+
+const NOTHING_CHECKED: ConsentChecks = {
+  documentsAcknowledged: false,
+  earlyPerformance: false,
+  withdrawalLoss: false,
+};
+
+export type ConsentFieldState = {
+  readonly checks: ConsentChecks;
+  readonly setCheck: (key: keyof ConsentChecks, value: boolean) => void;
+  readonly reset: () => void;
+  readonly allGiven: boolean;
+  readonly buildPayload: (locale: string) => CheckoutConsentPayload | undefined;
+};
+
+export function useConsentFieldState(texts: ConsentTextView | undefined): ConsentFieldState {
+  const [checks, setChecks] = useState<ConsentChecks>(NOTHING_CHECKED);
+  const documentsRequired = texts?.documentsAcknowledgement !== undefined;
+  return {
+    checks,
+    setCheck: (key, value) => setChecks((current) => ({ ...current, [key]: value })),
+    reset: () => setChecks(NOTHING_CHECKED),
+    allGiven:
+      checks.earlyPerformance &&
+      checks.withdrawalLoss &&
+      (!documentsRequired || checks.documentsAcknowledged),
+    buildPayload: (locale) =>
+      texts === undefined
+        ? undefined
+        : {
+            earlyPerformanceRequested: true,
+            withdrawalLossAcknowledged: true,
+            ...(documentsRequired && { documentsAcknowledged: true }),
+            consentTextVersion: texts.consentTextVersion,
+            locale,
+          },
+  };
+}
+
+export function ConsentLinks({ legalLinks }: { readonly legalLinks: LegalLinkSet }): ReactNode {
+  const t = useTranslation();
+  const { Link } = usePrimitives();
+  return (
+    <div className="flex flex-wrap gap-4">
+      <Link href={legalLinks.terms} target="_blank">
+        {t("billing-foundation.consent.link.terms")}
+      </Link>
+      <Link href={legalLinks.withdrawal} target="_blank">
+        {t("billing-foundation.consent.link.withdrawal")}
+      </Link>
+      <Link href={legalLinks.privacy} target="_blank">
+        {t("billing-foundation.consent.link.privacy")}
+      </Link>
+      {legalLinks.refund !== undefined && (
+        <Link href={legalLinks.refund} target="_blank">
+          {t("billing-foundation.consent.link.refund")}
+        </Link>
+      )}
+    </div>
+  );
+}
+
+export function ConsentCheckboxes({
+  idPrefix,
+  texts,
+  state,
+  disabled,
+}: {
+  readonly idPrefix: string;
+  readonly texts: ConsentTextView;
+  readonly state: ConsentFieldState;
+  readonly disabled: boolean;
+}): ReactNode {
+  const { Field, Input } = usePrimitives();
+  const boxes: readonly { key: keyof ConsentChecks; slug: string; label: string | undefined }[] = [
+    { key: "documentsAcknowledged", slug: "documents", label: texts.documentsAcknowledgement },
+    { key: "earlyPerformance", slug: "early-performance", label: texts.earlyPerformance },
+    { key: "withdrawalLoss", slug: "withdrawal-loss", label: texts.withdrawalLoss },
+  ];
+  return (
+    <>
+      {boxes.map(({ key, slug, label }) =>
+        label === undefined ? null : (
+          <Field key={key} id={`${idPrefix}-${slug}`} label={label} layout="inline">
+            <Input
+              kind="boolean"
+              id={`${idPrefix}-${slug}`}
+              name={`${idPrefix}-${slug}`}
+              value={state.checks[key]}
+              onChange={(value) => state.setCheck(key, value)}
+              disabled={disabled}
+            />
+          </Field>
+        ),
+      )}
+    </>
+  );
+}

package/packages/bundled-features/src/billing-foundation/web/plan-switch-confirm-dialog.tsx

@@ -8,10 +8,8 @@ import {
 import { formatMoney } from "@cosmicdrift/kumiko-renderer/web";
 import { type ReactNode, useState } from "react";
 import type { BillingPlansResult, PlanSwitchPreview } from "../types.ts";
-import {
-  type CheckoutConsentPayload,
-  CONSENT_TEXT_OUTDATED_CODE,
-} from "./checkout-consent-dialog.tsx";
+import { CONSENT_TEXT_OUTDATED_CODE } from "./checkout-consent-dialog.tsx";
+import { ConsentCheckboxes, ConsentLinks, useConsentFieldState } from "./consent-fields.tsx";
 import { SubscriptionFoundationHandlers, SubscriptionFoundationQueries } from "./constants.ts";
 import { resolveConsentLocale } from "./consumer-protection/consent-locale.ts";
 import { intervalKey } from "./plan-price.ts";
@@ -53,7 +51,7 @@ export function PlanSwitchConfirmDialog({
 }: PlanSwitchConfirmDialogProps): ReactNode {
   const t = useTranslation();
   const locale = useLocale().locale();
-  const { Modal, Text, Field, Input, Button, Link, Banner } = usePrimitives();
+  const { Modal, Text, Button, Banner } = usePrimitives();
   const previewQuery = useQuery<PlanSwitchPreviewReply>(
     SubscriptionFoundationQueries.planSwitchPreview,
     { tier },
@@ -61,28 +59,19 @@ export function PlanSwitchConfirmDialog({
   const switchMutation = useMutation<{ readonly applied: true }>(
     SubscriptionFoundationHandlers.switchPlan,
   );
-  const [earlyPerformance, setEarlyPerformance] = useState(false);
-  const [withdrawalLoss, setWithdrawalLoss] = useState(false);
   const [submitting, setSubmitting] = useState(false);
   const [errorText, setErrorText] = useState<string | null>(null);
 
   const consentLocale = resolveConsentLocale(locale);
   const texts = consumerProtection?.consentTexts[consentLocale];
   const legalLinks = consumerProtection?.legalLinks[consentLocale];
-  const consentGiven = consumerProtection === undefined || (earlyPerformance && withdrawalLoss);
+  const consentFields = useConsentFieldState(texts);
+  const consentGiven = consumerProtection === undefined || consentFields.allGiven;
 
   async function confirm(): Promise<void> {
     setSubmitting(true);
     setErrorText(null);
-    const consent: CheckoutConsentPayload | undefined =
-      texts === undefined
-        ? undefined
-        : {
-            earlyPerformanceRequested: true,
-            withdrawalLossAcknowledged: true,
-            consentTextVersion: texts.consentTextVersion,
-            locale: consentLocale,
-          };
+    const consent = consentFields.buildPayload(consentLocale);
     const result = await switchMutation.mutate({ tier, ...(consent && { consent }) });
     if (result.isSuccess) {
       onApplied();
@@ -91,8 +80,7 @@ export function PlanSwitchConfirmDialog({
     setSubmitting(false);
     setErrorText(t(result.error.i18nKey, result.error.i18nParams));
     if (result.error.code === CONSENT_TEXT_OUTDATED_CODE) {
-      setEarlyPerformance(false);
-      setWithdrawalLoss(false);
+      consentFields.reset();
       onConsentTextOutdated();
     }
   }
@@ -160,46 +148,14 @@ export function PlanSwitchConfirmDialog({
             <Text variant="muted">{t("billing-foundation.planSwitch.pendingNote")}</Text>
           </div>
         )}
-        {legalLinks !== undefined && (
-          <div className="flex flex-wrap gap-4">
-            <Link href={legalLinks.terms} target="_blank">
-              {t("billing-foundation.consent.link.terms")}
-            </Link>
-            <Link href={legalLinks.withdrawal} target="_blank">
-              {t("billing-foundation.consent.link.withdrawal")}
-            </Link>
-            <Link href={legalLinks.privacy} target="_blank">
-              {t("billing-foundation.consent.link.privacy")}
-            </Link>
-          </div>
-        )}
+        {legalLinks !== undefined && <ConsentLinks legalLinks={legalLinks} />}
         {texts !== undefined && (
-          <>
-            <Field
-              id="plan-switch-early-performance"
-              label={texts.earlyPerformance}
-              layout="inline"
-            >
-              <Input
-                kind="boolean"
-                id="plan-switch-early-performance"
-                name="plan-switch-early-performance"
-                value={earlyPerformance}
-                onChange={setEarlyPerformance}
-                disabled={submitting}
-              />
-            </Field>
-            <Field id="plan-switch-withdrawal-loss" label={texts.withdrawalLoss} layout="inline">
-              <Input
-                kind="boolean"
-                id="plan-switch-withdrawal-loss"
-                name="plan-switch-withdrawal-loss"
-                value={withdrawalLoss}
-                onChange={setWithdrawalLoss}
-                disabled={submitting}
-              />
-            </Field>
-          </>
+          <ConsentCheckboxes
+            idPrefix="plan-switch"
+            texts={texts}
+            state={consentFields}
+            disabled={submitting}
+          />
         )}
         {errorText !== null && (
           <Banner variant="error" testId="plan-switch-confirm-error">

package/packages/bundled-features/src/channel-in-app/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Inbox cursor, total and navigation target for the shell bell",
+    "detail": "`channel-in-app:query:inbox` accepts a `cursor` and answers `{ rows, nextCursor, total }`; each row carries `target` (`{ screenId, entityId? }` or null) parsed from `data.target`. Build the target with `inAppTarget(screenId, entityId?)`; a malformed target is dropped and the notification is still delivered. The SSE frame `channel-in-app:event:delivered` now carries only `{ id, userId, notificationType }`, and a failing push no longer fails the delivery because the row is already stored. The shared contract lives in `@cosmicdrift/kumiko-types/in-app-notification-types`."
+  },
   {
     "version": "0.354.0",
     "type": "fix",

package/packages/bundled-features/src/channel-in-app/constants.ts

@@ -1,11 +1,11 @@
-export const CHANNEL_IN_APP_FEATURE = "channel-in-app" as const;
+import {
+  IN_APP_NOTIFICATION_FEATURE,
+  IN_APP_NOTIFICATION_QUERIES,
+  IN_APP_NOTIFICATION_WRITES,
+} from "@cosmicdrift/kumiko-types/in-app-notification-types";
 
-export const InAppHandlers = {
-  markRead: "channel-in-app:write:mark-read",
-  markAllRead: "channel-in-app:write:mark-all-read",
-} as const;
+export const CHANNEL_IN_APP_FEATURE = IN_APP_NOTIFICATION_FEATURE;
 
-export const InAppQueries = {
-  inbox: "channel-in-app:query:inbox",
-  unreadCount: "channel-in-app:query:unread-count",
-} as const;
+export const InAppHandlers = IN_APP_NOTIFICATION_WRITES;
+
+export const InAppQueries = IN_APP_NOTIFICATION_QUERIES;

package/packages/bundled-features/src/channel-in-app/feature.ts

@@ -10,7 +10,7 @@ import { inAppMessagesTableMeta } from "./tables.ts";
 export function createChannelInAppFeature(): FeatureDefinition {
   return defineFeature("channel-in-app", (r) => {
     r.describe(
-      "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
+      "Persists notifications to an in-app inbox table so users can page through them via `queries.inbox` (cursor, total, parsed `target`) and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. A notification links to a screen when `data.target` is set with `inAppTarget(screenId, entityId?)`. The renderer shell shows a bell with a live unread badge whenever this feature is mounted. Requires `delivery`; no external service needed \u2014 messages are stored in the app's own database.",
     );
     r.uiHints({
       displayLabel: "In-App Inbox",

package/packages/bundled-features/src/channel-in-app/handlers/inbox.query.ts

@@ -1,13 +1,17 @@
 import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
+import { parseStoredNotificationData, targetOfNotificationData } from "../in-app-target.ts";
 import { inAppMessagesTable } from "../tables.ts";
 
+const SERIAL_ID_PATTERN = /^\d{1,15}$/;
+
 export const inboxQuery = defineQueryHandler({
   name: "inbox",
   schema: z.object({
     limit: z.number().min(1).max(100).default(50),
     unreadOnly: z.boolean().default(false),
+    cursor: z.string().regex(SERIAL_ID_PATTERN).optional(),
   }),
   access: {
     openToAll: {
@@ -17,14 +21,34 @@ export const inboxQuery = defineQueryHandler({
     },
   },
   description:
-    "Lists the calling user's own in-app notification messages newest-first, optionally only the unread ones; use it to show or inspect a user's notification inbox.",
+    "Lists the calling user's own in-app notification messages newest-first with a parsed navigation target, optionally only the unread ones. Pass the returned nextCursor as cursor for the next page; total counts all matching messages, not just the page. Use it to show or inspect a user's notification inbox.",
   handler: async (query, ctx) => {
-    const where: Record<string, unknown> = { userId: query.user.id };
-    if (query.payload.unreadOnly) where["isRead"] = false;
-    const rows = await selectMany(ctx.db, inAppMessagesTable, where, {
-      limit: query.payload.limit,
-      orderBy: { col: "createdAt", direction: "desc" },
+    const { limit, unreadOnly, cursor } = query.payload;
+    const ownMessages: Record<string, unknown> = { userId: query.user.id };
+    if (unreadOnly) ownMessages["isRead"] = false;
+
+    const pageWhere =
+      cursor === undefined ? ownMessages : { ...ownMessages, id: { lt: Number(cursor) } };
+    // One extra row tells whether another page exists without a second query.
+    const fetched = await selectMany(ctx.db, inAppMessagesTable, pageWhere, {
+      limit: limit + 1,
+      orderBy: { col: "id", direction: "desc" },
+    });
+    const page = fetched.slice(0, limit);
+    const lastRow = page[page.length - 1];
+    const nextCursor = fetched.length > limit && lastRow ? String(lastRow["id"]) : null;
+
+    const [totalRow] = await ctx.db.aggregate(
+      inAppMessagesTable,
+      { measure: { fn: "count" } },
+      ownMessages,
+    );
+
+    const rows = page.map((row) => {
+      const storedData = row["data"];
+      const data = parseStoredNotificationData(typeof storedData === "string" ? storedData : null);
+      return { ...row, target: targetOfNotificationData(data) };
     });
-    return { rows };
+    return { rows, nextCursor, total: totalRow?.value ?? 0 };
   },
 });

package/packages/bundled-features/src/channel-in-app/handlers/unread-count.query.ts

@@ -1,4 +1,3 @@
-import { selectMany } from "@cosmicdrift/kumiko-framework/db";
 import { defineQueryHandler } from "@cosmicdrift/kumiko-framework/engine";
 import * as z from "zod";
 import { inAppMessagesTable } from "../tables.ts";
@@ -16,13 +15,11 @@ export const unreadCountQuery = defineQueryHandler({
   description:
     "Counts the calling user's unread in-app notification messages; use it for an inbox badge or to check whether a user has pending notifications.",
   handler: async (query, ctx) => {
-    // The query helpers in db/query.ts have no aggregate helper, so selectMany returns all matching
-    // rows and count() runs in JS. This is acceptable because unread counts are low-cardinality and
-    // user-scoped, with at most a few hundred rows; use raw .unsafe() with COUNT(*) if that grows.
-    const rows = await selectMany(ctx.db, inAppMessagesTable, {
-      userId: query.user.id,
-      isRead: false,
-    });
-    return { count: rows.length };
+    const [countRow] = await ctx.db.aggregate(
+      inAppMessagesTable,
+      { measure: { fn: "count" } },
+      { userId: query.user.id, isRead: false },
+    );
+    return { count: countRow?.value ?? 0 };
   },
 });

package/packages/bundled-features/src/channel-in-app/in-app-channel.ts

@@ -1,7 +1,12 @@
 import { tenantChannel } from "@cosmicdrift/kumiko-framework/engine";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import { IN_APP_NOTIFICATION_DELIVERED_EVENT } from "@cosmicdrift/kumiko-types/in-app-notification-types";
 import type { DeliveryChannel } from "../delivery/index.ts";
+import { targetOfNotificationData } from "./in-app-target.ts";
 import { inAppMessagesTable } from "./tables.ts";
 
+const log = createFallbackLogger("channel-in-app");
+
 export const inAppChannel: DeliveryChannel = {
   name: "inApp",
   mode: "inline",
@@ -15,25 +20,34 @@ export const inAppChannel: DeliveryChannel = {
     // address is the user-id string after the ES migration — keep it as-is.
     const userId = address;
 
+    // A malformed target drops only the link, never the notification.
+    const target = targetOfNotificationData(message.data);
+    const storedData =
+      message.data === undefined
+        ? null
+        : JSON.stringify({ ...message.data, target: target ?? undefined });
+
     const row = await ctx.db.insertOne<{ id: string }>(inAppMessagesTable, {
       userId,
       notificationType: message.notificationType,
       title: message.title,
       body: message.body ?? null,
-      data: message.data ? JSON.stringify(message.data) : null,
+      data: storedData,
     });
 
     if (ctx.sseBroker) {
-      await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
-        type: "channel-in-app:event:delivered",
-        data: {
-          id: row?.id,
-          userId,
-          notificationType: message.notificationType,
-          title: message.title,
-          body: message.body,
-        },
-      });
+      // The row is stored, so a failing push (e.g. Redis down) must not turn the delivery into
+      // a failure that gets retried and stored twice. Clients fetch the inbox on reconnect.
+      try {
+        await ctx.sseBroker.pushToChannel(tenantChannel(ctx.tenantId), {
+          type: IN_APP_NOTIFICATION_DELIVERED_EVENT,
+          data: { id: row?.id, userId, notificationType: message.notificationType },
+        });
+      } catch (error) {
+        log.warn("in-app SSE push failed; the notification is stored", {
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
     }
 
     return { status: "sent", address };

package/packages/bundled-features/src/channel-in-app/in-app-target.ts

@@ -0,0 +1,37 @@
+import type { InAppNotificationTarget } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+import * as z from "zod";
+
+const SCREEN_ID_PATTERN = /^[^\s:]+:screen:[^\s:]+$/;
+
+const targetSchema = z.object({
+  screenId: z.string().regex(SCREEN_ID_PATTERN),
+  entityId: z.string().min(1).optional(),
+});
+
+export function inAppTarget(screenId: string, entityId?: string): InAppNotificationTarget {
+  return entityId === undefined ? { screenId } : { screenId, entityId };
+}
+
+// Returns null for anything that is not a well-formed target, so a malformed `data.target`
+// drops only the link and never the notification.
+export function parseInAppTarget(value: unknown): InAppNotificationTarget | null {
+  const parsed = targetSchema.safeParse(value);
+  if (!parsed.success) return null;
+  const { screenId, entityId } = parsed.data;
+  return inAppTarget(screenId, entityId);
+}
+
+// Reads `target` out of the stored notification data (a JSON string) or out of a raw data object.
+export function targetOfNotificationData(data: unknown): InAppNotificationTarget | null {
+  if (typeof data !== "object" || data === null || !("target" in data)) return null;
+  return parseInAppTarget(data.target);
+}
+
+export function parseStoredNotificationData(stored: string | null): unknown {
+  if (stored === null) return null;
+  try {
+    return JSON.parse(stored);
+  } catch {
+    return null;
+  }
+}

package/packages/bundled-features/src/channel-in-app/index.ts

@@ -1,4 +1,5 @@
 export { CHANNEL_IN_APP_FEATURE, InAppHandlers, InAppQueries } from "./constants.ts";
 export { createChannelInAppFeature } from "./feature.ts";
 export { inAppChannel } from "./in-app-channel.ts";
+export { inAppTarget } from "./in-app-target.ts";
 export { inAppMessagesTable } from "./tables.ts";

package/packages/bundled-features/src/metrics/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Metric access roles and group names from a source table",
+    "detail": "A metric declares `access: { roles }` to open its tenant query to roles other than the admin roles; an empty list fails boot validation and no `access` keeps the admin-only default. A `groupBy` metric on an entity-table source whose column is a single reference names the rows after the referenced row's label field; the lookup runs through the caller's read access on the target entity, so unreadable or foreign-tenant rows keep their key, and static `groupLabels` still win."
+  },
   {
     "version": "0.365.0",
     "type": "fix",

package/packages/bundled-features/src/metrics/compute.ts

@@ -26,6 +26,10 @@ export type MetricRunParams = {
   readonly filterWhere: WhereObject;
   /** Extra filter that narrows the source to the caller's scope. */
   readonly scopeWhere: WhereObject;
+  /** Names for referenced-row group keys; absent where the caller cannot resolve them (system scope). */
+  readonly referenceLabels?: (
+    keys: readonly AggregateKey[],
+  ) => Promise<ReadonlyMap<string, string>>;
 };
 
 const NULL_KEY_TEXT = "—";
@@ -153,6 +157,7 @@ function buildRows(
   aggregates: MetricAggregates,
   total: number | null,
   labelOf: (key: string) => string,
+  groupLabelOf: (key: string) => string,
 ): readonly MetricRow[] {
   const segmentsByGroup = groupSegments(aggregates.stacks, labelOf);
   return aggregates.groups.map((row) => {
@@ -161,7 +166,7 @@ function buildRows(
     return {
       id: key,
       key,
-      label: labelOf(key),
+      label: groupLabelOf(key),
       value: rowValue,
       fraction: fractionOf(rowValue, total),
       ...(metric.stackBy !== undefined && { segments: segmentsByGroup.get(key) ?? [] }),
@@ -188,6 +193,15 @@ function buildSeries(
   }));
 }
 
+async function resolveReferencedGroupLabels(
+  metric: MetricDefinition,
+  params: MetricRunParams,
+  groups: readonly AggregateRow[],
+): Promise<ReadonlyMap<string, string>> {
+  if (params.referenceLabels === undefined || metric.groupBy === undefined) return new Map();
+  return params.referenceLabels(groups.map((row) => row.keys[0] ?? null));
+}
+
 export async function runMetric(
   db: TenantDb,
   metric: MetricDefinition,
@@ -230,7 +244,10 @@ export async function runMetric(
           ),
         )
       : [];
-  const rows = buildRows(metric, aggregates, value, labelOf);
+  const referencedLabels = await resolveReferencedGroupLabels(metric, params, aggregates.groups);
+  const groupLabelOf = (key: string): string =>
+    metric.groupLabels?.[key] ?? referencedLabels.get(key) ?? key;
+  const rows = buildRows(metric, aggregates, value, labelOf, groupLabelOf);
 
   return {
     value,

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

@@ -1,9 +1,11 @@
+import { extractTableInfo } from "@cosmicdrift/kumiko-framework/db";
 import {
   access,
   defineFeature,
   defineQueryHandler,
   type FeatureDefinition,
   type QueryHandlerDefinition,
+  referenceGroupLabels,
 } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
@@ -78,7 +80,7 @@ function createTenantMetricQuery(
     name: metric.id,
     description: metric.description,
     schema: tenantPayloadSchema(metric),
-    access: { roles: access.admin },
+    access: { roles: metric.access?.roles ?? access.admin },
     handler: async (query, ctx) =>
       runMetric(ctx.db, metric, {
         range: query.payload.range,
@@ -87,6 +89,17 @@ function createTenantMetricQuery(
         filterWhere: await resolveMetricFilterWhere(metric, query.payload, ctx),
         // ctx.db already reads own-tenant + SYSTEM reference rows; this narrows to own-tenant only.
         scopeWhere: { tenantId: query.user.tenantId },
+        referenceLabels: (keys) =>
+          metric.groupBy === undefined
+            ? Promise.resolve(new Map())
+            : referenceGroupLabels(
+                ctx,
+                query.user,
+                extractTableInfo(metric.source).name,
+                metric.groupBy,
+                keys,
+                ctx.db,
+              ),
       }),
   });
 }

package/packages/bundled-features/src/metrics/types.ts

@@ -41,8 +41,10 @@ export type MetricDefinition = {
   readonly groupBy?: string;
   /** Second dimension, becomes `rows[].segments`; only without bucket. */
   readonly stackBy?: string;
-  /** Key value → i18n key, applied to groupBy and stackBy keys. */
+  /** Key value → i18n key, applied to groupBy and stackBy keys. Without an entry, a groupBy that is a single reference of an entity-table source is named after the referenced row (tenant scope, through the caller's read access); otherwise the key stays. */
   readonly groupLabels?: Readonly<Record<string, string>>;
+  /** Roles that may read the tenant query; default is the admin roles. Ignored for scope "system", which stays SystemAdmin only. */
+  readonly access?: { readonly roles: readonly string[] };
   readonly scopes: readonly MetricScope[];
 };
 

package/packages/bundled-features/src/metrics/validate.ts

@@ -31,6 +31,9 @@ function validateMetric(metric: MetricDefinition): void {
   };
   if (!KEBAB_ID.test(metric.id)) fail("has an id that is not kebab-case");
   if (metric.scopes.length === 0) fail("declares no scopes");
+  if (metric.access !== undefined && metric.access.roles.length === 0) {
+    fail("declares access with an empty roles list");
+  }
 
   const info = extractTableInfo(metric.source);
   validateColumns(metric, info, fail);

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

@@ -472,7 +472,7 @@
     },
     {
       "name": "channel-in-app",
-      "description": "Persists notifications to an in-app inbox table so users can retrieve them via `handlers.inbox` and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. Requires `delivery`; no external service needed — messages are stored in the app's own database.",
+      "description": "Persists notifications to an in-app inbox table so users can page through them via `queries.inbox` (cursor, total, parsed `target`) and track unread state with `handlers.markRead` / `handlers.markAllRead` and `queries.unreadCount`. A notification links to a screen when `data.target` is set with `inAppTarget(screenId, entityId?)`. The renderer shell shows a bell with a live unread badge whenever this feature is mounted. Requires `delivery`; no external service needed — messages are stored in the app's own database.",
       "toggleableDefault": null,
       "requires": [
         "delivery"