@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.339.0

package/dist/notes-history/handlers/add-note.write.js

@@ -1,5 +1,7 @@
 import { fetchOne, runInSavepointIfSupported } from "@cosmicdrift/kumiko-framework/bun-db";
+import { ValidationError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
 import { decryptStoredPii, denyUnlessJoinRowParentVisible } from "../../shared/index.js";
+import { tenantMembershipsTable } from "../../tenant/index.js";
 import { userTable } from "../../user/index.js";
 import { DEFAULT_NOTES_HISTORY_ACCESS } from "../constants.js";
 import { noteEntryExecutor, noteMentionExecutor } from "../executor.js";
@@ -17,13 +19,14 @@ const READ_AUTHOR_DISPLAY_NAME_REASON = "reads the author's displayName from the
 // Both the field names and the optional `parents` allowlist come from the
 // entity's own `parentRef` declaration, which the read gate reads too —
 // see shared/parent-visibility.ts.
-export function createAddNoteHandler(access = DEFAULT_NOTES_HISTORY_ACCESS) {
+export function createAddNoteHandler(access = DEFAULT_NOTES_HISTORY_ACCESS, entryExecutor = noteEntryExecutor) {
     return {
         name: "add-note",
         schema: addNotePayloadSchema,
         access,
         description: "Appends a note to one host entity's history, stamping the author from the authenticated caller rather than the payload; use it for every remark and correction alike, because entries can never be edited or removed afterwards.",
         escapeHatch: {
+            grants: ["unsafeRaw"],
             reason: READ_AUTHOR_DISPLAY_NAME_REASON,
         },
         handler: async (event, ctx) => {
@@ -31,13 +34,27 @@ export function createAddNoteHandler(access = DEFAULT_NOTES_HISTORY_ACCESS) {
             const denied = await denyUnlessJoinRowParentVisible(ctx.registry, "note-entry", payload, event.user, ctx.db);
             if (denied)
                 return denied;
+            // A mention of a non-member would leave a note body about that person out of reach of
+            // their forget run, which only visits the tenants they are a member of.
+            const mentionedUserIds = [...new Set(payload.mentions ?? [])];
+            if (mentionedUserIds.length > 0) {
+                const memberRows = await ctx.db.selectMany(tenantMembershipsTable, {
+                    userId: { in: mentionedUserIds },
+                });
+                const memberIds = new Set(memberRows.map((row) => row.userId));
+                if (mentionedUserIds.some((userId) => !memberIds.has(userId))) {
+                    return writeFailure(new ValidationError({
+                        fields: [{ path: "mentions", code: "custom", i18nKey: "errors.validation.custom" }],
+                    }));
+                }
+            }
             let authorName = null;
             try {
                 // read_users is tenant-agnostic → ctx.db.unsafeRaw, not the tenant-scoped ctx.db.
                 // Bun.SQL poisons the whole tx after any error inside it, even one that's
                 // caught — so the lookup runs in a savepoint where available, otherwise directly
                 // (pool statements are their own units).
-                authorName = await runInSavepointIfSupported(ctx.db.unsafeRaw(READ_AUTHOR_DISPLAY_NAME_REASON), async (sp) => {
+                authorName = await runInSavepointIfSupported(ctx.db.unsafeRaw(), async (sp) => {
                     const userRow = await fetchOne(sp, userTable, {
                         id: event.user.id,
                     });
@@ -54,13 +71,13 @@ export function createAddNoteHandler(access = DEFAULT_NOTES_HISTORY_ACCESS) {
                 authorName = null;
             }
             const { mentions, ...notePayload } = payload;
-            const created = await noteEntryExecutor.create({ ...notePayload, authorId: event.user.id, authorName }, event.user, ctx.db);
+            const created = await entryExecutor.create({ ...notePayload, authorId: event.user.id, authorName }, event.user, ctx.db);
             if (!created.isSuccess)
                 return created;
             // Same tx as the note create above (ctx.db) — a mention-row failure
             // rolls the note back with it, same as the framework's own nested-write
             // parent+child pattern (dispatch-write.ts).
-            for (const subjectId of new Set(mentions ?? [])) {
+            for (const subjectId of mentionedUserIds) {
                 const mentionResult = await noteMentionExecutor.create({ noteId: created.data.id, subjectId }, event.user, ctx.db);
                 if (!mentionResult.isSuccess)
                     return mentionResult;

package/dist/notes-history-user-data/hooks.js

@@ -93,12 +93,30 @@ export const noteEntryDeleteHook = async (ctx) => {
         });
     }
 };
-// note-mention rows are a plain (noteId, subjectId) pointer — like authorId
-// on note-entry, `subjectId`'s `personal: "ref"` annotation exists for the
-// GDPR-hook-coverage boot guard, not because the row itself holds separately
-// exportable content or needs its own physical erasure: forgetting the
-// mentioned user's data is already handled by noteEntryDeleteHook shredding
-// the mentioned NOTE's row-subject key above. Registered here only so the V3
-// boot guard (validateGdprPiiHookCoverage) sees a hook for "note-mention".
-export const noteMentionExportHook = async () => null;
+// Erasure reaches every note that structurally mentions the user (see
+// noteEntryDeleteHook), so the Art. 15/20 export must list those notes too.
+export const noteMentionExportHook = async (ctx) => {
+    const mentions = await ctx.db.selectMany(noteMentionTable, {
+        subjectId: ctx.userId,
+    });
+    if (mentions.length === 0)
+        return null;
+    const noteIds = [...new Set(mentions.map((m) => m.noteId))];
+    const notes = await ctx.db.selectMany(noteEntryTable, { id: { in: noteIds } });
+    if (notes.length === 0)
+        return null;
+    return {
+        entity: "note-mention",
+        rows: notes.map((note) => ({
+            noteId: note["id"],
+            entityType: note["entityType"],
+            entityId: note["entityId"],
+            body: note["body"],
+            insertedAt: note["insertedAt"],
+        })),
+    };
+};
+// note-mention rows are a plain (noteId, subjectId) pointer: forgetting the mentioned
+// user's data is already handled by noteEntryDeleteHook shredding the mentioned NOTE's
+// row-subject key, so this delete hook has nothing of its own to erase.
 export const noteMentionDeleteHook = async () => { };

package/dist/renderer-simple/feature.d.ts

@@ -1,4 +1,10 @@
 import { type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import type { NotificationRenderer } from "../delivery/index.js";
 import { type RendererContext, type RenderRequest, type RenderResponse } from "../renderer-foundation/index.js";
-export declare function adaptToFoundation(req: RenderRequest, ctx: RendererContext): Promise<RenderResponse>;
-export declare function createRendererSimpleFeature(): FeatureDefinition;
+import { type MailBranding } from "./simple-renderer.js";
+export declare function adaptToFoundation(req: RenderRequest, ctx: RendererContext, renderer?: NotificationRenderer): Promise<RenderResponse>;
+export type RendererSimpleOptions = {
+    /** Branding applied to every notification mail, including the framework auth mails. */
+    readonly mailBranding?: MailBranding;
+};
+export declare function createRendererSimpleFeature(options?: RendererSimpleOptions): FeatureDefinition;

package/dist/renderer-simple/feature.js

@@ -1,7 +1,7 @@
 import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { RENDERER_EXTENSION, RendererError, } from "../renderer-foundation/index.js";
 import { resolveNotificationVariables } from "./resolve-variables.js";
-import { simpleRenderer } from "./simple-renderer.js";
+import { createSimpleRenderer, simpleRenderer } from "./simple-renderer.js";
 // Adapter: simpleRenderer.render hat `Promise<string>`-Signatur (Legacy
 // NotificationRenderer-Contract), renderer-foundation erwartet
 // `Promise<RenderResponse>` mit discriminated union. Mapper bewahrt
@@ -9,20 +9,23 @@ import { simpleRenderer } from "./simple-renderer.js";
 // Inline-CSS) und packt sie in den RendererPlugin-Contract.
 //
 // Exported damit der Adapter-Pfad direkt testbar ist (unit-test).
-export async function adaptToFoundation(req, ctx) {
+export async function adaptToFoundation(req, ctx, renderer = simpleRenderer) {
     if (req.kind !== "notification") {
         // Defensiver Guard — Foundation wählt Plugins nur für matching kinds,
         // dieser Pfad sollte unter normalen Umständen nie erreicht werden.
         throw new RendererError(`renderer-simple supports only kind="notification", got "${req.kind}"`, "invalid_payload");
     }
     const variables = await resolveNotificationVariables(req, ctx);
-    const html = await simpleRenderer.render({
+    const html = await renderer.render({
         template: req.payload.template ?? "",
         variables,
     });
     return { kind: "notification", html };
 }
-export function createRendererSimpleFeature() {
+export function createRendererSimpleFeature(options) {
+    const renderer = options?.mailBranding
+        ? createSimpleRenderer(options.mailBranding)
+        : simpleRenderer;
     return defineFeature("renderer-simple", (r) => {
         r.describe('Default renderer plugin for `kind="notification"`: takes a structured `EmailTemplateData` variable map (with `header`, `sections[]` of text/button objects, and optional `footer`; falls back to `title`/`body` if no structured fields are present) and returns rendered HTML with inline CSS. Requires `renderer-foundation`; sufficient for plain notification emails \u2014 swap it for `renderer-mail-html` if you need MJML/Markdown layouts.');
         r.uiHints({
@@ -34,7 +37,7 @@ export function createRendererSimpleFeature() {
         r.optionalRequires("template-resolver");
         r.useExtension(RENDERER_EXTENSION, "simple", {
             kinds: ["notification"],
-            render: adaptToFoundation,
+            render: (req, ctx) => adaptToFoundation(req, ctx, renderer),
         });
     });
 }

package/dist/renderer-simple/index.d.ts

@@ -1,2 +1,2 @@
-export { createRendererSimpleFeature } from "./feature.js";
-export { simpleRenderer } from "./simple-renderer.js";
+export { createRendererSimpleFeature, type RendererSimpleOptions } from "./feature.js";
+export { createSimpleRenderer, type MailBranding, simpleRenderer } from "./simple-renderer.js";

package/dist/renderer-simple/index.js

@@ -1,2 +1,2 @@
 export { createRendererSimpleFeature } from "./feature.js";
-export { simpleRenderer } from "./simple-renderer.js";
+export { createSimpleRenderer, simpleRenderer } from "./simple-renderer.js";

package/dist/renderer-simple/simple-renderer.d.ts

@@ -1,2 +1,17 @@
 import type { NotificationRenderer } from "../delivery/index.js";
+export type MailBranding = {
+    /** Shown as text when there is no logo, and as the logo alt text. */
+    readonly productName?: string;
+    /** Hex color (#rgb, #rrggbb, #rrggbbaa); used for buttons and the header accent. */
+    readonly primaryColor?: string;
+    /** Absolute http(s) URL; anything else is dropped. */
+    readonly logoUrl?: string;
+    readonly footerText?: string;
+    /** Absolute http(s) URLs only; other entries are dropped. */
+    readonly footerLinks?: readonly {
+        readonly label: string;
+        readonly url: string;
+    }[];
+};
+export declare function createSimpleRenderer(branding?: MailBranding): NotificationRenderer;
 export declare const simpleRenderer: NotificationRenderer;

package/dist/renderer-simple/simple-renderer.js

@@ -1,37 +1,84 @@
-import { escapeHtml } from "@cosmicdrift/kumiko-headless";
-function renderSection(section) {
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+const DEFAULT_PRIMARY_COLOR = "#2563eb";
+const HEX_COLOR_PATTERN = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+function isHttpUrl(value) {
+    try {
+        const { protocol } = new URL(value);
+        return protocol === "http:" || protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+function resolvePrimaryColor(branding) {
+    const color = branding?.primaryColor;
+    return color && HEX_COLOR_PATTERN.test(color) ? color : DEFAULT_PRIMARY_COLOR;
+}
+function renderBrandingHeader(branding, primaryColor) {
+    if (!branding)
+        return "";
+    const logoUrl = branding.logoUrl && isHttpUrl(branding.logoUrl) ? branding.logoUrl : undefined;
+    if (!logoUrl && !branding.productName)
+        return "";
+    const logo = logoUrl
+        ? `<img src="${escapeHtmlAttr(logoUrl)}" alt="${escapeHtmlAttr(branding.productName ?? "")}" style="display:block;max-height:40px;max-width:200px;border:0" />`
+        : `<span style="font-size:18px;font-weight:700;color:${escapeHtmlAttr(primaryColor)}">${escapeHtml(branding.productName ?? "")}</span>`;
+    return `<div style="margin:0 0 24px;padding:0 0 16px;border-bottom:3px solid ${escapeHtmlAttr(primaryColor)}">${logo}</div>`;
+}
+function renderBrandingFooter(branding) {
+    if (!branding)
+        return "";
+    const links = (branding.footerLinks ?? [])
+        .filter((link) => isHttpUrl(link.url))
+        .map((link) => `<a href="${escapeHtmlAttr(link.url)}" style="color:#999">${escapeHtml(link.label)}</a>`);
+    const footerPartsHtml = [
+        branding.footerText ? escapeHtml(branding.footerText) : "",
+        links.join(" · "),
+    ].filter((part) => part !== "");
+    if (footerPartsHtml.length === 0)
+        return "";
+    const footerHtml = footerPartsHtml.join("<br />");
+    return `<p style="margin:16px 0 0;color:#999;font-size:12px">${footerHtml}</p>`;
+}
+function renderSection(section, primaryColor) {
     if ("text" in section) {
         return `<p style="margin:0 0 16px;color:#333;font-size:14px;line-height:1.5">${escapeHtml(section.text)}</p>`;
     }
     if ("button" in section) {
-        return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:#2563eb;color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
+        return `<p style="margin:0 0 16px"><a href="${escapeHtml(section.button.url)}" style="display:inline-block;padding:10px 24px;background:${escapeHtmlAttr(primaryColor)};color:#fff;text-decoration:none;border-radius:4px;font-size:14px">${escapeHtml(section.button.label)}</a></p>`;
     }
     return "";
 }
 // Simple Renderer: turns structured email template data into HTML with inline CSS.
 // No external dependencies, no template engine — just string concatenation.
-export const simpleRenderer = {
-    name: "simple",
-    async render(input) {
-        const data = input.variables; // @cast-boundary render-helper
-        // Fallback: if no structured fields, use title + body as header + single text section
-        const header = data.header ?? data.title;
-        const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
-        const parts = [];
-        parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
-        parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
-        if (header) {
-            parts.push(`<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`);
-        }
-        if (sections) {
-            for (const section of sections) {
-                parts.push(renderSection(section));
+export function createSimpleRenderer(branding) {
+    const primaryColor = resolvePrimaryColor(branding);
+    return {
+        name: "simple",
+        async render(input) {
+            const data = input.variables; // @cast-boundary render-helper
+            // Fallback: if no structured fields, use title + body as header + single text section
+            const header = data.header ?? data.title;
+            const sections = data.sections ?? (data.body ? [{ text: data.body }] : undefined);
+            const parts = [];
+            parts.push('<!DOCTYPE html><html><body style="margin:0;padding:0;font-family:sans-serif">');
+            parts.push('<div style="max-width:600px;margin:0 auto;padding:24px">');
+            parts.push(renderBrandingHeader(branding, primaryColor));
+            if (header) {
+                parts.push(`<h1 style="margin:0 0 24px;color:#111;font-size:20px;font-weight:600">${escapeHtml(header)}</h1>`);
+            }
+            if (sections) {
+                for (const section of sections) {
+                    parts.push(renderSection(section, primaryColor));
+                }
             }
-        }
-        if (data.footer) {
-            parts.push(`<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`);
-        }
-        parts.push("</div></body></html>");
-        return parts.join("");
-    },
-};
+            if (data.footer) {
+                parts.push(`<p style="margin:24px 0 0;color:#999;font-size:12px;border-top:1px solid #eee;padding-top:16px">${escapeHtml(data.footer)}</p>`);
+            }
+            parts.push(renderBrandingFooter(branding));
+            parts.push("</div></body></html>");
+            return parts.join("");
+        },
+    };
+}
+export const simpleRenderer = createSimpleRenderer();

package/dist/secrets/feature.js

@@ -135,7 +135,7 @@ export function createSecretsFeature(opts = {}) {
             escapeHatch: {
                 reason: ROTATE_ESCAPE_HATCH_REASON,
             },
-            handler: (payload, ctx) => rotateJob(payload, ctx, ctx.db.unsafeRaw(ROTATE_ESCAPE_HATCH_REASON)),
+            handler: (payload, ctx) => rotateJob(payload, ctx, ctx.db.unsafeRaw()),
         });
         // Pre-ES had a separate `retention-cleanup` job scrubbing the audit
         // table on a compliance-driven schedule (90d default). Post-ES the

package/dist/sessions/feature.js

@@ -121,7 +121,7 @@ export function createSessionsFeature(options) {
             name: "cleanup",
             trigger: { manual: true },
             escapeHatch: { reason: CLEANUP_ESCAPE_HATCH_REASON },
-            handler: (payload, ctx) => cleanupJob(payload, ctx, ctx.db.unsafeRaw(CLEANUP_ESCAPE_HATCH_REASON)),
+            handler: (payload, ctx) => cleanupJob(payload, ctx, ctx.db.unsafeRaw()),
         });
         // Cross-feature entity hook on "user". `r.entityHook` (NOT `r.hook`) is
         // the supported cross-feature path: entity-keyed, not prefixed by the

package/dist/sessions/handlers/revoke-all-for-user.write.js

@@ -37,10 +37,11 @@ export const revokeAllForUserWrite = defineWriteHandler({
     description: "Irreversibly signs a named user out of all their live sessions, across every tenant unless a tenantId narrows it, optionally sparing one session (exceptSessionId); use it for operator actions such as freezing or banning an account, or a role change that must not end the editor's own session.",
     agent: { risk: "high" },
     escapeHatch: {
+        grants: ["unsafeRaw"],
         reason: REVOKE_ALL_SESSIONS_REASON,
     },
     handler: async (event, ctx) => {
-        const runner = ctx.db.unsafeRaw(REVOKE_ALL_SESSIONS_REASON);
+        const runner = ctx.db.unsafeRaw();
         const updated = await updateMany(runner, userSessionTable, { revokedAt: Temporal.Now.instant() }, {
             userId: event.payload.userId,
             revokedAt: null,

package/dist/subscription-mollie/plugin-methods.js

@@ -49,6 +49,7 @@ export function createMollieCheckoutSession(client, priceToConfig, appWebhookUrl
             metadata: {
                 tenantId: options.tenantId,
                 priceId: options.priceId,
+                ...(options.consentId && { consentId: options.consentId }),
             },
         })); // @cast-boundary engine-bridge
         const checkoutHref = payment.getCheckoutUrl();

package/dist/subscription-mollie/verify-webhook.js

@@ -13,7 +13,7 @@
 // muss `customerSubscriptions.create` selbst aufrufen). Wir machen
 // das im Plugin (idempotent via list-check), damit Foundation einen
 // Created-Event mit subscription-id bekommt.
-import { SubscriptionEventTypes, SubscriptionStatuses, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { parseProviderConsentId, SubscriptionEventTypes, SubscriptionStatuses, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import { Temporal } from "temporal-polyfill";
 import { MOLLIE_PROVIDER_NAME } from "./constants.js";
@@ -85,17 +85,18 @@ export function verifyAndParseMollieWebhook(client, options) {
             throw new Error(`subscription-mollie: subscription ${subscription.id} has neither nextPaymentDate nor startDate`);
         }
         const currentPeriodEnd = mollieDateStringToInstantIso(periodEndSource);
+        const consentId = parseProviderConsentId(metadata["consentId"]);
         return {
             providerEventId: id,
             providerName: MOLLIE_PROVIDER_NAME,
             type,
             tenantId,
+            ...(consentId !== undefined && { consentId }),
             providerCustomerId: subscription.customerId,
             providerSubscriptionId: subscription.id,
             status,
             tier,
             currentPeriodEnd,
-            rawPayload: JSON.stringify({ webhookId: id, subscription, triggerPayment }),
         };
     };
 }
@@ -112,6 +113,7 @@ async function ensureSubscriptionForMandate(client, options, payment) {
     const paymentMetadata = payment.metadata ?? {}; // @cast-boundary engine-bridge
     const tenantId = paymentMetadata["tenantId"];
     const priceId = paymentMetadata["priceId"];
+    const consentId = parseProviderConsentId(paymentMetadata["consentId"]);
     if (!tenantId || !priceId)
         return null;
     const priceCfg = options.priceToConfig[priceId];
@@ -130,7 +132,7 @@ async function ensureSubscriptionForMandate(client, options, payment) {
         amount: { currency: priceCfg.amountCurrency, value: priceCfg.amountValue },
         interval: priceCfg.interval,
         description: priceCfg.description,
-        metadata: { tenantId, priceId },
+        metadata: { tenantId, priceId, ...(consentId && { consentId }) },
     });
 }
 // =============================================================================

package/dist/subscription-stripe/plugin-methods.d.ts

@@ -8,6 +8,7 @@ export type StripeCheckoutSessionRuntimeOptions = {
      *  Never applied in mode:"subscription" — Stripe rejects invoice_creation there. */
     readonly paymentInvoiceCreation?: boolean;
 };
+export declare function mapAppLocaleToStripeLocale(locale: string): Stripe.Checkout.SessionCreateParams.Locale;
 export declare function createStripeCheckoutSession(runtime: StripeCtxRuntime, { paymentInvoiceCreation }?: StripeCheckoutSessionRuntimeOptions): (ctx: HandlerContext, options: StripeCheckoutOptions) => Promise<{
     url: string;
 }>;
@@ -15,7 +16,8 @@ export type StripePortalOptions = Parameters<NonNullable<SubscriptionProviderPlu
 export declare function createStripePortalSession(runtime: StripeCtxRuntime): (ctx: HandlerContext, options: StripePortalOptions) => Promise<{
     url: string;
 }>;
-export declare function createStripeCancelSubscription(runtime: StripeCtxRuntime): (ctx: HandlerContext, providerSubscriptionId: string) => Promise<void>;
+export type StripeCancelOptions = Parameters<NonNullable<SubscriptionProviderPlugin["cancelSubscription"]>>[1];
+export declare function createStripeCancelSubscription(runtime: StripeCtxRuntime): (ctx: HandlerContext, options: StripeCancelOptions) => Promise<void>;
 export type StripeRetrieveSubscriptionOptions = {
     readonly priceToTier: Readonly<Record<string, string>>;
 };

package/dist/subscription-stripe/plugin-methods.js

@@ -15,10 +15,65 @@
 // Contract erweitert (z.B. neuer optionaler Field), bemerkt der
 // Stripe-Plugin das beim TS-Compile, nicht erst zur Laufzeit.
 import { createHash } from "node:crypto";
-import { KNOWN_RECURRING_INTERVALS, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { KNOWN_RECURRING_INTERVALS, SubscriptionCancelTimings, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import Stripe from "stripe";
 import { isResourceMissingStripeError, mapStripeSubscriptionState } from "./verify-webhook.js";
+// Stripe's own Locale union also accepts arbitrary strings, so the known set
+// is spelled out here to pick a value Stripe actually renders.
+const STRIPE_CHECKOUT_LOCALES = [
+    "bg",
+    "cs",
+    "da",
+    "de",
+    "el",
+    "en",
+    "en-GB",
+    "es",
+    "es-419",
+    "et",
+    "fi",
+    "fil",
+    "fr",
+    "fr-CA",
+    "hr",
+    "hu",
+    "id",
+    "it",
+    "ja",
+    "ko",
+    "lt",
+    "lv",
+    "ms",
+    "mt",
+    "nb",
+    "nl",
+    "pl",
+    "pt",
+    "pt-BR",
+    "ro",
+    "ru",
+    "sk",
+    "sl",
+    "sv",
+    "th",
+    "tr",
+    "vi",
+    "zh",
+    "zh-HK",
+    "zh-TW",
+];
+// Stripe rejects custom_text.submit.message above 1200 characters.
+const STRIPE_CUSTOM_TEXT_MAX_LENGTH = 1200;
+export function mapAppLocaleToStripeLocale(locale) {
+    const normalized = locale.replace("_", "-");
+    const knownLocales = STRIPE_CHECKOUT_LOCALES;
+    const exact = knownLocales.find((known) => known.toLowerCase() === normalized.toLowerCase());
+    if (exact)
+        return exact;
+    const language = normalized.split("-")[0]?.toLowerCase();
+    return knownLocales.find((known) => known === language) ?? "auto";
+}
 function isUnknownCustomerStripeError(error) {
     return (isResourceMissingStripeError(error) &&
         error instanceof Stripe.errors.StripeInvalidRequestError &&
@@ -34,11 +89,22 @@ export function createStripeCheckoutSession(runtime, { paymentInvoiceCreation =
         await runtime.assertBillingLive(ctx);
         const stripe = await runtime.clientForCtx(ctx);
         const mode = options.mode ?? "subscription";
+        const metadata = {
+            tenantId: options.tenantId,
+            ...(options.consentId && { consentId: options.consentId }),
+        };
         const sessionParams = (providerCustomerId) => ({
             mode,
             line_items: [{ price: options.priceId, quantity: 1 }],
             success_url: options.successUrl,
             cancel_url: options.cancelUrl,
+            submit_type: "pay",
+            ...(options.locale && { locale: mapAppLocaleToStripeLocale(options.locale) }),
+            ...(options.submitMessage && {
+                custom_text: {
+                    submit: { message: options.submitMessage.slice(0, STRIPE_CUSTOM_TEXT_MAX_LENGTH) },
+                },
+            }),
             // subscription_data is subscription-mode-only (Stripe rejects it in
             // payment-mode) — the subsequent webhook reads metadata.tenantId off
             // the subscription it creates. payment-mode has no subscription, so
@@ -47,9 +113,9 @@ export function createStripeCheckoutSession(runtime, { paymentInvoiceCreation =
             // rejects it in subscription-mode, which invoices via the subscription
             // itself.
             ...(mode === "subscription"
-                ? { subscription_data: { metadata: { tenantId: options.tenantId } } }
+                ? { subscription_data: { metadata } }
                 : {
-                    payment_intent_data: { metadata: { tenantId: options.tenantId } },
+                    payment_intent_data: { metadata },
                     invoice_creation: { enabled: paymentInvoiceCreation },
                     // Without a customer, Stripe's default "if_required" makes a guest
                     // checkout when invoice_creation is off; the webhook then has no
@@ -88,17 +154,17 @@ export function createStripePortalSession(runtime) {
         return { url: session.url };
     };
 }
-// =============================================================================
-// cancelSubscription
-// =============================================================================
-//
-// Stripe sendet danach `customer.subscription.deleted`-webhook → der
-// state-update läuft über den normalen webhook-pfad. Diese function
-// triggert nur die API-Cancellation.
 export function createStripeCancelSubscription(runtime) {
-    return async (ctx, providerSubscriptionId) => {
+    return async (ctx, options) => {
         const stripe = await runtime.clientForCtx(ctx);
-        await stripe.subscriptions.cancel(providerSubscriptionId);
+        if (options.when === SubscriptionCancelTimings.periodEnd) {
+            await stripe.subscriptions.update(options.providerSubscriptionId, {
+                cancel_at_period_end: true,
+            });
+        }
+        else {
+            await stripe.subscriptions.cancel(options.providerSubscriptionId);
+        }
     };
 }
 export function createStripeRetrieveSubscription(runtime, { priceToTier }) {
@@ -122,7 +188,6 @@ export function createStripeRetrieveSubscription(runtime, { priceToTier }) {
                 : subscription.customer.id,
             providerSubscriptionId: subscription.id,
             ...state,
-            rawPayload: JSON.stringify(subscription),
         };
     };
 }

package/dist/subscription-stripe/verify-webhook.js

@@ -31,7 +31,7 @@
 // status/tier/period-end mapping. resource_missing (deleted between webhook
 // and retrieve) returns null; any other Stripe error becomes 503 so Stripe
 // redelivers.
-import { BillingEventKinds, SubscriptionEventTypes, SubscriptionStatuses, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { BillingEventKinds, parseProviderConsentId, SubscriptionEventTypes, SubscriptionStatuses, } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { ExtraRouteRejection } from "@cosmicdrift/kumiko-framework/api";
 import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import Stripe from "stripe";
@@ -116,15 +116,16 @@ export function verifyAndParseStripeWebhook(runtime, options) {
         if (!state) {
             return null;
         }
+        const consentId = parseProviderConsentId(sub.metadata?.["consentId"]);
         return {
             providerEventId: event.id,
             providerName: STRIPE_PROVIDER_NAME,
             type: normalizedType,
             tenantId,
+            ...(consentId !== undefined && { consentId }),
             providerCustomerId: typeof sub.customer === "string" ? sub.customer : sub.customer.id,
             providerSubscriptionId: sub.id,
             ...state,
-            rawPayload: JSON.stringify(event),
         };
     };
 }
@@ -269,6 +270,7 @@ function dropPaidSession(event, session, reason) {
 }
 /** Parses a checkout.session.completed / .async_payment_succeeded event into
  *  a PaymentEvent, or null if it isn't a paid one-off-payment session. */
+// kumiko-lint-ignore complexity-budget optional-field spreads over the session, one branch per optional provider field
 async function parsePaymentEvent(event, stripe) {
     const session = event.data.object; // @cast-boundary engine-bridge
     // mode !== "payment" excludes subscription-checkout sessions (same event types);
@@ -326,13 +328,15 @@ async function parsePaymentEvent(event, stripe) {
     if (!providerCustomerId) {
         return dropPaidSession(event, session, "missing_customer");
     }
+    const consentId = parseProviderConsentId(paymentIntent.metadata?.["consentId"]);
     return {
         kind: BillingEventKinds.payment,
         providerEventId: event.id,
         providerName: STRIPE_PROVIDER_NAME,
         tenantId,
+        ...(consentId !== undefined && { consentId }),
+        providerCheckoutId: session.id,
         providerCustomerId,
         priceId,
-        rawPayload: JSON.stringify(event),
     };
 }

package/dist/tags/executor.d.ts

@@ -1,2 +1,4 @@
+import { type EntityDefinition } from "@cosmicdrift/kumiko-framework/engine";
 export declare const tagExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
 export declare const tagAssignmentExecutor: import("@cosmicdrift/kumiko-types/event-store-executor-types").EventStoreExecutor;
+export declare function createTagAssignmentExecutor(ownership: EntityDefinition["access"] | undefined): typeof tagAssignmentExecutor;

package/dist/tags/executor.js

@@ -1,7 +1,15 @@
 import { createEntityExecutor } from "@cosmicdrift/kumiko-framework/engine";
-import { tagAssignmentEntity, tagEntity } from "./entity.js";
+import { createTagAssignmentEntity, tagAssignmentEntity, tagEntity } from "./entity.js";
 // Shared executors for the tag + tag-assignment write-handlers.
 // createEntityExecutor is side-effect-free; instantiating once keeps the
 // table+executor pair in one place instead of rebuilding it per handler module.
 export const { executor: tagExecutor } = createEntityExecutor("tag", tagEntity);
 export const { executor: tagAssignmentExecutor } = createEntityExecutor("tag-assignment", tagAssignmentEntity);
+// Carries only `ownership.write`: the executor enforces entity.access.write on
+// create/restore/delete, while a read rule would hide rows from the handlers'
+// own idempotency reads and the delete-tag cascade.
+export function createTagAssignmentExecutor(ownership) {
+    if (ownership?.write === undefined)
+        return tagAssignmentExecutor;
+    return createEntityExecutor("tag-assignment", createTagAssignmentEntity({ write: ownership.write })).executor;
+}