@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/billing-foundation/__tests__/feature.test.ts

@@ -0,0 +1,110 @@
+// feature.ts contract tests for subscription-foundation.
+
+import { describe, expect, test } from "vitest";
+import { subscriptionAggregateId } from "../aggregate-id";
+import {
+  BILLING_FOUNDATION_FEATURE,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  SubscriptionEventTypes,
+  SubscriptionFoundationHandlers,
+  SubscriptionStatuses,
+} from "../constants";
+import { billingFoundationFeature } from "../feature";
+
+describe("billingFoundationFeature — shape", () => {
+  test("has the expected name", () => {
+    expect(billingFoundationFeature.name).toBe(BILLING_FOUNDATION_FEATURE);
+    // Naming-Disziplin pin: NICHT "billing-foundation" — damit
+    // marketplace-foundation später ohne Rename dazukommt (siehe
+    // docs/plans/architecture/subscription-foundation.md).
+    expect(billingFoundationFeature.name).toBe("billing-foundation");
+  });
+
+  test("does NOT require config (Multi-Provider — config liegt in den Plugins)", () => {
+    // Drift-Pin: foundation hat KEIN globales `provider`-config-key
+    // mehr. Webhook-URL trägt providerName als Pfad-Parameter, jeder
+    // gemountete Plugin ist gleichzeitig aktiv. Wenn jemand wieder
+    // `r.requires("config")` einbaut, verstößt das gegen die
+    // Multi-Provider-Architektur.
+    expect(billingFoundationFeature.requires).not.toContain("config");
+  });
+
+  test("does NOT require secrets — Provider-Plugins owne ihre eigenen API-Keys", () => {
+    expect(billingFoundationFeature.requires).not.toContain("secrets");
+  });
+
+  test("foundation has NO config-keys (alle config-keys liegen in den Plugins)", () => {
+    // Multi-Provider-Drift-Pin: foundation darf keine config-keys
+    // exportieren weil sonst sowas wie "globaler price-to-tier-Map"
+    // erzwungen wäre — der existiert NUR pro Plugin (Stripe-priceIds
+    // vs PayPal-plan-ids vs Apple-product-ids sind verschieden).
+    expect(Object.keys(billingFoundationFeature.configKeys)).toHaveLength(0);
+  });
+});
+
+describe("billingFoundationFeature — registers extension-point", () => {
+  test("declares 'subscriptionProvider' extension-point", () => {
+    expect(
+      billingFoundationFeature.registrarExtensions[SUBSCRIPTION_PROVIDER_EXTENSION],
+    ).toBeDefined();
+  });
+});
+
+describe("billingFoundationFeature — events + projection + handlers registered", () => {
+  test("5 domain-events registriert (created/updated/canceled/invoice-paid/invoice-payment-failed)", () => {
+    const events = billingFoundationFeature.events;
+    expect(events["subscription-created"]).toBeDefined();
+    expect(events["subscription-updated"]).toBeDefined();
+    expect(events["subscription-canceled"]).toBeDefined();
+    expect(events["invoice-paid"]).toBeDefined();
+    expect(events["invoice-payment-failed"]).toBeDefined();
+  });
+
+  test("subscription-projection registriert mit 5 apply-keys", () => {
+    const proj = billingFoundationFeature.projections["subscription"];
+    expect(proj).toBeDefined();
+    const applyKeys = Object.keys(proj?.apply ?? {});
+    expect(applyKeys).toHaveLength(5);
+  });
+
+  test("process-event write-handler registriert mit erwarteter QN", () => {
+    expect(billingFoundationFeature.writeHandlers["process-event"]).toBeDefined();
+    expect(SubscriptionFoundationHandlers.processEvent).toBe(
+      "billing-foundation:write:process-event",
+    );
+  });
+
+  test("process-event ist SystemAdmin-only (programmatic-only entry-point)", () => {
+    const handler = billingFoundationFeature.writeHandlers["process-event"];
+    const access = handler?.access as { roles?: readonly string[] } | undefined;
+    expect(access?.roles).toEqual(["SystemAdmin"]);
+  });
+});
+
+describe("aggregate-id namespace — drift-pin", () => {
+  test("subscriptionAggregateId stable per tenantId", () => {
+    expect(subscriptionAggregateId("tenant-1")).toBe("bfe0d98f-293c-5215-af7a-3282629aa5d3");
+  });
+});
+
+describe("normalized constants — provider-agnostic event-types + statuses", () => {
+  test("EventTypes whitelist — was die Foundation kennt", () => {
+    expect(Object.values(SubscriptionEventTypes)).toEqual([
+      "subscription.created",
+      "subscription.updated",
+      "subscription.canceled",
+      "invoice.paid",
+      "invoice.payment-failed",
+    ]);
+  });
+
+  test("Statuses normalized über Stripe + Mollie", () => {
+    expect(Object.values(SubscriptionStatuses)).toEqual([
+      "active",
+      "trialing",
+      "past_due",
+      "canceled",
+      "incomplete",
+    ]);
+  });
+});

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

@@ -0,0 +1,199 @@
+// Unit-Tests für createSubscriptionWebhookHandler. Treibt alle 5
+// HTTP-Pfade durch (400/401/404/500 + 200) via Hono `app.request()` —
+// ohne setupTestStack, weil der webhook-handler nur über die deps-
+// injection geht und keinen DB-roundtrip braucht.
+
+import { Hono } from "hono";
+import { describe, expect, test, vi } from "vitest";
+import { SubscriptionEventTypes, SubscriptionStatuses } from "../constants";
+import type { SubscriptionEvent, SubscriptionProviderPlugin } from "../types";
+import { createSubscriptionWebhookHandler, type SubscriptionWebhookDeps } from "../webhook-handler";
+
+// =============================================================================
+// Test-helpers
+// =============================================================================
+
+function buildEvent(): SubscriptionEvent {
+  return {
+    providerEventId: "evt_test_001",
+    providerName: "stripe",
+    type: SubscriptionEventTypes.created,
+    tenantId: "tenant-test",
+    providerCustomerId: "cus_test",
+    providerSubscriptionId: "sub_test",
+    status: SubscriptionStatuses.active,
+    tier: "pro",
+    currentPeriodEnd: "2026-06-01T00:00:00Z",
+    rawPayload: '{"raw":"payload"}',
+  };
+}
+
+function buildPlugin(
+  overrides: Partial<SubscriptionProviderPlugin> = {},
+): SubscriptionProviderPlugin {
+  return {
+    verifyAndParseWebhook: async () => buildEvent(),
+    ...overrides,
+  };
+}
+
+function buildDeps(overrides: Partial<SubscriptionWebhookDeps> = {}): SubscriptionWebhookDeps {
+  return {
+    dispatchWrite: async () => ({ isSuccess: true, data: { duplicate: false } }),
+    resolveProvider: () => buildPlugin(),
+    ...overrides,
+  };
+}
+
+function buildApp(deps: SubscriptionWebhookDeps) {
+  const app = new Hono();
+  app.post("/api/subscription/webhook/:providerName", createSubscriptionWebhookHandler(deps));
+  return app;
+}
+
+async function postWebhook(app: Hono, providerName: string, body = '{"id":"evt_test"}') {
+  return app.request(`/api/subscription/webhook/${providerName}`, {
+    method: "POST",
+    body,
+    headers: { "stripe-signature": "test_sig" },
+  });
+}
+
+// =============================================================================
+// Happy path — 200 OK + processed
+// =============================================================================
+
+describe("webhook-handler — happy path", () => {
+  test("verifyAndParseWebhook → SubscriptionEvent → dispatchWrite → 200 processed", async () => {
+    const dispatchWrite = vi.fn(async () => ({
+      isSuccess: true,
+      data: { duplicate: false, eventAggregateId: "evt-id" },
+    }));
+    const app = buildApp(buildDeps({ dispatchWrite }));
+
+    const res = await postWebhook(app, "stripe");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { processed: boolean; duplicate: boolean };
+    expect(body.processed).toBe(true);
+    expect(body.duplicate).toBe(false);
+
+    expect(dispatchWrite).toHaveBeenCalledExactlyOnceWith(
+      expect.objectContaining({
+        handlerQn: "billing-foundation:write:process-event",
+        tenantId: "tenant-test",
+        payload: expect.objectContaining({
+          providerEventId: "evt_test_001",
+          providerName: "stripe",
+          type: "subscription.created",
+          tier: "pro",
+        }),
+      }),
+    );
+  });
+
+  test("plugin returns null (= unbekannter event-type) → 200 ignored, kein dispatch", async () => {
+    const dispatchWrite = vi.fn();
+    const plugin = buildPlugin({ verifyAndParseWebhook: async () => null });
+    const app = buildApp(buildDeps({ dispatchWrite, resolveProvider: () => plugin }));
+
+    const res = await postWebhook(app, "stripe");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ignored: boolean };
+    expect(body.ignored).toBe(true);
+    expect(dispatchWrite).not.toHaveBeenCalled();
+  });
+});
+
+// =============================================================================
+// Error paths — 400/401/404/500
+// =============================================================================
+
+describe("webhook-handler — error paths", () => {
+  test("provider not registered → 404 mit subscription_provider_not_registered", async () => {
+    const app = buildApp(buildDeps({ resolveProvider: () => undefined }));
+
+    const res = await postWebhook(app, "ghost");
+    expect(res.status).toBe(404);
+    // Drift-Pin: error-code stable damit Stripe-/Mollie-retry-Logik
+    // sich auf den Code verlassen kann.
+    const body = (await res.json()) as { error: { code: string; message: string } };
+    expect(body.error.code).toBe("subscription_provider_not_registered");
+    expect(body.error.message).toMatch(/ghost/);
+  });
+
+  test("plugin throws beim sig-verify → 401 mit subscription_webhook_signature_invalid", async () => {
+    const plugin = buildPlugin({
+      verifyAndParseWebhook: async () => {
+        throw new Error("HMAC mismatch — wrong webhook secret?");
+      },
+    });
+    const app = buildApp(buildDeps({ resolveProvider: () => plugin }));
+
+    const res = await postWebhook(app, "stripe");
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string; message: string } };
+    expect(body.error.code).toBe("subscription_webhook_signature_invalid");
+    expect(body.error.message).toMatch(/HMAC mismatch/);
+  });
+
+  test("dispatchWrite returns isSuccess: false → 500 mit subscription_webhook_processing_failed", async () => {
+    const dispatchWrite = vi.fn(async () => ({
+      isSuccess: false,
+      error: { code: "internal_error", message: "DB unavailable" },
+    }));
+    const app = buildApp(buildDeps({ dispatchWrite }));
+
+    const res = await postWebhook(app, "stripe");
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as {
+      error: { code: string; message: string; details: unknown };
+    };
+    expect(body.error.code).toBe("subscription_webhook_processing_failed");
+    // Provider sees 500 + retries — that's the design (transient failure).
+    expect(body.error.details).toMatchObject({ code: "internal_error" });
+  });
+});
+
+// =============================================================================
+// Mounting-Pattern
+// =============================================================================
+
+describe("webhook-handler — Mounting-Pattern", () => {
+  test("Multi-Provider: zwei verschiedene URL-Pfade → unterschiedliche plugins", async () => {
+    // Drift-Pin für die Multi-Provider-Architektur: stripe-Plugin hat
+    // einen anderen verifyAndParseWebhook als paypal-Plugin. Wenn ein
+    // Refactor den path-segment-Lookup auf etwas anderes umstellt
+    // (z.B. globaler config-key wieder), würde dieser Test failen.
+    const stripeCalls: string[] = [];
+    const paypalCalls: string[] = [];
+    const stripePlugin = buildPlugin({
+      verifyAndParseWebhook: async () => {
+        stripeCalls.push("called");
+        return buildEvent();
+      },
+    });
+    const paypalPlugin = buildPlugin({
+      verifyAndParseWebhook: async () => {
+        paypalCalls.push("called");
+        return { ...buildEvent(), providerName: "paypal", providerEventId: "I-PAYPAL-001" };
+      },
+    });
+    const app = buildApp(
+      buildDeps({
+        resolveProvider: (name) => {
+          if (name === "stripe") return stripePlugin;
+          if (name === "paypal") return paypalPlugin;
+          return undefined;
+        },
+      }),
+    );
+
+    const stripeRes = await postWebhook(app, "stripe");
+    const paypalRes = await postWebhook(app, "paypal");
+
+    expect(stripeRes.status).toBe(200);
+    expect(paypalRes.status).toBe(200);
+    expect(stripeCalls).toHaveLength(1);
+    expect(paypalCalls).toHaveLength(1);
+  });
+});

package/src/billing-foundation/aggregate-id.ts

@@ -0,0 +1,21 @@
+import { v5 as uuidv5 } from "uuid";
+
+// Fixed UUID-namespace für die deterministic aggregate-id-Ableitung.
+// Generiert einmalig (2026-05-03), in Stein gemeißelt: ein Wechsel
+// würde jeden existing aggregate-Stream re-keyen → kaputter
+// Subscription-State, kaputte Audit-History. Drift-Pin in
+// __tests__/feature.test.ts pinnt die UUID.
+
+/** Pro Plattform-Tenant existiert genau EIN subscription-Aggregate. */
+const SUBSCRIPTION_NAMESPACE = "5c3b2d1e-9a4f-4e8c-b7a3-1f8d6c2e9a4b";
+
+/**
+ * Deterministic aggregate-id für die subscription eines Plattform-
+ * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
+ * derselben subscription, nicht eigene). Provider-Wechsel (z.B.
+ * Stripe→Mollie-Migration) appended einen neuen event auf denselben
+ * Stream — selber Tenant, selber Aggregate-Stream.
+ */
+export function subscriptionAggregateId(tenantId: string): string {
+  return uuidv5(tenantId, SUBSCRIPTION_NAMESPACE);
+}

package/src/billing-foundation/constants.ts

@@ -0,0 +1,70 @@
+// Feature name
+export const BILLING_FOUNDATION_FEATURE = "billing-foundation" as const;
+
+// Extension-point name fuer Provider-Plugins (subscription-stripe,
+// subscription-mollie, ...).
+export const SUBSCRIPTION_PROVIDER_EXTENSION = "subscriptionProvider" as const;
+
+// Qualified write handler names (QN format: scope:type:name).
+export const SubscriptionFoundationHandlers = {
+  /** Programmatic entry-point für den webhook-handler. Receives the
+   *  parsed SubscriptionEvent (vom Plugin schon verifiziert) + macht
+   *  insert-event + upsert-subscription + tier-sync atomic. */
+  processEvent: "billing-foundation:write:process-event",
+  /** Tenant-Admin klickt "Upgrade to Pro" → handler findet den
+   *  gewählten provider-plugin + ruft seine createCheckoutSession-
+   *  Methode + returnt die hosted-page-URL. Tenant-Admin wird dorthin
+   *  redirected, der subsequent provider-webhook erstellt die
+   *  subscription. */
+  createCheckoutSession: "billing-foundation:write:create-checkout-session",
+  /** Tenant-Admin klickt "Manage Subscription" → handler findet
+   *  current subscription, ruft plugin.createPortalSession, returnt
+   *  hosted-portal-URL. */
+  createPortalSession: "billing-foundation:write:create-portal-session",
+} as const;
+
+// Qualified query handler names.
+export const SubscriptionFoundationQueries = {
+  /** Sysadmin-cross-tenant + tenant-scoped self-list auf der
+   *  read_subscriptions-projection. Tenant-Admin sieht via ctx.db
+   *  tenant-scoping nur die eigene row. */
+  listSubscriptions: "billing-foundation:query:subscription:list",
+} as const;
+
+// Normalized subscription-event types — provider-agnostic.
+// Alle Provider-Plugins normalisieren ihre eigenen event-types auf einen
+// dieser. Whitelist: was die Foundation kennt; alles andere muss der
+// Plugin filtern und null returnen aus verifyAndParseWebhook.
+export const SubscriptionEventTypes = {
+  created: "subscription.created",
+  updated: "subscription.updated",
+  canceled: "subscription.canceled",
+  invoicePaid: "invoice.paid",
+  invoicePaymentFailed: "invoice.payment-failed",
+} as const;
+export type SubscriptionEventType =
+  (typeof SubscriptionEventTypes)[keyof typeof SubscriptionEventTypes];
+
+// Normalized subscription-status values — provider-agnostic.
+// Stripe + Mollie haben verschiedene Status-Sets; Plugin mapped auf
+// diesen common-subset.
+export const SubscriptionStatuses = {
+  active: "active",
+  trialing: "trialing",
+  pastDue: "past_due",
+  canceled: "canceled",
+  incomplete: "incomplete",
+} as const;
+export type SubscriptionStatus = (typeof SubscriptionStatuses)[keyof typeof SubscriptionStatuses];
+
+// **Multi-Provider von Tag 1:** subscription-foundation hat KEIN
+// `provider`-config-key. Alle gemounteten Plugins sind aktiv parallel —
+// der Endkunde wählt beim Subscribe-Klick zwischen Karte/PayPal/
+// Apple-Pay/Klarna/SEPA (Disney+-Pattern). Welcher Provider die
+// aktuelle subscription des Tenants gerade hält steht in
+// subscription.providerName, kommt aus dem checkout-flow.
+//
+// price-to-tier-Map ist KEIN foundation-config — pro-Plugin, weil
+// Stripe-priceIds vs PayPal-plan-ids vs Apple-product-ids
+// unterschiedliche IDs sind. Jeder Plugin definiert seinen eigenen
+// `<plugin-name>:config:price-to-tier`-Key.

package/src/billing-foundation/entities.ts

@@ -0,0 +1,50 @@
+import {
+  createEntity,
+  createTextField,
+  createTimestampField,
+} from "@cosmicdrift/kumiko-framework/engine";
+
+// =============================================================================
+// `subscription` — current state pro Plattform-Tenant (= Read-Model)
+// =============================================================================
+//
+// Inline-Projection-Target. Geschrieben vom `subscription`-projection-
+// apply (siehe feature.ts), NIE direkt vom handler. Source-of-truth ist
+// der event-store stream `subscription` mit aggregate-id =
+// uuidv5(SUBSCRIPTION_NAMESPACE, tenantId).
+//
+// EINE Row pro Plattform-Tenant. Aggregate-ID ist deterministic, damit
+// Webhook-Replays (Stripe sendet bei Hängern bis zu 5x in 4h) auf
+// denselben Stream schreiben statt zwei Rows zu erzeugen.
+//
+// **Felder:**
+//   - providerName: "stripe" / "mollie" — welcher Provider die
+//     Subscription hält. Provider-Wechsel = neuer event auf demselben
+//     Stream, projection überschreibt.
+//   - providerCustomerId / providerSubscriptionId: provider-eigene
+//     IDs.
+//   - status: active / past_due / canceled / trialing / incomplete —
+//     normalisiert über provider-grenzen hinweg.
+//   - tier: "free" / "pro" / ... — vom tier-engine konsumiert. Aus
+//     price-to-tier-Map resolved im Plugin.
+//   - currentPeriodEnd: wann läuft die aktuelle Billing-Period aus.
+//
+// **Was hier NICHT ist:**
+//   - invoice-history, payment-method, line-items, tax-info → all das
+//     fetcht der Tenant via customer-portal-session direkt vom Provider.
+//   - cancelAt, cancelAtPeriodEnd → Provider-Sache.
+//
+// **Audit/event-history:** lebt im event-store unter dem `subscription`-
+// stream — KEIN eigene `subscription-event`-Tabelle mehr (= ES ist die
+// audit-truth, replay-fähig durch upcasters).
+export const subscriptionEntity = createEntity({
+  table: "read_subscriptions",
+  fields: {
+    providerName: createTextField({ required: true, maxLength: 50 }),
+    providerCustomerId: createTextField({ required: true, maxLength: 200 }),
+    providerSubscriptionId: createTextField({ required: true, maxLength: 200 }),
+    status: createTextField({ required: true, maxLength: 30 }),
+    tier: createTextField({ required: true, maxLength: 50 }),
+    currentPeriodEnd: createTimestampField({ required: true }),
+  },
+});

package/src/billing-foundation/events.ts

@@ -0,0 +1,71 @@
+// Domain-events für subscription-foundation.
+//
+// **Pattern:** event-sourced — jeder Provider-Webhook (nach Plugin-
+// verify) wird zu einem domain-event auf dem subscription-stream
+// (= ein stream pro Tenant via subscriptionAggregateId(tenantId)).
+// Read-model = inline projection in `subscriptions`-Tabelle.
+//
+// 5 fine-grained event-typen statt einem generic "webhook-received"-
+// bucket — events sind business-facts: future-consumer (billing-history,
+// accounting-export, churn-analytics) listenen direkt auf den event-
+// type ohne payload-discriminator.
+
+import { z } from "zod";
+import { BILLING_FOUNDATION_FEATURE, SubscriptionStatuses } from "./constants";
+
+// Aggregate-type für den event-store. Eine subscription pro Tenant ist
+// ein stream; der subscriptionAggregateId-helper liefert die stream-id.
+export const SUBSCRIPTION_AGGREGATE_TYPE = "subscription" as const;
+
+// Event-name-Konstanten — short-form (für r.defineEvent) + qualifizierte
+// FQN (für ctx.appendEventUnsafe + projection-apply-keys).
+export const SUBSCRIPTION_CREATED_EVENT_SHORT = "subscription-created" as const;
+export const SUBSCRIPTION_UPDATED_EVENT_SHORT = "subscription-updated" as const;
+export const SUBSCRIPTION_CANCELED_EVENT_SHORT = "subscription-canceled" as const;
+export const INVOICE_PAID_EVENT_SHORT = "invoice-paid" as const;
+export const INVOICE_PAYMENT_FAILED_EVENT_SHORT = "invoice-payment-failed" as const;
+
+export const SUBSCRIPTION_CREATED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_CREATED_EVENT_SHORT}` as const;
+export const SUBSCRIPTION_UPDATED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_UPDATED_EVENT_SHORT}` as const;
+export const SUBSCRIPTION_CANCELED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${SUBSCRIPTION_CANCELED_EVENT_SHORT}` as const;
+export const INVOICE_PAID_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAID_EVENT_SHORT}` as const;
+export const INVOICE_PAYMENT_FAILED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${INVOICE_PAYMENT_FAILED_EVENT_SHORT}` as const;
+
+// Status-enum für event-payloads (= subscription-state-snapshot vom Provider).
+const statusEnum = z.enum([
+  SubscriptionStatuses.active,
+  SubscriptionStatuses.trialing,
+  SubscriptionStatuses.pastDue,
+  SubscriptionStatuses.canceled,
+  SubscriptionStatuses.incomplete,
+]);
+
+// Common payload — alle 5 events tragen denselben subscription-state-
+// snapshot. Event-type tagged was passiert ist, payload den state-after.
+// Provider-spezifischer rawPayload ist in metadata.rawPayload (nicht in
+// payload — payload ist domain-clean, metadata ist provider-truth).
+export const subscriptionEventPayloadSchema = z.object({
+  providerName: z.string().min(1).max(50),
+  providerCustomerId: z.string().min(1).max(200),
+  providerSubscriptionId: z.string().min(1).max(200),
+  status: statusEnum,
+  tier: z.string().min(1).max(50),
+  currentPeriodEndIso: z.string().min(1),
+});
+export type SubscriptionEventPayload = z.infer<typeof subscriptionEventPayloadSchema>;
+
+// Headers-shape — wird im event-store als event.metadata.headers
+// persistiert (open-shape jsonb-column, primitives only).
+// Idempotency-anchor: providerEventId pro provider, foundation checked
+// vor append ob bereits gesehen. rawPayload ist als string archiviert
+// damit Plugin-bug-fix-replays from-source machbar bleiben.
+export type SubscriptionEventHeaders = {
+  readonly providerEventId: string;
+  readonly providerName: string;
+  readonly rawPayload: string;
+};

package/src/billing-foundation/feature.ts

@@ -0,0 +1,122 @@
+// kumiko-feature-version: 1
+//
+// subscription-foundation als Kumiko bundled feature (Plugin-Host).
+//
+// **Multi-Provider von Tag 1** — der App-Builder kann mehrere Plugins
+// parallel mounten (subscription-stripe + subscription-paypal +
+// subscription-apple-iap + ...) und der Endkunde wählt beim Subscribe-
+// Klick zwischen Karte/PayPal/Apple-Pay/Klarna/SEPA (Disney+-Pattern).
+// KEIN globaler `provider`-config-key — alle gemounteten Plugins sind
+// aktiv.
+//
+// **Was diese Foundation liefert:**
+//   1. **Plugin-API** für Subscription-Provider via `r.extendsRegistrar(
+//      "subscriptionProvider", ...)`.
+//   2. **5 Domain-Events** auf dem `subscription`-stream (eine
+//      stream-id pro Tenant): created/updated/canceled/invoice-paid/
+//      invoice-payment-failed. Audit-history kommt frei vom event-store.
+//   3. **Inline-Projection** auf `read_subscriptions` (= current state
+//      pro Tenant). Apply läuft in derselben TX wie der event-append
+//      → read-your-own-write semantics.
+//   4. **process-event-handler**: programmatic write-handler den der
+//      webhook-handler aufruft, dispatcht zu type-passendem appendEvent.
+//   5. **createSubscriptionWebhookHandler**: factory für die HTTP-Route
+//      `/api/subscription/webhook/:providerName`.
+//
+// **Was diese Foundation NICHT macht:**
+//   - Kein r.entity für `subscription`. Die Tabelle ist eine reine
+//     Read-Projection — kein CRUD-Pfad. Schreibt wird ausschließlich
+//     via projection-apply, getriggert von einem der 5 events.
+//   - Kein Tier-Sync zum tier-engine. App-Owner liest die subscription-
+//     row via `getSubscriptionForTenant(ctx, tenantId)` wenn er möchte.
+//   - Keine provider-spezifischen Configs.
+//   - Kein Marketplace-Use-Case (App-Tenant billed Endkunden via
+//     Stripe Connect). Kommt als separate `marketplace-foundation`.
+//
+// **Provider-Wechsel:** Disney+-Pattern (= Tenant cancelt Stripe-sub,
+// startet neue mit PayPal) wird heute als zweiter `subscription-created`-
+// event modelliert. UPSERT in der projection-apply überschreibt den
+// existing row mit dem neuen providerName. Reicht für MVP. Wenn das
+// business-fact "Provider-Wechsel" ein eigenes domain-event braucht
+// (z.B. für analytics: "wie viele Wechsel im Monat?"), kommt ein
+// `subscription-provider-changed`-event-type später.
+
+import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
+import { BILLING_FOUNDATION_FEATURE, SUBSCRIPTION_PROVIDER_EXTENSION } from "./constants";
+import {
+  INVOICE_PAID_EVENT_QN,
+  INVOICE_PAID_EVENT_SHORT,
+  INVOICE_PAYMENT_FAILED_EVENT_QN,
+  INVOICE_PAYMENT_FAILED_EVENT_SHORT,
+  SUBSCRIPTION_AGGREGATE_TYPE,
+  SUBSCRIPTION_CANCELED_EVENT_QN,
+  SUBSCRIPTION_CANCELED_EVENT_SHORT,
+  SUBSCRIPTION_CREATED_EVENT_QN,
+  SUBSCRIPTION_CREATED_EVENT_SHORT,
+  SUBSCRIPTION_UPDATED_EVENT_QN,
+  SUBSCRIPTION_UPDATED_EVENT_SHORT,
+  subscriptionEventPayloadSchema,
+} from "./events";
+import { createCheckoutSessionHandler } from "./handlers/create-checkout-session.write";
+import { createPortalSessionHandler } from "./handlers/create-portal-session.write";
+import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query";
+import { processEventHandler } from "./handlers/process-event.write";
+import {
+  applyInvoicePaid,
+  applyInvoicePaymentFailed,
+  applySubscriptionCanceled,
+  applySubscriptionCreated,
+  applySubscriptionUpdated,
+  subscriptionsProjectionTable,
+} from "./projection";
+
+export const billingFoundationFeature: FeatureDefinition = defineFeature(
+  BILLING_FOUNDATION_FEATURE,
+  (r) => {
+    // 5 fine-grained domain-events. Alle 5 nutzen denselben payload-
+    // shape (= subscription-state-snapshot); der event-type taggt was
+    // passiert ist. Future-consumer (billing-history, accounting)
+    // listenen direkt auf den event-type ohne payload-discriminator.
+    r.defineEvent(SUBSCRIPTION_CREATED_EVENT_SHORT, subscriptionEventPayloadSchema);
+    r.defineEvent(SUBSCRIPTION_UPDATED_EVENT_SHORT, subscriptionEventPayloadSchema);
+    r.defineEvent(SUBSCRIPTION_CANCELED_EVENT_SHORT, subscriptionEventPayloadSchema);
+    r.defineEvent(INVOICE_PAID_EVENT_SHORT, subscriptionEventPayloadSchema);
+    r.defineEvent(INVOICE_PAYMENT_FAILED_EVENT_SHORT, subscriptionEventPayloadSchema);
+
+    // Inline projection: materialized current state in `read_subscriptions`.
+    // Apply läuft in derselben TX wie ctx.appendEventUnsafe — read-your-
+    // own-write ohne dispatcher-tick.
+    r.projection({
+      name: "subscription",
+      source: SUBSCRIPTION_AGGREGATE_TYPE,
+      table: subscriptionsProjectionTable,
+      apply: {
+        [SUBSCRIPTION_CREATED_EVENT_QN]: applySubscriptionCreated,
+        [SUBSCRIPTION_UPDATED_EVENT_QN]: applySubscriptionUpdated,
+        [SUBSCRIPTION_CANCELED_EVENT_QN]: applySubscriptionCanceled,
+        [INVOICE_PAID_EVENT_QN]: applyInvoicePaid,
+        [INVOICE_PAYMENT_FAILED_EVENT_QN]: applyInvoicePaymentFailed,
+      },
+    });
+
+    // Plugin extension-point. Provider-Plugins registrieren sich hier.
+    r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
+      onRegister: () => {
+        // No side-effects at register-time.
+      },
+    });
+
+    // Custom write-handlers:
+    //   - process-event: programmatic entry-point vom webhook-handler;
+    //     dispatcht zu type-passendem appendEvent
+    //   - create-checkout-session: Tenant-Admin "Upgrade to Pro"-flow
+    //   - create-portal-session: Tenant-Admin "Manage Subscription"-flow
+    r.writeHandler(processEventHandler);
+    r.writeHandler(createCheckoutSessionHandler);
+    r.writeHandler(createPortalSessionHandler);
+
+    // Custom list-query auf der subscription-projection (raw drizzle-
+    // table; kein r.entity weil Schreiben via projection-apply läuft).
+    r.queryHandler(listSubscriptionsQuery);
+  },
+);