@cosmicdrift/kumiko-bundled-features 0.397.0 → 0.399.0

package/dist/billing-foundation/consumer-protection/consent-gate.d.ts

@@ -5,6 +5,7 @@ export type CheckoutMode = "subscription" | "payment";
 export declare const consentPayloadSchema: z.ZodObject<{
     earlyPerformanceRequested: z.ZodBoolean;
     withdrawalLossAcknowledged: z.ZodBoolean;
+    documentsAcknowledged: z.ZodOptional<z.ZodBoolean>;
     consentTextVersion: z.ZodString;
     locale: z.ZodString;
 }, z.core.$strict>;
@@ -15,6 +16,7 @@ export type PreparedConsent = {
     readonly locale: string;
     readonly submitMessage: string;
     readonly consentTextVersion: string;
+    readonly documentsAcknowledged: boolean;
     readonly termsHash: string;
     readonly termsTemplateVersion: number;
 };

package/dist/billing-foundation/consumer-protection/consent-gate.js

@@ -8,13 +8,14 @@ import * as z from "zod";
 import { requireTemplateResolver, TEXT_BLOCK_KIND, TemplateNotFoundError, } from "../../template-resolver/index.js";
 import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js";
 import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, checkoutConsentRecordedPayloadSchema, PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
-import { consentTextVersion, resolveConsentLocale, submitMessageFor } from "./consent-text.js";
+import { consentTextVersion, documentsAcknowledgementTextFor, resolveConsentLocale, submitMessageFor, } from "./consent-text.js";
 // Optional at the schema level so a missing/unchecked consent reaches
 // prepareConsent and fails as 422 consent_required, not as a zod 400.
 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),
 })
@@ -39,14 +40,18 @@ export function assertValidOrderItem(item, priceId) {
     }
 }
 export async function prepareConsent(ctx, options, consent, mode) {
-    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}"`,
@@ -78,6 +83,7 @@ export async function prepareConsent(ctx, options, consent, mode) {
         locale,
         submitMessage: submitMessageFor(locale, mode),
         consentTextVersion: consent.consentTextVersion,
+        documentsAcknowledged: documentsRequired,
         termsHash: createHash("sha256").update(terms.content).digest("hex"),
         termsTemplateVersion: terms.version,
     };
@@ -100,6 +106,7 @@ export async function recordConsent(ctx, prepared, details) {
         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/dist/billing-foundation/consumer-protection/consent-text.d.ts

@@ -1,3 +1,4 @@
+import { type ConsumerProtectionOptions, type LegalLinkSet } from "../types.ts";
 import type { ConsentLocale } from "../web/consumer-protection/consent-locale.ts";
 export { CONSENT_LOCALES, type ConsentLocale, FALLBACK_CONSENT_LOCALE, resolveConsentLocale, } from "../web/consumer-protection/consent-locale.ts";
 export type ConsentTexts = {
@@ -7,5 +8,9 @@ export type ConsentTexts = {
     readonly paymentSubmitMessage: string;
 };
 export declare const CONSENT_TEXTS: Readonly<Record<ConsentLocale, ConsentTexts>>;
-export declare function consentTextVersion(locale: ConsentLocale): string;
+export declare function legalLinksPerLocale(legalLinks: ConsumerProtectionOptions["legalLinks"]): Readonly<Record<ConsentLocale, LegalLinkSet>>;
+/** 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 declare function documentsAcknowledgementTextFor(options: ConsumerProtectionOptions, locale: ConsentLocale): string | undefined;
+export declare function consentTextVersion(locale: ConsentLocale, documentsAcknowledgementText?: string): string;
 export declare function submitMessageFor(locale: ConsentLocale, mode: "subscription" | "payment"): string;

package/dist/billing-foundation/consumer-protection/consent-text.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isLegalLinkSet } from "../types.js";
 export { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE, resolveConsentLocale, } from "../web/consumer-protection/consent-locale.js";
 export const CONSENT_TEXTS = {
     de: {
@@ -14,13 +15,37 @@ export const CONSENT_TEXTS = {
         paymentSubmitMessage: "Paid one-off payment: by clicking the button you commit to paying.",
     },
 };
+const DOCUMENTS_ACKNOWLEDGEMENT_TEXTS = {
+    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) {
+    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, locale) {
+    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) {
+// The documents text joins the hash only when shown, so apps without the opt-in keep their version.
+export function consentTextVersion(locale, documentsAcknowledgementText) {
     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, mode) {
     const texts = CONSENT_TEXTS[locale];

package/dist/billing-foundation/events.d.ts

@@ -63,6 +63,7 @@ export declare const checkoutConsentRecordedPayloadSchema: z.ZodObject<{
     interval: z.ZodNullable<z.ZodString>;
     intervalCount: z.ZodNullable<z.ZodNumber>;
     consentTextVersion: z.ZodString;
+    documentsAcknowledged: z.ZodOptional<z.ZodBoolean>;
     termsHash: z.ZodString;
     termsTemplateVersion: z.ZodNumber;
     locale: z.ZodString;

package/dist/billing-foundation/events.js

@@ -102,6 +102,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/dist/billing-foundation/handlers/billing-plans.query.d.ts

@@ -1,3 +1,3 @@
 import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
-import { type BillingPlanCatalog, type ResolvedBillingFoundationOptions } from "../types.ts";
+import type { BillingPlanCatalog, ResolvedBillingFoundationOptions } from "../types.ts";
 export declare function createBillingPlansQuery(options: ResolvedBillingFoundationOptions, catalog: BillingPlanCatalog): QueryHandlerDef;

package/dist/billing-foundation/handlers/billing-plans.query.js

@@ -3,9 +3,8 @@
 // when `createBillingFoundationFeature` gets a `catalog`.
 import * as z from "zod";
 import { filterOfferedProviders, listCatalogProviders, } from "../checkout-core.js";
-import { CONSENT_TEXTS, consentTextVersion, } from "../consumer-protection/consent-text.js";
+import { CONSENT_TEXTS, consentTextVersion, documentsAcknowledgementTextFor, legalLinksPerLocale, } from "../consumer-protection/consent-text.js";
 import { buildProviderPlanViews, loadBillingPlansBase, toBillingPlansResult, } from "../plan-catalog.js";
-import { isLegalLinkSet, } from "../types.js";
 const billingPlansSchema = z.object({}).strict();
 export function createBillingPlansQuery(options, catalog) {
     return {
@@ -23,8 +22,8 @@ export function createBillingPlansQuery(options, catalog) {
                 ...result,
                 consumerProtection: {
                     consentTexts: {
-                        de: consentTextView("de"),
-                        en: consentTextView("en"),
+                        de: consentTextView(consumerProtection, "de"),
+                        en: consentTextView(consumerProtection, "en"),
                     },
                     legalLinks: legalLinksPerLocale(consumerProtection.legalLinks),
                 },
@@ -62,10 +61,13 @@ async function providerView(ctx, catalog, base, provider, providerTexts, known)
         plans: views.plans,
     };
 }
-function legalLinksPerLocale(legalLinks) {
-    return isLegalLinkSet(legalLinks) ? { de: legalLinks, en: legalLinks } : legalLinks;
-}
-function consentTextView(locale) {
+function consentTextView(consumerProtection, locale) {
     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/dist/billing-foundation/i18n.js

@@ -78,6 +78,7 @@ export const BILLING_FOUNDATION_I18N = {
     "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/dist/billing-foundation/types.d.ts

@@ -345,6 +345,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 declare function isLegalLinkSet(links: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>): links is LegalLinkSet;
 /** Consumer-protection consent gate (§ 312j / § 356 BGB style). When set,
@@ -382,6 +384,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 = {
     readonly tenantId: TenantId;
@@ -476,6 +481,8 @@ export type BillingPlansResult = {
         readonly consentTexts: Readonly<Record<"de" | "en", {
             readonly earlyPerformance: string;
             readonly withdrawalLoss: string;
+            /** Present only when `documentsAcknowledgement` is on. */
+            readonly documentsAcknowledgement?: string;
             readonly consentTextVersion: string;
         }>>;
         readonly legalLinks: Readonly<Record<ConsentLocale, LegalLinkSet>>;

package/dist/billing-foundation/validate-options.js

@@ -73,7 +73,10 @@ function validatePerLocaleLegalLinks(legalLinks) {
 }
 function validateLegalLinkSet(set, path) {
     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/dist/billing-foundation/web/checkout-consent-dialog.d.ts

@@ -6,6 +6,7 @@ type ConsumerProtectionView = NonNullable<BillingPlansResult["consumerProtection
 export type CheckoutConsentPayload = {
     readonly earlyPerformanceRequested: true;
     readonly withdrawalLossAcknowledged: true;
+    readonly documentsAcknowledged?: true;
     readonly consentTextVersion: string;
     readonly locale: string;
 };

package/dist/billing-foundation/web/checkout-consent-dialog.js

@@ -2,41 +2,33 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useLocale, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { ChoiceCards } from "@cosmicdrift/kumiko-renderer/web";
 import { useState } from "react";
+import { ConsentCheckboxes, ConsentLinks, useConsentFieldState } from "./consent-fields.js";
 import { resolveConsentLocale } from "./consumer-protection/consent-locale.js";
 export const CONSENT_TEXT_OUTDATED_CODE = "consent_text_outdated";
 // kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Modal internally, name is a billing domain action, not a primitive reimplementation
 export function CheckoutConsentDialog({ open, onOpenChange, planName, price, consumerProtection, providerChoice, note, onOrder, onConsentTextOutdated, }) {
     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(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() {
         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();
         }
     }
-    return (_jsx(Modal, { open: open, onOpenChange: onOpenChange, title: t("billing-foundation.consent.title"), testId: "checkout-consent-dialog", children: _jsxs("div", { className: "flex flex-col gap-4", children: [providerChoice !== undefined && (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Text, { variant: "muted", children: t("billing-foundation.consent.chooseProvider") }), _jsx(ChoiceCards, { value: providerChoice.value, options: providerChoice.options, onChange: providerChoice.onChange, ariaLabel: t("billing-foundation.consent.chooseProvider"), testId: "checkout-provider-choice" })] })), _jsxs("div", { className: "flex flex-col gap-1", "data-testid": "checkout-consent-summary", children: [_jsxs(Text, { children: [planName, " \u2014 ", price.amount] }), price.renewalKey !== undefined && (_jsxs(_Fragment, { children: [_jsx(Text, { variant: "muted", children: t(price.renewalKey, price.count !== undefined ? { count: price.count } : undefined) }), _jsx(Text, { variant: "muted", children: t("billing-foundation.consent.cancelAnytime") })] })), note !== undefined && (_jsx(Text, { variant: "muted", testId: "checkout-consent-note", children: note }))] }), legalLinks !== undefined && (_jsxs("div", { className: "flex flex-wrap gap-4", children: [_jsx(Link, { href: legalLinks.terms, target: "_blank", children: t("billing-foundation.consent.link.terms") }), _jsx(Link, { href: legalLinks.withdrawal, target: "_blank", children: t("billing-foundation.consent.link.withdrawal") }), _jsx(Link, { href: legalLinks.privacy, target: "_blank", children: t("billing-foundation.consent.link.privacy") })] })), texts !== undefined && (_jsxs(_Fragment, { children: [_jsx(Field, { id: "consent-early-performance", label: texts.earlyPerformance, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "consent-early-performance", name: "consent-early-performance", value: earlyPerformance, onChange: setEarlyPerformance, disabled: submitting }) }), _jsx(Field, { id: "consent-withdrawal-loss", label: texts.withdrawalLoss, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "consent-withdrawal-loss", name: "consent-withdrawal-loss", value: withdrawalLoss, onChange: setWithdrawalLoss, disabled: submitting }) })] })), errorText !== null && (_jsx(Banner, { variant: "error", testId: "checkout-consent-error", children: errorText })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", disabled: submitting, onClick: () => onOpenChange(false), testId: "checkout-consent-cancel", children: t("billing-foundation.consent.back") }), _jsx(Button, { disabled: !consentGiven || submitting, loading: submitting, onClick: order, testId: "checkout-consent-order", children: t("billing-foundation.consent.order") })] })] }) }));
+    return (_jsx(Modal, { open: open, onOpenChange: onOpenChange, title: t("billing-foundation.consent.title"), testId: "checkout-consent-dialog", children: _jsxs("div", { className: "flex flex-col gap-4", children: [providerChoice !== undefined && (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx(Text, { variant: "muted", children: t("billing-foundation.consent.chooseProvider") }), _jsx(ChoiceCards, { value: providerChoice.value, options: providerChoice.options, onChange: providerChoice.onChange, ariaLabel: t("billing-foundation.consent.chooseProvider"), testId: "checkout-provider-choice" })] })), _jsxs("div", { className: "flex flex-col gap-1", "data-testid": "checkout-consent-summary", children: [_jsxs(Text, { children: [planName, " \u2014 ", price.amount] }), price.renewalKey !== undefined && (_jsxs(_Fragment, { children: [_jsx(Text, { variant: "muted", children: t(price.renewalKey, price.count !== undefined ? { count: price.count } : undefined) }), _jsx(Text, { variant: "muted", children: t("billing-foundation.consent.cancelAnytime") })] })), note !== undefined && (_jsx(Text, { variant: "muted", testId: "checkout-consent-note", children: note }))] }), legalLinks !== undefined && _jsx(ConsentLinks, { legalLinks: legalLinks }), texts !== undefined && (_jsx(ConsentCheckboxes, { idPrefix: "consent", texts: texts, state: consentFields, disabled: submitting })), errorText !== null && (_jsx(Banner, { variant: "error", testId: "checkout-consent-error", children: errorText })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", disabled: submitting, onClick: () => onOpenChange(false), testId: "checkout-consent-cancel", children: t("billing-foundation.consent.back") }), _jsx(Button, { disabled: !consentGiven || submitting, loading: submitting, onClick: order, testId: "checkout-consent-order", children: t("billing-foundation.consent.order") })] })] }) }));
 }

package/dist/billing-foundation/web/consent-fields.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } 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;
+};
+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 declare function useConsentFieldState(texts: ConsentTextView | undefined): ConsentFieldState;
+export declare function ConsentLinks({ legalLinks }: {
+    readonly legalLinks: LegalLinkSet;
+}): ReactNode;
+export declare function ConsentCheckboxes({ idPrefix, texts, state, disabled, }: {
+    readonly idPrefix: string;
+    readonly texts: ConsentTextView;
+    readonly state: ConsentFieldState;
+    readonly disabled: boolean;
+}): ReactNode;
+export {};

package/dist/billing-foundation/web/consent-fields.js

@@ -0,0 +1,43 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import { useState } from "react";
+const NOTHING_CHECKED = {
+    documentsAcknowledged: false,
+    earlyPerformance: false,
+    withdrawalLoss: false,
+};
+export function useConsentFieldState(texts) {
+    const [checks, setChecks] = useState(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 }) {
+    const t = useTranslation();
+    const { Link } = usePrimitives();
+    return (_jsxs("div", { className: "flex flex-wrap gap-4", children: [_jsx(Link, { href: legalLinks.terms, target: "_blank", children: t("billing-foundation.consent.link.terms") }), _jsx(Link, { href: legalLinks.withdrawal, target: "_blank", children: t("billing-foundation.consent.link.withdrawal") }), _jsx(Link, { href: legalLinks.privacy, target: "_blank", children: t("billing-foundation.consent.link.privacy") }), legalLinks.refund !== undefined && (_jsx(Link, { href: legalLinks.refund, target: "_blank", children: t("billing-foundation.consent.link.refund") }))] }));
+}
+export function ConsentCheckboxes({ idPrefix, texts, state, disabled, }) {
+    const { Field, Input } = usePrimitives();
+    const boxes = [
+        { key: "documentsAcknowledged", slug: "documents", label: texts.documentsAcknowledgement },
+        { key: "earlyPerformance", slug: "early-performance", label: texts.earlyPerformance },
+        { key: "withdrawalLoss", slug: "withdrawal-loss", label: texts.withdrawalLoss },
+    ];
+    return (_jsx(_Fragment, { children: boxes.map(({ key, slug, label }) => label === undefined ? null : (_jsx(Field, { id: `${idPrefix}-${slug}`, label: label, layout: "inline", children: _jsx(Input, { kind: "boolean", id: `${idPrefix}-${slug}`, name: `${idPrefix}-${slug}`, value: state.checks[key], onChange: (value) => state.setCheck(key, value), disabled: disabled }) }, key))) }));
+}

package/dist/billing-foundation/web/plan-switch-confirm-dialog.js

@@ -1,8 +1,9 @@
-import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useLocale, useMutation, usePrimitives, useQuery, useTranslation, } from "@cosmicdrift/kumiko-renderer";
 import { formatMoney } from "@cosmicdrift/kumiko-renderer/web";
 import { useState } from "react";
-import { CONSENT_TEXT_OUTDATED_CODE, } from "./checkout-consent-dialog.js";
+import { CONSENT_TEXT_OUTDATED_CODE } from "./checkout-consent-dialog.js";
+import { ConsentCheckboxes, ConsentLinks, useConsentFieldState } from "./consent-fields.js";
 import { SubscriptionFoundationHandlers, SubscriptionFoundationQueries } from "./constants.js";
 import { resolveConsentLocale } from "./consumer-protection/consent-locale.js";
 import { intervalKey } from "./plan-price.js";
@@ -11,28 +12,20 @@ import { recurringAmountsOf } from "./plan-switch-recurring.js";
 export function PlanSwitchConfirmDialog({ open, onOpenChange, tier, fromPlanName, toPlanName, consumerProtection, onApplied, onConsentTextOutdated, }) {
     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(SubscriptionFoundationQueries.planSwitchPreview, { tier });
     const switchMutation = useMutation(SubscriptionFoundationHandlers.switchPlan);
-    const [earlyPerformance, setEarlyPerformance] = useState(false);
-    const [withdrawalLoss, setWithdrawalLoss] = useState(false);
     const [submitting, setSubmitting] = useState(false);
     const [errorText, setErrorText] = useState(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() {
         setSubmitting(true);
         setErrorText(null);
-        const consent = 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();
@@ -41,8 +34,7 @@ export function PlanSwitchConfirmDialog({ open, onOpenChange, tier, fromPlanName
         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();
         }
     }
@@ -66,5 +58,5 @@ export function PlanSwitchConfirmDialog({ open, onOpenChange, tier, fromPlanName
                                 amount: money(reply.preview.credit, reply.preview.currency),
                             }) }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.recurring", {
                                 amount: recurringPrice,
-                            }) }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.effective") }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.pendingNote") })] })), legalLinks !== undefined && (_jsxs("div", { className: "flex flex-wrap gap-4", children: [_jsx(Link, { href: legalLinks.terms, target: "_blank", children: t("billing-foundation.consent.link.terms") }), _jsx(Link, { href: legalLinks.withdrawal, target: "_blank", children: t("billing-foundation.consent.link.withdrawal") }), _jsx(Link, { href: legalLinks.privacy, target: "_blank", children: t("billing-foundation.consent.link.privacy") })] })), texts !== undefined && (_jsxs(_Fragment, { children: [_jsx(Field, { id: "plan-switch-early-performance", label: texts.earlyPerformance, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "plan-switch-early-performance", name: "plan-switch-early-performance", value: earlyPerformance, onChange: setEarlyPerformance, disabled: submitting }) }), _jsx(Field, { id: "plan-switch-withdrawal-loss", label: texts.withdrawalLoss, layout: "inline", children: _jsx(Input, { kind: "boolean", id: "plan-switch-withdrawal-loss", name: "plan-switch-withdrawal-loss", value: withdrawalLoss, onChange: setWithdrawalLoss, disabled: submitting }) })] })), errorText !== null && (_jsx(Banner, { variant: "error", testId: "plan-switch-confirm-error", children: errorText })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", disabled: submitting, onClick: () => onOpenChange(false), testId: "plan-switch-confirm-cancel", children: t("billing-foundation.consent.back") }), _jsx(Button, { disabled: !consentGiven || reply === null || submitting, loading: submitting, onClick: confirm, testId: "plan-switch-confirm-order", children: t("billing-foundation.planSwitch.order") })] })] }) }));
+                            }) }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.effective") }), _jsx(Text, { variant: "muted", children: t("billing-foundation.planSwitch.pendingNote") })] })), legalLinks !== undefined && _jsx(ConsentLinks, { legalLinks: legalLinks }), texts !== undefined && (_jsx(ConsentCheckboxes, { idPrefix: "plan-switch", texts: texts, state: consentFields, disabled: submitting })), errorText !== null && (_jsx(Banner, { variant: "error", testId: "plan-switch-confirm-error", children: errorText })), _jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { variant: "secondary", disabled: submitting, onClick: () => onOpenChange(false), testId: "plan-switch-confirm-cancel", children: t("billing-foundation.consent.back") }), _jsx(Button, { disabled: !consentGiven || reply === null || submitting, loading: submitting, onClick: confirm, testId: "plan-switch-confirm-order", children: t("billing-foundation.planSwitch.order") })] })] }) }));
 }

package/dist/channel-in-app/constants.js

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

package/dist/channel-in-app/feature.js

@@ -8,7 +8,7 @@ import { inAppChannel } from "./in-app-channel.js";
 import { inAppMessagesTableMeta } from "./tables.js";
 export function createChannelInAppFeature() {
     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.");
+        r.describe("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",
             category: "notifications",

package/dist/channel-in-app/handlers/inbox.query.d.ts

@@ -2,6 +2,9 @@ import * as z from "zod";
 export declare const inboxQuery: import("@cosmicdrift/kumiko-types/define-handler").QueryHandlerDefinition<"inbox", z.ZodObject<{
     limit: z.ZodDefault<z.ZodNumber>;
     unreadOnly: z.ZodDefault<z.ZodBoolean>;
+    cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, {
-    rows: readonly any[];
+    rows: any[];
+    nextCursor: string | null;
+    total: number;
 }, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;

package/dist/channel-in-app/handlers/inbox.query.js

@@ -1,12 +1,15 @@
 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.js";
 import { inAppMessagesTable } from "../tables.js";
+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: {
@@ -14,15 +17,27 @@ export const inboxQuery = defineQueryHandler({
                 "inAppMessagesTable by the caller's own id",
         },
     },
-    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.",
+    description: "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 = { 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 = { 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" },
         });
-        return { rows };
+        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, nextCursor, total: totalRow?.value ?? 0 };
     },
 });

package/dist/channel-in-app/handlers/unread-count.query.js

@@ -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.js";
@@ -13,13 +12,7 @@ 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/dist/channel-in-app/in-app-channel.js

@@ -1,5 +1,9 @@
 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 { targetOfNotificationData } from "./in-app-target.js";
 import { inAppMessagesTable } from "./tables.js";
+const log = createFallbackLogger("channel-in-app");
 export const inAppChannel = {
     name: "inApp",
     mode: "inline",
@@ -10,24 +14,32 @@ export const inAppChannel = {
     async send(address, message, ctx) {
         // 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(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/dist/channel-in-app/in-app-target.d.ts

@@ -0,0 +1,5 @@
+import type { InAppNotificationTarget } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+export declare function inAppTarget(screenId: string, entityId?: string): InAppNotificationTarget;
+export declare function parseInAppTarget(value: unknown): InAppNotificationTarget | null;
+export declare function targetOfNotificationData(data: unknown): InAppNotificationTarget | null;
+export declare function parseStoredNotificationData(stored: string | null): unknown;

package/dist/channel-in-app/in-app-target.js

@@ -0,0 +1,34 @@
+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, entityId) {
+    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) {
+    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) {
+    if (typeof data !== "object" || data === null || !("target" in data))
+        return null;
+    return parseInAppTarget(data.target);
+}
+export function parseStoredNotificationData(stored) {
+    if (stored === null)
+        return null;
+    try {
+        return JSON.parse(stored);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/channel-in-app/index.d.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/dist/channel-in-app/index.js

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

package/dist/metrics/compute.d.ts

@@ -1,4 +1,5 @@
 import type { WhereObject } from "@cosmicdrift/kumiko-framework/db";
+import type { AggregateKey } from "@cosmicdrift/kumiko-types/aggregate-types";
 import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import type { MetricDefinition, MetricResult } from "./types.ts";
@@ -11,5 +12,7 @@ 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>>;
 };
 export declare function runMetric(db: TenantDb, metric: MetricDefinition, params: MetricRunParams): Promise<MetricResult>;

package/dist/metrics/compute.js

@@ -75,7 +75,7 @@ function groupSegments(stackRows, labelOf) {
     }
     return segmentsByGroup;
 }
-function buildRows(metric, aggregates, total, labelOf) {
+function buildRows(metric, aggregates, total, labelOf, groupLabelOf) {
     const segmentsByGroup = groupSegments(aggregates.stacks, labelOf);
     return aggregates.groups.map((row) => {
         const key = keyText(row.keys[0]);
@@ -83,7 +83,7 @@ function buildRows(metric, aggregates, total, labelOf) {
         return {
             id: key,
             key,
-            label: labelOf(key),
+            label: groupLabelOf(key),
             value: rowValue,
             fraction: fractionOf(rowValue, total),
             ...(metric.stackBy !== undefined && { segments: segmentsByGroup.get(key) ?? [] }),
@@ -104,6 +104,11 @@ function buildSeries(rows, seriesRows, fillBuckets) {
         points: fillBuckets(bucketsByGroup.get(row.key) ?? new Map()),
     }));
 }
+async function resolveReferencedGroupLabels(metric, params, groups) {
+    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, metric, params) {
     const range = metric.window ?? params.range;
     const bucket = resolveBucket(metric, range);
@@ -129,7 +134,9 @@ export async function runMetric(db, metric, params) {
             row.value,
         ])))
         : [];
-    const rows = buildRows(metric, aggregates, value, labelOf);
+    const referencedLabels = await resolveReferencedGroupLabels(metric, params, aggregates.groups);
+    const groupLabelOf = (key) => metric.groupLabels?.[key] ?? referencedLabels.get(key) ?? key;
+    const rows = buildRows(metric, aggregates, value, labelOf, groupLabelOf);
     return {
         value,
         previousValue,

package/dist/metrics/feature.js

@@ -1,4 +1,5 @@
-import { access, defineFeature, defineQueryHandler, } from "@cosmicdrift/kumiko-framework/engine";
+import { extractTableInfo } from "@cosmicdrift/kumiko-framework/db";
+import { access, defineFeature, defineQueryHandler, referenceGroupLabels, } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError, ValidationError } from "@cosmicdrift/kumiko-framework/errors";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
@@ -45,7 +46,7 @@ function createTenantMetricQuery(metric, now) {
         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,
             timeZone: query.payload.timeZone,
@@ -53,6 +54,9 @@ function createTenantMetricQuery(metric, now) {
             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/dist/metrics/types.d.ts

@@ -33,8 +33,12 @@ 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[];
 };
 export declare function defineMetric(definition: MetricDefinition): MetricDefinition;

package/dist/metrics/validate.js

@@ -25,6 +25,9 @@ function validateMetric(metric) {
         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);
     validateFilters(metric, info, fail);

package/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>",
@@ -566,9 +566,9 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.397.0",
-    "@cosmicdrift/kumiko-renderer": "0.397.0",
-    "@cosmicdrift/kumiko-types": "0.397.0",
+    "@cosmicdrift/kumiko-framework": "0.399.0",
+    "@cosmicdrift/kumiko-renderer": "0.399.0",
+    "@cosmicdrift/kumiko-types": "0.399.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@tiptap/core": "^3.31.3",
@@ -584,10 +584,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",
@@ -1157,18 +1157,18 @@
     "LICENSE"
   ],
   "devDependencies": {
-    "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.397.0",
-    "@cosmicdrift/kumiko-locale-es": "0.397.0",
-    "@cosmicdrift/kumiko-locale-fr": "0.397.0",
-    "@cosmicdrift/kumiko-locale-it": "0.397.0",
-    "@cosmicdrift/kumiko-renderer-mail-html": "0.397.0",
+    "@testing-library/user-event": "^14.6.8",
+    "@cosmicdrift/kumiko-locale-de": "0.399.0",
+    "@cosmicdrift/kumiko-locale-es": "0.399.0",
+    "@cosmicdrift/kumiko-locale-fr": "0.399.0",
+    "@cosmicdrift/kumiko-locale-it": "0.399.0",
+    "@cosmicdrift/kumiko-renderer-mail-html": "0.399.0",
     "jsqr": "^1.4.0",
     "unpdf": "^1.8.1",
-    "@cosmicdrift/kumiko-testing": "0.397.0"
+    "@cosmicdrift/kumiko-testing": "0.399.0"
   },
   "peerDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.397.0"
+    "@cosmicdrift/kumiko-testing": "0.399.0"
   },
   "peerDependenciesMeta": {
     "@cosmicdrift/kumiko-testing": {

package/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/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/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",