@cosmicdrift/kumiko-bundled-features 0.251.0 → 0.252.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.251.0",
+  "version": "0.252.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>",
@@ -130,12 +130,12 @@
     "./workflow-runner": "./src/workflow-runner/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.251.0",
-    "@cosmicdrift/kumiko-framework": "0.251.0",
-    "@cosmicdrift/kumiko-headless": "0.251.0",
-    "@cosmicdrift/kumiko-renderer": "0.251.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.251.0",
-    "@cosmicdrift/kumiko-types": "0.251.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.252.0",
+    "@cosmicdrift/kumiko-framework": "0.252.0",
+    "@cosmicdrift/kumiko-headless": "0.252.0",
+    "@cosmicdrift/kumiko-renderer": "0.252.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.252.0",
+    "@cosmicdrift/kumiko-types": "0.252.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/mailparser": "^3.4.6",
@@ -164,7 +164,7 @@
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
     "@types/qrcode": "^1.5.5",
-    "@cosmicdrift/kumiko-locale-de": "0.251.0",
-    "@cosmicdrift/kumiko-locale-es": "0.251.0"
+    "@cosmicdrift/kumiko-locale-de": "0.252.0",
+    "@cosmicdrift/kumiko-locale-es": "0.252.0"
   }
 }

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

@@ -22,7 +22,7 @@ import {
   PII_ERASED_SENTINEL,
 } from "@cosmicdrift/kumiko-framework/crypto";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
-import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { defineFeature, type TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import {
   createEventsTable,
   isStreamArchived,
@@ -36,6 +36,7 @@ import {
   unsafeCreateEntityTable,
 } from "@cosmicdrift/kumiko-framework/stack";
 import { resetPiiSubjectKmsForTests } from "@cosmicdrift/kumiko-framework/testing";
+import { Hono } from "hono";
 import {
   ComplianceProfileHandlers,
   createComplianceProfilesFeature,
@@ -44,16 +45,18 @@ import {
 import { createConfigFeature } from "../../config";
 import { createTenantFeature } from "../../tenant/feature";
 import { createTenantLifecycleFeature } from "../../tenant-lifecycle";
-import { subscriptionAggregateId } from "../aggregate-id";
+import { paymentAggregateId, subscriptionAggregateId } from "../aggregate-id";
 import {
+  BillingEventKinds,
   SubscriptionEventTypes,
   SubscriptionFoundationHandlers,
   SubscriptionStatuses,
 } from "../constants";
 import { billingFoundationFeature } from "../feature";
-import { subscriptionsProjectionTable } from "../projection";
+import { paymentsProjectionTable, subscriptionsProjectionTable } from "../projection";
 import { subscriptionTenantDestroyHook } from "../tenant-destroy-hook";
-import type { SubscriptionProviderPlugin } from "../types";
+import type { PaymentEvent, SubscriptionProviderPlugin } from "../types";
+import { createSubscriptionWebhookHandler } from "../webhook-handler";
 
 // =============================================================================
 // Mock-plugin für create-checkout-session + create-portal-session-Tests.
@@ -98,12 +101,35 @@ const mockProviderFeature = defineFeature("test-mock-provider", (r) => {
   r.useExtension("subscriptionProvider", "mock", plugin);
 });
 
+// Second mock provider — parses its rawBody straight into a PaymentEvent
+// (no real Stripe-signing needed here, that's subscription-stripe's job).
+// Exercises the webhook-handler's payment branch end-to-end (scenario 11).
+const mockPaymentProviderFeature = defineFeature("test-mock-payment-provider", (r) => {
+  r.requires("billing-foundation");
+  const plugin: SubscriptionProviderPlugin = {
+    verifyAndParseWebhook: async (rawBody): Promise<PaymentEvent | null> => {
+      const parsed = JSON.parse(rawBody) as Record<string, string>;
+      return {
+        kind: BillingEventKinds.payment,
+        providerEventId: parsed["providerEventId"] ?? "evt_mock_payment",
+        providerName: "mock-payment",
+        tenantId: parsed["tenantId"] ?? "tenant-mock",
+        providerCustomerId: parsed["providerCustomerId"] ?? "cus_mock",
+        priceId: parsed["priceId"] ?? "price_mock",
+        rawPayload: rawBody,
+      };
+    },
+  };
+  r.useExtension("subscriptionProvider", "mock-payment", plugin);
+});
+
 // =============================================================================
 // Setup
 // =============================================================================
 
 let stack: TestStack;
 let db: DbConnection;
+let paymentWebhookApp: Hono;
 
 beforeAll(async () => {
   stack = await setupTestStack({
@@ -114,6 +140,7 @@ beforeAll(async () => {
       createTenantLifecycleFeature(),
       billingFoundationFeature,
       mockProviderFeature,
+      mockPaymentProviderFeature,
     ],
   });
   db = stack.db;
@@ -126,6 +153,34 @@ 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 () => {
@@ -807,3 +862,166 @@ describe("scenario 10: PII is encrypted at rest, not just erasable on destroy",
   // (`{kind: "user"}`), not the tenant-subject fields billing uses. Closing
   // that gap is new framework capability, not a wiring fix.
 });
+
+// =============================================================================
+// Scenario 11 — one-off payments (fw#2791): own aggregate, own
+// read_payments-row, idempotent like process-event above.
+// =============================================================================
+
+function buildPaymentEventPayload(
+  overrides: Partial<{
+    providerEventId: string;
+    providerCustomerId: string;
+    priceId: string;
+    rawPayload: string;
+  }> = {},
+) {
+  return {
+    providerEventId: overrides.providerEventId ?? "evt_payment_default",
+    providerName: "stripe",
+    providerCustomerId: overrides.providerCustomerId ?? "cus_payment_default",
+    priceId: overrides.priceId ?? "price_topup_test",
+    rawPayload: overrides.rawPayload ?? '{"raw":"payment-payload"}',
+  };
+}
+
+describe("scenario 11: one-off payment — own aggregate, own read_payments-row", () => {
+  test("first payment for tenant → read_payments-row created, duplicate=false", async () => {
+    const admin = adminFor(4001);
+    const result = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processPaymentEvent,
+      buildPaymentEventPayload({
+        providerEventId: "evt_4001_payment",
+        providerCustomerId: "cus_4001",
+        priceId: "price_topup_test",
+      }),
+      admin,
+    )) as Record<string, unknown>;
+
+    expect(result["duplicate"]).toBe(false);
+    expect(result["paymentAggregateId"]).toBe(paymentAggregateId(admin.tenantId));
+
+    const rows = await selectMany<{ tenantId: string; priceId: string; providerName: string }>(
+      db,
+      paymentsProjectionTable,
+      { tenantId: admin.tenantId },
+    );
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.priceId).toBe("price_topup_test");
+    expect(rows[0]?.providerName).toBe("stripe");
+  });
+
+  test("idempotency: second call with same providerEventId → duplicate=true, no second row", async () => {
+    const admin = adminFor(4002);
+
+    const first = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processPaymentEvent,
+      buildPaymentEventPayload({
+        providerEventId: "evt_4002_retry",
+        providerCustomerId: "cus_4002",
+      }),
+      admin,
+    )) as Record<string, unknown>;
+    expect(first["duplicate"]).toBe(false);
+
+    const second = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processPaymentEvent,
+      buildPaymentEventPayload({
+        providerEventId: "evt_4002_retry",
+        providerCustomerId: "cus_4002",
+        priceId: "price_should_be_ignored",
+      }),
+      admin,
+    )) as Record<string, unknown>;
+    expect(second["duplicate"]).toBe(true);
+
+    const rows = await selectMany(db, paymentsProjectionTable, { tenantId: admin.tenantId });
+    expect(rows).toHaveLength(1); // dedup'd — no second row
+
+    const esEvents = await loadAggregate(db, paymentAggregateId(admin.tenantId), admin.tenantId);
+    expect(esEvents).toHaveLength(1);
+  });
+
+  test("second payment for the same tenant → second row (payments are facts, not state — no upsert)", async () => {
+    const admin = adminFor(4003);
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processPaymentEvent,
+      buildPaymentEventPayload({
+        providerEventId: "evt_4003_first",
+        providerCustomerId: "cus_4003",
+      }),
+      admin,
+    );
+    await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processPaymentEvent,
+      buildPaymentEventPayload({
+        providerEventId: "evt_4003_second",
+        providerCustomerId: "cus_4003",
+      }),
+      admin,
+    );
+
+    const rows = await selectMany(db, paymentsProjectionTable, { tenantId: admin.tenantId });
+    expect(rows).toHaveLength(2);
+  });
+
+  test("idempotency anchor is tenant-scoped — same providerEventId for TWO tenants is NOT duplicate, each gets its own row", async () => {
+    // Same shape as scenario 4's cross-tenant pin: two tenants can
+    // legitimately see the same providerEventId (multiple Stripe accounts,
+    // test/prod mix). paymentRowId includes tenantId in its key — without
+    // that, the second INSERT would silently no-op (ON CONFLICT DO NOTHING)
+    // against the first tenant's row instead of creating its own.
+    const adminA = adminFor(4005);
+    const adminB = adminFor(4006);
+    const SHARED_EVT = "evt_shared_payment_id";
+
+    const a = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processPaymentEvent,
+      buildPaymentEventPayload({ providerEventId: SHARED_EVT, providerCustomerId: "cus_a_shared" }),
+      adminA,
+    )) as Record<string, unknown>;
+    const b = (await stack.http.writeOk(
+      SubscriptionFoundationHandlers.processPaymentEvent,
+      buildPaymentEventPayload({ providerEventId: SHARED_EVT, providerCustomerId: "cus_b_shared" }),
+      adminB,
+    )) as Record<string, unknown>;
+
+    expect(a["duplicate"]).toBe(false);
+    expect(b["duplicate"]).toBe(false);
+
+    const rowsA = await selectMany(db, paymentsProjectionTable, { tenantId: adminA.tenantId });
+    const rowsB = await selectMany(db, paymentsProjectionTable, { tenantId: adminB.tenantId });
+    expect(rowsA).toHaveLength(1);
+    expect(rowsB).toHaveLength(1);
+  });
+
+  test("webhook-handler payment-branch (createSubscriptionWebhookHandler): POST → row, retry POST → duplicate:true, still one row", async () => {
+    const tenantId = testTenantId(4004);
+    const body = JSON.stringify({
+      providerEventId: "evt_webhook_payment_001",
+      tenantId,
+      providerCustomerId: "cus_webhook_4004",
+      priceId: "price_webhook_test",
+    });
+
+    const first = await paymentWebhookApp.request("/api/subscription/webhook/mock-payment", {
+      method: "POST",
+      body,
+    });
+    expect(first.status).toBe(200);
+    const firstBody = (await first.json()) as Record<string, unknown>;
+    expect(firstBody["processed"]).toBe(true);
+    expect(firstBody["duplicate"]).toBe(false);
+
+    const second = await paymentWebhookApp.request("/api/subscription/webhook/mock-payment", {
+      method: "POST",
+      body,
+    });
+    expect(second.status).toBe(200);
+    const secondBody = (await second.json()) as Record<string, unknown>;
+    expect(secondBody["duplicate"]).toBe(true);
+
+    const rows = await selectMany(db, paymentsProjectionTable, { tenantId });
+    expect(rows).toHaveLength(1);
+  });
+});

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

@@ -1,7 +1,7 @@
 // feature.ts contract tests for subscription-foundation.
 
 import { describe, expect, test } from "bun:test";
-import { subscriptionAggregateId } from "../aggregate-id";
+import { paymentAggregateId, paymentRowId, subscriptionAggregateId } from "../aggregate-id";
 import {
   BILLING_FOUNDATION_FEATURE,
   SUBSCRIPTION_PROVIDER_EXTENSION,
@@ -85,6 +85,14 @@ describe("aggregate-id namespace — drift-pin", () => {
   test("subscriptionAggregateId stable per tenantId", () => {
     expect(subscriptionAggregateId("tenant-1")).toBe("bfe0d98f-293c-5215-af7a-3282629aa5d3");
   });
+
+  test("paymentAggregateId stable per tenantId", () => {
+    expect(paymentAggregateId("tenant-1")).toBe("ea425f43-38a8-53c5-98b2-084affd718c1");
+  });
+
+  test("paymentRowId stable per (tenantId, providerName, providerEventId)", () => {
+    expect(paymentRowId("tenant-1", "mock", "evt_1")).toBe("51117d31-4394-5f4e-a123-b30bc37f30b8");
+  });
 });
 
 describe("normalized constants — provider-agnostic event-types + statuses", () => {

package/src/billing-foundation/__tests__/subscription-provider-contract.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { BillingEventKinds } from "../constants";
 import type { SubscriptionProviderPlugin } from "../types";
 
 export type SubscriptionProviderContractFixture = {
@@ -50,8 +51,13 @@ export function describeSubscriptionProviderContract(
       if (!webhook) return;
       const event = await plugin.verifyAndParseWebhook(webhook.rawBody, webhook.headers);
       expect(event).not.toBeNull();
-      expect(event?.tenantId).toBe(webhook.expectedTenantId);
-      expect(event?.tier).toBe(webhook.expectedTier);
+      if (!event || event.kind === BillingEventKinds.payment) {
+        throw new Error(
+          "describeSubscriptionProviderContract: webhook fixture must parse into a SubscriptionEvent, not a PaymentEvent",
+        );
+      }
+      expect(event.tenantId).toBe(webhook.expectedTenantId);
+      expect(event.tier).toBe(webhook.expectedTier);
     });
 
     test("createCheckoutSession returns a hosted-page url", async () => {

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

@@ -9,6 +9,18 @@ import { v5 as uuidv5 } from "uuid";
 /** Pro Plattform-Tenant existiert genau EIN subscription-Aggregate. */
 const SUBSCRIPTION_NAMESPACE = "5c3b2d1e-9a4f-4e8c-b7a3-1f8d6c2e9a4b";
 
+/** Exactly ONE payment-aggregate-stream exists per platform tenant (it
+ *  collects many payment-received events — one stream per tenant, not one
+ *  per payment). Generated 2026-09-11, likewise set in stone. */
+const PAYMENT_NAMESPACE = "dec0b897-646d-4da3-be3c-e9a35a83f4e0";
+
+/** Namespace for deriving a `read_payments` row-id (PK) from
+ *  `(tenantId, providerName, providerEventId)` — see `paymentRowId` below.
+ *  StoredEvent.id is a bigserial (global chronological sequence), not a
+ *  UUID, so it can't back a uuid-typed PK. Generated 2026-09-11, set in
+ *  stone (same rationale as the two namespaces above). */
+const PAYMENT_ROW_NAMESPACE = "3a1c9f4e-6b2d-4c8a-9e5f-7d4b1a2c8e6f";
+
 /**
  * Deterministic aggregate-id für die subscription eines Plattform-
  * Tenants. EINE Subscription pro Tenant (Add-Ons sind line-items in
@@ -20,3 +32,33 @@ const SUBSCRIPTION_NAMESPACE = "5c3b2d1e-9a4f-4e8c-b7a3-1f8d6c2e9a4b";
 export function subscriptionAggregateId(tenantId: string): string {
   return uuidv5(tenantId, SUBSCRIPTION_NAMESPACE);
 }
+
+/**
+ * Deterministic aggregate-id for a platform tenant's payment-stream. A
+ * tenant can make arbitrarily many one-off-payments — all land as
+ * payment-received events on the same stream (like the subscription-
+ * stream); the read_payments-projection creates its own row per event
+ * (PK = paymentRowId(...), not aggregateId).
+ */
+// @wrapper-known uuid-domain
+export function paymentAggregateId(tenantId: string): string {
+  return uuidv5(tenantId, PAYMENT_NAMESPACE);
+}
+
+/** Deterministic `read_payments` row-id — keyed off `(tenantId, providerName,
+ *  providerEventId)` rather than the event-store's bigserial `event.id` (not
+ *  a UUID) or the shared per-tenant aggregateId (one row per payment). */
+// @wrapper-known uuid-domain
+export function paymentRowId(
+  tenantId: string,
+  providerName: string,
+  providerEventId: string,
+): string {
+  // tenantId is part of the key because the idempotency scan in
+  // process-payment-event.write.ts is per-tenant: two tenants can
+  // legitimately see the same providerEventId (multiple Stripe accounts,
+  // test/prod mix) — without it, the second tenant's INSERT would silently
+  // no-op (ON CONFLICT DO NOTHING) against the first tenant's row, losing
+  // the payment with no error anywhere.
+  return uuidv5(`${tenantId}:${providerName}:${providerEventId}`, PAYMENT_ROW_NAMESPACE);
+}

package/src/billing-foundation/constants.ts

@@ -21,6 +21,11 @@ export const SubscriptionFoundationHandlers = {
    *  current subscription, ruft plugin.createPortalSession, returnt
    *  hosted-portal-URL. */
   createPortalSession: "billing-foundation:write:create-portal-session",
+  /** Programmatic entry-point for the webhook-handler on a one-off-payment
+   *  (checkout mode "payment"). Its own per-tenant aggregate-stream
+   *  (payment-aggregate), separate from the subscription-aggregate — a
+   *  payment is not a subscription-state transition. */
+  processPaymentEvent: "billing-foundation:write:process-payment-event",
 } as const;
 
 // Qualified query handler names.
@@ -57,6 +62,17 @@ export const SubscriptionStatuses = {
 } as const;
 export type SubscriptionStatus = (typeof SubscriptionStatuses)[keyof typeof SubscriptionStatuses];
 
+// Discriminator for verifyAndParseWebhook's return union. `subscription` is
+// optional on SubscriptionEvent (kept backward-compatible for plugins like
+// subscription-mollie that pre-date this field) and required on
+// PaymentEvent — TS narrows `parsed.kind === BillingEventKinds.payment`
+// correctly either way since only PaymentEvent's `kind` can equal it.
+export const BillingEventKinds = {
+  subscription: "subscription",
+  payment: "payment",
+} as const;
+export type BillingEventKind = (typeof BillingEventKinds)[keyof typeof BillingEventKinds];
+
 // **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/

package/src/billing-foundation/db/queries/payment-projection.ts

@@ -0,0 +1,19 @@
+import { asRawClient } from "@cosmicdrift/kumiko-framework/bun-db";
+import type { DbRunner } from "@cosmicdrift/kumiko-framework/db";
+
+// INSERT-once, not UPSERT: unlike subscriptionsProjectionTable (one row per
+// tenant, state overwritten on every event), a payment row is an immutable
+// fact keyed by paymentRowId(tenantId, providerName, providerEventId) — ON
+// CONFLICT DO NOTHING makes a projection rebuild/replay idempotent without
+// ever mutating an existing row.
+export async function insertPaymentProjectionRow(
+  tx: DbRunner,
+  tableName: string,
+  insertCols: Record<string, unknown>,
+): Promise<void> {
+  const insertKeys = Object.keys(insertCols);
+  const insertPlaceholders = insertKeys.map((_, i) => `$${i + 1}`);
+  const sqlText = `INSERT INTO "${tableName}" (${insertKeys.map((k) => `"${k}"`).join(", ")}) VALUES (${insertPlaceholders.join(", ")}) ON CONFLICT ("id") DO NOTHING`;
+  // kumiko-lint-ignore raw-sql tableName + column keys are code-controlled, not user input: tableName is buildEntityTable()'s static table name and insertKeys come from applyPaymentReceived's hardcoded object-literal columns in projection.ts — only values flow through $1..$n
+  await asRawClient(tx).unsafe(sqlText, Object.values(insertCols));
+}

package/src/billing-foundation/entities.ts

@@ -74,3 +74,32 @@ export const subscriptionEntity = createEntity({
 // `tenantOwned`/`pii`/`userOwned` field doesn't need a matching manual
 // update at each call site.
 export const SUBSCRIPTION_PII_FIELDS = collectPiiSubjectFields(subscriptionEntity);
+
+// =============================================================================
+// `payment` — one row per one-off-payment (= read-model)
+// =============================================================================
+//
+// Inline-Projection-Target for the payment-received event (see feature.ts).
+// Unlike subscriptionEntity (one row per tenant, UPSERTed), a tenant can have
+// many payments — one INSERT-once row per event, PK = paymentRowId(...) (see
+// projection.ts / aggregate-id.ts). Source-of-truth is the event-store stream `payment` with
+// aggregate-id = paymentAggregateId(tenantId) — one stream per tenant
+// collecting all of that tenant's payment-received events.
+export const paymentEntity = createEntity({
+  table: "read_payments",
+  fields: {
+    providerName: createTextField({ required: true, maxLength: 50 }),
+    // Same `personal: "tenant"` rationale as subscriptionEntity above —
+    // crypto-shreds on tenant-destroy (#800) via eraseSubjectKeys.
+    providerCustomerId: createTextField({
+      required: true,
+      maxLength: 1000,
+      personal: "tenant",
+      find: "none",
+    }),
+    priceId: createTextField({ required: true, maxLength: 200 }),
+  },
+});
+
+// See the SUBSCRIPTION_PII_FIELDS comment above — same manual-wiring reason.
+export const PAYMENT_PII_FIELDS = collectPiiSubjectFields(paymentEntity);

package/src/billing-foundation/events.ts

@@ -73,3 +73,35 @@ export type SubscriptionEventHeaders = {
   readonly providerName: string;
   readonly rawPayload: string;
 };
+
+// =============================================================================
+// payment-received — one-off-payments (checkout mode "payment")
+// =============================================================================
+//
+// Own aggregate-type + event, separate from the 5 subscription events above.
+// A one-off-payment is not a subscription-state transition (no status/tier/
+// currentPeriodEnd) — it materializes as its own `read_payments` row (one
+// row per payment) via the payment-aggregate stream (one stream per tenant,
+// see aggregate-id.ts).
+
+export const PAYMENT_AGGREGATE_TYPE = "payment" as const;
+
+export const PAYMENT_RECEIVED_EVENT_SHORT = "payment-received" as const;
+export const PAYMENT_RECEIVED_EVENT_QN =
+  `${BILLING_FOUNDATION_FEATURE}:event:${PAYMENT_RECEIVED_EVENT_SHORT}` as const;
+
+export const paymentEventPayloadSchema = z.object({
+  providerName: z.string().min(1).max(50),
+  // 1000, not 200: `tenantOwned: true` on paymentEntity (see entities.ts) —
+  // this stores the PII-ciphertext, not the raw provider id. Mirrors
+  // subscriptionEventPayloadSchema's same rationale.
+  providerCustomerId: z.string().min(1).max(1000),
+  priceId: z.string().min(1).max(200),
+});
+export type PaymentEventPayload = z.infer<typeof paymentEventPayloadSchema>;
+
+export type PaymentEventHeaders = {
+  readonly providerEventId: string;
+  readonly providerName: string;
+  readonly rawPayload: string;
+};

package/src/billing-foundation/feature.ts

@@ -22,6 +22,10 @@
 //      webhook-handler aufruft, dispatcht zu type-passendem appendEvent.
 //   5. **createSubscriptionWebhookHandler**: factory für die HTTP-Route
 //      `/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
+//      — not a sixth SubscriptionEventTypes value (fw#2791).
 //
 // **Was diese Foundation NICHT macht:**
 //   - Kein r.entity für `subscription`. Die Tabelle ist eine reine
@@ -43,12 +47,16 @@
 
 import { defineFeature, EXT_TENANT_DATA } from "@cosmicdrift/kumiko-framework/engine";
 import { BILLING_FOUNDATION_FEATURE, SUBSCRIPTION_PROVIDER_EXTENSION } from "./constants";
-import { subscriptionEntity } from "./entities";
+import { paymentEntity, subscriptionEntity } from "./entities";
 import {
   INVOICE_PAID_EVENT_QN,
   INVOICE_PAID_EVENT_SHORT,
   INVOICE_PAYMENT_FAILED_EVENT_QN,
   INVOICE_PAYMENT_FAILED_EVENT_SHORT,
+  PAYMENT_AGGREGATE_TYPE,
+  PAYMENT_RECEIVED_EVENT_QN,
+  PAYMENT_RECEIVED_EVENT_SHORT,
+  paymentEventPayloadSchema,
   SUBSCRIPTION_AGGREGATE_TYPE,
   SUBSCRIPTION_CANCELED_EVENT_QN,
   SUBSCRIPTION_CANCELED_EVENT_SHORT,
@@ -62,19 +70,22 @@ import { createCheckoutSessionHandler } from "./handlers/create-checkout-session
 import { createPortalSessionHandler } from "./handlers/create-portal-session.write";
 import { listSubscriptionsQuery } from "./handlers/list-subscriptions.query";
 import { processEventHandler } from "./handlers/process-event.write";
+import { processPaymentEventHandler } from "./handlers/process-payment-event.write";
 import {
   applyInvoicePaid,
   applyInvoicePaymentFailed,
+  applyPaymentReceived,
   applySubscriptionCanceled,
   applySubscriptionCreated,
   applySubscriptionUpdated,
+  paymentsProjectionTable,
   subscriptionsProjectionTable,
 } from "./projection";
-import { subscriptionTenantDestroyHook } from "./tenant-destroy-hook";
+import { paymentTenantDestroyHook, subscriptionTenantDestroyHook } from "./tenant-destroy-hook";
 
 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 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 `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.",
   );
   r.uiHints({
     displayLabel: "Billing \u00b7 Foundation",
@@ -100,6 +111,10 @@ export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE
   r.defineEvent(INVOICE_PAYMENT_FAILED_EVENT_SHORT, subscriptionEventPayloadSchema, {
     piiFields: "none",
   });
+  // Own event, own aggregate-type — a one-off-payment is not a subscription
+  // state transition. piiFields: "none" for the same reason as the 5 above:
+  // providerCustomerId is tenantOwned ciphertext, not plaintext personal data.
+  r.defineEvent(PAYMENT_RECEIVED_EVENT_SHORT, paymentEventPayloadSchema, { piiFields: "none" });
 
   // Inline projection: materialized current state in `read_subscriptions`.
   // Apply läuft in derselben TX wie ctx.unsafeAppendEvent — read-your-
@@ -118,6 +133,17 @@ export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE
     },
   });
 
+  // Second inline projection: `read_payments`, one row per one-off-payment.
+  r.projection({
+    name: "payment",
+    source: PAYMENT_AGGREGATE_TYPE,
+    table: paymentsProjectionTable,
+    entity: paymentEntity,
+    apply: {
+      [PAYMENT_RECEIVED_EVENT_QN]: applyPaymentReceived,
+    },
+  });
+
   // Plugin extension-point. Provider-Plugins registrieren sich hier.
   r.extendsRegistrar(SUBSCRIPTION_PROVIDER_EXTENSION, {
     onRegister: () => {
@@ -133,6 +159,9 @@ export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE
   r.writeHandler(processEventHandler);
   r.writeHandler(createCheckoutSessionHandler);
   r.writeHandler(createPortalSessionHandler);
+  //   - process-payment-event: programmatic entry-point from the webhook-
+  //     handler for one-off-payments; appends onto the payment-aggregate
+  r.writeHandler(processPaymentEventHandler);
 
   // Custom list-query auf der subscription-projection (raw drizzle-
   // table; kein r.entity weil Schreiben via projection-apply läuft).
@@ -141,4 +170,7 @@ export const billingFoundationFeature = defineFeature(BILLING_FOUNDATION_FEATURE
   r.useExtension(EXT_TENANT_DATA, "subscription", {
     destroy: subscriptionTenantDestroyHook,
   });
+  r.useExtension(EXT_TENANT_DATA, "payment", {
+    destroy: paymentTenantDestroyHook,
+  });
 });