@cosmicdrift/kumiko-bundled-features 0.337.1 → 0.339.0

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,40 @@
+import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
+import { SubscriptionCancelTimings, SubscriptionFoundationHandlers } from "../constants.js";
+import { CONTRACT_TERMINATION_DECLARED_EVENT_QN, CONTRACT_TERMINATION_DECLARED_EVENT_SHORT, CONTRACT_TERMINATION_REQUESTED_EVENT_SHORT, CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT, contractTerminationDeclaredPayloadSchema, contractTerminationRequestedPayloadSchema, contractTerminationUnmatchedPayloadSchema, } from "../events.js";
+import { createDeclareContractTerminationHandler, 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_DECLARED_EVENT_SHORT, contractTerminationDeclaredPayloadSchema, { piiFields: "none" });
+    r.defineEvent(CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT, contractTerminationUnmatchedPayloadSchema, { piiFields: "none" });
+    r.queryHandler(createTerminableSubscriptionQuery());
+    r.writeHandler(createDeclareContractTerminationHandler());
+    r.writeHandler(createRecordContractTerminationHandler(options, consumerProtection));
+    r.writeHandler(createRecordUnmatchedContractTerminationHandler());
+    r.writeHandler(createRequestContractTerminationHandler(options, consumerProtection));
+    r.writeHandler(createTerminateContractHandler(options, consumerProtection));
+    // The provider cancel of a public declaration runs here, not in the
+    // request: matched and unmatched requests then do the same work and the
+    // response time does not tell whether the email belongs to a customer.
+    // The tenant comes from the stored trigger event (the job's system user).
+    r.job("cancel-on-public-termination-declared", { trigger: { on: CONTRACT_TERMINATION_DECLARED_EVENT_QN }, runIn: "worker" }, async (payload, ctx) => {
+        const declared = contractTerminationDeclaredPayloadSchema.safeParse(payload);
+        // skip: trigger event carries no usable declaration
+        if (!declared.success)
+            return;
+        const result = await ctx.writeAs(createSystemUser(ctx.systemUser.tenantId), SubscriptionFoundationHandlers.recordContractTermination, {
+            requestId: declared.data.requestId,
+            declarationType: declared.data.declarationType,
+            terminationKind: declared.data.terminationKind,
+            channel: "public",
+            when: declared.data.declarationType === "withdrawal"
+                ? "none"
+                : SubscriptionCancelTimings.periodEnd,
+            receivedAtIso: declared.data.receivedAtIso,
+            locale: declared.data.locale,
+        });
+        if (!result.isSuccess) {
+            throw new Error(`billing-foundation:cancel-on-public-termination-declared: record-contract-termination failed: ${JSON.stringify(result.error)}`);
+        }
+    });
+}

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

@@ -0,0 +1,45 @@
+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;
+};
+/** The operator notice for a provider problem has no declarant data at all. */
+export type OperatorNoticeDeclaration = Pick<TerminationDeclaration, "declarationType" | "terminationKind"> & Partial<Omit<TerminationDeclaration, "declarationType" | "terminationKind">>;
+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: OperatorNoticeDeclaration;
+    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}`] : []),
+        ...(declaration.email !== undefined ? [`${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-notify.d.ts

@@ -0,0 +1,18 @@
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { ProviderCancelOutcome } from "../events.js";
+import type { ConsumerProtectionOptions } from "../types.js";
+import type { ConsentLocale } from "./consent-text.js";
+import { type OperatorNoticeDeclaration } from "./termination-mail.js";
+import type { OperatorNoticeReason } from "./termination-texts.js";
+export type OperatorNoticePlan = {
+    readonly locale: ConsentLocale;
+    readonly requestId: string;
+    readonly receivedAtIso: string;
+    readonly channel: "public" | "account";
+    readonly declaration: OperatorNoticeDeclaration;
+    readonly reasons: readonly OperatorNoticeReason[];
+    readonly tenantId?: string;
+    readonly providerCancel?: ProviderCancelOutcome;
+};
+export declare function requireNotify(ctx: HandlerContext): NonNullable<HandlerContext["notify"]>;
+export declare function notifyOperator(ctx: HandlerContext, consumerProtection: ConsumerProtectionOptions, plan: OperatorNoticePlan): Promise<void>;

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

@@ -0,0 +1,21 @@
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE } from "../constants.js";
+import { renderOperatorNotice } from "./termination-mail.js";
+export function requireNotify(ctx) {
+    if (!ctx.notify) {
+        throw new InternalError({
+            message: "billing-foundation:termination: ctx.notify unavailable — the delivery feature must be mounted",
+        });
+    }
+    return ctx.notify;
+}
+export async function notifyOperator(ctx, consumerProtection, plan) {
+    await requireNotify(ctx)(CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE, {
+        route: { email: consumerProtection.operatorEmail },
+        data: renderOperatorNotice({
+            ...plan,
+            operatorEmail: consumerProtection.operatorEmail,
+        }),
+        priority: "critical",
+    });
+}

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[];