@nilovonjs/hcloud-js 1.0.0

package/src/apis/placement-groups/index.ts

@@ -0,0 +1,212 @@
+/**
+ * Hetzner Cloud Placement Groups API
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups
+ */
+
+import type { HCloudClient } from "@/client/index";
+import type {
+  ListPlacementGroupsParams,
+  ListPlacementGroupsResponse,
+  CreatePlacementGroupParams,
+  CreatePlacementGroupResponse,
+  GetPlacementGroupResponse,
+  UpdatePlacementGroupParams,
+  UpdatePlacementGroupResponse,
+  DeletePlacementGroupResponse,
+} from "@/apis/placement-groups/types";
+import { validate } from "@/validation/index";
+import {
+  listPlacementGroupsResponseSchema,
+  createPlacementGroupRequestSchema,
+  createPlacementGroupResponseSchema,
+  getPlacementGroupResponseSchema,
+  updatePlacementGroupRequestSchema,
+  updatePlacementGroupResponseSchema,
+  deletePlacementGroupResponseSchema,
+} from "@/apis/placement-groups/schemas";
+
+/**
+ * Placement Groups API client
+ */
+export class PlacementGroupsClient {
+  constructor(private readonly client: HCloudClient) {}
+
+  /**
+   * Returns all Placement Group objects.
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Promise resolving to list of placement groups with pagination metadata
+   * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-list-placement-groups
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // List all placement groups
+   * const result = await client.placementGroups.list();
+   *
+   * // List placement groups with filters
+   * const groups = await client.placementGroups.list({
+   *   name: 'my-group',
+   *   label_selector: 'environment=production',
+   *   sort: ['name:asc'],
+   *   page: 1,
+   *   per_page: 50
+   * });
+   * ```
+   */
+  async list(params?: ListPlacementGroupsParams): Promise<ListPlacementGroupsResponse> {
+    const queryParams: Record<string, string | number | string[] | undefined> = {};
+
+    if (params?.name) {
+      queryParams.name = params.name;
+    }
+
+    if (params?.label_selector) {
+      queryParams.label_selector = params.label_selector;
+    }
+
+    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>("/placement_groups", queryParams);
+
+    return validate(listPlacementGroupsResponseSchema, response, {
+      context: "List placement groups response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Creates a new Placement Group.
+   *
+   * @param params - Parameters for creating the placement group
+   * @returns Promise resolving to the created placement group
+   * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-create-a-placement-group
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Create a placement group
+   * const group = await client.placementGroups.create({
+   *   name: 'my-placement-group',
+   *   type: 'spread',
+   *   labels: { environment: 'production' }
+   * });
+   * ```
+   */
+  async create(params: CreatePlacementGroupParams): Promise<CreatePlacementGroupResponse> {
+    const validatedParams = validate(createPlacementGroupRequestSchema, params, {
+      context: "Create placement group request",
+      detailed: true,
+    });
+
+    const response = await this.client.post<unknown>("/placement_groups", validatedParams);
+
+    return validate(createPlacementGroupResponseSchema, response, {
+      context: "Create placement group response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Returns a specific Placement Group object.
+   *
+   * @param id - ID of the Placement Group
+   * @returns Promise resolving to the placement group
+   * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-get-a-placement-group
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Get a placement group by ID
+   * const group = await client.placementGroups.get(12345);
+   * console.log(group.placement_group.name);
+   * ```
+   */
+  async get(id: number): Promise<GetPlacementGroupResponse> {
+    const response = await this.client.get<unknown>(`/placement_groups/${id}`);
+
+    return validate(getPlacementGroupResponseSchema, response, {
+      context: "Get placement group response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Updates the Placement Group.
+   *
+   * You can update a Placement Group's name and labels.
+   *
+   * @param id - ID of the Placement Group
+   * @param params - Parameters to update (name and/or labels)
+   * @returns Promise resolving to the updated placement group
+   * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-update-a-placement-group
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Update placement group name
+   * const updated = await client.placementGroups.update(12345, {
+   *   name: 'new-group-name'
+   * });
+   *
+   * // Update labels
+   * const updated = await client.placementGroups.update(12345, {
+   *   labels: { environment: 'production', team: 'backend' }
+   * });
+   * ```
+   */
+  async update(
+    id: number,
+    params: UpdatePlacementGroupParams,
+  ): Promise<UpdatePlacementGroupResponse> {
+    const validatedParams = validate(updatePlacementGroupRequestSchema, params, {
+      context: "Update placement group request",
+      detailed: true,
+    });
+
+    const response = await this.client.put<unknown>(`/placement_groups/${id}`, validatedParams);
+
+    return validate(updatePlacementGroupResponseSchema, response, {
+      context: "Update placement group response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Deletes a Placement Group.
+   *
+   * @param id - ID of the Placement Group
+   * @returns Promise resolving to empty object
+   * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-delete-a-placement-group
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Delete a placement group
+   * await client.placementGroups.delete(12345);
+   * ```
+   */
+  async delete(id: number): Promise<DeletePlacementGroupResponse> {
+    const response = await this.client.delete<unknown>(`/placement_groups/${id}`);
+
+    return validate(deletePlacementGroupResponseSchema, response, {
+      context: "Delete placement group response",
+      detailed: true,
+    });
+  }
+}

package/src/apis/placement-groups/schemas.ts

@@ -0,0 +1,90 @@
+/**
+ * Zod schemas for Hetzner Cloud Placement Groups API
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups
+ */
+
+import { z } from "zod";
+import { actionSchema } from "@/apis/actions/schemas";
+import { paginationMetaSchema } from "@/apis/common/schemas";
+
+/**
+ * Placement Group type schema
+ */
+export const placementGroupTypeSchema = z.enum(["spread"]);
+
+/**
+ * Placement Group schema
+ */
+export const placementGroupSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    labels: z.record(z.string(), z.string()),
+    created: z.string(),
+    servers: z.array(z.number()),
+    type: placementGroupTypeSchema,
+  })
+  .passthrough();
+
+/**
+ * List Placement Groups response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-list-placement-groups
+ */
+export const listPlacementGroupsResponseSchema = z.object({
+  placement_groups: z.array(placementGroupSchema),
+  meta: z
+    .object({
+      pagination: paginationMetaSchema,
+    })
+    .optional(),
+});
+
+/**
+ * Create Placement Group request schema
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-create-a-placement-group
+ */
+export const createPlacementGroupRequestSchema = z.object({
+  name: z.string(),
+  type: placementGroupTypeSchema,
+  labels: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Create Placement Group response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-create-a-placement-group
+ */
+export const createPlacementGroupResponseSchema = z.object({
+  placement_group: placementGroupSchema,
+  action: actionSchema.optional(),
+});
+
+/**
+ * Get Placement Group response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-get-a-placement-group
+ */
+export const getPlacementGroupResponseSchema = z.object({
+  placement_group: placementGroupSchema,
+});
+
+/**
+ * Update Placement Group request schema
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-update-a-placement-group
+ */
+export const updatePlacementGroupRequestSchema = z.object({
+  name: z.string().optional(),
+  labels: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Update Placement Group response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-update-a-placement-group
+ */
+export const updatePlacementGroupResponseSchema = z.object({
+  placement_group: placementGroupSchema,
+});
+
+/**
+ * Delete Placement Group response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-delete-a-placement-group
+ */
+export const deletePlacementGroupResponseSchema = z.object({});

package/src/apis/placement-groups/types.ts

@@ -0,0 +1,99 @@
+/**
+ * Types for Hetzner Cloud Placement Groups API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  listPlacementGroupsResponseSchema,
+  createPlacementGroupRequestSchema,
+  createPlacementGroupResponseSchema,
+  getPlacementGroupResponseSchema,
+  updatePlacementGroupRequestSchema,
+  updatePlacementGroupResponseSchema,
+  deletePlacementGroupResponseSchema,
+  placementGroupSchema,
+  placementGroupTypeSchema,
+} from "@/apis/placement-groups/schemas";
+import type { z } from "zod";
+
+/**
+ * Placement Group type
+ */
+export type PlacementGroupType = z.infer<typeof placementGroupTypeSchema>;
+
+/**
+ * Hetzner Cloud Placement Group
+ */
+export type PlacementGroup = z.infer<typeof placementGroupSchema>;
+
+/**
+ * List Placement Groups query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-list-placement-groups
+ */
+export interface ListPlacementGroupsParams {
+  /**
+   * 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 Placement Groups response
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-list-placement-groups
+ */
+export type ListPlacementGroupsResponse = z.infer<typeof listPlacementGroupsResponseSchema>;
+
+/**
+ * Create Placement Group parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-create-a-placement-group
+ */
+export type CreatePlacementGroupParams = z.infer<typeof createPlacementGroupRequestSchema>;
+
+/**
+ * Create Placement Group response
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-create-a-placement-group
+ */
+export type CreatePlacementGroupResponse = z.infer<typeof createPlacementGroupResponseSchema>;
+
+/**
+ * Get Placement Group response
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-get-a-placement-group
+ */
+export type GetPlacementGroupResponse = z.infer<typeof getPlacementGroupResponseSchema>;
+
+/**
+ * Update Placement Group parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-update-a-placement-group
+ */
+export type UpdatePlacementGroupParams = z.infer<typeof updatePlacementGroupRequestSchema>;
+
+/**
+ * Update Placement Group response
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-update-a-placement-group
+ */
+export type UpdatePlacementGroupResponse = z.infer<typeof updatePlacementGroupResponseSchema>;
+
+/**
+ * Delete Placement Group response
+ * @see https://docs.hetzner.cloud/reference/cloud#placement-groups-delete-a-placement-group
+ */
+export type DeletePlacementGroupResponse = z.infer<typeof deletePlacementGroupResponseSchema>;

package/src/apis/pricing/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Hetzner Cloud Pricing API
+ * @see https://docs.hetzner.cloud/reference/cloud#pricing
+ */
+
+import type { HCloudClient } from "@/client/index";
+import type { GetPricingResponse } from "@/apis/pricing/types";
+import { validate } from "@/validation/index";
+import { getPricingResponseSchema } from "@/apis/pricing/schemas";
+
+/**
+ * Pricing API client
+ */
+export class PricingClient {
+  constructor(private readonly client: HCloudClient) {}
+
+  /**
+   * Returns all prices for all resources.
+   *
+   * @returns Promise resolving to all pricing information
+   * @see https://docs.hetzner.cloud/reference/cloud#pricing-get-all-prices
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Get all prices
+   * const pricing = await client.pricing.getAll();
+   * console.log(`Currency: ${pricing.currency}`);
+   * console.log(`VAT Rate: ${pricing.vat_rate}`);
+   * console.log(`Server Types: ${pricing.server_types.length}`);
+   * ```
+   */
+  async getAll(): Promise<GetPricingResponse> {
+    const response = await this.client.get<unknown>("/pricing");
+
+    return validate(getPricingResponseSchema, response, {
+      context: "Get pricing response",
+      detailed: true,
+    });
+  }
+}

package/src/apis/pricing/schemas.ts

@@ -0,0 +1,93 @@
+/**
+ * Zod schemas for Hetzner Cloud Pricing API
+ * @see https://docs.hetzner.cloud/reference/cloud#pricing
+ */
+
+import { z } from "zod";
+
+/**
+ * Price schema
+ */
+export const priceSchema = z.object({
+  net: z.string(),
+  gross: z.string(),
+});
+
+/**
+ * Pricing location schema
+ */
+export const pricingLocationSchema = z.object({
+  location: z.string(),
+  price_hourly: priceSchema,
+  price_monthly: priceSchema,
+});
+
+/**
+ * Server type pricing schema
+ */
+export const serverTypePricingSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  prices: z.array(pricingLocationSchema),
+});
+
+/**
+ * Load Balancer type pricing schema
+ */
+export const loadBalancerTypePricingSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  prices: z.array(pricingLocationSchema),
+});
+
+/**
+ * Volume pricing schema
+ */
+export const volumePricingSchema = z.object({
+  price_per_gb_month: priceSchema,
+});
+
+/**
+ * Floating IP pricing schema
+ */
+export const floatingIpPricingSchema = z.object({
+  price_monthly: priceSchema,
+});
+
+/**
+ * Primary IP pricing schema
+ */
+export const primaryIpPricingSchema = z.object({
+  price_monthly: priceSchema,
+});
+
+/**
+ * Traffic pricing schema
+ */
+export const trafficPricingSchema = z.object({
+  price_per_tb: priceSchema,
+});
+
+/**
+ * Image pricing schema
+ */
+export const imagePricingSchema = z.object({
+  price_per_gb_month: priceSchema,
+});
+
+/**
+ * Get Pricing response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#pricing-get-all-prices
+ */
+export const getPricingResponseSchema = z.object({
+  currency: z.string(),
+  vat_rate: z.string(),
+  image: imagePricingSchema,
+  floating_ip: floatingIpPricingSchema,
+  floating_ip_price_monthly: priceSchema,
+  primary_ips: z.array(primaryIpPricingSchema).optional(),
+  server_types: z.array(serverTypePricingSchema),
+  load_balancer_types: z.array(loadBalancerTypePricingSchema).optional(),
+  volume: volumePricingSchema,
+  traffic: trafficPricingSchema,
+});

package/src/apis/pricing/types.ts

@@ -0,0 +1,71 @@
+/**
+ * Types for Hetzner Cloud Pricing API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#pricing
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  getPricingResponseSchema,
+  priceSchema,
+  pricingLocationSchema,
+  serverTypePricingSchema,
+  loadBalancerTypePricingSchema,
+  volumePricingSchema,
+  floatingIpPricingSchema,
+  primaryIpPricingSchema,
+  trafficPricingSchema,
+  imagePricingSchema,
+} from "@/apis/pricing/schemas";
+import type { z } from "zod";
+
+/**
+ * Price
+ */
+export type Price = z.infer<typeof priceSchema>;
+
+/**
+ * Pricing location
+ */
+export type PricingLocation = z.infer<typeof pricingLocationSchema>;
+
+/**
+ * Server type pricing
+ */
+export type ServerTypePricing = z.infer<typeof serverTypePricingSchema>;
+
+/**
+ * Load Balancer type pricing
+ */
+export type LoadBalancerTypePricing = z.infer<typeof loadBalancerTypePricingSchema>;
+
+/**
+ * Volume pricing
+ */
+export type VolumePricing = z.infer<typeof volumePricingSchema>;
+
+/**
+ * Floating IP pricing
+ */
+export type FloatingIpPricing = z.infer<typeof floatingIpPricingSchema>;
+
+/**
+ * Primary IP pricing
+ */
+export type PrimaryIpPricing = z.infer<typeof primaryIpPricingSchema>;
+
+/**
+ * Traffic pricing
+ */
+export type TrafficPricing = z.infer<typeof trafficPricingSchema>;
+
+/**
+ * Image pricing
+ */
+export type ImagePricing = z.infer<typeof imagePricingSchema>;
+
+/**
+ * Get Pricing response
+ * @see https://docs.hetzner.cloud/reference/cloud#pricing-get-all-prices
+ */
+export type GetPricingResponse = z.infer<typeof getPricingResponseSchema>;