@cosmicdrift/kumiko-bundled-features 0.363.0 → 0.365.0

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

@@ -14,7 +14,7 @@
 import { configuredPiiSubjectKms, encryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
 import * as z from "zod";
 import { subscriptionAggregateId } from "../aggregate-id.js";
-import { isSubscriptionBlockingCheckout, SubscriptionEventTypes, SubscriptionStatuses, } from "../constants.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";
@@ -154,16 +154,20 @@ export async function appendSubscriptionEvent(ctx, tenantId, payload) {
 // Tenant-Admin direkt.
 // One subscription aggregate exists per tenant, but a tenant can legitimately hold two provider
 // subscriptions over time (a stale `incomplete` one superseded by a fresh checkout). A late or
-// retried event of the old subscription must not overwrite the row of the live one, so only a
-// `created` event may replace a blocking row that belongs to a different provider subscription.
+// retried event of the old subscription must not overwrite the row of the live one, so an event of a
+// different provider subscription only replaces a row that no longer blocks a checkout. The exception
+// is a `created` of a subscription that is itself live (a provider switch); a late `created` of a
+// never-completed `incomplete` one stays stale, since delivery order is not guaranteed.
 function isStaleSubscriptionEvent(current, payload, now) {
     if (current === null)
         return false;
-    if (payload.type === SubscriptionEventTypes.created)
-        return false;
     const sameSubscription = current.providerName === payload.providerName &&
         current.providerSubscriptionId === payload.providerSubscriptionId;
-    return !sameSubscription && isSubscriptionBlockingCheckout(current, now);
+    if (sameSubscription || !isSubscriptionBlockingCheckout(current, now))
+        return false;
+    const supersedesCurrent = payload.type === SubscriptionEventTypes.created &&
+        isSwitchableSubscriptionStatus(payload.status);
+    return !supersedesCurrent;
 }
 export function createProcessEventHandler(now) {
     return {

package/dist/billing-foundation/i18n.js

@@ -1,4 +1,10 @@
 export const BILLING_FOUNDATION_I18N = {
+    "billing-foundation:feature.label": { en: "Billing" },
+    "billing-foundation:notify.contract-confirmation.label": { en: "Contract confirmation" },
+    "billing-foundation:notify.contract-termination-receipt.label": { en: "Termination receipt" },
+    "billing-foundation:notify.contract-termination-operator-notice.label": {
+        en: "Termination notice to operator",
+    },
     "screen:billing-plans.title": { en: "Billing" },
     "billing-foundation.plans.billingDisabled": {
         en: "Billing is not active yet. Your current plan stays in place.",
@@ -90,6 +96,9 @@ export const BILLING_FOUNDATION_I18N = {
     "billing-foundation.errors.redirectOriginNotAllowed": {
         en: "This redirect URL is not allowed for this app.",
     },
+    "billing-foundation.errors.providerCustomerUnknown": {
+        en: "The billing account for this subscription no longer exists. Subscribe again to continue.",
+    },
     "billing-foundation.errors.providerHasNoPriceCatalog": {
         en: "This provider has no known prices configured.",
     },

package/dist/billing-foundation/subscription-tier-sync.d.ts

@@ -1,11 +1,17 @@
-import type { ExtraRouteDefinition } from "@cosmicdrift/kumiko-framework/api";
+import type { ExtraRouteDefinition, SignatureExtraRouteDeps } from "@cosmicdrift/kumiko-framework/api";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
 export declare const SUBSCRIPTION_WEBHOOK_PATH = "/webhooks/subscription/:providerName";
 export type SubscriptionTierSyncDeps<TTier extends string> = {
     readonly isTierName: (value: string) => value is TTier;
     readonly defaultTier: TTier;
     readonly onSyncError?: "log" | "fail-webhook";
 };
+export declare const TIER_SYNC_MANUAL_GRANT_SKIPPED = "tier_sync_manual_grant_skipped";
 export declare function effectiveTierFromSubscription<TTier extends string>(status: string | undefined, tier: string | undefined, isTierName: (value: string) => value is TTier, defaultTier: TTier): TTier;
 export declare function createSubscriptionTierSync<TTier extends string>(deps: SubscriptionTierSyncDeps<TTier>): {
     createWebhookRoute: () => ExtraRouteDefinition;
+    syncTierFromSubscription: (tenantId: TenantId, routeDeps: Pick<SignatureExtraRouteDeps, "dispatchSystemQuery" | "dispatchSystemWrite">) => Promise<{
+        code: string;
+        message: string;
+    } | null>;
 };

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

@@ -2,7 +2,7 @@
 // near-identical webhook-route.ts app copies in show-pony and publicstatus
 // (infra#446) — the only per-app variables were the TierName union/default,
 // so it is now a factory parameter.
-import { TierAssignmentSources, TierEngineHandlers, TierEngineQueries, tierAssignmentAggregateId, } from "@cosmicdrift/kumiko-bundled-features/tier-engine";
+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";
@@ -10,6 +10,9 @@ 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.
 export const SUBSCRIPTION_WEBHOOK_PATH = "/webhooks/subscription/:providerName";
+// A manual grant that differs from what billing would assign is reported with this
+// code but never fails the webhook: a provider retry cannot resolve it.
+export const TIER_SYNC_MANUAL_GRANT_SKIPPED = "tier_sync_manual_grant_skipped";
 export function effectiveTierFromSubscription(status, tier, isTierName, defaultTier) {
     const usable = status === SubscriptionStatuses.active || status === SubscriptionStatuses.trialing;
     return usable && typeof tier === "string" && isTierName(tier) ? tier : defaultTier;
@@ -29,7 +32,13 @@ function findTierAssignment(rows, tenantId) {
     if (!row || typeof row["id"] !== "string" || typeof row["version"] !== "number") {
         return undefined;
     }
-    return { id: row["id"], version: row["version"], tier: row["tier"], source: row["source"] };
+    const source = row["source"];
+    return {
+        id: row["id"],
+        version: row["version"],
+        tier: row["tier"],
+        source: isTierAssignmentSource(source) ? source : null,
+    };
 }
 export function createSubscriptionTierSync(deps) {
     async function syncTierFromSubscription(tenantId, routeDeps) {
@@ -68,10 +77,14 @@ export function createSubscriptionTierSync(deps) {
                 }
                 return null;
             }
-            if (assignment.source === TierAssignmentSources.manual)
-                return null;
             if (assignment.tier === effective)
                 return null;
+            if (assignment.source === TierAssignmentSources.manual) {
+                return {
+                    code: TIER_SYNC_MANUAL_GRANT_SKIPPED,
+                    message: `manual tier grant "${String(assignment.tier)}" kept although the subscription yields "${effective}"`,
+                };
+            }
             const result = await routeDeps.dispatchSystemWrite({
                 handlerQn: TierEngineHandlers.update,
                 payload: {
@@ -108,8 +121,9 @@ export function createSubscriptionTierSync(deps) {
                 const syncError = await syncTierFromSubscription(tenantId, routeDeps);
                 if (syncError) {
                     // biome-ignore lint/suspicious/noConsole: operator visibility for a post-commit sync failure
-                    console.warn(`[subscription-tier-sync] tier sync failed for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`);
-                    if (deps.onSyncError === "fail-webhook") {
+                    console.warn(`[subscription-tier-sync] tier sync for tenant ${tenantId} after successful webhook write: ${syncError.code} ${syncError.message}`);
+                    if (deps.onSyncError === "fail-webhook" &&
+                        syncError.code !== TIER_SYNC_MANUAL_GRANT_SKIPPED) {
                         return {
                             isSuccess: false,
                             error: {
@@ -125,5 +139,5 @@ export function createSubscriptionTierSync(deps) {
             },
         });
     }
-    return { createWebhookRoute };
+    return { createWebhookRoute, syncTierFromSubscription };
 }

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

@@ -289,7 +289,10 @@ export type LegalLinkSet = {
 export declare function isLegalLinkSet(links: LegalLinkSet | Readonly<Record<ConsentLocale, LegalLinkSet>>): links is LegalLinkSet;
 /** Consumer-protection consent gate (§ 312j / § 356 BGB style). When set,
  *  `start-plan-checkout` and `create-checkout-session` require a `consent`
- *  payload and record it as an event before the buyer reaches the provider. */
+ *  payload and record it as an event before the buyer reaches the provider.
+ *  Every provider used with `create-checkout-session` must implement
+ *  `retrievePrices`: the live price is part of the consent record, and a
+ *  provider without it fails the checkout with an InternalError. */
 export type ConsumerProtectionOptions = {
     /** Slug of the template-resolver `text-block` holding the terms text; its
      *  content hash is stored with every recorded consent. */
@@ -304,7 +307,9 @@ export type ConsumerProtectionOptions = {
     readonly terminationScope?: TerminationScope;
     /** Names the item of a one-off payment (mode "payment") for the consent record
      *  and the confirmation mail; the label key is resolved through the registry
-     *  i18n, so it must be qualified with the registering feature. */
+     *  i18n, so it must be qualified with the registering feature. The label key
+     *  is 1-200 characters, string params at most 100; a violation fails the
+     *  checkout with an InternalError before the provider session is created. */
     readonly oneOffItemLabel?: (ctx: HandlerContext, priceId: string) => Promise<OrderItem | undefined>;
     /** Root-relative paths or absolute https URLs. One set for every locale, or
      *  one set per consent locale (`de` and `en` required). */

package/dist/cap-counter/book-cap-usage.js

@@ -173,6 +173,11 @@ export async function markCapSoftWarned(ctx, options) {
     }
     return retryCounterWriteOnVersionConflict(() => attemptMark(writeDb));
 }
+// A release is written up to a reservation TTL after its increment; once the increment left the
+// window the release must not subtract from other increments still inside it.
+function isBefore(isoInstant, cutoff) {
+    return Temporal.Instant.compare(Temporal.Instant.from(isoInstant), cutoff) < 0;
+}
 async function sumRollingEventAmounts(db, tenantId, options, type) {
     const aggregateId = rollingCapAggregateId(tenantId, options.capName);
     const cutoff = Temporal.Now.instant().subtract({ hours: options.windowDays * 24 });
@@ -189,6 +194,9 @@ async function sumRollingEventAmounts(db, tenantId, options, type) {
         // unknown by drizzle's $type<Record<string,unknown>>); narrowing the
         // shape here mirrors enforceRollingCap's own read-side contract.
         const payload = row["payload"];
+        if (typeof payload.incrementedAt === "string" && isBefore(payload.incrementedAt, cutoff)) {
+            continue;
+        }
         if (typeof payload.amount === "number") {
             total += payload.amount;
         }

package/dist/cap-counter/calendar-cap-usage-reservation.js

@@ -12,6 +12,8 @@ export async function reserveEnforcedCalendarCap(ctx, cap) {
             profile: cap.profile,
             notify: cap.notify,
             amount: cap.amount,
+            ...(cap.periodEndIso !== undefined && { periodEndIso: cap.periodEndIso }),
+            ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
             markSoftWarnedOutsideTransaction: outsideTransaction,
         });
     }

package/dist/cap-counter/cap-reservation.js

@@ -61,13 +61,13 @@ export async function reserveCalendarCap(ctx, options, outsideTransaction = true
         counterValue: valueBeforeBooking + options.amount,
     };
 }
-function rollingEvent(user, capName, amount, expectedVersion, type) {
+function rollingEvent(user, capName, amount, expectedVersion, type, extraPayload = {}) {
     return {
         aggregateId: rollingCapAggregateId(user.tenantId, capName),
         aggregateType: CAP_COUNTER_ROLLING_AGGREGATE_TYPE,
         expectedVersion,
         type,
-        payload: { capName, amount },
+        payload: { capName, amount, ...extraPayload },
         metadata: { userId: user.id },
     };
 }
@@ -104,7 +104,11 @@ async function giveBackCalendar(txDb, user, row) {
 }
 async function giveBackRolling(txDb, user, row) {
     const version = await getStreamVersionInTenantDb(txDb, rollingCapAggregateId(user.tenantId, row.capName));
-    await appendEventInTenantDb(txDb, rollingEvent(user, row.capName, row.amount, version, ROLLING_RELEASED_EVENT_QN));
+    await appendEventInTenantDb(txDb, 
+    // The window filter must use the increment's time: a sweep releases up to a TTL later.
+    rollingEvent(user, row.capName, row.amount, version, ROLLING_RELEASED_EVENT_QN, {
+        incrementedAt: row.createdAt.toString(),
+    }));
     return NOTHING_TO_RELEASE;
 }
 async function giveBackReservation(txDb, user, id) {

package/dist/cap-counter/enforce-cap.d.ts

@@ -57,6 +57,9 @@ export declare function assertBelowHardCap(valueSeenByLastUnit: number, cap: {
     readonly capName: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
+    readonly periodStartIso?: string;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
 }): void;
 /**
  * Synchronous read-and-check of the calling tenant's counter for
@@ -85,6 +88,8 @@ export declare function enforceCap(ctx: CapCounterContext, options: {
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
 }): Promise<EnforceCapResult>;
 /**
  * Synchronous read-and-check of the calling tenant's Rolling-Window-
@@ -120,6 +125,9 @@ export declare function enforceRollingCap(ctx: CapCounterContext, options: {
  * Thrown by enforceCap/enforceRollingCap when value ≥ hard-threshold.
  * Extends `KumikoError` — the dispatcher auto-maps this to HTTP 429
  * with `code: "cap_exceeded"`, no caller-side catch needed.
+ *
+ * Calendar caps carry `resetAt` (end of the period) and `retryAfterSeconds`, which the API
+ * answers as Retry-After. Rolling caps have no fixed reset instant, so both stay undefined.
  */
 export declare class CapExceededError extends KumikoError {
     readonly capName: string;
@@ -128,7 +136,13 @@ export declare class CapExceededError extends KumikoError {
     readonly tolerance: CapToleranceProfile;
     readonly code: "cap_exceeded";
     readonly httpStatus = 429;
-    constructor(capName: string, limit: number, currentValue: number, tolerance: CapToleranceProfile);
+    readonly resetAt: string | undefined;
+    constructor(capName: string, limit: number, currentValue: number, tolerance: CapToleranceProfile, options?: {
+        readonly resetAt?: string;
+        readonly i18nKey?: string;
+        readonly cause?: Error;
+        readonly now?: Temporal.Instant;
+    });
 }
 /**
  * Calendar-month period start in UTC. Use this for monthly caps
@@ -137,6 +151,7 @@ export declare class CapExceededError extends KumikoError {
  * Returns ISO string for the 1st of the current month at 00:00 UTC.
  */
 export declare function currentCalendarMonthStartIso(now?: Temporal.Instant): string;
+export declare function calendarMonthPeriodEndIso(periodStartIso: string): string;
 /**
  * Soft-hit-notifier callback. Caller liefert die Funktion die ein
  * delivery-event emittet (z.B. `delivery.send({to, template, payload})`).
@@ -169,6 +184,8 @@ export declare function enforceCapAndMaybeNotify(ctx: CapCounterContext, options
     readonly profile: CapToleranceProfileName;
     readonly notify: SoftHitNotifier;
     readonly amount?: number;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
     readonly markSoftWarnedOutsideTransaction?: boolean;
 }): Promise<EnforceCapResult>;
 /**

package/dist/cap-counter/enforce-cap.js

@@ -17,8 +17,24 @@ export const CAP_TOLERANCES = {
 export function assertBelowHardCap(valueSeenByLastUnit, cap) {
     const tolerance = CAP_TOLERANCES[cap.profile];
     if (valueSeenByLastUnit >= cap.limit * tolerance.hard) {
-        throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance);
+        const resetAt = resolvePeriodEndIso(cap.periodStartIso, cap.periodEndIso);
+        throw new CapExceededError(cap.capName, cap.limit, valueSeenByLastUnit, tolerance, {
+            ...(resetAt !== undefined && { resetAt }),
+            ...(cap.i18nKey !== undefined && { i18nKey: cap.i18nKey }),
+        });
+    }
+}
+function resolvePeriodEndIso(periodStartIso, periodEndIso) {
+    if (periodStartIso === undefined)
+        return periodEndIso;
+    if (periodEndIso === undefined)
+        return calendarMonthPeriodEndIso(periodStartIso);
+    const start = Temporal.Instant.from(periodStartIso);
+    const end = Temporal.Instant.from(periodEndIso);
+    if (Temporal.Instant.compare(end, start) <= 0) {
+        throw new Error(`cap-counter: periodEndIso (${periodEndIso}) must be after periodStartIso (${periodStartIso})`);
     }
+    return end.toString();
 }
 // =============================================================================
 // Enforce-Cap helper
@@ -115,6 +131,9 @@ export async function enforceRollingCap(ctx, options) {
  * Thrown by enforceCap/enforceRollingCap when value ≥ hard-threshold.
  * Extends `KumikoError` — the dispatcher auto-maps this to HTTP 429
  * with `code: "cap_exceeded"`, no caller-side catch needed.
+ *
+ * Calendar caps carry `resetAt` (end of the period) and `retryAfterSeconds`, which the API
+ * answers as Retry-After. Rolling caps have no fixed reset instant, so both stay undefined.
  */
 export class CapExceededError extends KumikoError {
     capName;
@@ -123,17 +142,32 @@ export class CapExceededError extends KumikoError {
     tolerance;
     code = "cap_exceeded";
     httpStatus = 429;
-    constructor(capName, limit, currentValue, tolerance) {
+    resetAt;
+    constructor(capName, limit, currentValue, tolerance, options) {
+        const resetAt = options?.resetAt;
+        const retryAfterSeconds = resetAt === undefined
+            ? undefined
+            : Math.max(0, Math.ceil(Temporal.Instant.from(resetAt).epochMilliseconds / 1000 -
+                (options?.now ?? Temporal.Now.instant()).epochMilliseconds / 1000));
         super({
-            message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.`,
-            i18nKey: "errors.cap.exceeded",
-            i18nParams: { capName, limit, currentValue },
-            details: { capName, limit, currentValue, tolerance },
+            message: `Cap "${capName}" exceeded: current=${currentValue}, limit=${limit}, hard-threshold=${limit * tolerance.hard}. Upgrade tier or wait for next period reset.${resetAt === undefined ? "" : ` Resets at ${resetAt}.`}`,
+            i18nKey: options?.i18nKey ?? "errors.cap.exceeded",
+            i18nParams: { capName, limit, currentValue, ...(resetAt !== undefined && { resetAt }) },
+            details: {
+                capName,
+                limit,
+                currentValue,
+                tolerance,
+                ...(resetAt !== undefined && { resetAt, retryAfterSeconds }),
+            },
+            ...(retryAfterSeconds !== undefined && { retryAfterSeconds }),
+            ...(options?.cause && { cause: options.cause }),
         });
         this.capName = capName;
         this.limit = limit;
         this.currentValue = currentValue;
         this.tolerance = tolerance;
+        this.resetAt = resetAt;
     }
 }
 // =============================================================================
@@ -158,6 +192,13 @@ export function currentCalendarMonthStartIso(now = Temporal.Now.instant()) {
     });
     return start.toInstant().toString();
 }
+export function calendarMonthPeriodEndIso(periodStartIso) {
+    return Temporal.Instant.from(periodStartIso)
+        .toZonedDateTimeISO("UTC")
+        .add({ months: 1 })
+        .toInstant()
+        .toString();
+}
 /**
  * Calendar-Period-enforcement + automatische soft-hit-Notification.
  * Ruft `enforceCap`, bei `crossed: true` den Notifier UND
@@ -175,6 +216,8 @@ export async function enforceCapAndMaybeNotify(ctx, options) {
         limit: options.limit,
         profile: options.profile,
         ...(options.amount !== undefined && { amount: options.amount }),
+        ...(options.periodEndIso !== undefined && { periodEndIso: options.periodEndIso }),
+        ...(options.i18nKey !== undefined && { i18nKey: options.i18nKey }),
     });
     if (result.state === "soft-hit" && result.crossed) {
         await options.notify({

package/dist/cap-counter/handlers/increment-rolling.write.d.ts

@@ -10,5 +10,6 @@ export declare const rollingIncrementedSchema: z.ZodObject<{
 export declare const rollingReleasedSchema: z.ZodObject<{
     capName: z.ZodString;
     amount: z.ZodNumber;
+    incrementedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const incrementRollingCapHandler: WriteHandlerDef;

package/dist/cap-counter/handlers/increment-rolling.write.js

@@ -34,6 +34,8 @@ export const rollingIncrementedSchema = incrementRollingSchema;
 /** Payload of the event that gives a reserved rolling amount back. */
 export const rollingReleasedSchema = incrementRollingSchema.extend({
     amount: z.number().int().positive(),
+    /** When the released increment was booked; absent on events written before it was recorded. */
+    incrementedAt: z.string().optional(),
 });
 // Rolling-Increment-Handler — append-only. Race-frei: zwei parallele
 // Increments für (tenant, cap) hängen sich am selben aggregate-stream

package/dist/cap-counter/index.d.ts

@@ -2,7 +2,7 @@ export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js"
 export { type BookCapUsageOptions, bookCapUsage, type MarkCapSoftWarnedOptions, markCapSoftWarned, type ReadRollingCapUsageOptions, readRollingCapUsage, } from "./book-cap-usage.js";
 export { type CalendarCapUsageReservation, type CalendarCapUsageReservationSpec, reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
 export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
-export { CAP_TOLERANCES, CapExceededError, type CapToleranceProfile, type CapToleranceProfileName, currentCalendarMonthStartIso, type EnforceCapResult, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, type SoftHitNotifier, type StockCapResult, } from "./enforce-cap.js";
+export { CAP_TOLERANCES, CapExceededError, type CapToleranceProfile, type CapToleranceProfileName, calendarMonthPeriodEndIso, currentCalendarMonthStartIso, type EnforceCapResult, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, type SoftHitNotifier, type StockCapResult, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
 export { readPayloadField } from "./payload-field.js";

package/dist/cap-counter/index.js

@@ -3,7 +3,7 @@ export { capCounterAggregateId, rollingCapAggregateId } from "./aggregate-id.js"
 export { bookCapUsage, markCapSoftWarned, readRollingCapUsage, } from "./book-cap-usage.js";
 export { reserveCalendarCapUsage, } from "./calendar-cap-usage-reservation.js";
 export { CAP_COUNTER_FEATURE, CAP_COUNTER_ROLLING_AGGREGATE_TYPE, CapCounterHandlers, CapCounterQueries, ROLLING_INCREMENTED_EVENT_QN, ROLLING_INCREMENTED_EVENT_SHORT, ROLLING_RELEASED_EVENT_QN, ROLLING_RELEASED_EVENT_SHORT, } from "./constants.js";
-export { CAP_TOLERANCES, CapExceededError, currentCalendarMonthStartIso, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, } from "./enforce-cap.js";
+export { CAP_TOLERANCES, CapExceededError, calendarMonthPeriodEndIso, currentCalendarMonthStartIso, enforceCap, enforceCapAndMaybeNotify, enforceRollingCap, enforceRollingCapAndMaybeNotify, enforceStockCap, } from "./enforce-cap.js";
 export { capCounterEntity } from "./entity.js";
 export { capCounterFeature } from "./feature.js";
 export { readPayloadField } from "./payload-field.js";

package/dist/cap-counter/with-cap-enforcement.d.ts

@@ -10,6 +10,8 @@ import { type CapToleranceProfileName, type SoftHitNotifier } from "./enforce-ca
 export type CalendarCapDef = {
     readonly capName: string;
     readonly periodStartIso: string;
+    readonly periodEndIso?: string;
+    readonly i18nKey?: string;
     readonly limit: number;
     readonly profile: CapToleranceProfileName;
     /** Increment-amount post-success. Default 1. */

package/dist/cap-overview/handlers/tenant-caps-list.query.js

@@ -116,7 +116,9 @@ export function createTenantCapsListQuery(caps, listCaps) {
                 });
             }
             const db = ctx.systemDb.acknowledgeCrossTenant("cap-overview:tenant-caps:list — SystemAdmin platform-wide tenant overview");
-            const tenants = await decryptTenantNames(await selectMany(db, tenantTable, {}), "cap-overview:tenant-caps:list");
+            const tenants = await decryptTenantNames(
+            // Destroyed tenants decrypt to the erased sentinel, which a picker or list would show verbatim.
+            await selectMany(db, tenantTable, { destroyedAt: null }), "cap-overview:tenant-caps:list");
             const assignments = await selectMany(db, tierAssignmentTable, {});
             const subscriptions = await selectMany(db, subscriptionsProjectionTable, {});
             const assignmentByTenant = new Map(assignments.map((row) => [row.tenantId, row]));

package/dist/cap-overview/handlers/tenant-options.query.js

@@ -15,7 +15,9 @@ export const tenantOptionsQuery = defineQueryHandler({
             });
         }
         const db = ctx.systemDb.acknowledgeCrossTenant("cap-overview:tenant-options — SystemAdmin dashboard tenant-filter options");
-        const tenants = await decryptTenantNames(await selectMany(db, tenantTable, {}), "cap-overview:tenant-options");
+        const tenants = await decryptTenantNames(
+        // Destroyed tenants decrypt to the erased sentinel, which the picker would show verbatim.
+        await selectMany(db, tenantTable, { destroyedAt: null }), "cap-overview:tenant-options");
         const sorted = [...tenants].sort((a, b) => a.name.localeCompare(b.name));
         return { rows: sorted.map((tenant) => ({ value: tenant.id, label: tenant.name })) };
     },

package/dist/channel-discord/discord-channel.js

@@ -1,7 +1,8 @@
 import { chatMessageText, createChatWebhookChannel, truncateChars, } from "../delivery/index.js";
+const DISCORD_WEBHOOK_PREFIX = "channel-discord:webhooks.";
 export const DISCORD_SECRET_KEYS = {
-    webhookPrefix: "channel-discord:webhooks.",
-    webhookKeyFor: (connection) => `channel-discord:webhooks.${connection}`,
+    webhookPrefix: DISCORD_WEBHOOK_PREFIX,
+    webhookKeyFor: (connection) => `${DISCORD_WEBHOOK_PREFIX}${connection}`,
 };
 export const DISCORD_DEFAULT_ALLOWED_HOSTS = ["discord.com", "discordapp.com"];
 export const DISCORD_WEBHOOK_PATH_PREFIX = "/api/webhooks/";

package/dist/channel-email/email-channel.js

@@ -1,7 +1,8 @@
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-framework/crypto";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
 import * as z from "zod";
 import { DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE, DELIVERY_UNSUBSCRIBE_PATH, EMAIL_CHANNEL_NAME, fileAttachmentRefSchema, MAX_EMAIL_ATTACHMENTS, renderedPdfAttachmentRefSchema, } from "../delivery/index.js";
-import { decryptStoredPii } from "../shared/index.js";
+import { decryptStoredPii, extensionForResourceContentType } from "../shared/index.js";
 import { guardEmailMessage } from "./pii-guard.js";
 // Envelope (From / Reply-To / threading headers) rides on the channel data —
 // the notification's email template echoes it out of the notify() call, since
@@ -22,7 +23,8 @@ const UNSUBSCRIBE_HEADER_NAMES = new Set([
     "list-unsubscribe",
     "list-unsubscribe-post",
 ]);
-// Only the framework's own unsubscribe route can honor a one-click POST.
+// Only the framework's own unsubscribe route can honor a one-click POST; an app's
+// own unsubscribe page still gets the plain List-Unsubscribe link (RFC 2369).
 function listUnsubscribeHeaders(data) {
     const rawUrl = data?.["unsubscribeUrl"];
     if (typeof rawUrl !== "string")
@@ -36,8 +38,9 @@ function listUnsubscribeHeaders(data) {
     }
     if (url.protocol !== "https:" && url.protocol !== "http:")
         return undefined;
-    if (url.pathname !== DELIVERY_UNSUBSCRIBE_PATH)
-        return undefined;
+    if (url.pathname !== DELIVERY_UNSUBSCRIBE_PATH) {
+        return { "List-Unsubscribe": `<${url.toString()}>` };
+    }
     return {
         "List-Unsubscribe": `<${url.toString()}>`,
         "List-Unsubscribe-Post": DELIVERY_UNSUBSCRIBE_ONE_CLICK_HEADER_VALUE,
@@ -81,15 +84,13 @@ export function fileAttachmentsFrom(data, messageLocale) {
         ? { ...ref, locale: messageLocale }
         : ref);
 }
-const INLINE_EXTENSION_BY_CONTENT_TYPE = {
-    "image/png": "png",
-    "image/jpeg": "jpg",
-    "image/gif": "gif",
-    "image/webp": "webp",
-};
+function inlineFileName(cid, contentType) {
+    const extension = extensionForResourceContentType(contentType);
+    return extension === undefined ? cid : `${cid}.${extension}`;
+}
 async function resolveAttachments(sources, ctx) {
     if (sources.length === 0)
-        return [];
+        return { kind: "resolved", attachments: [] };
     if (ctx.readAttachment === undefined) {
         throw new Error("email channel: the message has attachments but the channel context cannot read files");
     }
@@ -113,16 +114,12 @@ async function resolveAttachments(sources, ctx) {
             // A missing inline image only degrades the look; a missing file is content the recipient expects.
             if (ref.kind === "inline")
                 continue;
-            throw new Error(`email channel: attachment file ${ref.fileRefId} was not found`);
+            return { kind: "missing-file", fileRefId: ref.fileRefId };
         }
-        const fileName = ref.kind === "file"
-            ? ref.fileName
-            : INLINE_EXTENSION_BY_CONTENT_TYPE[found.contentType]
-                ? `${ref.cid}.${INLINE_EXTENSION_BY_CONTENT_TYPE[found.contentType]}`
-                : ref.cid;
+        const fileName = ref.kind === "file" ? ref.fileName : inlineFileName(ref.cid, found.contentType);
         resolved.push({ ...ref, fileName, content: found.content, contentType: found.contentType });
     }
-    return resolved;
+    return { kind: "resolved", attachments: resolved };
 }
 export function createEmailChannel(options) {
     const { transport, resolveEmail } = options;
@@ -138,13 +135,20 @@ export function createEmailChannel(options) {
             throw new Error(`email channel: notification "${notificationType}" has a mail template but the channel context carries no renderMail`);
         }
         const unsubscribeUrl = message.data?.["unsubscribeUrl"];
-        const { subject, html, text, attachments } = await ctx.renderMail({
+        const { subject, html, text, attachments, fromName, replyTo } = await ctx.renderMail({
             slug: notificationType,
             locale: message.locale ?? "en",
             variables: message.data ?? {},
             ...(typeof unsubscribeUrl === "string" && { unsubscribeUrl }),
         });
-        return { html, subject, text, ...(attachments !== undefined && { attachments }) };
+        return {
+            html,
+            subject,
+            text,
+            ...(fromName !== undefined && { fromName }),
+            ...(replyTo !== undefined && { replyTo }),
+            ...(attachments !== undefined && { attachments }),
+        };
     }
     return {
         name: EMAIL_CHANNEL_NAME,
@@ -161,12 +165,25 @@ export function createEmailChannel(options) {
             return renderMessage(message, ctx);
         },
         async send(address, message, ctx, rendered) {
-            const { html, subject, text, attachments } = rendered ?? (await renderMessage(message, ctx));
-            const envelope = emailEnvelopeFrom(message.data);
-            const resolvedAttachments = await resolveAttachments([
+            const { html, subject, text, attachments, fromName, replyTo } = rendered ?? (await renderMessage(message, ctx));
+            // Template-level sender defaults; notify data wins.
+            const envelope = {
+                ...(fromName && { fromName }),
+                ...(replyTo && { replyTo }),
+                ...emailEnvelopeFrom(message.data),
+            };
+            const resolution = await resolveAttachments([
                 ...(attachments ?? []).map((ref) => ({ ref, origin: "template" })),
                 ...fileAttachmentsFrom(message.data, message.locale).map((ref) => ({ ref, origin: "message" })),
             ], ctx);
+            if (resolution.kind === "missing-file") {
+                // A missing file is permanent, a retry cannot bring it back.
+                createFallbackLogger("delivery").warn("mail attachment file not found, send failed", {
+                    fileRefId: resolution.fileRefId,
+                });
+                return { status: "failed", error: "send_failed", address };
+            }
+            const resolvedAttachments = resolution.attachments;
             await transport.send(guardEmailMessage({
                 to: address,
                 subject,

package/dist/channel-email/smtp-transport.js

@@ -21,11 +21,16 @@ function isControlCharacter(char) {
     const code = char.charCodeAt(0);
     return code <= 0x1f || code === 0x7f;
 }
+// Mail clients often show only the display name: an embedded address ("<", ">", "@") would
+// pass for a foreign sender on the platform's own SPF/DKIM-signed domain.
+function isUnsafeDisplayNameCharacter(char) {
+    return isControlCharacter(char) || char === "<" || char === ">" || char === "@";
+}
 // Control characters in a display name would let a caller inject headers.
 function sanitizedDisplayName(name) {
     const cleaned = name
         ?.split("")
-        .map((char) => (isControlCharacter(char) ? " " : char))
+        .map((char) => (isUnsafeDisplayNameCharacter(char) ? " " : char))
         .join("")
         .trim();
     return cleaned === undefined || cleaned === "" ? undefined : cleaned;

package/dist/channel-in-app/handlers/mark-all-read.write.d.ts

@@ -1,4 +1,4 @@
 import * as z from "zod";
 export declare const markAllReadWrite: import("@cosmicdrift/kumiko-types/define-handler").WriteHandlerDefinition<"markAllRead", z.ZodObject<{}, z.core.$strip>, {
     marked: number;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;

package/dist/channel-in-app/handlers/mark-read.write.d.ts

@@ -3,4 +3,4 @@ export declare const markReadWrite: import("@cosmicdrift/kumiko-types/define-han
     id: z.ZodNumber;
 }, z.core.$strip>, {
     id: number | undefined;
-}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap>;
+}, import("@cosmicdrift/kumiko-types/event-type-map").KumikoEventTypeMap, undefined>;