@nilovonjs/hcloud-js 1.0.0

package/src/apis/isos/index.ts

@@ -0,0 +1,91 @@
+/**
+ * Hetzner Cloud ISOs API
+ * @see https://docs.hetzner.cloud/reference/cloud#isos
+ */
+
+import type { HCloudClient } from "@/client/index";
+import type { ListISOsParams, ListISOsResponse, GetISOResponse } from "@/apis/isos/types";
+import { validate } from "@/validation/index";
+import { listISOsResponseSchema, getISOResponseSchema } from "@/apis/isos/schemas";
+
+/**
+ * ISOs API client
+ */
+export class ISOsClient {
+  constructor(private readonly client: HCloudClient) {}
+
+  /**
+   * Returns all available ISO objects.
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Promise resolving to list of ISOs with pagination metadata
+   * @see https://docs.hetzner.cloud/reference/cloud#isos-list-isos
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // List all ISOs
+   * const result = await client.isos.list();
+   *
+   * // List ISOs with filters
+   * const isos = await client.isos.list({
+   *   name: 'debian',
+   *   sort: ['name:asc'],
+   *   page: 1,
+   *   per_page: 50
+   * });
+   * ```
+   */
+  async list(params?: ListISOsParams): Promise<ListISOsResponse> {
+    const queryParams: Record<string, string | number | string[] | undefined> = {};
+
+    if (params?.name) {
+      queryParams.name = params.name;
+    }
+
+    if (params?.sort) {
+      queryParams.sort = Array.isArray(params.sort) ? params.sort : [params.sort];
+    }
+
+    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>("/isos", queryParams);
+
+    return validate(listISOsResponseSchema, response, {
+      context: "List ISOs response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Returns a specific ISO object.
+   *
+   * @param id - ID of the ISO
+   * @returns Promise resolving to the ISO
+   * @see https://docs.hetzner.cloud/reference/cloud#isos-get-an-iso
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Get an ISO by ID
+   * const iso = await client.isos.get(12345);
+   * console.log(iso.iso.name);
+   * ```
+   */
+  async get(id: number): Promise<GetISOResponse> {
+    const response = await this.client.get<unknown>(`/isos/${id}`);
+
+    return validate(getISOResponseSchema, response, {
+      context: "Get ISO response",
+      detailed: true,
+    });
+  }
+}

package/src/apis/isos/schemas.ts

@@ -0,0 +1,43 @@
+/**
+ * Zod schemas for Hetzner Cloud ISOs API
+ * @see https://docs.hetzner.cloud/reference/cloud#isos-list-isos
+ */
+
+import { z } from "zod";
+import { paginationMetaSchema } from "@/apis/common/schemas";
+
+/**
+ * ISO type schema
+ */
+export const isoTypeSchema = z.enum(["public", "private"]);
+
+/**
+ * ISO schema
+ */
+export const isoSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  description: z.string(),
+  type: isoTypeSchema,
+});
+
+/**
+ * List ISOs response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#isos-list-isos
+ */
+export const listISOsResponseSchema = z.object({
+  isos: z.array(isoSchema),
+  meta: z
+    .object({
+      pagination: paginationMetaSchema,
+    })
+    .optional(),
+});
+
+/**
+ * Get ISO response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#isos-get-an-iso
+ */
+export const getISOResponseSchema = z.object({
+  iso: isoSchema,
+});

package/src/apis/isos/types.ts

@@ -0,0 +1,60 @@
+/**
+ * Types for Hetzner Cloud ISOs API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#isos
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  listISOsResponseSchema,
+  getISOResponseSchema,
+  isoSchema,
+  isoTypeSchema,
+} from "@/apis/isos/schemas";
+import type { z } from "zod";
+
+/**
+ * ISO type
+ */
+export type ISOType = z.infer<typeof isoTypeSchema>;
+
+/**
+ * Hetzner Cloud ISO
+ */
+export type ISO = z.infer<typeof isoSchema>;
+
+/**
+ * List ISOs query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#isos-list-isos
+ */
+export interface ListISOsParams {
+  /**
+   * Can be used multiple times. Choices: id, id:asc, id:desc, name, name:asc, name:desc
+   * @see https://docs.hetzner.cloud/reference/cloud#sorting
+   */
+  sort?: string | string[];
+  /**
+   * Can be used to filter ISOs by their name. The response will only contain the ISO matching the specified name.
+   */
+  name?: 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 ISOs response
+ * @see https://docs.hetzner.cloud/reference/cloud#isos-list-isos
+ */
+export type ListISOsResponse = z.infer<typeof listISOsResponseSchema>;
+
+/**
+ * Get ISO response
+ * @see https://docs.hetzner.cloud/reference/cloud#isos-get-an-iso
+ */
+export type GetISOResponse = z.infer<typeof getISOResponseSchema>;