@pagopa/dx-savemoney 0.3.2 → 0.4.0

package/src/azure/pricing/resolvers/app-service.ts

@@ -0,0 +1,102 @@
+/**
+ * Resolver: estimated monthly cost of an Azure App Service Plan.
+ *
+ * App Service Plan meters are published as hourly prices per plan instance.
+ * The resolver looks up all App Service meters in the target region, then
+ * matches the ARM plan SKU locally because Retail Prices uses inconsistent
+ * spacing for some families (for example `P1v3` vs `P1 v3`).
+ */
+
+import type { Money } from "../../../finding.js";
+import type { PricingClient } from "../client.js";
+import type { PriceItem } from "../schema.js";
+
+import { HOURS_PER_MONTH, normalizeArmRegion } from "./vm.js";
+
+export type AppServicePlanOs = "linux" | "windows";
+
+export type ResolveAppServicePlanInput = {
+  /** ARM region name, e.g. `westeurope`. */
+  armRegionName: string;
+  /** Optional OS hint. When absent, the cheapest matching meter is used. */
+  os?: AppServicePlanOs;
+  /** App Service Plan SKU name, e.g. `S1`, `P1v3`, `P1mv3`. */
+  skuName: string;
+  /** Number of plan workers/instances to price. Defaults to 1. */
+  workerCount?: number;
+};
+
+/**
+ * Resolves the estimated monthly cost for an App Service Plan. Returns
+ * `undefined` if no matching consumption meter can be found.
+ */
+export async function resolveAppServicePlanMonthlyPrice(
+  client: PricingClient,
+  input: ResolveAppServicePlanInput,
+): Promise<Money | undefined> {
+  const filter = [
+    "serviceName eq 'Azure App Service'",
+    `armRegionName eq '${normalizeArmRegion(input.armRegionName)}'`,
+  ].join(" and ");
+
+  const items = await client.query(filter);
+  const item = pickAppServicePlanItem(items, input);
+  if (!item) {
+    return undefined;
+  }
+
+  return {
+    amount: round2(
+      item.unitPrice *
+        HOURS_PER_MONTH *
+        normalizeWorkerCount(input.workerCount),
+    ),
+    currency: item.currencyCode,
+  };
+}
+
+function matchesOs(item: PriceItem, os: AppServicePlanOs | undefined): boolean {
+  if (!os) return true;
+  // Retail meters encode the OS variant in the product name, not in a
+  // dedicated field.
+  const product = item.productName?.toLowerCase() ?? "";
+  const isLinuxItem = product.includes("linux");
+  return os === "linux" ? isLinuxItem : !isLinuxItem;
+}
+
+function normalizeSkuName(value: string | undefined): string {
+  // ARM uses compact SKU names (`P1v3`), while Retail Prices sometimes
+  // inserts spaces (`P1 v3`).
+  return value?.toLowerCase().replace(/\s+/g, "") ?? "";
+}
+
+function normalizeWorkerCount(workerCount: number | undefined): number {
+  // App Service Plan billing is per whole worker instance; invalid or missing
+  // values fall back to the minimum billable instance.
+  if (!workerCount || workerCount < 1) return 1;
+  return Math.ceil(workerCount);
+}
+
+function pickAppServicePlanItem(
+  items: PriceItem[],
+  input: ResolveAppServicePlanInput,
+): PriceItem | undefined {
+  const skuName = normalizeSkuName(input.skuName);
+  const candidates = items.filter(
+    (it) =>
+      it.type === "Consumption" &&
+      it.unitOfMeasure === "1 Hour" &&
+      normalizeSkuName(it.skuName) === skuName &&
+      (it.productName?.toLowerCase().includes("app service") ?? false) &&
+      (it.productName?.toLowerCase().includes("plan") ?? false) &&
+      matchesOs(it, input.os),
+  );
+  if (candidates.length === 0) return undefined;
+  return candidates.reduce((cheapest, it) =>
+    it.unitPrice < cheapest.unitPrice ? it : cheapest,
+  );
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}

package/src/azure/pricing/resolvers/disk.ts

@@ -0,0 +1,170 @@
+/**
+ * Resolver: estimated monthly cost of an Azure Managed Disk.
+ *
+ * Azure prices managed disks per discrete capacity tier (P1…P80,
+ * E1…E80, S4…S80) rather than per actual `diskSizeGB`. The resolver:
+ *
+ *  1. Maps the disk SKU (`Premium_LRS`, `StandardSSD_ZRS`, …) and
+ *     `diskSizeGB` to the corresponding billing tier (e.g. `P10 LRS`).
+ *  2. Queries the Azure Retail Prices API with the tier-derived
+ *     `skuName` for the right service / region.
+ *  3. Returns the consumption price (already `1/Month` in the API) as
+ *     `Money`, or `undefined` if no match (e.g. Ultra disks, which use
+ *     a different per-GB / IOPS / throughput pricing model and are not
+ *     yet supported).
+ *
+ * The mapping is intentionally encoded in a single Zod-validated
+ * lookup table so a malformed input fails fast and loud rather than
+ * silently producing a wrong tier.
+ */
+
+import { z } from "zod";
+
+import type { Money } from "../../../finding.js";
+import type { PricingClient } from "../client.js";
+import type { PriceItem } from "../schema.js";
+
+import { normalizeArmRegion } from "./vm.js";
+
+/**
+ * Replication mode supported by the resolver. Ultra disks (`UltraSSD_LRS`)
+ * are intentionally excluded because their pricing is multi-dimensional
+ * (capacity + IOPS + throughput) and would need a dedicated resolver.
+ */
+export const DiskSkuSchema = z.enum([
+  "Premium_LRS",
+  "Premium_ZRS",
+  "StandardSSD_LRS",
+  "StandardSSD_ZRS",
+  "Standard_LRS",
+]);
+export type DiskSku = z.infer<typeof DiskSkuSchema>;
+
+/**
+ * Inclusive upper bound (GiB) → tier name. Order matters: the resolver
+ * picks the FIRST entry whose `maxSizeGiB` is greater-or-equal to the
+ * requested size.
+ *
+ * See https://learn.microsoft.com/azure/virtual-machines/disks-types for
+ * the canonical tier table.
+ */
+const TIER_TABLE: readonly { maxSizeGiB: number; tier: number }[] = [
+  { maxSizeGiB: 4, tier: 1 },
+  { maxSizeGiB: 8, tier: 2 },
+  { maxSizeGiB: 16, tier: 3 },
+  { maxSizeGiB: 32, tier: 4 },
+  { maxSizeGiB: 64, tier: 6 },
+  { maxSizeGiB: 128, tier: 10 },
+  { maxSizeGiB: 256, tier: 15 },
+  { maxSizeGiB: 512, tier: 20 },
+  { maxSizeGiB: 1024, tier: 30 },
+  { maxSizeGiB: 2048, tier: 40 },
+  { maxSizeGiB: 4096, tier: 50 },
+  { maxSizeGiB: 8192, tier: 60 },
+  { maxSizeGiB: 16384, tier: 70 },
+  { maxSizeGiB: 32768, tier: 80 },
+];
+
+const SKU_METADATA = {
+  Premium_LRS: {
+    prefix: "P",
+    productName: "Premium SSD Managed Disks",
+    replication: "LRS",
+  },
+  Premium_ZRS: {
+    prefix: "P",
+    productName: "Premium SSD Managed Disks",
+    replication: "ZRS",
+  },
+  Standard_LRS: {
+    prefix: "S",
+    productName: "Standard HDD Managed Disks",
+    replication: "LRS",
+  },
+  StandardSSD_LRS: {
+    prefix: "E",
+    productName: "Standard SSD Managed Disks",
+    replication: "LRS",
+  },
+  StandardSSD_ZRS: {
+    prefix: "E",
+    productName: "Standard SSD Managed Disks",
+    replication: "ZRS",
+  },
+} as const satisfies Record<
+  DiskSku,
+  { prefix: string; productName: string; replication: string }
+>;
+
+export const ResolveDiskInputSchema = z.object({
+  /** ARM region name, e.g. `westeurope`. */
+  armRegionName: z.string().min(1),
+  /** Disk capacity in GiB as reported by the Compute API (`diskSizeGB`). */
+  diskSizeGiB: z.number().int().positive(),
+  /** Managed disk SKU. */
+  sku: DiskSkuSchema,
+});
+export type ResolveDiskInput = z.infer<typeof ResolveDiskInputSchema>;
+
+/**
+ * Pure helper exposed for testing: resolves the size→tier mapping
+ * without touching the network.
+ */
+export function pickTier(diskSizeGiB: number): number | undefined {
+  return TIER_TABLE.find((row) => diskSizeGiB <= row.maxSizeGiB)?.tier;
+}
+
+/**
+ * Resolves the estimated monthly cost for a Managed Disk. Returns
+ * `undefined` if the SKU/size combo is unsupported (e.g. exceeds the
+ * largest tier) or if no matching Retail Prices entry is found.
+ */
+export async function resolveDiskMonthlyPrice(
+  client: PricingClient,
+  rawInput: ResolveDiskInput,
+): Promise<Money | undefined> {
+  const input = ResolveDiskInputSchema.parse(rawInput);
+  const tier = pickTier(input.diskSizeGiB);
+  if (tier === undefined) return undefined;
+
+  const { prefix, productName, replication } = SKU_METADATA[input.sku];
+  const skuName = `${prefix}${tier} ${replication}`;
+
+  const filter = [
+    "serviceName eq 'Storage'",
+    `armRegionName eq '${normalizeArmRegion(input.armRegionName)}'`,
+    `productName eq '${productName}'`,
+    `skuName eq '${skuName}'`,
+  ].join(" and ");
+
+  const items = await client.query(filter);
+  const item = pickDiskItem(items, skuName);
+  if (!item) return undefined;
+
+  return {
+    amount: round2(item.unitPrice),
+    currency: item.currencyCode,
+  };
+}
+
+function pickDiskItem(
+  items: PriceItem[],
+  skuName: string,
+): PriceItem | undefined {
+  // Managed Disk meters are reported as `1/Month`; we keep the filter
+  // explicit to avoid accidentally picking a per-hour or per-IOPS entry.
+  const candidates = items.filter(
+    (it) =>
+      it.type === "Consumption" &&
+      it.unitOfMeasure === "1/Month" &&
+      it.skuName === skuName,
+  );
+  if (candidates.length === 0) return undefined;
+  return candidates.reduce((cheapest, it) =>
+    it.unitPrice < cheapest.unitPrice ? it : cheapest,
+  );
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}

package/src/azure/pricing/resolvers/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Public exports for resolvers.
+ */
+
+export type {
+  AppServicePlanOs,
+  ResolveAppServicePlanInput,
+} from "./app-service.js";
+export { resolveAppServicePlanMonthlyPrice } from "./app-service.js";
+
+export type { DiskSku, ResolveDiskInput } from "./disk.js";
+export {
+  DiskSkuSchema,
+  pickTier,
+  ResolveDiskInputSchema,
+  resolveDiskMonthlyPrice,
+} from "./disk.js";
+
+export type {
+  PublicIpAllocation,
+  PublicIpSku,
+  ResolvePublicIpInput,
+} from "./public-ip.js";
+export { resolvePublicIpMonthlyPrice } from "./public-ip.js";
+
+export type { ResolveVmInput, VmOs } from "./vm.js";
+export {
+  HOURS_PER_MONTH,
+  normalizeArmRegion,
+  resolveVmMonthlyPrice,
+} from "./vm.js";

package/src/azure/pricing/resolvers/public-ip.ts

@@ -0,0 +1,87 @@
+/**
+ * Resolver: estimated monthly cost of an Azure Public IP address.
+ *
+ * Uses the Azure Retail Prices API to look up the pay-as-you-go price for
+ * the given SKU + region + allocation method combination, then converts
+ * the hourly rate (when reported as `1 Hour`) to a monthly figure using
+ * the conventional 730-hours-per-month constant.
+ *
+ * Public IP pricing is published per `(sku, allocation)` pair. Both
+ * Standard SKU and a Static Basic SKU carry a billable hourly rate; a
+ * Dynamic Basic SKU is typically free when associated, and the lookup
+ * returns `undefined` in that case.
+ */
+
+import type { Money } from "../../../finding.js";
+import type { PricingClient } from "../client.js";
+import type { PriceItem } from "../schema.js";
+
+import { HOURS_PER_MONTH, normalizeArmRegion } from "./vm.js";
+
+export type PublicIpAllocation = "dynamic" | "static";
+export type PublicIpSku = "basic" | "standard";
+
+export type ResolvePublicIpInput = {
+  /** Allocation method (`Static` / `Dynamic`). */
+  allocation: PublicIpAllocation;
+  /** ARM region name, e.g. `westeurope`. */
+  armRegionName: string;
+  /** SKU (`Basic` / `Standard`). */
+  sku: PublicIpSku;
+};
+
+/**
+ * Resolves the estimated monthly cost for a Public IP. Returns
+ * `undefined` when no matching consumption meter is found (e.g. the
+ * combination is genuinely free).
+ */
+export async function resolvePublicIpMonthlyPrice(
+  client: PricingClient,
+  input: ResolvePublicIpInput,
+): Promise<Money | undefined> {
+  // Public IPs are billed under the "Virtual Network" service.
+  const filter = [
+    "serviceName eq 'Virtual Network'",
+    `armRegionName eq '${normalizeArmRegion(input.armRegionName)}'`,
+    `skuName eq '${capitalize(input.sku)}'`,
+  ].join(" and ");
+
+  const items = await client.query(filter);
+  const item = pickPublicIpItem(items, input.allocation);
+  if (!item) {
+    return undefined;
+  }
+
+  return {
+    amount: round2(item.unitPrice * HOURS_PER_MONTH),
+    currency: item.currencyCode,
+  };
+}
+
+function capitalize(value: string): string {
+  if (value.length === 0) return value;
+  return value[0].toUpperCase() + value.slice(1).toLowerCase();
+}
+
+function pickPublicIpItem(
+  items: PriceItem[],
+  allocation: PublicIpAllocation,
+): PriceItem | undefined {
+  const allocationToken = allocation === "static" ? "static" : "dynamic";
+  const candidates = items.filter(
+    (it) =>
+      it.type === "Consumption" &&
+      it.unitOfMeasure === "1 Hour" &&
+      (it.meterName?.toLowerCase().includes("ip address") ?? false) &&
+      (it.meterName?.toLowerCase().includes(allocationToken) ?? false),
+  );
+  if (candidates.length === 0) return undefined;
+  // Pick the cheapest entry as a conservative lower bound.
+  return candidates.reduce((cheapest, it) =>
+    it.unitPrice < cheapest.unitPrice ? it : cheapest,
+  );
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}

package/src/azure/pricing/resolvers/vm.ts

@@ -0,0 +1,125 @@
+/**
+ * Resolver: estimated monthly cost of an Azure Virtual Machine SKU.
+ *
+ * Uses the Azure Retail Prices API to look up the pay-as-you-go consumption
+ * price for the given `armSkuName` in the given region, then converts the
+ * hourly rate to a monthly figure assuming the conventional `730 hours`
+ * (365.25 * 24 / 12) for "always-on" workloads.
+ *
+ * The lookup is intentionally conservative:
+ *  - It restricts results to `type === "Consumption"` (no Reservations,
+ *    no Spot/Low Priority, no Savings Plans).
+ *  - It defaults to the Linux variant (cheapest) when the resource OS is
+ *    unknown, so the returned figure is a LOWER BOUND of the real cost.
+ *  - It returns `undefined` whenever it cannot identify a single
+ *    unambiguous price item, so callers can treat the savings estimate
+ *    as best-effort.
+ */
+
+import type { Money } from "../../../finding.js";
+import type { PricingClient } from "../client.js";
+import type { PriceItem } from "../schema.js";
+
+/**
+ * Conventional hours-per-month used across Azure cost calculators
+ * (365.25 days × 24 h / 12 months ≈ 730).
+ */
+export const HOURS_PER_MONTH = 730;
+
+export type ResolveVmInput = {
+  /** ARM region name, e.g. `westeurope`. */
+  armRegionName: string;
+  /** ARM SKU name, e.g. `Standard_B2s`. */
+  armSkuName: string;
+  /** Optional OS hint. Defaults to `linux`. */
+  os?: VmOs;
+};
+
+/**
+ * Operating system hint used to disambiguate Windows vs. Linux meters.
+ * When unset (default) the cheapest Linux variant is picked.
+ */
+export type VmOs = "linux" | "windows";
+
+/**
+ * Normalises a region string to the `armRegionName` format expected by
+ * the Retail Prices API (lowercase, no spaces). The Azure SDK sometimes
+ * returns the display name (`"West Europe"`) instead of the ARM name
+ * (`"westeurope"`); without this normalisation the OData filter would
+ * silently miss every entry.
+ */
+export function normalizeArmRegion(region: string): string {
+  return region.toLowerCase().replace(/\s+/g, "");
+}
+
+/**
+ * Resolves the estimated monthly cost for a VM SKU. Returns `undefined`
+ * if no matching consumption meter can be found.
+ */
+export async function resolveVmMonthlyPrice(
+  client: PricingClient,
+  input: ResolveVmInput,
+): Promise<Money | undefined> {
+  const filter = [
+    "serviceName eq 'Virtual Machines'",
+    `armRegionName eq '${normalizeArmRegion(input.armRegionName)}'`,
+    `armSkuName eq '${input.armSkuName}'`,
+  ].join(" and ");
+
+  const items = await client.query(filter);
+  const item = pickVmItem(items, input.os ?? "linux");
+  if (!item) {
+    return undefined;
+  }
+
+  return {
+    amount: round2(item.unitPrice * HOURS_PER_MONTH),
+    currency: item.currencyCode,
+  };
+}
+
+function isSpotOrLowPriority(item: PriceItem): boolean {
+  const sku = item.skuName?.toLowerCase() ?? "";
+  const meter = item.meterName?.toLowerCase() ?? "";
+  return (
+    sku.includes("spot") ||
+    sku.includes("low priority") ||
+    meter.includes("spot") ||
+    meter.includes("low priority")
+  );
+}
+
+function matchesOs(item: PriceItem, os: VmOs): boolean {
+  const product = item.productName?.toLowerCase() ?? "";
+  const isWindowsItem = product.includes("windows");
+  return os === "windows" ? isWindowsItem : !isWindowsItem;
+}
+
+/**
+ * Picks the most appropriate Retail Prices entry for the given OS hint.
+ *
+ * Filters out:
+ *  - non-Consumption entries (Reservations, Savings Plans, …)
+ *  - Spot / Low Priority entries (variable pricing)
+ *  - Windows entries when the hint is `linux` and vice versa
+ *
+ * Then prefers the entry with the lowest `unitPrice` to act as a
+ * conservative lower bound.
+ */
+function pickVmItem(items: PriceItem[], os: VmOs): PriceItem | undefined {
+  const candidates = items.filter(
+    (it) =>
+      it.type === "Consumption" &&
+      it.unitOfMeasure === "1 Hour" &&
+      !isSpotOrLowPriority(it) &&
+      matchesOs(it, os),
+  );
+  if (candidates.length === 0) return undefined;
+  return candidates.reduce((cheapest, it) =>
+    it.unitPrice < cheapest.unitPrice ? it : cheapest,
+  );
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}

package/src/azure/pricing/schema.ts

@@ -0,0 +1,69 @@
+/**
+ * Zod schemas for the Azure Retail Prices REST API.
+ *
+ * Endpoint: https://prices.azure.com/api/retail/prices
+ * Docs:     https://learn.microsoft.com/rest/api/cost-management/retail-prices/azure-retail-prices
+ *
+ * The API returns a flat list of `Items` (one per meter) plus an optional
+ * `NextPageLink` for pagination. Extra fields returned by Azure are tolerated,
+ * but the fields used by pricing logic are validated with narrow shapes.
+ */
+
+import { z } from "zod";
+
+const NonEmptyStringSchema = z.string().min(1);
+const PriceTypeSchema = z.enum([
+  "Consumption",
+  "DevTestConsumption",
+  "Reservation",
+]);
+const PriceValueSchema = z.number().finite().nonnegative();
+
+/**
+ * A single priced meter returned by the Retail Prices API.
+ *
+ * Notable fields:
+ * - `unitPrice`: list price per `unitOfMeasure` (e.g. "1 Hour", "1 GB/Month")
+ * - `retailPrice`: typically equals `unitPrice` but kept distinct by Azure
+ * - `armSkuName`: ARM SKU identifier (e.g. "Standard_B2s") — present for
+ *   VM/compute meters, absent for some services (Bandwidth, Support, …)
+ * - `reservationTerm`: present ONLY for Reservation meters; consumers that
+ *   want on-demand pricing must filter by `type === "Consumption"`.
+ */
+export const PriceItemSchema = z.object({
+  armRegionName: NonEmptyStringSchema.optional(),
+  armSkuName: NonEmptyStringSchema.optional(),
+  currencyCode: z.string().length(3),
+  effectiveStartDate: NonEmptyStringSchema.optional(),
+  isPrimaryMeterRegion: z.boolean().optional(),
+  location: NonEmptyStringSchema.optional(),
+  meterId: NonEmptyStringSchema.optional(),
+  meterName: NonEmptyStringSchema.optional(),
+  productId: NonEmptyStringSchema.optional(),
+  productName: NonEmptyStringSchema.optional(),
+  reservationTerm: NonEmptyStringSchema.optional(),
+  retailPrice: PriceValueSchema,
+  serviceFamily: NonEmptyStringSchema.optional(),
+  serviceId: NonEmptyStringSchema.optional(),
+  serviceName: NonEmptyStringSchema.optional(),
+  skuId: NonEmptyStringSchema.optional(),
+  skuName: NonEmptyStringSchema.optional(),
+  tierMinimumUnits: PriceValueSchema.optional(),
+  /** "Consumption" | "Reservation" | "DevTestConsumption". */
+  type: PriceTypeSchema,
+  unitOfMeasure: NonEmptyStringSchema,
+  unitPrice: PriceValueSchema,
+});
+export type PriceItem = z.infer<typeof PriceItemSchema>;
+
+/**
+ * Top-level response envelope. `Count` reflects the number of items in the
+ * current page, not the grand total.
+ */
+export const PricingResponseSchema = z.object({
+  BillingCurrency: z.string().length(3).optional(),
+  Count: z.number().int().nonnegative().optional(),
+  Items: z.array(PriceItemSchema),
+  NextPageLink: z.string().url().nullable().optional(),
+});
+export type PricingResponse = z.infer<typeof PricingResponseSchema>;

package/src/azure/pricing/test-cache-dir.ts

@@ -0,0 +1,26 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { isAbsolute, join, relative } from "node:path";
+
+const TEST_CACHE_PARENT = join(
+  process.cwd(),
+  "node_modules",
+  ".cache",
+  "dx-savemoney-tests",
+);
+
+export async function makeTestCacheDir(prefix: string): Promise<string> {
+  await mkdir(TEST_CACHE_PARENT, { recursive: true });
+  return mkdtemp(join(TEST_CACHE_PARENT, `${prefix}-`));
+}
+
+export async function removeTestCacheDir(dir: string): Promise<void> {
+  const relativePath = relative(TEST_CACHE_PARENT, dir);
+  if (
+    relativePath === "" ||
+    relativePath.startsWith("..") ||
+    isAbsolute(relativePath)
+  ) {
+    throw new Error(`Refusing to remove non-test cache directory: ${dir}`);
+  }
+  await rm(dir, { force: true, recursive: true });
+}