Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
+349
@@ -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,
|
||||
});
|
||||
}
|
||||
Reference in new issue
Block a user