@modexvpn/hcloud

A clean, type-safe SDK for the Hetzner Cloud API using Node.js, TypeScript, and Zod.

Features

• 🔐 Zod-powered runtime validation — fully JavaScript-safe
• 🧠 Fully type-safe using TypeScript with z.infer<> and enums
• 📆 Modular structure: hcloud.servers.list(), hcloud.locations.getById()
• ⚠️ Centralized error handling with formatHcloudError()
• ⚙️ Axios-based HTTP client with auto-authentication
• 🔁 ESM and CommonJS compatible
• 🗂️ Clean folder structure for scalability and maintainability

SDK Status

This SDK is stable, but not yet feature-complete.
We're already on v1.x and will maintain backward compatibility.
Any breaking changes will be released as v2.0.0.

🚀 What's New in v1.4

• createSSHKey(options) — Create a new SSH key
• getSSHKeys() — List all SSH keys
• getSSHKey(id) — Get a single SSH key by ID
• updateSSHKey(id, options) — Update an existing SSH key
• deleteSSHKey(id) — Delete an SSH key

✍️ Usage Examples

Create SSH Key

const sshKey = await hcloud.security.createSSHKey({
  name: "modex-prod-key",
  public_key: "ssh-ed25519 AAAAC3N...",
  labels: { environment: "prod" }
})

List SSH Keys

const allKeys = await hcloud.security.listSSHKeys()

Get SSH Key by ID

const key = await hcloud.security.getSSHKey(12345)

Update SSH Key

const updated = await hcloud.security.updateSSHKey(12345, {
  name: "modex-updated-key",
  labels: { updated: "true" }
})

Delete SSH Key

await hcloud.security.deleteSSHKey(12345)

📆 Installation

npm install @modexvpn/hcloud

🧠 Usage

List all servers

import { hcloud } from '@modexvpn/hcloud'

const servers = await hcloud.servers.list()

Get a single server by ID

const server = await hcloud.servers.getById(123456)

Fetch server metrics

const metrics = await hcloud.servers.getMetrics(123456)

Power control

await hcloud.servers.powerControl.off(123456)
await hcloud.servers.powerControl.reboot(123456)
await hcloud.servers.powerControl.on(123456)
await hcloud.servers.powerControl.reset(123456)
await hcloud.servers.powerControl.shutdown(123456)

Create a server

await hcloud.servers.create({
  name: 'test-server',
  server_type: 'cx21',
  image: 'ubuntu-22.04',
  location: 'nbg1',
  ssh_keys: ['ssh-key-id'],
})

Delete a server

await hcloud.servers.delete(123456)

SSH Into Server

const { stdout } = await sshIntoServer("192.168.1.100", "apt update && apt upgrade -y", "root")
console.log(stdout)

💡 Requires SSH_PRIVATE_KEY in your environment

🔢 Environment Setup

Create a .env file and add your Hetzner API token:

HCLOUD_API_TOKEN=your-token-here

📁 Project Structure

@modexvpn/hcloud
├── client.ts
├── index.ts
├── sdk/
│   ├── servers/
│   │   ├── actions/
│   │   │   └── sshIntoServer.ts
│   │   ├── createServer.ts
│   │   └── server-type/
│   │       ├── getServerTypes.ts
│   │       ├── getServerType.ts
│   │       └── index.ts
│   └── locations/
│       └── datacenters/
│           ├── getDatacenters.ts
│           └── getDatacenter.ts
├── types/
│   ├── common/
│   ├── enums/
│   ├── errors/
│   ├── ...
├── utils/
│   └── formatError.ts
├── tsconfig.json
├── tsup.config.ts
├── README.md

🔫 API Coverage

Core Resources

• [x] Errors
• [x] Servers
  • [~] Actions
  • [x] Types
• [x] Locations
  • [x] Datacenters
• [ ] Actions

Security

• [x] SSH Keys
• [ ] Certificates

Storage & Networking

• [ ] Volumes
• [ ] Networks

Firewalls & IPs

• [ ] Firewalls
• [ ] Floating IPs

Load Balancers

• [ ] Load Balancers

Billing

• [ ] Pricing

📝 Contributing

PRs welcome! Please follow the existing structure and run:

npm run lint
npm run build

📄 Resources

• Hetzner Cloud API Docs

👉 License

MIT © 2025 MODEX