@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.338.0

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;

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

@@ -0,0 +1,76 @@
+import { Temporal } from "temporal-polyfill";
+import { TERMINATION_TEXTS } from "./termination-texts.js";
+const TIME_ZONE_BY_LOCALE = {
+    de: "Europe/Berlin",
+    en: "UTC",
+};
+export function formatReceivedAt(iso, locale) {
+    let epochMilliseconds;
+    try {
+        epochMilliseconds = Temporal.Instant.from(iso).epochMilliseconds;
+    }
+    catch {
+        return iso;
+    }
+    return new Intl.DateTimeFormat(locale, {
+        dateStyle: "long",
+        timeStyle: "long",
+        timeZone: TIME_ZONE_BY_LOCALE[locale],
+    }).format(epochMilliseconds);
+}
+function declarationLines(declaration, locale) {
+    const texts = TERMINATION_TEXTS[locale];
+    const lines = [
+        `${texts.declarationType}: ${texts.declarationTypeLabel[declaration.declarationType]}`,
+        `${texts.terminationKind}: ${texts.terminationKindLabel[declaration.terminationKind]}`,
+        ...(declaration.name !== undefined ? [`${texts.name}: ${declaration.name}`] : []),
+        `${texts.email}: ${declaration.email}`,
+        ...(declaration.customerReference
+            ? [`${texts.customerReference}: ${declaration.customerReference}`]
+            : []),
+        ...(declaration.reason ? [`${texts.reasonFieldLabel}: ${declaration.reason}`] : []),
+    ];
+    return lines.map((text) => ({ text }));
+}
+/** Built from the declarant's own input only: the content must not depend on
+ *  whether (or how) the declaration matched a contract. */
+export function renderTerminationReceipt(args) {
+    const texts = TERMINATION_TEXTS[args.locale];
+    const subject = texts.receiptSubject[args.declaration.declarationType];
+    return {
+        subject,
+        header: subject,
+        sections: [
+            { text: texts.receiptIntro },
+            { text: `${texts.receivedAt}: ${formatReceivedAt(args.receivedAtIso, args.locale)}` },
+            { text: `${texts.requestId}: ${args.requestId}` },
+            ...declarationLines(args.declaration, args.locale),
+            { text: texts.receiptNextSteps },
+            { text: texts.receiptRevoke(args.operatorEmail) },
+        ],
+        footer: `${texts.contact} ${args.operatorEmail}`,
+    };
+}
+export function renderOperatorNotice(args) {
+    const texts = TERMINATION_TEXTS[args.locale];
+    const subject = texts.operatorSubject[args.declaration.declarationType];
+    return {
+        subject,
+        header: subject,
+        sections: [
+            { text: texts.operatorIntro },
+            ...args.reasons.map((reason) => ({
+                text: `${texts.noticeReasons}: ${texts.operatorReasons[reason]}`,
+            })),
+            { text: `${texts.receivedAt}: ${formatReceivedAt(args.receivedAtIso, args.locale)}` },
+            { text: `${texts.requestId}: ${args.requestId}` },
+            { text: `${texts.channel}: ${texts.channelLabel[args.channel]}` },
+            ...(args.tenantId !== undefined ? [{ text: `${texts.tenant}: ${args.tenantId}` }] : []),
+            ...(args.providerCancel !== undefined
+                ? [{ text: `${texts.providerResult}: ${texts.providerResultLabel[args.providerCancel]}` }]
+                : []),
+            ...declarationLines(args.declaration, args.locale),
+        ],
+        footer: args.operatorEmail,
+    };
+}

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

@@ -0,0 +1,8 @@
+import type { AnonymousExtraRoute } from "@cosmicdrift/kumiko-framework/api";
+import type { ConsentLocale } from "./consent-text.js";
+export type ContractTerminationRoutesOptions = {
+    readonly paths?: Readonly<Partial<Record<ConsentLocale, string>>>;
+};
+/** GET + POST pages for de (`/legal/kuendigen`) and en (`/legal/cancel`);
+ *  mount via the app's `extraRoutes`. */
+export declare function createContractTerminationRoutes(options?: ContractTerminationRoutesOptions): AnonymousExtraRoute[];