@cosmicdrift/kumiko-samples 0.338.0

package/packages/bundled-features/src/subscription-mollie/feature.ts

@@ -0,0 +1,169 @@
+// kumiko-feature-version: 1
+//
+// subscription-mollie — Mollie-Plugin für die subscription-foundation
+// Plugin-API (EU-Compliance-Story für DACH-Mid-Market).
+//
+// **Factory-Pattern (analog subscription-stripe):** liest API-key beim
+// mount-time aus den factory-options (typisch process.env aus dem App-
+// Builder-bin/server.ts). Mollie hat KEIN webhook-secret — Mollie-SDK
+// 4.5.0 bietet keine native HMAC-sig-verify-API. Sicherheit kommt aus
+// nicht-guessable IDs + API-Validation; App-Builder kann optional
+// einen URL-Token-Wrapper davor schalten.
+//
+// **Phase-5.3-Scope:**
+//   - verifyAndParseWebhook ✓ (lazy-fetch payment + subscription via
+//     Mollie-API, heuristisches event-type-mapping)
+//   - createCheckoutSession ✓ (Mollie's mehrstufiger flow: customer
+//     anlegen + first-payment mit sequenceType="first" → redirectUrl)
+//   - createPortalSession ✗ (Mollie hat keinen Customer-Portal)
+//   - cancelSubscription ✗ (Mollie braucht customerId zusätzlich zur
+//     subId; Plugin-Contract reicht's nicht durch — App-Builder cancelt
+//     via Mollie-Dashboard oder custom-route)
+//
+// **Beispiel-Verwendung in run-config.ts:**
+//
+//   const features = [
+//     billingFoundationFeature,
+//     createSubscriptionMollieFeature({
+//       apiKey: process.env.MOLLIE_API_KEY ?? "",
+//       webhookUrl: "https://app.example.com/api/subscription/webhook/mollie",
+//       priceToTier: { plan_pro: "pro", plan_business: "business" },
+//       priceToConfig: {
+//         plan_pro: {
+//           amountValue: "9.99",
+//           amountCurrency: "EUR",
+//           interval: "1 month",
+//           description: "Pro-Abo monatlich",
+//         },
+//       },
+//     }),
+//   ];
+
+import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { createMollieClient } from "@mollie/api-client";
+import * as z from "zod";
+import { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "./constants.js";
+import { createMollieCheckoutSession, type MolliePriceConfig } from "./plugin-methods.js";
+import { type MollieClientShape, verifyAndParseMollieWebhook } from "./verify-webhook.js";
+
+/**
+ * Env-vars contract for the `subscription-mollie` feature.
+ * Apps load `MOLLIE_API_KEY` from env and forward it to
+ * `createSubscriptionMollieFeature({ apiKey, ... })`.
+ */
+export const subscriptionMollieEnvSchema = z.object({
+  MOLLIE_API_KEY: z
+    .string()
+    .min(1, "MOLLIE_API_KEY must not be empty")
+    .regex(/^(test|live)_/, "MOLLIE_API_KEY must start with 'test_' or 'live_'")
+    .describe("Mollie API key (`test_...` for sandbox, `live_...` for production).")
+    .meta({ kumiko: { pulumi: { secret: true } } }),
+});
+
+export type SubscriptionMollieOptions = {
+  /** Mollie-API-key (`test_...` oder `live_...`). App-wide, beim Plugin-
+   *  mount aus process.env oder system-config. */
+  readonly apiKey: string;
+  /** Foundation-webhook-URL die der App-Builder unter Mollie-Dashboard
+   *  als webhook eingetragen hat. Plugin reicht das beim payment-
+   *  create an Mollie weiter — Mollie sendet beim payment-event
+   *  webhooks an diese URL. Typisch:
+   *  `https://app.example.com/api/subscription/webhook/mollie`. */
+  readonly webhookUrl: string;
+  /** Price-to-tier-Map. Plugin liest die priceId aus dem subscription-
+   *  metadata (= `metadata.priceId` den der App-Builder beim
+   *  createCheckoutSession setzt) und mappt auf einen tier-name. */
+  readonly priceToTier: Readonly<Record<string, string>>;
+  /** Mollie-Subscription-Setup pro priceId. Mollie hat keinen nativen
+   *  price-id-Konzept — App-Builder muss pro virtuellem priceId einen
+   *  amount/interval/description bereitstellen. */
+  readonly priceToConfig: Readonly<Record<string, MolliePriceConfig>>;
+  /** @internal Test-only injection-port: ersetzt den verify-webhook-
+   *  fetch-client durch eine Mock-instance. Production left undefined —
+   *  factory baut den Adapter aus `createMollieClient(apiKey)`. Wird
+   *  vom IT (mollie-foundation.integration.ts) genutzt damit der echte
+   *  factory-Code (drift-validation, plugin-registration) im Test-pfad
+   *  durchläuft, ohne dass Mollie-API-Calls passieren. */
+  readonly _clientShapeForTests?: MollieClientShape;
+};
+
+export function createSubscriptionMollieFeature(
+  options: SubscriptionMollieOptions,
+): FeatureDefinition {
+  if (options.apiKey.length === 0) {
+    throw new Error(
+      "subscription-mollie: apiKey is empty. Set MOLLIE_API_KEY (or system-config) before mounting.",
+    );
+  }
+  if (options.webhookUrl.length === 0) {
+    throw new Error(
+      "subscription-mollie: webhookUrl is empty. Set the foundation-webhook-URL where Mollie sends events.",
+    );
+  }
+
+  // Drift-Guard: priceToTier + priceToConfig müssen identische Keys
+  // haben — sonst silent-null-returns aus verifyAndParseWebhook.
+  const tierKeys = new Set(Object.keys(options.priceToTier));
+  const configKeys = new Set(Object.keys(options.priceToConfig));
+  const missingInConfig = [...tierKeys].filter((k) => !configKeys.has(k));
+  const missingInTier = [...configKeys].filter((k) => !tierKeys.has(k));
+  if (missingInConfig.length > 0 || missingInTier.length > 0) {
+    throw new Error(
+      `subscription-mollie: priceToTier ↔ priceToConfig drift — ` +
+        `priceIds in tier but missing config: [${missingInConfig.join(", ")}]; ` +
+        `priceIds in config but missing tier: [${missingInTier.join(", ")}]`,
+    );
+  }
+
+  const client = createMollieClient({ apiKey: options.apiKey });
+
+  // Adapter um den Plugin's verify-fetch-client an den vollen Mollie-
+  // Client zu binden. Plugin-fetch-API ist minimal damit Tests ohne
+  // den vollen MollieClient mocken können.
+  const fetchAdapter: MollieClientShape = options._clientShapeForTests ?? {
+    payments: { get: (id: string) => client.payments.get(id) },
+    customerSubscriptions: {
+      get: (subId: string, customerId: string) =>
+        client.customerSubscriptions.get(subId, { customerId }),
+      list: async (customerId: string) => {
+        const page = await client.customerSubscriptions.page({ customerId });
+        return [...page];
+      },
+      create: (customerId, params) =>
+        client.customerSubscriptions.create({ customerId, ...params }),
+    },
+  };
+
+  const verifyAndParse = verifyAndParseMollieWebhook(fetchAdapter, {
+    priceToTier: options.priceToTier,
+    priceToConfig: options.priceToConfig,
+  });
+  const checkoutSession = createMollieCheckoutSession(
+    client,
+    options.priceToConfig,
+    options.webhookUrl,
+  );
+
+  return defineFeature(SUBSCRIPTION_MOLLIE_FEATURE, (r) => {
+    r.describe(
+      'Mollie payment provider plugin for `billing-foundation`, covering the DACH/EU mid-market use case. Mount via `createSubscriptionMollieFeature({ apiKey, webhookUrl, priceToTier, priceToConfig })` \u2014 the factory validates that `priceToTier` and `priceToConfig` keys are identical at boot time. Implements `verifyAndParseWebhook` (lazy Mollie-API fetch + heuristic event-type mapping) and `createCheckoutSession` (customer + first-payment with `sequenceType="first"`); `createPortalSession` and `cancelSubscription` are not available because Mollie has no customer portal and requires a `customerId` that the plugin contract does not carry.',
+    );
+    r.uiHints({
+      displayLabel: "Billing \u00b7 Mollie",
+      category: "billing",
+      recommended: false,
+    });
+    r.requires("billing-foundation");
+    r.envSchema(subscriptionMollieEnvSchema);
+
+    const plugin: SubscriptionProviderPlugin = {
+      verifyAndParseWebhook: verifyAndParse,
+      createCheckoutSession: checkoutSession,
+      // createPortalSession + cancelSubscription bewusst nicht — siehe
+      // plugin-methods.ts für Begründung.
+      priceToTier: options.priceToTier,
+    };
+    r.useExtension("subscriptionProvider", MOLLIE_PROVIDER_NAME, plugin);
+  });
+}

package/packages/bundled-features/src/subscription-mollie/index.ts

@@ -0,0 +1,14 @@
+// Public API of the subscription-mollie bundled-feature.
+//
+// **Internal-only** (NICHT im public-barrel — App-Builder nutzt das nie direkt):
+//   - verifyAndParseMollieWebhook (intern vom feature.ts factory aufgerufen)
+//   - mapMollieEventType / mapMollieStatus / extractMollieId (pure helpers,
+//     test-only — direct-import aus dem File wenn echt mal extern gebraucht)
+
+export { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "./constants.js";
+export {
+  createSubscriptionMollieFeature,
+  type SubscriptionMollieOptions,
+  subscriptionMollieEnvSchema,
+} from "./feature.js";
+export type { MolliePriceConfig } from "./plugin-methods.js";

package/packages/bundled-features/src/subscription-mollie/plugin-methods.ts

@@ -0,0 +1,97 @@
+// Mollie-Plugin-Methoden für die POST-tenant-resolution-Phase:
+// createCheckoutSession (only). createPortalSession + cancelSubscription
+// nicht implementiert weil Mollie's API die Patterns nicht 1:1 bietet:
+//
+// - **Portal:** Mollie hat keinen Customer-Portal — App-Builder UI muss
+//   das selbst rendern.
+// - **Cancel:** Mollie braucht (customerId, subId), Plugin-Contract
+//   reicht aber nur subId durch — App-Builder cancelt via Mollie-
+//   Dashboard oder eigener Route bis Foundation-Contract erweitert ist.
+//
+// **Mollie-Checkout-Flow ist mehrstufig:** Customer anlegen → first-
+// payment mit sequenceType="first" (= Mandate-setup) → User bezahlt →
+// Mollie-webhook → verify-webhook erstellt die Mollie-Subscription
+// idempotent (siehe verify-webhook.ts ensureSubscriptionForMandate).
+
+import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { MollieClient, Payment } from "@mollie/api-client";
+import { SequenceType } from "@mollie/api-client";
+
+export type MollieCheckoutOptions = Parameters<
+  NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
+>[1];
+
+/** Mollie hat keinen nativen price-id-Konzept — App-Builder pflegt
+ *  pro virtuellem priceId einen amount/interval/description. */
+export type MolliePriceConfig = {
+  /** Mollie-format: 2-decimal string, z.B. `"9.99"`. */
+  readonly amountValue: string;
+  readonly amountCurrency: string;
+  /** Mollie-format: `1 month` / `1 year` / `14 days`. Required for
+   *  subscription prices; omit for one-off prices (`mode: "payment"`). */
+  readonly interval?: string;
+  readonly description: string;
+};
+
+export function createMollieCheckoutSession(
+  client: MollieClient,
+  priceToConfig: Readonly<Record<string, MolliePriceConfig>>,
+  appWebhookUrl: string,
+) {
+  return async (_ctx: HandlerContext, options: MollieCheckoutOptions): Promise<{ url: string }> => {
+    const priceCfg = priceToConfig[options.priceId];
+    if (!priceCfg) {
+      throw new Error(`subscription-mollie: priceId "${options.priceId}" not in priceToConfig-Map`);
+    }
+
+    // A first payment without an interval would set up a mandate that
+    // verify-webhook can't turn into a subscription — fail before charging.
+    if (options.mode !== "payment" && !priceCfg.interval) {
+      throw new Error(
+        `subscription-mollie: priceId "${options.priceId}" has no interval but is booked as a subscription (mode is not "payment")`,
+      );
+    }
+
+    let customerId = options.providerCustomerId;
+    if (!customerId) {
+      const customer = await client.customers.create({
+        metadata: { tenantId: options.tenantId },
+      });
+      customerId = customer.id;
+    }
+
+    // mode "payment" (one-off top-up) → sequenceType.oneoff, no mandate
+    // setup. Oneoff payments carry no subscriptionId and are not
+    // sequenceType "first", so verifyAndParseMollieWebhook drops them before
+    // any mandate/subscription handling.
+    const sequenceType = options.mode === "payment" ? SequenceType.oneoff : SequenceType.first;
+
+    // payments.create ist overloaded (Promise OR void mit callback);
+    // explicit cast auf Promise<Payment>-overload.
+    const payment = (await (client.payments.create({
+      amount: { currency: priceCfg.amountCurrency, value: priceCfg.amountValue },
+      description: priceCfg.description,
+      sequenceType,
+      customerId,
+      redirectUrl: options.successUrl,
+      cancelUrl: options.cancelUrl,
+      webhookUrl: appWebhookUrl,
+      metadata: {
+        tenantId: options.tenantId,
+        priceId: options.priceId,
+        ...(options.consentId && { consentId: options.consentId }),
+      },
+    }) as Promise<Payment>)) satisfies Payment; // @cast-boundary engine-bridge
+
+    const checkoutHref = payment.getCheckoutUrl();
+    if (!checkoutHref) {
+      const mandateHint =
+        sequenceType === SequenceType.first ? " — first-payment-mandates ggf. nicht aktiviert" : "";
+      throw new Error(
+        `subscription-mollie: payment.getCheckoutUrl() returned null (sequenceType=${sequenceType})${mandateHint}`,
+      );
+    }
+    return { url: checkoutHref };
+  };
+}

package/packages/bundled-features/src/subscription-mollie/verify-webhook.ts

@@ -0,0 +1,259 @@
+// verifyAndParseMollieWebhook — Mollie-spezifische lazy-fetch +
+// event-type-Heuristik. Wird vom Plugin-Build (feature.ts) als
+// `verifyAndParseWebhook` registriert.
+//
+// Mollie's classic-webhook sendet nur eine `id` (form-urlencoded oder
+// JSON). Wir lazy-fetchen payment + subscription via Mollie-API. Sub-
+// xxx-events werden NICHT supported — App-Builder bekommt sie indirekt
+// via tr_xxx-payment-events (Mollie sendet beide parallel bei normalen
+// Lifecycle-Events).
+//
+// **Mandate-setup-flow:** first-payment-paid kommt mit
+// `payment.subscriptionId === null` (Mollie's Pattern: App-Builder
+// muss `customerSubscriptions.create` selbst aufrufen). Wir machen
+// das im Plugin (idempotent via list-check), damit Foundation einen
+// Created-Event mit subscription-id bekommt.
+
+import {
+  parseProviderConsentId,
+  type SubscriptionEvent,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import type {
+  Payment as MolliePayment,
+  Subscription as MollieSubscription,
+} from "@mollie/api-client";
+import { Temporal } from "temporal-polyfill";
+import { MOLLIE_PROVIDER_NAME } from "./constants.js";
+import type { MolliePriceConfig } from "./plugin-methods.js";
+
+const log = createFallbackLogger("subscription-mollie");
+
+/** Minimal-Subset des Mollie-Clients, das der Plugin nutzt — separat
+ *  damit Tests ohne den vollen MollieClient mocken können. Adapter in
+ *  feature.ts bridged das gegen den echten SDK. */
+export type MollieClientShape = {
+  readonly payments: { readonly get: (id: string) => Promise<MolliePayment> };
+  readonly customerSubscriptions: {
+    readonly get: (subId: string, customerId: string) => Promise<MollieSubscription>;
+    readonly list: (customerId: string) => Promise<readonly MollieSubscription[]>;
+    readonly create: (
+      customerId: string,
+      params: {
+        amount: { currency: string; value: string };
+        interval: string;
+        description: string;
+        metadata: Record<string, string>;
+      },
+    ) => Promise<MollieSubscription>;
+  };
+};
+
+export type MollieWebhookOptions = {
+  /** priceId (= virtueller Schlüssel aus subscription.metadata) → tier-name. */
+  readonly priceToTier: Readonly<Record<string, string>>;
+  /** priceId → amount/interval/description. Wird beim mandate-setup-
+   *  flow zum `customerSubscriptions.create`-Call gebraucht. App-
+   *  Builder pflegt die Map einmal in den factory-options. */
+  readonly priceToConfig: Readonly<Record<string, MolliePriceConfig>>;
+};
+
+export function verifyAndParseMollieWebhook(
+  client: MollieClientShape,
+  options: MollieWebhookOptions,
+): (rawBody: string, headers: Record<string, string>) => Promise<SubscriptionEvent | null> {
+  return async (rawBody, headers) => {
+    const id = extractMollieId(rawBody, headers);
+    if (!id) {
+      throw new Error("subscription-mollie: webhook body has no `id` field");
+    }
+
+    let subscription: MollieSubscription | null = null;
+    let triggerPayment: MolliePayment | null = null;
+
+    if (id.startsWith("tr_")) {
+      let payment: MolliePayment;
+      try {
+        payment = await client.payments.get(id);
+      } catch {
+        // Garbage-id → Mollie 404 → Foundation 200 ignored.
+        return null;
+      }
+      triggerPayment = payment;
+      const customerId = payment.customerId;
+      if (!customerId) return null;
+
+      if (payment.subscriptionId) {
+        try {
+          subscription = await client.customerSubscriptions.get(payment.subscriptionId, customerId);
+        } catch {
+          return null;
+        }
+      } else if (payment.sequenceType === "first" && payment.status === "paid") {
+        subscription = await ensureSubscriptionForMandate(client, options, payment);
+        if (!subscription) return null;
+      } else {
+        // One-shot oder first-payment-failed → nicht unsere Domain.
+        return null;
+      }
+    } else if (id.startsWith("sub_")) {
+      // sub_xxx-events kommen indirekt via parallele tr_xxx-events.
+      return null;
+    } else {
+      return null;
+    }
+
+    const metadata = (subscription.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
+    const tenantId = metadata["tenantId"];
+    if (!tenantId || tenantId.length === 0) return null;
+    const priceId = metadata["priceId"];
+    if (!priceId) return null;
+    const tier = options.priceToTier[priceId];
+    if (!tier) return null;
+
+    const type = mapMollieEventType(subscription, triggerPayment);
+    if (!type) return null;
+
+    const status = mapMollieStatus(subscription.status);
+    const periodEndSource = subscription.nextPaymentDate ?? subscription.startDate;
+    if (!periodEndSource) {
+      // Mollie-API-Drift: valid Subs haben mindestens startDate. Loud-
+      // fail damit App-Owner's monitoring den drift sieht.
+      throw new Error(
+        `subscription-mollie: subscription ${subscription.id} has neither nextPaymentDate nor startDate`,
+      );
+    }
+    const currentPeriodEnd = mollieDateStringToInstantIso(periodEndSource);
+
+    const consentId = parseProviderConsentId(metadata["consentId"]);
+    return {
+      providerEventId: id,
+      providerName: MOLLIE_PROVIDER_NAME,
+      type,
+      tenantId,
+      ...(consentId !== undefined && { consentId }),
+      providerCustomerId: subscription.customerId,
+      providerSubscriptionId: subscription.id,
+      status,
+      tier,
+      currentPeriodEnd,
+    };
+  };
+}
+
+// =============================================================================
+// Mandate-setup: subscription on-the-fly erstellen
+// =============================================================================
+
+/** first-payment-paid OHNE subscriptionId → Mollie-Sub erstellen.
+ *  Idempotent via list-check (replay-safe). Returns null bei
+ *  unvollständiger metadata oder unbekanntem priceId. */
+async function ensureSubscriptionForMandate(
+  client: MollieClientShape,
+  options: MollieWebhookOptions,
+  payment: MolliePayment,
+): Promise<MollieSubscription | null> {
+  const customerId = payment.customerId;
+  if (!customerId) return null;
+  const paymentMetadata = (payment.metadata as Record<string, string> | null) ?? {}; // @cast-boundary engine-bridge
+  const tenantId = paymentMetadata["tenantId"];
+  const priceId = paymentMetadata["priceId"];
+  const consentId = parseProviderConsentId(paymentMetadata["consentId"]);
+  if (!tenantId || !priceId) return null;
+  const priceCfg = options.priceToConfig[priceId];
+  if (!priceCfg) return null;
+  if (!priceCfg.interval) {
+    log.warn("price has no interval, no subscription created", { priceId });
+    return null;
+  }
+
+  const existing = await client.customerSubscriptions.list(customerId);
+  const matchingExisting = existing.find(
+    (sub) =>
+      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId && // @cast-boundary engine-bridge
+      (sub.status === "active" || sub.status === "pending"),
+  );
+  if (matchingExisting) return matchingExisting;
+
+  return await client.customerSubscriptions.create(customerId, {
+    amount: { currency: priceCfg.amountCurrency, value: priceCfg.amountValue },
+    interval: priceCfg.interval,
+    description: priceCfg.description,
+    metadata: { tenantId, priceId, ...(consentId && { consentId }) },
+  });
+}
+
+// =============================================================================
+// Helpers (exported für Tests)
+// =============================================================================
+
+/** Extract `id` aus rawBody — handelt form-urlencoded + JSON. */
+export function extractMollieId(rawBody: string, headers: Record<string, string>): string | null {
+  const contentType = headers["content-type"] ?? "";
+  if (contentType.includes("application/json")) {
+    try {
+      const parsed: unknown = JSON.parse(rawBody);
+      const id =
+        typeof parsed === "object" && parsed !== null && "id" in parsed
+          ? (parsed as Record<string, unknown>)["id"] // @cast-boundary engine-payload
+          : undefined;
+      return typeof id === "string" ? id : null;
+    } catch {
+      return null;
+    }
+  }
+  const params = new URLSearchParams(rawBody);
+  return params.get("id");
+}
+
+/** Mollie-subscription + optional payment → SubscriptionEventType.
+ *  Heuristik (Mollie hat keine explicit-typed events). */
+export function mapMollieEventType(
+  subscription: MollieSubscription,
+  triggerPayment: MolliePayment | null,
+): SubscriptionEventType | null {
+  if (subscription.status === "canceled" || subscription.status === "completed") {
+    return SubscriptionEventTypes.canceled;
+  }
+
+  if (triggerPayment) {
+    const seq = triggerPayment.sequenceType;
+    const paid = triggerPayment.status === "paid";
+    const failed = triggerPayment.status === "failed" || triggerPayment.status === "expired";
+    if (seq === "first" && paid) return SubscriptionEventTypes.created;
+    if (seq === "recurring" && paid) return SubscriptionEventTypes.invoicePaid;
+    if (seq === "recurring" && failed) return SubscriptionEventTypes.invoicePaymentFailed;
+  }
+
+  if (subscription.status === "active") return SubscriptionEventTypes.updated;
+  return null;
+}
+
+/** Mollie-status → normalized. */
+export function mapMollieStatus(mollieStatus: MollieSubscription["status"]): SubscriptionStatus {
+  switch (mollieStatus) {
+    case "active":
+      return SubscriptionStatuses.active;
+    case "canceled":
+    case "completed":
+      // completed = alle `times`-charges durchgelaufen → wie canceled.
+      return SubscriptionStatuses.canceled;
+    case "suspended":
+      // Mandate ungültig / payment-method failed → grace-period.
+      return SubscriptionStatuses.pastDue;
+    case "pending":
+      return SubscriptionStatuses.incomplete;
+    default:
+      return SubscriptionStatuses.incomplete;
+  }
+}
+
+/** Mollie liefert dates als YYYY-MM-DD; foundation will ISO-Instant.
+ *  Throws bei malformed input (= Mollie-API-Drift, soll loud-fail). */
+function mollieDateStringToInstantIso(dateString: string): string {
+  return Temporal.Instant.from(`${dateString.slice(0, 10)}T00:00:00Z`).toString();
+}

package/packages/bundled-features/src/subscription-stripe/changes.json

@@ -0,0 +1,80 @@
+[
+  {
+    "version": "0.338.0",
+    "type": "improvement",
+    "title": "Stripe checkout sets submit_type, locale, submit text and consentId; cancel can run to period end",
+    "detail": "Checkout sessions in both modes set `submit_type: \"pay\"`. `locale` maps to a Stripe checkout locale (exact match, else the language part such as `de-AT` to `de`, else `\"auto\"`), and `submitMessage` becomes `custom_text.submit.message` (capped at Stripe's 1200 characters). `consentId` is written to `subscription_data.metadata` or `payment_intent_data.metadata` next to `tenantId` and read back from the same place on the webhook. `cancelSubscription` with `when: \"period-end\"` sets `cancel_at_period_end`; `\"immediately\"` cancels the subscription.",
+    "migration": "No code change needed."
+  },
+  {
+    "version": "0.338.0",
+    "type": "fix",
+    "title": "Stripe webhooks no longer archive the full provider event",
+    "detail": "Subscription and one-off-payment events parsed from Stripe webhooks, and the snapshot returned by sync-subscriptions, no longer include the serialized Stripe event, so customer details never land in the event store."
+  },
+  {
+    "version": "0.337.0",
+    "type": "fix",
+    "title": "plan switch rejects unretrievable prices, concurrent request-deletion loser reports the fresh user status",
+    "detail": "The Stripe plan switch now fails with `price_unavailable` when an allowed price cannot be retrieved, instead of creating an incomplete Stripe portal configuration under a different price-set hash. A concurrent losing `request-deletion` now reports the user's current status in `user_not_in_active_state` instead of the stale `active`."
+  },
+  {
+    "version": "0.336.1",
+    "type": "fix",
+    "title": "Checkout retries without a customer id Stripe no longer knows",
+    "detail": "Stripe checkout now retries once without the customer when the stored customer id is unknown to Stripe (for example after switching from a test to a live account), instead of failing with \"No such customer\"."
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "One-off payment checkouts create a customer when none is passed"
+  },
+  {
+    "version": "0.335.0",
+    "type": "fix",
+    "title": "Stripe unknown price intervals stay consistent, plan-switch errors keep their cause, dropped paid sessions are logged",
+    "detail": "Stripe prices with an interval Stripe added after this release now report `intervalCount: null` alongside `interval: null`, and log one warning per price. A `billingPortal.sessions.create` failure during a plan switch is no longer reported as `plan_tiers_share_product`, so the real Stripe error surfaces; only portal-configuration errors map to it. A paid one-off checkout session that is dropped for missing tenant, price or customer data now logs a warning with event and session id."
+  },
+  {
+    "version": "0.332.0",
+    "type": "fix",
+    "title": "Stripe retrieve transient errors answer 503 instead of ignored"
+  },
+  {
+    "version": "0.320.0",
+    "type": "fix",
+    "title": "subscription-stripe narrows a recurring price interval to a closed union instead of widening on an unrecognized Stripe value",
+    "detail": "stripe >= 22.5 widened Recurring.Interval to an open union. mapStripePrice now maps anything outside RecurringInterval (\"day\" | \"week\" | \"month\" | \"year\") to null via isKnownRecurringInterval, the same as a one-off price, instead of letting an unrecognized interval leak into ProviderPrice untyped. stripe bumped to 22.6.2. Closes #3312."
+  },
+  {
+    "version": "0.319.0",
+    "type": "fix",
+    "title": "subscription-stripe bumps the stripe SDK to ^22.6.2 and fixes the resulting price-interval type break",
+    "detail": "The bundled `stripe` dependency moves from ^22.1.1 to ^22.6.2.\nStripe.Price.Recurring.Interval widened in that range; mapStripePrice\nnow narrows it against the exported `KNOWN_RECURRING_INTERVALS` /\n`RecurringInterval` from billing-foundation instead of a cast (an\nunrecognized interval maps to `null`). Apps pinning their own\n`stripe` override for this mismatch can remove it.\n\nThe plugin gains a new `oneOffPriceIds` option (validated at mount\ntime — an empty-string or duplicate entry throws) and now maps Stripe's\n`subscription.cancel_at` (or `current_period_end` when only\n`cancel_at_period_end` is set) into the `cancelAtIso` event field\nbilling-foundation's process-event consumes."
+  },
+  {
+    "version": "0.318.0",
+    "type": "fix",
+    "title": "switch-plan returns a 422 instead of a 500 when two plan tiers share one Stripe product",
+    "detail": "`createStripePlanSwitchSession`'s pre-check (two allowed prices at the same product+interval) and a matching Stripe Customer-Portal `StripeInvalidRequestError` (from `configurations.create()` or `sessions.create()`) both now throw `UnprocessableError('plan_tiers_share_product')` with i18nKey `billing-foundation.errors.planTiersShareProduct`, so the caller gets an actionable 422 instead of an opaque 500. Every other Stripe error keeps its existing mapping; the portal-configuration cache is still evicted on a `sessions.create()` failure.\nEach plan tier needs its own Stripe product: the Customer Portal configuration allows only one price per product and interval, so tiers that share a product cannot be switched between."
+  },
+  {
+    "version": "0.318.0",
+    "type": "fix",
+    "title": "Stripe subscription status incomplete_expired now maps to canceled instead of incomplete",
+    "detail": "incomplete_expired means Stripe abandoned the subscription's first payment for good (unlike a live incomplete, which is still retryable). Mapping it to canceled instead of incomplete lets the tenant start a fresh checkout instead of being blocked by openCheckout's subscription-already-exists conflict."
+  },
+  {
+    "version": "0.318.0",
+    "type": "improvement",
+    "title": "subscription-stripe implements retrievePrices, createPlanSwitchSession and isBillingEnabled for the shared billing-plans catalog",
+    "detail": "Adds priceToTier (Stripe price id -> app tier name), a 10-minute TTL-cached retrievePrices for the billing-plans catalog, createPlanSwitchSession (auto-provisions a Stripe Customer-Portal configuration content-addressed by its price set, reusing an existing one via configurations.list() before calling configurations.create()) and isBillingEnabled (billingLive plus an api-key existence probe, no secret read). Each plan tier needs its own Stripe product: two allowed prices sharing a product+interval are rejected before any Stripe portal call."
+  },
+  {
+    "version": "0.313.0",
+    "type": "breaking",
+    "title": "subscription-stripe mode:\"payment\" checkouts now get a Stripe invoice by default",
+    "detail": "createCheckoutSession's mode:\"payment\" call (one-off top-ups etc.) never\npassed invoice_creation, so Stripe never generated an invoice document for\nthose payments. It now defaults to `invoice_creation: { enabled: true }`\nfor mode:\"payment\" — mode:\"subscription\" is unaffected, Stripe rejects\ninvoice_creation there. Stripe Invoicing charges a per-invoice fee on top\nof the payment itself, so an existing high-volume, low-value payment flow\nmay see new fees appear.",
+    "migration": "Pass `createSubscriptionStripeFeature({ paymentInvoiceCreation: false })`\nto opt out and keep the old no-invoice behaviour for mode:\"payment\" checkouts."
+  }
+]

package/packages/bundled-features/src/subscription-stripe/constants.ts

@@ -0,0 +1,35 @@
+// Feature name
+export const SUBSCRIPTION_STRIPE_FEATURE = "subscription-stripe" as const;
+
+// entityName under den der Plugin gegen "subscriptionProvider"
+// registriert. Matcht den path-segment in der webhook-URL
+// `/api/subscription/webhook/stripe`.
+export const STRIPE_PROVIDER_NAME = "stripe" as const;
+
+// Config-key short-names, qualified to `subscription-stripe:config:<name>`
+// at registry-build. api-key + webhook-secret declare backing:"secrets"
+// (value lives envelope-encrypted in the secrets store under SYSTEM_TENANT_ID)
+// but are addressed as config keys; billingLive is a plain system config flag.
+export const STRIPE_API_KEY_CONFIG = "api-key" as const;
+export const STRIPE_WEBHOOK_SECRET_CONFIG = "webhook-secret" as const;
+export const STRIPE_BILLING_LIVE_CONFIG = "billingLive" as const;
+
+// =============================================================================
+// Stripe-event-types die wir auf normalisierte SubscriptionEventTypes
+// mappen. Stripe hat ~80 event-types insgesamt; wir filtern auf 5.
+// =============================================================================
+
+export const StripeEventTypes = {
+  customerSubscriptionCreated: "customer.subscription.created",
+  customerSubscriptionUpdated: "customer.subscription.updated",
+  customerSubscriptionDeleted: "customer.subscription.deleted",
+  invoicePaid: "invoice.paid",
+  invoicePaymentFailed: "invoice.payment_failed",
+  // One-off-payment checkout (mode: "payment") completion. Both fire for a
+  // successful payment — `completed` for synchronous methods (card),
+  // `async_payment_succeeded` for delayed ones (SEPA, bank transfers). Never
+  // fed into mapStripeEventType — handled by a dedicated branch in
+  // verify-webhook.ts before the subscription-event switch runs.
+  checkoutSessionCompleted: "checkout.session.completed",
+  checkoutSessionAsyncPaymentSucceeded: "checkout.session.async_payment_succeeded",
+} as const;