@cosmicdrift/kumiko-bundled-features 0.377.0 → 0.379.0

package/dist/billing-foundation/handlers/process-event.write.js

@@ -12,12 +12,14 @@
 //   3. ctx.unsafeAppendEvent — Inline-projection materialisiert die
 //      `read_subscriptions`-row in derselben TX.
 import { configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.js";
-import { isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, SubscriptionEventTypes, SubscriptionStatuses, } from "../constants.js";
 import { SUBSCRIPTION_PII_FIELDS, subscriptionEntity } from "../entities.js";
 import { INVOICE_PAID_EVENT_QN, INVOICE_PAYMENT_FAILED_EVENT_QN, SUBSCRIPTION_AGGREGATE_TYPE, SUBSCRIPTION_CANCELED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_QN, SUBSCRIPTION_UPDATED_EVENT_QN, } from "../events.js";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
+import { BILLING_SUBSCRIPTION_LOCK_NAMESPACE, isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, SubscriptionEventTypes, SubscriptionStatuses, } from "../web/constants.js";
 // =============================================================================
 // Input-Schema = der normalisierte SubscriptionEvent (ohne tenantId, der
 // kommt aus event.user.tenantId — der webhook-handler setzt den
@@ -47,6 +49,7 @@ export const processEventSchema = z.object({
     tier: z.string().min(1).max(50),
     currentPeriodEndIso: z.string().min(1),
     cancelAtIso: z.string().min(1).nullable().optional(),
+    providerEventAtIso: z.iso.datetime().optional(),
     consentId: z.string().min(1).max(100).optional(),
 });
 // Map normalized SubscriptionEventType → fully-qualified ES event-name.
@@ -57,14 +60,55 @@ const NORMALIZED_TO_ES_EVENT = {
     [SubscriptionEventTypes.invoicePaid]: INVOICE_PAID_EVENT_QN,
     [SubscriptionEventTypes.invoicePaymentFailed]: INVOICE_PAYMENT_FAILED_EVENT_QN,
 };
+const STATE_EVENT_TYPES = new Set([
+    SubscriptionEventTypes.created,
+    SubscriptionEventTypes.updated,
+    SubscriptionEventTypes.canceled,
+]);
+function isLateStateEvent(storedEvents, payload) {
+    if (payload.providerEventAtIso === undefined || !STATE_EVENT_TYPES.has(payload.type)) {
+        return false;
+    }
+    const incoming = Temporal.Instant.from(payload.providerEventAtIso);
+    return storedEvents.some((stored) => {
+        const storedAt = propertyOf(stored.payload, "providerEventAtIso");
+        if (stored.metadata.headers?.["providerName"] !== payload.providerName)
+            return false;
+        if (typeof storedAt !== "string")
+            return false;
+        // A stored value that does not parse can never prove a newer event; skip it instead of
+        // failing every later delivery of this tenant's stream.
+        try {
+            return Temporal.Instant.compare(Temporal.Instant.from(storedAt), incoming) > 0;
+        }
+        catch {
+            return false;
+        }
+    });
+}
 // =============================================================================
 // appendSubscriptionEvent — the append-body, shared by processEventHandler
 // (webhook path) and sync-subscription.write.ts (backfill path). Both call
 // this with the same normalized payload shape; the difference is only in
 // who constructs `payload` and what `providerEventId` they use.
 // =============================================================================
-export async function appendSubscriptionEvent(ctx, tenantId, payload) {
+// A provider timestamp far in the future would make every later, genuine event look late.
+const PROVIDER_EVENT_CLOCK_SKEW_SECONDS = 300;
+export function clampProviderEventAt(payload, now) {
+    if (payload.providerEventAtIso === undefined)
+        return payload;
+    const ceiling = now.add({ seconds: PROVIDER_EVENT_CLOCK_SKEW_SECONDS });
+    return Temporal.Instant.compare(Temporal.Instant.from(payload.providerEventAtIso), ceiling) > 0
+        ? { ...payload, providerEventAtIso: ceiling.toString() }
+        : payload;
+}
+export async function appendSubscriptionEvent(ctx, tenantId, rawPayload, now = Temporal.Now.instant()) {
     const aggId = subscriptionAggregateId(tenantId);
+    const payload = clampProviderEventAt(rawPayload, now);
+    // Serialises the read (idempotency + late check) with the append: the append re-reads the
+    // stream version itself, so without the lock a concurrent delivery could slip in between and
+    // the late check would have judged an outdated stream.
+    await ctx.db.advisoryXactLock(BILLING_SUBSCRIPTION_LOCK_NAMESPACE, aggId);
     // ---------------------------------------------------------------
     // 1. Idempotency: load the subscription stream and check whether this
     //    providerEventId was already seen. A provider retry storm (Stripe
@@ -85,6 +129,13 @@ export async function appendSubscriptionEvent(ctx, tenantId, payload) {
     if (alreadySeen) {
         return { duplicate: true, subscriptionAggregateId: aggId };
     }
+    // A state event the provider emitted before the newest one already stored is a
+    // late delivery: appending it would roll the row back (a canceled subscription
+    // would come back active). Invoice events carry the live state, not a snapshot.
+    if (isLateStateEvent(existingEvents, payload)) {
+        ctx.log?.warn(`[billing-foundation:process-event] dropped late ${payload.type} ${payload.providerEventId}: a newer provider event is already stored`);
+        return { duplicate: false, stale: true, subscriptionAggregateId: aggId };
+    }
     // ---------------------------------------------------------------
     // 2. Map normalized event-type → ES event-FQN.
     // ---------------------------------------------------------------
@@ -131,6 +182,9 @@ export async function appendSubscriptionEvent(ctx, tenantId, payload) {
         currentPeriodEndIso: payload.currentPeriodEndIso,
         ...(payload.cancelAtIso !== undefined && { cancelAtIso: payload.cancelAtIso }),
         ...(payload.consentId !== undefined && { consentId: payload.consentId }),
+        ...(payload.providerEventAtIso !== undefined && {
+            providerEventAtIso: payload.providerEventAtIso,
+        }),
     };
     const headers = {
         providerEventId: payload.providerEventId,
@@ -190,7 +244,7 @@ export function createProcessEventHandler(now) {
                     },
                 };
             }
-            const result = await appendSubscriptionEvent(ctx, event.user.tenantId, payload);
+            const result = await appendSubscriptionEvent(ctx, event.user.tenantId, payload, now());
             return { isSuccess: true, data: result };
         },
     };

package/dist/billing-foundation/handlers/switch-plan.write.js

@@ -5,9 +5,9 @@
 import { ConflictError, UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { assertBillingEnabled, assertRedirectOrigins, isNonEmptyStringArray, joinBaseUrl, resolveCatalogProvider, } from "../checkout-core.js";
-import { isSwitchableSubscriptionStatus } from "../constants.js";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
 import { purchaseRolesOf, resolvePlanPrices } from "../plan-catalog.js";
+import { isSwitchableSubscriptionStatus } from "../web/constants.js";
 export function createSwitchPlanHandler(options, catalog) {
     const plans = catalog.plans;
     if (!isNonEmptyStringArray(plans)) {

package/dist/billing-foundation/handlers/sync-subscription.write.js

@@ -17,8 +17,8 @@ import { SYSTEM_ROLE } from "@cosmicdrift/kumiko-framework/engine";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import { findProviderPlugin } from "../checkout-core.js";
-import { isTerminalSubscriptionStatus, SubscriptionEventTypes } from "../constants.js";
 import { getSubscriptionForTenant } from "../get-subscription-for-tenant.js";
+import { isTerminalSubscriptionStatus, SubscriptionEventTypes } from "../web/constants.js";
 import { appendSubscriptionEvent } from "./process-event.write.js";
 export const syncSubscriptionSchema = z.object({}).strict();
 // Parses both sides fresh via Temporal before comparing — tolerant of a

package/dist/billing-foundation/index.d.ts

@@ -1,9 +1,7 @@
 export { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.ts";
 export { type BillingInfo, type BillingInfoQueryDeps, createBillingInfoQueryConfig, } from "./billing-info-query.ts";
 export { isBillingEnabled, type ResolvedProvider, resolveProviderPlugin, } from "./checkout-core.ts";
-export { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID, type BillingEventKind, BillingEventKinds, type BillingPlanAction, BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSwitchableSubscriptionStatus, isTerminalSubscriptionStatus, parseProviderConsentId, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, SubscriptionCancelTimings, type SubscriptionEventType, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "./constants.ts";
 export { type ConsentPayload, consentPayloadSchema, type OrderItem, } from "./consumer-protection/consent-gate.ts";
-export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "./consumer-protection/consent-locale.ts";
 export { type ContractTerminationRoutesOptions, createContractTerminationRoutes, } from "./consumer-protection/termination-pages.ts";
 export { paymentEntity, subscriptionEntity } from "./entities.ts";
 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, SUBSCRIPTION_CREATED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_SHORT, SUBSCRIPTION_UPDATED_EVENT_QN, SUBSCRIPTION_UPDATED_EVENT_SHORT, type SubscriptionEventHeaders, type SubscriptionEventPayload, subscriptionEventPayloadSchema, } from "./events.ts";
@@ -13,4 +11,6 @@ export { paymentsProjectionTable, subscriptionsProjectionTable } from "./project
 export { billingPlansPanel, createBillingPlansScreen } from "./screens.ts";
 export { createSubscriptionTierSync, effectiveTierFromSubscription, SUBSCRIPTION_WEBHOOK_PATH, type SubscriptionTierSyncDeps, type TierSyncResult, } from "./subscription-tier-sync.ts";
 export { type BillingFoundationOptions, type BillingPlanBenefit, type BillingPlanCatalog, type BillingPlanContactCard, type BillingPlanPrice, type BillingPlansResult, type BillingPlanView, type ConsumerProtectionOptions, KNOWN_RECURRING_INTERVALS, type LegalLinkSet, type PaymentEvent, type ProviderPrice, type ProviderSubscriptionSnapshot, type RecurringInterval, type SubscriptionEvent, type SubscriptionProviderPlugin, } from "./types.ts";
+export { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID, type BillingEventKind, BillingEventKinds, type BillingPlanAction, BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSwitchableSubscriptionStatus, isTerminalSubscriptionStatus, parseProviderConsentId, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, SubscriptionCancelTimings, type SubscriptionEventType, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "./web/constants.ts";
+export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "./web/consumer-protection/consent-locale.ts";
 export { createSubscriptionWebhookRoute, type SubscriptionWebhookRouteOptions, } from "./webhook-handler.ts";

package/dist/billing-foundation/index.js

@@ -2,9 +2,7 @@
 export { paymentAggregateId, subscriptionAggregateId } from "./aggregate-id.js";
 export { createBillingInfoQueryConfig, } from "./billing-info-query.js";
 export { isBillingEnabled, resolveProviderPlugin, } from "./checkout-core.js";
-export { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID, BillingEventKinds, BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSwitchableSubscriptionStatus, isTerminalSubscriptionStatus, parseProviderConsentId, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionCancelTimings, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "./constants.js";
 export { consentPayloadSchema, } from "./consumer-protection/consent-gate.js";
-export { CONSENT_LOCALES, resolveConsentLocale, } from "./consumer-protection/consent-locale.js";
 export { createContractTerminationRoutes, } from "./consumer-protection/termination-pages.js";
 export { paymentEntity, subscriptionEntity } from "./entities.js";
 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, paymentEventPayloadSchema, SUBSCRIPTION_AGGREGATE_TYPE, SUBSCRIPTION_CANCELED_EVENT_QN, SUBSCRIPTION_CANCELED_EVENT_SHORT, SUBSCRIPTION_CREATED_EVENT_QN, SUBSCRIPTION_CREATED_EVENT_SHORT, SUBSCRIPTION_UPDATED_EVENT_QN, SUBSCRIPTION_UPDATED_EVENT_SHORT, subscriptionEventPayloadSchema, } from "./events.js";
@@ -14,4 +12,6 @@ export { paymentsProjectionTable, subscriptionsProjectionTable } from "./project
 export { billingPlansPanel, createBillingPlansScreen } from "./screens.js";
 export { createSubscriptionTierSync, effectiveTierFromSubscription, SUBSCRIPTION_WEBHOOK_PATH, } from "./subscription-tier-sync.js";
 export { KNOWN_RECURRING_INTERVALS, } from "./types.js";
+export { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID, BillingEventKinds, BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSwitchableSubscriptionStatus, isTerminalSubscriptionStatus, parseProviderConsentId, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionCancelTimings, SubscriptionEventTypes, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "./web/constants.js";
+export { CONSENT_LOCALES, resolveConsentLocale, } from "./web/consumer-protection/consent-locale.js";
 export { createSubscriptionWebhookRoute, } from "./webhook-handler.js";

package/dist/billing-foundation/plan-catalog.js

@@ -3,8 +3,8 @@
 // caller's current tier + subscription, and the action available per plan.
 // Internal — not re-exported from index.ts.
 import { isPluginBillingEnabled } from "./checkout-core.js";
-import { BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, SubscriptionStatuses, } from "./constants.js";
 import { getSubscriptionForTenant } from "./get-subscription-for-tenant.js";
+import { BillingPlanActions, DEFAULT_PURCHASE_ROLES, isSubscriptionBlockingCheckout, isSwitchableSubscriptionStatus, SubscriptionStatuses, } from "./web/constants.js";
 function userHasAnyRole(userRoles, allowedRoles) {
     return allowedRoles.some((role) => userRoles.includes(role));
 }

package/dist/billing-foundation/screens.js

@@ -1,4 +1,4 @@
-import { BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID } from "./constants.js";
+import { BILLING_PLANS_PANEL_COMPONENT, BILLING_PLANS_SCREEN_ID } from "./web/constants.js";
 /** The billing-plans panel, meant to be dropped into an app's own dashboard
  *  screen alongside its own panels — not just the dormant single-panel
  *  screen below. */

package/dist/billing-foundation/subscription-tier-sync.js

@@ -5,7 +5,7 @@
 import { isTierAssignmentSource, TierAssignmentSources, TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
 import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { subscriptionAggregateId } from "./aggregate-id.js";
-import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./constants.js";
+import { SubscriptionFoundationQueries, SubscriptionStatuses } from "./web/constants.js";
 import { createSubscriptionWebhookRoute } from "./webhook-handler.js";
 // Outside /api — signature routes carry their own auth (verify()) and are
 // not JWT-guarded, so provider dashboards (Stripe, PayPal, ...) point here.

package/dist/billing-foundation/types.d.ts

@@ -2,9 +2,9 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { HandlerContext, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus, type TerminationScope } from "./constants.ts";
 import type { OrderItem } from "./consumer-protection/consent-gate.ts";
-import type { ConsentLocale } from "./consumer-protection/consent-locale.ts";
+import { type BillingEventKinds, type BillingPlanAction, SUBSCRIPTION_PROVIDER_EXTENSION, type SubscriptionCancelTiming, type SubscriptionEventType, type SubscriptionStatus, type TerminationScope } from "./web/constants.ts";
+import type { ConsentLocale } from "./web/consumer-protection/consent-locale.ts";
 export type SubscriptionEvent = {
     /** Discriminator against PaymentEvent. Optional (instead of required) so
      *  existing plugins like subscription-mollie, which don't set this field,
@@ -46,6 +46,10 @@ export type SubscriptionEvent = {
      *  Mollie), so projection.ts leaves the column unchanged instead of
      *  nulling it. */
     readonly cancelAt?: string | null;
+    /** ISO instant the provider emitted this event. process-event drops a
+     *  state event older than the newest one already stored, since providers
+     *  do not guarantee delivery order. Omitted by providers that report none. */
+    readonly providerEventAt?: string;
 };
 export type PaymentEvent = {
     /** Required — distinguishes this union member at runtime from
@@ -171,6 +175,14 @@ export type SubscriptionProviderPlugin = {
         readonly providerSubscriptionId: string;
         readonly when: SubscriptionCancelTiming;
     }) => Promise<void>;
+    /**
+     * Optional: takes back a `period-end` cancellation that has not taken effect
+     * yet. Without it, a revoked public termination is reported to the operator
+     * to undo by hand.
+     */
+    readonly resumeSubscription?: (ctx: HandlerContext, options: {
+        readonly providerSubscriptionId: string;
+    }) => Promise<void>;
     /**
      * The provider's own price/plan-id → app-tier-name mapping. This is the
      * one source `checkout-core`/`plan-catalog` derive both hardening

package/dist/billing-foundation/types.js

@@ -24,7 +24,7 @@
 // Foundation nutzt nur den common-subset der Provider-Funktionalität —
 // proration, multi-currency, coupons etc. bleiben provider-spezifisch
 // und sind über den Customer-Portal-Link erreichbar.
-import { SUBSCRIPTION_PROVIDER_EXTENSION, } from "./constants.js";
+import { SUBSCRIPTION_PROVIDER_EXTENSION, } from "./web/constants.js";
 // =============================================================================
 // Provider price + billing-plans catalog
 // =============================================================================

package/dist/billing-foundation/validate-options.js

@@ -3,10 +3,10 @@
 // concerns (app-feature-structure guard's 300-line budget). Internal — not
 // re-exported from index.ts.
 import * as z from "zod";
-import { isTerminationScope, TERMINATION_SCOPES } from "./constants.js";
-import { CONSENT_LOCALES } from "./consumer-protection/consent-locale.js";
-import { isContactCardHref } from "./contact-card.js";
 import { isLegalLinkSet, } from "./types.js";
+import { isTerminationScope, TERMINATION_SCOPES } from "./web/constants.js";
+import { CONSENT_LOCALES } from "./web/consumer-protection/consent-locale.js";
+import { isContactCardHref } from "./web/contact-card.js";
 function isRootRelativePath(path) {
     return path.startsWith("/") && !path.startsWith("//");
 }

package/dist/billing-foundation/web/billing-contact-plan.js

@@ -1,8 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-// @runtime client
 import { useLocale, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { PlanCard } from "@cosmicdrift/kumiko-renderer/web";
-import { isContactCardHref } from "../contact-card.js";
+import { isContactCardHref } from "./contact-card.js";
 import { localizedParams } from "./localized-params.js";
 export function BillingContactPlan({ contact, }) {
     const t = useTranslation();

package/dist/billing-foundation/web/billing-plans-panel.js

@@ -1,13 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// @runtime client
 import { useLocale, useMutation, usePrimitives, useQuery, useTranslation, } from "@cosmicdrift/kumiko-renderer";
 import { toInstant } from "@cosmicdrift/kumiko-renderer/headless";
 import { formatMoney, PlanCard, PlanGrid, } from "@cosmicdrift/kumiko-renderer/web";
 import { useState } from "react";
-import { BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "../constants.js";
 import { BillingContactPlan } from "./billing-contact-plan.js";
 import { CancelContractDialog } from "./cancel-contract-dialog.js";
 import { CheckoutConsentDialog } from "./checkout-consent-dialog.js";
+import { BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "./constants.js";
 import { localizedParams } from "./localized-params.js";
 function intervalKey(price) {
     if (price === null || price.interval === null)

package/dist/billing-foundation/web/cancel-contract-dialog.js

@@ -1,10 +1,9 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// @runtime client
 import { useLocale, useMutation, usePrimitives, useTranslation, } from "@cosmicdrift/kumiko-renderer";
 import { toInstant } from "@cosmicdrift/kumiko-renderer/headless";
 import { ModeSwitch } from "@cosmicdrift/kumiko-renderer/web";
 import { useState } from "react";
-import { SubscriptionFoundationHandlers } from "../constants.js";
+import { SubscriptionFoundationHandlers } from "./constants.js";
 const DECLARATION_TYPES = [
     "termination",
     "withdrawal",

package/dist/billing-foundation/web/checkout-consent-dialog.js

@@ -1,8 +1,7 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// @runtime client
 import { useLocale, usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
 import { useState } from "react";
-import { resolveConsentLocale } from "../consumer-protection/consent-locale.js";
+import { resolveConsentLocale } from "./consumer-protection/consent-locale.js";
 export const CONSENT_TEXT_OUTDATED_CODE = "consent_text_outdated";
 // kumiko-lint-ignore no-custom-primitives Uses usePrimitives().Modal internally, name is a billing domain action, not a primitive reimplementation
 export function CheckoutConsentDialog({ open, onOpenChange, planName, price, consumerProtection, onOrder, onConsentTextOutdated, }) {

package/dist/billing-foundation/web/client-plugin.js

@@ -1,5 +1,5 @@
-import { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT } from "../constants.js";
 import { BillingPlansPanel } from "./billing-plans-panel.js";
+import { BILLING_FOUNDATION_FEATURE, BILLING_PLANS_PANEL_COMPONENT } from "./constants.js";
 export function billingFoundationClient(options) {
     return {
         name: BILLING_FOUNDATION_FEATURE,

package/dist/billing-foundation/{constants.d.ts → web/constants.d.ts}

@@ -9,19 +9,18 @@ export declare const CONTRACT_CONFIRMATION_NOTIFICATION_TYPE: "billing-foundatio
 export declare const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE: "billing-foundation:notify:contract-termination-receipt";
 export declare const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE: "billing-foundation:notify:contract-termination-operator-notice";
 export declare const SubscriptionFoundationHandlers: {
-    /** Programmatic entry-point für den webhook-handler. Receives the
-     *  parsed SubscriptionEvent (vom Plugin schon verifiziert) + macht
-     *  insert-event + upsert-subscription + tier-sync atomic. */
+    /** Programmatic entry point for the webhook handler. Receives the
+     *  parsed SubscriptionEvent (already verified by the plugin) and does
+     *  insert-event + upsert-subscription + tier-sync atomically. */
     readonly processEvent: "billing-foundation:write:process-event";
-    /** Tenant-Admin klickt "Upgrade to Pro" → handler findet den
-     *  gewählten provider-plugin + ruft seine createCheckoutSession-
-     *  Methode + returnt die hosted-page-URL. Tenant-Admin wird dorthin
-     *  redirected, der subsequent provider-webhook erstellt die
-     *  subscription. */
+    /** Tenant admin clicks "Upgrade to Pro": the handler finds the chosen
+     *  provider plugin, calls its createCheckoutSession and returns the
+     *  hosted-page URL. The admin is redirected there; the subsequent
+     *  provider webhook creates the subscription. */
     readonly createCheckoutSession: "billing-foundation:write:create-checkout-session";
-    /** Tenant-Admin klickt "Manage Subscription" → handler findet
-     *  current subscription, ruft plugin.createPortalSession, returnt
-     *  hosted-portal-URL. */
+    /** Tenant admin clicks "Manage Subscription": the handler finds the
+     *  current subscription, calls plugin.createPortalSession and returns the
+     *  hosted-portal URL. */
     readonly 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
@@ -45,6 +44,12 @@ export declare const SubscriptionFoundationHandlers: {
     /** Anonymous § 312k cancellation/withdrawal declaration (consumerProtection
      *  only). */
     readonly requestContractTermination: "billing-foundation:write:request-contract-termination";
+    /** Anonymous "this was not me" revocation of a public declaration, by the
+     *  link of the receipt mail (consumerProtection only). */
+    readonly revokeContractTermination: "billing-foundation:write:revoke-contract-termination";
+    /** System-only: checks the revocation token against the tenant's declaration
+     *  and takes the cancellation back (consumerProtection only). */
+    readonly recordContractTerminationRevocation: "billing-foundation:write:record-contract-termination-revocation";
     /** Tenant-Admin terminates or withdraws from the contract of their own
      *  tenant (consumerProtection only). */
     readonly terminateContract: "billing-foundation:write:terminate-contract";
@@ -65,9 +70,9 @@ export declare const SubscriptionFoundationHandlers: {
     readonly syncSubscription: "billing-foundation:write:sync-subscription";
 };
 export declare const SubscriptionFoundationQueries: {
-    /** Sysadmin-cross-tenant + tenant-scoped self-list auf der
-     *  read_subscriptions-projection. Tenant-Admin sieht via ctx.db
-     *  tenant-scoping nur die eigene row. */
+    /** Sysadmin cross-tenant and tenant-scoped self-list on the
+     *  read_subscriptions projection. A tenant admin only sees their own row
+     *  because ctx.db is tenant-scoped. */
     readonly listSubscriptions: "billing-foundation:query:subscription:list";
     /** Lists the catalog's plans with live price, benefits, the caller's
      *  current tier and per-plan action. Only registered when a `catalog` is
@@ -135,3 +140,5 @@ export declare const DEFAULT_PURCHASE_ROLES: readonly ["TenantAdmin", "SystemAdm
 export declare const TERMINATION_SCOPES: readonly ["tenant-host", "platform"];
 export type TerminationScope = (typeof TERMINATION_SCOPES)[number];
 export declare function isTerminationScope(value: unknown): value is TerminationScope;
+/** Advisory-lock namespace serialising appends onto one tenant's subscription stream. */
+export declare const BILLING_SUBSCRIPTION_LOCK_NAMESPACE = 1651076204;

package/dist/billing-foundation/{constants.js → web/constants.js}

@@ -1,10 +1,9 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-// @runtime client
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 // Feature name
 export const BILLING_FOUNDATION_FEATURE = "billing-foundation";
-// Extension-point name fuer Provider-Plugins (subscription-stripe,
+// Extension-point name for provider plugins (subscription-stripe,
 // subscription-mollie, ...).
 export const SUBSCRIPTION_PROVIDER_EXTENSION = "subscriptionProvider";
 /** delivery notification type of the § 312f contract confirmation mail. */
@@ -15,19 +14,18 @@ export const CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE = "billing-foundatio
 export const CONTRACT_TERMINATION_OPERATOR_NOTIFICATION_TYPE = "billing-foundation:notify:contract-termination-operator-notice";
 // Qualified write handler names (QN format: scope:type:name).
 export const SubscriptionFoundationHandlers = {
-    /** Programmatic entry-point für den webhook-handler. Receives the
-     *  parsed SubscriptionEvent (vom Plugin schon verifiziert) + macht
-     *  insert-event + upsert-subscription + tier-sync atomic. */
+    /** Programmatic entry point for the webhook handler. Receives the
+     *  parsed SubscriptionEvent (already verified by the plugin) and does
+     *  insert-event + upsert-subscription + tier-sync atomically. */
     processEvent: "billing-foundation:write:process-event",
-    /** Tenant-Admin klickt "Upgrade to Pro" → handler findet den
-     *  gewählten provider-plugin + ruft seine createCheckoutSession-
-     *  Methode + returnt die hosted-page-URL. Tenant-Admin wird dorthin
-     *  redirected, der subsequent provider-webhook erstellt die
-     *  subscription. */
+    /** Tenant admin clicks "Upgrade to Pro": the handler finds the chosen
+     *  provider plugin, calls its createCheckoutSession and returns the
+     *  hosted-page URL. The admin is redirected there; the subsequent
+     *  provider webhook creates the subscription. */
     createCheckoutSession: "billing-foundation:write:create-checkout-session",
-    /** Tenant-Admin klickt "Manage Subscription" → handler findet
-     *  current subscription, ruft plugin.createPortalSession, returnt
-     *  hosted-portal-URL. */
+    /** Tenant admin clicks "Manage Subscription": the handler finds the
+     *  current subscription, calls plugin.createPortalSession and returns the
+     *  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
@@ -51,6 +49,12 @@ export const SubscriptionFoundationHandlers = {
     /** Anonymous § 312k cancellation/withdrawal declaration (consumerProtection
      *  only). */
     requestContractTermination: "billing-foundation:write:request-contract-termination",
+    /** Anonymous "this was not me" revocation of a public declaration, by the
+     *  link of the receipt mail (consumerProtection only). */
+    revokeContractTermination: "billing-foundation:write:revoke-contract-termination",
+    /** System-only: checks the revocation token against the tenant's declaration
+     *  and takes the cancellation back (consumerProtection only). */
+    recordContractTerminationRevocation: "billing-foundation:write:record-contract-termination-revocation",
     /** Tenant-Admin terminates or withdraws from the contract of their own
      *  tenant (consumerProtection only). */
     terminateContract: "billing-foundation:write:terminate-contract",
@@ -72,9 +76,9 @@ export const SubscriptionFoundationHandlers = {
 };
 // Qualified query handler names.
 export const SubscriptionFoundationQueries = {
-    /** Sysadmin-cross-tenant + tenant-scoped self-list auf der
-     *  read_subscriptions-projection. Tenant-Admin sieht via ctx.db
-     *  tenant-scoping nur die eigene row. */
+    /** Sysadmin cross-tenant and tenant-scoped self-list on the
+     *  read_subscriptions projection. A tenant admin only sees their own row
+     *  because ctx.db is tenant-scoped. */
     listSubscriptions: "billing-foundation:query:subscription:list",
     /** Lists the catalog's plans with live price, benefits, the caller's
      *  current tier and per-plan action. Only registered when a `catalog` is
@@ -85,9 +89,9 @@ export const SubscriptionFoundationQueries = {
     terminableSubscription: "billing-foundation:query:terminable-subscription",
 };
 // Normalized subscription-event types — provider-agnostic.
-// Alle Provider-Plugins normalisieren ihre eigenen event-types auf einen
-// dieser. Whitelist: was die Foundation kennt; alles andere muss der
-// Plugin filtern und null returnen aus verifyAndParseWebhook.
+// All provider plugins normalize their own event types onto one of these.
+// Whitelist of what the foundation knows; anything else must be filtered by
+// the plugin, which returns null from verifyAndParseWebhook.
 export const SubscriptionEventTypes = {
     created: "subscription.created",
     updated: "subscription.updated",
@@ -96,8 +100,8 @@ export const SubscriptionEventTypes = {
     invoicePaymentFailed: "invoice.payment-failed",
 };
 // Normalized subscription-status values — provider-agnostic.
-// Stripe + Mollie haben verschiedene Status-Sets; Plugin mapped auf
-// diesen common-subset.
+// Stripe and Mollie have different status sets; the plugin maps onto this
+// common subset.
 export const SubscriptionStatuses = {
     active: "active",
     trialing: "trialing",
@@ -183,18 +187,18 @@ export function isSwitchableSubscriptionStatus(status) {
 // override `purchaseRoles` — matches create-checkout-session's existing
 // TenantAdmin/SystemAdmin-only access.
 export const DEFAULT_PURCHASE_ROLES = ["TenantAdmin", "SystemAdmin"];
-// **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/
-// Apple-Pay/Klarna/SEPA (Disney+-Pattern). Welcher Provider die
-// aktuelle subscription des Tenants gerade hält steht in
-// subscription.providerName, kommt aus dem checkout-flow.
+// **Multi-provider from day one:** subscription-foundation has NO `provider`
+// config key. All mounted plugins are active in parallel; the end customer
+// picks between card/PayPal/Apple Pay/Klarna/SEPA at subscribe time
+// (Disney+ pattern). Which provider currently holds the tenant's
+// subscription is stored in subscription.providerName, set by the checkout flow.
 //
-// price-to-tier-Map ist KEIN foundation-config — pro-Plugin, weil
-// Stripe-priceIds vs PayPal-plan-ids vs Apple-product-ids
-// unterschiedliche IDs sind. Jeder Plugin definiert seinen eigenen
-// `<plugin-name>:config:price-to-tier`-Key.
+// The price-to-tier map is NOT foundation config: it is per plugin, because
+// Stripe priceIds, PayPal plan ids and Apple product ids are different IDs.
+// Each plugin defines its own `<plugin-name>:config:price-to-tier` key.
 export const TERMINATION_SCOPES = ["tenant-host", "platform"];
 export function isTerminationScope(value) {
     return isOneOf(TERMINATION_SCOPES, value);
 }
+/** Advisory-lock namespace serialising appends onto one tenant's subscription stream. */
+export const BILLING_SUBSCRIPTION_LOCK_NAMESPACE = 0x62_69_6c_6c; // 'bill'

package/dist/billing-foundation/{consumer-protection → web/consumer-protection}/consent-locale.js

@@ -1,4 +1,3 @@
-// @runtime client
 // Crypto-free so the browser panel can share the locale rule with the server.
 export const CONSENT_LOCALES = ["de", "en"];
 export const FALLBACK_CONSENT_LOCALE = "en";

package/dist/billing-foundation/{contact-card.js → web/contact-card.js}

@@ -1,4 +1,3 @@
-// @runtime client
 /** Shared by boot validation and the panel (defense in depth); keep free of server imports. */
 export function isContactCardHref(href) {
     if (href !== href.trim())

package/dist/billing-foundation/web/index.d.ts

@@ -1,6 +1,6 @@
-export { BILLING_PLANS_SCREEN_ID, type BillingPlanAction, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "../constants.ts";
-export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "../consumer-protection/consent-locale.ts";
 export type { BillingPlanBenefit, BillingPlanCatalog, BillingPlansResult, BillingPlanView, LegalLinkSet, } from "../types.ts";
 export { BillingPlansPanel } from "./billing-plans-panel.tsx";
 export { CheckoutConsentDialog, type CheckoutConsentDialogProps, type CheckoutConsentPayload, CONSENT_TEXT_OUTDATED_CODE, } from "./checkout-consent-dialog.tsx";
 export { type BillingFoundationClientOptions, billingFoundationClient } from "./client-plugin.tsx";
+export { BILLING_PLANS_SCREEN_ID, type BillingPlanAction, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, type SubscriptionStatus, SubscriptionStatuses, } from "./constants.ts";
+export { CONSENT_LOCALES, type ConsentLocale, resolveConsentLocale, } from "./consumer-protection/consent-locale.ts";

package/dist/billing-foundation/web/index.js

@@ -1,10 +1,9 @@
-// @runtime client
 // Public exports for the browser side of the billing-foundation feature.
 // Consumed via `@cosmicdrift/kumiko-bundled-features/billing-foundation/web` —
 // the server side (createBillingFoundationFeature) lives under
 // `@cosmicdrift/kumiko-bundled-features/billing-foundation` and has no React deps.
-export { BILLING_PLANS_SCREEN_ID, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "../constants.js";
-export { CONSENT_LOCALES, resolveConsentLocale, } from "../consumer-protection/consent-locale.js";
 export { BillingPlansPanel } from "./billing-plans-panel.js";
 export { CheckoutConsentDialog, CONSENT_TEXT_OUTDATED_CODE, } from "./checkout-consent-dialog.js";
 export { billingFoundationClient } from "./client-plugin.js";
+export { BILLING_PLANS_SCREEN_ID, BillingPlanActions, SubscriptionFoundationHandlers, SubscriptionFoundationQueries, SubscriptionStatuses, } from "./constants.js";
+export { CONSENT_LOCALES, resolveConsentLocale, } from "./consumer-protection/consent-locale.js";

package/dist/billing-foundation/web/localized-params.js

@@ -1,4 +1,3 @@
-// @runtime client
 export function localizedParams(params, locale) {
     if (params === undefined)
         return undefined;

package/dist/billing-foundation/webhook-handler.js

@@ -4,7 +4,7 @@
 // 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 { ExtraRouteRejection, signatureRoute } from "@cosmicdrift/kumiko-framework/api";
-import { BILLING_FOUNDATION_FEATURE, BillingEventKinds, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionFoundationHandlers, } from "./constants.js";
+import { BILLING_FOUNDATION_FEATURE, BillingEventKinds, SUBSCRIPTION_PROVIDER_EXTENSION, SubscriptionFoundationHandlers, } from "./web/constants.js";
 const DEFAULT_WEBHOOK_PATH = "/api/subscription/webhook/:providerName";
 function resolveProvider(registry, providerName) {
     return registry
@@ -84,6 +84,9 @@ export function createSubscriptionWebhookRoute(options = {}) {
                     tier: parsed.tier,
                     currentPeriodEndIso: parsed.currentPeriodEnd,
                     ...(parsed.cancelAt !== undefined && { cancelAtIso: parsed.cancelAt }),
+                    ...(parsed.providerEventAt !== undefined && {
+                        providerEventAtIso: parsed.providerEventAt,
+                    }),
                     ...(parsed.consentId !== undefined && { consentId: parsed.consentId }),
                 },
             });

package/dist/cap-counter/stock-cap-guard.js

@@ -4,8 +4,12 @@
 // tenant, so both are now factory parameters.
 import { UnprocessableError, writeFailure, } from "@cosmicdrift/kumiko-framework/errors";
 import { enforceStockCap } from "./enforce-cap.js";
+// pg_advisory_xact_lock namespace (int4): 'scap' as ASCII, disjoint from the
+// framework's other fixed advisory-lock keys.
+const STOCK_CAP_LOCK_NAMESPACE = 0x73636170;
 export function createStockCapGuard(resolveTierCaps) {
     async function checkStockCap(db, spec, context = {}) {
+        // Lock-free on its own: a direct call outside withStockCap is not atomic.
         const caps = await resolveTierCaps(db, context);
         const current = await db.count(spec.table, { ...spec.where, tenantId: db.tenantId });
         const { state, limit } = enforceStockCap({
@@ -24,6 +28,10 @@ export function createStockCapGuard(resolveTierCaps) {
         return {
             ...handler,
             handler: async (event, ctx) => {
+                // ctx.db is the handler's transaction, so the xact lock releases with its commit or
+                // rollback. A handler wrapped in several caps must list them in the same order
+                // everywhere; Postgres aborts one side of an inverse order with a deadlock error.
+                await ctx.db.advisoryXactLock(STOCK_CAP_LOCK_NAMESPACE, spec.code);
                 const failure = await checkStockCap(ctx.db, spec, { config: ctx.config });
                 return failure ?? handler.handler(event, ctx);
             },