Consumption metrics

1/**
2 * Consumption metrics: shapes, unit conversion, and cost math for the Neon
3 * v2 consumption API (`/consumption_history/v2/projects` and `/branches`).
4 *
5 * The API reports raw units — CU-seconds, byte-hours, branch-hours — which
6 * are not what an invoice or a dashboard shows. Every conversion Neon
7 * documents lives here once, so a chart, a breakdown, and a cost estimate
8 * can't drift from each other or from the bill.
9 *
10 * See https://neon.com/docs/introduction/usage-calculations.
11 */
12 
13/** The eight billable metrics returned by the per-project endpoint. */
14export const CONSUMPTION_METRICS = [
15  "compute_unit_seconds",
16  "root_branch_bytes_month",
17  "child_branch_bytes_month",
18  "instant_restore_bytes_month",
19  "snapshot_storage_bytes_month",
20  "public_network_transfer_bytes",
21  "private_network_transfer_bytes",
22  "extra_branches_month",
23] as const;
24 
25export type ConsumptionMetricName = (typeof CONSUMPTION_METRICS)[number];
26 
27/** The six metrics the per-branch endpoint supports. */
28export const BRANCH_CONSUMPTION_METRICS = [
29  "compute_unit_seconds",
30  "root_branch_bytes_month",
31  "child_branch_bytes_month",
32  "instant_restore_bytes_month",
33  "public_network_transfer_bytes",
34  "private_network_transfer_bytes",
35] as const;
36 
37export type BranchConsumptionMetricName =
38  (typeof BRANCH_CONSUMPTION_METRICS)[number];
39 
40export type ConsumptionGranularity = "hourly" | "daily" | "monthly";
41 
42export type ConsumptionPlan = "launch" | "scale" | "agent" | "enterprise";
43 
44/**
45 * Shapes mirror the SDK's response types, optional fields and all: the API
46 * omits a metric whose value was zero, and omits timeframe bounds on empty
47 * buckets. Accepting that here means an SDK response drops straight in.
48 */
49export interface ConsumptionMetricValue {
50  metric_name: string;
51  value: number;
52}
53 
54export interface ConsumptionTimeframe {
55  timeframe_start?: string;
56  timeframe_end?: string;
57  metrics?: ConsumptionMetricValue[];
58}
59 
60export interface ConsumptionPeriod {
61  period_id?: string;
62  period_plan?: string;
63  period_start?: string;
64  consumption?: ConsumptionTimeframe[];
65}
66 
67export interface ConsumptionProject {
68  project_id: string;
69  periods: ConsumptionPeriod[];
70}
71 
72export interface ConsumptionBranch {
73  branch_id: string;
74  project_id: string;
75  periods: ConsumptionPeriod[];
76}
77 
78/** One timeframe flattened to a metric-name -> value map. */
79export interface ConsumptionBucket {
80  start: string;
81  end: string;
82  values: Partial<Record<ConsumptionMetricName, number>>;
83}
84 
85// … truncated