@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/billing-foundation/types.ts

@@ -0,0 +1,157 @@
+// Plugin-Contract + Domain-Types der subscription-foundation. Provider-
+// Plugins (subscription-stripe, subscription-mollie, ...) implementieren
+// `SubscriptionProviderPlugin` und registrieren via
+// `r.useExtension("subscriptionProvider", "<name>", { build })`.
+//
+// **Two-phase plugin contract:**
+//   1. **Pre-tenant-resolution:** `verifyAndParseWebhook` läuft BEVOR
+//      ein Tenant aus dem Event aufgelöst ist — kein HandlerContext
+//      verfügbar. Plugin liest seinen webhook-secret aus
+//      module-load-Closure (ENV-VAR oder system-config), NICHT aus
+//      ctx. **Webhook-secret ist app-wide**, nicht per-tenant — das
+//      ist App-Owner's Stripe-/PayPal-Account, nicht Tenant-Sache.
+//   2. **Post-tenant-resolution:** `createPortalSession` +
+//      `cancelSubscription` werden aus regulären write-handlern
+//      gerufen mit voll-aufgelöstem HandlerContext. Plugin kann
+//      hier ctx.config + ctx.secrets nutzen für tenant-spezifische
+//      Konfiguration (z.B. tenant-eigene customer-id-mapping).
+//
+// Foundation nutzt nur den common-subset der Provider-Funktionalität —
+// proration, multi-currency, coupons etc. bleiben provider-spezifisch
+// und sind über den Customer-Portal-Link erreichbar.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import type { SubscriptionEventType, SubscriptionStatus } from "./constants";
+
+// =============================================================================
+// Normalisierter Webhook-Event
+// =============================================================================
+//
+// Der Plugin parsed den raw provider-payload und liefert diese Form
+// zurück. Foundation kennt KEINE Stripe-/Mollie-types direkt — der
+// Plugin abstrahiert.
+
+export type SubscriptionEvent = {
+  /** Provider-eigene Event-ID — UNIQUE-key für Idempotency.
+   *  Stripe: "evt_..."; Mollie: payment-id oder subscription-id. */
+  readonly providerEventId: string;
+  /** Discriminator — welcher Plugin diesen Event geliefert hat. */
+  readonly providerName: string;
+  /** Normalisierter Event-Type. Plugin filtert provider-spezifische
+   *  Sub-Types raus (Stripe hat ~80 Event-types, wir kennen 5). */
+  readonly type: SubscriptionEventType;
+  /** Plattform-Tenant-ID (provider-customer-metadata oder lookup
+   *  via providerCustomerId). Plugin macht die resolution. */
+  readonly tenantId: string;
+  /** Provider-eigene customer-id für späteren Lookup bei events
+   *  ohne metadata. */
+  readonly providerCustomerId: string;
+  /** Provider-eigene subscription-id. */
+  readonly providerSubscriptionId: string;
+  /** Normalisierter status. */
+  readonly status: SubscriptionStatus;
+  /** Resolved tier — Plugin liest die price-id aus dem event und
+   *  mapped via plugin-eigenem `<plugin>:config:price-to-tier` auf
+   *  einen tier-name. Wenn der price-id im Mapping fehlt, returnt
+   *  der Plugin null aus verifyAndParseWebhook (= "unknown event,
+   *  ignore"). */
+  readonly tier: string;
+  /** ISO-timestamp wann die aktuelle Billing-Period endet. */
+  readonly currentPeriodEnd: string;
+  /** Raw provider-payload — wird 1:1 in subscription-event.rawPayload
+   *  archiviert. Plugin liefert das als JSON-stringified-string. */
+  readonly rawPayload: string;
+};
+
+// =============================================================================
+// Plugin-Contract
+// =============================================================================
+
+export type SubscriptionProviderPlugin = {
+  /**
+   * Verify webhook signature + parse provider-event into normalized
+   * form. **Pre-tenant-resolution** — kein HandlerContext, weil zum
+   * Zeitpunkt des sig-verify der Tenant noch nicht aufgelöst ist
+   * (Plugin macht die Tenant-Resolution selbst aus dem provider-
+   * payload metadata).
+   *
+   * Plugin liest seinen webhook-secret aus module-load-Closure
+   * (process.env.STRIPE_WEBHOOK_SECRET oder system-config), NICHT
+   * aus ctx. App-wide-secret = App-Owner's eigener Provider-Account.
+   *
+   * Returns null für events die der Plugin nicht versteht oder die
+   * foundation nicht braucht (= filter out, foundation returnt 200
+   * "ignored").
+   *
+   * **Throws** bei sig-mismatch — der webhook-handler mapped das auf
+   * 401 damit der Provider keine retries macht (sig-fail = config-bug,
+   * nicht transient).
+   */
+  readonly verifyAndParseWebhook: (
+    rawBody: string,
+    headers: Record<string, string>,
+  ) => Promise<SubscriptionEvent | null>;
+
+  /**
+   * **Post-tenant-resolution** — wird aus dem
+   * `create-checkout-session`-write-handler gerufen. Plugin baut
+   * eine provider-eigene checkout-session und returnt die hosted-
+   * page-URL — Tenant-Admin wird dorthin redirected, schließt den
+   * Bezahl-Flow ab, Provider sendet `subscription.created`-webhook
+   * mit `metadata.tenantId` zurück.
+   *
+   * Optional: Apple-IAP hat keinen Web-Checkout (alles in der App).
+   * Apps die ausschließlich Apple-IAP nutzen lassen das weg.
+   */
+  readonly createCheckoutSession?: (
+    ctx: HandlerContext,
+    options: {
+      /** Provider-eigene price/plan-ID die der Endkunde abonniert. */
+      readonly priceId: string;
+      /** Plattform-Tenant-ID — landet als metadata im checkout-session
+       *  damit der subsequent webhook den tenant resolved (siehe
+       *  `verifyAndParseWebhook`'s metadata.tenantId-lookup). */
+      readonly tenantId: string;
+      /** Wo der Endkunde nach erfolgreichem checkout landed. */
+      readonly successUrl: string;
+      /** Wo der Endkunde landed wenn er abbricht. */
+      readonly cancelUrl: string;
+      /** Optional: existierende provider-customer-id wenn der Tenant
+       *  schon einen Account beim Provider hat. Sonst legt der Provider
+       *  beim checkout einen neuen customer an. */
+      readonly providerCustomerId?: string;
+    },
+  ) => Promise<{ readonly url: string }>;
+
+  /**
+   * **Post-tenant-resolution** — wird aus einem write-handler gerufen
+   * mit voll-aufgelöstem ctx. Erstellt einen self-service Portal-Link.
+   * Stripe: customer-portal-session, Mollie: hosted-management-page.
+   * Tenant-Admin klickt darauf um Subscription selbst zu verwalten
+   * (cancel, payment-method, ...).
+   *
+   * Optional weil nicht jeder Provider einen Portal-Pattern hat
+   * (Apple-IAP managed Subs in der Apple-App, kein Web-Portal).
+   * Plugin der das nicht supported kann das Field weglassen — foundation
+   * returnt dann "portal_not_supported"-error wenn ein Tenant-Admin
+   * den Portal-Link anfordert.
+   */
+  readonly createPortalSession?: (
+    ctx: HandlerContext,
+    options: {
+      readonly providerCustomerId: string;
+      readonly returnUrl: string;
+    },
+  ) => Promise<{ readonly url: string }>;
+
+  /**
+   * Optional: Cancel-aus-der-App-API. Wenn nicht implementiert, kann
+   * der Tenant nur über den Customer-Portal-Link cancellen (oder gar
+   * nicht, wenn auch createPortalSession fehlt — dann ist
+   * Cancel-Flow Provider-Dashboard-only).
+   */
+  readonly cancelSubscription?: (
+    ctx: HandlerContext,
+    providerSubscriptionId: string,
+  ) => Promise<void>;
+};

package/src/billing-foundation/webhook-handler.ts

@@ -0,0 +1,184 @@
+// createSubscriptionWebhookHandler — Hono-route-factory den der App-
+// Owner via `extraRoutes` in seinem bin/server.ts mountet.
+//
+// **Multi-Provider:** der Plugin wird via Pfad-Parameter
+// `:providerName` ausgewählt — Stripe-Dashboard zeigt auf
+// `/api/subscription/webhook/stripe`, PayPal auf
+// `/api/subscription/webhook/paypal`. Eine Hono-Route, alle Plugins
+// gleichzeitig aktiv.
+//
+// Beispiel-Verwendung in bin/server.ts:
+//
+//   await runDevApp({
+//     features: APP_FEATURES,
+//     extraRoutes: (app, deps) => {
+//       const handler = createSubscriptionWebhookHandler(deps);
+//       app.post("/api/subscription/webhook/:providerName", handler);
+//     },
+//   });
+//
+// Was der handler macht:
+//   1. providerName aus dem URL-Pfad lesen
+//   2. raw-body via c.req.text() lesen (NICHT JSON-parsen — Stripe-Sig
+//      prüft exakte bytes)
+//   3. Headers sammeln + an Plugin durchreichen
+//   4. Plugin-Lookup im Registry via "subscriptionProvider"-extension
+//      und dem providerName aus dem URL-Pfad
+//   5. plugin.verifyAndParseWebhook(raw, headers, ctx) → SubscriptionEvent | null
+//   6. Bei null (= Plugin filtert event-type raus): 200 OK ohne side-effects
+//   7. Bei Event: ctx.write("billing-foundation:write:process-event")
+//      mit der vom Plugin aufgelösten tenantId
+//   8. Returnt 200 OK an Provider
+//
+// **Auth:** kein JWT/Cookie. Authentifizierung läuft via Provider-
+// Webhook-Sig im Plugin. Kein `c.get("user")`-call hier.
+
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { Context, Hono } from "hono";
+import {
+  BILLING_FOUNDATION_FEATURE,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  SubscriptionFoundationHandlers,
+} from "./constants";
+import type { SubscriptionProviderPlugin } from "./types";
+
+/**
+ * Dependencies the App-Owner gibt dem webhook-handler. Identisch zum
+ * `extraRoutes`-Callback-Argument-shape von runDevApp/runProdApp.
+ */
+export type SubscriptionWebhookDeps = {
+  /** Schreibt durch den Standard-Dispatcher mit einem auto-konstruierten
+   *  SystemUser. Muss `process-event` als SystemAdmin durchlassen. */
+  readonly dispatchWrite: (args: {
+    readonly handlerQn: string;
+    readonly payload: unknown;
+    readonly tenantId: string;
+  }) => Promise<{
+    readonly isSuccess: boolean;
+    readonly data?: unknown;
+    readonly error?: unknown;
+  }>;
+
+  /** Plugin-Lookup-Function — bekommt den providerName aus dem URL-
+   *  Pfad und returnt den passenden Plugin (= entityName-match in
+   *  registry.getExtensionUsages("subscriptionProvider")). */
+  readonly resolveProvider: (providerName: string) => SubscriptionProviderPlugin | undefined;
+};
+
+/**
+ * Returnt einen Hono-handler. Mounten via
+ * `app.post("/api/subscription/webhook/:providerName", handler)`.
+ */
+export function createSubscriptionWebhookHandler(deps: SubscriptionWebhookDeps) {
+  return async (c: Context): Promise<Response> => {
+    // 1. providerName aus URL-Pfad. Hono-Standard via c.req.param.
+    const providerName = c.req.param("providerName");
+    if (!providerName || providerName.length === 0) {
+      return c.json(
+        {
+          error: {
+            code: "subscription_provider_path_missing",
+            message: `${BILLING_FOUNDATION_FEATURE}: Mount the route as POST /api/subscription/webhook/:providerName so each provider has its own URL (Stripe-Dashboard → /stripe, PayPal-Dashboard → /paypal).`,
+          },
+        },
+        400,
+      );
+    }
+
+    // 2. Raw-body. Provider-Sigs werden gegen die exakten bytes verifiziert.
+    const rawBody = await c.req.text();
+    const headers: Record<string, string> = {};
+    c.req.raw.headers.forEach((value, key) => {
+      headers[key.toLowerCase()] = value;
+    });
+
+    // 3. Plugin-Lookup via path-segment. Jeder gemountete Plugin hat
+    //    sich mit `r.useExtension("subscriptionProvider", entityName,
+    //    {...})` registriert; entityName matcht hier den path-segment.
+    const plugin = deps.resolveProvider(providerName);
+    if (!plugin) {
+      return c.json(
+        {
+          error: {
+            code: "subscription_provider_not_registered",
+            message: `${BILLING_FOUNDATION_FEATURE}: provider "${providerName}" not registered as '${SUBSCRIPTION_PROVIDER_EXTENSION}'-plugin. Mount the matching subscription-${providerName} feature.`,
+          },
+        },
+        404,
+      );
+    }
+
+    // 4. Plugin verifies + parses. **Pre-tenant-resolution** — kein
+    //    ctx, Plugin liest seinen webhook-secret aus eigener
+    //    module-load-Closure (ENV-VAR oder system-config).
+    //    Throws on sig-mismatch — wir mappen auf 401 (= "config-bug,
+    //    retry won't help, Provider stopp").
+    let parsed: Awaited<ReturnType<SubscriptionProviderPlugin["verifyAndParseWebhook"]>>;
+    try {
+      parsed = await plugin.verifyAndParseWebhook(rawBody, headers);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return c.json(
+        {
+          error: {
+            code: "subscription_webhook_signature_invalid",
+            message: `Plugin "${providerName}" rejected webhook: ${msg}`,
+          },
+        },
+        401,
+      );
+    }
+
+    // 5. Plugin returned null = "ich kenne diesen event-type nicht / ist
+    //    nicht relevant". 200 OK damit der Provider keine retries macht.
+    if (parsed === null) {
+      return c.json({ ignored: true }, 200);
+    }
+
+    // 6. Dispatch process-event-handler durch den Standard-Dispatcher.
+    //    Idempotency macht der handler intern via deterministic
+    //    aggregate-id + UNIQUE-constraint.
+    const dispatched = await deps.dispatchWrite({
+      handlerQn: SubscriptionFoundationHandlers.processEvent,
+      tenantId: parsed.tenantId,
+      payload: {
+        providerEventId: parsed.providerEventId,
+        providerName: parsed.providerName,
+        type: parsed.type,
+        providerCustomerId: parsed.providerCustomerId,
+        providerSubscriptionId: parsed.providerSubscriptionId,
+        status: parsed.status,
+        tier: parsed.tier,
+        currentPeriodEndIso: parsed.currentPeriodEnd,
+        rawPayload: parsed.rawPayload,
+      },
+    });
+
+    if (!dispatched.isSuccess) {
+      // Internal error — Provider soll retry'n. 500 statt 401/404 weil
+      // das transient ist (DB down etc.) nicht config-bug.
+      return c.json(
+        {
+          error: {
+            code: "subscription_webhook_processing_failed",
+            message: "Internal error processing subscription event",
+            details: dispatched.error,
+          },
+        },
+        500,
+      );
+    }
+
+    return c.json({ processed: true, ...((dispatched.data as object) ?? {}) }, 200);
+  };
+}
+
+/**
+ * Convenience für TypeScript-IDE: `Hono.post(...)`-Call-Type damit der
+ * App-Owner-Code typed bleibt ohne Hono-types zu importieren.
+ */
+export type SubscriptionWebhookHandler = ReturnType<typeof createSubscriptionWebhookHandler>;
+
+// Re-export für convenience: App-Owner kann den TenantId-type aus dem
+// gleichen Modul importieren (vermeidet ein zweites Framework-import).
+export type { Hono, TenantId };