@nilovonjs/hcloud-js 1.0.0

package/src/apis/certificates/index.ts

@@ -0,0 +1,326 @@
+/**
+ * Hetzner Cloud Certificates API
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates
+ */
+
+import type { HCloudClient } from "../../client/index";
+import type {
+  ListCertificatesParams,
+  ListCertificatesResponse,
+  CreateCertificateParams,
+  CreateCertificateResponse,
+  GetCertificateResponse,
+  UpdateCertificateParams,
+  UpdateCertificateResponse,
+  DeleteCertificateResponse,
+  ListCertificateActionsParams,
+  ListCertificateActionsResponse,
+  GetCertificateActionResponse,
+  RetryCertificateIssuanceResponse,
+} from "../../apis/certificates/types";
+import { validate } from "../../validation/index";
+import {
+  listCertificatesResponseSchema,
+  createCertificateRequestSchema,
+  createCertificateResponseSchema,
+  getCertificateResponseSchema,
+  updateCertificateRequestSchema,
+  updateCertificateResponseSchema,
+  deleteCertificateResponseSchema,
+  listCertificateActionsResponseSchema,
+  getCertificateActionResponseSchema,
+  retryCertificateIssuanceResponseSchema,
+} from "../../apis/certificates/schemas";
+
+/**
+ * Certificates API client
+ */
+export class CertificatesClient {
+  constructor(private readonly client: HCloudClient) {}
+
+  /**
+   * Returns all Certificate objects.
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Promise resolving to list of certificates with pagination metadata
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-certificates
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // List all certificates
+   * const result = await client.certificates.list();
+   *
+   * // List certificates with filters
+   * const managedCerts = await client.certificates.list({
+   *   type: ['managed'],
+   *   label_selector: 'environment=production',
+   *   sort: ['name:asc'],
+   *   page: 1,
+   *   per_page: 50
+   * });
+   * ```
+   */
+  async list(params?: ListCertificatesParams): Promise<ListCertificatesResponse> {
+    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?.type) {
+      queryParams.type = Array.isArray(params.type) ? params.type : [params.type];
+    }
+
+    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>("/certificates", queryParams);
+
+    return validate(listCertificatesResponseSchema, response, {
+      context: "List certificates response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Creates a new Certificate.
+   *
+   * @param params - Parameters for creating the certificate
+   * @returns Promise resolving to the created certificate with action
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-create-a-certificate
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Create an uploaded certificate
+   * const result = await client.certificates.create({
+   *   name: 'my-certificate',
+   *   type: 'uploaded',
+   *   certificate: '-----BEGIN CERTIFICATE-----...',
+   *   private_key: '-----BEGIN PRIVATE KEY-----...'
+   * });
+   *
+   * // Create a managed certificate
+   * const result = await client.certificates.create({
+   *   name: 'my-managed-cert',
+   *   type: 'managed',
+   *   domain_names: ['example.com', 'www.example.com']
+   * });
+   * ```
+   */
+  async create(params: CreateCertificateParams): Promise<CreateCertificateResponse> {
+    const validatedParams = validate(createCertificateRequestSchema, params, {
+      context: "Create certificate request",
+      detailed: true,
+    });
+
+    const response = await this.client.post<unknown>("/certificates", validatedParams);
+
+    return validate(createCertificateResponseSchema, response, {
+      context: "Create certificate response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Returns a specific Certificate object.
+   *
+   * @param id - ID of the Certificate
+   * @returns Promise resolving to the certificate
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-get-a-certificate
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const certificate = await client.certificates.get(12345);
+   * console.log(certificate.certificate.name);
+   * ```
+   */
+  async get(id: number): Promise<GetCertificateResponse> {
+    const response = await this.client.get<unknown>(`/certificates/${id}`);
+
+    return validate(getCertificateResponseSchema, response, {
+      context: "Get certificate response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Updates a Certificate.
+   *
+   * You can update a Certificate's name and labels.
+   *
+   * @param id - ID of the Certificate
+   * @param params - Parameters to update (name and/or labels)
+   * @returns Promise resolving to the updated certificate
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-update-a-certificate
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const updated = await client.certificates.update(12345, {
+   *   name: 'new-certificate-name',
+   *   labels: { environment: 'production' }
+   * });
+   * ```
+   */
+  async update(id: number, params: UpdateCertificateParams): Promise<UpdateCertificateResponse> {
+    const validatedParams = validate(updateCertificateRequestSchema, params, {
+      context: "Update certificate request",
+      detailed: true,
+    });
+
+    const response = await this.client.put<unknown>(`/certificates/${id}`, validatedParams);
+
+    return validate(updateCertificateResponseSchema, response, {
+      context: "Update certificate response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Deletes a Certificate.
+   *
+   * @param id - ID of the Certificate
+   * @returns Promise resolving to the delete action
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-delete-a-certificate
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const result = await client.certificates.delete(12345);
+   * console.log(`Delete action ID: ${result.action.id}`);
+   * ```
+   */
+  async delete(id: number): Promise<DeleteCertificateResponse> {
+    const response = await this.client.delete<unknown>(`/certificates/${id}`);
+
+    return validate(deleteCertificateResponseSchema, response, {
+      context: "Delete certificate response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Returns all Action objects for a Certificate.
+   *
+   * @param id - ID of the Certificate
+   * @param params - Query parameters for filtering and pagination
+   * @returns Promise resolving to list of actions with pagination metadata
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-actions-for-a-certificate
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const actions = await client.certificates.listActions(12345, {
+   *   status: ['running'],
+   *   sort: ['started:desc']
+   * });
+   * ```
+   */
+  async listActions(
+    id: number,
+    params?: ListCertificateActionsParams,
+  ): Promise<ListCertificateActionsResponse> {
+    const queryParams: Record<string, string | number | string[] | undefined> = {};
+
+    if (params?.id !== undefined) {
+      const ids = Array.isArray(params.id) ? params.id : [params.id];
+      queryParams.id = ids.map(String);
+    }
+
+    if (params?.status) {
+      queryParams.status = Array.isArray(params.status) ? params.status : [params.status];
+    }
+
+    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>(`/certificates/${id}/actions`, queryParams);
+
+    return validate(listCertificateActionsResponseSchema, response, {
+      context: "List certificate actions response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Returns a specific Action object for a Certificate.
+   *
+   * @param id - ID of the Certificate
+   * @param actionId - ID of the Action
+   * @returns Promise resolving to the action
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-get-an-action-for-a-certificate
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const action = await client.certificates.getAction(12345, 67890);
+   * console.log(action.action.command);
+   * ```
+   */
+  async getAction(id: number, actionId: number): Promise<GetCertificateActionResponse> {
+    const response = await this.client.get<unknown>(`/certificates/${id}/actions/${actionId}`);
+
+    return validate(getCertificateActionResponseSchema, response, {
+      context: "Get certificate action response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Retries the issuance or renewal of a managed Certificate.
+   *
+   * Only works for managed Certificates in state `verification_process`.
+   *
+   * @param id - ID of the Certificate
+   * @returns Promise resolving to the retry action
+   * @see https://docs.hetzner.cloud/reference/cloud#certificates-retry-issuance-or-renewal
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const result = await client.certificates.retryIssuance(12345);
+   * console.log(`Retry action ID: ${result.action.id}`);
+   * ```
+   */
+  async retryIssuance(id: number): Promise<RetryCertificateIssuanceResponse> {
+    const response = await this.client.post<unknown>(`/certificates/${id}/actions/retry`, {});
+
+    return validate(retryCertificateIssuanceResponseSchema, response, {
+      context: "Retry certificate issuance response",
+      detailed: true,
+    });
+  }
+}

package/src/apis/certificates/schemas.ts

@@ -0,0 +1,140 @@
+/**
+ * Zod schemas for Hetzner Cloud Certificates API
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates
+ */
+
+import { z } from "zod";
+import { actionSchema, actionResourceSchema } from "../../apis/actions/schemas";
+import { paginationMetaSchema } from "../../apis/common/schemas";
+
+/**
+ * Certificate status schema
+ */
+export const certificateStatusSchema = z.enum(["ready", "verification_process", "pending_deletion"]);
+
+/**
+ * Certificate type schema
+ */
+export const certificateTypeSchema = z.enum(["uploaded", "managed"]);
+
+/**
+ * Certificate schema
+ */
+export const certificateSchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    labels: z.record(z.string(), z.string()),
+    type: certificateTypeSchema,
+    certificate: z.string().nullable(),
+    created: z.string(),
+    not_valid_before: z.string(),
+    not_valid_after: z.string(),
+    domain_names: z.array(z.string()),
+    fingerprint: z.string().nullable(),
+    status: certificateStatusSchema.optional(),
+    used_by: z
+      .array(
+        z.object({
+          id: z.number(),
+          type: z.string(),
+        }),
+      )
+      .optional(),
+  })
+  .passthrough();
+
+/**
+ * List Certificates response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-certificates
+ */
+export const listCertificatesResponseSchema = z.object({
+  certificates: z.array(certificateSchema),
+  meta: z
+    .object({
+      pagination: paginationMetaSchema,
+    })
+    .optional(),
+});
+
+/**
+ * Create Certificate request schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-create-a-certificate
+ */
+export const createCertificateRequestSchema = z.object({
+  name: z.string().min(1),
+  type: certificateTypeSchema.optional(),
+  certificate: z.string().optional(),
+  private_key: z.string().optional(),
+  domain_names: z.array(z.string()).optional(),
+  labels: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Create Certificate response schema
+ */
+export const createCertificateResponseSchema = z.object({
+  certificate: certificateSchema,
+  action: actionSchema.nullable(),
+});
+
+/**
+ * Get Certificate response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-get-a-certificate
+ */
+export const getCertificateResponseSchema = z.object({
+  certificate: certificateSchema,
+});
+
+/**
+ * Update Certificate request schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-update-a-certificate
+ */
+export const updateCertificateRequestSchema = z.object({
+  name: z.string().min(1).optional(),
+  labels: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Update Certificate response schema
+ */
+export const updateCertificateResponseSchema = z.object({
+  certificate: certificateSchema,
+});
+
+/**
+ * Delete Certificate response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-delete-a-certificate
+ */
+export const deleteCertificateResponseSchema = z.object({
+  action: actionSchema,
+});
+
+/**
+ * List Certificate Actions response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-actions-for-a-certificate
+ */
+export const listCertificateActionsResponseSchema = z.object({
+  actions: z.array(actionSchema),
+  meta: z
+    .object({
+      pagination: paginationMetaSchema,
+    })
+    .optional(),
+});
+
+/**
+ * Get Certificate Action response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-get-an-action-for-a-certificate
+ */
+export const getCertificateActionResponseSchema = z.object({
+  action: actionSchema,
+});
+
+/**
+ * Retry Certificate Issuance/Renewal response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-retry-issuance-or-renewal
+ */
+export const retryCertificateIssuanceResponseSchema = z.object({
+  action: actionSchema,
+});

package/src/apis/certificates/types.ts

@@ -0,0 +1,176 @@
+/**
+ * Types for Hetzner Cloud Certificates API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  certificateStatusSchema,
+  certificateTypeSchema,
+  listCertificatesResponseSchema,
+  createCertificateRequestSchema,
+  createCertificateResponseSchema,
+  getCertificateResponseSchema,
+  updateCertificateRequestSchema,
+  updateCertificateResponseSchema,
+  deleteCertificateResponseSchema,
+  listCertificateActionsResponseSchema,
+  getCertificateActionResponseSchema,
+  retryCertificateIssuanceResponseSchema,
+  certificateSchema,
+} from "../../apis/certificates/schemas";
+import { actionSchema } from "../../apis/actions/schemas";
+import type { z } from "zod";
+
+/**
+ * Certificate status values
+ */
+export type CertificateStatus = z.infer<typeof certificateStatusSchema>;
+
+/**
+ * Certificate type values
+ */
+export type CertificateType = z.infer<typeof certificateTypeSchema>;
+
+/**
+ * Hetzner Cloud Certificate
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-certificates
+ */
+export type Certificate = z.infer<typeof certificateSchema>;
+
+/**
+ * Pagination metadata
+ * @see https://docs.hetzner.cloud/reference/cloud#pagination
+ * Re-exported from servers module for consistency
+ */
+export type { PaginationMeta } from "../../apis/servers/types";
+
+/**
+ * Action information
+ * Re-exported from servers module for consistency
+ */
+export type Action = z.infer<typeof actionSchema>;
+
+/**
+ * List Certificates query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-certificates
+ */
+export interface ListCertificatesParams {
+  /**
+   * Can be used to filter Certificates by their name. The response will only contain the Certificate matching the specified name.
+   */
+  name?: string;
+  /**
+   * Can be used to filter Certificates by labels. The response will only contain Certificates 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
+   * @see https://docs.hetzner.cloud/reference/cloud#sorting
+   */
+  sort?: string | string[];
+  /**
+   * Can be used multiple times. The response will only contain Certificates matching the specified type.
+   * Choices: uploaded, managed
+   */
+  type?: CertificateType | CertificateType[];
+  /**
+   * 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 Certificates response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-certificates
+ */
+export type ListCertificatesResponse = z.infer<typeof listCertificatesResponseSchema>;
+
+/**
+ * Create Certificate request parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-create-a-certificate
+ */
+export type CreateCertificateParams = z.infer<typeof createCertificateRequestSchema>;
+
+/**
+ * Create Certificate response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-create-a-certificate
+ */
+export type CreateCertificateResponse = z.infer<typeof createCertificateResponseSchema>;
+
+/**
+ * Get Certificate response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-get-a-certificate
+ */
+export type GetCertificateResponse = z.infer<typeof getCertificateResponseSchema>;
+
+/**
+ * Update Certificate request parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-update-a-certificate
+ */
+export type UpdateCertificateParams = z.infer<typeof updateCertificateRequestSchema>;
+
+/**
+ * Update Certificate response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-update-a-certificate
+ */
+export type UpdateCertificateResponse = z.infer<typeof updateCertificateResponseSchema>;
+
+/**
+ * Delete Certificate response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-delete-a-certificate
+ */
+export type DeleteCertificateResponse = z.infer<typeof deleteCertificateResponseSchema>;
+
+/**
+ * List Certificate Actions query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-actions-for-a-certificate
+ */
+export interface ListCertificateActionsParams {
+  /**
+   * Can be used multiple times. The response will only contain Actions matching the specified IDs.
+   */
+  id?: number | number[];
+  /**
+   * Can be used multiple times. The response will only contain Actions matching the specified status.
+   * Choices: running, success, error
+   */
+  status?: "running" | "success" | "error" | Array<"running" | "success" | "error">;
+  /**
+   * 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[];
+  /**
+   * 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 Certificate Actions response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-list-actions-for-a-certificate
+ */
+export type ListCertificateActionsResponse = z.infer<typeof listCertificateActionsResponseSchema>;
+
+/**
+ * Get Certificate Action response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-get-an-action-for-a-certificate
+ */
+export type GetCertificateActionResponse = z.infer<typeof getCertificateActionResponseSchema>;
+
+/**
+ * Retry Certificate Issuance/Renewal response
+ * @see https://docs.hetzner.cloud/reference/cloud#certificates-retry-issuance-or-renewal
+ */
+export type RetryCertificateIssuanceResponse = z.infer<typeof retryCertificateIssuanceResponseSchema>;

package/src/apis/common/schemas.ts

@@ -0,0 +1,19 @@
+/**
+ * Common Zod schemas shared across multiple API modules
+ * @see https://docs.hetzner.cloud/reference/cloud#pagination
+ */
+
+import { z } from "zod";
+
+/**
+ * Pagination metadata schema
+ * @see https://docs.hetzner.cloud/reference/cloud#pagination
+ */
+export const paginationMetaSchema = z.object({
+  page: z.number(),
+  per_page: z.number(),
+  previous_page: z.number().nullable(),
+  next_page: z.number().nullable(),
+  last_page: z.number(),
+  total_entries: z.number(),
+});