@cosmicdrift/kumiko-bundled-features 0.1.0

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

@@ -0,0 +1,244 @@
+// 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 {
+  type SubscriptionEvent,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type {
+  Payment as MolliePayment,
+  Subscription as MollieSubscription,
+} from "@mollie/api-client";
+import { MOLLIE_PROVIDER_NAME } from "./constants";
+import type { MolliePriceConfig } from "./plugin-methods";
+
+/** 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) ?? {};
+    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);
+
+    return {
+      providerEventId: id,
+      providerName: MOLLIE_PROVIDER_NAME,
+      type,
+      tenantId,
+      providerCustomerId: subscription.customerId,
+      providerSubscriptionId: subscription.id,
+      status,
+      tier,
+      currentPeriodEnd,
+      rawPayload: JSON.stringify({ webhookId: id, subscription, triggerPayment }),
+    };
+  };
+}
+
+// =============================================================================
+// 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) ?? {};
+  const tenantId = paymentMetadata["tenantId"];
+  const priceId = paymentMetadata["priceId"];
+  if (!tenantId || !priceId) return null;
+  const priceCfg = options.priceToConfig[priceId];
+  if (!priceCfg) return null;
+
+  const existing = await client.customerSubscriptions.list(customerId);
+  const matchingExisting = existing.find(
+    (sub) =>
+      (sub.metadata as Record<string, string> | null)?.["priceId"] === priceId &&
+      (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 },
+  });
+}
+
+// =============================================================================
+// 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 = JSON.parse(rawBody) as { id?: unknown };
+      return typeof parsed.id === "string" ? parsed.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/src/subscription-stripe/__tests__/feature.test.ts

@@ -0,0 +1,98 @@
+// feature.ts contract tests for subscription-stripe.
+
+import { describe, expect, test } from "vitest";
+import { STRIPE_PROVIDER_NAME, StripeEventTypes, SUBSCRIPTION_STRIPE_FEATURE } from "../constants";
+import { createSubscriptionStripeFeature } from "../feature";
+
+const VALID_OPTIONS = {
+  webhookSecret: "whsec_test_dummy",
+  apiKey: "sk_test_dummy",
+  priceToTier: { price_test: "pro" },
+};
+
+describe("createSubscriptionStripeFeature — shape", () => {
+  test("has the expected name", () => {
+    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+    expect(feature.name).toBe(SUBSCRIPTION_STRIPE_FEATURE);
+    expect(feature.name).toBe("subscription-stripe");
+  });
+
+  test("requires only subscription-foundation (NICHT config/secrets — alles app-wide via factory-options)", () => {
+    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+    expect(feature.requires).toContain("billing-foundation");
+    // Drift-Pin: webhook-secret + apiKey kommen aus factory-options
+    // (= module-load-Closure), NICHT aus tenant-config/-secrets.
+    expect(feature.requires).not.toContain("config");
+    expect(feature.requires).not.toContain("secrets");
+  });
+});
+
+describe("createSubscriptionStripeFeature — module-load validation", () => {
+  test("throws bei empty webhookSecret (= App-Owner hat sub-stripe gemountet aber Stripe-Account nicht konfiguriert)", () => {
+    expect(() =>
+      createSubscriptionStripeFeature({
+        ...VALID_OPTIONS,
+        webhookSecret: "",
+      }),
+    ).toThrow(/webhookSecret is empty/);
+  });
+
+  test("throws bei empty apiKey", () => {
+    expect(() =>
+      createSubscriptionStripeFeature({
+        ...VALID_OPTIONS,
+        apiKey: "",
+      }),
+    ).toThrow(/apiKey is empty/);
+  });
+});
+
+describe("subscription-stripe — plugin-registration", () => {
+  test("registers itself under entityName 'stripe' for subscription-foundation's extension", () => {
+    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+    const usages = feature.extensionUsages;
+    expect(
+      usages.some(
+        (u) => u.extensionName === "subscriptionProvider" && u.entityName === STRIPE_PROVIDER_NAME,
+      ),
+    ).toBe(true);
+  });
+
+  test("plugin-options have a valid SubscriptionProviderPlugin shape (drift-pin alle 4 methods)", () => {
+    // Stärker als nur "extension-usage existiert": wenn jemand eine der
+    // plugin-methods aus dem plugin-build entfernt, würde der
+    // entsprechende Foundation-write-handler zur Laufzeit als
+    // "method not supported"-error brechen — type-check würde es nicht
+    // fangen weil die useExtension-options als `unknown` durchgereicht
+    // werden.
+    const feature = createSubscriptionStripeFeature(VALID_OPTIONS);
+    const usage = feature.extensionUsages.find((u) => u.entityName === STRIPE_PROVIDER_NAME);
+    expect(usage).toBeDefined();
+    const options = usage?.options as {
+      verifyAndParseWebhook?: unknown;
+      createCheckoutSession?: unknown;
+      createPortalSession?: unknown;
+      cancelSubscription?: unknown;
+    };
+    expect(typeof options?.verifyAndParseWebhook).toBe("function");
+    expect(typeof options?.createCheckoutSession).toBe("function");
+    expect(typeof options?.createPortalSession).toBe("function");
+    expect(typeof options?.cancelSubscription).toBe("function");
+  });
+});
+
+describe("constants — Stripe-event-types die wir mappen", () => {
+  test("StripeEventTypes whitelist — was die Foundation verarbeitet", () => {
+    // Drift-Pin: ein Refactor das einen event-type rauswirft (z.B.
+    // invoice.paid weil "wir nutzen das nicht") würde tier-grace-period-
+    // tracking brechen. Plus: ein Refactor der einen NICHT-existing
+    // Stripe-event-type reinschreibt (typo) würde silent ignored werden.
+    expect(Object.values(StripeEventTypes)).toEqual([
+      "customer.subscription.created",
+      "customer.subscription.updated",
+      "customer.subscription.deleted",
+      "invoice.paid",
+      "invoice.payment_failed",
+    ]);
+  });
+});

package/src/subscription-stripe/__tests__/plugin-methods.test.ts

@@ -0,0 +1,161 @@
+// Unit-Tests für die Stripe-Plugin-Methoden (createCheckoutSession,
+// createPortalSession, cancelSubscription). Stripe-SDK-calls werden via
+// vi.spyOn gemockt — wir testen unsere Mapping-Logik (Argumente die wir
+// an Stripe schicken + Antwort-Parsing), NICHT Stripe selbst.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import Stripe from "stripe";
+import { describe, expect, test, vi } from "vitest";
+import {
+  createStripeCancelSubscription,
+  createStripeCheckoutSession,
+  createStripePortalSession,
+} from "../plugin-methods";
+
+const TEST_API_KEY = "sk_test_dummy";
+
+function buildStripe(): Stripe {
+  return new Stripe(TEST_API_KEY, { apiVersion: "2026-04-22.dahlia" });
+}
+
+const stubCtx = {} as HandlerContext;
+
+// =============================================================================
+// createCheckoutSession
+// =============================================================================
+
+describe("createStripeCheckoutSession", () => {
+  test("ruft stripe.checkout.sessions.create mit mode=subscription + tenant-metadata", async () => {
+    const stripe = buildStripe();
+    const createMock = vi
+      .spyOn(stripe.checkout.sessions, "create")
+      // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
+      .mockResolvedValue({ url: "https://checkout.stripe.com/c/pay/test" } as any);
+
+    const checkout = createStripeCheckoutSession(stripe);
+    const result = await checkout(stubCtx, {
+      priceId: "price_pro_monthly",
+      tenantId: "tenant-001",
+      successUrl: "https://example.com/success",
+      cancelUrl: "https://example.com/cancel",
+    });
+
+    expect(result).toEqual({ url: "https://checkout.stripe.com/c/pay/test" });
+    expect(createMock).toHaveBeenCalledExactlyOnceWith({
+      mode: "subscription",
+      line_items: [{ price: "price_pro_monthly", quantity: 1 }],
+      success_url: "https://example.com/success",
+      cancel_url: "https://example.com/cancel",
+      // Drift-Pin: metadata.tenantId LANDET auf der subscription, NICHT
+      // auf der checkout-session direkt — sonst kann verifyAndParse-
+      // Webhook den tenant beim subsequent webhook nicht resolven.
+      subscription_data: {
+        metadata: { tenantId: "tenant-001" },
+      },
+    });
+  });
+
+  test("passes existing customer-id wenn gesetzt (Plan-Wechsel-Flow)", async () => {
+    const stripe = buildStripe();
+    const createMock = vi
+      .spyOn(stripe.checkout.sessions, "create")
+      // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
+      .mockResolvedValue({ url: "https://x" } as any);
+
+    const checkout = createStripeCheckoutSession(stripe);
+    await checkout(stubCtx, {
+      priceId: "price_x",
+      tenantId: "tenant-002",
+      successUrl: "https://x/s",
+      cancelUrl: "https://x/c",
+      providerCustomerId: "cus_existing_123",
+    });
+
+    expect(createMock).toHaveBeenCalledWith(
+      expect.objectContaining({ customer: "cus_existing_123" }),
+    );
+  });
+
+  test("throws wenn Stripe keine url returnt (defensive — sollte nie passieren bei mode=subscription)", async () => {
+    const stripe = buildStripe();
+    vi.spyOn(stripe.checkout.sessions, "create")
+      // biome-ignore lint/suspicious/noExplicitAny: SDK-Drift-Test
+      .mockResolvedValue({ url: null } as any);
+
+    const checkout = createStripeCheckoutSession(stripe);
+    await expect(
+      checkout(stubCtx, {
+        priceId: "p",
+        tenantId: "t",
+        successUrl: "https://x/s",
+        cancelUrl: "https://x/c",
+      }),
+    ).rejects.toThrow(/returned no url/);
+  });
+
+  test("Stripe-API-failure (z.B. 500 / network) → propagated zum Caller (Foundation mapped auf 500)", async () => {
+    // Drift-Pin: Plugin schluckt KEINE Stripe-Errors. Foundation
+    // verlässt sich darauf dass create-checkout-session-handler einen
+    // throw kriegt + zur HTTP 500 mapped (transient — Provider/Stripe
+    // soll retried werden statt silent-success-mit-leerer-URL).
+    const stripe = buildStripe();
+    vi.spyOn(stripe.checkout.sessions, "create").mockRejectedValue(
+      new Error("Stripe API: Internal server error"),
+    );
+
+    const checkout = createStripeCheckoutSession(stripe);
+    await expect(
+      checkout(stubCtx, {
+        priceId: "p",
+        tenantId: "t",
+        successUrl: "https://x/s",
+        cancelUrl: "https://x/c",
+      }),
+    ).rejects.toThrow(/Internal server error/);
+  });
+});
+
+// =============================================================================
+// createPortalSession
+// =============================================================================
+
+describe("createStripePortalSession", () => {
+  test("ruft stripe.billingPortal.sessions.create mit customer + return_url", async () => {
+    const stripe = buildStripe();
+    const createMock = vi
+      .spyOn(stripe.billingPortal.sessions, "create")
+      // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
+      .mockResolvedValue({ url: "https://billing.stripe.com/p/session/test" } as any);
+
+    const portal = createStripePortalSession(stripe);
+    const result = await portal(stubCtx, {
+      providerCustomerId: "cus_001",
+      returnUrl: "https://example.com/return",
+    });
+
+    expect(result).toEqual({ url: "https://billing.stripe.com/p/session/test" });
+    expect(createMock).toHaveBeenCalledExactlyOnceWith({
+      customer: "cus_001",
+      return_url: "https://example.com/return",
+    });
+  });
+});
+
+// =============================================================================
+// cancelSubscription
+// =============================================================================
+
+describe("createStripeCancelSubscription", () => {
+  test("ruft stripe.subscriptions.cancel mit subscription-id", async () => {
+    const stripe = buildStripe();
+    const cancelMock = vi
+      .spyOn(stripe.subscriptions, "cancel")
+      // biome-ignore lint/suspicious/noExplicitAny: Stripe-SDK-typed mock-return
+      .mockResolvedValue({ id: "sub_001", status: "canceled" } as any);
+
+    const cancel = createStripeCancelSubscription(stripe);
+    await cancel(stubCtx, "sub_001");
+
+    expect(cancelMock).toHaveBeenCalledExactlyOnceWith("sub_001");
+  });
+});