@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.338.0

package/dist/billing-foundation/consumer-protection/termination-pages.js

@@ -0,0 +1,239 @@
+// Public § 312k pages (/legal/kuendigen, /legal/cancel): form → review → confirm,
+// no JavaScript. Every echoed value goes through escapeHtml/escapeHtmlAttr.
+import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-headless";
+import { securePageHeaders, wrapInLayout } from "../../page-render/index.js";
+import { SubscriptionFoundationHandlers } from "../constants.js";
+import { CONTRACT_TERMINATION_DECLARATION_TYPES, CONTRACT_TERMINATION_KINDS } from "../events.js";
+import { formatReceivedAt } from "./termination-mail.js";
+import { requestContractTerminationSchema } from "./termination-request.js";
+import { TERMINATION_TEXTS } from "./termination-texts.js";
+const DEFAULT_PATHS = {
+    de: "/legal/kuendigen",
+    en: "/legal/cancel",
+};
+const FORM_FIELDS = [
+    "declarationType",
+    "terminationKind",
+    "name",
+    "email",
+    "customerReference",
+    "reason",
+];
+const EMPTY_TEXT = "";
+const EMPTY_FORM = {
+    declarationType: "termination",
+    terminationKind: "ordinary",
+    name: "",
+    email: "",
+    customerReference: "",
+    reason: EMPTY_TEXT,
+};
+// The shared security headers leave framing to SAMEORIGIN; this form must
+// never be framed (clickjacking a "cancel now" button).
+function pageHeaders() {
+    const headers = securePageHeaders({
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+    });
+    return {
+        ...headers,
+        "content-security-policy": `${headers["content-security-policy"] ?? ""}; frame-ancestors 'none'; form-action 'self'`,
+        "x-frame-options": "DENY",
+    };
+}
+function htmlResponse(locale, title, bodyHtml, status) {
+    return new Response(wrapInLayout({ title, bodyHtml, lang: locale }), {
+        status,
+        headers: pageHeaders(),
+    });
+}
+function isOneOf(options, value) {
+    return options.includes(value);
+}
+async function readForm(c) {
+    const body = await c.req.parseBody();
+    const text = (key) => {
+        const value = body[key];
+        return typeof value === "string" ? value : "";
+    };
+    return {
+        step: text("step"),
+        values: {
+            declarationType: text("declarationType"),
+            terminationKind: text("terminationKind"),
+            name: text("name").trim(),
+            email: text("email").trim(),
+            customerReference: text("customerReference").trim(),
+            reason: text("reason").trim(),
+        },
+    };
+}
+function payloadOf(values, locale) {
+    return {
+        declarationType: values.declarationType,
+        terminationKind: values.terminationKind,
+        name: values.name,
+        email: values.email,
+        locale,
+        ...(values.customerReference !== "" && { customerReference: values.customerReference }),
+        ...(values.reason !== "" && { reason: values.reason }),
+    };
+}
+function validationMessages(values, locale) {
+    const parsed = requestContractTerminationSchema.safeParse(payloadOf(values, locale));
+    if (parsed.success)
+        return [];
+    const page = TERMINATION_TEXTS[locale].page;
+    const byField = {
+        name: page.errorName,
+        email: page.errorEmail,
+        reason: page.errorReason,
+        declarationType: page.errorChoice,
+        terminationKind: page.errorChoice,
+    };
+    return [
+        ...new Set(parsed.error.issues.map((issue) => byField[String(issue.path[0])] ?? page.errorGeneric)),
+    ];
+}
+function errorsHtml(messages, page) {
+    if (messages.length === 0)
+        return "";
+    return `<div role="alert"><h2>${escapeHtml(page.errorsHeading)}</h2><ul>${messages
+        .map((message) => `<li>${escapeHtml(message)}</li>`)
+        .join("")}</ul></div>`;
+}
+function radioGroup(name, options, labels, selected) {
+    return options
+        .map((option) => `<label><input type="radio" name="${name}" value="${escapeHtmlAttr(option)}"${option === selected ? " checked" : ""}> ${escapeHtml(labels[option])}</label><br>`)
+        .join("");
+}
+function textField(name, label, value, attributes) {
+    return `<p><label>${escapeHtml(label)}<br><input type="${escapeHtmlAttr(attributes.type ?? "text")}" name="${name}" value="${escapeHtmlAttr(value)}" maxlength="${attributes.maxlength}"${attributes.required ? " required" : ""}></label></p>`;
+}
+function formPage(locale, path, values, messages, status) {
+    const texts = TERMINATION_TEXTS[locale];
+    const { page } = texts;
+    const body = `<h1>${escapeHtml(page.title)}</h1>
+<p>${escapeHtml(page.lead)}</p>
+${errorsHtml(messages, page)}
+<form method="post" action="${escapeHtmlAttr(path)}">
+<input type="hidden" name="step" value="review">
+<fieldset><legend>${escapeHtml(page.declarationTypeHeading)}</legend>${radioGroup("declarationType", CONTRACT_TERMINATION_DECLARATION_TYPES, texts.declarationTypeLabel, values.declarationType)}</fieldset>
+<fieldset><legend>${escapeHtml(page.kindHeading)}</legend>${radioGroup("terminationKind", CONTRACT_TERMINATION_KINDS, texts.terminationKindLabel, values.terminationKind)}<p>${escapeHtml(page.earliestDate)}</p></fieldset>
+${textField("name", page.nameLabel, values.name, { required: true, maxlength: 200 })}
+${textField("email", page.emailLabel, values.email, { type: "email", required: true, maxlength: 254 })}
+${textField("customerReference", page.customerReferenceLabel, values.customerReference, { maxlength: 200 })}
+<p><label>${escapeHtml(page.reasonLabel)} (${escapeHtml(page.reasonHint)})<br><textarea name="reason" rows="5" maxlength="2000">${escapeHtml(values.reason)}</textarea></label></p>
+<p><button type="submit">${escapeHtml(page.reviewButton)}</button></p>
+</form>`;
+    return htmlResponse(locale, page.title, body, status);
+}
+function hiddenInputs(values) {
+    return FORM_FIELDS.map((field) => `<input type="hidden" name="${field}" value="${escapeHtmlAttr(values[field])}">`).join("\n");
+}
+function reviewPage(locale, path, values) {
+    const texts = TERMINATION_TEXTS[locale];
+    const { page } = texts;
+    // validationMessages already proved the enum values.
+    const declarationType = isOneOf(CONTRACT_TERMINATION_DECLARATION_TYPES, values.declarationType)
+        ? values.declarationType
+        : "termination";
+    const terminationKind = isOneOf(CONTRACT_TERMINATION_KINDS, values.terminationKind)
+        ? values.terminationKind
+        : "ordinary";
+    const row = (label, value) => value === ""
+        ? ""
+        : `<tr><th scope="row">${escapeHtml(label)}</th><td>${escapeHtml(value)}</td></tr>`;
+    const body = `<h1>${escapeHtml(page.reviewTitle)}</h1>
+<p>${escapeHtml(page.reviewLead)}</p>
+<table>
+${row(texts.declarationType, texts.declarationTypeLabel[declarationType])}
+${row(texts.terminationKind, texts.terminationKindLabel[terminationKind])}
+${row(texts.name, values.name)}
+${row(texts.email, values.email)}
+${row(texts.customerReference, values.customerReference)}
+${row(texts.reasonFieldLabel, values.reason)}
+</table>
+<form method="post" action="${escapeHtmlAttr(path)}">
+${hiddenInputs(values)}
+<button type="submit" name="step" value="confirm">${escapeHtml(page.confirmButton[declarationType])}</button>
+<button type="submit" name="step" value="edit">${escapeHtml(page.backButton)}</button>
+</form>`;
+    return htmlResponse(locale, page.reviewTitle, body, 200);
+}
+function resultPage(locale, receivedAtIso, requestId) {
+    const { page } = TERMINATION_TEXTS[locale];
+    const body = `<h1>${escapeHtml(page.resultTitle)}</h1>
+<p>${escapeHtml(page.resultLead)}</p>
+<p>${escapeHtml(page.resultReceivedAt)}: <strong>${escapeHtml(formatReceivedAt(receivedAtIso, locale))}</strong></p>
+<p>${escapeHtml(page.resultRequestId)}: <code>${escapeHtml(requestId)}</code></p>
+<p>${escapeHtml(page.resultMailNote)}</p>`;
+    return htmlResponse(locale, page.resultTitle, body, 200);
+}
+const RATE_LIMITED_CODE = "rate_limited";
+async function submitDeclaration(c, app, clientIp, values, locale) {
+    // deps.write only resolves a session user under /api/*; this page lives
+    // outside it, so it re-enters the dispatcher through the app like the
+    // user-export by-token route. The resolved clientIp as env keeps the
+    // handler's per-IP rate limit per visitor instead of one shared bucket.
+    const response = await app.fetch(new Request(`${new URL(c.req.url).origin}/api/write`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+            type: SubscriptionFoundationHandlers.requestContractTermination,
+            payload: payloadOf(values, locale),
+        }),
+    }), clientIp);
+    const parsed = await response.json().catch(() => null);
+    if (response.status === 429 || parsed?.error?.code === RATE_LIMITED_CODE) {
+        return { kind: "rate-limited" };
+    }
+    const requestId = parsed?.data?.requestId;
+    const receivedAtIso = parsed?.data?.receivedAtIso;
+    if (response.ok &&
+        parsed?.isSuccess === true &&
+        typeof requestId === "string" &&
+        typeof receivedAtIso === "string") {
+        return { kind: "received", requestId, receivedAtIso };
+    }
+    return { kind: "failed" };
+}
+function routesFor(locale, path) {
+    return [
+        {
+            method: "GET",
+            path,
+            entry: "anonymous",
+            handler: () => formPage(locale, path, EMPTY_FORM, [], 200),
+        },
+        {
+            method: "POST",
+            path,
+            entry: "anonymous",
+            handler: async (c, deps) => {
+                const { step, values } = await readForm(c);
+                if (step === "edit")
+                    return formPage(locale, path, values, [], 200);
+                const messages = validationMessages(values, locale);
+                if (messages.length > 0)
+                    return formPage(locale, path, values, messages, 400);
+                if (step !== "confirm")
+                    return reviewPage(locale, path, values);
+                const outcome = await submitDeclaration(c, deps.app, deps.clientIp, values, locale);
+                const { page } = TERMINATION_TEXTS[locale];
+                if (outcome.kind === "received") {
+                    return resultPage(locale, outcome.receivedAtIso, outcome.requestId);
+                }
+                if (outcome.kind === "rate-limited") {
+                    return htmlResponse(locale, page.rateLimitedTitle, `<h1>${escapeHtml(page.rateLimitedTitle)}</h1><p>${escapeHtml(page.rateLimitedBody)}</p>`, 429);
+                }
+                return formPage(locale, path, values, [page.errorGeneric], 400);
+            },
+        },
+    ];
+}
+/** GET + POST pages for de (`/legal/kuendigen`) and en (`/legal/cancel`);
+ *  mount via the app's `extraRoutes`. */
+export function createContractTerminationRoutes(options = {}) {
+    return ["de", "en"].flatMap((locale) => routesFor(locale, options.paths?.[locale] ?? DEFAULT_PATHS[locale]));
+}

package/dist/billing-foundation/consumer-protection/termination-record.d.ts

@@ -0,0 +1,51 @@
+import { type QueryHandlerDef, type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { type ProviderCancelOutcome } from "../events.js";
+import type { ResolvedBillingFoundationOptions } from "../types.js";
+import type { OperatorNoticeReason } from "./termination-texts.js";
+export declare const recordContractTerminationSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    declarationType: z.ZodEnum<{
+        termination: "termination";
+        withdrawal: "withdrawal";
+    }>;
+    terminationKind: z.ZodEnum<{
+        extraordinary: "extraordinary";
+        ordinary: "ordinary";
+    }>;
+    channel: z.ZodEnum<{
+        account: "account";
+        public: "public";
+    }>;
+    when: z.ZodEnum<{
+        immediately: "immediately";
+        none: "none";
+        "period-end": "period-end";
+    }>;
+}, z.core.$strict>;
+export type RecordContractTerminationResult = {
+    readonly receivedAtIso: string;
+    readonly effectiveAtIso: string | null;
+    readonly providerCancel: ProviderCancelOutcome;
+    readonly noticeReason: Extract<OperatorNoticeReason, "provider_cannot_cancel" | "provider_error" | "no_active_subscription"> | null;
+};
+export declare const recordUnmatchedContractTerminationSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    declarationType: z.ZodEnum<{
+        termination: "termination";
+        withdrawal: "withdrawal";
+    }>;
+    terminationKind: z.ZodEnum<{
+        extraordinary: "extraordinary";
+        ordinary: "ordinary";
+    }>;
+    receivedAtIso: z.ZodString;
+    matchResult: z.ZodEnum<{
+        ambiguous: "ambiguous";
+        none: "none";
+    }>;
+}, z.core.$strict>;
+export declare const terminableSubscriptionSchema: z.ZodObject<{}, z.core.$strict>;
+export declare function createTerminableSubscriptionQuery(): QueryHandlerDef;
+export declare function createRecordContractTerminationHandler(options: ResolvedBillingFoundationOptions): WriteHandlerDef;
+export declare function createRecordUnmatchedContractTerminationHandler(): WriteHandlerDef;

package/dist/billing-foundation/consumer-protection/termination-record.js

@@ -0,0 +1,162 @@
+// System-only building blocks of the § 312k flow: the per-tenant record
+// handler (provider cancel + event), the system-stream handler for
+// declarations no tenant matched, and the non-terminal probe the anonymous
+// request handler uses to find candidate tenants.
+import { access, SYSTEM_ROLE, } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { subscriptionAggregateId, terminationUnmatchedAggregateId } from "../aggregate-id.js";
+import { resolveProviderPlugin } from "../checkout-core.js";
+import { isTerminalSubscriptionStatus, SubscriptionCancelTimings } from "../constants.js";
+import { CONTRACT_TERMINATION_CHANNELS, CONTRACT_TERMINATION_DECLARATION_TYPES, CONTRACT_TERMINATION_KINDS, CONTRACT_TERMINATION_REQUESTED_EVENT_QN, CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE, CONTRACT_TERMINATION_UNMATCHED_EVENT_QN, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
+import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
+const REQUESTED_CANCEL_TIMINGS = [
+    SubscriptionCancelTimings.periodEnd,
+    SubscriptionCancelTimings.immediately,
+    "none",
+];
+export const recordContractTerminationSchema = z
+    .object({
+    requestId: z.string().min(1).max(100),
+    declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+    terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+    channel: z.enum(CONTRACT_TERMINATION_CHANNELS),
+    when: z.enum(REQUESTED_CANCEL_TIMINGS),
+})
+    .strict();
+export const recordUnmatchedContractTerminationSchema = z
+    .object({
+    requestId: z.string().min(1).max(100),
+    declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+    terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+    receivedAtIso: z.string().min(1),
+    matchResult: z.enum(["none", "ambiguous"]),
+})
+    .strict();
+export const terminableSubscriptionSchema = z.object({}).strict();
+export function createTerminableSubscriptionQuery() {
+    return {
+        name: "terminable-subscription",
+        description: "Tells whether the caller tenant holds a subscription that is not terminal; the anonymous termination request uses it to pick the tenant a declaration belongs to.",
+        agent: { expose: false },
+        schema: terminableSubscriptionSchema,
+        access: { roles: [SYSTEM_ROLE] },
+        handler: async (_query, ctx) => {
+            const subscription = await getSubscriptionForTenant(ctx, ctx.user.tenantId);
+            return {
+                terminable: subscription !== null && !isTerminalSubscriptionStatus(subscription.status),
+            };
+        },
+    };
+}
+export function createRecordContractTerminationHandler(options) {
+    return {
+        name: "record-contract-termination",
+        agent: { expose: false },
+        schema: recordContractTerminationSchema,
+        access: { roles: access.system },
+        handler: async (event, ctx) => {
+            // @cast-boundary engine-payload — dispatcher-zod-validated payload
+            const payload = event.payload;
+            const tenantId = event.user.tenantId;
+            if (payload.channel === "public" && payload.when === SubscriptionCancelTimings.immediately) {
+                throw new UnprocessableError("immediate_cancel_not_allowed", {
+                    message: "billing-foundation: the public channel never cancels at the provider immediately",
+                });
+            }
+            const receivedAtIso = options.now().toString();
+            const stream = await ctx.fetchForWriting({
+                aggregateId: subscriptionAggregateId(tenantId),
+                aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
+            });
+            let providerCancel = "none";
+            let effectiveAtIso = null;
+            let noticeReason = null;
+            if (payload.when !== "none") {
+                const subscription = await getSubscriptionForTenant(ctx, tenantId);
+                if (subscription === null || isTerminalSubscriptionStatus(subscription.status)) {
+                    noticeReason = "no_active_subscription";
+                }
+                else {
+                    const plugin = findPlugin(ctx, subscription.providerName);
+                    if (!plugin?.cancelSubscription) {
+                        noticeReason = "provider_cannot_cancel";
+                    }
+                    else {
+                        try {
+                            await plugin.cancelSubscription(ctx, {
+                                providerSubscriptionId: subscription.providerSubscriptionId,
+                                when: payload.when,
+                            });
+                            providerCancel = payload.when;
+                            effectiveAtIso =
+                                payload.when === SubscriptionCancelTimings.immediately
+                                    ? receivedAtIso
+                                    : subscription.currentPeriodEnd.toString();
+                        }
+                        catch (error) {
+                            ctx.log?.warn(`[billing-foundation:record-contract-termination] provider cancel failed for tenant ${tenantId}: ${error instanceof Error ? error.message : String(error)}`);
+                            noticeReason = "provider_error";
+                        }
+                    }
+                }
+            }
+            const recorded = {
+                requestId: payload.requestId,
+                declarationType: payload.declarationType,
+                terminationKind: payload.terminationKind,
+                channel: payload.channel,
+                receivedAtIso,
+                effectiveAtIso,
+                providerCancel,
+            };
+            await stream.appendOne({
+                type: CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
+                payload: recorded,
+            });
+            return {
+                isSuccess: true,
+                data: {
+                    receivedAtIso,
+                    effectiveAtIso,
+                    providerCancel,
+                    noticeReason,
+                },
+            };
+        },
+    };
+}
+function findPlugin(ctx, providerName) {
+    try {
+        return resolveProviderPlugin(ctx, providerName).plugin;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function createRecordUnmatchedContractTerminationHandler() {
+    return {
+        name: "record-unmatched-contract-termination",
+        agent: { expose: false },
+        schema: recordUnmatchedContractTerminationSchema,
+        access: { roles: access.system },
+        handler: async (event, ctx) => {
+            // @cast-boundary engine-payload — dispatcher-zod-validated payload
+            const payload = event.payload;
+            const stream = await ctx.fetchForWriting({
+                aggregateId: terminationUnmatchedAggregateId(payload.requestId),
+                aggregateType: CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE,
+            });
+            const recorded = {
+                requestId: payload.requestId,
+                declarationType: payload.declarationType,
+                terminationKind: payload.terminationKind,
+                channel: "public",
+                receivedAtIso: payload.receivedAtIso,
+                matchResult: payload.matchResult,
+            };
+            await stream.appendOne({ type: CONTRACT_TERMINATION_UNMATCHED_EVENT_QN, payload: recorded });
+            return { isSuccess: true, data: { recorded: true } };
+        },
+    };
+}

package/dist/billing-foundation/consumer-protection/termination-request.d.ts

@@ -0,0 +1,45 @@
+import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import { type ProviderCancelOutcome } from "../events.js";
+import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
+export declare const requestContractTerminationSchema: z.ZodObject<{
+    declarationType: z.ZodEnum<{
+        termination: "termination";
+        withdrawal: "withdrawal";
+    }>;
+    terminationKind: z.ZodEnum<{
+        extraordinary: "extraordinary";
+        ordinary: "ordinary";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    email: z.ZodEmail;
+    customerReference: z.ZodOptional<z.ZodString>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        de: "de";
+        en: "en";
+    }>>;
+}, z.core.$strict>;
+export declare const terminateContractSchema: z.ZodObject<{
+    declarationType: z.ZodEnum<{
+        termination: "termination";
+        withdrawal: "withdrawal";
+    }>;
+    terminationKind: z.ZodEnum<{
+        extraordinary: "extraordinary";
+        ordinary: "ordinary";
+    }>;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type RequestContractTerminationResult = {
+    readonly requestId: string;
+    readonly receivedAtIso: string;
+};
+export type TerminateContractResult = {
+    readonly requestId: string;
+    readonly receivedAtIso: string;
+    readonly effectiveAtIso: string | null;
+    readonly providerCancel: ProviderCancelOutcome;
+};
+export declare function createRequestContractTerminationHandler(options: ResolvedBillingFoundationOptions, consumerProtection: ConsumerProtectionOptions): WriteHandlerDef;
+export declare function createTerminateContractHandler(options: ResolvedBillingFoundationOptions, consumerProtection: ConsumerProtectionOptions): WriteHandlerDef;