@saasicat/nest 0.2.0

package/dist/aggregation-CJ3qQf92.d.cts

@@ -0,0 +1,288 @@
+import { PlanId, QuotaKey, FeatureKey, PlanCatalog, SubscriptionRepository, PlanVersionRepository, TransactionRunner, SubscriptionBundleRepository, BundleRepository, SubscriptionContractRepository, DiscoverySnapshot, SubscriptionRecord, TransactionContext, ContractLineItemRecord } from '@saasicat/types';
+import { E as EntitlementResolutionConfig } from './plan-resolution-CFCoUkrE.cjs';
+
+/**
+ * Snapshot of the binding `PlanVersion` of a subscription. Quotas are
+ * delivered as a record of `quotaKey → number`; concrete keys are declared
+ * by the code via `@DefinesQuota`.
+ *
+ * `-1` is the catalog convention for "unlimited" — consumers must map that
+ * to `Number.POSITIVE_INFINITY` themselves if they want to compute with it.
+ */
+interface PlanVersionSnapshot {
+    planId: PlanId;
+    quotas: Record<QuotaKey, number>;
+    features: FeatureKey[];
+}
+/**
+ * Snapshot of a published BundleVersion (for BusinessType aggregation).
+ * The consumer resolves the bundle composition via repository lookup before
+ * the `aggregateLimits()` call.
+ */
+interface BundleVersionSnapshot {
+    bundleKey: string;
+    quotas: Record<QuotaKey, number>;
+    features: FeatureKey[];
+}
+/**
+ * Snapshot of the binding `BusinessTypeVersion` of a subscription
+ * (SPEC_V2 §11.1 M5). Contains the resolved bundle snapshots in sortOrder
+ * order, plus the quota overrides of the BusinessTypeVersion.
+ *
+ * Aggregation (see GESCHAEFTSTYP_SPEC §6.2):
+ * - Quotas: Σ(bundle quotas) per QuotaKey, then override via
+ *   `quotaOverrides[k]` if set
+ * - Features: ⋃ of all bundle features (set union)
+ */
+interface BusinessTypeVersionSnapshot {
+    businessTypeKey: string;
+    /** Bundles in sortOrder order. */
+    bundles: BundleVersionSnapshot[];
+    /** Override per QuotaKey. Missing key → Σ(bundle quotas) is used. */
+    quotaOverrides: Partial<Record<QuotaKey, number>>;
+}
+/**
+ * Snapshot of an active SubscriptionBundle booking (P11.7.3 +
+ * SPEC_V2 §11.1 M6 Pack 2e). Resolved by the EntitlementService from the
+ * `subscription_bundles` junction + BundleRepository.findVersionById and
+ * passed to `aggregateLimits`.
+ *
+ * Aggregation: quotas additive with -1 dominance, features ⋃ set union.
+ * The filter (`canceledEffectiveAt > now`) lives in the aggregator
+ * (`filterActiveSubscriptionBundles`), so the caller can simply pass in all
+ * bookings.
+ */
+interface SubscriptionBundleSnapshot {
+    bundleKey: string;
+    features: FeatureKey[];
+    quotas: Record<QuotaKey, number>;
+    /**
+     * Date up to which the booking is effectively active (= NULL for
+     * non-canceled bookings). The aggregator filters
+     * `canceledEffectiveAt > now` as active.
+     */
+    canceledEffectiveAt: Date | null;
+}
+/**
+ * Consumer override from `Subscription.customLimits` (e.g. an ENTERPRISE
+ * special contract or pilot). Field-wise — unset quotas/features fall back
+ * to the plan default.
+ */
+interface CustomLimitsShape {
+    quotas?: Record<QuotaKey, number>;
+    features?: FeatureKey[];
+}
+/**
+ * Input for `aggregateLimits` — the platform expects the consumer to have
+ * already performed the plan resolution (trial/pilot/pending). `plan` and
+ * `planVersion` are the result of that resolution; see
+ * `resolveEntitlementPlan` for a configurable default strategy.
+ *
+ * `businessTypeVersion` is optional (SPEC_V2 §11.1 M5). When set, the
+ * BusinessType composition is included in the aggregation in addition to
+ * plan + add-ons — see GESCHAEFTSTYP_SPEC §6.
+ */
+interface SubscriptionLimitsInput {
+    plan: PlanId;
+    planVersion: PlanVersionSnapshot;
+    businessTypeVersion?: BusinessTypeVersionSnapshot | null;
+    /**
+     * Active bundle bookings (P11.7.3). The aggregator filters by
+     * `canceledEffectiveAt > now` and sums quotas + collects features into
+     * the effective limits.
+     */
+    subscriptionBundles?: SubscriptionBundleSnapshot[];
+    customLimits?: CustomLimitsShape | null;
+}
+/**
+ * Effective limits of a tenant: plan ID + aggregated quotas + features.
+ */
+interface EffectiveLimits {
+    plan: PlanId;
+    quotas: Record<QuotaKey, number>;
+    features: Set<FeatureKey>;
+}
+/**
+ * Serializable form for snapshot fields (e.g. `Invoice.entitlementSnapshot`).
+ * `features` is a sorted array instead of a Set for stable JSON serialization.
+ */
+interface EffectiveLimitsSnapshot {
+    plan: PlanId;
+    quotas: Record<QuotaKey, number>;
+    features: FeatureKey[];
+}
+
+interface EnforceLimitInput<T> {
+    /** Tenant whose subscription is checked. */
+    tenantId: string;
+    /** Quota key from saas.yaml (`users`, `vehicles`, `storageGb`, …). */
+    dimension: string;
+    /**
+     * Counter for the units currently consumed within the transaction.
+     * The consumer counts e.g. `users WHERE tenantId AND deletedAt IS NULL`.
+     */
+    currentUsage: (tx: TransactionContext, tenantId: string) => Promise<number>;
+    /**
+     * Inserts the new row(s). Only executed when the limit is not exceeded
+     * after the increment.
+     */
+    insert: (tx: TransactionContext) => Promise<T>;
+    /**
+     * Increment that `insert` adds to the usage. Default 1
+     * (USERS/VEHICLES — one row per insert). For STORAGE inserts the caller
+     * can pass variable GB values through, so that even a 10 GB file blocks
+     * against a 1 GB limit.
+     */
+    delta?: number;
+    /** Override for tests; default `new Date()`. */
+    now?: Date;
+}
+declare class EntitlementService {
+    private readonly catalog;
+    private readonly subscriptions;
+    private readonly planVersions;
+    private readonly tx;
+    private readonly resolutionConfig;
+    private readonly subscriptionBundles;
+    private readonly bundles;
+    private readonly subscriptionContracts;
+    private readonly discoverySnapshot;
+    private readonly cache;
+    private replacedByIndex;
+    constructor(catalog: PlanCatalog, subscriptions: SubscriptionRepository, planVersions: PlanVersionRepository, tx: TransactionRunner, resolutionConfig?: EntitlementResolutionConfig | null, subscriptionBundles?: SubscriptionBundleRepository | null, bundles?: BundleRepository | null, subscriptionContracts?: SubscriptionContractRepository | null, discoverySnapshot?: DiscoverySnapshot | null);
+    computeLimits(tenantId: string, now?: Date): Promise<EffectiveLimits>;
+    /**
+     * Clears a tenant's cache entry. MUST be called as soon as a mutation
+     * changes the subscription, a bundle booking, or a PlanVersion binding —
+     * otherwise FeatureGuard and the sidebar stay on stale state for up to
+     * 60s.
+     */
+    invalidateTenant(tenantId: string): void;
+    /** Clears the entire cache. Only for tests / bootstrap. */
+    invalidateAll(): void;
+    /**
+     * Aggregator path — also callable directly by consumers that already
+     * have a `SubscriptionRecord` (e.g. within a transaction).
+     */
+    deriveLimits(sub: SubscriptionRecord, now: Date, tx?: TransactionContext): Promise<EffectiveLimits>;
+    /**
+     * Grandfathering (#39): granted old feature keys transitively grant
+     * their successors from the `replaces` chains of the discovery snapshot.
+     * A no-op without a snapshot or without replaces declarations.
+     */
+    private withReplacedFeatureAliases;
+    private deriveLimitsFromContract;
+    /**
+     * Loads a subscription's active bundle bookings and resolves the
+     * `BundleVersion` features/quotas per entry. Without a registered
+     * `SubscriptionBundleRepository` or `BundleRepository` the method
+     * returns an empty list — apps without a bundle schema stay unchanged
+     * (plan-only aggregation).
+     */
+    private loadSubscriptionBundleSnapshots;
+    enforceLimit<T>(input: EnforceLimitInput<T>): Promise<T>;
+    /**
+     * Plan fallback for TRIAL/PENDING_SALES: returns the PlanVersion active
+     * as of `asOf` (SPEC_V2 §4.2). If the repo does not implement
+     * `findActive`, we fall back to `findLatestLive` (backward compat for
+     * adapters without `validFrom` columns).
+     */
+    private findActivePlanVersionOrFallback;
+    private readCache;
+    private writeCache;
+}
+
+declare class LimitExceededError extends Error {
+    readonly dimension: string;
+    readonly max: number;
+    readonly used: number;
+    constructor(dimension: string, max: number, used: number);
+}
+
+/**
+ * Aggregates the quotas of a BusinessTypeVersion: Σ(bundle quotas) per
+ * QuotaKey, then override via `quotaOverrides[k]` if set.
+ *
+ * `-1` (unlimited) is handled as follows:
+ * - In Σ summation: -1 dominates (if a bundle has -1 for a key,
+ *   the Σ is likewise -1 for that key — regardless of the other values).
+ * - In overrides: if the override is -1, it replaces the sum entirely.
+ *
+ * Spec: GESCHAEFTSTYP_SPEC §6.2.
+ */
+declare function aggregateBusinessTypeQuotas(snapshot: BusinessTypeVersionSnapshot): Record<QuotaKey, number>;
+/**
+ * Filters SubscriptionBundle bookings down to those active at the given
+ * point in time. Active = `canceledEffectiveAt === null` or
+ * `canceledEffectiveAt > now`.
+ *
+ * Spec: SPEC_V2 §11.1 M6 Pack 2e + P11.7.3.
+ */
+declare function filterActiveSubscriptionBundles(bundles: readonly SubscriptionBundleSnapshot[], now: Date): SubscriptionBundleSnapshot[];
+/**
+ * Aggregates the quotas of all active SubscriptionBundle bookings:
+ * Σ per QuotaKey, `-1` (unlimited) dominates. Bundle features +
+ * bundle quotas are **additive** to the PlanVersion (not replacing).
+ */
+declare function aggregateSubscriptionBundleQuotas(bundles: readonly SubscriptionBundleSnapshot[]): Record<QuotaKey, number>;
+/**
+ * Collects all feature keys from active SubscriptionBundle bookings
+ * (set union; duplicate features are included once).
+ */
+declare function collectSubscriptionBundleFeatures(bundles: readonly SubscriptionBundleSnapshot[]): FeatureKey[];
+/**
+ * V3 aggregation directly from frozen ContractLineItems. This function
+ * uses no catalog lookups: `featuresSnapshot` and
+ * `quotaEffectsSnapshot` are the contractual truth.
+ */
+declare function aggregateContractLineItemEntitlements(lineItems: readonly Pick<ContractLineItemRecord, 'kind' | 'sourceKey' | 'featuresSnapshot' | 'quotaEffectsSnapshot'>[], fallbackPlan?: string): EffectiveLimits;
+/**
+ * Collects all feature keys from all bundles of a BusinessTypeVersion
+ * (set union; duplicate features are included once).
+ *
+ * Spec: GESCHAEFTSTYP_SPEC §6.3.
+ */
+declare function collectBusinessTypeFeatures(snapshot: BusinessTypeVersionSnapshot): FeatureKey[];
+/**
+ * Consistently filters out `plannedOnly` features — regardless of whether they
+ * come from the plan, a bundle or customLimits. `plannedOnly` means: the feature
+ * is declared in the catalog, but not yet rolled out to production.
+ */
+declare function filterPlannedOnlyFeatures(features: ReadonlySet<FeatureKey>, catalog: PlanCatalog): Set<FeatureKey>;
+/**
+ * Applies `customLimits` (ENTERPRISE special contract, pilot) field-by-field to
+ * the plan default limits. `quotas[k]` overrides; `features[]` adds.
+ * Fields not set in the override fall back to the default.
+ */
+declare function applyCustomLimits(base: EffectiveLimits, custom: CustomLimitsShape | null | undefined): EffectiveLimits;
+/**
+ * Main aggregator — yields the effective limits from PlanVersion + optional
+ * BusinessTypeVersion + active bundle bookings + catalog + optional
+ * CustomLimits override.
+ *
+ * Order (SPEC_V2 §11.1 M5 + GESCHAEFTSTYP_SPEC §6):
+ *   1. Filter active bundle bookings (canceledEffectiveAt).
+ *   2. Sum plan quotas + (BusinessType quotas with override logic) + bundle quotas
+ *      per `quotaKey`. -1 (unlimited) dominates.
+ *   3. Collect plan features ∪ BusinessType features ∪ bundle features
+ *      (set union, deduplicated).
+ *   4. Apply CustomLimits (quotas override, features add).
+ *   5. Consistently hide plannedOnly features.
+ */
+declare function aggregateLimits(input: SubscriptionLimitsInput, catalog: PlanCatalog, now: Date): EffectiveLimits;
+/**
+ * Checks whether a feature is contained in the effective limits.
+ */
+declare function hasFeature(limits: EffectiveLimits, feature: FeatureKey): boolean;
+/**
+ * Checks whether at least one of the given features is contained in the
+ * effective limits. An empty list yields `false`.
+ */
+declare function hasAnyFeature(limits: EffectiveLimits, features: readonly FeatureKey[]): boolean;
+/**
+ * Converts EffectiveLimits into a JSON-serializable shape (Set → sorted
+ * array). Used e.g. in `Invoice.entitlementSnapshot`.
+ */
+declare function toEffectiveLimitsSnapshot(limits: EffectiveLimits): EffectiveLimitsSnapshot;
+
+export { type BundleVersionSnapshot as B, type CustomLimitsShape as C, type EffectiveLimits as E, LimitExceededError as L, type PlanVersionSnapshot as P, type SubscriptionBundleSnapshot as S, type BusinessTypeVersionSnapshot as a, type EffectiveLimitsSnapshot as b, type EnforceLimitInput as c, EntitlementService as d, type SubscriptionLimitsInput as e, aggregateBusinessTypeQuotas as f, aggregateContractLineItemEntitlements as g, aggregateLimits as h, aggregateSubscriptionBundleQuotas as i, applyCustomLimits as j, collectBusinessTypeFeatures as k, collectSubscriptionBundleFeatures as l, filterActiveSubscriptionBundles as m, filterPlannedOnlyFeatures as n, hasAnyFeature as o, hasFeature as p, toEffectiveLimitsSnapshot as t };

package/dist/aggregation-Dvz9e8X2.d.ts

@@ -0,0 +1,288 @@
+import { PlanId, QuotaKey, FeatureKey, PlanCatalog, SubscriptionRepository, PlanVersionRepository, TransactionRunner, SubscriptionBundleRepository, BundleRepository, SubscriptionContractRepository, DiscoverySnapshot, SubscriptionRecord, TransactionContext, ContractLineItemRecord } from '@saasicat/types';
+import { E as EntitlementResolutionConfig } from './plan-resolution-CFCoUkrE.js';
+
+/**
+ * Snapshot of the binding `PlanVersion` of a subscription. Quotas are
+ * delivered as a record of `quotaKey → number`; concrete keys are declared
+ * by the code via `@DefinesQuota`.
+ *
+ * `-1` is the catalog convention for "unlimited" — consumers must map that
+ * to `Number.POSITIVE_INFINITY` themselves if they want to compute with it.
+ */
+interface PlanVersionSnapshot {
+    planId: PlanId;
+    quotas: Record<QuotaKey, number>;
+    features: FeatureKey[];
+}
+/**
+ * Snapshot of a published BundleVersion (for BusinessType aggregation).
+ * The consumer resolves the bundle composition via repository lookup before
+ * the `aggregateLimits()` call.
+ */
+interface BundleVersionSnapshot {
+    bundleKey: string;
+    quotas: Record<QuotaKey, number>;
+    features: FeatureKey[];
+}
+/**
+ * Snapshot of the binding `BusinessTypeVersion` of a subscription
+ * (SPEC_V2 §11.1 M5). Contains the resolved bundle snapshots in sortOrder
+ * order, plus the quota overrides of the BusinessTypeVersion.
+ *
+ * Aggregation (see GESCHAEFTSTYP_SPEC §6.2):
+ * - Quotas: Σ(bundle quotas) per QuotaKey, then override via
+ *   `quotaOverrides[k]` if set
+ * - Features: ⋃ of all bundle features (set union)
+ */
+interface BusinessTypeVersionSnapshot {
+    businessTypeKey: string;
+    /** Bundles in sortOrder order. */
+    bundles: BundleVersionSnapshot[];
+    /** Override per QuotaKey. Missing key → Σ(bundle quotas) is used. */
+    quotaOverrides: Partial<Record<QuotaKey, number>>;
+}
+/**
+ * Snapshot of an active SubscriptionBundle booking (P11.7.3 +
+ * SPEC_V2 §11.1 M6 Pack 2e). Resolved by the EntitlementService from the
+ * `subscription_bundles` junction + BundleRepository.findVersionById and
+ * passed to `aggregateLimits`.
+ *
+ * Aggregation: quotas additive with -1 dominance, features ⋃ set union.
+ * The filter (`canceledEffectiveAt > now`) lives in the aggregator
+ * (`filterActiveSubscriptionBundles`), so the caller can simply pass in all
+ * bookings.
+ */
+interface SubscriptionBundleSnapshot {
+    bundleKey: string;
+    features: FeatureKey[];
+    quotas: Record<QuotaKey, number>;
+    /**
+     * Date up to which the booking is effectively active (= NULL for
+     * non-canceled bookings). The aggregator filters
+     * `canceledEffectiveAt > now` as active.
+     */
+    canceledEffectiveAt: Date | null;
+}
+/**
+ * Consumer override from `Subscription.customLimits` (e.g. an ENTERPRISE
+ * special contract or pilot). Field-wise — unset quotas/features fall back
+ * to the plan default.
+ */
+interface CustomLimitsShape {
+    quotas?: Record<QuotaKey, number>;
+    features?: FeatureKey[];
+}
+/**
+ * Input for `aggregateLimits` — the platform expects the consumer to have
+ * already performed the plan resolution (trial/pilot/pending). `plan` and
+ * `planVersion` are the result of that resolution; see
+ * `resolveEntitlementPlan` for a configurable default strategy.
+ *
+ * `businessTypeVersion` is optional (SPEC_V2 §11.1 M5). When set, the
+ * BusinessType composition is included in the aggregation in addition to
+ * plan + add-ons — see GESCHAEFTSTYP_SPEC §6.
+ */
+interface SubscriptionLimitsInput {
+    plan: PlanId;
+    planVersion: PlanVersionSnapshot;
+    businessTypeVersion?: BusinessTypeVersionSnapshot | null;
+    /**
+     * Active bundle bookings (P11.7.3). The aggregator filters by
+     * `canceledEffectiveAt > now` and sums quotas + collects features into
+     * the effective limits.
+     */
+    subscriptionBundles?: SubscriptionBundleSnapshot[];
+    customLimits?: CustomLimitsShape | null;
+}
+/**
+ * Effective limits of a tenant: plan ID + aggregated quotas + features.
+ */
+interface EffectiveLimits {
+    plan: PlanId;
+    quotas: Record<QuotaKey, number>;
+    features: Set<FeatureKey>;
+}
+/**
+ * Serializable form for snapshot fields (e.g. `Invoice.entitlementSnapshot`).
+ * `features` is a sorted array instead of a Set for stable JSON serialization.
+ */
+interface EffectiveLimitsSnapshot {
+    plan: PlanId;
+    quotas: Record<QuotaKey, number>;
+    features: FeatureKey[];
+}
+
+interface EnforceLimitInput<T> {
+    /** Tenant whose subscription is checked. */
+    tenantId: string;
+    /** Quota key from saas.yaml (`users`, `vehicles`, `storageGb`, …). */
+    dimension: string;
+    /**
+     * Counter for the units currently consumed within the transaction.
+     * The consumer counts e.g. `users WHERE tenantId AND deletedAt IS NULL`.
+     */
+    currentUsage: (tx: TransactionContext, tenantId: string) => Promise<number>;
+    /**
+     * Inserts the new row(s). Only executed when the limit is not exceeded
+     * after the increment.
+     */
+    insert: (tx: TransactionContext) => Promise<T>;
+    /**
+     * Increment that `insert` adds to the usage. Default 1
+     * (USERS/VEHICLES — one row per insert). For STORAGE inserts the caller
+     * can pass variable GB values through, so that even a 10 GB file blocks
+     * against a 1 GB limit.
+     */
+    delta?: number;
+    /** Override for tests; default `new Date()`. */
+    now?: Date;
+}
+declare class EntitlementService {
+    private readonly catalog;
+    private readonly subscriptions;
+    private readonly planVersions;
+    private readonly tx;
+    private readonly resolutionConfig;
+    private readonly subscriptionBundles;
+    private readonly bundles;
+    private readonly subscriptionContracts;
+    private readonly discoverySnapshot;
+    private readonly cache;
+    private replacedByIndex;
+    constructor(catalog: PlanCatalog, subscriptions: SubscriptionRepository, planVersions: PlanVersionRepository, tx: TransactionRunner, resolutionConfig?: EntitlementResolutionConfig | null, subscriptionBundles?: SubscriptionBundleRepository | null, bundles?: BundleRepository | null, subscriptionContracts?: SubscriptionContractRepository | null, discoverySnapshot?: DiscoverySnapshot | null);
+    computeLimits(tenantId: string, now?: Date): Promise<EffectiveLimits>;
+    /**
+     * Clears a tenant's cache entry. MUST be called as soon as a mutation
+     * changes the subscription, a bundle booking, or a PlanVersion binding —
+     * otherwise FeatureGuard and the sidebar stay on stale state for up to
+     * 60s.
+     */
+    invalidateTenant(tenantId: string): void;
+    /** Clears the entire cache. Only for tests / bootstrap. */
+    invalidateAll(): void;
+    /**
+     * Aggregator path — also callable directly by consumers that already
+     * have a `SubscriptionRecord` (e.g. within a transaction).
+     */
+    deriveLimits(sub: SubscriptionRecord, now: Date, tx?: TransactionContext): Promise<EffectiveLimits>;
+    /**
+     * Grandfathering (#39): granted old feature keys transitively grant
+     * their successors from the `replaces` chains of the discovery snapshot.
+     * A no-op without a snapshot or without replaces declarations.
+     */
+    private withReplacedFeatureAliases;
+    private deriveLimitsFromContract;
+    /**
+     * Loads a subscription's active bundle bookings and resolves the
+     * `BundleVersion` features/quotas per entry. Without a registered
+     * `SubscriptionBundleRepository` or `BundleRepository` the method
+     * returns an empty list — apps without a bundle schema stay unchanged
+     * (plan-only aggregation).
+     */
+    private loadSubscriptionBundleSnapshots;
+    enforceLimit<T>(input: EnforceLimitInput<T>): Promise<T>;
+    /**
+     * Plan fallback for TRIAL/PENDING_SALES: returns the PlanVersion active
+     * as of `asOf` (SPEC_V2 §4.2). If the repo does not implement
+     * `findActive`, we fall back to `findLatestLive` (backward compat for
+     * adapters without `validFrom` columns).
+     */
+    private findActivePlanVersionOrFallback;
+    private readCache;
+    private writeCache;
+}
+
+declare class LimitExceededError extends Error {
+    readonly dimension: string;
+    readonly max: number;
+    readonly used: number;
+    constructor(dimension: string, max: number, used: number);
+}
+
+/**
+ * Aggregates the quotas of a BusinessTypeVersion: Σ(bundle quotas) per
+ * QuotaKey, then override via `quotaOverrides[k]` if set.
+ *
+ * `-1` (unlimited) is handled as follows:
+ * - In Σ summation: -1 dominates (if a bundle has -1 for a key,
+ *   the Σ is likewise -1 for that key — regardless of the other values).
+ * - In overrides: if the override is -1, it replaces the sum entirely.
+ *
+ * Spec: GESCHAEFTSTYP_SPEC §6.2.
+ */
+declare function aggregateBusinessTypeQuotas(snapshot: BusinessTypeVersionSnapshot): Record<QuotaKey, number>;
+/**
+ * Filters SubscriptionBundle bookings down to those active at the given
+ * point in time. Active = `canceledEffectiveAt === null` or
+ * `canceledEffectiveAt > now`.
+ *
+ * Spec: SPEC_V2 §11.1 M6 Pack 2e + P11.7.3.
+ */
+declare function filterActiveSubscriptionBundles(bundles: readonly SubscriptionBundleSnapshot[], now: Date): SubscriptionBundleSnapshot[];
+/**
+ * Aggregates the quotas of all active SubscriptionBundle bookings:
+ * Σ per QuotaKey, `-1` (unlimited) dominates. Bundle features +
+ * bundle quotas are **additive** to the PlanVersion (not replacing).
+ */
+declare function aggregateSubscriptionBundleQuotas(bundles: readonly SubscriptionBundleSnapshot[]): Record<QuotaKey, number>;
+/**
+ * Collects all feature keys from active SubscriptionBundle bookings
+ * (set union; duplicate features are included once).
+ */
+declare function collectSubscriptionBundleFeatures(bundles: readonly SubscriptionBundleSnapshot[]): FeatureKey[];
+/**
+ * V3 aggregation directly from frozen ContractLineItems. This function
+ * uses no catalog lookups: `featuresSnapshot` and
+ * `quotaEffectsSnapshot` are the contractual truth.
+ */
+declare function aggregateContractLineItemEntitlements(lineItems: readonly Pick<ContractLineItemRecord, 'kind' | 'sourceKey' | 'featuresSnapshot' | 'quotaEffectsSnapshot'>[], fallbackPlan?: string): EffectiveLimits;
+/**
+ * Collects all feature keys from all bundles of a BusinessTypeVersion
+ * (set union; duplicate features are included once).
+ *
+ * Spec: GESCHAEFTSTYP_SPEC §6.3.
+ */
+declare function collectBusinessTypeFeatures(snapshot: BusinessTypeVersionSnapshot): FeatureKey[];
+/**
+ * Consistently filters out `plannedOnly` features — regardless of whether they
+ * come from the plan, a bundle or customLimits. `plannedOnly` means: the feature
+ * is declared in the catalog, but not yet rolled out to production.
+ */
+declare function filterPlannedOnlyFeatures(features: ReadonlySet<FeatureKey>, catalog: PlanCatalog): Set<FeatureKey>;
+/**
+ * Applies `customLimits` (ENTERPRISE special contract, pilot) field-by-field to
+ * the plan default limits. `quotas[k]` overrides; `features[]` adds.
+ * Fields not set in the override fall back to the default.
+ */
+declare function applyCustomLimits(base: EffectiveLimits, custom: CustomLimitsShape | null | undefined): EffectiveLimits;
+/**
+ * Main aggregator — yields the effective limits from PlanVersion + optional
+ * BusinessTypeVersion + active bundle bookings + catalog + optional
+ * CustomLimits override.
+ *
+ * Order (SPEC_V2 §11.1 M5 + GESCHAEFTSTYP_SPEC §6):
+ *   1. Filter active bundle bookings (canceledEffectiveAt).
+ *   2. Sum plan quotas + (BusinessType quotas with override logic) + bundle quotas
+ *      per `quotaKey`. -1 (unlimited) dominates.
+ *   3. Collect plan features ∪ BusinessType features ∪ bundle features
+ *      (set union, deduplicated).
+ *   4. Apply CustomLimits (quotas override, features add).
+ *   5. Consistently hide plannedOnly features.
+ */
+declare function aggregateLimits(input: SubscriptionLimitsInput, catalog: PlanCatalog, now: Date): EffectiveLimits;
+/**
+ * Checks whether a feature is contained in the effective limits.
+ */
+declare function hasFeature(limits: EffectiveLimits, feature: FeatureKey): boolean;
+/**
+ * Checks whether at least one of the given features is contained in the
+ * effective limits. An empty list yields `false`.
+ */
+declare function hasAnyFeature(limits: EffectiveLimits, features: readonly FeatureKey[]): boolean;
+/**
+ * Converts EffectiveLimits into a JSON-serializable shape (Set → sorted
+ * array). Used e.g. in `Invoice.entitlementSnapshot`.
+ */
+declare function toEffectiveLimitsSnapshot(limits: EffectiveLimits): EffectiveLimitsSnapshot;
+
+export { type BundleVersionSnapshot as B, type CustomLimitsShape as C, type EffectiveLimits as E, LimitExceededError as L, type PlanVersionSnapshot as P, type SubscriptionBundleSnapshot as S, type BusinessTypeVersionSnapshot as a, type EffectiveLimitsSnapshot as b, type EnforceLimitInput as c, EntitlementService as d, type SubscriptionLimitsInput as e, aggregateBusinessTypeQuotas as f, aggregateContractLineItemEntitlements as g, aggregateLimits as h, aggregateSubscriptionBundleQuotas as i, applyCustomLimits as j, collectBusinessTypeFeatures as k, collectSubscriptionBundleFeatures as l, filterActiveSubscriptionBundles as m, filterPlannedOnlyFeatures as n, hasAnyFeature as o, hasFeature as p, toEffectiveLimitsSnapshot as t };