import { ANNUAL_SEPA_EXTRA_DISCOUNT, getSeatPackage, seatPackageIds, type SeatPackageId } from "./seat-packages.js"; import { entitlementPlanIds, type EntitlementPlanId } from "./plans.js"; import { emailMarketingCommercialProducts } from "./email-marketing-commercial.js"; import type { SeatType } from "./seats.js"; /** * Katalogversion fuer den kontrollierten Lago-Sync. * * Jede fachliche Aenderung an Namen, Preisen, Laufzeiten, Steuern oder Limits * erhoeht diese Version. Staging und Production muessen denselben Wert melden. */ export const hiveGridBillingCatalogVersion = "2026-08-03.3"; export const billingCadences = Object.freeze({ monthly: "monthly", annualSepa: "annual_sepa", } as const); export type BillingCadence = (typeof billingCadences)[keyof typeof billingCadences]; export const hiveGridVat = Object.freeze({ code: "de-vat-19", name: "Deutsche Umsatzsteuer 19 %", countryCode: "DE", rateBasisPoints: 1_900, appliedToAmount: "exclusive", } as const); export interface BillingCatalogPlanVariant { readonly code: string; readonly cadence: BillingCadence; /** Both variants are invoiced monthly. Annual means commitment, not prepayment. */ readonly lagoInterval: "monthly"; readonly contractMonths: 1 | 12; readonly requiredPaymentMethod: "any" | "sepa"; readonly baseAmountCents: number; readonly extraSeatAmountCents: Readonly>; readonly taxCode: typeof hiveGridVat.code; } export interface BillingCatalogBasePlan { readonly technicalCode: EntitlementPlanId; readonly publicName: "Core" | "Swarm" | "Colony"; readonly seatPackageId: SeatPackageId; readonly includedSeats: Readonly>; readonly includedStorageGb: number; readonly storagePerAdditionalSeatGb: number; readonly variants: readonly [BillingCatalogPlanVariant, BillingCatalogPlanVariant]; } export const storageAddOnCodes = Object.freeze({ gb100: "storage_100gb", gb500: "storage_500gb", tb1: "storage_1tb", tb5: "storage_5tb", } as const); export type StorageAddOnCode = (typeof storageAddOnCodes)[keyof typeof storageAddOnCodes]; export interface BillingCatalogStorageAddOn { readonly code: StorageAddOnCode; readonly publicName: string; readonly includedStorageGb: number; readonly amountCents: number; /** False keeps historical contracts resolvable without offering the package to new purchases. */ readonly purchasable: boolean; readonly lagoInterval: "monthly"; readonly taxCode: typeof hiveGridVat.code; } export interface BillingCatalogPriceSelection { readonly planCode: EntitlementPlanId | string; readonly cadence: BillingCadence; readonly officeSeatQuantity: number; readonly fieldSeatQuantity: number; readonly storageAddOnCodes?: readonly (StorageAddOnCode | string)[]; } export interface BillingCatalogPriceBreakdown { readonly planCode: EntitlementPlanId; readonly variantCode: string; readonly cadence: BillingCadence; readonly contractMonths: 1 | 12; readonly requiredPaymentMethod: "any" | "sepa"; readonly officeSeatQuantity: number; readonly fieldSeatQuantity: number; readonly includedOfficeSeatQuantity: number; readonly includedFieldSeatQuantity: number; readonly extraOfficeSeatQuantity: number; readonly extraFieldSeatQuantity: number; readonly baseAmountCents: number; readonly officeSeatAmountCents: number; readonly fieldSeatAmountCents: number; readonly storageAmountCents: number; readonly recurringNetAmountCents: number; readonly vatRateBasisPoints: typeof hiveGridVat.rateBasisPoints; readonly vatAmountCents: number; readonly recurringGrossAmountCents: number; readonly storageAddOns: readonly BillingCatalogStorageAddOn[]; } function extraSeatAmountCents(listPriceEur: number, cadence: BillingCadence): number { const discount = cadence === billingCadences.annualSepa ? ANNUAL_SEPA_EXTRA_DISCOUNT : 0; return Math.round(listPriceEur * 100 * (1 - discount)); } function planVariant( technicalCode: EntitlementPlanId, cadence: BillingCadence, baseAmountCents: number, extraSeatListPricesEur: Readonly> ): BillingCatalogPlanVariant { const annual = cadence === billingCadences.annualSepa; return Object.freeze({ code: annual ? `${technicalCode}_annual_sepa` : technicalCode, cadence, lagoInterval: "monthly", contractMonths: annual ? 12 : 1, requiredPaymentMethod: "any", baseAmountCents, extraSeatAmountCents: Object.freeze({ office: extraSeatAmountCents(extraSeatListPricesEur.office, cadence), field: extraSeatAmountCents(extraSeatListPricesEur.field, cadence), }), taxCode: hiveGridVat.code, }); } function basePlan(input: { technicalCode: EntitlementPlanId; publicName: BillingCatalogBasePlan["publicName"]; seatPackageId: SeatPackageId; }): BillingCatalogBasePlan { const seatPackage = getSeatPackage(input.seatPackageId); const extraSeatListPricesEur = { office: seatPackage.seats.office.extraPriceEur, field: seatPackage.seats.field.extraPriceEur, } as const; return Object.freeze({ technicalCode: input.technicalCode, publicName: input.publicName, seatPackageId: input.seatPackageId, includedSeats: Object.freeze({ office: seatPackage.seats.office.included, field: seatPackage.seats.field.included, }), includedStorageGb: seatPackage.storage.includedGb, storagePerAdditionalSeatGb: seatPackage.storage.perAdditionalSeatGb, variants: Object.freeze([ planVariant(input.technicalCode, billingCadences.monthly, seatPackage.monthlyEur * 100, extraSeatListPricesEur), planVariant(input.technicalCode, billingCadences.annualSepa, seatPackage.annualSepaEur * 100, extraSeatListPricesEur), ]) as BillingCatalogBasePlan["variants"], }); } export const hiveGridBasePlans = Object.freeze([ basePlan({ technicalCode: entitlementPlanIds.starter, publicName: "Core", seatPackageId: seatPackageIds.starter, }), basePlan({ technicalCode: entitlementPlanIds.pro, publicName: "Swarm", seatPackageId: seatPackageIds.team, }), basePlan({ technicalCode: entitlementPlanIds.business, publicName: "Colony", seatPackageId: seatPackageIds.business, }), ] as const satisfies readonly BillingCatalogBasePlan[]); function storageAddOn( code: StorageAddOnCode, publicName: string, includedStorageGb: number, amountCents: number, purchasable: boolean ): BillingCatalogStorageAddOn { return Object.freeze({ code, publicName, includedStorageGb, amountCents, purchasable, lagoInterval: "monthly", taxCode: hiveGridVat.code, }); } export const hiveGridStorageAddOns = Object.freeze([ storageAddOn(storageAddOnCodes.gb100, "Cloud-Speicher Plus · 100 GB", 100, 125, false), storageAddOn(storageAddOnCodes.gb500, "Cloud-Speicher Plus · 500 GB", 500, 699, true), storageAddOn(storageAddOnCodes.tb1, "Cloud-Speicher Plus · 1 TB", 1_000, 1_299, true), storageAddOn(storageAddOnCodes.tb5, "Cloud-Speicher Plus · 5 TB", 5_000, 6_099, true), ] as const satisfies readonly BillingCatalogStorageAddOn[]); export const hiveGridPurchasableStorageAddOns = Object.freeze(hiveGridStorageAddOns.filter((addOn) => addOn.purchasable)); /** Current direct marginal Hetzner storage COGS. */ export const hetznerAdditionalStorageCostCentsPerTb = 626; /** Current external Hetzner egress overage COGS; the account-wide allowance is deliberately not allocated to a package. */ export const hetznerAdditionalEgressCostCentsPerTb = 100; /** Commercial safety envelope: each package remains contribution-positive after five fully billable read-outs. */ export const storageAddOnEgressCoverageCycles = 5; /** HiveGrid quotas use GiB-sized units while Hetzner bills storage and traffic in decimal TB. */ export const storageCapacityBytesPerGb = 1_024 ** 3; const hetznerBytesPerTb = 1_000_000_000_000; function calculateStorageCostCents(addOn: BillingCatalogStorageAddOn, egressCycles: number): number { if (!Number.isSafeInteger(egressCycles) || egressCycles < 0 || egressCycles > 10_000) { throw new RangeError("Storage egress cycles must be a non-negative safe integer up to 10000."); } const capacityBytes = addOn.includedStorageGb * storageCapacityBytesPerGb; const rateCentsPerTb = hetznerAdditionalStorageCostCentsPerTb + egressCycles * hetznerAdditionalEgressCostCentsPerTb; const costCents = (capacityBytes / hetznerBytesPerTb) * rateCentsPerTb; if (!Number.isFinite(costCents) || costCents < 0) { throw new RangeError("Storage cost inputs exceed the safe integer range."); } return costCents; } export function calculateStorageAddOnGrossMarginBasisPoints(addOn: BillingCatalogStorageAddOn): number { return calculateStorageAddOnGrossMarginAfterEgressBasisPoints(addOn, 0); } export function calculateStorageAddOnGrossMarginAfterEgressBasisPoints( addOn: BillingCatalogStorageAddOn, egressCycles: number ): number { if (!Number.isSafeInteger(addOn.amountCents) || addOn.amountCents <= 0) { throw new RangeError("Storage revenue inputs exceed the safe integer range."); } const costCents = calculateStorageCostCents(addOn, egressCycles); return Math.round(((addOn.amountCents - costCents) / addOn.amountCents) * 10_000); } const planByTechnicalCode = new Map(hiveGridBasePlans.map((plan) => [plan.technicalCode, plan])); const variantByCode = new Map( hiveGridBasePlans.flatMap((plan) => plan.variants.map((variant) => [variant.code, variant] as const)) ); const storageAddOnByCode = new Map(hiveGridStorageAddOns.map((addOn) => [addOn.code, addOn])); export function getBillingCatalogPlan(code: EntitlementPlanId | string): BillingCatalogBasePlan | undefined { return planByTechnicalCode.get(code as EntitlementPlanId); } export function getBillingCatalogVariant(code: string): BillingCatalogPlanVariant | undefined { return variantByCode.get(code); } export function getBillingCatalogVariantForSelection(planCode: EntitlementPlanId | string, cadence: BillingCadence): BillingCatalogPlanVariant | undefined { return getBillingCatalogPlan(planCode)?.variants.find((variant) => variant.cadence === cadence); } export function getBillingCatalogStorageAddOn(code: StorageAddOnCode | string): BillingCatalogStorageAddOn | undefined { return storageAddOnByCode.get(code as StorageAddOnCode); } function requireSeatQuantity(value: number, label: string): number { if (!Number.isSafeInteger(value) || value < 0 || value > 10_000) { throw new RangeError(`${label} must be a non-negative safe integer up to 10000.`); } return value; } function safeAmount(...values: number[]): number { const amount = values.reduce((total, value) => total + value, 0); if (!Number.isSafeInteger(amount) || amount < 0) { throw new RangeError("Billing amount exceeds the safe integer range."); } return amount; } export function calculateHiveGridVatAmountCents(netAmountCents: number): number { if (!Number.isSafeInteger(netAmountCents) || netAmountCents < 0) { throw new RangeError("Billing net amount must be a non-negative safe integer."); } const scaled = netAmountCents * hiveGridVat.rateBasisPoints; if (!Number.isSafeInteger(scaled)) { throw new RangeError("Billing tax amount exceeds the safe integer range."); } return Math.round(scaled / 10_000); } export function calculateHiveGridGrossAmountCents(netAmountCents: number): number { return safeAmount(netAmountCents, calculateHiveGridVatAmountCents(netAmountCents)); } export function calculateBillingCatalogPrice(selection: BillingCatalogPriceSelection): BillingCatalogPriceBreakdown { const plan = getBillingCatalogPlan(selection.planCode); if (!plan) throw new RangeError(`Unknown billing plan: ${selection.planCode}`); const variant = getBillingCatalogVariantForSelection(plan.technicalCode, selection.cadence); if (!variant) throw new RangeError(`Unknown billing cadence for ${plan.technicalCode}: ${selection.cadence}`); const officeSeatQuantity = requireSeatQuantity(selection.officeSeatQuantity, "officeSeatQuantity"); const fieldSeatQuantity = requireSeatQuantity(selection.fieldSeatQuantity, "fieldSeatQuantity"); const storageCodes = selection.storageAddOnCodes ?? []; if (new Set(storageCodes).size !== storageCodes.length) { throw new RangeError("Storage add-on codes must be unique."); } const storageAddOns = storageCodes.map((code) => { const addOn = getBillingCatalogStorageAddOn(code); if (!addOn) throw new RangeError(`Unknown storage add-on: ${code}`); return addOn; }); const extraOfficeSeatQuantity = Math.max(0, officeSeatQuantity - plan.includedSeats.office); const extraFieldSeatQuantity = Math.max(0, fieldSeatQuantity - plan.includedSeats.field); const officeSeatAmountCents = extraOfficeSeatQuantity * variant.extraSeatAmountCents.office; const fieldSeatAmountCents = extraFieldSeatQuantity * variant.extraSeatAmountCents.field; const storageAmountCents = safeAmount(...storageAddOns.map((addOn) => addOn.amountCents)); const recurringNetAmountCents = safeAmount(variant.baseAmountCents, officeSeatAmountCents, fieldSeatAmountCents, storageAmountCents); const vatAmountCents = calculateHiveGridVatAmountCents(recurringNetAmountCents); return Object.freeze({ planCode: plan.technicalCode, variantCode: variant.code, cadence: variant.cadence, contractMonths: variant.contractMonths, requiredPaymentMethod: variant.requiredPaymentMethod, officeSeatQuantity, fieldSeatQuantity, includedOfficeSeatQuantity: plan.includedSeats.office, includedFieldSeatQuantity: plan.includedSeats.field, extraOfficeSeatQuantity, extraFieldSeatQuantity, baseAmountCents: variant.baseAmountCents, officeSeatAmountCents, fieldSeatAmountCents, storageAmountCents, recurringNetAmountCents, vatRateBasisPoints: hiveGridVat.rateBasisPoints, vatAmountCents, recurringGrossAmountCents: calculateHiveGridGrossAmountCents(recurringNetAmountCents), storageAddOns: Object.freeze([...storageAddOns]), }); } /** Deterministic provider-neutral manifest used by sync and drift tooling. */ export function serializeHiveGridBillingCatalog(): string { return JSON.stringify({ version: hiveGridBillingCatalogVersion, tax: hiveGridVat, basePlans: hiveGridBasePlans, storageAddOns: hiveGridStorageAddOns, emailMarketingAddOns: emailMarketingCommercialProducts, }); }