@ebowwa/hetzner 0.1.0

package/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Hetzner Cloud API client
+ * For server-side use only (requires API token)
+ *
+ * TODO:
+ * - Certificate actions: https://docs.hetzner.cloud/reference/cloud#certificate-actions
+ * - DNS operations
+ */
+
+// Core exports
+export { HetznerClient } from "./client.js";
+export { ServerOperations } from "./servers.js";
+export { ActionOperations } from "./actions.js";
+export { SSHKeyOperations } from "./ssh-keys.js";
+
+// Auth
+export { getTokenFromCLI, isAuthenticated, resolveApiToken } from "./auth.js";
+
+// Config
+export { HETZNER_API_BASE } from "./config.js";
+
+// Types
+export * from "./types.js";
+
+// Schemas
+export * from "./schemas.js";
+
+// Errors
+export * from "./errors.js";
+
+// Action utilities
+export {
+  waitForAction,
+  waitForMultipleActions,
+  waitForMultipleActionsWithLimit,
+  batchCheckActions,
+  getActionTimeout,
+  isActionRunning,
+  isActionSuccess,
+  isActionError,
+  formatActionProgress,
+  getActionDescription,
+  getPollInterval,
+  getAdaptivePollInterval,
+  waitForActionAdaptive,
+  parseRateLimitHeaders,
+  isRateLimitLow,
+  formatRateLimitStatus,
+  waitForRateLimitReset,
+  createProgressLogger,
+  ACTION_TIMEOUTS,
+} from "./actions.js";
+
+// Bootstrap security modules
+export * from "./bootstrap/index.js";

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ebowwa/hetzner",
+  "version": "0.1.0",
+  "description": "Hetzner Cloud API client - servers, volumes, SSH keys, actions, pricing",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "default": "./index.js"
+    },
+    "./client": {
+      "types": "./client.ts",
+      "default": "./client.js"
+    },
+    "./types": {
+      "types": "./types.ts",
+      "default": "./types.js"
+    },
+    "./schemas": {
+      "types": "./schemas.ts",
+      "default": "./schemas.js"
+    },
+    "./bootstrap": {
+      "types": "./bootstrap/index.ts",
+      "default": "./bootstrap/index.js"
+    }
+  },
+  "keywords": [
+    "hetzner",
+    "cloud",
+    "vps",
+    "api",
+    "servers",
+    "volumes",
+    "ssh"
+  ],
+  "author": "Ebowwa Labs <labs@ebowwa.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/ebowwa/codespaces/tree/main/packages/src/hetzner#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ebowwa/codespaces.git",
+    "directory": "packages/src/hetzner"
+  },
+  "bugs": {
+    "url": "https://github.com/ebowwa/codespaces/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}

package/pricing.js

@@ -0,0 +1,284 @@
+/**
+ * Hetzner pricing operations - fetch server types, locations, and calculate costs
+ */
+import { z } from "zod";
+import { HetznerListServerTypesResponseSchema, HetznerListLocationsResponseSchema, HetznerListDatacentersResponseSchema, } from "./schemas.js";
+/**
+ * Default fallback price for unknown server types (EUR/month)
+ * Conservative estimate based on Hetzner's smallest standard server
+ */
+const DEFAULT_FALLBACK_PRICE_MONTHLY = 5.0;
+/**
+ * Hours per month for hourly cost calculation
+ * Using 730 hours (average month: 365.25 days * 24 hours / 12 months)
+ */
+const HOURS_PER_MONTH = 730;
+// ============================================================================
+// Zod Schemas for Cost Calculation
+// ============================================================================
+/**
+ * Schema for server type price entry
+ */
+export const ServerTypePriceSchema = z.object({
+    serverType: z.string(),
+    priceMonthly: z.number().nonnegative(),
+    priceHourly: z.number().nonnegative(),
+    deprecated: z.boolean().optional().default(false),
+});
+/**
+ * Schema for environment cost entry
+ */
+export const EnvironmentCostSchema = z.object({
+    environmentId: z.string(),
+    environmentName: z.string(),
+    serverType: z.string(),
+    isRunning: z.boolean(),
+    costMonthly: z.number().nonnegative(),
+    costHourly: z.number().nonnegative(),
+    priceInfo: ServerTypePriceSchema.optional(),
+});
+/**
+ * Schema for cost calculation result
+ */
+export const CostCalculationResultSchema = z.object({
+    totalMonthly: z.number().nonnegative(),
+    totalHourly: z.number().nonnegative(),
+    runningEnvironmentCount: z.number().nonnegative().int(),
+    stoppedEnvironmentCount: z.number().nonnegative().int(),
+    unknownServerTypeCount: z.number().nonnegative().int(),
+    breakdown: z.array(EnvironmentCostSchema),
+    priceMap: z.custom(),
+});
+// ============================================================================
+// Cost Calculation Utilities
+// ============================================================================
+/**
+ * Parse Hetzner price string to number (EUR)
+ * Hetzner returns prices as strings in gross format (e.g., "5.3400" for 5.34 EUR)
+ *
+ * @param priceString - Price string from Hetzner API (gross field)
+ * @returns Price in EUR as number
+ */
+export function parseHetznerPrice(priceString) {
+    const parsed = parseFloat(priceString);
+    if (isNaN(parsed)) {
+        console.warn(`Failed to parse Hetzner price string: ${priceString}`);
+        return 0;
+    }
+    return parsed;
+}
+/**
+ * Extract pricing information from a Hetzner server type
+ * Uses the first price entry (location-agnostic pricing)
+ *
+ * @param serverType - Hetzner server type object
+ * @returns Server type price info or undefined if pricing unavailable
+ */
+export function extractServerTypePrice(serverType) {
+    if (!serverType.prices || serverType.prices.length === 0) {
+        console.warn(`Server type ${serverType.name} has no pricing information`);
+        return undefined;
+    }
+    // Use first price entry (Hetzner API returns location-agnostic pricing first)
+    const priceEntry = serverType.prices[0];
+    const priceMonthly = parseHetznerPrice(priceEntry.price_monthly.gross);
+    const priceHourly = parseHetznerPrice(priceEntry.price_hourly.gross);
+    return {
+        serverType: serverType.name,
+        priceMonthly,
+        priceHourly,
+        deprecated: serverType.deprecated ?? false,
+    };
+}
+/**
+ * Build a price lookup map from server types
+ *
+ * @param serverTypes - Array of Hetzner server types
+ * @returns Map of server type name to price info
+ */
+export function buildPriceMap(serverTypes) {
+    const priceMap = new Map();
+    for (const serverType of serverTypes) {
+        const priceInfo = extractServerTypePrice(serverType);
+        if (priceInfo) {
+            priceMap.set(serverType.name, priceInfo);
+        }
+    }
+    return priceMap;
+}
+/**
+ * Get the monthly price for a server type from the price map
+ * Returns fallback price for unknown/deprecated types
+ *
+ * @param serverTypeName - Name of the server type
+ * @param priceMap - Price lookup map
+ * @param fallbackPrice - Fallback price for unknown types (default: 5.0 EUR)
+ * @returns Monthly price in EUR
+ */
+export function getServerTypeMonthlyPrice(serverTypeName, priceMap, fallbackPrice = DEFAULT_FALLBACK_PRICE_MONTHLY) {
+    const priceInfo = priceMap.get(serverTypeName);
+    return priceInfo?.priceMonthly ?? fallbackPrice;
+}
+/**
+ * Calculate hourly price from monthly price
+ * Uses standard 730 hours per month
+ *
+ * @param monthlyPrice - Monthly price in EUR
+ * @returns Hourly price in EUR
+ */
+export function calculateHourlyFromMonthly(monthlyPrice) {
+    return monthlyPrice / HOURS_PER_MONTH;
+}
+// ============================================================================
+// Main Cost Calculation Function
+// ============================================================================
+/**
+ * Calculate total costs for a list of environments
+ *
+ * This function:
+ * - Only includes environments with "running" status
+ * - Handles missing/deprecated server types with fallback pricing
+ * - Returns detailed breakdown and aggregated totals
+ *
+ * @param environments - Array of environment objects
+ * @param serverTypes - Array of Hetzner server types with pricing
+ * @param options - Optional configuration
+ * @returns Cost calculation result with totals and breakdown
+ */
+export function calculateCosts(environments, serverTypes, options = {}) {
+    const { fallbackPrice = DEFAULT_FALLBACK_PRICE_MONTHLY, includeStopped = false } = options;
+    // Build price lookup map
+    const priceMap = buildPriceMap(serverTypes);
+    // Calculate costs for each environment
+    const breakdown = [];
+    let totalMonthly = 0;
+    let runningCount = 0;
+    let stoppedCount = 0;
+    let unknownTypeCount = 0;
+    for (const env of environments) {
+        const isRunning = env.status === "running";
+        const priceInfo = priceMap.get(env.serverType);
+        const isUnknownType = !priceInfo;
+        // Count environments by status
+        if (isRunning) {
+            runningCount++;
+        }
+        else {
+            stoppedCount++;
+        }
+        // Count unknown server types (only for running environments)
+        if (isRunning && isUnknownType) {
+            unknownTypeCount++;
+        }
+        // Get price (use fallback for unknown types, or 0 for stopped environments)
+        const monthlyPrice = isRunning
+            ? (priceInfo?.priceMonthly ?? fallbackPrice)
+            : 0;
+        const hourlyPrice = isRunning
+            ? (priceInfo?.priceHourly ?? calculateHourlyFromMonthly(fallbackPrice))
+            : 0;
+        // Add to totals (only running environments)
+        if (isRunning) {
+            totalMonthly += monthlyPrice;
+        }
+        // Include in breakdown if running or if includeStopped is true
+        if (isRunning || includeStopped) {
+            breakdown.push({
+                environmentId: env.id,
+                environmentName: env.name,
+                serverType: env.serverType,
+                isRunning,
+                costMonthly: monthlyPrice,
+                costHourly: hourlyPrice,
+                priceInfo: priceInfo,
+            });
+        }
+    }
+    // Calculate total hourly from monthly total
+    const totalHourly = calculateHourlyFromMonthly(totalMonthly);
+    return {
+        totalMonthly,
+        totalHourly,
+        runningEnvironmentCount: runningCount,
+        stoppedEnvironmentCount: stoppedCount,
+        unknownServerTypeCount: unknownTypeCount,
+        breakdown,
+        priceMap,
+    };
+}
+// ============================================================================
+// Pricing Operations Class
+// ============================================================================
+export class PricingOperations {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * List all server types
+     */
+    async listServerTypes() {
+        const response = await this.client.request("/server_types");
+        // Validate response with Zod
+        const validated = HetznerListServerTypesResponseSchema.safeParse(response);
+        if (!validated.success) {
+            console.warn('Hetzner list server types validation warning:', validated.error.issues);
+            return response.server_types; // Return unvalidated data for backward compatibility
+        }
+        return validated.data.server_types;
+    }
+    /**
+     * Get a specific server type by name
+     */
+    async getServerType(name) {
+        const types = await this.listServerTypes();
+        return types.find(t => t.name === name);
+    }
+    /**
+     * List all locations
+     */
+    async listLocations() {
+        const response = await this.client.request("/locations");
+        // Validate response with Zod
+        const validated = HetznerListLocationsResponseSchema.safeParse(response);
+        if (!validated.success) {
+            console.warn('Hetzner list locations validation warning:', validated.error.issues);
+            return response.locations; // Return unvalidated data for backward compatibility
+        }
+        return validated.data.locations;
+    }
+    /**
+     * Get a specific location by name
+     */
+    async getLocation(name) {
+        const locations = await this.listLocations();
+        return locations.find(l => l.name === name);
+    }
+    /**
+     * List all datacenters
+     */
+    async listDatacenters() {
+        const response = await this.client.request("/datacenters");
+        // Validate response with Zod
+        const validated = HetznerListDatacentersResponseSchema.safeParse(response);
+        if (!validated.success) {
+            console.warn('Hetzner list datacenters validation warning:', validated.error.issues);
+            return response.datacenters; // Return unvalidated data for backward compatibility
+        }
+        return validated.data.datacenters;
+    }
+    /**
+     * Calculate costs for environments using current Hetzner pricing
+     *
+     * Convenience method that fetches server types and calculates costs in one call
+     *
+     * @param environments - Array of environment objects
+     * @param options - Optional configuration for cost calculation
+     * @returns Cost calculation result
+     */
+    async calculateEnvironmentCosts(environments, options) {
+        const serverTypes = await this.listServerTypes();
+        return calculateCosts(environments, serverTypes, options);
+    }
+}
+//# sourceMappingURL=pricing.js.map