@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/subscription-mollie/__tests__/verify-webhook.test.ts

@@ -0,0 +1,388 @@
+// Unit-Tests für verifyAndParseMollieWebhook — Mollie's classic
+// webhook-pattern (lazy-fetch, ohne sig-verify). Mollie-Client wird
+// als minimal-mock-shape (`MollieClientShape`) injiziert; Plugin-
+// Verhalten ist vom konkreten Mollie-SDK entkoppelt.
+
+import {
+  SubscriptionEventTypes,
+  SubscriptionStatuses,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { describe, expect, test, vi } from "vitest";
+import {
+  extractMollieId,
+  type MollieClientShape,
+  mapMollieEventType,
+  mapMollieStatus,
+  verifyAndParseMollieWebhook,
+} from "../verify-webhook";
+
+// =============================================================================
+// Test-helpers
+// =============================================================================
+
+function buildMockSubscription(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    id: "sub_test_001",
+    customerId: "cst_test_001",
+    status: "active",
+    nextPaymentDate: "2026-06-15",
+    startDate: "2026-05-15",
+    metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+    ...overrides,
+    // biome-ignore lint/suspicious/noExplicitAny: minimal mock — wir nutzen nur 4 Felder
+  } as any;
+}
+
+function buildMockPayment(overrides: Partial<Record<string, unknown>> = {}) {
+  return {
+    id: "tr_test_001",
+    customerId: "cst_test_001",
+    subscriptionId: "sub_test_001",
+    sequenceType: "first",
+    status: "paid",
+    ...overrides,
+    // biome-ignore lint/suspicious/noExplicitAny: minimal mock
+  } as any;
+}
+
+function buildClient(
+  overrides: {
+    paymentResolve?: ReturnType<typeof buildMockPayment>;
+    paymentReject?: Error;
+    subResolve?: ReturnType<typeof buildMockSubscription>;
+    subReject?: Error;
+    /** Bestehende subs die `customerSubscriptions.list` zurückgibt (für
+     *  mandate-setup-idempotency-tests). */
+    listResolve?: ReturnType<typeof buildMockSubscription>[];
+    /** Was `customerSubscriptions.create` zurückgibt. Default: eine
+     *  neu-erstellte sub mit metadata vom payment. */
+    createResolve?: ReturnType<typeof buildMockSubscription>;
+  } = {},
+): MollieClientShape {
+  return {
+    payments: {
+      get: vi.fn(async () => {
+        if (overrides.paymentReject) throw overrides.paymentReject;
+        return overrides.paymentResolve ?? buildMockPayment();
+      }),
+    },
+    customerSubscriptions: {
+      get: vi.fn(async () => {
+        if (overrides.subReject) throw overrides.subReject;
+        return overrides.subResolve ?? buildMockSubscription();
+      }),
+      list: vi.fn(async () => overrides.listResolve ?? []),
+      create: vi.fn(
+        async () => overrides.createResolve ?? buildMockSubscription({ id: "sub_just_created" }),
+      ),
+    },
+  };
+}
+
+const TEST_PRICE_CONFIG = {
+  plan_pro: {
+    amountValue: "9.99",
+    amountCurrency: "EUR",
+    interval: "1 month",
+    description: "Pro-Abo monatlich",
+  },
+};
+
+// =============================================================================
+// extractMollieId — body-parsing
+// =============================================================================
+
+describe("extractMollieId", () => {
+  test("form-urlencoded body → extract id", () => {
+    expect(
+      extractMollieId("id=tr_xxx", { "content-type": "application/x-www-form-urlencoded" }),
+    ).toBe("tr_xxx");
+  });
+
+  test("default content-type wird als form-urlencoded behandelt (Mollie-classic)", () => {
+    expect(extractMollieId("id=sub_yyy", {})).toBe("sub_yyy");
+  });
+
+  test("JSON body mit content-type", () => {
+    expect(extractMollieId('{"id":"tr_zzz"}', { "content-type": "application/json" })).toBe(
+      "tr_zzz",
+    );
+  });
+
+  test("malformed JSON → null statt throw (defensive)", () => {
+    expect(extractMollieId("not json", { "content-type": "application/json" })).toBeNull();
+  });
+
+  test("body ohne id → null", () => {
+    expect(extractMollieId("foo=bar", {})).toBeNull();
+  });
+});
+
+// =============================================================================
+// Lazy-fetch
+// =============================================================================
+
+describe("verifyAndParseMollieWebhook — payment-event happy path", () => {
+  const verify = (client: MollieClientShape) =>
+    verifyAndParseMollieWebhook(client, {
+      priceToTier: { plan_pro: "pro" },
+      priceToConfig: TEST_PRICE_CONFIG,
+    });
+
+  test("tr_xxx → fetch payment + subscription → SubscriptionEvent.created (first-payment paid)", async () => {
+    const client = buildClient();
+    const event = await verify(client)("id=tr_test_001", {});
+    expect(event).not.toBeNull();
+    expect(event?.providerName).toBe("mollie");
+    expect(event?.providerEventId).toBe("tr_test_001");
+    expect(event?.type).toBe(SubscriptionEventTypes.created);
+    expect(event?.tenantId).toBe("tenant-test");
+    expect(event?.tier).toBe("pro");
+    expect(event?.providerSubscriptionId).toBe("sub_test_001");
+    expect(event?.providerCustomerId).toBe("cst_test_001");
+    expect(event?.status).toBe(SubscriptionStatuses.active);
+  });
+
+  test("recurring-payment paid → invoicePaid", async () => {
+    const client = buildClient({
+      paymentResolve: buildMockPayment({ sequenceType: "recurring", status: "paid" }),
+    });
+    const event = await verify(client)("id=tr_renewal_001", {});
+    expect(event?.type).toBe(SubscriptionEventTypes.invoicePaid);
+  });
+
+  test("recurring-payment failed → invoicePaymentFailed", async () => {
+    const client = buildClient({
+      paymentResolve: buildMockPayment({ sequenceType: "recurring", status: "failed" }),
+    });
+    const event = await verify(client)("id=tr_failed_001", {});
+    expect(event?.type).toBe(SubscriptionEventTypes.invoicePaymentFailed);
+  });
+
+  test("subscription canceled → SubscriptionEventTypes.canceled (egal welche payment-status)", async () => {
+    const client = buildClient({
+      subResolve: buildMockSubscription({ status: "canceled" }),
+    });
+    const event = await verify(client)("id=tr_test_001", {});
+    expect(event?.type).toBe(SubscriptionEventTypes.canceled);
+    expect(event?.status).toBe(SubscriptionStatuses.canceled);
+  });
+});
+
+describe("verifyAndParseMollieWebhook — mandate-setup-flow (= first-payment-paid OHNE existierende sub)", () => {
+  const verify = (client: MollieClientShape) =>
+    verifyAndParseMollieWebhook(client, {
+      priceToTier: { plan_pro: "pro" },
+      priceToConfig: TEST_PRICE_CONFIG,
+    });
+
+  test("first-payment paid, subscriptionId=null → list ist leer → ensureSubscription erstellt neue Sub → Created-Event mit der neuen sub-id", async () => {
+    const newlyCreatedSub = buildMockSubscription({
+      id: "sub_just_created",
+      metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+    });
+    const client = buildClient({
+      paymentResolve: buildMockPayment({
+        subscriptionId: null,
+        sequenceType: "first",
+        status: "paid",
+        metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+      }),
+      listResolve: [],
+      createResolve: newlyCreatedSub,
+    });
+
+    const event = await verify(client)("id=tr_first_paid_001", {});
+
+    expect(event).not.toBeNull();
+    expect(event?.type).toBe(SubscriptionEventTypes.created);
+    expect(event?.providerSubscriptionId).toBe("sub_just_created");
+    expect(client.customerSubscriptions.create).toHaveBeenCalledExactlyOnceWith("cst_test_001", {
+      amount: { currency: "EUR", value: "9.99" },
+      interval: "1 month",
+      description: "Pro-Abo monatlich",
+      metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+    });
+  });
+
+  test("Replay (Mollie sendet webhook nochmal) → list findet existing-active-sub für priceId → kein zweiter create", async () => {
+    const existingSub = buildMockSubscription({
+      id: "sub_already_there",
+      status: "active",
+      metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+    });
+    const client = buildClient({
+      paymentResolve: buildMockPayment({
+        subscriptionId: null,
+        sequenceType: "first",
+        status: "paid",
+        metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+      }),
+      listResolve: [existingSub],
+    });
+
+    const event = await verify(client)("id=tr_first_paid_replay", {});
+
+    expect(event?.providerSubscriptionId).toBe("sub_already_there");
+    expect(client.customerSubscriptions.create).not.toHaveBeenCalled();
+  });
+
+  test("List hat sub für ANDEREN priceId (= App-Builder bietet Plan-Wechsel) → trotzdem create für neuen priceId", async () => {
+    const otherPlanSub = buildMockSubscription({
+      id: "sub_basic_old",
+      status: "active",
+      metadata: { tenantId: "tenant-test", priceId: "plan_basic" },
+    });
+    const client = buildClient({
+      paymentResolve: buildMockPayment({
+        subscriptionId: null,
+        sequenceType: "first",
+        status: "paid",
+        metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+      }),
+      listResolve: [otherPlanSub],
+      createResolve: buildMockSubscription({
+        id: "sub_pro_new",
+        metadata: { tenantId: "tenant-test", priceId: "plan_pro" },
+      }),
+    });
+
+    const event = await verify(client)("id=tr_upgrade", {});
+
+    expect(event?.providerSubscriptionId).toBe("sub_pro_new");
+    expect(client.customerSubscriptions.create).toHaveBeenCalledOnce();
+  });
+});
+
+describe("verifyAndParseMollieWebhook — error + ignore paths", () => {
+  const verify = (client: MollieClientShape) =>
+    verifyAndParseMollieWebhook(client, {
+      priceToTier: { plan_pro: "pro" },
+      priceToConfig: TEST_PRICE_CONFIG,
+    });
+
+  test("body ohne id → throws", async () => {
+    const client = buildClient();
+    await expect(verify(client)("not-an-id-form", {})).rejects.toThrow(/no `id` field/);
+  });
+
+  test("unbekannte ID-form (kein tr_/sub_ prefix) → null", async () => {
+    const client = buildClient();
+    expect(await verify(client)("id=unknown_xyz", {})).toBeNull();
+  });
+
+  test("Mollie-API rejectet payment-fetch (= garbage-id) → null (foundation 200 ignored)", async () => {
+    const client = buildClient({ paymentReject: new Error("Mollie 404: not found") });
+    expect(await verify(client)("id=tr_garbage", {})).toBeNull();
+  });
+
+  test("payment ohne subscriptionId UND nicht first-payment-paid → null (= one-shot, nicht unsere domain)", async () => {
+    const client = buildClient({
+      paymentResolve: buildMockPayment({ subscriptionId: null, sequenceType: "oneoff" }),
+    });
+    expect(await verify(client)("id=tr_oneshot", {})).toBeNull();
+  });
+
+  test("first-payment-paid OHNE payment.metadata → null (App-Builder hat tenantId/priceId nicht gesetzt)", async () => {
+    const client = buildClient({
+      paymentResolve: buildMockPayment({
+        subscriptionId: null,
+        sequenceType: "first",
+        status: "paid",
+        metadata: null,
+      }),
+    });
+    expect(await verify(client)("id=tr_no_metadata", {})).toBeNull();
+  });
+
+  test("first-payment-paid mit unbekanntem priceId → null (priceToConfig-Drift)", async () => {
+    const client = buildClient({
+      paymentResolve: buildMockPayment({
+        subscriptionId: null,
+        sequenceType: "first",
+        status: "paid",
+        metadata: { tenantId: "tenant-test", priceId: "plan_unknown" },
+      }),
+    });
+    expect(await verify(client)("id=tr_unknown_price", {})).toBeNull();
+  });
+
+  test("subscription ohne metadata.tenantId → null", async () => {
+    const client = buildClient({
+      subResolve: buildMockSubscription({ metadata: { priceId: "plan_pro" } }),
+    });
+    expect(await verify(client)("id=tr_no_tenant", {})).toBeNull();
+  });
+
+  test("priceId nicht im Mapping → null", async () => {
+    const client = buildClient({
+      subResolve: buildMockSubscription({
+        metadata: { tenantId: "t", priceId: "plan_unknown" },
+      }),
+    });
+    expect(await verify(client)("id=tr_test_001", {})).toBeNull();
+  });
+
+  test("sub_xxx-direct-events sind heute NICHT supported (= null) — App-Builder bekommt sie indirekt via tr_xxx-payment-events", async () => {
+    const client = buildClient();
+    expect(await verify(client)("id=sub_direct_evt", {})).toBeNull();
+  });
+
+  test("subscription ohne nextPaymentDate UND ohne startDate → throws (Mollie-API-Drift)", async () => {
+    const client = buildClient({
+      subResolve: buildMockSubscription({ nextPaymentDate: null, startDate: null }),
+    });
+    await expect(verify(client)("id=tr_no_dates", {})).rejects.toThrow(
+      /has neither nextPaymentDate nor startDate/,
+    );
+  });
+
+  test("malformed nextPaymentDate (z.B. 'invalid') → throws (Mollie-API-Drift)", async () => {
+    const client = buildClient({
+      subResolve: buildMockSubscription({ nextPaymentDate: "garbage-date" }),
+    });
+    // Temporal.Instant.from wirft RangeError bei malformed input.
+    await expect(verify(client)("id=tr_bad_date", {})).rejects.toThrow();
+  });
+});
+
+// =============================================================================
+// Mapping-helpers
+// =============================================================================
+
+describe("mapMollieStatus — Mollie-status → normalized", () => {
+  test("active/canceled/completed", () => {
+    // Mollie-status-strings sind ein typed enum, casts hier weil wir
+    // die Werte als plain literals testen (analog zu wie sie aus dem
+    // Mollie-API als `status: string` JSON kommen).
+    expect(mapMollieStatus("active" as never)).toBe(SubscriptionStatuses.active);
+    expect(mapMollieStatus("canceled" as never)).toBe(SubscriptionStatuses.canceled);
+    // completed = sub ist fertig (alle times-charges durch) — wie canceled
+    expect(mapMollieStatus("completed" as never)).toBe(SubscriptionStatuses.canceled);
+  });
+
+  test("suspended → past_due (= grace-period bei mandate-fail)", () => {
+    expect(mapMollieStatus("suspended" as never)).toBe(SubscriptionStatuses.pastDue);
+  });
+
+  test("pending → incomplete (= mandate noch nicht confirmed)", () => {
+    expect(mapMollieStatus("pending" as never)).toBe(SubscriptionStatuses.incomplete);
+  });
+});
+
+describe("mapMollieEventType — heuristik", () => {
+  test("subscription canceled trumps alles", () => {
+    const sub = buildMockSubscription({ status: "canceled" });
+    expect(mapMollieEventType(sub, null)).toBe(SubscriptionEventTypes.canceled);
+  });
+
+  test("active sub ohne payment-context → updated (z.B. metadata-change via API)", () => {
+    const sub = buildMockSubscription({ status: "active" });
+    expect(mapMollieEventType(sub, null)).toBe(SubscriptionEventTypes.updated);
+  });
+
+  test("pending sub ohne payment-context → null (= noch nichts entschieden)", () => {
+    const sub = buildMockSubscription({ status: "pending" });
+    expect(mapMollieEventType(sub, null)).toBeNull();
+  });
+});

package/src/subscription-mollie/constants.ts

@@ -0,0 +1,33 @@
+// Feature name
+export const SUBSCRIPTION_MOLLIE_FEATURE = "subscription-mollie" as const;
+
+// entityName under den der Plugin gegen "subscriptionProvider"
+// registriert. Matcht den path-segment in der webhook-URL
+// `/api/subscription/webhook/mollie`.
+export const MOLLIE_PROVIDER_NAME = "mollie" as const;
+
+// =============================================================================
+// Mollie-Webhook-Pattern (anders als Stripe!)
+// =============================================================================
+//
+// Mollie sendet bei JEDEM event nur die ID im body (form-urlencoded
+// oder JSON). Plugin muss IMMER lazy-fetchen via Mollie-API:
+//   - `id=tr_xxx`  → payment-id, fetch payment + subscription
+//   - `id=sub_xxx` → subscription-id, fetch subscription direkt
+//
+// **Keine native HMAC-sig-verify** in Mollie-SDK 4.5.0. Mollie's
+// Sicherheits-Modell stützt sich auf nicht-guessable IDs (~10^25
+// brute-force-space) + API-Lookup-Validation (garbage-id → 401 von
+// Mollie-API). Plus: App-Builder kann zusätzlich einen URL-Token-
+// Wrapper vor die Foundation-route schalten (eigener extraRoute der
+// einen secret-token im URL-Pfad verifiziert + dann an die Foundation
+// weiterreicht).
+//
+// **Event-Type-Mapping** ist heuristisch — Mollie hat keine explicit-
+// typed events:
+//   - sub_xxx + status=canceled/completed     → SubscriptionEventTypes.canceled
+//   - sub_xxx + status=active/pending         → SubscriptionEventTypes.updated
+//   - tr_xxx + sequenceType=first + paid      → SubscriptionEventTypes.created
+//   - tr_xxx + sequenceType=recurring + paid  → SubscriptionEventTypes.invoicePaid
+//   - tr_xxx + sequenceType=recurring + failed → SubscriptionEventTypes.invoicePaymentFailed
+//   - alles andere                            → null (foundation 200 ignored)

package/src/subscription-mollie/feature.ts

@@ -0,0 +1,144 @@
+// 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 { MOLLIE_PROVIDER_NAME, SUBSCRIPTION_MOLLIE_FEATURE } from "./constants";
+import { createMollieCheckoutSession, type MolliePriceConfig } from "./plugin-methods";
+import { type MollieClientShape, verifyAndParseMollieWebhook } from "./verify-webhook";
+
+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.requires("billing-foundation");
+
+    const plugin: SubscriptionProviderPlugin = {
+      verifyAndParseWebhook: verifyAndParse,
+      createCheckoutSession: checkoutSession,
+      // createPortalSession + cancelSubscription bewusst nicht — siehe
+      // plugin-methods.ts für Begründung.
+    };
+    r.useExtension("subscriptionProvider", MOLLIE_PROVIDER_NAME, plugin);
+  });
+}

package/src/subscription-mollie/index.ts

@@ -0,0 +1,13 @@
+// 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";
+export {
+  createSubscriptionMollieFeature,
+  type SubscriptionMollieOptions,
+} from "./feature";
+export type { MolliePriceConfig } from "./plugin-methods";

package/src/subscription-mollie/plugin-methods.ts

@@ -0,0 +1,79 @@
+// 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`. */
+  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`);
+    }
+
+    let customerId = options.providerCustomerId;
+    if (!customerId) {
+      const customer = await client.customers.create({
+        metadata: { tenantId: options.tenantId },
+      });
+      customerId = customer.id;
+    }
+
+    // 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: SequenceType.first,
+      customerId,
+      redirectUrl: options.successUrl,
+      cancelUrl: options.cancelUrl,
+      webhookUrl: appWebhookUrl,
+      metadata: {
+        tenantId: options.tenantId,
+        priceId: options.priceId,
+      },
+    }) as Promise<Payment>)) satisfies Payment;
+
+    const checkoutHref = payment.getCheckoutUrl();
+    if (!checkoutHref) {
+      throw new Error(
+        "subscription-mollie: payment.getCheckoutUrl() returned null — first-payment-mandates ggf. nicht aktiviert",
+      );
+    }
+    return { url: checkoutHref };
+  };
+}