@cosmicdrift/kumiko-bundled-features 0.251.0 → 0.252.0

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

@@ -0,0 +1,117 @@
+// process-payment-event — programmatic write-handler that the webhook-
+// handler calls AFTER a plugin has verified a one-off-payment webhook and
+// normalized it into a PaymentEvent.
+//
+// **ES-Pattern (mirrors process-event.write.ts):**
+//   1. Idempotency-check: loads the payment-stream and scans for an
+//      already-seen `metadata.providerEventId`. A provider-replay with
+//      the same event-id → duplicate=true, no second append.
+//   2. ctx.unsafeAppendEvent — inline-projection materializes a new
+//      `read_payments`-row (INSERT-once, not UPSERT — every payment is
+//      its own fact, not a state-update).
+
+import {
+  configuredPiiSubjectKms,
+  encryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
+import type { WriteHandlerDef } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { paymentAggregateId } from "../aggregate-id";
+import { PAYMENT_PII_FIELDS, paymentEntity } from "../entities";
+import {
+  PAYMENT_AGGREGATE_TYPE,
+  PAYMENT_RECEIVED_EVENT_QN,
+  type PaymentEventHeaders,
+  type PaymentEventPayload,
+} from "../events";
+
+export const processPaymentEventSchema = z.object({
+  providerEventId: z.string().min(1).max(200),
+  providerName: z.string().min(1).max(50),
+  providerCustomerId: z.string().min(1).max(200),
+  priceId: z.string().min(1).max(200),
+  rawPayload: z.string().min(1),
+});
+type ProcessPaymentEventPayload = z.infer<typeof processPaymentEventSchema>;
+
+// SystemAdmin-only: this handler is called exclusively by the programmatic
+// webhook-handler (with an internal SystemUser), never directly by the
+// tenant-admin.
+export const processPaymentEventHandler: WriteHandlerDef = {
+  name: "process-payment-event",
+  agent: { expose: false },
+  schema: processPaymentEventSchema,
+  access: { roles: ["SystemAdmin"] },
+  handler: async (event, ctx) => {
+    // @cast-boundary engine-payload — dispatcher-zod-validated payload
+    const payload = event.payload as ProcessPaymentEventPayload;
+    const tenantId = event.user.tenantId;
+    const aggId = paymentAggregateId(tenantId);
+
+    // ---------------------------------------------------------------
+    // 1. Idempotency: same scan pattern as process-event.write.ts — see
+    //    that file's comment for the O(N)-per-stream performance caveat
+    //    (a tenant with hundreds of purchases scans hundreds of events;
+    //    optimize via a per-tenant providerEventId-index if that bites).
+    // ---------------------------------------------------------------
+    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, paymentAggregateId: aggId },
+      };
+    }
+
+    // ---------------------------------------------------------------
+    // 2. Encrypt the provider-subject PII field before it touches storage
+    //    — same rationale as process-event.write.ts's step 3.
+    // ---------------------------------------------------------------
+    const piiKms = configuredPiiSubjectKms();
+    const encryptedFields = piiKms
+      ? await encryptPiiFieldValues(
+          { tenantId, providerCustomerId: payload.providerCustomerId },
+          paymentEntity,
+          PAYMENT_PII_FIELDS,
+          piiKms,
+          {
+            requestId: `billing-foundation:process-payment-event:${payload.providerEventId}`,
+            tenantId,
+          },
+        )
+      : { providerCustomerId: payload.providerCustomerId };
+
+    // ---------------------------------------------------------------
+    // 3. Append event on the payment-stream. Inline-projection
+    //    materializes a new read_payments-row in the same TX.
+    // ---------------------------------------------------------------
+    const eventPayload: PaymentEventPayload = {
+      providerName: payload.providerName,
+      providerCustomerId: encryptedFields["providerCustomerId"] as string,
+      priceId: payload.priceId,
+    };
+    const headers: PaymentEventHeaders = {
+      providerEventId: payload.providerEventId,
+      providerName: payload.providerName,
+      rawPayload: payload.rawPayload,
+    };
+    await ctx.unsafeAppendEvent({
+      aggregateId: aggId,
+      aggregateType: PAYMENT_AGGREGATE_TYPE,
+      type: PAYMENT_RECEIVED_EVENT_QN,
+      payload: eventPayload,
+      headers,
+    });
+
+    return {
+      isSuccess: true as const,
+      data: { duplicate: false as const, paymentAggregateId: aggId },
+    };
+  },
+};

package/src/billing-foundation/index.ts

@@ -1,8 +1,10 @@
 // Public API of the subscription-foundation bundled-feature.
 
-export { subscriptionAggregateId } from "./aggregate-id";
+export { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id";
 export {
   BILLING_FOUNDATION_FEATURE,
+  type BillingEventKind,
+  BillingEventKinds,
   SUBSCRIPTION_PROVIDER_EXTENSION,
   type SubscriptionEventType,
   SubscriptionEventTypes,
@@ -11,12 +13,18 @@ export {
   type SubscriptionStatus,
   SubscriptionStatuses,
 } from "./constants";
-export { subscriptionEntity } from "./entities";
+export { paymentEntity, subscriptionEntity } from "./entities";
 export {
   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,
+  type PaymentEventHeaders,
+  type PaymentEventPayload,
+  paymentEventPayloadSchema,
   SUBSCRIPTION_AGGREGATE_TYPE,
   SUBSCRIPTION_CANCELED_EVENT_QN,
   SUBSCRIPTION_CANCELED_EVENT_SHORT,
@@ -30,7 +38,7 @@ export {
 } from "./events";
 export { billingFoundationFeature } from "./feature";
 export { getSubscriptionForTenant, type SubscriptionView } from "./get-subscription-for-tenant";
-export { subscriptionsProjectionTable } from "./projection";
+export { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection";
 export {
   createSubscriptionTierSync,
   effectiveTierFromSubscription,
@@ -39,6 +47,7 @@ export {
   type SystemWriteResult,
 } from "./subscription-tier-sync";
 export type {
+  PaymentEvent,
   SubscriptionEvent,
   SubscriptionProviderPlugin,
 } from "./types";

package/src/billing-foundation/projection.ts

@@ -16,15 +16,22 @@
 
 import { buildEntityTable } from "@cosmicdrift/kumiko-framework/db";
 import { defineApply } from "@cosmicdrift/kumiko-framework/engine";
+import { paymentRowId } from "./aggregate-id";
+import { insertPaymentProjectionRow } from "./db/queries/payment-projection";
 import { upsertSubscriptionProjectionRow } from "./db/queries/subscription-projection";
-import { subscriptionEntity } from "./entities";
-import type { SubscriptionEventPayload } from "./events";
+import { paymentEntity, subscriptionEntity } from "./entities";
+import type { PaymentEventPayload, 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 = buildEntityTable("subscription", subscriptionEntity);
 
+// Same production-deployment caveat as subscriptionsProjectionTable above:
+// raw drizzle-pgTable, not an r.entity — apps mounting billing-foundation in
+// production must add read_payments to their own drizzle/generate.ts too.
+export const paymentsProjectionTable = buildEntityTable("payment", paymentEntity);
+
 // =============================================================================
 // Shared helpers
 // =============================================================================
@@ -152,3 +159,34 @@ export const applyInvoicePaymentFailed = defineApply<SubscriptionEventPayload>(
     await upsert(tx, event, { status: p.status, tier: p.tier }, p);
   },
 );
+
+// =============================================================================
+// payment-received apply — one row per event, no UPSERT
+// =============================================================================
+
+/** payment-received → INSERT-once row keyed by a deterministic uuid derived
+ *  from (tenantId, providerName, providerEventId) — NOT `event.id`, which is
+ *  the event-store's global bigserial sequence (not a UUID, can't back this
+ *  uuid-typed PK) — and not aggregateId, which is shared by every payment on
+ *  the same tenant's payment-stream. tenantId is part of the key because the
+ *  idempotency scan is per-tenant: without it, two tenants sharing the same
+ *  providerEventId would collide on ON CONFLICT DO NOTHING and silently lose
+ *  the second tenant's row. ON CONFLICT DO NOTHING also makes a projection
+ *  rebuild idempotent without mutating an existing row. */
+export const applyPaymentReceived = defineApply<PaymentEventPayload>(async (event, tx) => {
+  const tableName = (paymentsProjectionTable as { tableName: string }).tableName;
+  const providerEventId = event.metadata.headers?.["providerEventId"];
+  const providerName = event.metadata.headers?.["providerName"];
+  if (typeof providerEventId !== "string" || typeof providerName !== "string") {
+    throw new Error(
+      "applyPaymentReceived: event.metadata.headers is missing providerEventId/providerName — process-payment-event.write.ts always sets both",
+    );
+  }
+  await insertPaymentProjectionRow(tx, tableName, {
+    id: paymentRowId(event.tenantId, providerName, providerEventId),
+    tenant_id: event.tenantId,
+    provider_name: event.payload.providerName,
+    provider_customer_id: event.payload.providerCustomerId,
+    price_id: event.payload.priceId,
+  });
+});

package/src/billing-foundation/tenant-destroy-hook.ts

@@ -2,9 +2,9 @@ import { deleteMany, type EntityTableMeta, updateMany } from "@cosmicdrift/kumik
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { archiveStream } from "@cosmicdrift/kumiko-framework/event-store";
 import { resolveProfileForTenant } from "../compliance-profiles";
-import { subscriptionAggregateId } from "./aggregate-id";
-import { SUBSCRIPTION_AGGREGATE_TYPE } from "./events";
-import { subscriptionsProjectionTable } from "./projection";
+import { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id";
+import { PAYMENT_AGGREGATE_TYPE, SUBSCRIPTION_AGGREGATE_TYPE } from "./events";
+import { paymentsProjectionTable, subscriptionsProjectionTable } from "./projection";
 
 // providerCustomerId/providerSubscriptionId are `personal: "tenant"` on the
 // entity (envelope-encrypted with the tenant subject key, see entities.ts) —
@@ -44,3 +44,38 @@ export async function subscriptionTenantDestroyHook(ctx: {
     reason: "tenant_destroy",
   });
 }
+
+/** Tenant-destroy hook for payment PII (#800). Unlike subscriptionTenantDestroyHook
+ *  (one row per tenant, targeted by `id`), a tenant can have many payment
+ *  rows — the predicate here is `tenantId`, not `id`. The payment-stream
+ *  itself is still one stream per tenant (paymentAggregateId), so
+ *  archiveStream targets that single aggregateId as usual. */
+export async function paymentTenantDestroyHook(ctx: {
+  readonly db: import("@cosmicdrift/kumiko-framework/db").DbRunner;
+  readonly tenantId: TenantId;
+}): Promise<void> {
+  const { profile } = await resolveProfileForTenant({
+    db: ctx.db,
+    tenantId: ctx.tenantId,
+  });
+  const aggregateId = paymentAggregateId(ctx.tenantId);
+  if (profile.key === "de-hr-dsgvo-hgb") {
+    await updateMany(
+      ctx.db,
+      paymentsProjectionTable as EntityTableMeta,
+      { providerCustomerId: REDACTED_PII_VALUE },
+      { tenantId: ctx.tenantId },
+    );
+  } else {
+    await deleteMany(ctx.db, paymentsProjectionTable as EntityTableMeta, {
+      tenantId: ctx.tenantId,
+    });
+  }
+  await archiveStream(ctx.db, {
+    tenantId: ctx.tenantId,
+    aggregateId,
+    aggregateType: PAYMENT_AGGREGATE_TYPE,
+    archivedBy: "tenant-lifecycle:destroy",
+    reason: "tenant_destroy",
+  });
+}

package/src/billing-foundation/types.ts

@@ -26,7 +26,7 @@
 
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import type { SubscriptionEventType, SubscriptionStatus } from "./constants";
+import type { BillingEventKinds, SubscriptionEventType, SubscriptionStatus } from "./constants";
 
 // =============================================================================
 // Normalisierter Webhook-Event
@@ -37,6 +37,12 @@ import type { SubscriptionEventType, SubscriptionStatus } from "./constants";
 // Plugin abstrahiert.
 
 export type SubscriptionEvent = {
+  /** Discriminator against PaymentEvent. Optional (instead of required) so
+   *  existing plugins like subscription-mollie, which don't set this field,
+   *  stay backward-compatible without changes — TS still narrows
+   *  `parsed.kind === BillingEventKinds.payment` correctly, because only
+   *  PaymentEvent["kind"] can take that value. */
+  readonly kind?: typeof BillingEventKinds.subscription;
   /** Provider-eigene Event-ID — UNIQUE-key für Idempotency.
    *  Stripe: "evt_..."; Mollie: payment-id oder subscription-id. */
   readonly providerEventId: string;
@@ -68,6 +74,40 @@ export type SubscriptionEvent = {
   readonly rawPayload: string;
 };
 
+// =============================================================================
+// Normalized One-off-Payment-Event
+// =============================================================================
+//
+// Separate type instead of a sixth SubscriptionEventTypes value: a one-off-
+// payment is not a subscription-state transition (no status/tier/
+// currentPeriodEnd — a purchase either happened or it didn't) and
+// materializes into its own `read_payments`-row instead of overwriting the
+// subscription-row. Provider-plugins that don't support one-off-payments
+// (e.g. Mollie-recurring-only) never deliver this type — verifyAndParseWebhook
+// still returns just SubscriptionEvent | null for them, unchanged.
+
+export type PaymentEvent = {
+  /** Required — distinguishes this union member at runtime from
+   *  SubscriptionEvent (whose `kind` is optional and never "payment"). */
+  readonly kind: typeof BillingEventKinds.payment;
+  /** Provider's own event-ID — UNIQUE key for idempotency. */
+  readonly providerEventId: string;
+  /** Discriminator — which plugin delivered this event. */
+  readonly providerName: string;
+  /** Platform-tenant-ID. **Must** come from provider-verified metadata
+   *  (e.g. the PaymentIntent metadata the app itself set at checkout-
+   *  create time) — never from a freely-choosable payload field, or an
+   *  attacker could attribute payments to someone else's tenant. */
+  readonly tenantId: string;
+  /** Provider's own customer-id. */
+  readonly providerCustomerId: string;
+  /** Provider's own price/plan-ID of the purchased item. */
+  readonly priceId: string;
+  /** Raw provider-payload — archived 1:1 into payment-event.rawPayload.
+   *  Plugin delivers this as a JSON-stringified string. */
+  readonly rawPayload: string;
+};
+
 // =============================================================================
 // Plugin-Contract
 // =============================================================================
@@ -75,31 +115,37 @@ export type SubscriptionEvent = {
 export type SubscriptionProviderPlugin = {
   /**
    * Verify webhook signature + parse provider-event into normalized
-   * form. **Pre-tenant-resolution** — kein HandlerContext, weil zum
-   * Zeitpunkt des sig-verify der Tenant noch nicht aufgelöst ist
-   * (Plugin macht die Tenant-Resolution selbst aus dem provider-
-   * payload metadata).
+   * form. **Pre-tenant-resolution** — no HandlerContext, because at
+   * sig-verify time the tenant hasn't been resolved yet (the plugin
+   * does the tenant-resolution itself from the provider-payload
+   * metadata).
    *
-   * App-wide-secret = App-Owner's eigener Provider-Account. Der Plugin
-   * liest ihn entweder aus einem mount-time-Closure ODER — zur Laufzeit
-   * rotierbar — aus dem optionalen `systemSecrets`-Arg (system-scoped
-   * SecretsContext, vom webhook-handler durchgereicht). `systemSecrets`
-   * ist undefined, wenn der App-Owner keinen wired; Plugins müssen dann
-   * auf ihren Closure-Fallback zurückfallen.
+   * App-wide-secret = the App-Owner's own provider account. The plugin
+   * reads it either from a mount-time closure OR — rotatable at
+   * runtime — from the optional `systemSecrets` arg (system-scoped
+   * SecretsContext, passed through by the webhook-handler).
+   * `systemSecrets` is undefined when the App-Owner hasn't wired one;
+   * plugins then fall back to their closure fallback.
    *
-   * Returns null für events die der Plugin nicht versteht oder die
-   * foundation nicht braucht (= filter out, foundation returnt 200
+   * Returns null for events the plugin doesn't understand or that the
+   * foundation doesn't need (= filter out, foundation returns 200
    * "ignored").
    *
-   * **Throws** bei sig-mismatch — der webhook-handler mapped das auf
-   * 401 damit der Provider keine retries macht (sig-fail = config-bug,
-   * nicht transient).
+   * **Throws** on sig-mismatch — the webhook-handler maps that to 401
+   * so the provider doesn't retry (sig-fail = config-bug, not
+   * transient).
+   *
+   * Returns `PaymentEvent` for one-off-payment-webhooks (checkout mode
+   * "payment"). Plugins without one-off-payment support never deliver this
+   * union member — the return-type extension is covariant, so a
+   * `Promise<SubscriptionEvent | null>` implementor stays assignable
+   * without any change.
    */
   readonly verifyAndParseWebhook: (
     rawBody: string,
     headers: Record<string, string>,
     systemSecrets?: SecretsContext,
-  ) => Promise<SubscriptionEvent | null>;
+  ) => Promise<SubscriptionEvent | PaymentEvent | null>;
 
   /**
    * **Post-tenant-resolution** — wird aus dem

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

@@ -45,6 +45,7 @@ import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { Context, Hono } from "hono";
 import {
   BILLING_FOUNDATION_FEATURE,
+  BillingEventKinds,
   SUBSCRIPTION_PROVIDER_EXTENSION,
   SubscriptionFoundationHandlers,
 } from "./constants";
@@ -153,9 +154,31 @@ export function createSubscriptionWebhookHandler(deps: SubscriptionWebhookDeps)
       return c.json({ ignored: true }, 200);
     }
 
-    // 6. Dispatch process-event-handler durch den Standard-Dispatcher.
-    //    Idempotency macht der handler intern via deterministic
-    //    aggregate-id + UNIQUE-constraint.
+    // 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,
+        payload: {
+          providerEventId: parsed.providerEventId,
+          providerName: parsed.providerName,
+          providerCustomerId: parsed.providerCustomerId,
+          priceId: parsed.priceId,
+          rawPayload: parsed.rawPayload,
+        },
+      });
+      return respondFromDispatch(
+        c,
+        dispatched,
+        "subscription_payment_webhook_processing_failed",
+        "Internal error processing payment event",
+      );
+    }
+
     const dispatched = await deps.dispatchWrite({
       handlerQn: SubscriptionFoundationHandlers.processEvent,
       tenantId: parsed.tenantId,
@@ -171,26 +194,32 @@ export function createSubscriptionWebhookHandler(deps: SubscriptionWebhookDeps)
         rawPayload: parsed.rawPayload,
       },
     });
-
-    if (!dispatched.isSuccess) {
-      // Internal error — Provider soll retry'n. 500 statt 401/404 weil
-      // das transient ist (DB down etc.) nicht config-bug.
-      return c.json(
-        {
-          error: {
-            code: "subscription_webhook_processing_failed",
-            message: "Internal error processing subscription event",
-            details: dispatched.error,
-          },
-        },
-        500,
-      );
-    }
-
-    return c.json({ processed: true, ...((dispatched.data as object) ?? {}) }, 200); // @cast-boundary engine-bridge
+    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"]>>,
+  errorCode: string,
+  errorMessage: string,
+): Response {
+  if (!dispatched.isSuccess) {
+    return c.json(
+      { error: { code: errorCode, message: errorMessage, details: dispatched.error } },
+      500,
+    );
+  }
+  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.