@nilovonjs/hcloud-js 1.0.0

package/README.md

@@ -0,0 +1,90 @@
+# @nilovonjs/hcloud-js
+
+TypeScript SDK for the Hetzner Cloud API - Fully typed, validated, and easy to use.
+
+## Installation
+
+```bash
+npm install @nilovonjs/hcloud-js
+# or
+yarn add @nilovonjs/hcloud-js
+# or
+pnpm add @nilovonjs/hcloud-js
+# or
+bun add @nilovonjs/hcloud-js
+```
+
+## Quick Start
+
+```typescript
+import { HCloudClient } from '@nilovonjs/hcloud-js';
+
+const client = new HCloudClient({
+  token: 'your-api-token'
+});
+
+// List all servers
+const servers = await client.servers.list();
+console.log(`Found ${servers.servers.length} server(s)`);
+
+// Get a specific server
+const server = await client.servers.get(12345);
+console.log(server.server.name);
+
+// Create a new server
+const newServer = await client.servers.create({
+  name: 'my-server',
+  server_type: 'cpx11',
+  image: 'ubuntu-22.04',
+  location: 'nbg1'
+});
+```
+
+## Features
+
+- ✅ **Fully Typed** - Complete TypeScript types for all API endpoints
+- ✅ **Validated** - Built-in validation using Zod schemas
+- ✅ **Easy to Use** - Simple, intuitive API
+- ✅ **Complete Coverage** - All Hetzner Cloud API endpoints supported
+- ✅ **Well Documented** - Comprehensive documentation with examples
+
+## Supported APIs
+
+- Servers
+- Images
+- Actions
+- Certificates
+- SSH Keys
+- Locations
+- Firewalls
+- Floating IPs
+- ISOs
+- Placement Groups
+- Primary IPs
+- Server Types
+- Load Balancers
+- Networks
+- Pricing
+- Volumes
+- DNS (Zones)
+
+## Documentation
+
+Full documentation is available at: [https://hcloud-js.nilovon.com](https://hcloud-js.nilovon.com)
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0.0
+
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for a list of changes.
+
+## License
+
+MIT © [Nilovon](https://github.com/Nilovon)

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@nilovonjs/hcloud-js",
+  "version": "1.0.0",
+  "description": "TypeScript SDK for the Hetzner Cloud API - Fully typed, validated, and easy to use",
+  "author": "Nilovon",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "module": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "hetzner",
+    "hetzner-cloud",
+    "hcloud",
+    "cloud",
+    "api",
+    "sdk",
+    "typescript",
+    "types",
+    "servers",
+    "networks",
+    "load-balancer",
+    "dns",
+    "infrastructure"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nilovon/hcloud-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Nilovon/hcloud-js/issues"
+  },
+  "homepage": "https://hcloud-js.nilovon.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": false
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Running prepublish checks...' && exit 0"
+  }
+}

package/src/apis/actions/index.ts

@@ -0,0 +1,113 @@
+/**
+ * Hetzner Cloud Actions API
+ * @see https://docs.hetzner.cloud/reference/cloud#actions
+ */
+
+import type { HCloudClient } from "../../client/index";
+import type {
+  ListActionsParams,
+  ListActionsResponse,
+  GetActionResponse,
+} from "../../apis/actions/types";
+import { validate } from "../../validation/index";
+import {
+  listActionsResponseSchema,
+  getActionResponseSchema,
+} from "../../apis/actions/schemas";
+
+/**
+ * Actions API client
+ */
+export class ActionsClient {
+  constructor(private readonly client: HCloudClient) {}
+
+  /**
+   * Returns all Action objects.
+   *
+   * ⚠️ **Note:** As of 2025-01-30, the Hetzner Cloud API removed the ability to list arbitrary actions.
+   * This endpoint may return a 410 error. Actions should be retrieved individually by ID
+   * (typically obtained from resource operations).
+   *
+   * @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#actions-get-multiple-actions
+   * @see https://docs.hetzner.cloud/changelog#2025-01-30-listing-arbitrary-actions-in-the-actions-list-endpoint-is-removed
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Note: This may fail with 410 error
+   * // Use client.actions.get(id) instead with an action ID from a resource operation
+   * try {
+   *   const result = await client.actions.list();
+   * } catch (error) {
+   *   // Handle 410 error (deprecated endpoint)
+   * }
+   * ```
+   * @deprecated This endpoint may be deprecated. Use {@link ActionsClient.get} with an action ID instead.
+   */
+  async list(params?: ListActionsParams): Promise<ListActionsResponse> {
+    // Build query parameters
+    const queryParams: Record<string, string | number | string[] | undefined> = {};
+
+    if (params?.id !== undefined) {
+      // Convert id(s) to array of strings for query params
+      const ids = Array.isArray(params.id) ? params.id : [params.id];
+      queryParams.id = ids.map(String);
+    }
+
+    if (params?.status) {
+      // Convert single status to array for consistent handling
+      queryParams.status = Array.isArray(params.status) ? params.status : [params.status];
+    }
+
+    if (params?.sort) {
+      // Convert single string to array for consistent handling
+      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>("/actions", queryParams);
+
+    // Validate response with Zod
+    return validate(listActionsResponseSchema, response, {
+      context: "List actions response",
+      detailed: true,
+    });
+  }
+
+  /**
+   * Returns a specific Action object.
+   *
+   * @param id - ID of the Action
+   * @returns Promise resolving to the action
+   * @see https://docs.hetzner.cloud/reference/cloud#actions-get-an-action
+   *
+   * @example
+   * ```typescript
+   * const client = new HCloudClient({ token: 'your-token' });
+   *
+   * // Get an action by ID
+   * const action = await client.actions.get(12345);
+   * console.log(action.action.command);
+   * console.log(action.action.status);
+   * ```
+   */
+  async get(id: number): Promise<GetActionResponse> {
+    const response = await this.client.get<unknown>(`/actions/${id}`);
+
+    // Validate response with Zod
+    return validate(getActionResponseSchema, response, {
+      context: "Get action response",
+      detailed: true,
+    });
+  }
+}

package/src/apis/actions/schemas.ts

@@ -0,0 +1,59 @@
+/**
+ * Zod schemas for Hetzner Cloud Actions API
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-multiple-actions
+ */
+
+import { z } from "zod";
+import { paginationMetaSchema } from "../common/schemas";
+
+/**
+ * Action resource schema
+ * Common schema for action resources
+ */
+export const actionResourceSchema = z.object({
+  id: z.number(),
+  type: z.string(),
+});
+
+/**
+ * Action schema
+ * Common schema for all Hetzner Cloud Actions
+ */
+export const actionSchema = z
+  .object({
+    id: z.number(),
+    command: z.string(),
+    status: z.enum(["running", "success", "error"]),
+    progress: z.number(),
+    started: z.string(),
+    finished: z.string().nullable(),
+    resources: z.array(actionResourceSchema),
+    error: z
+      .object({
+        code: z.string(),
+        message: z.string(),
+      })
+      .nullable(),
+  })
+  .passthrough();
+
+/**
+ * List Actions response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-multiple-actions
+ */
+export const listActionsResponseSchema = z.object({
+  actions: z.array(actionSchema),
+  meta: z
+    .object({
+      pagination: paginationMetaSchema,
+    })
+    .optional(),
+});
+
+/**
+ * Get Action response schema
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-an-action
+ */
+export const getActionResponseSchema = z.object({
+  action: actionSchema,
+});

package/src/apis/actions/types.ts

@@ -0,0 +1,77 @@
+/**
+ * Types for Hetzner Cloud Actions API
+ * Types are inferred from Zod schemas
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-multiple-actions
+ */
+
+// biome-ignore assist/source/organizeImports: we need to import the schemas first
+import {
+  listActionsResponseSchema,
+  getActionResponseSchema,
+} from "../../apis/actions/schemas";
+import { actionSchema, actionResourceSchema } from "../../apis/actions/schemas";
+import type { z } from "zod";
+
+/**
+ * Action resource information
+ */
+export type ActionResource = z.infer<typeof actionResourceSchema>;
+
+/**
+ * Hetzner Cloud Action
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-multiple-actions
+ */
+export type Action = z.infer<typeof actionSchema>;
+
+/**
+ * Action status values
+ */
+export type ActionStatus = "running" | "success" | "error";
+
+/**
+ * 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 Actions query parameters
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-multiple-actions
+ */
+export interface ListActionsParams {
+  /**
+   * 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?: ActionStatus | ActionStatus[];
+  /**
+   * 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 Actions response
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-multiple-actions
+ */
+export type ListActionsResponse = z.infer<typeof listActionsResponseSchema>;
+
+/**
+ * Get Action response
+ * @see https://docs.hetzner.cloud/reference/cloud#actions-get-an-action
+ */
+export type GetActionResponse = z.infer<typeof getActionResponseSchema>;