@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/subscription-stripe/feature.ts

@@ -0,0 +1,120 @@
+// kumiko-feature-version: 1
+//
+// subscription-stripe — Stripe-Plugin für die subscription-foundation
+// Plugin-API.
+//
+// **Factory-Pattern (= createSubscriptionStripeFeature(options)):**
+// Im Gegensatz zu mail-transport-smtp / file-provider-s3 (die ihre
+// secrets aus tenant-secrets lesen) ist Stripe's webhook-secret
+// **app-wide** — App-Owner hat einen Stripe-account, alle Webhooks
+// gehen dorthin. Plugin braucht den secret beim webhook-sig-verify-
+// Zeitpunkt, der ist PRE-tenant-resolution (kein ctx).
+//
+// Lösung: factory-Funktion `createSubscriptionStripeFeature(options)`
+// liest webhook-secret + apiKey beim mount-time aus dem Caller (= App-
+// Builder's bin/server.ts der's aus process.env zieht). Closure
+// hält's für den verifyAndParseWebhook-call.
+//
+// Beispiel-Verwendung in run-config.ts:
+//
+//   import { createSubscriptionStripeFeature } from "@cosmicdrift/kumiko-bundled-features/subscription-stripe";
+//
+//   const features = [
+//     billingFoundationFeature,
+//     createSubscriptionStripeFeature({
+//       webhookSecret: process.env.STRIPE_WEBHOOK_SECRET ?? "",
+//       apiKey: process.env.STRIPE_API_KEY ?? "",
+//       priceToTier: {
+//         "price_1ABC": "pro",
+//         "price_1XYZ": "business",
+//       },
+//     }),
+//   ];
+//
+// **Pattern-Vorbild:** mirrors createFeatureTogglesFeature(options) —
+// gleiche factory-Form für features die module-load-time-Konfiguration
+// haben (analog zum FeatureToggle-runtime-holder).
+
+import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import Stripe from "stripe";
+import { STRIPE_PROVIDER_NAME, SUBSCRIPTION_STRIPE_FEATURE } from "./constants";
+import {
+  createStripeCancelSubscription,
+  createStripeCheckoutSession,
+  createStripePortalSession,
+} from "./plugin-methods";
+import { verifyAndParseStripeWebhook } from "./verify-webhook";
+
+export type SubscriptionStripeOptions = {
+  /** Webhook-secret aus dem Stripe-Dashboard. App-wide. Plugin throws
+   *  beim runtime wenn empty (= App-Owner hat sub-stripe gemountet
+   *  aber Stripe-Account nicht konfiguriert). */
+  readonly webhookSecret: string;
+  /** Stripe-API-key (sk_live_... / sk_test_...). Heute nur für
+   *  constructEvent-API-Version-Pin gebraucht; Phase 5.2b nutzt's
+   *  für outgoing-API-calls (createPortalSession etc.). */
+  readonly apiKey: string;
+  /** Price-to-tier-Mapping. Plugin liest die price-id aus Stripe-event
+   *  (subscription.items.data[0].price.id) und mappt auf einen tier-
+   *  name. Fehlt die price-id im Mapping → null (foundation 200
+   *  ignored — App-Owner-Bug, hat den Stripe-price angelegt aber
+   *  nicht zur tier zugeordnet). */
+  readonly priceToTier: Readonly<Record<string, string>>;
+};
+
+/**
+ * Factory für das subscription-stripe-feature. Wird mit den App-Owner-
+ * eigenen Stripe-Credentials gemountet. Der returnte FeatureDefinition
+ * registriert den Plugin gegen subscription-foundation's
+ * "subscriptionProvider"-extension-point unter entityName "stripe".
+ */
+export function createSubscriptionStripeFeature(
+  options: SubscriptionStripeOptions,
+): FeatureDefinition {
+  // Module-load-Validation: ohne webhook-secret kann der Plugin keinen
+  // single Webhook verifizieren. Throw vor dem mount damit der App-
+  // Owner nicht zur Laufzeit Mystery-401s sieht.
+  if (options.webhookSecret.length === 0) {
+    throw new Error(
+      "subscription-stripe: webhookSecret is empty. Set STRIPE_WEBHOOK_SECRET (or system-config) before mounting.",
+    );
+  }
+  if (options.apiKey.length === 0) {
+    throw new Error(
+      "subscription-stripe: apiKey is empty. Set STRIPE_API_KEY (or system-config) before mounting.",
+    );
+  }
+
+  // EIN Stripe-Client für alle vier plugin-methods (verify-webhook +
+  // checkout + portal + cancel). API-version-pin zentral, kein
+  // Connection-Duplikat.
+  const stripe = new Stripe(options.apiKey, { apiVersion: "2026-04-22.dahlia" });
+
+  const verifyAndParse = verifyAndParseStripeWebhook(stripe, {
+    webhookSecret: options.webhookSecret,
+    priceToTier: options.priceToTier,
+  });
+  const checkoutSession = createStripeCheckoutSession(stripe);
+  const portalSession = createStripePortalSession(stripe);
+  const cancel = createStripeCancelSubscription(stripe);
+
+  return defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
+    // Hard-deps: subscription-foundation als plugin-host. KEIN
+    // `r.requires("config", "secrets")` — der Plugin nutzt weder
+    // tenant-config noch tenant-secrets (alles app-wide via factory-
+    // options).
+    r.requires("billing-foundation");
+
+    // Plugin: register against subscription-foundation's
+    // "subscriptionProvider" extension. entityName "stripe" matcht den
+    // path-segment in der webhook-URL (`/api/subscription/webhook/stripe`).
+    const plugin: SubscriptionProviderPlugin = {
+      verifyAndParseWebhook: verifyAndParse,
+      createCheckoutSession: checkoutSession,
+      createPortalSession: portalSession,
+      cancelSubscription: cancel,
+    };
+    r.useExtension("subscriptionProvider", STRIPE_PROVIDER_NAME, plugin);
+  });
+}

package/src/subscription-stripe/index.ts

@@ -0,0 +1,14 @@
+// Public API of the subscription-stripe bundled-feature.
+//
+// **Internal-only** (NICHT im public-barrel — App-Builder nutzt das nie direkt):
+//   - StripeWebhookOptions / verifyAndParseStripeWebhook (intern vom
+//     feature.ts factory aufgerufen)
+//   - mapStripeEventType / mapStripeStatus (pure helpers, test-only;
+//     direct-import aus dem File wenn echt mal extern gebraucht)
+
+export {
+  STRIPE_PROVIDER_NAME,
+  StripeEventTypes,
+  SUBSCRIPTION_STRIPE_FEATURE,
+} from "./constants";
+export { createSubscriptionStripeFeature, type SubscriptionStripeOptions } from "./feature";

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

@@ -0,0 +1,91 @@
+// Stripe-Plugin-Methoden für die POST-tenant-resolution-Phase:
+// createCheckoutSession, createPortalSession, cancelSubscription.
+//
+// Werden vom Plugin-build (feature.ts) als methods auf dem
+// SubscriptionProviderPlugin registriert. Anders als
+// verifyAndParseWebhook (= pre-tenant) bekommen diese den vollen
+// HandlerContext (für ggf. tenant-spezifische Lookups).
+//
+// **Type-Ableitung:** die options-shapes der drei methods werden
+// **direkt vom Plugin-Contract** abgeleitet (`Parameters<NonNullable
+// <SubscriptionProviderPlugin["...method"]>>[1]`). Wenn Foundation den
+// Contract erweitert (z.B. neuer optionaler Field), bemerkt der
+// Stripe-Plugin das beim TS-Compile, nicht erst zur Laufzeit.
+
+import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type Stripe from "stripe";
+
+// =============================================================================
+// createCheckoutSession
+// =============================================================================
+//
+// Stripe-Checkout-Session erstellen. Der hosted-page-URL wird returnt;
+// der App-Builder redirected den Tenant-Admin dorthin. Nach erfolgreichem
+// checkout sendet Stripe `customer.subscription.created` mit
+// `metadata.tenantId` zurück — das ist wie der subsequent webhook den
+// Tenant resolved.
+
+export type StripeCheckoutOptions = Parameters<
+  NonNullable<SubscriptionProviderPlugin["createCheckoutSession"]>
+>[1];
+
+export function createStripeCheckoutSession(stripe: Stripe) {
+  return async (_ctx: HandlerContext, options: StripeCheckoutOptions): Promise<{ url: string }> => {
+    const session = await stripe.checkout.sessions.create({
+      mode: "subscription",
+      line_items: [{ price: options.priceId, quantity: 1 }],
+      success_url: options.successUrl,
+      cancel_url: options.cancelUrl,
+      // metadata.tenantId landet auf der subscription die durch diese
+      // checkout-session entsteht — beim subsequent webhook lesen wir's
+      // aus subscription.metadata.tenantId zurück.
+      subscription_data: {
+        metadata: { tenantId: options.tenantId },
+      },
+      ...(options.providerCustomerId && { customer: options.providerCustomerId }),
+    });
+
+    if (!session.url) {
+      // Stripe garantiert url für mode: subscription. Defensive für
+      // zukünftige API-Drift.
+      throw new Error("subscription-stripe: checkout.sessions.create returned no url");
+    }
+    return { url: session.url };
+  };
+}
+
+// =============================================================================
+// createPortalSession
+// =============================================================================
+//
+// Stripe Customer-Portal-Session — Tenant verwaltet seine subscription
+// selbst (cancel, payment-method, invoice-history).
+
+export type StripePortalOptions = Parameters<
+  NonNullable<SubscriptionProviderPlugin["createPortalSession"]>
+>[1];
+
+export function createStripePortalSession(stripe: Stripe) {
+  return async (_ctx: HandlerContext, options: StripePortalOptions): Promise<{ url: string }> => {
+    const session = await stripe.billingPortal.sessions.create({
+      customer: options.providerCustomerId,
+      return_url: options.returnUrl,
+    });
+    return { url: session.url };
+  };
+}
+
+// =============================================================================
+// cancelSubscription
+// =============================================================================
+//
+// Stripe sendet danach `customer.subscription.deleted`-webhook → der
+// state-update läuft über den normalen webhook-pfad. Diese function
+// triggert nur die API-Cancellation.
+
+export function createStripeCancelSubscription(stripe: Stripe) {
+  return async (_ctx: HandlerContext, providerSubscriptionId: string): Promise<void> => {
+    await stripe.subscriptions.cancel(providerSubscriptionId);
+  };
+}

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

@@ -0,0 +1,235 @@
+// verifyAndParseStripeWebhook — Stripe-spezifische sig-verify +
+// event-mapping. Wird vom Plugin-Build (feature.ts) als
+// `verifyAndParseWebhook` registriert.
+//
+// **Drei Schritte:**
+//   1. Sig-verify via stripe.webhooks.constructEvent (HMAC-SHA-256
+//      gegen rawBody + Stripe-Signature-Header). Wirft bei mismatch
+//      oder älter als 5min (Replay-Protection).
+//   2. Event-type-Filter: nur die 5 event-types die wir auf
+//      SubscriptionEventTypes mappen kommen weiter; alles andere
+//      returnt null (foundation antwortet 200 ignored).
+//   3. Stripe-payload → SubscriptionEvent normalisieren
+//      (status-mapping, tenant-id aus metadata, price-to-tier-Lookup).
+//
+// **Invoice-event lazy-fetch (Phase 5.2b):**
+// Bei `invoice.paid` und `invoice.payment_failed` enthält der webhook-
+// payload nur die subscription-id (Stripe-Webhooks expanden subscription
+// nicht automatisch). Plugin macht einen lazy-fetch via
+// `stripe.subscriptions.retrieve(subId)` um an das full subscription-
+// Object für status/tier/period-end-mapping zu kommen. Bei Stripe-API-
+// failure (= subscription gelöscht zwischen webhook + retrieve)
+// 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 SubscriptionEventType,
+  SubscriptionEventTypes,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import type Stripe from "stripe";
+import { STRIPE_PROVIDER_NAME, StripeEventTypes } from "./constants";
+
+// =============================================================================
+// Sig-verify + parse
+// =============================================================================
+
+export type StripeWebhookOptions = {
+  /** Webhook-secret aus dem Stripe-Dashboard. **App-wide**, nicht
+   *  per-tenant. Liest aus ENV-VAR oder system-config beim Plugin-
+   *  build. */
+  readonly webhookSecret: string;
+  /** Price-to-tier-Map. Plugin liest die price-id aus dem event und
+   *  mapped auf tier-name. Fehlt die price-id im Mapping → null. */
+  readonly priceToTier: Readonly<Record<string, string>>;
+};
+
+/**
+ * Stripe-webhook-handler. Implementiert den Plugin-Contract
+ * `verifyAndParseWebhook`. Closure über die `options` + den shared
+ * Stripe-Client (kein ctx-arg — das ist die Pre-tenant-resolution-Phase).
+ *
+ * **Shared Stripe-Client:** Der Caller (feature.ts) baut EINEN Stripe-
+ * Client beim mount und gibt ihn an alle vier plugin-methods weiter.
+ * Konstruktor-API-version-pin ist damit zentral; verify-webhook nutzt
+ * den client für `webhooks.constructEvent` (sig-verify) + lazy-fetch
+ * der invoice-events.
+ */
+export function verifyAndParseStripeWebhook(
+  stripe: Stripe,
+  options: StripeWebhookOptions,
+): (rawBody: string, headers: Record<string, string>) => Promise<SubscriptionEvent | null> {
+  return async (rawBody, headers) => {
+    const sigHeader = headers["stripe-signature"];
+    if (!sigHeader) {
+      throw new Error("subscription-stripe: stripe-signature header missing");
+    }
+
+    // 1. Sig-verify. constructEvent throws bei mismatch (= invalid sig)
+    //    oder timestamp-tolerance-violation (default 5min). Foundation
+    //    mapped throw → HTTP 401.
+    let event: Stripe.Event;
+    try {
+      event = stripe.webhooks.constructEvent(rawBody, sigHeader, options.webhookSecret);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`subscription-stripe: webhook signature verify failed — ${msg}`);
+    }
+
+    // 2. Event-type-Filter — wir kennen nur 5.
+    const normalizedType = mapStripeEventType(event.type);
+    if (!normalizedType) {
+      return null; // foundation returnt 200 ignored
+    }
+
+    // 3. Payload-extraction. Stripe liefert je nach event.type
+    //    verschiedene data.object-shapes. Wir extrahieren die
+    //    Subscription-Daten — entweder direkt (subscription-events)
+    //    oder via lazy-fetch (invoice-events, Phase 5.2b).
+    const sub = await extractSubscriptionFromEvent(event, stripe);
+    if (!sub) {
+      // event-type war unter den 5 (oben gefiltert), aber payload-shape
+      // matched nicht — Stripe-SDK-Schema-Drift, defensive null.
+      return null;
+    }
+
+    // 4. Tenant-resolution aus metadata. App-Builder setzt
+    //    `metadata.tenantId` beim createCheckoutSession-call.
+    const tenantId = sub.metadata?.["tenantId"];
+    if (!tenantId || tenantId.length === 0) {
+      // Subscription ohne tenant-metadata → kann kein subscription
+      // erstellen ohne tenant-resolution. Drop the event silent
+      // (foundation 200 ignored). App-Owner-Bug, nicht foundation-Bug.
+      return null;
+    }
+
+    // 5. Price-to-tier-Mapping. Stripe-subscription hat items[0].price.id.
+    const priceId = sub.items.data[0]?.price.id;
+    if (!priceId) {
+      return null;
+    }
+    const tier = options.priceToTier[priceId];
+    if (!tier) {
+      // Price-id nicht im Mapping → App-Owner hat den Stripe-price
+      // angelegt aber nicht zur tier zugeordnet. Drop silent.
+      return null;
+    }
+
+    // 6. Status-Mapping + period-end. Stripe hat den period-end seit
+    //    2024 vom subscription-level auf item-level migriert (=
+    //    subscription.items.data[i].current_period_end). Wir lesen
+    //    das vom ersten item; multi-item-subs (Add-Ons) sind kein
+    //    Phase-5-Scope.
+    const status = mapStripeStatus(sub.status);
+    const periodEndUnixSec = sub.items.data[0]?.current_period_end ?? 0;
+    // Stripe returns Unix-seconds; Temporal.Instant.fromEpochMilliseconds
+    // expects ms. Multiply, then ISO. (No-Date-API-Guard verbietet
+    // `new Date()` — Temporal ist global verfügbar via polyfill.)
+    const currentPeriodEnd = Temporal.Instant.fromEpochMilliseconds(
+      periodEndUnixSec * 1000,
+    ).toString();
+
+    return {
+      providerEventId: event.id,
+      providerName: STRIPE_PROVIDER_NAME,
+      type: normalizedType,
+      tenantId,
+      providerCustomerId: typeof sub.customer === "string" ? sub.customer : sub.customer.id,
+      providerSubscriptionId: sub.id,
+      status,
+      tier,
+      currentPeriodEnd,
+      rawPayload: JSON.stringify(event),
+    };
+  };
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Stripe-event-type → normalisiert. null = ignore. */
+export function mapStripeEventType(stripeType: string): SubscriptionEventType | null {
+  switch (stripeType) {
+    case StripeEventTypes.customerSubscriptionCreated:
+      return SubscriptionEventTypes.created;
+    case StripeEventTypes.customerSubscriptionUpdated:
+      return SubscriptionEventTypes.updated;
+    case StripeEventTypes.customerSubscriptionDeleted:
+      return SubscriptionEventTypes.canceled;
+    case StripeEventTypes.invoicePaid:
+      return SubscriptionEventTypes.invoicePaid;
+    case StripeEventTypes.invoicePaymentFailed:
+      return SubscriptionEventTypes.invoicePaymentFailed;
+    default:
+      return null;
+  }
+}
+
+/** Stripe-status → normalisiert. Defensive: unbekannte Status →
+ *  incomplete (Plugin sollte das nicht erreichen, aber wir wollen
+ *  kein ungültiger status-string in der DB). */
+export function mapStripeStatus(stripeStatus: Stripe.Subscription.Status): SubscriptionStatus {
+  switch (stripeStatus) {
+    case "active":
+      return SubscriptionStatuses.active;
+    case "trialing":
+      return SubscriptionStatuses.trialing;
+    case "past_due":
+    case "unpaid":
+    case "paused":
+      return SubscriptionStatuses.pastDue;
+    case "canceled":
+      return SubscriptionStatuses.canceled;
+    case "incomplete":
+    case "incomplete_expired":
+      return SubscriptionStatuses.incomplete;
+    default:
+      return SubscriptionStatuses.incomplete;
+  }
+}
+
+/** Holt die Subscription aus dem Event. Subscription-events haben sie
+ *  direkt im data.object; invoice-events haben nur die subscription-id
+ *  und brauchen einen lazy-fetch via stripe.subscriptions.retrieve
+ *  (Phase 5.2b). */
+async function extractSubscriptionFromEvent(
+  event: Stripe.Event,
+  stripe: Stripe,
+): Promise<Stripe.Subscription | null> {
+  switch (event.type) {
+    case StripeEventTypes.customerSubscriptionCreated:
+    case StripeEventTypes.customerSubscriptionUpdated:
+    case StripeEventTypes.customerSubscriptionDeleted:
+      return event.data.object as Stripe.Subscription;
+    case StripeEventTypes.invoicePaid:
+    case StripeEventTypes.invoicePaymentFailed: {
+      // Lazy-fetch der subscription. invoice.subscription ist eine
+      // string-id (Stripe-Webhooks expanden nicht auto). Wir holen das
+      // full subscription-Object damit der downstream-mapping
+      // (status, tier via priceId, period-end) konsistent funktioniert.
+      const invoice = event.data.object as Stripe.Invoice;
+      const subRef = (invoice as { subscription?: string | Stripe.Subscription | null })
+        .subscription;
+      if (!subRef) {
+        // Invoice ohne subscription-reference (= one-shot-invoice, nicht
+        // recurring). Nicht unsere Domain — ignorieren.
+        return null;
+      }
+      const subId = typeof subRef === "string" ? subRef : subRef.id;
+      try {
+        return await stripe.subscriptions.retrieve(subId);
+      } catch {
+        // Stripe-API-failure beim retrieve (z.B. subscription gelöscht
+        // zwischen webhook + retrieve). Defensive: null returnen, damit
+        // foundation 200 ignored returnt — der nächste subscription-
+        // event wird's korrekt handhaben.
+        return null;
+      }
+    }
+    default:
+      return null;
+  }
+}