@cosmicdrift/kumiko-bundled-features 0.296.0 → 0.299.0

package/src/billing-foundation/feature.ts

@@ -20,8 +20,8 @@
 //      → 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`.
+//   5. **createSubscriptionWebhookRoute**: factory for the `entry:"signature"`
+//      extraRoute `/api/subscription/webhook/:providerName`.
 //   6. **payment-received event + read_payments projection**: one-off-
 //      payments (checkout mode "payment") get their own event, own
 //      per-tenant aggregate, and own `process-payment-event` write-handler
@@ -85,7 +85,7 @@ import { paymentTenantDestroyHook, subscriptionTenantDestroyHook } from "./tenan
 
 export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE, (r) => {
   r.describe(
-    "Plugin host for subscription billing \u2014 manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookHandler` factory for the `/api/subscription/webhook/:providerName` route. Low-level building block \u2014 use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
+    "Plugin host for subscription billing \u2014 manages the `read_subscriptions` projection table and exposes 5 domain events (subscription created/updated/canceled, invoice paid/failed) appended by the foundation's own `billing-foundation:write:process-event` write-handler after provider plugins verify and normalize each webhook. Also manages a separate `read_payments` projection table (one row per one-off-payment) fed by its own `payment-received` event and `billing-foundation:write:process-payment-event` write-handler. Also ships `billing-foundation:write:create-checkout-session` and `billing-foundation:write:create-portal-session` write-handlers, a `billing-foundation:query:subscription:list` query handler, and a `createSubscriptionWebhookRoute` factory for the `/api/subscription/webhook/:providerName` extraRoute. Low-level building block \u2014 use `subscription-stripe` or `subscription-mollie` unless you are writing a new payment provider.",
   );
   r.uiHints({
     displayLabel: "Billing \u00b7 Foundation",

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

@@ -1,5 +1,5 @@
 // process-event — programmatic write-handler den der webhook-handler
-// (createSubscriptionWebhookHandler) aufruft NACHDEM Plugin den raw-body
+// (createSubscriptionWebhookRoute) aufruft NACHDEM Plugin den raw-body
 // verifiziert + zu SubscriptionEvent normalisiert hat.
 //
 // **ES-Pattern:**

package/src/billing-foundation/index.ts

@@ -49,7 +49,6 @@ export {
   effectiveTierFromSubscription,
   SUBSCRIPTION_WEBHOOK_PATH,
   type SubscriptionTierSyncDeps,
-  type SystemWriteResult,
 } from "./subscription-tier-sync";
 export type {
   PaymentEvent,
@@ -57,7 +56,6 @@ export type {
   SubscriptionProviderPlugin,
 } from "./types";
 export {
-  createSubscriptionWebhookHandler,
-  type SubscriptionWebhookDeps,
-  type SubscriptionWebhookHandler,
+  createSubscriptionWebhookRoute,
+  type SubscriptionWebhookRouteOptions,
 } from "./webhook-handler";

package/src/billing-foundation/subscription-tier-sync.ts

@@ -1,38 +1,31 @@
 // Generic Stripe/PayPal-webhook → tier-engine sync route. Extracted from the
 // near-identical webhook-route.ts app copies in show-pony and publicstatus
-// (infra#446) — the only per-app variables were the TierName union/default
-// and the tier-assignment table handle, so both are now factory parameters.
+// (infra#446) — the only per-app variables were the TierName union/default,
+// so it is now a factory parameter.
 
 import {
   TierEngineHandlers,
+  TierEngineQueries,
   tierAssignmentAggregateId,
 } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
-import { type DbRunner, type EntityTable, fetchOne } from "@cosmicdrift/kumiko-framework/db";
-import type { EntityDefinition, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import type { Hono } from "hono";
+import type {
+  ExtraRouteDefinition,
+  SignatureExtraRouteDeps,
+} from "@cosmicdrift/kumiko-framework/api";
+import type { TenantId, WriteResult } from "@cosmicdrift/kumiko-framework/engine";
 import { subscriptionAggregateId } from "./aggregate-id";
-import { SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionStatuses } from "./constants";
-import { subscriptionsProjectionTable } from "./projection";
-import type { SubscriptionProviderPlugin } from "./types";
-import { createSubscriptionWebhookHandler } from "./webhook-handler";
+import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants";
+import { createSubscriptionWebhookRoute } from "./webhook-handler";
 
+// Outside /api — signature routes carry their own auth (verify()) and are
+// not JWT-guarded, so provider dashboards (Stripe, PayPal, ...) point here.
 export const SUBSCRIPTION_WEBHOOK_PATH = "/webhooks/subscription/:providerName";
 
-export type SystemWriteResult = {
-  readonly isSuccess: boolean;
-  readonly data?: unknown;
-  readonly error?: { readonly code?: string; readonly message?: string };
-};
-
+// No db/tierAssignmentTable dep: extraRoutes are built before buildServer
+// exists (no db at construction time), and handlers never see a raw db
+// escape hatch either — the sync reads and writes exclusively through
+// dispatchSystemQuery/dispatchSystemWrite in afterDispatch below.
 export type SubscriptionTierSyncDeps<TTier extends string> = {
-  readonly db: DbRunner;
-  readonly registry: Registry;
-  readonly dispatchSystemWrite: (args: {
-    readonly handlerQn: string;
-    readonly payload: unknown;
-    readonly tenantId: TenantId;
-  }) => Promise<SystemWriteResult>;
-  readonly tierAssignmentTable: EntityTable<EntityDefinition>;
   readonly isTierName: (value: string) => value is TTier;
   readonly defaultTier: TTier;
   // "log" (default): sync failure only warns, the webhook still reports
@@ -53,96 +46,130 @@ export function effectiveTierFromSubscription<TTier extends string>(
   return usable && typeof tier === "string" && isTierName(tier) ? tier : defaultTier;
 }
 
+// Narrows an unknown dispatchSystemQuery result to its `{ rows }` list
+// shape without an unchecked cast — a query returning something else
+// (handler bug, or the handlerQn resolving to a non-list query) fails
+// loudly instead of crashing on `.find` against `undefined`.
+function asRows(result: unknown): ReadonlyArray<Record<string, unknown>> {
+  if (
+    typeof result === "object" &&
+    result !== null &&
+    Array.isArray((result as { rows?: unknown }).rows)
+  ) {
+    return (result as { rows: ReadonlyArray<Record<string, unknown>> }).rows;
+  }
+  throw new Error("expected a { rows: [...] } list-query result");
+}
+
 export function createSubscriptionTierSync<TTier extends string>(
   deps: SubscriptionTierSyncDeps<TTier>,
 ) {
   async function syncTierFromSubscription(
     tenantId: TenantId,
+    routeDeps: SignatureExtraRouteDeps,
   ): Promise<{ code: string; message: string } | null> {
-    const sub = await fetchOne<{ status?: unknown; tier?: unknown }>(
-      deps.db,
-      subscriptionsProjectionTable,
-      { id: subscriptionAggregateId(tenantId) },
-    );
-    if (!sub) return null;
+    try {
+      const subscriptionId = subscriptionAggregateId(tenantId);
+      const subscriptionRows = asRows(
+        await routeDeps.dispatchSystemQuery({
+          handlerQn: SubscriptionFoundationQueries.listSubscriptions,
+          payload: {},
+          tenantId,
+        }),
+      );
+      const sub = subscriptionRows.find((row) => row["id"] === subscriptionId);
+      if (!sub) return null;
+
+      const effective = effectiveTierFromSubscription(
+        typeof sub["status"] === "string" ? sub["status"] : undefined,
+        typeof sub["tier"] === "string" ? sub["tier"] : undefined,
+        deps.isTierName,
+        deps.defaultTier,
+      );
 
-    const effective = effectiveTierFromSubscription(
-      typeof sub.status === "string" ? sub.status : undefined,
-      typeof sub.tier === "string" ? sub.tier : undefined,
-      deps.isTierName,
-      deps.defaultTier,
-    );
+      const tierAssignmentRows = asRows(
+        await routeDeps.dispatchSystemQuery({
+          handlerQn: TierEngineQueries.list,
+          payload: {},
+          tenantId,
+        }),
+      );
+      const assignment = tierAssignmentRows.find((row) => row["tenantId"] === tenantId);
+      if (
+        !assignment ||
+        typeof assignment["id"] !== "string" ||
+        typeof assignment["version"] !== "number"
+      ) {
+        const created = await routeDeps.dispatchSystemWrite({
+          handlerQn: TierEngineHandlers.create,
+          payload: { id: tierAssignmentAggregateId(tenantId), tier: effective },
+          tenantId,
+        });
+        if (!created.isSuccess) {
+          return {
+            code: "tier_sync_failed",
+            message: `tier-engine create with "${effective}" failed: ${created.error?.code ?? "unknown"}`,
+          };
+        }
+        return null;
+      }
+      if (assignment["tier"] === effective) return null;
 
-    const assignment = await fetchOne<{ id?: unknown; version?: unknown; tier?: unknown }>(
-      deps.db,
-      deps.tierAssignmentTable,
-      { tenantId },
-    );
-    if (
-      !assignment ||
-      typeof assignment.id !== "string" ||
-      typeof assignment.version !== "number"
-    ) {
-      const created = await deps.dispatchSystemWrite({
-        handlerQn: TierEngineHandlers.create,
-        payload: { id: tierAssignmentAggregateId(tenantId), tier: effective },
+      const result = await routeDeps.dispatchSystemWrite({
+        handlerQn: TierEngineHandlers.update,
+        payload: {
+          id: assignment["id"],
+          version: assignment["version"],
+          changes: { tier: effective },
+        },
         tenantId,
       });
-      if (!created.isSuccess) {
+      if (!result.isSuccess) {
         return {
           code: "tier_sync_failed",
-          message: `tier-engine create with "${effective}" failed: ${created.error?.code ?? "unknown"}`,
+          message: `tier-engine update to "${effective}" failed: ${result.error?.code ?? "unknown"}`,
         };
       }
       return null;
-    }
-    if (assignment.tier === effective) return null;
-
-    const result = await deps.dispatchSystemWrite({
-      handlerQn: TierEngineHandlers.update,
-      payload: { id: assignment.id, version: assignment.version, changes: { tier: effective } },
-      tenantId,
-    });
-    if (!result.isSuccess) {
+    } catch (error) {
+      // dispatchSystemQuery throws (AccessDenied/NotFound/Validation) rather
+      // than returning an error envelope — e.g. a consumer that mounts
+      // billing-foundation without tier-engine. Surface it the same way as
+      // a failed dispatchSystemWrite instead of letting it bubble into the
+      // webhook response as an unhandled 500.
       return {
         code: "tier_sync_failed",
-        message: `tier-engine update to "${effective}" failed: ${result.error?.code ?? "unknown"}`,
+        message: error instanceof Error ? error.message : "tier sync threw a non-Error value",
       };
     }
-    return null;
   }
 
-  function wireSubscriptionWebhookRoute(app: Hono): void {
-    const handler = createSubscriptionWebhookHandler({
-      dispatchWrite: async ({ handlerQn, payload, tenantId }) => {
-        const targetTenantId = tenantId as TenantId;
-        const result = await deps.dispatchSystemWrite({
-          handlerQn,
-          payload,
-          tenantId: targetTenantId,
-        });
-        if (!result.isSuccess) return result;
-        const syncError = await syncTierFromSubscription(targetTenantId);
+  function createWebhookRoute(): ExtraRouteDefinition {
+    return createSubscriptionWebhookRoute({
+      path: SUBSCRIPTION_WEBHOOK_PATH,
+      afterDispatch: async (dispatched: WriteResult, tenantId, routeDeps): Promise<WriteResult> => {
+        const syncError = await syncTierFromSubscription(tenantId, routeDeps);
         if (syncError) {
           // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
           console.warn(
-            `[subscription-tier-sync] tier sync failed for tenant ${targetTenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
+            `[subscription-tier-sync] tier sync failed for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`,
           );
           if (deps.onSyncError === "fail-webhook") {
-            return { isSuccess: false, error: syncError };
+            return {
+              isSuccess: false,
+              error: {
+                code: syncError.code,
+                httpStatus: 500,
+                i18nKey: "errors.subscriptionTierSyncFailed",
+                message: syncError.message,
+              },
+            };
           }
         }
-        return result;
-      },
-      resolveProvider: (providerName) => {
-        const usage = deps.registry
-          .getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION)
-          .find((u) => u.entityName === providerName);
-        return usage?.options as SubscriptionProviderPlugin | undefined;
+        return dispatched;
       },
     });
-    app.post(SUBSCRIPTION_WEBHOOK_PATH, handler);
   }
 
-  return { wireSubscriptionWebhookRoute };
+  return { createWebhookRoute };
 }

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

@@ -1,213 +1,153 @@
-// 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 (runDevApp wie runProdApp liefern
-// `registry` + `dispatchSystemWrite` in den extraRoutes-deps):
-//
-//   await runDevApp({
-//     features: APP_FEATURES,
-//     extraRoutes: (app, deps) => {
-//       const handler = createSubscriptionWebhookHandler({
-//         dispatchWrite: ({ handlerQn, payload, tenantId }) =>
-//           deps.dispatchSystemWrite({ handlerQn, payload, tenantId: tenantId as TenantId }),
-//         resolveProvider: (name) =>
-//           deps.registry.getExtensionUsages("subscriptionProvider")
-//             .find((u) => u.entityName === name)?.options as
-//             SubscriptionProviderPlugin | undefined,
-//       });
-//       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.
+// Multi-provider: the plugin is selected via the `:providerName` path-param
+// (Stripe → /stripe, PayPal → /paypal), one route mounts every plugin at once.
+// rawBody is intentionally NOT JSON-parsed before verify() — Stripe's
+// signature check needs the exact bytes. No JWT/cookie auth: the provider's
+// webhook signature in verify() IS the auth, so no c.get("user") here.
 
-import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import type { Context, Hono } from "hono";
+import { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
+import type { Context } from "hono";
 import {
   BILLING_FOUNDATION_FEATURE,
   BillingEventKinds,
   SUBSCRIPTION_PROVIDER_EXTENSION,
   SubscriptionFoundationHandlers,
 } from "./constants";
-import type { SubscriptionProviderPlugin } from "./types";
+import type { PaymentEvent, SubscriptionEvent, SubscriptionProviderPlugin } from "./types";
 
-/**
- * Dependencies the App-Owner gibt dem webhook-handler — beide direkt aus
- * den `extraRoutes`-deps ableitbar (`dispatchSystemWrite` + `registry`),
- * siehe Beispiel im Header.
- */
-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;
-  }>;
+export type SubscriptionWebhookRouteOptions = {
+  /** Route path — MUST carry the `:providerName` path-param. Default
+   *  "/api/subscription/webhook/:providerName". */
+  readonly path?: string;
+  /** Runs after a successful dispatchSystemWrite, before the 200 response —
+   *  lets callers (e.g. subscription-tier-sync) chain a side-effect without
+   *  duplicating the provider-resolve/payload-mapping logic above. Returning
+   *  a failed WriteResult turns the response into the same 500 a dispatch
+   *  failure would produce. */
+  readonly afterDispatch?: (
+    dispatched: import("@cosmicdrift/kumiko-framework/engine").WriteResult,
+    tenantId: import("@cosmicdrift/kumiko-framework/engine").TenantId,
+    deps: import("@cosmicdrift/kumiko-framework/api").SignatureExtraRouteDeps,
+  ) => Promise<import("@cosmicdrift/kumiko-framework/engine").WriteResult>;
+};
 
-  /** 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;
+const DEFAULT_WEBHOOK_PATH = "/api/subscription/webhook/:providerName";
 
-  /** Optionaler system-scoped SecretsContext, durchgereicht an
-   *  `verifyAndParseWebhook` (3. Arg). Erlaubt Plugins, ihre app-wide-
-   *  Credentials (Stripe api-key/webhook-secret) zur Laufzeit aus
-   *  secrets unter SYSTEM_TENANT_ID zu lesen statt aus einem mount-time-
-   *  Closure. Der App-Owner baut ihn via `createSecretsContext({ db,
-   *  masterKeyProvider })` aus den extraRoutes-deps. Fehlt er, fallen
-   *  Plugins auf ihren Closure-Fallback zurück. */
-  readonly systemSecrets?: import("@cosmicdrift/kumiko-framework/secrets").SecretsContext;
+function resolveProvider(
+  registry: import("@cosmicdrift/kumiko-framework/engine").Registry,
+  providerName: string,
+): SubscriptionProviderPlugin | undefined {
+  return registry
+    .getExtensionUsages(SUBSCRIPTION_PROVIDER_EXTENSION)
+    .find((u) => u.entityName === providerName)?.options as SubscriptionProviderPlugin | undefined;
+}
+
+type VerifiedWebhook = {
+  readonly providerName: string;
+  readonly event: SubscriptionEvent | PaymentEvent | null;
 };
 
 /**
- * Returnt einen Hono-handler. Mounten via
- * `app.post("/api/subscription/webhook/:providerName", handler)`.
+ * Builds the `entry:"signature"` extraRoute definition. Mount via
+ * `extraRoutes: [createSubscriptionWebhookRoute()]`.
  */
-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).`,
+export function createSubscriptionWebhookRoute(options: SubscriptionWebhookRouteOptions = {}) {
+  const path = options.path ?? DEFAULT_WEBHOOK_PATH;
+  return signatureRoute<VerifiedWebhook>({
+    method: "POST",
+    path,
+    entry: "signature",
+    verify: async ({ rawBody, headers, params }, deps) => {
+      const providerName = params["providerName"];
+      if (!providerName) {
+        throw new ExtraRouteRejection(
+          400,
+          {
+            error: {
+              code: "subscription_provider_path_missing",
+              message: `${BILLING_FOUNDATION_FEATURE}: mount the route with a :providerName path-param 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.`,
+          "subscription webhook route mounted without :providerName",
+        );
+      }
+      const plugin = resolveProvider(deps.registry, providerName);
+      if (!plugin) {
+        throw new ExtraRouteRejection(
+          404,
+          {
+            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, deps.systemSecrets);
-    } 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}`,
+          `subscription provider "${providerName}" not registered`,
+        );
+      }
+      // Throws on sig-mismatch — the ExtraRoute wrapper maps any non-
+      // ExtraRouteRejection throw to 401 extra_route_signature_invalid
+      // (= config-bug, retry won't help, provider stop).
+      const event = await plugin.verifyAndParseWebhook(rawBody, headers, deps.secrets);
+      return { providerName, event };
+    },
+    handler: async (c: Context, verified, deps) => {
+      if (verified.event === null) {
+        return c.json({ ignored: true }, 200);
+      }
+      const parsed = verified.event;
+      const tenantId = parsed.tenantId as import("@cosmicdrift/kumiko-framework/engine").TenantId;
+      if (parsed.kind === BillingEventKinds.payment) {
+        const dispatched = await deps.dispatchSystemWrite({
+          handlerQn: SubscriptionFoundationHandlers.processPaymentEvent,
+          tenantId,
+          payload: {
+            providerEventId: parsed.providerEventId,
+            providerName: parsed.providerName,
+            providerCustomerId: parsed.providerCustomerId,
+            priceId: parsed.priceId,
+            rawPayload: parsed.rawPayload,
           },
-        },
-        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 to the type-matching write-handler. Payment-events (own
-    //    aggregate, own `read_payments`-row) go to process-payment-event;
-    //    everything else (kind is undefined or "subscription") keeps going
-    //    through process-event, unchanged. Every handler handles idempotency
-    //    internally via deterministic aggregate-id + stream-scan.
-    if (parsed.kind === BillingEventKinds.payment) {
-      const dispatched = await deps.dispatchWrite({
-        handlerQn: SubscriptionFoundationHandlers.processPaymentEvent,
-        tenantId: parsed.tenantId,
+        });
+        return respondFromDispatch(
+          c,
+          dispatched.isSuccess && options.afterDispatch
+            ? await options.afterDispatch(dispatched, tenantId, deps)
+            : dispatched,
+          "subscription_payment_webhook_processing_failed",
+          "Internal error processing payment event",
+        );
+      }
+      const dispatched = await deps.dispatchSystemWrite({
+        handlerQn: SubscriptionFoundationHandlers.processEvent,
+        tenantId,
         payload: {
           providerEventId: parsed.providerEventId,
           providerName: parsed.providerName,
+          type: parsed.type,
           providerCustomerId: parsed.providerCustomerId,
-          priceId: parsed.priceId,
+          providerSubscriptionId: parsed.providerSubscriptionId,
+          status: parsed.status,
+          tier: parsed.tier,
+          currentPeriodEndIso: parsed.currentPeriodEnd,
           rawPayload: parsed.rawPayload,
         },
       });
       return respondFromDispatch(
         c,
-        dispatched,
-        "subscription_payment_webhook_processing_failed",
-        "Internal error processing payment event",
+        dispatched.isSuccess && options.afterDispatch
+          ? await options.afterDispatch(dispatched, tenantId, deps)
+          : dispatched,
+        "subscription_webhook_processing_failed",
+        "Internal error processing subscription event",
       );
-    }
-
-    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,
-      },
-    });
-    return respondFromDispatch(
-      c,
-      dispatched,
-      "subscription_webhook_processing_failed",
-      "Internal error processing subscription event",
-    );
-  };
+    },
+  });
 }
 
 /** Shared 500/200-mapping for both dispatch branches above. Internal error →
  *  provider should retry, hence 500 instead of 401/404 (transient, not a config-bug). */
 function respondFromDispatch(
   c: Context,
-  dispatched: Awaited<ReturnType<SubscriptionWebhookDeps["dispatchWrite"]>>,
+  dispatched: import("@cosmicdrift/kumiko-framework/engine").WriteResult,
   errorCode: string,
   errorMessage: string,
 ): Response {
@@ -219,13 +159,3 @@ function respondFromDispatch(
   }
   return c.json({ processed: true, ...((dispatched.data as object) ?? {}) }, 200); // @cast-boundary engine-bridge
 }
-
-/**
- * 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 };