@nilovonjs/hcloud-js 1.0.0

package/src/apis/volumes/types.ts

@@ -0,0 +1,197 @@
+/**
+ * Types for Hetzner Cloud Volumes API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  listVolumesResponseSchema,
+  createVolumeRequestSchema,
+  createVolumeResponseSchema,
+  getVolumeResponseSchema,
+  updateVolumeRequestSchema,
+  updateVolumeResponseSchema,
+  deleteVolumeResponseSchema,
+  listVolumeActionsResponseSchema,
+  getVolumeActionResponseSchema,
+  attachVolumeToServerRequestSchema,
+  attachVolumeToServerResponseSchema,
+  detachVolumeRequestSchema,
+  detachVolumeResponseSchema,
+  resizeVolumeRequestSchema,
+  resizeVolumeResponseSchema,
+  changeVolumeProtectionRequestSchema,
+  changeVolumeProtectionResponseSchema,
+  volumeSchema,
+  volumeStatusSchema,
+  volumeProtectionSchema,
+} from "../../apis/volumes/schemas";
+import type { z } from "zod";
+
+/**
+ * Volume status
+ */
+export type VolumeStatus = z.infer<typeof volumeStatusSchema>;
+
+/**
+ * Volume protection
+ */
+export type VolumeProtection = z.infer<typeof volumeProtectionSchema>;
+
+/**
+ * Volume
+ */
+export type Volume = z.infer<typeof volumeSchema>;
+
+/**
+ * List Volumes query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-list-volumes
+ */
+export interface ListVolumesParams {
+  /**
+   * Can be used to filter resources by their name. The response will only contain the resources matching the specified name.
+   */
+  name?: string;
+  /**
+   * Can be used multiple times. Choices: id, id:asc, id:desc, name, name:asc, name:desc, created, created:asc, created:desc
+   * @see https://docs.hetzner.cloud/reference/cloud#sorting
+   */
+  sort?: string | string[];
+  /**
+   * Can be used to filter resources by labels. The response will only contain resources matching the label selector.
+   */
+  label_selector?: string;
+  /**
+   * Page number to return. For more information, see [Pagination](https://docs.hetzner.cloud/reference/cloud#pagination).
+   */
+  page?: number;
+  /**
+   * Maximum number of entries returned per page. For more information, see [Pagination](https://docs.hetzner.cloud/reference/cloud#pagination).
+   */
+  per_page?: number;
+}
+
+/**
+ * List Volumes response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-list-volumes
+ */
+export type ListVolumesResponse = z.infer<typeof listVolumesResponseSchema>;
+
+/**
+ * Create Volume parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-create-a-volume
+ */
+export type CreateVolumeParams = z.infer<typeof createVolumeRequestSchema>;
+
+/**
+ * Create Volume response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-create-a-volume
+ */
+export type CreateVolumeResponse = z.infer<typeof createVolumeResponseSchema>;
+
+/**
+ * Get Volume response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-get-a-volume
+ */
+export type GetVolumeResponse = z.infer<typeof getVolumeResponseSchema>;
+
+/**
+ * Update Volume parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-update-a-volume
+ */
+export type UpdateVolumeParams = z.infer<typeof updateVolumeRequestSchema>;
+
+/**
+ * Update Volume response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-update-a-volume
+ */
+export type UpdateVolumeResponse = z.infer<typeof updateVolumeResponseSchema>;
+
+/**
+ * Delete Volume response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-delete-a-volume
+ */
+export type DeleteVolumeResponse = z.infer<typeof deleteVolumeResponseSchema>;
+
+/**
+ * List Volume Actions query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-list-actions-for-a-volume
+ */
+export interface ListVolumeActionsParams {
+  /**
+   * Can be used multiple times. Choices: id, id:asc, id:desc, command, command:asc, command:desc, status, status:asc, status:desc, progress, progress:asc, progress:desc, started, started:asc, started:desc, finished, finished:asc, finished:desc
+   * @see https://docs.hetzner.cloud/reference/cloud#sorting
+   */
+  sort?: string | string[];
+  /**
+   * Can be used to filter Actions by status. The response will only contain Actions matching the status.
+   */
+  status?: string | string[];
+  /**
+   * Page number to return. For more information, see [Pagination](https://docs.hetzner.cloud/reference/cloud#pagination).
+   */
+  page?: number;
+  /**
+   * Maximum number of entries returned per page. For more information, see [Pagination](https://docs.hetzner.cloud/reference/cloud#pagination).
+   */
+  per_page?: number;
+}
+
+/**
+ * List Volume Actions response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-list-actions-for-a-volume
+ */
+export type ListVolumeActionsResponse = z.infer<typeof listVolumeActionsResponseSchema>;
+
+/**
+ * Get Volume Action response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-get-an-action-for-a-volume
+ */
+export type GetVolumeActionResponse = z.infer<typeof getVolumeActionResponseSchema>;
+
+/**
+ * Attach Volume to Server parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-attach-volume-to-a-server
+ */
+export type AttachVolumeToServerParams = z.infer<typeof attachVolumeToServerRequestSchema>;
+
+/**
+ * Attach Volume to Server response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-attach-volume-to-a-server
+ */
+export type AttachVolumeToServerResponse = z.infer<typeof attachVolumeToServerResponseSchema>;
+
+/**
+ * Detach Volume response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-detach-volume
+ */
+export type DetachVolumeResponse = z.infer<typeof detachVolumeResponseSchema>;
+
+/**
+ * Resize Volume parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-resize-volume
+ */
+export type ResizeVolumeParams = z.infer<typeof resizeVolumeRequestSchema>;
+
+/**
+ * Resize Volume response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-resize-volume
+ */
+export type ResizeVolumeResponse = z.infer<typeof resizeVolumeResponseSchema>;
+
+/**
+ * Change Volume Protection parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-change-volume-protection
+ */
+export type ChangeVolumeProtectionParams = z.infer<
+  typeof changeVolumeProtectionRequestSchema
+>;
+
+/**
+ * Change Volume Protection response
+ * @see https://docs.hetzner.cloud/reference/cloud#volumes-change-volume-protection
+ */
+export type ChangeVolumeProtectionResponse = z.infer<
+  typeof changeVolumeProtectionResponseSchema
+>;

package/src/auth/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Authentication for Hetzner Cloud API
+ * @see https://docs.hetzner.cloud/reference/cloud#authentication
+ */
+
+/**
+ * Creates the Authorization header with Bearer token
+ * for Hetzner Cloud API requests.
+ *
+ * The API uses Bearer token authentication. Every request must include
+ * the Authorization header with your API token.
+ *
+ * @param token - Hetzner Cloud API token
+ * @returns Authorization header object
+ * @throws {Error} If token is not provided
+ * @see https://docs.hetzner.cloud/reference/cloud#authentication
+ */
+export function createAuthHeader(token: string): { Authorization: string } {
+  if (!token || token.trim().length === 0) {
+    throw new Error("API token is required for Hetzner Cloud API authentication");
+  }
+
+  return {
+    Authorization: `Bearer ${token}`,
+  };
+}

package/src/base/index.ts

@@ -0,0 +1,10 @@
+/**
+ * @deprecated Use exports from root level instead
+ * This file is kept for backward compatibility but will be removed in a future version.
+ */
+
+export * from "../client/index";
+export * from "../errors/index";
+export * from "../types/index";
+export * from "../config/index";
+export * from "../auth/index";

package/src/client/index.ts

@@ -0,0 +1,388 @@
+/**
+ * Hetzner Cloud API Client
+ * @see https://docs.hetzner.cloud/reference/cloud
+ */
+
+import type { RequestOptions } from "../types/index";  
+import type { ClientOptions } from "../config/index";
+import { HCLOUD_API_BASE_URL, DEFAULT_TIMEOUT_MS } from "../config/index";
+import { createAuthHeader } from "../auth/index";
+import { HCloudError } from "../errors/index";
+import type { ApiErrorResponse } from "../types/index";
+import { ServersClient } from "../apis/servers/index";
+import { ImagesClient } from "../apis/images/index";
+import { ActionsClient } from "../apis/actions/index";
+import { CertificatesClient } from "../apis/certificates/index";
+  import { SSHKeysClient } from "../apis/ssh-keys/index";
+import { LocationsClient } from "../apis/locations/index";
+import { FirewallsClient } from "../apis/firewalls/index";
+import { FloatingIPsClient } from "../apis/floating-ips/index";
+import { ISOsClient } from "../apis/isos/index";
+import { PlacementGroupsClient } from "../apis/placement-groups/index";
+import { PrimaryIPsClient } from "../apis/primary-ips/index";
+import { ServerTypesClient } from "../apis/server-types/index";
+import { LoadBalancersClient } from "../apis/load-balancers/index";
+import { NetworksClient } from "../apis/networks/index";
+import { PricingClient } from "../apis/pricing/index";
+import { VolumesClient } from "../apis/volumes/index";
+import { DNSClient } from "../apis/dns/index";
+import type { HeadersInit } from "bun";
+
+/**
+ * Hetzner Cloud API Client
+ *
+ * This is the main client class for interacting with the Hetzner Cloud API.
+ * It handles authentication, request/response processing, and error handling.
+ *
+ * @example
+ * ```typescript
+ * import { HCloudClient } from '@hcloud-js/library';
+ *
+ * const client = new HCloudClient({
+ *   token: 'your-api-token'
+ * });
+ *
+ * const servers = await client.get('/servers');
+ * ```
+ */
+export class HCloudClient {
+  private readonly token: string;
+  private readonly baseUrl: string;
+  private readonly timeout: number;
+
+  /**
+   * Servers API client
+   * @see https://docs.hetzner.cloud/reference/cloud#servers
+   */
+  public readonly servers: ServersClient;
+
+  /**
+   * Images API client
+   * @see https://docs.hetzner.cloud/reference/cloud#images
+   */
+  public readonly images: ImagesClient;
+
+  /**
+   * Actions API client
+   * @see https://docs.hetzner.cloud/reference/cloud#actions
+   */
+  public readonly actions: ActionsClient;
+
+  /**
+   * Certificates API client
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates
+   */
+  public readonly certificates: CertificatesClient;
+
+  /**
+   * SSH Keys API client
+   * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys
+   */
+  public readonly sshKeys: SSHKeysClient;
+
+  /**
+   * Locations API client
+   * @see https://docs.hetzner.cloud/reference/cloud#locations
+   */
+  public readonly locations: LocationsClient;
+
+  /**
+   * Firewalls API client
+   * @see https://docs.hetzner.cloud/reference/cloud#firewalls
+   */
+  public readonly firewalls: FirewallsClient;
+
+  /**
+   * Floating IPs API client
+   * @see https://docs.hetzner.cloud/reference/cloud#floating-ips
+   */
+  public readonly floatingIPs: FloatingIPsClient;
+
+  /**
+   * ISOs API client
+   * @see https://docs.hetzner.cloud/reference/cloud#isos
+   */
+  public readonly isos: ISOsClient;
+
+  /**
+   * Placement Groups API client
+   * @see https://docs.hetzner.cloud/reference/cloud#placement-groups
+   */
+  public readonly placementGroups: PlacementGroupsClient;
+
+  /**
+   * Primary IPs API client
+   * @see https://docs.hetzner.cloud/reference/cloud#primary-ips
+   */
+  public readonly primaryIPs: PrimaryIPsClient;
+
+  /**
+   * Server Types API client
+   * @see https://docs.hetzner.cloud/reference/cloud#server-types
+   */
+  public readonly serverTypes: ServerTypesClient;
+
+  /**
+   * Load Balancers API client
+   * @see https://docs.hetzner.cloud/reference/cloud#load-balancers
+   */
+  public readonly loadBalancers: LoadBalancersClient;
+
+  /**
+   * Networks API client
+   * @see https://docs.hetzner.cloud/reference/cloud#networks
+   */
+  public readonly networks: NetworksClient;
+
+  /**
+   * Pricing API client
+   * @see https://docs.hetzner.cloud/reference/cloud#pricing
+   */
+  public readonly pricing: PricingClient;
+
+  /**
+   * Volumes API client
+   * @see https://docs.hetzner.cloud/reference/cloud#volumes
+   */
+  public readonly volumes: VolumesClient;
+
+  /**
+   * DNS (Zones) API client
+   * @see https://docs.hetzner.cloud/reference/cloud#dns
+   */
+  public readonly dns: DNSClient;
+
+  /**
+   * Creates a new Hetzner Cloud API client
+   *
+   * @param options - Client configuration options
+   * @throws {HCloudError} If token is not provided
+   */
+  constructor(options: ClientOptions) {
+    if (!options.token || options.token.trim().length === 0) {
+      throw new HCloudError("API token is required", "INVALID_TOKEN");
+    }
+
+    this.token = options.token;
+    this.baseUrl = options.baseUrl ?? HCLOUD_API_BASE_URL;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+
+    // Initialize API clients
+    this.servers = new ServersClient(this);
+    this.images = new ImagesClient(this);
+    this.actions = new ActionsClient(this);
+    this.certificates = new CertificatesClient(this);
+    this.sshKeys = new SSHKeysClient(this);
+    this.locations = new LocationsClient(this);
+    this.firewalls = new FirewallsClient(this);
+    this.floatingIPs = new FloatingIPsClient(this);
+    this.isos = new ISOsClient(this);
+    this.placementGroups = new PlacementGroupsClient(this);
+    this.primaryIPs = new PrimaryIPsClient(this);
+    this.serverTypes = new ServerTypesClient(this);
+    this.loadBalancers = new LoadBalancersClient(this);
+    this.networks = new NetworksClient(this);
+    this.pricing = new PricingClient(this);
+    this.volumes = new VolumesClient(this);
+    this.dns = new DNSClient(this);
+  }
+
+  /**
+   * Make an HTTP request to the Hetzner Cloud API
+   *
+   * @param options - Request options
+   * @returns Promise resolving to the response data
+   * @throws {HCloudError} If the request fails
+   */
+  async request<T>(options: RequestOptions): Promise<T> {
+    const { method = "GET", path, body, params, headers = {} } = options;
+
+    // Build URL with query parameters
+    const baseUrlWithoutTrailingSlash = this.baseUrl.replace(/\/$/, "");
+    const pathWithoutLeadingSlash = path.replace(/^\//, "");
+    const url = new URL(`${baseUrlWithoutTrailingSlash}/${pathWithoutLeadingSlash}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          // Handle array values (e.g., sort, status) - append each value separately
+          if (Array.isArray(value)) {
+            value.forEach((item) => {
+              url.searchParams.append(key, String(item));
+            });
+          } else {
+            url.searchParams.append(key, String(value));
+          }
+        }
+      });
+    }
+
+    // Prepare request headers with authentication
+    const authHeader = createAuthHeader(this.token);
+    const requestHeaders: HeadersInit = {
+      ...authHeader,
+      "Content-Type": "application/json",
+      "User-Agent": "hcloud-ts",
+      ...headers,
+    };
+
+    // Prepare fetch options
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+      signal: AbortSignal.timeout(this.timeout),
+    };
+
+    // Add body for non-GET requests
+    if (body !== undefined && method !== "GET") {
+      fetchOptions.body = JSON.stringify(body);
+    }
+
+    try {
+      const response = await fetch(url.toString(), fetchOptions);
+
+      // Handle error responses
+      if (!response.ok) {
+        await this.handleErrorResponse(response);
+      }
+
+      // Handle empty responses (e.g., 204 No Content)
+      if (response.status === 204 || response.headers.get("content-length") === "0") {
+        return undefined as T;
+      }
+
+      // Parse JSON response
+      return (await response.json()) as T;
+    } catch (error: unknown) {
+      // Re-throw HCloudError as-is
+      if (error instanceof HCloudError) {
+        throw error;
+      }
+
+      // Handle fetch errors (network, timeout, etc.)
+      this.handleFetchError(error);
+    }
+  }
+
+  /**
+   * Handle error responses from the API
+   */
+  private async handleErrorResponse(response: Response): Promise<never> {
+    let errorMessage = `HTTP ${response.status} ${response.statusText}`;
+    let errorCode: string | undefined;
+    let errorDetails: ApiErrorResponse["error"]["details"];
+
+    try {
+      const errorData = (await response.json()) as ApiErrorResponse;
+      if (errorData.error) {
+        errorMessage = errorData.error.message || errorMessage;
+        errorCode = errorData.error.code;
+        errorDetails = errorData.error.details;
+      }
+    } catch {
+      // If error response is not JSON, use default message
+    }
+
+    throw new HCloudError(errorMessage, errorCode, response.status, errorDetails);
+  }
+
+  /**
+   * Handle fetch errors (network, timeout, etc.)
+   */
+  private handleFetchError(error: unknown): never {
+    if (error instanceof Error) {
+      if (error.name === "AbortError" || error.message.includes("timeout")) {
+        throw new HCloudError(`Request timeout after ${this.timeout}ms`, "TIMEOUT", 0);
+      }
+      throw new HCloudError(`Request failed: ${error.message}`, "NETWORK_ERROR", 0);
+    }
+
+    throw new HCloudError("Unknown error occurred", "UNKNOWN_ERROR", 0);
+  }
+
+  /**
+   * GET request
+   *
+   * @param path - API endpoint path
+   * @param params - Query parameters
+   * @param headers - Additional headers
+   * @returns Promise resolving to the response data
+   */
+  async get<T>(
+    path: string,
+    params?: RequestOptions["params"],
+    headers?: RequestOptions["headers"],
+  ): Promise<T> {
+    return this.request<T>({ method: "GET", path, params, headers });
+  }
+
+  /**
+   * POST request
+   *
+   * @param path - API endpoint path
+   * @param body - Request body
+   * @param params - Query parameters
+   * @param headers - Additional headers
+   * @returns Promise resolving to the response data
+   */
+  async post<T>(
+    path: string,
+    body?: unknown,
+    params?: RequestOptions["params"],
+    headers?: RequestOptions["headers"],
+  ): Promise<T> {
+    return this.request<T>({ method: "POST", path, body, params, headers });
+  }
+
+  /**
+   * PUT request
+   *
+   * @param path - API endpoint path
+   * @param body - Request body
+   * @param params - Query parameters
+   * @param headers - Additional headers
+   * @returns Promise resolving to the response data
+   */
+  async put<T>(
+    path: string,
+    body?: unknown,
+    params?: RequestOptions["params"],
+    headers?: RequestOptions["headers"],
+  ): Promise<T> {
+    return this.request<T>({ method: "PUT", path, body, params, headers });
+  }
+
+  /**
+   * PATCH request
+   *
+   * @param path - API endpoint path
+   * @param body - Request body
+   * @param params - Query parameters
+   * @param headers - Additional headers
+   * @returns Promise resolving to the response data
+   */
+  async patch<T>(
+    path: string,
+    body?: unknown,
+    params?: RequestOptions["params"],
+    headers?: RequestOptions["headers"],
+  ): Promise<T> {
+    return this.request<T>({ method: "PATCH", path, body, params, headers });
+  }
+
+  /**
+   * DELETE request
+   *
+   * @param path - API endpoint path
+   * @param params - Query parameters
+   * @param headers - Additional headers
+   * @returns Promise resolving to the response data
+   */
+  async delete<T>(
+    path: string,
+    params?: RequestOptions["params"],
+    headers?: RequestOptions["headers"],
+  ): Promise<T> {
+    return this.request<T>({ method: "DELETE", path, params, headers });
+  }
+}

package/src/config/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Configuration for Hetzner Cloud API Client
+ */
+
+/**
+ * Default base URL for Hetzner Cloud API
+ * @see https://docs.hetzner.cloud/
+ */
+export const HCLOUD_API_BASE_URL = "https://api.hetzner.cloud/v1";
+
+/**
+ * Default request timeout in milliseconds
+ */
+export const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * Client configuration options
+ */
+export interface ClientOptions {
+  /**
+   * Hetzner Cloud API token (Bearer token)
+   * Get your API token from: https://console.hetzner.cloud/
+   * @see https://docs.hetzner.cloud/reference/cloud#authentication
+   */
+  token: string;
+  /**
+   * Custom base URL (defaults to official Hetzner Cloud API)
+   */
+  baseUrl?: string;
+  /**
+   * Request timeout in milliseconds (defaults to 30000)
+   */
+  timeout?: number;
+}

package/src/errors/index.ts

@@ -0,0 +1,38 @@
+/**
+ * Error handling for Hetzner Cloud API
+ * @see https://docs.hetzner.cloud/reference/cloud#errors
+ */
+
+import type { ApiErrorResponse } from "../types/index";
+
+/**
+ * Hetzner Cloud API Error
+ *
+ * All API errors follow a consistent format with a code and message.
+ * @see https://docs.hetzner.cloud/reference/cloud#errors
+ */
+export class HCloudError extends Error {
+  constructor(
+    message: string,
+    public readonly code?: string,
+    public readonly statusCode?: number,
+    public readonly details?: ApiErrorResponse["error"]["details"],
+  ) {
+    super(message);
+    this.name = "HCloudError";
+  }
+
+  /**
+   * Check if error has field validation errors
+   */
+  hasFieldErrors(): boolean {
+    return Boolean(this.details?.fields && this.details.fields.length > 0);
+  }
+
+  /**
+   * Get field errors if available
+   */
+  getFieldErrors() {
+    return this.details?.fields ?? [];
+  }
+}