@cosmicdrift/kumiko-bundled-features 0.336.1 → 0.338.0

package/dist/billing-foundation/consumer-protection/confirmation-mail.js

@@ -0,0 +1,125 @@
+import { Temporal } from "temporal-polyfill";
+import { CONSENT_TEXTS, resolveConsentLocale } from "./consent-text.js";
+const LABELS = {
+    de: {
+        subject: "Vertragsbestätigung",
+        intro: "vielen Dank für Ihre Bestellung. Hiermit bestätigen wir den Vertragsschluss mit folgendem Inhalt.",
+        plan: "Tarif",
+        oneOffPayment: "Einmalzahlung",
+        price: "Preis",
+        oneOff: "einmalig",
+        contractStart: "Vertragsbeginn",
+        currentPeriodEnd: "Aktueller Abrechnungszeitraum bis",
+        consentHeading: "Ihre Zustimmungen",
+        consentGivenAt: "Erteilt am",
+        termsHeading: "Allgemeine Geschäftsbedingungen",
+        contact: "Fragen zu Ihrem Vertrag richten Sie bitte an",
+        every: "alle",
+        intervals: {
+            day: { one: "Tag", many: "Tage" },
+            week: { one: "Woche", many: "Wochen" },
+            month: { one: "Monat", many: "Monate" },
+            year: { one: "Jahr", many: "Jahre" },
+        },
+    },
+    en: {
+        subject: "Contract confirmation",
+        intro: "thank you for your order. We hereby confirm the conclusion of the contract with the following content.",
+        plan: "Plan",
+        oneOffPayment: "One-off payment",
+        price: "Price",
+        oneOff: "one-off",
+        contractStart: "Contract start",
+        currentPeriodEnd: "Current billing period ends",
+        consentHeading: "Your consents",
+        consentGivenAt: "Given on",
+        termsHeading: "Terms and conditions",
+        contact: "Questions about your contract go to",
+        every: "every",
+        intervals: {
+            day: { one: "day", many: "days" },
+            week: { one: "week", many: "weeks" },
+            month: { one: "month", many: "months" },
+            year: { one: "year", many: "years" },
+        },
+    },
+};
+function formatPrice(consent, locale) {
+    const labels = LABELS[locale];
+    if (consent.unitAmount === null || consent.currency === null)
+        return "-";
+    let amount;
+    try {
+        const format = new Intl.NumberFormat(locale, { style: "currency", currency: consent.currency });
+        const fractionDigits = format.resolvedOptions().maximumFractionDigits ?? 2;
+        amount = format.format(consent.unitAmount / 10 ** fractionDigits);
+    }
+    catch {
+        // Currency codes come from the provider; an unknown one must not block the mail.
+        amount = `${consent.unitAmount} ${consent.currency.toUpperCase()}`;
+    }
+    if (consent.interval === null)
+        return `${amount} (${labels.oneOff})`;
+    const unit = labels.intervals[consent.interval];
+    const count = consent.intervalCount ?? 1;
+    const intervalText = unit === undefined
+        ? consent.interval
+        : count === 1
+            ? unit.one
+            : `${labels.every} ${count} ${unit.many}`;
+    return count === 1 ? `${amount} / ${intervalText}` : `${amount}, ${intervalText}`;
+}
+function formatDate(iso, locale) {
+    let epochMilliseconds;
+    try {
+        epochMilliseconds = Temporal.Instant.from(iso).epochMilliseconds;
+    }
+    catch {
+        return iso;
+    }
+    return new Intl.DateTimeFormat(locale, {
+        dateStyle: "long",
+        timeStyle: "short",
+        timeZone: "UTC",
+    }).format(epochMilliseconds);
+}
+function paragraphs(text) {
+    return text
+        .split(/\n{2,}/)
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0)
+        .map((part) => ({ text: part }));
+}
+/** Structured mail content (header/sections/footer) for the email channel's
+ *  renderer; the renderer owns HTML escaping, this only builds plain text. */
+export function renderContractConfirmation(args) {
+    const locale = resolveConsentLocale(args.consent.locale);
+    const labels = LABELS[locale];
+    const texts = CONSENT_TEXTS[locale];
+    const { consent } = args;
+    const contractLines = [
+        `${labels.plan}: ${consent.tier ?? labels.oneOffPayment}`,
+        `${labels.price}: ${formatPrice(consent, locale)}`,
+        `${labels.contractStart}: ${formatDate(args.contractStartIso, locale)}`,
+        ...(args.currentPeriodEndIso !== undefined
+            ? [`${labels.currentPeriodEnd}: ${formatDate(args.currentPeriodEndIso, locale)}`]
+            : []),
+    ];
+    const vatNote = args.vatNote[locale] ?? args.vatNote[resolveConsentLocale()];
+    return {
+        subject: labels.subject,
+        header: labels.subject,
+        sections: [
+            { text: labels.intro },
+            ...contractLines.map((text) => ({ text })),
+            ...(vatNote !== undefined ? [{ text: vatNote }] : []),
+            { text: labels.consentHeading },
+            { text: texts.earlyPerformance },
+            { text: texts.withdrawalLoss },
+            { text: `${labels.consentGivenAt}: ${formatDate(args.consentGivenAtIso, locale)}` },
+            { text: labels.termsHeading },
+            ...paragraphs(args.termsContent),
+        ],
+        footer: `${labels.contact} ${args.operatorEmail}`,
+    };
+}

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

@@ -0,0 +1,32 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { ConsumerProtectionOptions, ProviderPrice } from "../types.js";
+export type CheckoutMode = "subscription" | "payment";
+export declare const consentPayloadSchema: z.ZodObject<{
+    earlyPerformanceRequested: z.ZodLiteral<true>;
+    withdrawalLossAcknowledged: z.ZodLiteral<true>;
+    consentTextVersion: z.ZodString;
+    locale: z.ZodString;
+}, z.core.$strict>;
+export type ConsentPayload = z.infer<typeof consentPayloadSchema>;
+export type PreparedConsent = {
+    readonly consentId: string;
+    readonly mode: CheckoutMode;
+    readonly locale: string;
+    readonly submitMessage: string;
+    readonly consentTextVersion: string;
+    readonly termsHash: string;
+    readonly termsTemplateVersion: number;
+};
+export type ConsentPriceDetails = {
+    readonly tier: string | null;
+    readonly priceId: string;
+    readonly price: Pick<ProviderPrice, "unitAmount" | "currency" | "interval" | "intervalCount"> | null;
+};
+export declare function prepareConsent(ctx: HandlerContext, options: ConsumerProtectionOptions, consent: ConsentPayload, mode: CheckoutMode): Promise<PreparedConsent>;
+export declare function consentCheckoutFields(prepared: PreparedConsent): {
+    readonly consentId: string;
+    readonly locale: string;
+    readonly submitMessage: string;
+};
+export declare function recordConsent(ctx: HandlerContext, prepared: PreparedConsent, details: ConsentPriceDetails): Promise<void>;

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

@@ -0,0 +1,88 @@
+// Consent gate shared by start-plan-checkout and create-checkout-session:
+// validate + prepare before the provider call, record only after it succeeded.
+import { createHash } from "node:crypto";
+import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+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, PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
+import { consentTextVersion, resolveConsentLocale, submitMessageFor } from "./consent-text.js";
+export const consentPayloadSchema = z
+    .object({
+    earlyPerformanceRequested: z.literal(true),
+    withdrawalLossAcknowledged: z.literal(true),
+    consentTextVersion: z.string().min(1).max(64),
+    locale: z.string().min(2).max(35),
+})
+    .strict();
+export async function prepareConsent(ctx, options, consent, mode) {
+    const locale = resolveConsentLocale(consent.locale);
+    if (consent.consentTextVersion !== consentTextVersion(locale)) {
+        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}"`,
+        });
+    }
+    const resolver = requireTemplateResolver(ctx, "billing-foundation");
+    let terms;
+    try {
+        terms = await resolver.resolveTemplate({
+            tenantId: ctx.user.tenantId,
+            slug: options.termsTextBlock,
+            kind: TEXT_BLOCK_KIND,
+            locale,
+        });
+    }
+    catch (error) {
+        if (error instanceof TemplateNotFoundError) {
+            throw new UnprocessableError("terms_unavailable", {
+                i18nKey: "billing-foundation.errors.termsUnavailable",
+                message: `billing-foundation: terms text block "${options.termsTextBlock}" could not be resolved`,
+                cause: error,
+            });
+        }
+        throw error;
+    }
+    return {
+        consentId: generateId(),
+        mode,
+        locale,
+        submitMessage: submitMessageFor(locale, mode),
+        consentTextVersion: consent.consentTextVersion,
+        termsHash: createHash("sha256").update(terms.content).digest("hex"),
+        termsTemplateVersion: terms.version,
+    };
+}
+export function consentCheckoutFields(prepared) {
+    return {
+        consentId: prepared.consentId,
+        locale: prepared.locale,
+        submitMessage: prepared.submitMessage,
+    };
+}
+export async function recordConsent(ctx, prepared, details) {
+    const payload = {
+        consentId: prepared.consentId,
+        mode: prepared.mode,
+        tier: details.tier,
+        priceId: details.priceId,
+        unitAmount: details.price?.unitAmount ?? null,
+        currency: details.price?.currency ?? null,
+        interval: details.price?.interval ?? null,
+        intervalCount: details.price?.intervalCount ?? null,
+        consentTextVersion: prepared.consentTextVersion,
+        termsHash: prepared.termsHash,
+        termsTemplateVersion: prepared.termsTemplateVersion,
+        locale: prepared.locale,
+        actorUserId: String(ctx.user.id),
+    };
+    const tenantId = ctx.user.tenantId;
+    const isSubscription = prepared.mode === "subscription";
+    await ctx.unsafeAppendEvent({
+        aggregateId: isSubscription ? subscriptionAggregateId(tenantId) : paymentAggregateId(tenantId),
+        aggregateType: isSubscription ? SUBSCRIPTION_AGGREGATE_TYPE : PAYMENT_AGGREGATE_TYPE,
+        type: CHECKOUT_CONSENT_RECORDED_EVENT_QN,
+        payload,
+    });
+}

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

@@ -0,0 +1,5 @@
+export declare const CONSENT_LOCALES: readonly ["de", "en"];
+export type ConsentLocale = (typeof CONSENT_LOCALES)[number];
+export declare const FALLBACK_CONSENT_LOCALE: ConsentLocale;
+/** Exact match, else the language part ("de-AT" → "de"), else the fallback. */
+export declare function resolveConsentLocale(input?: string): ConsentLocale;

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

@@ -0,0 +1,17 @@
+// @runtime client
+// Crypto-free so the browser panel can share the locale rule with the server.
+export const CONSENT_LOCALES = ["de", "en"];
+export const FALLBACK_CONSENT_LOCALE = "de";
+function isConsentLocale(value) {
+    return CONSENT_LOCALES.some((locale) => locale === value);
+}
+/** Exact match, else the language part ("de-AT" → "de"), else the fallback. */
+export function resolveConsentLocale(input) {
+    if (input === undefined)
+        return FALLBACK_CONSENT_LOCALE;
+    const lower = input.toLowerCase();
+    if (isConsentLocale(lower))
+        return lower;
+    const language = lower.split("-")[0] ?? "";
+    return isConsentLocale(language) ? language : FALLBACK_CONSENT_LOCALE;
+}

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

@@ -0,0 +1,11 @@
+import type { ConsentLocale } from "./consent-locale.js";
+export { CONSENT_LOCALES, type ConsentLocale, FALLBACK_CONSENT_LOCALE, resolveConsentLocale, } from "./consent-locale.js";
+export type ConsentTexts = {
+    readonly earlyPerformance: string;
+    readonly withdrawalLoss: string;
+    readonly subscriptionSubmitMessage: string;
+    readonly paymentSubmitMessage: string;
+};
+export declare const CONSENT_TEXTS: Readonly<Record<ConsentLocale, ConsentTexts>>;
+export declare function consentTextVersion(locale: ConsentLocale): string;
+export declare function submitMessageFor(locale: ConsentLocale, mode: "subscription" | "payment"): string;

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

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+export { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE, resolveConsentLocale, } from "./consent-locale.js";
+export const CONSENT_TEXTS = {
+    de: {
+        earlyPerformance: "Ich verlange ausdrücklich, dass der Anbieter vor Ablauf der Widerrufsfrist mit der Ausführung des Vertrags beginnt.",
+        withdrawalLoss: "Ich nehme zur Kenntnis, dass ich mein Widerrufsrecht verliere, sobald der Vertrag von dem Anbieter vollständig erfüllt ist, bei digitalen Inhalten sobald die Ausführung begonnen hat, nachdem ich ausdrücklich zugestimmt habe und bestätigt habe, dass ich dadurch mein Widerrufsrecht verliere.",
+        subscriptionSubmitMessage: "Kostenpflichtiges Abonnement: Es verlängert sich zum Ende jedes Abrechnungszeitraums automatisch, bis Sie es kündigen. Sie können jederzeit zum Ende des laufenden Zeitraums kündigen.",
+        paymentSubmitMessage: "Kostenpflichtige Einmalzahlung: Mit Klick auf den Button verpflichten Sie sich zur Zahlung.",
+    },
+    en: {
+        earlyPerformance: "I expressly request that the provider begins performing the contract before the withdrawal period has expired.",
+        withdrawalLoss: "I acknowledge that I lose my right of withdrawal once the provider has fully performed the contract, and for digital content once performance has begun, after I have expressly consented and confirmed that I lose my right of withdrawal as a result.",
+        subscriptionSubmitMessage: "Paid subscription: it renews automatically at the end of each billing period until you cancel. You can cancel at any time, effective at the end of the current period.",
+        paymentSubmitMessage: "Paid one-off payment: by clicking the button you commit to paying.",
+    },
+};
+const CONSENT_TEXT_VERSION_LENGTH = 16;
+export function consentTextVersion(locale) {
+    const { earlyPerformance, withdrawalLoss } = CONSENT_TEXTS[locale];
+    return createHash("sha256")
+        .update(`${earlyPerformance}\n${withdrawalLoss}`)
+        .digest("hex")
+        .slice(0, CONSENT_TEXT_VERSION_LENGTH);
+}
+export function submitMessageFor(locale, mode) {
+    const texts = CONSENT_TEXTS[locale];
+    return mode === "subscription" ? texts.subscriptionSubmitMessage : texts.paymentSubmitMessage;
+}

package/dist/billing-foundation/consumer-protection/issue-confirmation.d.ts

@@ -0,0 +1,15 @@
+import { type WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import * as z from "zod";
+import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
+export declare const issueContractConfirmationSchema: z.ZodObject<{
+    consentId: z.ZodString;
+    sourceAggregateId: z.ZodUUID;
+    currentPeriodEndIso: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type IssueContractConfirmationResult = {
+    readonly issued: true;
+} | {
+    readonly issued: false;
+    readonly reason: "consent_not_found" | "already_issued" | "recipient_not_found";
+};
+export declare function createIssueContractConfirmationHandler(options: ResolvedBillingFoundationOptions, consumerProtection: ConsumerProtectionOptions): WriteHandlerDef;

package/dist/billing-foundation/consumer-protection/issue-confirmation.js

@@ -0,0 +1,149 @@
+// § 312f contract confirmation: one mail per recorded consent, sent by the
+// system-only issue-contract-confirmation handler that the event-triggered
+// jobs (register-consent.ts) call.
+import { access, createSystemUser, } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
+import * as z from "zod";
+import { requireTemplateResolver, TEXT_BLOCK_KIND } from "../../template-resolver/index.js";
+import { UserQueries } from "../../user/index.js";
+import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js";
+import { CONTRACT_CONFIRMATION_NOTIFICATION_TYPE } from "../constants.js";
+import { CHECKOUT_CONSENT_RECORDED_EVENT_QN, CONTRACT_CONFIRMATION_ISSUED_EVENT_QN, checkoutConsentRecordedPayloadSchema, contractConfirmationIssuedPayloadSchema, PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE, } from "../events.js";
+import { renderContractConfirmation } from "./confirmation-mail.js";
+import { resolveConsentLocale } from "./consent-text.js";
+export const issueContractConfirmationSchema = z
+    .object({
+    consentId: z.string().min(1).max(100),
+    sourceAggregateId: z.uuid(),
+    // Only set when the triggering subscription event carries it.
+    currentPeriodEndIso: z.string().min(1).optional(),
+})
+    .strict();
+const recipientRowSchema = z.object({
+    email: z.string().min(1),
+    isDeleted: z.boolean().optional(),
+});
+export function createIssueContractConfirmationHandler(options, consumerProtection) {
+    return {
+        name: "issue-contract-confirmation",
+        agent: { expose: false },
+        schema: issueContractConfirmationSchema,
+        access: { roles: access.system },
+        escapeHatch: {
+            reason: "reads the consenting buyer's email via UserQueries.findForAuth as a tenant system user; the mail goes only to the user recorded in the consent event",
+        },
+        // kumiko-lint-ignore complexity-budget one linear pass: stream lookup, consent match, idempotency check, recipient lookup, mail, marker append
+        handler: async (event, ctx) => {
+            // @cast-boundary engine-payload — dispatcher-zod-validated payload
+            const payload = event.payload;
+            const tenantId = event.user.tenantId;
+            // The stream is derived from the caller's tenant: no read of another
+            // tenant's stream and no arbitrary aggregate id.
+            const isSubscription = payload.sourceAggregateId === subscriptionAggregateId(tenantId);
+            if (!isSubscription && payload.sourceAggregateId !== paymentAggregateId(tenantId)) {
+                throw new UnprocessableError("invalid_source_aggregate", {
+                    message: `billing-foundation: ${payload.sourceAggregateId} is not the subscription or payment stream of tenant ${tenantId}`,
+                });
+            }
+            const stream = await ctx.fetchForWriting({
+                aggregateId: payload.sourceAggregateId,
+                aggregateType: isSubscription ? SUBSCRIPTION_AGGREGATE_TYPE : PAYMENT_AGGREGATE_TYPE,
+            });
+            let consentEvent;
+            let consent;
+            for (const e of stream.events) {
+                if (e.type !== CHECKOUT_CONSENT_RECORDED_EVENT_QN)
+                    continue;
+                const parsed = checkoutConsentRecordedPayloadSchema.safeParse(e.payload);
+                if (parsed.success && parsed.data.consentId === payload.consentId) {
+                    consentEvent = e;
+                    consent = parsed.data;
+                    break;
+                }
+            }
+            if (!consentEvent || !consent) {
+                ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] no recorded consent ${payload.consentId} on the stream; no mail sent`);
+                return {
+                    isSuccess: true,
+                    data: {
+                        issued: false,
+                        reason: "consent_not_found",
+                    },
+                };
+            }
+            const alreadyIssued = stream.events.some((e) => e.type === CONTRACT_CONFIRMATION_ISSUED_EVENT_QN &&
+                contractConfirmationIssuedPayloadSchema.safeParse(e.payload).data?.consentId ===
+                    payload.consentId);
+            if (alreadyIssued) {
+                return {
+                    isSuccess: true,
+                    data: {
+                        issued: false,
+                        reason: "already_issued",
+                    },
+                };
+            }
+            // Everything that can fail runs before the append, so a failed run
+            // leaves no marker behind and the job retry starts clean.
+            const recipient = recipientRowSchema.safeParse(await ctx.queryAs(createSystemUser(tenantId), UserQueries.findForAuth, {
+                id: consent.actorUserId,
+            }));
+            if (!recipient.success || recipient.data.isDeleted === true) {
+                ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] recipient of consent ${payload.consentId} not found; no mail sent`);
+                return {
+                    isSuccess: true,
+                    data: {
+                        issued: false,
+                        reason: "recipient_not_found",
+                    },
+                };
+            }
+            const locale = resolveConsentLocale(consent.locale);
+            const terms = await requireTemplateResolver(ctx, "billing-foundation").resolveTemplate({
+                tenantId,
+                slug: consumerProtection.termsTextBlock,
+                kind: TEXT_BLOCK_KIND,
+                locale,
+            });
+            if (terms.version !== consent.termsTemplateVersion) {
+                ctx.log?.warn(`[billing-foundation:issue-contract-confirmation] terms text block changed since consent ${payload.consentId} (version ${consent.termsTemplateVersion} -> ${terms.version}); the mail carries the current text`);
+            }
+            const issuedAtIso = options.now().toString();
+            const content = renderContractConfirmation({
+                consent,
+                consentGivenAtIso: consentEvent.createdAt.toString(),
+                contractStartIso: issuedAtIso,
+                ...(payload.currentPeriodEndIso !== undefined && {
+                    currentPeriodEndIso: payload.currentPeriodEndIso,
+                }),
+                vatNote: consumerProtection.vatNote,
+                operatorEmail: consumerProtection.operatorEmail,
+                termsContent: terms.content,
+            });
+            if (!ctx.notify) {
+                throw new InternalError({
+                    message: "billing-foundation:issue-contract-confirmation: ctx.notify unavailable — the delivery feature must be mounted",
+                });
+            }
+            // Append BEFORE notifying: appendOne carries the fetched stream version
+            // as expectedVersion, so of two concurrent runs only one insert wins
+            // (the other fails with a version conflict) and only the winner mails.
+            const issued = {
+                consentId: payload.consentId,
+                issuedAtIso,
+                locale,
+                termsTemplateVersion: terms.version,
+            };
+            await stream.appendOne({ type: CONTRACT_CONFIRMATION_ISSUED_EVENT_QN, payload: issued });
+            await ctx.notify(CONTRACT_CONFIRMATION_NOTIFICATION_TYPE, {
+                route: { email: recipient.data.email },
+                data: content,
+                priority: "critical",
+            });
+            return {
+                isSuccess: true,
+                data: { issued: true },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,3 @@
+import type { FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
+export declare function registerConsumerProtection(r: FeatureRegistrar, options: ResolvedBillingFoundationOptions, consumerProtection: ConsumerProtectionOptions): void;

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

@@ -0,0 +1,63 @@
+import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id.js";
+import { SubscriptionFoundationHandlers, SubscriptionStatuses } from "../constants.js";
+import { CHECKOUT_CONSENT_RECORDED_EVENT_SHORT, CONTRACT_CONFIRMATION_ISSUED_EVENT_SHORT, checkoutConsentRecordedPayloadSchema, contractConfirmationIssuedPayloadSchema, INVOICE_PAID_EVENT_QN, PAYMENT_RECEIVED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN, SUBSCRIPTION_UPDATED_EVENT_QN, } from "../events.js";
+import { createIssueContractConfirmationHandler } from "./issue-confirmation.js";
+import { registerContractTermination } from "./register-termination.js";
+const CONFIRMATION_TRIGGERS = [
+    {
+        eventQn: SUBSCRIPTION_CREATED_EVENT_QN,
+        jobName: "confirm-on-subscription-created",
+        stream: "subscription",
+    },
+    {
+        eventQn: SUBSCRIPTION_UPDATED_EVENT_QN,
+        jobName: "confirm-on-subscription-updated",
+        stream: "subscription",
+    },
+    { eventQn: INVOICE_PAID_EVENT_QN, jobName: "confirm-on-invoice-paid", stream: "subscription" },
+    { eventQn: PAYMENT_RECEIVED_EVENT_QN, jobName: "confirm-on-payment-received", stream: "payment" },
+];
+function isConfirmableSubscriptionStatus(status) {
+    return status === SubscriptionStatuses.active || status === SubscriptionStatuses.trialing;
+}
+export function registerConsumerProtection(r, options, consumerProtection) {
+    r.requires("template-resolver", "delivery", "user", "tenant");
+    registerContractTermination(r, options, consumerProtection);
+    r.defineEvent(CHECKOUT_CONSENT_RECORDED_EVENT_SHORT, checkoutConsentRecordedPayloadSchema, {
+        piiFields: "none",
+    });
+    r.defineEvent(CONTRACT_CONFIRMATION_ISSUED_EVENT_SHORT, contractConfirmationIssuedPayloadSchema, {
+        piiFields: "none",
+    });
+    r.writeHandler(createIssueContractConfirmationHandler(options, consumerProtection));
+    // The consent is recorded before the buyer pays; the mail goes out once a
+    // later event for the same consentId shows the contract is live. The jobs
+    // are at-least-once, the handler's append makes the mail once-only.
+    for (const trigger of CONFIRMATION_TRIGGERS) {
+        r.job(trigger.jobName, { trigger: { on: trigger.eventQn }, runIn: "worker" }, async (payload, ctx) => {
+            const consentId = payload["consentId"];
+            // skip: trigger event carries no consent to confirm
+            if (typeof consentId !== "string" || consentId.length === 0)
+                return;
+            const isSubscriptionEvent = trigger.stream === "subscription";
+            // skip: subscription not live yet, a later event confirms
+            if (isSubscriptionEvent && !isConfirmableSubscriptionStatus(payload["status"]))
+                return;
+            // The tenant comes from the stored trigger event (the job's system
+            // user), never from payload data.
+            const tenantId = ctx.systemUser.tenantId;
+            const currentPeriodEndIso = payload["currentPeriodEndIso"];
+            const result = await ctx.writeAs(createSystemUser(tenantId), SubscriptionFoundationHandlers.issueContractConfirmation, {
+                consentId,
+                sourceAggregateId: isSubscriptionEvent
+                    ? subscriptionAggregateId(tenantId)
+                    : paymentAggregateId(tenantId),
+                ...(typeof currentPeriodEndIso === "string" && { currentPeriodEndIso }),
+            });
+            if (!result.isSuccess) {
+                throw new Error(`billing-foundation:${trigger.jobName}: issue-contract-confirmation failed: ${JSON.stringify(result.error)}`);
+            }
+        });
+    }
+}

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

@@ -0,0 +1,3 @@
+import type { FeatureRegistrar } from "@cosmicdrift/kumiko-framework/engine";
+import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.js";
+export declare function registerContractTermination(r: FeatureRegistrar, options: ResolvedBillingFoundationOptions, consumerProtection: ConsumerProtectionOptions): void;

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

@@ -0,0 +1,12 @@
+import { CONTRACT_TERMINATION_REQUESTED_EVENT_SHORT, CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT, contractTerminationRequestedPayloadSchema, contractTerminationUnmatchedPayloadSchema, } from "../events.js";
+import { createRecordContractTerminationHandler, createRecordUnmatchedContractTerminationHandler, createTerminableSubscriptionQuery, } from "./termination-record.js";
+import { createRequestContractTerminationHandler, createTerminateContractHandler, } from "./termination-request.js";
+export function registerContractTermination(r, options, consumerProtection) {
+    r.defineEvent(CONTRACT_TERMINATION_REQUESTED_EVENT_SHORT, contractTerminationRequestedPayloadSchema, { piiFields: "none" });
+    r.defineEvent(CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT, contractTerminationUnmatchedPayloadSchema, { piiFields: "none" });
+    r.queryHandler(createTerminableSubscriptionQuery());
+    r.writeHandler(createRecordContractTerminationHandler(options));
+    r.writeHandler(createRecordUnmatchedContractTerminationHandler());
+    r.writeHandler(createRequestContractTerminationHandler(options, consumerProtection));
+    r.writeHandler(createTerminateContractHandler(options, consumerProtection));
+}

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

@@ -0,0 +1,43 @@
+import type { ContractTerminationDeclarationType, ContractTerminationKind, ProviderCancelOutcome } from "../events.js";
+import type { ConsentLocale } from "./consent-text.js";
+import { type OperatorNoticeReason } from "./termination-texts.js";
+export type TerminationMailContent = {
+    readonly subject: string;
+    readonly header: string;
+    readonly sections: readonly {
+        readonly text: string;
+    }[];
+    readonly footer: string;
+};
+/** What the declarant entered; the only input of the receipt. */
+export type TerminationDeclaration = {
+    readonly declarationType: ContractTerminationDeclarationType;
+    readonly terminationKind: ContractTerminationKind;
+    readonly name?: string;
+    readonly email: string;
+    readonly customerReference?: string;
+    readonly reason?: string;
+};
+export declare function formatReceivedAt(iso: string, locale: ConsentLocale): string;
+export type RenderTerminationReceiptArgs = {
+    readonly locale: ConsentLocale;
+    readonly requestId: string;
+    readonly receivedAtIso: string;
+    readonly declaration: TerminationDeclaration;
+    readonly operatorEmail: string;
+};
+/** Built from the declarant's own input only: the content must not depend on
+ *  whether (or how) the declaration matched a contract. */
+export declare function renderTerminationReceipt(args: RenderTerminationReceiptArgs): TerminationMailContent;
+export type RenderOperatorNoticeArgs = {
+    readonly locale: ConsentLocale;
+    readonly requestId: string;
+    readonly receivedAtIso: string;
+    readonly channel: "public" | "account";
+    readonly declaration: TerminationDeclaration;
+    readonly reasons: readonly OperatorNoticeReason[];
+    readonly tenantId?: string;
+    readonly providerCancel?: ProviderCancelOutcome;
+    readonly operatorEmail: string;
+};
+export declare function renderOperatorNotice(args: RenderOperatorNoticeArgs): TerminationMailContent;