@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/billing-foundation/get-subscription-for-tenant.ts

@@ -0,0 +1,39 @@
+// Resolver-helper: liest die current subscription-row für einen Tenant
+// aus der read_subscriptions-projection.
+
+import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { subscriptionAggregateId } from "./aggregate-id";
+import { subscriptionsProjectionTable } from "./projection";
+
+export type SubscriptionView = {
+  readonly tier: string;
+  readonly status: string;
+  readonly providerName: string;
+  readonly providerCustomerId: string;
+  readonly providerSubscriptionId: string;
+};
+
+/** Liefert die einzige subscription-row für den Tenant (deterministic
+ *  aggregate-id), oder null wenn der Tenant nie subscribed hat. Status
+ *  kann active/canceled/past_due/etc sein — Caller entscheidet was tun. */
+export async function getSubscriptionForTenant(
+  ctx: HandlerContext,
+  tenantId: string,
+): Promise<SubscriptionView | null> {
+  const aggId = subscriptionAggregateId(tenantId);
+  const [row] = await ctx.db
+    .select()
+    .from(subscriptionsProjectionTable)
+    .where(eq(subscriptionsProjectionTable["id"], aggId))
+    .limit(1);
+  if (!row) return null;
+  // @cast-boundary db-row — drizzle-row carries column-as-unknown
+  return {
+    tier: row["tier"] as string,
+    status: row["status"] as string,
+    providerName: row["providerName"] as string,
+    providerCustomerId: row["providerCustomerId"] as string,
+    providerSubscriptionId: row["providerSubscriptionId"] as string,
+  };
+}

package/src/billing-foundation/handlers/create-checkout-session.write.ts

@@ -0,0 +1,79 @@
+// create-checkout-session — Tenant-Admin klickt "Upgrade to Pro" (oder
+// wählt zwischen Karte/PayPal/Apple-Pay). Handler findet den
+// providerName aus der payload, lookuppt den Plugin, ruft
+// `plugin.createCheckoutSession(ctx, ...)`, returnt hosted-page-URL.
+// Tenant-Admin wird dorthin redirected.
+//
+// **Multi-Provider-Pfad:** payload.providerName ist der entityName
+// eines registrierten Plugins ("stripe" / "paypal" / "mollie" / ...).
+// App-Builder zeigt eine UI-Liste der gemounteten provider, Endkunde
+// pickt einen, dieser handler dispatched zum richtigen Plugin.
+//
+// **Tenant-resolution:** ctx.user.tenantId wird als metadata an den
+// Provider mitgegeben. Beim subsequent webhook (subscription.created)
+// liest verifyAndParseWebhook das aus dem provider-payload zurück und
+// resolved den Tenant.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { SUBSCRIPTION_PROVIDER_EXTENSION } from "../constants";
+import type { SubscriptionProviderPlugin } from "../types";
+
+const createCheckoutSessionSchema = z.object({
+  /** Welcher Provider — entityName eines registrierten subscription-
+   *  Plugins ("stripe" / "paypal" / ...). */
+  providerName: z.string().min(1).max(50),
+  /** Provider-eigene price/plan-ID. */
+  priceId: z.string().min(1).max(200),
+  /** Wo der Endkunde nach erfolgreichem checkout landed. */
+  successUrl: z.string().url(),
+  /** Wo der Endkunde landed wenn er abbricht. */
+  cancelUrl: z.string().url(),
+  /** Optional: existierender provider-customer wenn der Tenant schon
+   *  einen account beim Provider hat (= Plan-Wechsel statt Neuregistrierung). */
+  providerCustomerId: z.string().max(200).optional(),
+});
+type CreateCheckoutSessionPayload = z.infer<typeof createCheckoutSessionSchema>;
+
+export const createCheckoutSessionHandler: WriteHandlerDef = {
+  name: "create-checkout-session",
+  schema: createCheckoutSessionSchema,
+  // Tenant-Admin-only — der Tenant muss bewusst seine Subscription
+  // konfigurieren. SystemAdmin als Fallback für Operator-Initiated-Flows.
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as CreateCheckoutSessionPayload;
+
+    // Plugin-Lookup via registry. Dispatcher-context hat ctx.registry —
+    // wir suchen den entityName-match in den extension-usages.
+    const usages = ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION);
+    const usage = usages.find((u) => u.entityName === payload.providerName);
+    if (!usage) {
+      const known = usages.map((u) => u.entityName).join(", ") || "<none>";
+      throw new Error(
+        `subscription-foundation: provider "${payload.providerName}" not registered. Known: ${known}.`,
+      );
+    }
+    // @cast-boundary engine-payload — extension-usage carries unknown options
+    const plugin = usage.options as SubscriptionProviderPlugin;
+    if (!plugin.createCheckoutSession) {
+      throw new Error(
+        `subscription-foundation: provider "${payload.providerName}" has no createCheckoutSession-method (e.g. Apple-IAP-only providers). Use the provider's native checkout flow.`,
+      );
+    }
+
+    const result = await plugin.createCheckoutSession(ctx, {
+      priceId: payload.priceId,
+      tenantId: event.user.tenantId,
+      successUrl: payload.successUrl,
+      cancelUrl: payload.cancelUrl,
+      ...(payload.providerCustomerId && { providerCustomerId: payload.providerCustomerId }),
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { url: result.url, providerName: payload.providerName },
+    };
+  },
+};

package/src/billing-foundation/handlers/create-portal-session.write.ts

@@ -0,0 +1,73 @@
+// create-portal-session — Tenant-Admin klickt "Manage Subscription".
+// Handler findet die current subscription des Tenants, lookuppt den
+// passenden Plugin (= subscription.providerName-Spalte), ruft
+// `plugin.createPortalSession(ctx, ...)`, returnt hosted-portal-URL.
+//
+// **Provider-resolution:** anders als create-checkout-session (= der
+// Tenant wählt einen NEUEN Provider beim Subscribe) ist hier der
+// Provider durch die existing subscription-row festgelegt — Tenant
+// kann nicht zum Portal eines OTHER Providers, weil der ihn nicht
+// kennt.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { eq } from "drizzle-orm";
+import { z } from "zod";
+import { subscriptionAggregateId } from "../aggregate-id";
+import { SUBSCRIPTION_PROVIDER_EXTENSION } from "../constants";
+import { subscriptionsProjectionTable as subTable } from "../projection";
+import type { SubscriptionProviderPlugin } from "../types";
+
+const createPortalSessionSchema = z.object({
+  /** Wo der Endkunde nach Portal-Session landed. */
+  returnUrl: z.string().url(),
+});
+type CreatePortalSessionPayload = z.infer<typeof createPortalSessionSchema>;
+
+export const createPortalSessionHandler: WriteHandlerDef = {
+  name: "create-portal-session",
+  schema: createPortalSessionSchema,
+  access: { roles: ["TenantAdmin", "SystemAdmin"] },
+  handler: async (event, ctx) => {
+    const payload = event.payload as CreatePortalSessionPayload;
+    const tenantId = event.user.tenantId;
+
+    // 1. Hol current subscription-row für den Tenant. Aggregate-id ist
+    //    deterministic per tenant — eine row pro tenant.
+    const subAggId = subscriptionAggregateId(tenantId);
+    const rows = await ctx.db.select().from(subTable).where(eq(subTable["id"], subAggId)).limit(1);
+    const row = rows[0];
+    if (!row) {
+      throw new Error(
+        "subscription-foundation: no active subscription for this tenant. Create one via create-checkout-session first.",
+      );
+    }
+    const providerName = row["providerName"] as string;
+    const providerCustomerId = row["providerCustomerId"] as string;
+
+    // 2. Plugin-Lookup
+    const usages = ctx.registry.getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION);
+    const usage = usages.find((u) => u.entityName === providerName);
+    if (!usage) {
+      throw new Error(
+        `subscription-foundation: subscription belongs to provider "${providerName}" but the matching plugin is not mounted.`,
+      );
+    }
+    // @cast-boundary engine-payload — extension-usage carries unknown options
+    const plugin = usage.options as SubscriptionProviderPlugin;
+    if (!plugin.createPortalSession) {
+      throw new Error(
+        `subscription-foundation: provider "${providerName}" has no createPortalSession-method (e.g. Apple-IAP managed Subs in der Apple-App).`,
+      );
+    }
+
+    const result = await plugin.createPortalSession(ctx, {
+      providerCustomerId,
+      returnUrl: payload.returnUrl,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { url: result.url, providerName },
+    };
+  },
+};

package/src/billing-foundation/handlers/list-subscriptions.query.ts

@@ -0,0 +1,20 @@
+// list-subscriptions — sysadmin-cross-tenant list-query auf der
+// `read_subscriptions`-projection. Tenant-Admins lesen ihre eigene
+// subscription via getSubscriptionForTenant-helper (= ctx.db ist
+// tenant-scoped, gibt automatisch nur die row des Callers zurück).
+
+import type { QueryHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { subscriptionsProjectionTable } from "../projection";
+
+const listSchema = z.object({}).strict();
+
+export const listSubscriptionsQuery: QueryHandlerDef = {
+  name: "subscription:list",
+  schema: listSchema,
+  access: { roles: ["SystemAdmin", "TenantAdmin"] },
+  handler: async (_query, ctx) => {
+    const rows = await ctx.db.select().from(subscriptionsProjectionTable);
+    return { rows };
+  },
+};

package/src/billing-foundation/handlers/process-event.write.ts

@@ -0,0 +1,160 @@
+// process-event — programmatic write-handler den der webhook-handler
+// (createSubscriptionWebhookHandler) aufruft NACHDEM Plugin den raw-body
+// verifiziert + zu SubscriptionEvent normalisiert hat.
+//
+// **ES-Pattern:**
+//   1. Idempotency-check: lädt subscription-stream + scannt nach
+//      bereits gesehenem `metadata.providerEventId`. Provider-Replay
+//      (Stripe-Retry-Storm) sieht denselben event-id → duplicate=true,
+//      kein zweiter append.
+//   2. Type-mapping: SubscriptionEvent.type (= normalisiert vom Plugin)
+//      → einer der 5 ES-event-typen.
+//   3. ctx.appendEventUnsafe — Inline-projection materialisiert die
+//      `read_subscriptions`-row in derselben TX.
+
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { subscriptionAggregateId } from "../aggregate-id";
+import { SubscriptionEventTypes, SubscriptionStatuses } from "../constants";
+import {
+  INVOICE_PAID_EVENT_QN,
+  INVOICE_PAYMENT_FAILED_EVENT_QN,
+  SUBSCRIPTION_AGGREGATE_TYPE,
+  SUBSCRIPTION_CANCELED_EVENT_QN,
+  SUBSCRIPTION_CREATED_EVENT_QN,
+  SUBSCRIPTION_UPDATED_EVENT_QN,
+  type SubscriptionEventHeaders,
+  type SubscriptionEventPayload,
+} from "../events";
+
+// =============================================================================
+// Input-Schema = der normalisierte SubscriptionEvent (ohne tenantId, der
+// kommt aus event.user.tenantId — der webhook-handler setzt den
+// programmatic-user mit der vom Plugin aufgelösten tenantId).
+// =============================================================================
+
+const eventTypeSchema = z.enum([
+  SubscriptionEventTypes.created,
+  SubscriptionEventTypes.updated,
+  SubscriptionEventTypes.canceled,
+  SubscriptionEventTypes.invoicePaid,
+  SubscriptionEventTypes.invoicePaymentFailed,
+]);
+
+const statusSchema = z.enum([
+  SubscriptionStatuses.active,
+  SubscriptionStatuses.trialing,
+  SubscriptionStatuses.pastDue,
+  SubscriptionStatuses.canceled,
+  SubscriptionStatuses.incomplete,
+]);
+
+export const processEventSchema = z.object({
+  providerEventId: z.string().min(1).max(200),
+  providerName: z.string().min(1).max(50),
+  type: eventTypeSchema,
+  providerCustomerId: z.string().min(1).max(200),
+  providerSubscriptionId: z.string().min(1).max(200),
+  status: statusSchema,
+  tier: z.string().min(1).max(50),
+  currentPeriodEndIso: z.string().min(1),
+  rawPayload: z.string().min(1),
+});
+type ProcessEventPayload = z.infer<typeof processEventSchema>;
+
+// Map normalized SubscriptionEventType → fully-qualified ES event-name.
+const NORMALIZED_TO_ES_EVENT: Readonly<Record<string, string>> = {
+  [SubscriptionEventTypes.created]: SUBSCRIPTION_CREATED_EVENT_QN,
+  [SubscriptionEventTypes.updated]: SUBSCRIPTION_UPDATED_EVENT_QN,
+  [SubscriptionEventTypes.canceled]: SUBSCRIPTION_CANCELED_EVENT_QN,
+  [SubscriptionEventTypes.invoicePaid]: INVOICE_PAID_EVENT_QN,
+  [SubscriptionEventTypes.invoicePaymentFailed]: INVOICE_PAYMENT_FAILED_EVENT_QN,
+};
+
+// =============================================================================
+// Handler
+// =============================================================================
+//
+// SystemAdmin-only: dieser handler wird ausschließlich vom programmatic
+// webhook-handler aufgerufen (mit einem internal SystemUser), nie vom
+// Tenant-Admin direkt.
+export const processEventHandler: WriteHandlerDef = {
+  name: "process-event",
+  schema: processEventSchema,
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as ProcessEventPayload;
+    const tenantId = event.user.tenantId;
+    const aggId = subscriptionAggregateId(tenantId);
+
+    // ---------------------------------------------------------------
+    // 1. Idempotency: load subscription-stream + check ob dieser
+    //    providerEventId bereits gesehen wurde. Provider-Retry-Storm
+    //    (Stripe sendet bis zu 5x in 4h) trifft denselben Stream und
+    //    findet den event-id in metadata.
+    //
+    //    **Performance-caveat:** O(N) pro stream. Bei 5 Jahren history
+    //    (recurring monatlich = ~60 events) noch <50ms. Bei deutlich
+    //    längeren streams optimieren via snapshot oder per-tenant
+    //    dedup-table als idempotency-anchor (analog cap-counter).
+    // ---------------------------------------------------------------
+    const existingEvents = await ctx.loadAggregate(aggId);
+    const alreadySeen = existingEvents.some((e) => {
+      const headers = e.metadata.headers ?? {};
+      return (
+        headers["providerEventId"] === payload.providerEventId &&
+        headers["providerName"] === payload.providerName
+      );
+    });
+    if (alreadySeen) {
+      return {
+        isSuccess: true as const,
+        data: { duplicate: true as const, subscriptionAggregateId: aggId },
+      };
+    }
+
+    // ---------------------------------------------------------------
+    // 2. Map normalized event-type → ES event-FQN.
+    // ---------------------------------------------------------------
+    const esEventType = NORMALIZED_TO_ES_EVENT[payload.type];
+    if (!esEventType) {
+      // Schema-validation oben sollte das schon fangen, aber defensive
+      // gegen drift im SubscriptionEventTypes-enum vs NORMALIZED-Map.
+      throw new Error(`subscription-foundation: no ES event-type mapping for "${payload.type}"`);
+    }
+
+    // ---------------------------------------------------------------
+    // 3. Append event auf den subscription-stream. Inline-projection
+    //    materialisiert die read_subscriptions-row in derselben TX.
+    // ---------------------------------------------------------------
+    const eventPayload: SubscriptionEventPayload = {
+      providerName: payload.providerName,
+      providerCustomerId: payload.providerCustomerId,
+      providerSubscriptionId: payload.providerSubscriptionId,
+      status: payload.status,
+      tier: payload.tier,
+      currentPeriodEndIso: payload.currentPeriodEndIso,
+    };
+    const headers: SubscriptionEventHeaders = {
+      providerEventId: payload.providerEventId,
+      providerName: payload.providerName,
+      rawPayload: payload.rawPayload,
+    };
+    await ctx.appendEventUnsafe({
+      aggregateId: aggId,
+      aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
+      type: esEventType,
+      payload: eventPayload,
+      headers,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: {
+        duplicate: false as const,
+        subscriptionAggregateId: aggId,
+      },
+    };
+  },
+};

package/src/billing-foundation/index.ts

@@ -0,0 +1,42 @@
+// Public API of the subscription-foundation bundled-feature.
+
+export { subscriptionAggregateId } from "./aggregate-id";
+export {
+  BILLING_FOUNDATION_FEATURE,
+  SUBSCRIPTION_PROVIDER_EXTENSION,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+  SubscriptionFoundationHandlers,
+  SubscriptionFoundationQueries,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "./constants";
+export { subscriptionEntity } from "./entities";
+export {
+  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,
+  type SubscriptionEventHeaders,
+  type SubscriptionEventPayload,
+  subscriptionEventPayloadSchema,
+} from "./events";
+export { billingFoundationFeature } from "./feature";
+export { getSubscriptionForTenant, type SubscriptionView } from "./get-subscription-for-tenant";
+export { subscriptionsProjectionTable } from "./projection";
+export type {
+  SubscriptionEvent,
+  SubscriptionProviderPlugin,
+} from "./types";
+export {
+  createSubscriptionWebhookHandler,
+  type SubscriptionWebhookDeps,
+  type SubscriptionWebhookHandler,
+} from "./webhook-handler";

package/src/billing-foundation/projection.ts

@@ -0,0 +1,135 @@
+// Inline-projection für `read_subscriptions`. Materialisiert die 5
+// subscription-events in eine row pro Tenant.
+//
+// Apply läuft in derselben TX wie ctx.appendEventUnsafe — Caller sieht
+// seinen Schreib-State sofort (kein dispatcher-tick nötig). PK = event.
+// aggregateId (= deterministic uuidv5 pro Tenant) → replays kollidieren
+// auf der PK statt doppelte rows zu erzeugen.
+//
+// **Production-deployment caveat:** der Generator in
+// `samples/apps/platform/drizzle/generate.ts` scant `feature.entities` —
+// `subscriptionsProjectionTable` ist als raw drizzle-pgTable in der
+// projection registriert, NICHT als r.entity. Apps die subscription-
+// foundation production mounten müssen die Tabelle in ihre eigene
+// `drizzle/generate.ts` ergänzen (= via subscriptionsProjectionTable-
+// import). setupTestStack pusht sie automatisch via r.projection.table.
+
+import { buildDrizzleTable } from "@cosmicdrift/kumiko-framework/db";
+import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
+import { subscriptionEntity } from "./entities";
+import type { SubscriptionEventPayload } from "./events";
+
+// Drizzle-table-instance aus dem entity-shape. Wird sowohl von der
+// projection-apply als auch von list-query / get-helper genutzt damit
+// alle drei Stellen denselben column-namespace teilen.
+export const subscriptionsProjectionTable = buildDrizzleTable("subscription", subscriptionEntity);
+
+// =============================================================================
+// Shared helpers
+// =============================================================================
+
+/** Felder die alle 5 events vollständig zur Verfügung haben. */
+function fullSetFromPayload(p: SubscriptionEventPayload) {
+  return {
+    providerName: p.providerName,
+    providerCustomerId: p.providerCustomerId,
+    providerSubscriptionId: p.providerSubscriptionId,
+    status: p.status,
+    tier: p.tier,
+    currentPeriodEnd: p.currentPeriodEndIso,
+  };
+}
+
+/** UPSERT-helper für defensive apply: wenn die row nicht existiert
+ *  (= z.B. Plugin sendet "updated" als ersten event eines streams,
+ *  oder rebuild-aus-dem-Nichts), legen wir sie an statt fail-silent
+ *  zu sein. Apply läuft in der event-TX, expectedVersion macht
+ *  drizzle-on-conflict korrekt. */
+async function upsert(
+  tx: Parameters<Parameters<typeof defineApply<SubscriptionEventPayload>>[0]>[1],
+  event: { aggregateId: string; tenantId: string },
+  set: Partial<{
+    providerName: string;
+    providerCustomerId: string;
+    providerSubscriptionId: string;
+    status: string;
+    tier: string;
+    currentPeriodEnd: string;
+  }>,
+  fullPayload: SubscriptionEventPayload,
+): Promise<void> {
+  // INSERT-fallback braucht ALL fields (NOT NULL constraints). Wenn
+  // jemand nur teil-felder updated (z.B. invoice-payment-failed nur
+  // status+tier), nutzen wir trotzdem den vollen payload für den
+  // INSERT-Pfad und nur den teil-`set` für ON CONFLICT.
+  await tx
+    .insert(subscriptionsProjectionTable)
+    .values({
+      id: event.aggregateId,
+      tenantId: event.tenantId,
+      ...fullSetFromPayload(fullPayload),
+    })
+    .onConflictDoUpdate({
+      target: subscriptionsProjectionTable["id"],
+      set,
+    });
+}
+
+// =============================================================================
+// Apply-functions — eine pro event-typ
+//
+// Alle UPSERT für defensive consistency: ein out-of-order event
+// (z.B. rebuild-from-events) kann in jeder Reihenfolge ankommen
+// und die row korrekt materialisieren.
+// =============================================================================
+
+/** subscription-created → UPSERT mit allen Feldern. PK = aggregateId =
+ *  subscriptionAggregateId(tenantId), one row pro Tenant. UPSERT damit
+ *  Disney+-Wechsel-Pattern (= zweiter Provider sendet create für selben
+ *  Tenant) den existing row überschreibt statt PK-conflict. */
+export const applySubscriptionCreated = defineApply<SubscriptionEventPayload>(async (event, tx) => {
+  const full = fullSetFromPayload(event.payload);
+  await upsert(tx, event, full, event.payload);
+});
+
+/** subscription-updated → UPSERT mit allen Feldern. */
+export const applySubscriptionUpdated = defineApply<SubscriptionEventPayload>(async (event, tx) => {
+  const full = fullSetFromPayload(event.payload);
+  await upsert(tx, event, full, event.payload);
+});
+
+/** subscription-canceled → status/tier/currentPeriodEnd patchen. */
+export const applySubscriptionCanceled = defineApply<SubscriptionEventPayload>(
+  async (event, tx) => {
+    const p = event.payload;
+    await upsert(
+      tx,
+      event,
+      { status: p.status, tier: p.tier, currentPeriodEnd: p.currentPeriodEndIso },
+      p,
+    );
+  },
+);
+
+/** invoice-paid → state-update (status, tier, currentPeriodEnd).
+ *  Invoice-history selbst lebt im event-store (= Replay-fähig). */
+export const applyInvoicePaid = defineApply<SubscriptionEventPayload>(async (event, tx) => {
+  const p = event.payload;
+  await upsert(
+    tx,
+    event,
+    { status: p.status, tier: p.tier, currentPeriodEnd: p.currentPeriodEndIso },
+    p,
+  );
+});
+
+/** invoice-payment-failed → status (typisch past_due) + tier. tier-
+ *  engine liest die row + entscheidet ob downgrade. currentPeriodEnd
+ *  bewusst nicht — die Period ist noch nicht "vorbei", payment hat
+ *  nur nicht geklappt. */
+export const applyInvoicePaymentFailed = defineApply<SubscriptionEventPayload>(
+  async (event, tx) => {
+    const p = event.payload;
+    await upsert(tx, event, { status: p.status, tier: p.tier }, p);
+  },
+);