@cosmicdrift/kumiko-bundled-features 0.250.0 → 0.252.0

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

@@ -8,7 +8,9 @@
 // Aufwand ohne Test-Wert.
 
 import { describe, expect, test } from "bun:test";
+import type { SubscriptionEvent } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
+  BillingEventKinds,
   SubscriptionEventTypes,
   SubscriptionStatuses,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
@@ -35,6 +37,21 @@ function webhookRuntime(webhookSecret = TEST_SECRET): StripeWebhookRuntime {
   return { resolve: async () => ({ stripe: stripeForFixtures, webhookSecret }) };
 }
 
+/** This file's fixtures are all subscription/invoice events — never
+ *  checkout.session.* (that's payment-checkout.test.ts's job). Narrows the
+ *  widened `verifyAndParseStripeWebhook` return type back down via the
+ *  `kind` discriminator, so the rest of this file can keep asserting on
+ *  SubscriptionEvent-only fields without a union check at every call-site. */
+function asSubscriptionVerifier(
+  verifyFn: ReturnType<typeof verifyAndParseStripeWebhook>,
+): (rawBody: string, headers: Record<string, string>) => Promise<SubscriptionEvent | null> {
+  return async (rawBody, headers) => {
+    const event = await verifyFn(rawBody, headers);
+    if (!event || event.kind === BillingEventKinds.payment) return null;
+    return event;
+  };
+}
+
 function buildSubscriptionEvent(overrides: {
   eventType?: string;
   eventId?: string;
@@ -102,9 +119,11 @@ async function signEvent(payload: string, secret = TEST_SECRET): Promise<string>
 // =============================================================================
 
 describe("verifyAndParseStripeWebhook — sig-verify", () => {
-  const verify = verifyAndParseStripeWebhook(webhookRuntime(), {
-    priceToTier: { price_pro_monthly: "pro" },
-  });
+  const verify = asSubscriptionVerifier(
+    verifyAndParseStripeWebhook(webhookRuntime(), {
+      priceToTier: { price_pro_monthly: "pro" },
+    }),
+  );
 
   test("happy path: valid sig + bekannter event-type → SubscriptionEvent", async () => {
     const payload = JSON.stringify(buildSubscriptionEvent({}));
@@ -148,9 +167,11 @@ describe("verifyAndParseStripeWebhook — sig-verify", () => {
 // =============================================================================
 
 describe("verifyAndParseStripeWebhook — event-filter", () => {
-  const verify = verifyAndParseStripeWebhook(webhookRuntime(), {
-    priceToTier: { price_pro_monthly: "pro" },
-  });
+  const verify = asSubscriptionVerifier(
+    verifyAndParseStripeWebhook(webhookRuntime(), {
+      priceToTier: { price_pro_monthly: "pro" },
+    }),
+  );
 
   test("unbekannter event-type → null (foundation 200 ignored)", async () => {
     // customer.created ist gültiger Stripe-event aber nicht in unserer
@@ -216,9 +237,11 @@ describe("verifyAndParseStripeWebhook — event-filter", () => {
 // =============================================================================
 
 describe("verifyAndParseStripeWebhook — tenant-resolution + price-to-tier", () => {
-  const verify = verifyAndParseStripeWebhook(webhookRuntime(), {
-    priceToTier: { price_pro_monthly: "pro", price_business_yearly: "business" },
-  });
+  const verify = asSubscriptionVerifier(
+    verifyAndParseStripeWebhook(webhookRuntime(), {
+      priceToTier: { price_pro_monthly: "pro", price_business_yearly: "business" },
+    }),
+  );
 
   test("metadata.tenantId fehlt → null (App-Owner-Bug, foundation 200 ignored)", async () => {
     const ev = buildSubscriptionEvent({});
@@ -257,9 +280,11 @@ describe("verifyAndParseStripeWebhook — tenant-resolution + price-to-tier", ()
 
 describe("verifyAndParseStripeWebhook — kumiko-framework#1525: no ambient Temporal global", () => {
   test("computes currentPeriodEnd without relying on globalThis.Temporal", async () => {
-    const verify = verifyAndParseStripeWebhook(webhookRuntime(), {
-      priceToTier: { price_pro_monthly: "pro" },
-    });
+    const verify = asSubscriptionVerifier(
+      verifyAndParseStripeWebhook(webhookRuntime(), {
+        priceToTier: { price_pro_monthly: "pro" },
+      }),
+    );
     const payload = JSON.stringify(buildSubscriptionEvent({ currentPeriodEndUnix: 1_780_000_000 }));
     const sig = await signEvent(payload);
 

package/src/subscription-stripe/constants.ts

@@ -25,4 +25,11 @@ export const StripeEventTypes = {
   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;

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

@@ -2,10 +2,13 @@
 // event-mapping. Wird vom Plugin-Build (feature.ts) als
 // `verifyAndParseWebhook` registriert.
 //
-// **Drei Schritte:**
+// **Steps:**
 //   1. Sig-verify via stripe.webhooks.constructEvent (HMAC-SHA-256
 //      gegen rawBody + Stripe-Signature-Header). Wirft bei mismatch
 //      oder älter als 5min (Replay-Protection).
+//   1b. checkout.session.completed / .async_payment_succeeded branch off
+//       here into a PaymentEvent (one-off-payment, own aggregate) — see
+//       "One-off-payment" section below. Everything else falls through.
 //   2. Event-type-Filter: nur die 5 event-types die wir auf
 //      SubscriptionEventTypes mappen kommen weiter; alles andere
 //      returnt null (foundation antwortet 200 ignored).
@@ -31,8 +34,12 @@
 // returnt der Plugin defensiv null — der nächste subscription-event
 // wird den state korrekt handhaben.
 
-import type { SubscriptionEvent } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type {
+  PaymentEvent,
+  SubscriptionEvent,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
+  BillingEventKinds,
   type SubscriptionEventType,
   SubscriptionEventTypes,
   type SubscriptionStatus,
@@ -69,7 +76,7 @@ export function verifyAndParseStripeWebhook(
   rawBody: string,
   headers: Record<string, string>,
   systemSecrets?: SecretsContext,
-) => Promise<SubscriptionEvent | null> {
+) => Promise<SubscriptionEvent | PaymentEvent | null> {
   return async (rawBody, headers, systemSecrets) => {
     const sigHeader = headers["stripe-signature"];
     if (!sigHeader) {
@@ -83,7 +90,9 @@ export function verifyAndParseStripeWebhook(
 
     // 1. Sig-verify. constructEvent throws bei mismatch (= invalid sig)
     //    oder timestamp-tolerance-violation (default 5min). Foundation
-    //    mapped throw → HTTP 401.
+    //    mapped throw → HTTP 401. Applies to BOTH branches below — the
+    //    payment-branch only branches off AFTER this check; there's no
+    //    path that bypasses signature verification.
     let event: Stripe.Event;
     try {
       event = await stripe.webhooks.constructEventAsync(rawBody, sigHeader, webhookSecret);
@@ -92,6 +101,15 @@ export function verifyAndParseStripeWebhook(
       throw new Error(`subscription-stripe: webhook signature verify failed — ${msg}`);
     }
 
+    // 1b. One-off-payment events (checkout mode "payment") branch off BEFORE
+    //     the mapStripeEventType filter below — they don't map to a
+    //     SubscriptionEventType and must not touch mapStripeEventType's
+    //     5-item whitelist (drift-pin in verify-webhook.test.ts still
+    //     expects null for "checkout.session.completed").
+    if (isCheckoutSessionEventType(event.type)) {
+      return await parsePaymentEvent(event, stripe);
+    }
+
     // 2. Event-type-Filter — wir kennen nur 5.
     const normalizedType = mapStripeEventType(event.type);
     if (!normalizedType) {
@@ -247,3 +265,91 @@ async function extractSubscriptionFromEvent(
       return null;
   }
 }
+
+// =============================================================================
+// One-off-payment (checkout mode "payment") extraction
+// =============================================================================
+
+function isCheckoutSessionEventType(stripeType: string): boolean {
+  return (
+    stripeType === StripeEventTypes.checkoutSessionCompleted ||
+    stripeType === StripeEventTypes.checkoutSessionAsyncPaymentSucceeded
+  );
+}
+
+/** Parses a checkout.session.completed / .async_payment_succeeded event into
+ *  a PaymentEvent, or null if it isn't a paid one-off-payment session. */
+async function parsePaymentEvent(
+  event: Stripe.Event,
+  stripe: Stripe,
+): Promise<PaymentEvent | null> {
+  const session = event.data.object as Stripe.Checkout.Session; // @cast-boundary engine-bridge
+  // mode !== "payment" excludes subscription-checkout sessions (same event types);
+  // payment_status !== "paid" excludes an unpaid/expired session. Null here — not an
+  // error — maps to foundation's 200 "ignored", same as the subscription-path's filters.
+  if (session.mode !== "payment" || session.payment_status !== "paid") {
+    return null;
+  }
+
+  // Lazy-fetch with expand: the raw webhook payload carries neither
+  // line_items (needed for priceId) nor an expanded payment_intent (needed
+  // for tenantId — see below). Same lazy-fetch pattern as
+  // extractSubscriptionFromEvent's invoice-branch above, same defensive
+  // null on API failure (session gone/expired between webhook + retrieve).
+  let expanded: Stripe.Checkout.Session;
+  try {
+    expanded = await stripe.checkout.sessions.retrieve(session.id, {
+      expand: ["line_items", "payment_intent"],
+    });
+  } catch {
+    return null;
+  }
+
+  // Tenant-resolution: mode:"payment" checkout sessions carry tenantId on
+  // the PaymentIntent's OWN metadata (plugin-methods.ts sets it via
+  // payment_intent_data.metadata), NOT on session-level metadata —
+  // session.metadata is unset for this mode. Reading it off the expanded,
+  // Stripe-verified PaymentIntent (not a freely-choosable payload field) is
+  // what keeps tenant-attribution trustworthy: the webhook signature proves
+  // this whole object chain came from Stripe, and the metadata itself was
+  // set by our own backend at checkout-creation time.
+  const paymentIntent = expanded.payment_intent;
+  if (!paymentIntent || typeof paymentIntent === "string") {
+    // Not expanded (Stripe-API-drift) or absent — no verified tenant-claim
+    // to trust. Drop silent, same as the subscription-path's missing-
+    // metadata case.
+    return null;
+  }
+  const tenantId = paymentIntent.metadata?.["tenantId"];
+  if (!tenantId || tenantId.length === 0) {
+    return null;
+  }
+
+  const priceId = expanded.line_items?.data[0]?.price?.id;
+  if (!priceId) {
+    return null;
+  }
+
+  // providerCustomerId: session.customer is null for guest checkouts (no
+  // customer_creation configured) — fall back to the PaymentIntent's own
+  // customer, which Stripe sets independently of the session-level field.
+  const sessionCustomer = expanded.customer;
+  const providerCustomerId =
+    (typeof sessionCustomer === "string" ? sessionCustomer : sessionCustomer?.id) ??
+    (typeof paymentIntent.customer === "string"
+      ? paymentIntent.customer
+      : paymentIntent.customer?.id);
+  if (!providerCustomerId) {
+    return null;
+  }
+
+  return {
+    kind: BillingEventKinds.payment,
+    providerEventId: event.id,
+    providerName: STRIPE_PROVIDER_NAME,
+    tenantId,
+    providerCustomerId,
+    priceId,
+    rawPayload: JSON.stringify(event),
+  };
+}