Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -0,0 +1,349 @@
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,
});
}