@nilovonjs/hcloud-js 1.0.0

package/src/apis/floating-ips/types.ts

@@ -0,0 +1,207 @@
+/**
+ * Types for Hetzner Cloud Floating IPs API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  listFloatingIPsResponseSchema,
+  createFloatingIPRequestSchema,
+  createFloatingIPResponseSchema,
+  getFloatingIPResponseSchema,
+  updateFloatingIPRequestSchema,
+  updateFloatingIPResponseSchema,
+  deleteFloatingIPResponseSchema,
+  listFloatingIPActionsResponseSchema,
+  getFloatingIPActionResponseSchema,
+  assignFloatingIPToServerRequestSchema,
+  assignFloatingIPToServerResponseSchema,
+  changeFloatingIPReverseDNSRequestSchema,
+  changeFloatingIPReverseDNSResponseSchema,
+  changeFloatingIPProtectionRequestSchema,
+  changeFloatingIPProtectionResponseSchema,
+  unassignFloatingIPRequestSchema,
+  unassignFloatingIPResponseSchema,
+  floatingIpSchema,
+  floatingIpTypeSchema,
+  floatingIpDnsPointerSchema,
+  floatingIpProtectionSchema,
+} from "../../apis/floating-ips/schemas";
+import type { z } from "zod";
+
+/**
+ * Floating IP type
+ */
+export type FloatingIPType = z.infer<typeof floatingIpTypeSchema>;
+
+/**
+ * Floating IP DNS pointer
+ */
+export type FloatingIPDnsPointer = z.infer<typeof floatingIpDnsPointerSchema>;
+
+/**
+ * Floating IP protection
+ */
+export type FloatingIPProtection = z.infer<typeof floatingIpProtectionSchema>;
+
+/**
+ * Floating IP
+ */
+export type FloatingIP = z.infer<typeof floatingIpSchema>;
+
+/**
+ * List Floating IPs query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-list-floating-ips
+ */
+export interface ListFloatingIPsParams {
+  /**
+   * Can be used to filter Floating IPs by their name. The response will only contain the Floating IP 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 Floating IPs by labels. The response will only contain Floating IPs 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 Floating IPs response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-list-floating-ips
+ */
+export type ListFloatingIPsResponse = z.infer<typeof listFloatingIPsResponseSchema>;
+
+/**
+ * Create Floating IP parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-create-a-floating-ip
+ */
+export type CreateFloatingIPParams = z.infer<typeof createFloatingIPRequestSchema>;
+
+/**
+ * Create Floating IP response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-create-a-floating-ip
+ */
+export type CreateFloatingIPResponse = z.infer<typeof createFloatingIPResponseSchema>;
+
+/**
+ * Get Floating IP response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-get-a-floating-ip
+ */
+export type GetFloatingIPResponse = z.infer<typeof getFloatingIPResponseSchema>;
+
+/**
+ * Update Floating IP parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-update-a-floating-ip
+ */
+export type UpdateFloatingIPParams = z.infer<typeof updateFloatingIPRequestSchema>;
+
+/**
+ * Update Floating IP response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-update-a-floating-ip
+ */
+export type UpdateFloatingIPResponse = z.infer<typeof updateFloatingIPResponseSchema>;
+
+/**
+ * Delete Floating IP response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-delete-a-floating-ip
+ */
+export type DeleteFloatingIPResponse = z.infer<typeof deleteFloatingIPResponseSchema>;
+
+/**
+ * List Floating IP Actions query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-list-actions-for-a-floating-ip
+ */
+export interface ListFloatingIPActionsParams {
+  /**
+   * 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 Floating IP Actions response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-list-actions-for-a-floating-ip
+ */
+export type ListFloatingIPActionsResponse = z.infer<typeof listFloatingIPActionsResponseSchema>;
+
+/**
+ * Get Floating IP Action response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-get-an-action-for-a-floating-ip
+ */
+export type GetFloatingIPActionResponse = z.infer<typeof getFloatingIPActionResponseSchema>;
+
+/**
+ * Assign Floating IP to Server parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-assign-a-floating-ip-to-a-server
+ */
+export type AssignFloatingIPToServerParams = z.infer<typeof assignFloatingIPToServerRequestSchema>;
+
+/**
+ * Assign Floating IP to Server response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-assign-a-floating-ip-to-a-server
+ */
+export type AssignFloatingIPToServerResponse = z.infer<typeof assignFloatingIPToServerResponseSchema>;
+
+/**
+ * Change Floating IP reverse DNS parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-change-reverse-dns-records-for-a-floating-ip
+ */
+export type ChangeFloatingIPReverseDNSParams = z.infer<
+  typeof changeFloatingIPReverseDNSRequestSchema
+>;
+
+/**
+ * Change Floating IP reverse DNS response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-change-reverse-dns-records-for-a-floating-ip
+ */
+export type ChangeFloatingIPReverseDNSResponse = z.infer<
+  typeof changeFloatingIPReverseDNSResponseSchema
+>;
+
+/**
+ * Change Floating IP Protection parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-change-floating-ip-protection
+ */
+export type ChangeFloatingIPProtectionParams = z.infer<
+  typeof changeFloatingIPProtectionRequestSchema
+>;
+
+/**
+ * Change Floating IP Protection response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-change-floating-ip-protection
+ */
+export type ChangeFloatingIPProtectionResponse = z.infer<
+  typeof changeFloatingIPProtectionResponseSchema
+>;
+
+/**
+ * Unassign Floating IP response
+ * @see https://docs.hetzner.cloud/reference/cloud#floating-ips-unassign-a-floating-ip
+ */
+export type UnassignFloatingIPResponse = z.infer<typeof unassignFloatingIPResponseSchema>;

package/src/apis/images/index.ts

@@ -0,0 +1,195 @@
+/**
+ * Hetzner Cloud Images API
+ * @see https://docs.hetzner.cloud/reference/cloud#images
+ */
+
+import type { HCloudClient } from "@/client/index";
+import { validate } from "@/validation/index";
+import { deleteImageResponseSchema, getImageResponseSchema, listImagesResponseSchema, updateImageRequestSchema, updateImageResponseSchema } from "@/apis/images/schemas";
+import type {
+  ListImagesParams,
+  ListImagesResponse,
+  GetImageResponse,
+  UpdateImageParams,
+  UpdateImageResponse,
+  DeleteImageResponse,
+} from "@/apis/images/types";
+
+/**
+ * Images API client
+ */
+export class ImagesClient {
+  constructor(private readonly client: HCloudClient) {}
+
+  /**
+   * Returns all Image objects.
+   *
+   * You can select specific Image types only and sort the results by using URI parameters.
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Promise resolving to list of images with pagination metadata
+   * @see https://docs.hetzner.cloud/reference/cloud#images-list-images
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // List all images
+   * const result = await client.images.list();
+   *
+   * // List images with filters
+   * const snapshots = await client.images.list({
+   *   type: ['snapshot'],
+   *   status: ['available'],
+   *   label_selector: 'environment=production',
+   *   sort: ['created:desc'],
+   *   page: 1,
+   *   per_page: 50
+   * });
+   * ```
+   */
+  async list(params?: ListImagesParams): Promise<ListImagesResponse> {
+    // Build query parameters
+    const queryParams: Record<string, string | number | boolean | string[] | undefined> = {};
+
+    if (params?.type) {
+      // Convert single type to array for consistent handling
+      queryParams.type = Array.isArray(params.type) ? params.type : [params.type];
+    }
+
+    if (params?.status) {
+      // Convert single status to array for consistent handling
+      queryParams.status = Array.isArray(params.status) ? params.status : [params.status];
+    }
+
+    if (params?.name) {
+      queryParams.name = params.name;
+    }
+
+    if (params?.label_selector) {
+      queryParams.label_selector = params.label_selector;
+    }
+
+    if (params?.sort) {
+      // Convert single string to array for consistent handling
+      queryParams.sort = Array.isArray(params.sort) ? params.sort : [params.sort];
+    }
+
+    if (params?.architecture) {
+      // Convert single architecture to array for consistent handling
+      queryParams.architecture = Array.isArray(params.architecture)
+        ? params.architecture
+        : [params.architecture];
+    }
+
+    if (params?.bound_to !== undefined) {
+      queryParams.bound_to = params.bound_to;
+    }
+
+    if (params?.include_deprecated !== undefined) {
+      queryParams.include_deprecated = params.include_deprecated;
+    }
+
+    if (params?.page !== undefined) {
+      queryParams.page = params.page;
+    }
+
+    if (params?.per_page !== undefined) {
+      queryParams.per_page = params.per_page;
+    }
+
+    const response = await this.client.get<unknown>("/images", queryParams);
+
+    // Validate response with Zod
+    return validate(listImagesResponseSchema, response, { context: "List images response" });
+  }
+
+  /**
+   * Returns a specific Image object.
+   *
+   * @param id - ID of the Image
+   * @returns Promise resolving to the image
+   * @see https://docs.hetzner.cloud/reference/cloud#images-get-an-image
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Get an image by ID
+   * const image = await client.images.get(12345);
+   * console.log(image.image.name);
+   * ```
+   */
+  async get(id: number): Promise<GetImageResponse> {
+    const response = await this.client.get<unknown>(`/images/${id}`);
+
+    // Validate response with Zod
+    return validate(getImageResponseSchema, response, { context: "Get image response" });
+  }
+
+  /**
+   * Updates the Image. You may change the description or convert a Snapshot to a backup Image.
+   *
+   * Only callable on `snapshot` and `backup` image types.
+   *
+   * @param id - ID of the Image
+   * @param params - Parameters to update (description, type, and/or labels)
+   * @returns Promise resolving to the updated image
+   * @see https://docs.hetzner.cloud/reference/cloud#images-update-an-image
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Update image description
+   * const updated = await client.images.update(12345, {
+   *   description: 'Updated description'
+   * });
+   *
+   * // Update labels
+   * const updated = await client.images.update(12345, {
+   *   labels: { environment: 'production', team: 'backend' }
+   * });
+   *
+   * // Convert snapshot to backup
+   * const updated = await client.images.update(12345, {
+   *   type: 'snapshot'
+   * });
+   * ```
+   */
+  async update(id: number, params: UpdateImageParams): Promise<UpdateImageResponse> {
+    // Validate request parameters
+    const validatedParams = validate(updateImageRequestSchema, params, { context: "Update image request" });
+
+    // Make API request
+    const response = await this.client.put<unknown>(`/images/${id}`, validatedParams);
+
+    // Validate response with Zod
+    return validate(updateImageResponseSchema, response, { context: "Update image response" });
+  }
+
+  /**
+   * Deletes an Image.
+   *
+   * Only available for `snapshot` and `backup` image types.
+   *
+   * @param id - ID of the Image
+   * @returns Promise resolving to the delete action
+   * @see https://docs.hetzner.cloud/reference/cloud#images-delete-an-image
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Delete an image
+   * const result = await client.images.delete(12345);
+   * console.log(`Delete action ID: ${result.action.id}`);
+   * ```
+   */
+  async delete(id: number): Promise<DeleteImageResponse> {
+    const response = await this.client.delete<unknown>(`/images/${id}`);
+
+    // Validate response with Zod
+    return validate(deleteImageResponseSchema, response, { context: "Delete image response" });
+  }
+}

package/src/apis/images/schemas.ts

@@ -0,0 +1,113 @@
+/**
+ * Zod schemas for Hetzner Cloud Images API
+ * @see https://docs.hetzner.cloud/reference/cloud#images-list-images
+ */
+
+import { z } from "zod";
+import { paginationMetaSchema } from "@/apis/common/schemas";
+import { actionSchema } from "@/apis/actions/schemas";
+
+/**
+ * Image status schema
+ */
+export const imageStatusSchema = z.enum(["available", "creating", "unavailable"]);
+
+/**
+ * Image type schema
+ */
+export const imageTypeSchema = z.enum(["system", "app", "snapshot", "backup"]);
+
+/**
+ * Image created from schema
+ */
+export const imageCreatedFromSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+});
+
+/**
+ * Image protection schema
+ */
+export const imageProtectionSchema = z.object({
+  delete: z.boolean(),
+});
+
+/**
+ * Image deprecation schema
+ */
+export const imageDeprecationSchema = z.object({
+  announced: z.string(),
+  unavailable_after: z.string(),
+});
+
+/**
+ * Image schema
+ */
+export const imageSchema = z
+  .object({
+    id: z.number(),
+    type: imageTypeSchema,
+    status: imageStatusSchema,
+    name: z.string(),
+    description: z.string(),
+    image_size: z.number().nullable(),
+    disk_size: z.number(),
+    created: z.string(),
+    created_from: imageCreatedFromSchema.nullable(),
+    bound_to: z.number().nullable(),
+    os_flavor: z.string(),
+    os_version: z.string().nullable(),
+    rapid_deploy: z.boolean(),
+    protection: imageProtectionSchema,
+    deprecation: imageDeprecationSchema.nullable().optional(),
+    labels: z.record(z.string(), z.string()),
+    deleted: z.string().nullable(),
+  })
+  .passthrough();
+
+/**
+ * List Images response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#images-list-images
+ */
+export const listImagesResponseSchema = z.object({
+  images: z.array(imageSchema),
+  meta: z
+    .object({
+      pagination: paginationMetaSchema,
+    })
+    .optional(),
+});
+
+/**
+ * Update Image request schema
+ * @see https://docs.hetzner.cloud/reference/cloud#images-update-an-image
+ */
+export const updateImageRequestSchema = z.object({
+  description: z.string().optional(),
+  type: z.enum(["snapshot"]).optional(),
+  labels: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Get Image response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#images-get-an-image
+ */
+export const getImageResponseSchema = z.object({
+  image: imageSchema,
+});
+
+/**
+ * Update Image response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#images-update-an-image
+ */
+export const updateImageResponseSchema = z.object({
+  image: imageSchema,
+});
+
+/**
+ * Delete Image response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#images-delete-an-image
+ */
+export const deleteImageResponseSchema = z.object({
+  action: actionSchema,
+});

package/src/apis/images/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Types for Hetzner Cloud Images API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#images-list-images
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  imageStatusSchema,
+  imageTypeSchema,
+  listImagesResponseSchema,
+  updateImageRequestSchema,
+  getImageResponseSchema,
+  updateImageResponseSchema,
+  deleteImageResponseSchema,
+} from "@/apis/images/schemas";
+import { imageSchema } from "@/apis/images/schemas";
+import type { z } from "zod";
+
+/**
+ * Image status values
+ */
+export type ImageStatus = z.infer<typeof imageStatusSchema>;
+
+/**
+ * Image type values
+ */
+export type ImageType = z.infer<typeof imageTypeSchema>;
+
+/**
+ * Hetzner Cloud Image
+ * @see https://docs.hetzner.cloud/reference/cloud#images-list-images
+ */
+export type Image = z.infer<typeof imageSchema>;
+
+/**
+ * Pagination metadata
+ * @see https://docs.hetzner.cloud/reference/cloud#pagination
+ * Re-exported from servers module for consistency
+ */
+export type { PaginationMeta } from "@/apis/servers/types";
+
+/**
+ * List Images query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#images-list-images
+ */
+export interface ListImagesParams {
+  /**
+   * Can be used multiple times. The response will only contain Images matching the type.
+   * Choices: system, app, snapshot, backup
+   */
+  type?: ImageType | ImageType[];
+  /**
+   * Can be used multiple times. The response will only contain Images matching the status.
+   * Choices: available, creating, unavailable
+   */
+  status?: ImageStatus | ImageStatus[];
+  /**
+   * Can be used to filter Images by their name. The response will only contain the Image matching the specified name.
+   */
+  name?: string;
+  /**
+   * Can be used to filter Images by labels. The response will only contain Images matching the label selector.
+   * @see https://docs.hetzner.cloud/reference/cloud#label-selector
+   */
+  label_selector?: string;
+  /**
+   * Can be used multiple times. Choices: id, id:asc, id:desc, name, name:asc, name:desc, created, created:asc, created:desc, type, type:asc, type:desc
+   * @see https://docs.hetzner.cloud/reference/cloud#sorting
+   */
+  sort?: string | string[];
+  /**
+   * Can be used multiple times, the response will only contain Images matching the specified architecture.
+   * Choices: x86, arm
+   */
+  architecture?: "x86" | "arm" | ("x86" | "arm")[];
+  /**
+   * Can be used to filter Images by their bound server. The response will only contain the Image matching the specified server ID.
+   */
+  bound_to?: number;
+  /**
+   * Can be used to filter Images by their include_deprecated status.
+   * If set to true, deprecated Images are included in the response. If set to false, deprecated Images are excluded from the response.
+   */
+  include_deprecated?: boolean;
+  /**
+   * 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 Images response
+ * @see https://docs.hetzner.cloud/reference/cloud#images-list-images
+ */
+export type ListImagesResponse = z.infer<typeof listImagesResponseSchema>;
+
+/**
+ * Update Image request parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#images-update-an-image
+ */
+export type UpdateImageParams = z.infer<typeof updateImageRequestSchema>;
+
+/**
+ * Get Image response
+ * @see https://docs.hetzner.cloud/reference/cloud#images-get-an-image
+ */
+export type GetImageResponse = z.infer<typeof getImageResponseSchema>;
+
+/**
+ * Update Image response
+ * @see https://docs.hetzner.cloud/reference/cloud#images-update-an-image
+ */
+export type UpdateImageResponse = z.infer<typeof updateImageResponseSchema>;
+
+/**
+ * Delete Image response
+ * @see https://docs.hetzner.cloud/reference/cloud#images-delete-an-image
+ */
+export type DeleteImageResponse = z.infer<typeof deleteImageResponseSchema>;