@nilovonjs/hcloud-js 1.0.0

package/src/apis/ssh-keys/index.ts

@@ -0,0 +1,204 @@
+/**
+ * Hetzner Cloud SSH Keys API
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys
+ */
+
+import type { HCloudClient } from "../../client/index";
+import type {
+  ListSSHKeysParams,
+  ListSSHKeysResponse,
+  CreateSSHKeyParams,
+  CreateSSHKeyResponse,
+  GetSSHKeyResponse,
+  UpdateSSHKeyParams,
+  UpdateSSHKeyResponse,
+  DeleteSSHKeyResponse,
+} from "../../apis/ssh-keys/types";
+import { validate } from "../../validation/index";
+import {
+  listSSHKeysResponseSchema,
+  createSSHKeyRequestSchema,
+  createSSHKeyResponseSchema,
+  getSSHKeyResponseSchema,
+  updateSSHKeyRequestSchema,
+  updateSSHKeyResponseSchema,
+  deleteSSHKeyResponseSchema,
+} from "../../apis/ssh-keys/schemas";
+
+/**
+ * SSH Keys API client
+ */
+export class SSHKeysClient {
+  constructor(private readonly client: HCloudClient) {}
+
+  /**
+   * Returns all SSH key objects.
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Promise resolving to list of SSH keys with pagination metadata
+   * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-list-ssh-keys
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // List all SSH keys
+   * const result = await client.sshKeys.list();
+   *
+   * // List SSH keys with filters
+   * const filtered = await client.sshKeys.list({
+   *   label_selector: 'environment=production',
+   *   sort: ['name:asc'],
+   *   page: 1,
+   *   per_page: 50
+   * });
+   * ```
+   */
+  async list(params?: ListSSHKeysParams): Promise<ListSSHKeysResponse> {
+    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?.fingerprint) {
+      queryParams.fingerprint = params.fingerprint;
+    }
+
+    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>("/ssh_keys", queryParams);
+
+    return validate(listSSHKeysResponseSchema, response, {
+      context: "List SSH keys response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Creates a new SSH key.
+   *
+   * @param params - Parameters for creating the SSH key
+   * @returns Promise resolving to the created SSH key
+   * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-create-an-ssh-key
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const result = await client.sshKeys.create({
+   *   name: 'my-ssh-key',
+   *   public_key: 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB...'
+   * });
+   * ```
+   */
+  async create(params: CreateSSHKeyParams): Promise<CreateSSHKeyResponse> {
+    const validatedParams = validate(createSSHKeyRequestSchema, params, {
+      context: "Create SSH key request",
+      detailed: true,
+    });
+
+    const response = await this.client.post<unknown>("/ssh_keys", validatedParams);
+
+    return validate(createSSHKeyResponseSchema, response, {
+      context: "Create SSH key response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Returns a specific SSH key object.
+   *
+   * @param id - ID of the SSH key
+   * @returns Promise resolving to the SSH key
+   * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-get-an-ssh-key
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const sshKey = await client.sshKeys.get(12345);
+   * console.log(sshKey.ssh_key.name);
+   * ```
+   */
+  async get(id: number): Promise<GetSSHKeyResponse> {
+    const response = await this.client.get<unknown>(`/ssh_keys/${id}`);
+
+    return validate(getSSHKeyResponseSchema, response, {
+      context: "Get SSH key response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Updates an SSH key.
+   *
+   * You can update an SSH key's name and labels.
+   *
+   * @param id - ID of the SSH key
+   * @param params - Parameters to update (name and/or labels)
+   * @returns Promise resolving to the updated SSH key
+   * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-update-an-ssh-key
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const updated = await client.sshKeys.update(12345, {
+   *   name: 'new-ssh-key-name',
+   *   labels: { environment: 'production' }
+   * });
+   * ```
+   */
+  async update(id: number, params: UpdateSSHKeyParams): Promise<UpdateSSHKeyResponse> {
+    const validatedParams = validate(updateSSHKeyRequestSchema, params, {
+      context: "Update SSH key request",
+      detailed: true,
+    });
+
+    const response = await this.client.put<unknown>(`/ssh_keys/${id}`, validatedParams);
+
+    return validate(updateSSHKeyResponseSchema, response, {
+      context: "Update SSH key response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Deletes an SSH key.
+   *
+   * @param id - ID of the SSH key
+   * @returns Promise resolving to the delete action
+   * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-delete-an-ssh-key
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * const result = await client.sshKeys.delete(12345);
+   * console.log(`Delete action ID: ${result.action.id}`);
+   * ```
+   */
+  async delete(id: number): Promise<DeleteSSHKeyResponse> {
+    const response = await this.client.delete<unknown>(`/ssh_keys/${id}`);
+
+    return validate(deleteSSHKeyResponseSchema, response, {
+      context: "Delete SSH key response",
+      detailed: true,
+    });
+  }
+}

package/src/apis/ssh-keys/schemas.ts

@@ -0,0 +1,84 @@
+/**
+ * Zod schemas for Hetzner Cloud SSH Keys API
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys
+ */
+
+import { z } from "zod";
+import { actionSchema } from "../../apis/actions/schemas";
+import { paginationMetaSchema } from "../../apis/common/schemas";
+
+/**
+ * SSH Key schema
+ */
+export const sshKeySchema = z
+  .object({
+    id: z.number(),
+    name: z.string(),
+    fingerprint: z.string(),
+    public_key: z.string(),
+    labels: z.record(z.string(), z.string()),
+    created: z.string(),
+  })
+  .passthrough();
+
+/**
+ * List SSH Keys response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-list-ssh-keys
+ */
+export const listSSHKeysResponseSchema = z.object({
+  ssh_keys: z.array(sshKeySchema),
+  meta: z
+    .object({
+      pagination: paginationMetaSchema,
+    })
+    .optional(),
+});
+
+/**
+ * Create SSH Key request schema
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-create-an-ssh-key
+ */
+export const createSSHKeyRequestSchema = z.object({
+  name: z.string().min(1),
+  public_key: z.string().min(1),
+  labels: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Create SSH Key response schema
+ */
+export const createSSHKeyResponseSchema = z.object({
+  ssh_key: sshKeySchema,
+});
+
+/**
+ * Get SSH Key response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-get-an-ssh-key
+ */
+export const getSSHKeyResponseSchema = z.object({
+  ssh_key: sshKeySchema,
+});
+
+/**
+ * Update SSH Key request schema
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-update-an-ssh-key
+ */
+export const updateSSHKeyRequestSchema = z.object({
+  name: z.string().min(1).optional(),
+  labels: z.record(z.string(), z.string()).optional(),
+});
+
+/**
+ * Update SSH Key response schema
+ */
+export const updateSSHKeyResponseSchema = z.object({
+  ssh_key: sshKeySchema,
+});
+
+/**
+ * Delete SSH Key response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-delete-an-ssh-key
+ */
+export const deleteSSHKeyResponseSchema = z.object({
+  action: actionSchema,
+});

package/src/apis/ssh-keys/types.ts

@@ -0,0 +1,106 @@
+/**
+ * Types for Hetzner Cloud SSH Keys API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  listSSHKeysResponseSchema,
+  createSSHKeyRequestSchema,
+  createSSHKeyResponseSchema,
+  getSSHKeyResponseSchema,
+  updateSSHKeyRequestSchema,
+  updateSSHKeyResponseSchema,
+  deleteSSHKeyResponseSchema,
+  sshKeySchema,
+} from "../../apis/ssh-keys/schemas";
+import type { z } from "zod";
+
+/**
+ * Hetzner Cloud SSH Key
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-list-ssh-keys
+ */
+export type SSHKey = z.infer<typeof sshKeySchema>;
+
+/**
+ * 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 SSH Keys query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-list-ssh-keys
+ */
+export interface ListSSHKeysParams {
+  /**
+   * Can be used to filter SSH Keys by their name. The response will only contain the SSH Key matching the specified name.
+   */
+  name?: string;
+  /**
+   * Can be used to filter SSH Keys by labels. The response will only contain SSH Keys 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 to filter SSH Keys by their fingerprint. The response will only contain the SSH Key matching the specified fingerprint.
+   */
+  fingerprint?: 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 SSH Keys response
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-list-ssh-keys
+ */
+export type ListSSHKeysResponse = z.infer<typeof listSSHKeysResponseSchema>;
+
+/**
+ * Create SSH Key request parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-create-an-ssh-key
+ */
+export type CreateSSHKeyParams = z.infer<typeof createSSHKeyRequestSchema>;
+
+/**
+ * Create SSH Key response
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-create-an-ssh-key
+ */
+export type CreateSSHKeyResponse = z.infer<typeof createSSHKeyResponseSchema>;
+
+/**
+ * Get SSH Key response
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-get-an-ssh-key
+ */
+export type GetSSHKeyResponse = z.infer<typeof getSSHKeyResponseSchema>;
+
+/**
+ * Update SSH Key request parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-update-an-ssh-key
+ */
+export type UpdateSSHKeyParams = z.infer<typeof updateSSHKeyRequestSchema>;
+
+/**
+ * Update SSH Key response
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-update-an-ssh-key
+ */
+export type UpdateSSHKeyResponse = z.infer<typeof updateSSHKeyResponseSchema>;
+
+/**
+ * Delete SSH Key response
+ * @see https://docs.hetzner.cloud/reference/cloud#ssh-keys-delete-an-ssh-key
+ */
+export type DeleteSSHKeyResponse = z.infer<typeof deleteSSHKeyResponseSchema>;