vibecarbon 0.1.0

package/src/lib/providers/hetzner.js

@@ -0,0 +1,755 @@
+/**
+ * Hetzner Cloud Provider
+ *
+ * Implementation of the BaseProvider interface for Hetzner Cloud.
+ * Provides server, SSH key, and firewall management through the Hetzner API.
+ *
+ * API Documentation: https://docs.hetzner.cloud/
+ */
+
+import { fetchWithRetry } from '../fetch-retry.js';
+import { BaseProvider } from './base.js';
+
+export class HetznerProvider extends BaseProvider {
+  static NAME = 'Hetzner Cloud';
+  static API_BASE = 'https://api.hetzner.cloud/v1';
+
+  static REGIONS = {
+    fsn1: 'Falkenstein, Germany',
+    nbg1: 'Nuremberg, Germany',
+    hel1: 'Helsinki, Finland',
+    ash: 'Ashburn, Virginia, USA',
+    hil: 'Hillsboro, Oregon, USA',
+  };
+
+  // Offline fallback catalog — used when the API is unreachable or no token is available.
+  // Prices and availability are approximate; live data from fetchServerTypes() takes precedence.
+  static FALLBACK_SERVER_TYPES = {
+    cx23: { vcpu: 2, ram: 4, disk: 40, price: '€4.19/mo' },
+    cx33: { vcpu: 4, ram: 8, disk: 80, price: '€7.09/mo' },
+    cx43: { vcpu: 8, ram: 16, disk: 160, price: '€13.49/mo' },
+    cx53: { vcpu: 16, ram: 32, disk: 320, price: '€27.49/mo' },
+    cx22: { vcpu: 2, ram: 4, disk: 40, price: '€3.99/mo' },
+    cx32: { vcpu: 4, ram: 8, disk: 80, price: '€6.49/mo' },
+    cx42: { vcpu: 8, ram: 16, disk: 160, price: '€11.99/mo' },
+    cx52: { vcpu: 16, ram: 32, disk: 320, price: '€22.49/mo' },
+    cpx11: { vcpu: 2, ram: 2, disk: 40, price: '€7.99/mo' },
+    cpx21: { vcpu: 3, ram: 4, disk: 80, price: '€13.99/mo' },
+    cpx22: { vcpu: 3, ram: 4, disk: 80, price: '€13.99/mo' },
+    cpx31: { vcpu: 4, ram: 8, disk: 160, price: '€25.49/mo' },
+    cpx41: { vcpu: 8, ram: 16, disk: 240, price: '€36.49/mo' },
+    cpx51: { vcpu: 16, ram: 32, disk: 360, price: '€50.49/mo' },
+    cax11: { vcpu: 2, ram: 4, disk: 40, price: '€4.49/mo' },
+    cax21: { vcpu: 4, ram: 8, disk: 80, price: '€7.99/mo' },
+    cax31: { vcpu: 8, ram: 16, disk: 160, price: '€15.99/mo' },
+    cax41: { vcpu: 16, ram: 32, disk: 320, price: '€31.49/mo' },
+    ccx13: { vcpu: 2, ram: 8, disk: 80, price: '€15.99/mo' },
+    ccx23: { vcpu: 4, ram: 16, disk: 160, price: '€31.49/mo' },
+    ccx33: { vcpu: 8, ram: 32, disk: 240, price: '€62.49/mo' },
+    ccx43: { vcpu: 16, ram: 64, disk: 360, price: '€124.99/mo' },
+    ccx53: { vcpu: 32, ram: 128, disk: 600, price: '€249.99/mo' },
+    ccx63: { vcpu: 48, ram: 192, disk: 960, price: '€374.49/mo' },
+  };
+
+  // Live catalog populated by fetchServerTypes(). Falls back to FALLBACK_SERVER_TYPES.
+  static SERVER_TYPES = { ...HetznerProvider.FALLBACK_SERVER_TYPES };
+
+  // Per-location availability populated by fetchServerTypes().
+  // Maps location name → Set of available server type names.
+  static _locationTypes = null;
+
+  static DEFAULT_TYPE = 'cpx11';
+  static HA_REGIONS = ['fsn1', 'hel1'];
+
+  // Infrastructure costs (EUR/mo, as of Apr 2026)
+  static INFRA_COSTS = {
+    floatingIp: 3.57,
+    volumePerGb: 0.052, // Hetzner CSI volumes
+    s3MinBucket: 4.49, // 250 GB Object Storage minimum
+    firewall: 0, // Free
+    network: 0, // Free (first 1 TB)
+  };
+
+  // Known PVC sizes (Gi) per service
+  static VOLUME_SIZES = {
+    base: 30, // postgres 20Gi + storage 10Gi
+    observability: 25, // prometheus 10Gi + loki 10Gi + grafana 5Gi
+    n8n: 5,
+    metabase: 1,
+    redis: 1,
+  };
+
+  static EU_REGIONS = ['fsn1', 'nbg1', 'hel1'];
+  static US_REGIONS = ['ash', 'hil'];
+
+  // Prefix-based fallback for region filtering when live data is unavailable.
+  static REGION_TYPE_PREFIXES = {
+    us: ['cpx', 'ccx'],
+    eu: ['cx', 'cpx', 'cax', 'ccx'],
+  };
+
+  /**
+   * Fetch server types and per-location pricing from the Hetzner API.
+   * Populates SERVER_TYPES with live data and caches per-location availability.
+   * Safe to call multiple times — returns cached data after the first successful fetch.
+   * @param {string} apiToken - Hetzner API token
+   * @returns {Promise<boolean>} true if live data was loaded, false on failure (fallback used)
+   */
+  static async fetchServerTypes(apiToken) {
+    if (HetznerProvider._locationTypes) return true; // already fetched
+
+    try {
+      const response = await fetchWithRetry(
+        `${HetznerProvider.API_BASE}/server_types?per_page=50`,
+        {
+          headers: { Authorization: `Bearer ${apiToken}` },
+        },
+      );
+      if (!response.ok) return false;
+
+      const data = await response.json();
+      const types = {};
+      const locationTypes = {};
+
+      for (const t of data.server_types) {
+        if (t.deprecation) continue;
+
+        // Build per-location availability from the `locations` field (actual availability),
+        // not `prices` (which includes regions where the type is priced but not placeable).
+        for (const loc of t.locations || []) {
+          const locName = loc.name || loc;
+          if (loc.deprecation) continue;
+          if (!locationTypes[locName]) locationTypes[locName] = new Set();
+          locationTypes[locName].add(t.name);
+        }
+
+        // Build per-location price map
+        const locationPrices = {};
+        for (const p of t.prices || []) {
+          const loc = p.location;
+          if (loc) {
+            locationPrices[loc] = `€${parseFloat(p.price_monthly.gross).toFixed(2)}/mo`;
+          }
+        }
+
+        // Use first available location price as the default display price
+        const firstPrice = t.prices[0];
+        const defaultMonthly = firstPrice
+          ? `€${parseFloat(firstPrice.price_monthly.gross).toFixed(2)}/mo`
+          : '';
+
+        types[t.name] = {
+          vcpu: t.cores,
+          ram: t.memory,
+          disk: t.disk,
+          price: defaultMonthly,
+          locationPrices,
+          cpuType: t.cpu_type,
+          architecture: t.architecture,
+        };
+      }
+
+      HetznerProvider.SERVER_TYPES = types;
+      HetznerProvider._locationTypes = locationTypes;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Returns region-appropriate default server types.
+   *
+   * Hetzner's SKU availability is split by geography:
+   *   - EU (fsn1/nbg1/hel1): `cx*` (Intel shared) + `cax*` (ARM) + `ccx*` (dedicated)
+   *   - US (ash/hil):        `cpx*` (AMD shared) + `cax*` (ARM)
+   *
+   * We prefer x86 shared-vCPU for cluster nodes (ARM mixes poorly with
+   * amd64-only Helm charts like Supabase). Prefer tiers in this order for
+   * each role, falling back to the first available:
+   *   - master/worker: 2 vCPU, 2–4 GB RAM
+   *   - supabase:      2–4 vCPU, 4+ GB RAM
+   */
+  static getRegionDefaults(region) {
+    const available = HetznerProvider._locationTypes?.[region];
+
+    // Preference lists — order matters. First available in the region wins.
+    const smallShared = ['cpx11', 'cx23', 'cx22']; // ~2 vCPU, 2–4 GB
+    const mediumShared = ['cx23', 'cpx21', 'cx33']; // 2–4 vCPU, 4–8 GB
+
+    const pickAvailable = (prefs, fallback) => {
+      if (available) {
+        for (const t of prefs) if (available.has(t)) return t;
+      }
+      return fallback;
+    };
+
+    if (available) {
+      return {
+        masterType: pickAvailable(smallShared, 'cpx11'),
+        supabaseType: pickAvailable(mediumShared, 'cpx21'),
+        workerType: pickAvailable(smallShared, 'cpx11'),
+      };
+    }
+
+    // Offline fallback — assume US (cpx available) since EU cx SKUs rotate
+    // faster (cx11→cx21→cx22→cx23 in five years) and are more likely to be
+    // stale in a hard-coded fallback.
+    return { masterType: 'cpx11', supabaseType: 'cpx21', workerType: 'cpx11' };
+  }
+
+  /**
+   * Returns the equivalent server type available in a target region.
+   * Maps across architectures (e.g. cax11 → cpx11 when ARM unavailable).
+   * Returns the original type if it's available, or the best match otherwise.
+   */
+  static resolveServerTypeForRegion(serverType, targetRegion) {
+    const available = HetznerProvider._locationTypes?.[targetRegion];
+
+    // If live data available, check directly
+    if (available) {
+      if (available.has(serverType)) return serverType;
+
+      // Map cax→cpx (ARM→shared x86) or cpx→cax (x86→ARM) by numeric suffix
+      const suffix = serverType.replace(/^[a-z]+/, '');
+      if (serverType.startsWith('cax')) {
+        const alt = `cpx${suffix}`;
+        if (available.has(alt)) return alt;
+      } else if (serverType.startsWith('cpx')) {
+        const alt = `cax${suffix}`;
+        if (available.has(alt)) return alt;
+      }
+
+      // Fall back to region defaults at same tier
+      const defaults = HetznerProvider.getRegionDefaults(targetRegion);
+      if (suffix.startsWith('1')) return defaults.masterType;
+      if (suffix.startsWith('2')) return defaults.supabaseType;
+      return defaults.workerType;
+    }
+
+    // Offline fallback: EU regions have ARM, US regions don't.
+    // Only map to types that exist in the fallback catalog — blindly swapping
+    // the prefix can produce invalid types (e.g. cpx22 → cax22 which doesn't exist).
+    if (HetznerProvider.US_REGIONS.includes(targetRegion) && serverType.startsWith('cax')) {
+      const alt = `cpx${serverType.replace(/^cax/, '')}`;
+      if (HetznerProvider.FALLBACK_SERVER_TYPES[alt]) return alt;
+    }
+    if (HetznerProvider.EU_REGIONS.includes(targetRegion) && serverType.startsWith('cpx')) {
+      const alt = `cax${serverType.replace(/^cpx/, '')}`;
+      if (HetznerProvider.FALLBACK_SERVER_TYPES[alt]) return alt;
+    }
+    return serverType;
+  }
+
+  /**
+   * Returns server types available in the given region.
+   * Uses live per-location data when available, otherwise falls back to prefix filtering.
+   */
+  static getServerTypesForRegion(region) {
+    const available = HetznerProvider._locationTypes?.[region];
+
+    if (available) {
+      return [...available]
+        .filter((name) => name in HetznerProvider.SERVER_TYPES)
+        .map((name) => {
+          const spec = HetznerProvider.SERVER_TYPES[name];
+          const price = spec.locationPrices?.[region] || spec.price;
+          return { name, ...spec, price };
+        })
+        .sort((a, b) => a.vcpu - b.vcpu || a.ram - b.ram);
+    }
+
+    // Offline fallback — filter by prefix
+    const prefixes = HetznerProvider.US_REGIONS.includes(region)
+      ? HetznerProvider.REGION_TYPE_PREFIXES.us
+      : HetznerProvider.REGION_TYPE_PREFIXES.eu;
+    return Object.entries(HetznerProvider.SERVER_TYPES)
+      .filter(([name]) => prefixes.some((prefix) => name.startsWith(prefix)))
+      .map(([name, info]) => ({ name, ...info }));
+  }
+
+  /**
+   * Returns the monthly price for a server type in a specific location.
+   * Only available after fetchServerTypes() — returns null otherwise.
+   */
+  static getPrice(serverType, location) {
+    const spec = HetznerProvider.SERVER_TYPES[serverType];
+    if (!spec) return null;
+    return (location && spec.locationPrices?.[location]) || spec.price || null;
+  }
+
+  /**
+   * Create a new Hetzner server
+   * @param {object} config - Server configuration
+   * @returns {Promise<{id: number, server: object}>}
+   */
+  async createServer(config) {
+    const {
+      name,
+      serverType,
+      region,
+      sshKeyId,
+      sshKeys,
+      environment,
+      image,
+      firewalls,
+      labels,
+      userData,
+    } = config;
+
+    const body = {
+      name,
+      server_type: serverType,
+      location: region,
+      image: image || 'docker-ce',
+      ssh_keys: sshKeys || (sshKeyId ? [sshKeyId] : []),
+      public_net: {
+        enable_ipv4: true,
+        enable_ipv6: true,
+      },
+      labels: labels || {
+        'managed-by': 'vibecarbon',
+        environment: environment || 'default',
+      },
+    };
+    if (firewalls?.length) {
+      body.firewalls = firewalls.map((id) => ({ firewall: id }));
+    }
+    // user_data runs at boot time via cloud-init. Hetzner accepts either a
+    // raw shell script or a #cloud-config YAML document up to 32KB. We pass
+    // whatever string the caller supplies; compose deploy uses a cloud-config
+    // YAML that front-loads ufw + unattended-upgrades installs so setupServer
+    // can shrink to a marker-file probe.
+    if (userData) {
+      body.user_data = userData;
+    }
+
+    // Retry on transient resource_limit_exceeded — observed when several
+    // scenarios concurrently provision in a quota-tight project (e.g.
+    // matrix-mode e2e + W1.5a parallel compose-ha scale doubled
+    // the in-flight Primary IP allocations and tripped Hetzner's project
+    // quota at iter-reliab 2026-05-01T14:13Z). Old servers being torn
+    // down free their Primary IPs within 30-90s, so backing off and
+    // retrying tends to succeed without operator intervention. If the
+    // quota is genuinely too low for the workload, we still surface the
+    // error after exhausting attempts.
+    const RESOURCE_LIMIT_DELAYS_MS = [15_000, 45_000, 90_000];
+    let response;
+    let attemptError = null;
+    for (let attempt = 0; attempt <= RESOURCE_LIMIT_DELAYS_MS.length; attempt++) {
+      response = await this.apiRequest('/servers', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      });
+      if (response.ok) break;
+      // Body is read at most once per attempt; reuse `attemptError` rather
+      // than `response.clone()` so the WHATWG fetch shim and the test mock
+      // (which doesn't implement clone()) both work.
+      attemptError = await response.json();
+      const peekCode = attemptError.error?.code || '';
+      const peekMessage = attemptError.error?.message || '';
+      const isResourceLimit =
+        peekCode === 'resource_limit_exceeded' || /resource_limit_exceeded/i.test(peekMessage);
+      if (!isResourceLimit || attempt === RESOURCE_LIMIT_DELAYS_MS.length) {
+        break;
+      }
+      // Log to stderr so operator (or post-run analysis) can see we're
+      // queueing rather than dying on first quota bump.
+      console.warn(
+        `[hetzner] createServer(${name}): quota busy (${peekMessage}); ` +
+          `retrying in ${RESOURCE_LIMIT_DELAYS_MS[attempt] / 1000}s ` +
+          `(attempt ${attempt + 1}/${RESOURCE_LIMIT_DELAYS_MS.length + 1})`,
+      );
+      await new Promise((r) => setTimeout(r, RESOURCE_LIMIT_DELAYS_MS[attempt]));
+    }
+
+    if (!response.ok) {
+      const error = attemptError ?? { error: { message: 'Unknown error', code: 'unknown' } };
+      const message = error.error?.message || 'Unknown error';
+      const code = error.error?.code || 'unknown';
+
+      let hint = '';
+      if (code === 'invalid_input' && message.includes('unsupported location')) {
+        hint = `\nHint: Server type "${serverType}" is not available in region "${region}". Try a different server type or region.`;
+      } else if (code === 'uniqueness_error') {
+        // Recover: look up the existing server by name and return it
+        const listResponse = await this.apiRequest(`/servers?name=${encodeURIComponent(name)}`);
+        if (listResponse.ok) {
+          const listData = await listResponse.json();
+          const existing = listData.servers?.find((s) => s.name === name);
+          if (existing) {
+            return { id: existing.id, server: existing, reused: true };
+          }
+        }
+        hint = `\nHint: A server with this name already exists. Use --destroy first or choose a different environment name.`;
+      } else if (code === 'unauthorized') {
+        hint = '\nHint: Check that your API token is valid and has Read & Write permissions.';
+      } else if (code === 'resource_limit_exceeded') {
+        hint =
+          '\nHint: Project quota exhausted even after retries. Either wait for in-flight tear-downs to free resources, or raise the project quota in the Hetzner Console (Resources → Limits).';
+      }
+
+      throw new Error(`Hetzner API error: ${message} (${code})${hint}`);
+    }
+
+    const data = await response.json();
+    return { id: data.server.id, server: data.server };
+  }
+
+  /**
+   * Delete a server
+   * @param {number} serverId - Server ID
+   */
+  async deleteServer(serverId) {
+    const response = await this.apiRequest(`/servers/${serverId}`, {
+      method: 'DELETE',
+    });
+
+    if (!response.ok && response.status !== 404) {
+      const error = await response.json();
+      throw new Error(`Failed to delete server: ${error.error?.message || 'Unknown error'}`);
+    }
+  }
+
+  /**
+   * Get server details
+   * @param {number} serverId - Server ID
+   * @returns {Promise<object>}
+   */
+  async getServer(serverId) {
+    const response = await this.apiRequest(`/servers/${serverId}`);
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(`Failed to get server: ${error.error?.message || 'Unknown error'}`);
+    }
+
+    const data = await response.json();
+    return data.server;
+  }
+
+  /**
+   * Wait for a server to become ready
+   * @param {number} serverId - Server ID
+   * @param {number} [timeout=300000] - Timeout in ms (default 5 minutes)
+   * @returns {Promise<object>}
+   */
+  async waitForServer(serverId, timeout = 300000) {
+    const startTime = Date.now();
+    const pollInterval = 5000;
+
+    while (Date.now() - startTime < timeout) {
+      try {
+        const response = await this.apiRequest(`/servers/${serverId}`);
+        const { server } = await response.json();
+
+        if (server.status === 'running') {
+          return server;
+        }
+      } catch (error) {
+        // Network errors - continue retrying
+        if (Date.now() - startTime >= timeout - pollInterval) {
+          throw new Error(`Failed to check server status: ${error.message}`);
+        }
+      }
+
+      await new Promise((r) => setTimeout(r, pollInterval));
+    }
+
+    throw new Error('Server creation timed out');
+  }
+
+  /**
+   * Create or update an SSH key
+   * @param {string} name - SSH key name
+   * @param {string} publicKey - Public key content
+   * @returns {Promise<number>} SSH key ID
+   */
+  async createSSHKey(name, publicKey) {
+    // Hetzner paginates /ssh_keys at 25 entries/page by default. Long-lived
+    // Hetzner projects accumulate dozens of keys; with the default pagination
+    // the dedup scan below would silently miss keys on pages 2+, and we'd hit
+    // the very 409/"not unique" error the dedup is meant to prevent. Ask for
+    // the max allowed page size (50) and still walk pagination defensively.
+    const ssh_keys = [];
+    let page = 1;
+    for (let guard = 0; guard < 20; guard++) {
+      const resp = await this.apiRequest(`/ssh_keys?per_page=50&page=${page}`);
+      const body = await resp.json();
+      if (Array.isArray(body.ssh_keys)) ssh_keys.push(...body.ssh_keys);
+      const next = body.meta?.pagination?.next_page;
+      if (!next) break;
+      page = next;
+    }
+
+    const newKeyPart = publicKey.split(' ').slice(0, 2).join(' ');
+
+    // 1. If a key with the same name already exists, prefer it (by-name lookup).
+    const existingByName = ssh_keys.find((k) => k.name === name);
+    if (existingByName) {
+      const existingKeyPart = existingByName.public_key.split(' ').slice(0, 2).join(' ');
+      if (existingKeyPart === newKeyPart) {
+        return existingByName.id;
+      }
+      // Same name but different key — delete so we can recreate.
+      await this.apiRequest(`/ssh_keys/${existingByName.id}`, { method: 'DELETE' });
+    }
+
+    // 2. Hetzner also rejects `POST /ssh_keys` with 409/"not unique" if the
+    // public-key bytes are already registered under a DIFFERENT name (common
+    // in e2e test reruns that share a single dev key pair). Scan the
+    // list a second time by key content and reuse if found.
+    const existingByKey = ssh_keys.find((k) => {
+      const kPart = k.public_key.split(' ').slice(0, 2).join(' ');
+      return kPart === newKeyPart;
+    });
+    if (existingByKey) {
+      return existingByKey.id;
+    }
+
+    // 3. Truly new — create it. Always tag with `managed-by=vibecarbon` so
+    // post-run sweeps that filter by label_selector reap it on cleanup.
+    // Without the label, leaked keys only show up in the name-prefix
+    // preflight scan and silently block the next e2e run.
+    const createResponse = await this.apiRequest('/ssh_keys', {
+      method: 'POST',
+      body: JSON.stringify({
+        name,
+        public_key: publicKey,
+        labels: { 'managed-by': 'vibecarbon' },
+      }),
+    });
+
+    if (!createResponse.ok) {
+      const error = await createResponse.json();
+      throw new Error(`Failed to create SSH key: ${error.error?.message || 'Unknown error'}`);
+    }
+
+    const { ssh_key } = await createResponse.json();
+    return ssh_key.id;
+  }
+
+  /**
+   * Delete an SSH key
+   * @param {number} keyId - SSH key ID
+   */
+  async deleteSSHKey(keyId) {
+    const response = await this.apiRequest(`/ssh_keys/${keyId}`, {
+      method: 'DELETE',
+    });
+
+    if (!response.ok && response.status !== 404) {
+      const error = await response.json();
+      throw new Error(`Failed to delete SSH key: ${error.error?.message || 'Unknown error'}`);
+    }
+  }
+
+  /**
+   * Create a firewall and attach to server
+   * @param {string} name - Firewall name
+   * @param {number} serverId - Server ID
+   * @param {number[]} [ports=[22, 80, 443, 3000]] - Ports to open
+   * @returns {Promise<object>}
+   */
+  async createFirewall(name, serverId, ports = [22, 80, 443, 3000]) {
+    // Reuse existing firewall with the same name
+    const allFirewalls = await this.listFirewalls();
+    const existing = allFirewalls.find((fw) => fw.name === name);
+    if (existing) {
+      return { firewall: existing };
+    }
+
+    const rules = ports.map((port) => ({
+      direction: 'in',
+      protocol: 'tcp',
+      port: String(port),
+      source_ips: ['0.0.0.0/0', '::/0'],
+    }));
+
+    const body = { name, rules };
+    if (serverId) {
+      body.apply_to = [{ type: 'server', server: { id: serverId } }];
+    }
+
+    const response = await this.apiRequest('/firewalls', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(`Failed to create firewall: ${error.error?.message || 'Unknown error'}`);
+    }
+
+    return response.json();
+  }
+
+  /**
+   * Delete a firewall
+   * @param {number} firewallId - Firewall ID
+   */
+  async deleteFirewall(firewallId) {
+    const response = await this.apiRequest(`/firewalls/${firewallId}`, {
+      method: 'DELETE',
+    });
+
+    if (!response.ok && response.status !== 404) {
+      const error = await response.json();
+      throw new Error(`Failed to delete firewall: ${error.error?.message || 'Unknown error'}`);
+    }
+  }
+
+  /**
+   * List servers with optional label filter
+   * @param {object} labels - Labels to filter by
+   * @returns {Promise<object[]>}
+   */
+  async listServers(labels = {}) {
+    let url = '/servers';
+
+    // Build label selector query
+    if (Object.keys(labels).length > 0) {
+      const selector = Object.entries(labels)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(',');
+      url += `?label_selector=${encodeURIComponent(selector)}`;
+    }
+
+    const response = await this.apiRequest(url);
+    const data = await response.json();
+    return data.servers || [];
+  }
+
+  /**
+   * List firewalls with optional label filter
+   * @param {object} labels - Labels to filter by
+   * @returns {Promise<object[]>}
+   */
+  async listFirewalls(labels = {}) {
+    let url = '/firewalls';
+
+    if (Object.keys(labels).length > 0) {
+      const selector = Object.entries(labels)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(',');
+      url += `?label_selector=${encodeURIComponent(selector)}`;
+    }
+
+    const response = await this.apiRequest(url);
+    const data = await response.json();
+    return data.firewalls || [];
+  }
+
+  /**
+   * List all SSH keys
+   * @returns {Promise<object[]>}
+   */
+  async listSSHKeys() {
+    const response = await this.apiRequest('/ssh_keys');
+    const data = await response.json();
+    return data.ssh_keys || [];
+  }
+
+  /**
+   * Power off a server
+   * @param {number} serverId - Server ID
+   * @returns {Promise<object>} Action object
+   */
+  async poweroffServer(serverId) {
+    const response = await this.apiRequest(`/servers/${serverId}/actions/poweroff`, {
+      method: 'POST',
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(`Failed to power off server: ${error.error?.message || 'Unknown error'}`);
+    }
+
+    const data = await response.json();
+    return data.action;
+  }
+
+  /**
+   * Power on a server
+   * @param {number} serverId - Server ID
+   * @returns {Promise<object>} Action object
+   */
+  async poweronServer(serverId) {
+    const response = await this.apiRequest(`/servers/${serverId}/actions/poweron`, {
+      method: 'POST',
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(`Failed to power on server: ${error.error?.message || 'Unknown error'}`);
+    }
+
+    const data = await response.json();
+    return data.action;
+  }
+
+  /**
+   * Change the type of a server (server must be powered off)
+   * @param {number} serverId - Server ID
+   * @param {string} serverType - New server type name (e.g. 'cpx31')
+   * @param {boolean} [upgradeDisk=true] - Whether to upgrade disk size (irreversible)
+   * @returns {Promise<object>} Action object
+   */
+  async changeServerType(serverId, serverType, upgradeDisk = true) {
+    const response = await this.apiRequest(`/servers/${serverId}/actions/change_type`, {
+      method: 'POST',
+      body: JSON.stringify({ server_type: serverType, upgrade_disk: upgradeDisk }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json();
+      throw new Error(`Failed to change server type: ${error.error?.message || 'Unknown error'}`);
+    }
+
+    const data = await response.json();
+    return data.action;
+  }
+
+  /**
+   * Wait for an action to complete
+   * @param {number} actionId - Action ID
+   * @param {number} [timeout=300000] - Timeout in ms (default 5 minutes)
+   * @returns {Promise<object>} Completed action object
+   */
+  async waitForAction(actionId, timeout = 300000) {
+    const startTime = Date.now();
+    const pollInterval = 5000;
+
+    while (Date.now() - startTime < timeout) {
+      const response = await this.apiRequest(`/actions/${actionId}`);
+      const { action } = await response.json();
+
+      if (action.status === 'success') return action;
+      if (action.status === 'error') {
+        throw new Error(`Action failed: ${action.error?.message || 'Unknown error'}`);
+      }
+
+      await new Promise((r) => setTimeout(r, pollInterval));
+    }
+
+    throw new Error('Action timed out');
+  }
+
+  /**
+   * Get public IPv4 address of a server
+   * @param {object} server - Server object
+   * @returns {string|null}
+   */
+  static getPublicIP(server) {
+    return server?.public_net?.ipv4?.ip || null;
+  }
+
+  /**
+   * Get public IPv6 address of a server
+   * @param {object} server - Server object
+   * @returns {string|null}
+   */
+  static getPublicIPv6(server) {
+    return server?.public_net?.ipv6?.ip || null;
+  }
+}