@cosmicdrift/kumiko-bundled-features 0.296.0 → 0.299.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.296.0",
+  "version": "0.299.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -133,12 +133,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.296.0",
-    "@cosmicdrift/kumiko-framework": "0.296.0",
-    "@cosmicdrift/kumiko-headless": "0.296.0",
-    "@cosmicdrift/kumiko-renderer": "0.296.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.296.0",
-    "@cosmicdrift/kumiko-types": "0.296.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.299.0",
+    "@cosmicdrift/kumiko-framework": "0.299.0",
+    "@cosmicdrift/kumiko-headless": "0.299.0",
+    "@cosmicdrift/kumiko-renderer": "0.299.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.299.0",
+    "@cosmicdrift/kumiko-types": "0.299.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -167,8 +167,8 @@
   ],
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "@cosmicdrift/kumiko-locale-de": "0.296.0",
-    "@cosmicdrift/kumiko-locale-es": "0.296.0",
+    "@cosmicdrift/kumiko-locale-de": "0.299.0",
+    "@cosmicdrift/kumiko-locale-es": "0.299.0",
     "jsqr": "^1.4.0"
   }
 }

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

@@ -8,8 +8,8 @@
 // beweist die Foundation-eigene Verdrahtung (atomic insert + upsert,
 // Idempotency via deterministic aggregate-ids, tenant-isolation).
 //
-// Webhook-Handler-Factory (createSubscriptionWebhookHandler) wird in
-// einem separaten Test mit Hono-mock geprüft.
+// Webhook-route (createSubscriptionWebhookRoute) gets its own dedicated
+// coverage in webhook-handler.integration.test.ts.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
@@ -22,7 +22,7 @@ import {
   PII_ERASED_SENTINEL,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { defineFeature, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import { isStreamArchived, loadAggregate } from "@cosmicdrift/kumiko-framework/event-store";
 import {
   createTestUser,
@@ -32,7 +32,6 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
-import { Hono } from "hono";
 import {
   ComplianceProfileHandlers,
   createComplianceProfilesFeature,
@@ -53,7 +52,7 @@ import { billingFoundationFeature } from "../feature";
 import { paymentsProjectionTable, subscriptionsProjectionTable } from "../projection";
 import { subscriptionTenantDestroyHook } from "../tenant-destroy-hook";
 import type { PaymentEvent, SubscriptionProviderPlugin } from "../types";
-import { createSubscriptionWebhookHandler } from "../webhook-handler";
+import { createSubscriptionWebhookRoute } from "../webhook-handler";
 
 // =============================================================================
 // Mock-plugin für create-checkout-session + create-portal-session-Tests.
@@ -126,7 +125,6 @@ const mockPaymentProviderFeature = defineFeature("test-mock-payment-provider", (
 
 let stack: TestStack;
 let db: DbConnection;
-let paymentWebhookApp: Hono;
 
 beforeAll(async () => {
   stack = await setupTestStack({
@@ -139,6 +137,10 @@ beforeAll(async () => {
       mockProviderFeature,
       mockPaymentProviderFeature,
     ],
+    // Scenario 11 exercises the real payment-branch of the webhook route
+    // (webhook-handler.ts) mounted through the same stack — no hand-rolled
+    // Hono app, real HTTP via stack.app.
+    extraRoutes: [createSubscriptionWebhookRoute()],
   });
   db = stack.db;
   // subscriptionsProjectionTable wird von setupTestStack automatisch
@@ -150,34 +152,6 @@ beforeAll(async () => {
   // see feature.ts), so process-event.write.ts calls configuredPiiSubjectKms()
   // directly and needs one configured, same as run{Prod,Dev}App do at boot.
   configurePiiSubjectKms(new InMemoryKmsAdapter());
-
-  // Webhook-app for scenario 11 — same mountWebhook shape as
-  // stripe-foundation.integration.test.ts, exercising the real
-  // createSubscriptionWebhookHandler payment-branch (webhook-handler.ts).
-  paymentWebhookApp = new Hono();
-  paymentWebhookApp.post(
-    "/api/subscription/webhook/:providerName",
-    createSubscriptionWebhookHandler({
-      dispatchWrite: async ({ handlerQn, payload, tenantId }) => {
-        const systemUser = createTestUser({
-          id: 1,
-          tenantId: tenantId as TenantId,
-          roles: ["SystemAdmin"],
-        });
-        const res = await stack.http.write(handlerQn, payload, systemUser);
-        const body = await res.json();
-        return body.isSuccess
-          ? { isSuccess: true, data: body.data }
-          : { isSuccess: false, error: body.error };
-      },
-      resolveProvider: (providerName) => {
-        const usage = stack.registry
-          .getExtensionUsages("subscriptionProvider")
-          .find((u) => u.entityName === providerName);
-        return usage?.options as SubscriptionProviderPlugin | undefined;
-      },
-    }),
-  );
 });
 
 afterAll(async () => {
@@ -993,7 +967,7 @@ describe("scenario 11: one-off payment — own aggregate, own read_payments-row"
     expect(rowsB).toHaveLength(1);
   });
 
-  test("webhook-handler payment-branch (createSubscriptionWebhookHandler): POST → row, retry POST → duplicate:true, still one row", async () => {
+  test("webhook-route payment-branch (createSubscriptionWebhookRoute): POST → row, retry POST → duplicate:true, still one row", async () => {
     const tenantId = testTenantId(4004);
     const body = JSON.stringify({
       providerEventId: "evt_webhook_payment_001",
@@ -1002,7 +976,7 @@ describe("scenario 11: one-off payment — own aggregate, own read_payments-row"
       priceId: "price_webhook_test",
     });
 
-    const first = await paymentWebhookApp.request("/api/subscription/webhook/mock-payment", {
+    const first = await stack.app.request("/api/subscription/webhook/mock-payment", {
       method: "POST",
       body,
     });
@@ -1011,7 +985,7 @@ describe("scenario 11: one-off payment — own aggregate, own read_payments-row"
     expect(firstBody["processed"]).toBe(true);
     expect(firstBody["duplicate"]).toBe(false);
 
-    const second = await paymentWebhookApp.request("/api/subscription/webhook/mock-payment", {
+    const second = await stack.app.request("/api/subscription/webhook/mock-payment", {
       method: "POST",
       body,
     });

package/src/billing-foundation/__tests__/subscription-tier-sync.integration.test.ts

@@ -1,28 +1,28 @@
-// Integration test for createSubscriptionTierSync()'s onSyncError option
-// (#3027). Forces a sync failure via a dispatchSystemWrite stub that fails
-// only the tier-engine handlers (the primary billing-foundation writes run
-// for real against the test DB) — proving that "log" (default) still
-// answers the webhook successfully, while "fail-webhook" surfaces the sync
-// error all the way into the HTTP response.
+// Integration test for createSubscriptionTierSync() (kumiko-framework
+// #3050 rewrite). No stubbed dispatchSystemWrite anymore — the sync reads
+// and writes through the real dispatcher via the extraRoute's
+// dispatchSystemQuery/dispatchSystemWrite, exercised with real HTTP.
+//
+// `createWebhookRoute()` has a fixed path (SUBSCRIPTION_WEBHOOK_PATH), so
+// the two onSyncError modes ("log" vs "fail-webhook") each need their own
+// stack — you can't mount the same path twice on one Hono app.
+//
+// The forced sync failure is a REAL one: a stack that never mounts
+// tier-engine, so `TierEngineQueries.list` resolves to no handler and
+// dispatchSystemQuery throws — exactly what a consumer forgetting to mount
+// tier-engine would hit in production.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { configurePiiSubjectKms, InMemoryKmsAdapter } from "@cosmicdrift/kumiko-framework/crypto";
-import { buildEntityTable, type EntityTable } from "@cosmicdrift/kumiko-framework/db";
-import {
-  defineFeature,
-  type EntityDefinition,
-  type TenantId,
-} from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createTestUser,
   setupTestStack,
   type TestStack,
   testTenantId,
   unsafeCreateEntityTable,
-  unsafePushTables,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
-import { Hono } from "hono";
 import {
   createComplianceProfilesFeature,
   tenantComplianceProfileEntity,
@@ -32,16 +32,12 @@ import { createTenantFeature } from "../../tenant/feature";
 import { tenantEntity } from "../../tenant/schema/tenant";
 import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
 import type { TierMap } from "../../tier-engine/compose-app";
-import { TierEngineHandlers } from "../../tier-engine/constants";
+import { TierEngineQueries } from "../../tier-engine/constants";
 import { tierAssignmentEntity } from "../../tier-engine/entity";
 import { createTierEngineFeature } from "../../tier-engine/feature";
 import { SubscriptionEventTypes, SubscriptionStatuses } from "../constants";
 import { billingFoundationFeature } from "../feature";
-import {
-  createSubscriptionTierSync,
-  SUBSCRIPTION_WEBHOOK_PATH,
-  type SystemWriteResult,
-} from "../subscription-tier-sync";
+import { createSubscriptionTierSync } from "../subscription-tier-sync";
 import type { SubscriptionEvent, SubscriptionProviderPlugin } from "../types";
 
 type TestTier = "free" | "pro";
@@ -51,98 +47,42 @@ const TEST_TIER_MAP: TierMap<{ readonly maxItems: number }> = {
   pro: { features: [], caps: { maxItems: 100 } },
 };
 
-const mockProviderFeature = defineFeature("test-mock-tier-sync-provider", (r) => {
-  r.requires("billing-foundation");
-  const plugin: SubscriptionProviderPlugin = {
-    verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody) as SubscriptionEvent,
-  };
-  r.useExtension("subscriptionProvider", "mock", plugin);
-});
-
-// Boundary-cast: SubscriptionTierSyncDeps deliberately erases the entity's
-// concrete field types to EntityDefinition (generic factory), which TS
-// can't structurally widen to on its own.
-const tierAssignmentTable = buildEntityTable(
-  "tier-assignment",
-  tierAssignmentEntity,
-) as unknown as EntityTable<EntityDefinition>;
-
-let stack: TestStack;
-let forceTierSyncFailure = false;
-
-async function dispatchSystemWrite(args: {
-  readonly handlerQn: string;
-  readonly payload: unknown;
-  readonly tenantId: TenantId;
-}): Promise<SystemWriteResult> {
-  if (
-    forceTierSyncFailure &&
-    (args.handlerQn === TierEngineHandlers.create || args.handlerQn === TierEngineHandlers.update)
-  ) {
-    return {
-      isSuccess: false,
-      error: { code: "test_forced_failure", message: "forced tier-sync failure" },
+function mockProviderFeature() {
+  return defineFeature("test-mock-tier-sync-provider", (r) => {
+    r.requires("billing-foundation");
+    const plugin: SubscriptionProviderPlugin = {
+      verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody) as SubscriptionEvent,
     };
-  }
-  const systemUser = createTestUser({ id: 1, tenantId: args.tenantId, roles: ["SystemAdmin"] });
-  const res = await stack.http.write(args.handlerQn, args.payload, systemUser);
-  const body = (await res.json()) as {
-    isSuccess: boolean;
-    data?: unknown;
-    error?: { readonly code?: string; readonly message?: string };
-  };
-  return body.isSuccess
-    ? { isSuccess: true, data: body.data }
-    : { isSuccess: false, error: body.error };
+    r.useExtension("subscriptionProvider", "mock", plugin);
+  });
 }
 
-let logApp: Hono;
-let failApp: Hono;
-
-beforeAll(async () => {
-  stack = await setupTestStack({
-    features: [
-      createConfigFeature(),
-      createTenantFeature(),
-      createComplianceProfilesFeature(),
-      createTenantLifecycleFeature(),
-      billingFoundationFeature,
-      createTierEngineFeature({ defaultTier: "free", tierMap: TEST_TIER_MAP }),
-      mockProviderFeature,
-    ],
-  });
+const sharedBaseFeatures = () => [
+  createConfigFeature(),
+  createTenantFeature(),
+  createComplianceProfilesFeature(),
+  createTenantLifecycleFeature(),
+  billingFoundationFeature,
+  mockProviderFeature(),
+];
+
+async function bootStack(
+  features: ReturnType<typeof sharedBaseFeatures>,
+  extraRoutes: NonNullable<Parameters<typeof setupTestStack>[0]["extraRoutes"]>,
+): Promise<TestStack> {
+  const stack = await setupTestStack({ features, extraRoutes });
   await unsafeCreateEntityTable(stack.db, tenantEntity);
   await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
-  await unsafePushTables(stack.db, { tier_assignments: tierAssignmentTable });
+  await unsafeCreateEntityTable(stack.db, tierAssignmentEntity);
   configurePiiSubjectKms(new InMemoryKmsAdapter());
+  return stack;
+}
 
-  const sharedDeps = {
-    db: stack.db,
-    registry: stack.registry,
-    dispatchSystemWrite,
-    tierAssignmentTable,
-    isTierName,
-    defaultTier: "free" as const,
-  };
-
-  logApp = new Hono();
-  createSubscriptionTierSync<TestTier>(sharedDeps).wireSubscriptionWebhookRoute(logApp);
-
-  failApp = new Hono();
-  createSubscriptionTierSync<TestTier>({
-    ...sharedDeps,
-    onSyncError: "fail-webhook",
-  }).wireSubscriptionWebhookRoute(failApp);
-});
-
-afterAll(async () => {
-  await stack.cleanup();
-  resetPiiSubjectKmsForTests();
-});
-
-const webhookPath = SUBSCRIPTION_WEBHOOK_PATH.replace(":providerName", "mock");
-
-function buildEvent(tenantId: string, providerEventId: string): SubscriptionEvent {
+function buildEvent(
+  tenantId: string,
+  providerEventId: string,
+  overrides: Partial<SubscriptionEvent> = {},
+): SubscriptionEvent {
   return {
     providerEventId,
     providerName: "mock",
@@ -154,33 +94,133 @@ function buildEvent(tenantId: string, providerEventId: string): SubscriptionEven
     tier: "pro",
     currentPeriodEnd: "2026-06-01T00:00:00Z",
     rawPayload: "{}",
+    ...overrides,
   };
 }
 
+async function postWebhook(stack: TestStack, path: string, event: SubscriptionEvent) {
+  return stack.app.request(path.replace(":providerName", "mock"), {
+    method: "POST",
+    body: JSON.stringify(event),
+  });
+}
+
+// =============================================================================
+// onSyncError — tier-engine deliberately NOT mounted, so the sync's
+// dispatchSystemQuery(TierEngineQueries.list) throws a real NotFoundError.
+// =============================================================================
+
 describe("createSubscriptionTierSync onSyncError", () => {
-  test("default ('log'): a tier-sync failure still returns a successful webhook response", async () => {
-    forceTierSyncFailure = true;
-    const tenantId = testTenantId(9001);
-    const res = await logApp.request(webhookPath, {
-      method: "POST",
-      body: JSON.stringify(buildEvent(tenantId, "evt_log_1")),
+  let logStack: TestStack;
+  let failStack: TestStack;
+  let logPath: string;
+  let failPath: string;
+
+  beforeAll(async () => {
+    const logSync = createSubscriptionTierSync<TestTier>({ isTierName, defaultTier: "free" });
+    const logRoute = logSync.createWebhookRoute();
+    logStack = await bootStack(sharedBaseFeatures(), [logRoute]);
+    logPath = logRoute.path;
+
+    const failSync = createSubscriptionTierSync<TestTier>({
+      isTierName,
+      defaultTier: "free",
+      onSyncError: "fail-webhook",
     });
-    forceTierSyncFailure = false;
+    const failRoute = failSync.createWebhookRoute();
+    failStack = await bootStack(sharedBaseFeatures(), [failRoute]);
+    failPath = failRoute.path;
+  });
+
+  afterAll(async () => {
+    await logStack.cleanup();
+    await failStack.cleanup();
+    resetPiiSubjectKmsForTests();
+  });
 
+  test("default ('log'): a tier-sync failure still returns a successful webhook response", async () => {
+    const tenantId = testTenantId(9001);
+    const res = await postWebhook(logStack, logPath, buildEvent(tenantId, "evt_log_1"));
     expect(res.status).toBe(200);
   });
 
   test("'fail-webhook': a tier-sync failure also fails the webhook response", async () => {
-    forceTierSyncFailure = true;
     const tenantId = testTenantId(9002);
-    const res = await failApp.request(webhookPath, {
-      method: "POST",
-      body: JSON.stringify(buildEvent(tenantId, "evt_fail_1")),
-    });
-    forceTierSyncFailure = false;
-
+    const res = await postWebhook(failStack, failPath, buildEvent(tenantId, "evt_fail_1"));
     expect(res.status).toBe(500);
     const body = (await res.json()) as { error: { code: string } };
     expect(body.error.code).toBe("subscription_webhook_processing_failed");
   });
 });
+
+// =============================================================================
+// Happy path — tier-engine mounted, tier-sync effect visible through
+// TierEngineQueries.list.
+// =============================================================================
+
+describe("createSubscriptionTierSync — tier-sync effect", () => {
+  let stack: TestStack;
+  let webhookPath: string;
+
+  beforeAll(async () => {
+    const sync = createSubscriptionTierSync<TestTier>({ isTierName, defaultTier: "free" });
+    const route = sync.createWebhookRoute();
+    webhookPath = route.path;
+    stack = await bootStack(
+      [
+        ...sharedBaseFeatures(),
+        createTierEngineFeature({ defaultTier: "free", tierMap: TEST_TIER_MAP }),
+      ],
+      [route],
+    );
+  });
+
+  afterAll(async () => {
+    await stack.cleanup();
+    resetPiiSubjectKmsForTests();
+  });
+
+  test("active subscription → tier-assignment created with the subscription's tier", async () => {
+    const tenantId = testTenantId(9101);
+    const res = await postWebhook(
+      stack,
+      webhookPath,
+      buildEvent(tenantId, "evt_create_1", { status: SubscriptionStatuses.active, tier: "pro" }),
+    );
+    expect(res.status).toBe(200);
+
+    const admin = createTestUser({ id: 9101, tenantId, roles: ["SystemAdmin"] });
+    const listed = (await stack.http.queryOk(TierEngineQueries.list, {}, admin)) as {
+      rows: Array<Record<string, unknown>>;
+    };
+    expect(listed.rows).toHaveLength(1);
+    expect(listed.rows[0]?.["tier"]).toBe("pro");
+  });
+
+  test("subsequent canceled event → tier-assignment updated to the default tier", async () => {
+    const tenantId = testTenantId(9102);
+    await postWebhook(
+      stack,
+      webhookPath,
+      buildEvent(tenantId, "evt_create_2", { status: SubscriptionStatuses.active, tier: "pro" }),
+    );
+
+    const res = await postWebhook(
+      stack,
+      webhookPath,
+      buildEvent(tenantId, "evt_cancel_2", {
+        type: SubscriptionEventTypes.canceled,
+        status: SubscriptionStatuses.canceled,
+        tier: "pro",
+      }),
+    );
+    expect(res.status).toBe(200);
+
+    const admin = createTestUser({ id: 9102, tenantId, roles: ["SystemAdmin"] });
+    const listed = (await stack.http.queryOk(TierEngineQueries.list, {}, admin)) as {
+      rows: Array<Record<string, unknown>>;
+    };
+    expect(listed.rows).toHaveLength(1);
+    expect(listed.rows[0]?.["tier"]).toBe("free");
+  });
+});

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

@@ -0,0 +1,174 @@
+// Integration-tests for createSubscriptionWebhookRoute (kumiko-framework
+// #3050). No injected dispatchWrite/resolveProvider stubs anymore — the
+// route is a real `entry:"signature"` extraRoute mounted through
+// setupTestStack, driven with real HTTP against the real dispatcher +
+// registry (never createTestDispatcher, per project rule).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  setupTestStack,
+  type TestStack,
+  testTenantId,
+  unsafeCreateEntityTable,
+} from "@cosmicdrift/kumiko-framework/stack";
+import {
+  createComplianceProfilesFeature,
+  tenantComplianceProfileEntity,
+} from "../../compliance-profiles";
+import { createConfigFeature } from "../../config";
+import { createTenantFeature } from "../../tenant/feature";
+import { tenantEntity } from "../../tenant/schema/tenant";
+import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
+import {
+  SubscriptionEventTypes,
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "../constants";
+import { billingFoundationFeature } from "../feature";
+import type { SubscriptionEvent, SubscriptionProviderPlugin } from "../types";
+import { createSubscriptionWebhookRoute } from "../webhook-handler";
+
+const stripeLikePlugin: SubscriptionProviderPlugin = {
+  verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody) as SubscriptionEvent | null,
+};
+const paypalLikePlugin: SubscriptionProviderPlugin = {
+  verifyAndParseWebhook: async (rawBody) => JSON.parse(rawBody) as SubscriptionEvent | null,
+};
+
+// Test-mock-provider whose `verifyAndParseWebhook` is swapped per test via
+// `resolvedPlugin` — lets each scenario control verify()'s throw/return
+// behavior without touching the wired extraRoute.
+const mockProviderFeature = defineFeature("test-mock-webhook-provider", (r) => {
+  r.requires("billing-foundation");
+  r.useExtension("subscriptionProvider", "stripe", stripeLikePlugin);
+  r.useExtension("subscriptionProvider", "paypal", paypalLikePlugin);
+});
+
+let stack: TestStack;
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [
+      createConfigFeature(),
+      createTenantFeature(),
+      createComplianceProfilesFeature(),
+      createTenantLifecycleFeature(),
+      billingFoundationFeature,
+      mockProviderFeature,
+    ],
+    extraRoutes: [createSubscriptionWebhookRoute()],
+  });
+  await unsafeCreateEntityTable(stack.db, tenantEntity);
+  await unsafeCreateEntityTable(stack.db, tenantComplianceProfileEntity);
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+function buildEvent(overrides: Partial<SubscriptionEvent> = {}): SubscriptionEvent {
+  return {
+    providerEventId: "evt_test_001",
+    providerName: "stripe",
+    type: SubscriptionEventTypes.created,
+    tenantId: testTenantId(5001),
+    providerCustomerId: "cus_test",
+    providerSubscriptionId: "sub_test",
+    status: SubscriptionStatuses.active,
+    tier: "pro",
+    currentPeriodEnd: "2026-06-01T00:00:00Z",
+    rawPayload: '{"raw":"payload"}',
+    ...overrides,
+  };
+}
+
+async function postWebhook(providerName: string, body: unknown) {
+  return stack.app.request(`/api/subscription/webhook/${providerName}`, {
+    method: "POST",
+    body: JSON.stringify(body),
+    headers: { "stripe-signature": "test_sig" },
+  });
+}
+
+describe("webhook-handler — happy path", () => {
+  test("verifyAndParseWebhook → SubscriptionEvent → process-event write → 200 processed", async () => {
+    const res = await postWebhook("stripe", buildEvent({ tenantId: testTenantId(5002) }));
+    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);
+  });
+
+  test("plugin returns null (unknown event-type) → 200 ignored", async () => {
+    const res = await stack.app.request("/api/subscription/webhook/stripe", {
+      method: "POST",
+      body: "null",
+      headers: { "stripe-signature": "test_sig" },
+    });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as { ignored: boolean };
+    expect(body.ignored).toBe(true);
+  });
+});
+
+describe("webhook-handler — error paths", () => {
+  test("provider not registered → 404 subscription_provider_not_registered", async () => {
+    const res = await postWebhook("ghost-provider", buildEvent());
+    expect(res.status).toBe(404);
+    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-provider/);
+  });
+
+  test("verify() throws (sig mismatch) → 401 extra_route_signature_invalid", async () => {
+    const res = await stack.app.request("/api/subscription/webhook/stripe", {
+      method: "POST",
+      body: "not valid json — forces JSON.parse to throw inside verify()",
+      headers: { "stripe-signature": "test_sig" },
+    });
+    expect(res.status).toBe(401);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("extra_route_signature_invalid");
+  });
+
+  test("process-event write rejected by schema → 500 subscription_webhook_processing_failed", async () => {
+    // status outside the enum trips processEventSchema validation inside
+    // process-event.write.ts, so dispatchSystemWrite returns isSuccess:false
+    // — a real dispatch failure, not a stubbed one.
+    const res = await postWebhook(
+      "stripe",
+      // @cast-boundary test-only invalid input — deliberately outside the
+      // SubscriptionStatus enum to trip processEventSchema validation.
+      buildEvent({
+        tenantId: testTenantId(5003),
+        status: "not-a-real-status" as SubscriptionStatus,
+      }),
+    );
+    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");
+  });
+});
+
+describe("webhook-handler — multi-provider mounting", () => {
+  test("two different path-segments resolve to two different plugins", async () => {
+    const stripeRes = await postWebhook(
+      "stripe",
+      buildEvent({ tenantId: testTenantId(5004), providerEventId: "evt_multi_stripe" }),
+    );
+    const paypalRes = await postWebhook(
+      "paypal",
+      buildEvent({
+        tenantId: testTenantId(5005),
+        providerEventId: "evt_multi_paypal",
+        providerName: "paypal",
+      }),
+    );
+
+    expect(stripeRes.status).toBe(200);
+    expect(paypalRes.status).toBe(200);
+  });
+});

package/src/billing-foundation/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.298.0",
+    "type": "breaking",
+    "title": "Billing webhook wiring moves from a raw handler to createSubscriptionWebhookRoute()/createWebhookRoute()",
+    "migration": "createSubscriptionWebhookHandler(...) is replaced by createSubscriptionWebhookRoute({ path?, afterDispatch? }), which returns an ExtraRouteDefinition for the extraRoutes array instead of a manually-mounted handler; the route path still defaults to /webhooks/subscription/:providerName. createSubscriptionTierSync(...) deps drop db, registry, dispatchSystemWrite and tierAssignmentTable - it now exposes .createWebhookRoute(), which produces the signature-verified ExtraRouteDefinition to add to extraRoutes. A webhook previously wired as extraRoutes: (app, deps) => { app.post(\"/webhooks/subscription/:providerName\", createSubscriptionWebhookHandler(...)) } becomes extraRoutes: [createSubscriptionTierSync({ ... }).createWebhookRoute()] (or createSubscriptionWebhookRoute({...}) for the lower-level handler), with db/registry/dispatchSystemWrite no longer passed in - the route's signature-entry deps (systemQuery, dispatchSystemWrite, dispatchSystemQuery) cover the read/write access the old handler needed."
+  },
   {
     "version": "0.288.0",
     "type": "improvement",