350 lines
14 KiB
TypeScript
350 lines
14 KiB
TypeScript
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<Record<SeatType, number>>;
|
|
readonly taxCode: typeof hiveGridVat.code;
|
|
}
|
|
|
|
export interface BillingCatalogBasePlan {
|
|
readonly technicalCode: EntitlementPlanId;
|
|
readonly publicName: "Core" | "Swarm" | "Colony";
|
|
readonly seatPackageId: SeatPackageId;
|
|
readonly includedSeats: Readonly<Record<SeatType, number>>;
|
|
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<Record<SeatType, number>>
|
|
): 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<EntitlementPlanId, BillingCatalogBasePlan>(hiveGridBasePlans.map((plan) => [plan.technicalCode, plan]));
|
|
const variantByCode = new Map<string, BillingCatalogPlanVariant>(
|
|
hiveGridBasePlans.flatMap((plan) => plan.variants.map((variant) => [variant.code, variant] as const))
|
|
);
|
|
const storageAddOnByCode = new Map<StorageAddOnCode, BillingCatalogStorageAddOn>(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,
|
|
});
|
|
}
|