@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-texts.ts

@@ -0,0 +1,242 @@
+import type { ContractTerminationDeclarationType, ContractTerminationKind } from "../events.js";
+import type { ConsentLocale } from "./consent-text.js";
+
+// Legal wording shown to the consumer, deliberately inline de/en like the
+// consent texts (not the en-only i18n convention).
+export type TerminationTexts = {
+  readonly declarationTypeLabel: Readonly<Record<ContractTerminationDeclarationType, string>>;
+  readonly terminationKindLabel: Readonly<Record<ContractTerminationKind, string>>;
+  readonly declarationType: string;
+  readonly terminationKind: string;
+  readonly receivedAt: string;
+  readonly requestId: string;
+  readonly name: string;
+  readonly email: string;
+  readonly customerReference: string;
+  readonly reasonFieldLabel: string;
+  readonly receiptSubject: Readonly<Record<ContractTerminationDeclarationType, string>>;
+  readonly receiptIntro: string;
+  readonly receiptNextSteps: string;
+  readonly receiptRevoke: (operatorEmail: string) => string;
+  readonly contact: string;
+  readonly operatorSubject: Readonly<Record<ContractTerminationDeclarationType, string>>;
+  readonly operatorIntro: string;
+  readonly operatorReasons: Readonly<Record<OperatorNoticeReason, string>>;
+  readonly noticeReasons: string;
+  readonly channel: string;
+  readonly channelLabel: Readonly<Record<"public" | "account", string>>;
+  readonly tenant: string;
+  readonly providerResult: string;
+  readonly providerResultLabel: Readonly<Record<"period-end" | "immediately" | "none", string>>;
+  readonly page: PageTexts;
+};
+
+export type PageTexts = {
+  readonly title: string;
+  readonly lead: string;
+  readonly declarationTypeHeading: string;
+  readonly kindHeading: string;
+  readonly reasonHint: string;
+  readonly earliestDate: string;
+  readonly nameLabel: string;
+  readonly emailLabel: string;
+  readonly customerReferenceLabel: string;
+  readonly reasonLabel: string;
+  readonly reviewButton: string;
+  readonly reviewTitle: string;
+  readonly reviewLead: string;
+  readonly confirmButton: Readonly<Record<ContractTerminationDeclarationType, string>>;
+  readonly backButton: string;
+  readonly resultTitle: string;
+  readonly resultLead: string;
+  readonly resultReceivedAt: string;
+  readonly resultRequestId: string;
+  readonly resultMailNote: string;
+  readonly errorsHeading: string;
+  readonly errorName: string;
+  readonly errorEmail: string;
+  readonly errorReason: string;
+  readonly errorChoice: string;
+  readonly errorGeneric: string;
+  readonly rateLimitedTitle: string;
+  readonly rateLimitedBody: string;
+};
+
+export const OPERATOR_NOTICE_REASONS = [
+  "unmatched",
+  "ambiguous",
+  "withdrawal",
+  "extraordinary",
+  "provider_cannot_cancel",
+  "provider_error",
+  "no_active_subscription",
+  "recording_failed",
+] as const;
+export type OperatorNoticeReason = (typeof OPERATOR_NOTICE_REASONS)[number];
+
+export const TERMINATION_TEXTS: Readonly<Record<ConsentLocale, TerminationTexts>> = {
+  de: {
+    declarationTypeLabel: { termination: "Kündigung", withdrawal: "Widerruf" },
+    terminationKindLabel: {
+      ordinary: "Ordentlich zum nächstmöglichen Zeitpunkt",
+      extraordinary: "Außerordentlich (aus wichtigem Grund)",
+    },
+    declarationType: "Erklärung",
+    terminationKind: "Art der Kündigung",
+    receivedAt: "Eingegangen am",
+    requestId: "Vorgangsnummer",
+    name: "Name",
+    email: "E-Mail",
+    customerReference: "Kundennummer / Referenz",
+    reasonFieldLabel: "Begründung",
+    receiptSubject: {
+      termination: "Eingangsbestätigung Ihrer Kündigung",
+      withdrawal: "Eingangsbestätigung Ihres Widerrufs",
+    },
+    receiptIntro:
+      "wir bestätigen den Eingang Ihrer Erklärung mit folgendem Inhalt. Diese E-Mail ist eine Eingangsbestätigung, keine Bestätigung der Wirksamkeit.",
+    receiptNextSteps:
+      "Wir prüfen Ihre Erklärung und melden uns, sobald sie bearbeitet ist oder wir Rückfragen haben.",
+    receiptRevoke: (operatorEmail) =>
+      `Haben Sie diese Erklärung nicht abgegeben oder möchten Sie sie zurücknehmen? Schreiben Sie uns bitte umgehend an ${operatorEmail}.`,
+    contact: "Fragen richten Sie bitte an",
+    operatorSubject: {
+      termination: "Kündigung: Bearbeitung nötig",
+      withdrawal: "Widerruf: Bearbeitung nötig",
+    },
+    operatorIntro: "Es ist eine Erklärung eingegangen, die Ihre Bearbeitung braucht.",
+    operatorReasons: {
+      unmatched: "Kein passender Vertrag zur angegebenen E-Mail gefunden",
+      ambiguous: "Die angegebene E-Mail passt zu mehreren Verträgen",
+      withdrawal: "Widerruf (nur Erfassung, kein Anbieter-Aufruf über das öffentliche Formular)",
+      extraordinary: "Außerordentliche Kündigung, Begründung prüfen",
+      provider_cannot_cancel: "Der Zahlungsanbieter unterstützt keine Kündigung per Schnittstelle",
+      provider_error: "Die Kündigung beim Zahlungsanbieter ist fehlgeschlagen",
+      no_active_subscription: "Keine laufende Subscription beim Anbieter",
+      recording_failed: "Die Erklärung konnte nicht gespeichert werden",
+    },
+    noticeReasons: "Grund der Benachrichtigung",
+    channel: "Kanal",
+    channelLabel: { public: "Öffentliches Formular", account: "Kundenkonto" },
+    tenant: "Mandant",
+    providerResult: "Kündigung beim Anbieter",
+    providerResultLabel: {
+      "period-end": "zum Ende des Abrechnungszeitraums veranlasst",
+      immediately: "sofort veranlasst",
+      none: "nicht veranlasst",
+    },
+    page: {
+      title: "Vertrag kündigen oder widerrufen",
+      lead: "Mit diesem Formular erklären Sie die Kündigung oder den Widerruf Ihres Vertrags. Sie brauchen dafür kein Kundenkonto.",
+      declarationTypeHeading: "Was möchten Sie erklären?",
+      kindHeading: "Art der Kündigung",
+      reasonHint: "Pflicht bei außerordentlicher Kündigung.",
+      earliestDate: "Die Kündigung gilt zum nächstmöglichen Zeitpunkt.",
+      nameLabel: "Name",
+      emailLabel: "E-Mail-Adresse des Kontos",
+      customerReferenceLabel: "Kundennummer (optional)",
+      reasonLabel: "Begründung",
+      reviewButton: "Weiter zur Prüfung",
+      reviewTitle: "Bitte prüfen Sie Ihre Angaben",
+      reviewLead: "Erst mit dem Klick auf den Button unten wird Ihre Erklärung abgegeben.",
+      confirmButton: { termination: "Jetzt kündigen", withdrawal: "Jetzt widerrufen" },
+      backButton: "Angaben ändern",
+      resultTitle: "Ihre Erklärung ist eingegangen",
+      resultLead: "Wir haben Ihre Erklärung erhalten und senden Ihnen eine Eingangsbestätigung.",
+      resultReceivedAt: "Eingegangen am",
+      resultRequestId: "Vorgangsnummer",
+      resultMailNote: "Die Eingangsbestätigung geht an die von Ihnen angegebene E-Mail-Adresse.",
+      errorsHeading: "Bitte korrigieren Sie Ihre Angaben",
+      errorName: "Bitte geben Sie Ihren Namen an.",
+      errorEmail: "Bitte geben Sie eine gültige E-Mail-Adresse an.",
+      errorReason: "Bei einer außerordentlichen Kündigung ist eine Begründung nötig.",
+      errorChoice: "Bitte wählen Sie eine Erklärung und die Art der Kündigung.",
+      errorGeneric:
+        "Ihre Erklärung konnte nicht verarbeitet werden. Bitte versuchen Sie es erneut.",
+      rateLimitedTitle: "Zu viele Anfragen",
+      rateLimitedBody:
+        "Von Ihrer Adresse kamen zu viele Anfragen. Bitte versuchen Sie es später erneut.",
+    },
+  },
+  en: {
+    declarationTypeLabel: { termination: "Termination", withdrawal: "Withdrawal" },
+    terminationKindLabel: {
+      ordinary: "Ordinary, at the earliest possible date",
+      extraordinary: "Extraordinary (for good cause)",
+    },
+    declarationType: "Declaration",
+    terminationKind: "Kind of termination",
+    receivedAt: "Received on",
+    requestId: "Reference number",
+    name: "Name",
+    email: "Email",
+    customerReference: "Customer number / reference",
+    reasonFieldLabel: "Reason",
+    receiptSubject: {
+      termination: "Receipt for your termination",
+      withdrawal: "Receipt for your withdrawal",
+    },
+    receiptIntro:
+      "we confirm receipt of your declaration with the following content. This email is a receipt, not a confirmation that the declaration is effective.",
+    receiptNextSteps:
+      "We will review your declaration and get back to you once it is processed or if we have questions.",
+    receiptRevoke: (operatorEmail) =>
+      `If you did not make this declaration or want to take it back, please write to ${operatorEmail} right away.`,
+    contact: "Questions go to",
+    operatorSubject: {
+      termination: "Termination: action needed",
+      withdrawal: "Withdrawal: action needed",
+    },
+    operatorIntro: "A declaration arrived that needs your attention.",
+    operatorReasons: {
+      unmatched: "No contract matches the entered email",
+      ambiguous: "The entered email matches several contracts",
+      withdrawal: "Withdrawal (recorded only, no provider call from the public form)",
+      extraordinary: "Extraordinary termination, review the reason",
+      provider_cannot_cancel: "The payment provider does not support cancelling through its API",
+      provider_error: "Cancelling at the payment provider failed",
+      no_active_subscription: "No running subscription at the provider",
+      recording_failed: "The declaration could not be stored",
+    },
+    noticeReasons: "Reason for this notice",
+    channel: "Channel",
+    channelLabel: { public: "Public form", account: "Customer account" },
+    tenant: "Tenant",
+    providerResult: "Cancellation at the provider",
+    providerResultLabel: {
+      "period-end": "requested for the end of the billing period",
+      immediately: "requested immediately",
+      none: "not requested",
+    },
+    page: {
+      title: "Terminate or withdraw from your contract",
+      lead: "Use this form to terminate your contract or withdraw from it. You do not need a customer account.",
+      declarationTypeHeading: "What do you want to declare?",
+      kindHeading: "Kind of termination",
+      reasonHint: "Required for an extraordinary termination.",
+      earliestDate: "The termination takes effect at the earliest possible date.",
+      nameLabel: "Name",
+      emailLabel: "Email address of the account",
+      customerReferenceLabel: "Customer number (optional)",
+      reasonLabel: "Reason",
+      reviewButton: "Continue to review",
+      reviewTitle: "Please check your details",
+      reviewLead: "Your declaration is only submitted when you click the button below.",
+      confirmButton: { termination: "Cancel now", withdrawal: "Withdraw now" },
+      backButton: "Change details",
+      resultTitle: "Your declaration was received",
+      resultLead: "We received your declaration and are sending you a receipt.",
+      resultReceivedAt: "Received on",
+      resultRequestId: "Reference number",
+      resultMailNote: "The receipt goes to the email address you entered.",
+      errorsHeading: "Please correct your details",
+      errorName: "Please enter your name.",
+      errorEmail: "Please enter a valid email address.",
+      errorReason: "An extraordinary termination needs a reason.",
+      errorChoice: "Please choose a declaration and the kind of termination.",
+      errorGeneric: "Your declaration could not be processed. Please try again.",
+      rateLimitedTitle: "Too many requests",
+      rateLimitedBody: "Too many requests came from your address. Please try again later.",
+    },
+  },
+};

package/packages/bundled-features/src/billing-foundation/db/queries/payment-projection.ts

@@ -0,0 +1,19 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+// INSERT-once, not UPSERT: unlike subscriptionsProjectionTable (one row per
+// tenant, state overwritten on every event), a payment row is an immutable
+// fact keyed by paymentRowId(tenantId, providerName, providerEventId) — ON
+// CONFLICT DO NOTHING makes a projection rebuild/replay idempotent without
+// ever mutating an existing row.
+export async function insertPaymentProjectionRow(
+  tx: DbRunner,
+  tableName: string,
+  insertCols: Record<string, unknown>,
+): Promise<void> {
+  const insertKeys = Object.keys(insertCols);
+  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
+  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO NOTHING`;
+  // kumiko-lint-ignore raw-sql tableName + column keys are code-controlled, not user input: tableName is buildEntityTable()'s static table name and insertKeys come from applyPaymentReceived's hardcoded object-literal columns in projection.ts — only values flow through $1..$n
+  await asRawClient(tx).unsafe(sqlText, Object.values(insertCols));
+}

package/packages/bundled-features/src/billing-foundation/db/queries/subscription-projection.ts

@@ -0,0 +1,15 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+export async function upsertSubscriptionProjectionRow(
+  tx: DbRunner,
+  tableName: string,
+  insertCols: Record<string, unknown>,
+  setClauses: readonly string[],
+  params: readonly unknown[],
+): Promise<void> {
+  const insertKeys = Object.keys(insertCols);
+  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
+  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO UPDATE SET ${setClauses.join(", ")}`;
+  await asRawClient(tx).unsafe(sqlText, params);
+}

package/packages/bundled-features/src/billing-foundation/entities.ts

@@ -0,0 +1,132 @@
+import { collectPiiSubjectFields } from "@cosmicdrift/kumiko-framework/crypto";
+import {
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+// `subscription` — current state pro Plattform-Tenant (= Read-Model)
+// =============================================================================
+//
+// Inline-Projection-Target. Geschrieben vom `subscription`-projection-
+// apply (siehe feature.ts), NIE direkt vom handler. Source-of-truth ist
+// der event-store stream `subscription` mit aggregate-id =
+// uuidv5(SUBSCRIPTION_NAMESPACE, tenantId).
+//
+// EINE Row pro Plattform-Tenant. Aggregate-ID ist deterministic, damit
+// Webhook-Replays (Stripe sendet bei Hängern bis zu 5x in 4h) auf
+// denselben Stream schreiben statt zwei Rows zu erzeugen.
+//
+// **Felder:**
+//   - providerName: "stripe" / "mollie" — welcher Provider die
+//     Subscription hält. Provider-Wechsel = neuer event auf demselben
+//     Stream, projection überschreibt.
+//   - providerCustomerId / providerSubscriptionId: provider-eigene
+//     IDs.
+//   - status: active / past_due / canceled / trialing / incomplete —
+//     normalisiert über provider-grenzen hinweg.
+//   - tier: "free" / "pro" / ... — vom tier-engine konsumiert. Aus
+//     price-to-tier-Map resolved im Plugin.
+//   - currentPeriodEnd: wann läuft die aktuelle Billing-Period aus.
+//   - cancelAt: when a scheduled cancellation ends the subscription;
+//     nullable because a renewing subscription has none.
+//
+// **Was hier NICHT ist:**
+//   - invoice-history, payment-method, line-items, tax-info → all das
+//     fetcht der Tenant via customer-portal-session direkt vom Provider.
+//
+// **Audit/event-history:** lebt im event-store unter dem `subscription`-
+// stream — KEIN eigene `subscription-event`-Tabelle mehr (= ES ist die
+// audit-truth, replay-fähig durch upcasters).
+export const subscriptionEntity = createEntity({
+  table: "read_subscriptions",
+  fields: {
+    providerName: createTextField({
+      required: true,
+      maxLength: 50,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    // `personal: "tenant"` (not `encrypted`): the field must crypto-shred when
+    // eraseSubjectKeys erases the tenant's subject key on tenant-destroy
+    // (#800). `encrypted: true` uses the app-wide master key instead — that
+    // key is never erased per-tenant, so it would only add encryption-at-
+    // rest, not the erasure guarantee #800 actually asks for.
+    // maxLength 1000, not 200: the stored value is PII-ciphertext
+    // (`kumiko-pii:v1:<subject>:<blob>`), not the raw provider id — a
+    // 200-char plaintext id becomes ~300+ chars of ciphertext. Matches
+    // subscriptionEventPayloadSchema in events.ts.
+    providerCustomerId: createTextField({
+      required: true,
+      maxLength: 1000,
+      personal: "tenant",
+      find: "none",
+    }),
+    providerSubscriptionId: createTextField({
+      required: true,
+      maxLength: 1000,
+      personal: "tenant",
+      find: "none",
+    }),
+    status: createTextField({
+      required: true,
+      maxLength: 30,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    tier: createTextField({
+      required: true,
+      maxLength: 50,
+      personal: false,
+      reason: "catalog_label",
+    }),
+    currentPeriodEnd: createTimestampField({ required: true }),
+    cancelAt: createTimestampField({ required: false }),
+  },
+});
+
+// No executor manages this table (raw r.projection, see feature.ts) — the
+// process-event write-handler and every read site must encrypt/decrypt
+// these fields manually via the PII-subject-KMS path (same mechanism
+// eraseSubjectKeys erases). Single source of truth so a future third
+// `tenantOwned`/`pii`/`userOwned` field doesn't need a matching manual
+// update at each call site.
+export const SUBSCRIPTION_PII_FIELDS = collectPiiSubjectFields(subscriptionEntity);
+
+// =============================================================================
+// `payment` — one row per one-off-payment (= read-model)
+// =============================================================================
+//
+// Inline-Projection-Target for the payment-received event (see feature.ts).
+// Unlike subscriptionEntity (one row per tenant, UPSERTed), a tenant can have
+// many payments — one INSERT-once row per event, PK = paymentRowId(...) (see
+// projection.ts / aggregate-id.ts). Source-of-truth is the event-store stream `payment` with
+// aggregate-id = paymentAggregateId(tenantId) — one stream per tenant
+// collecting all of that tenant's payment-received events.
+export const paymentEntity = createEntity({
+  table: "read_payments",
+  fields: {
+    providerName: createTextField({
+      required: true,
+      maxLength: 50,
+      personal: false,
+      reason: "technical_reference",
+    }),
+    // Same `personal: "tenant"` rationale as subscriptionEntity above —
+    // crypto-shreds on tenant-destroy (#800) via eraseSubjectKeys.
+    providerCustomerId: createTextField({
+      required: true,
+      maxLength: 1000,
+      personal: "tenant",
+      find: "none",
+    }),
+    priceId: createTextField({
+      required: true,
+      maxLength: 200,
+      personal: false,
+      reason: "technical_reference",
+    }),
+  },
+});
+
+// See the SUBSCRIPTION_PII_FIELDS comment above — same manual-wiring reason.
+export const PAYMENT_PII_FIELDS = collectPiiSubjectFields(paymentEntity);

package/packages/bundled-features/src/billing-foundation/events.ts

@@ -0,0 +1,215 @@
+// Domain-events für subscription-foundation.
+//
+// **Pattern:** event-sourced — jeder Provider-Webhook (nach Plugin-
+// verify) wird zu einem domain-event auf dem subscription-stream
+// (= ein stream pro Tenant via subscriptionAggregateId(tenantId)).
+// Read-model = inline projection in `subscriptions`-Tabelle.
+//
+// 5 fine-grained event-typen statt einem generic "webhook-received"-
+// bucket — events sind business-facts: future-consumer (billing-history,
+// accounting-export, churn-analytics) listenen direkt auf den event-
+// type ohne payload-discriminator.
+
+import * as z from "zod";
+import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./constants.js";
+
+// Aggregate-type für den event-store. Eine subscription pro Tenant ist
+// ein stream; der subscriptionAggregateId-helper liefert die stream-id.
+export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription" as const;
+
+// Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
+// FQN (für ctx.unsafeAppendEvent + projection-apply-keys).
+export const SUBSCRIPTION_CREATED_EVENT_SHORT = "subscription-created" as const;
+export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated" as const;
+export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled" as const;
+export const INVOICE_PAID_EVENT_SHORT = "invoice-paid" as const;
+export const INVOICE_PAYMENT_FAILED_EVENT_SHORT = "invoice-payment-failed" as const;
+
+export const SUBSCRIPTION_CREATED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_CREATED_EVENT_SHORT}` as const;
+export const SUBSCRIPTION_UPDATED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_UPDATED_EVENT_SHORT}` as const;
+export const SUBSCRIPTION_CANCELED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_CANCELED_EVENT_SHORT}` as const;
+export const INVOICE_PAID_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAID_EVENT_SHORT}` as const;
+export const INVOICE_PAYMENT_FAILED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAYMENT_FAILED_EVENT_SHORT}` as const;
+
+// Status-enum für event-payloads (= subscription-state-snapshot vom Provider).
+const statusEnum = z.enum([
+  SubscriptionStatuses.active,
+  SubscriptionStatuses.trialing,
+  SubscriptionStatuses.pastDue,
+  SubscriptionStatuses.canceled,
+  SubscriptionStatuses.incomplete,
+]);
+
+// Common payload — alle 5 events tragen denselben subscription-state-
+// snapshot. Event-type tagged was passiert ist, payload den state-after.
+// The raw provider event is deliberately not stored: it carries plaintext
+// PII and event headers are not crypto-shreddable.
+export const subscriptionEventPayloadSchema = z.object({
+  providerName: z.string().min(1).max(50),
+  // 1000, not 200: these two are `tenantOwned: true` on the entity (see
+  // entities.ts — crypto-shreds on tenant-destroy, unlike `encrypted`).
+  // process-event.write.ts stores the PII-ciphertext here, not the raw
+  // provider id. A 200-char plaintext id becomes ~300+ chars of ciphertext.
+  providerCustomerId: z.string().min(1).max(1000),
+  providerSubscriptionId: z.string().min(1).max(1000),
+  status: statusEnum,
+  tier: z.string().min(1).max(50),
+  currentPeriodEndIso: z.string().min(1),
+  // Optional (not required): existing events (Mollie-style providers, or
+  // events appended before this field existed) stay valid without an
+  // upcaster. null = the subscription renews; undefined = the provider
+  // doesn't report cancelAt at all — projection.ts tells the two apart.
+  cancelAtIso: z.string().min(1).nullable().optional(),
+  consentId: z.string().min(1).max(100).optional(),
+});
+export type SubscriptionEventPayload = z.infer<typeof subscriptionEventPayloadSchema>;
+
+// Headers-shape — wird im event-store als event.metadata.headers
+// persistiert (open-shape jsonb-column, primitives only).
+// Idempotency-anchor: providerEventId pro provider, foundation checked
+// vor append ob bereits gesehen.
+export type SubscriptionEventHeaders = {
+  readonly providerEventId: string;
+  readonly providerName: string;
+};
+
+// =============================================================================
+// payment-received — one-off-payments (checkout mode "payment")
+// =============================================================================
+//
+// Own aggregate-type + event, separate from the 5 subscription events above.
+// A one-off-payment is not a subscription-state transition (no status/tier/
+// currentPeriodEnd) — it materializes as its own `read_payments` row (one
+// row per payment) via the payment-aggregate stream (one stream per tenant,
+// see aggregate-id.ts).
+
+export const PAYMENT_AGGREGATE_TYPE = "payment" as const;
+
+export const PAYMENT_RECEIVED_EVENT_SHORT = "payment-received" as const;
+export const PAYMENT_RECEIVED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${PAYMENT_RECEIVED_EVENT_SHORT}` as const;
+
+export const paymentEventPayloadSchema = z.object({
+  providerName: z.string().min(1).max(50),
+  // 1000, not 200: `tenantOwned: true` on paymentEntity (see entities.ts) —
+  // this stores the PII-ciphertext, not the raw provider id. Mirrors
+  // subscriptionEventPayloadSchema's same rationale.
+  providerCustomerId: z.string().min(1).max(1000),
+  priceId: z.string().min(1).max(200),
+  consentId: z.string().min(1).max(100).optional(),
+});
+export type PaymentEventPayload = z.infer<typeof paymentEventPayloadSchema>;
+
+export type PaymentEventHeaders = {
+  readonly providerEventId: string;
+  readonly providerName: string;
+  readonly providerCheckoutId?: string;
+};
+
+// =============================================================================
+// checkout-consent-recorded — consumer-protection consent
+// =============================================================================
+//
+// Appended onto the subscription- or payment-stream (by checkout mode) after
+// the provider handed out the checkout URL. No projection applies it. Carries
+// no email or IP: the consenting user is identified by `actorUserId` only.
+
+export const CHECKOUT_CONSENT_RECORDED_EVENT_SHORT = "checkout-consent-recorded" as const;
+export const CHECKOUT_CONSENT_RECORDED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${CHECKOUT_CONSENT_RECORDED_EVENT_SHORT}` as const;
+
+export const checkoutConsentRecordedPayloadSchema = z.object({
+  consentId: z.string().min(1).max(100),
+  mode: z.enum(["subscription", "payment"]),
+  tier: z.string().min(1).max(50).nullable(),
+  priceId: z.string().min(1).max(200),
+  unitAmount: z.number().nullable(),
+  currency: z.string().nullable(),
+  interval: z.string().nullable(),
+  intervalCount: z.number().nullable(),
+  consentTextVersion: z.string().min(1).max(64),
+  termsHash: z.string().length(64),
+  termsTemplateVersion: z.number(),
+  locale: z.string().min(2).max(35),
+  actorUserId: z.string().min(1),
+});
+export type CheckoutConsentRecordedPayload = z.infer<typeof checkoutConsentRecordedPayloadSchema>;
+
+// =============================================================================
+// contract-confirmation-issued — § 312f confirmation mail sent
+// =============================================================================
+//
+// Appended onto the stream that carries the consent, BEFORE the mail is
+// handed to delivery: the append is the optimistic-concurrency guard that
+// keeps a concurrent or replayed run from sending a second mail.
+
+export const CONTRACT_CONFIRMATION_ISSUED_EVENT_SHORT = "contract-confirmation-issued" as const;
+export const CONTRACT_CONFIRMATION_ISSUED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_CONFIRMATION_ISSUED_EVENT_SHORT}` as const;
+
+export const contractConfirmationIssuedPayloadSchema = z.object({
+  consentId: z.string().min(1).max(100),
+  issuedAtIso: z.string().min(1),
+  locale: z.string().min(2).max(35),
+  termsTemplateVersion: z.number(),
+});
+export type ContractConfirmationIssuedPayload = z.infer<
+  typeof contractConfirmationIssuedPayloadSchema
+>;
+
+// =============================================================================
+// contract-termination-requested / -unmatched — § 312k cancellation
+// =============================================================================
+//
+// Payloads carry no name, email or reason: those only travel in the mails.
+// `requested` goes onto the tenant's subscription stream; `unmatched` onto a
+// system-tenant stream of its own, keyed by the request id.
+
+export const CONTRACT_TERMINATION_DECLARATION_TYPES = ["termination", "withdrawal"] as const;
+export type ContractTerminationDeclarationType =
+  (typeof CONTRACT_TERMINATION_DECLARATION_TYPES)[number];
+export const CONTRACT_TERMINATION_KINDS = ["ordinary", "extraordinary"] as const;
+export type ContractTerminationKind = (typeof CONTRACT_TERMINATION_KINDS)[number];
+export const CONTRACT_TERMINATION_CHANNELS = ["public", "account"] as const;
+export const PROVIDER_CANCEL_OUTCOMES = ["period-end", "immediately", "none"] as const;
+export type ProviderCancelOutcome = (typeof PROVIDER_CANCEL_OUTCOMES)[number];
+
+export const CONTRACT_TERMINATION_REQUESTED_EVENT_SHORT = "contract-termination-requested" as const;
+export const CONTRACT_TERMINATION_REQUESTED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_REQUESTED_EVENT_SHORT}` as const;
+
+export const contractTerminationRequestedPayloadSchema = 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),
+  receivedAtIso: z.string().min(1),
+  effectiveAtIso: z.string().min(1).nullable(),
+  providerCancel: z.enum(PROVIDER_CANCEL_OUTCOMES),
+});
+export type ContractTerminationRequestedPayload = z.infer<
+  typeof contractTerminationRequestedPayloadSchema
+>;
+
+export const CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE =
+  "contract-termination-unmatched" as const;
+export const CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT = "contract-termination-unmatched" as const;
+export const CONTRACT_TERMINATION_UNMATCHED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${CONTRACT_TERMINATION_UNMATCHED_EVENT_SHORT}` as const;
+
+export const contractTerminationUnmatchedPayloadSchema = z.object({
+  requestId: z.string().min(1).max(100),
+  declarationType: z.enum(CONTRACT_TERMINATION_DECLARATION_TYPES),
+  terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
+  channel: z.literal("public"),
+  receivedAtIso: z.string().min(1),
+  matchResult: z.enum(["none", "ambiguous"]),
+});
+export type ContractTerminationUnmatchedPayload = z.infer<
+  typeof contractTerminationUnmatchedPayloadSchema
+>;