hetznercloud/readme.md

# @apiclient.xyz/hetznercloud
An unofficial API client for the Hetzner Cloud API

## Install

You can install the `@apiclient.xyz/hetznercloud` package via npm:

```bash
npm install @apiclient.xyz/hetznercloud
```

Or using yarn:

```bash
yarn add @apiclient.xyz/hetznercloud
```

## Usage

The `@apiclient.xyz/hetznercloud` package provides a modern approach to interact with the Hetzner Cloud API. Below are some detailed examples demonstrating the usage of this package for different scenarios like managing accounts, servers, volumes, and firewalls. 

### Initial Setup

To begin using the package, you need to import it and initialize your Hetzner account with an API token:

```typescript
import { HetznerAccount, HetznerServer, Volume, HetznerFirewall } from '@apiclient.xyz/hetznercloud';

// Initialize Hetzner account
const myHetznerAccount = new HetznerAccount('yourHetznerApiToken');
```

### Managing Servers

#### Creating a Server

You can create a new server using the `createServer` method in the `HetznerAccount` class. Provide the necessary options such as name, type, location, labels, and optional user data:

```typescript
const newServer = await myHetznerAccount.createServer({
  name: 'my-server',
  type: 'cpx31',
  location: 'nbg1',
  labels: {
    purpose: 'test'
  },
  userData: '#!/bin/bash\necho Hello from your new server!'
});

console.log('New server details:', newServer.data);
```

#### Listing Servers

To list all servers in your account, you can use the `getServers` method:

```typescript
const servers = await myHetznerAccount.getServers();
console.log('Current servers:', servers);
```

#### Filtering Servers by Labels

You can filter servers based on specific labels:

```typescript
const filteredServers = await myHetznerAccount.getServersByLabel({ purpose: 'test' });
console.log('Filtered servers:', filteredServers);
```

#### Deleting a Server

To delete a server, call the `delete` method on the server instance:

```typescript
const serverToDelete = filteredServers[0]; // Example, choose the first filtered server
await serverToDelete.delete();
console.log('Server deleted successfully');
```

### Managing Volumes

#### Creating a Volume

To create a new volume, use the `Volume.create` method, passing in the necessary options:

```typescript
const newVolume = await Volume.create(myHetznerAccount, {
  name: 'my-volume',
  size: 10, // Size in GB
  location: 'nbg1',
  labels: {
    purpose: 'test-volume'
  },
  server: newServer // Attach the volume to a specific server (newServer in this case)
});

console.log('New volume details:', newVolume.data);
```

#### Listing Volumes

You can list all volumes in your account with the `getVolumes` method:

```typescript
const volumes = await Volume.getVolumes(myHetznerAccount);
console.log('Current volumes:', volumes);
```

#### Filtering Volumes by Labels

To filter volumes based on specific labels:

```typescript
const filteredVolumes = await Volume.getVolumesByLabel(myHetznerAccount, { purpose: 'test-volume' });
console.log('Filtered volumes:', filteredVolumes);
```

#### Deleting a Volume

To delete a volume, call the `delete` method on the volume instance:

```typescript
const volumeToDelete = filteredVolumes[0]; // Example, choose the first filtered volume
await volumeToDelete.delete();
console.log('Volume deleted successfully');
```

### Managing Firewalls

#### Creating a Firewall

To create a new firewall, use the `create` method in the `HetznerFirewall` class:

```typescript
const newFirewall = await HetznerFirewall.create(myHetznerAccount, {
  name: 'my-firewall',
  labels: {
    purpose: 'test-firewall'
  },
  rules: [
    {
      direction: 'in',
      protocol: 'tcp',
      port: '80',
      source_ips: ['0.0.0.0/0', '::/0']
    },
    {
      direction: 'in',
      protocol: 'tcp',
      port: '443',
      source_ips: ['0.0.0.0/0', '::/0']
    }
  ]
});

console.log('New firewall details:', newFirewall.data);
```

#### Listing Firewalls

To list all firewalls in your account:

```typescript
const firewalls = await HetznerFirewall.getFirewalls(myHetznerAccount);
console.log('Current firewalls:', firewalls);
```

#### Filtering Firewalls by Labels

To filter firewalls based on specific labels:

```typescript
const filteredFirewalls = await HetznerFirewall.getFirewallsByLabel(myHetznerAccount, { purpose: 'test-firewall' });
console.log('Filtered firewalls:', filteredFirewalls);
```

#### Deleting a Firewall

To delete a firewall, call the `delete` method on the firewall instance:

```typescript
const firewallToDelete = filteredFirewalls[0]; // Example, choose the first filtered firewall
await firewallToDelete.delete();
console.log('Firewall deleted successfully');
```

### Example: Full Lifecycle Management

Here is a complete example that demonstrates the full lifecycle of creating, listing, filtering, and deleting servers, volumes, and firewalls:

```typescript
import { HetznerAccount, HetznerServer, Volume, HetznerFirewall } from '@apiclient.xyz/hetznercloud';

// Initialize Hetzner account
const myHetznerAccount = new HetznerAccount('yourHetznerApiToken');

// Step 1: Create a new server
const newServer = await myHetznerAccount.createServer({
  name: 'my-server',
  type: 'cpx31',
  location: 'nbg1',
  labels: { purpose: 'test' },
  userData: '#!/bin/bash\necho Hello from your new server!'
});
console.log('New server created:', newServer.data);

// Step 2: Create a new volume and attach it to the server
const newVolume = await Volume.create(myHetznerAccount, {
  name: 'my-volume',
  size: 10, // GB
  location: 'nbg1',
  labels: { purpose: 'test-volume' },
  server: newServer
});
console.log('New volume created:', newVolume.data);

// Step 3: Create a new firewall and attach rules to it
const newFirewall = await HetznerFirewall.create(myHetznerAccount, {
  name: 'my-firewall',
  labels: { purpose: 'test-firewall' },
  rules: [
    { direction: 'in', protocol: 'tcp', port: '80', source_ips: ['0.0.0.0/0', '::/0'] },
    { direction: 'in', protocol: 'tcp', port: '443', source_ips: ['0.0.0.0/0', '::/0'] }
  ]
});
console.log('New firewall created:', newFirewall.data);

// Step 4: List all servers, volumes, and firewalls
const servers = await myHetznerAccount.getServers();
console.log('All servers:', servers);

const volumes = await Volume.getVolumes(myHetznerAccount);
console.log('All volumes:', volumes);

const firewalls = await HetznerFirewall.getFirewalls(myHetznerAccount);
console.log('All firewalls:', firewalls);

// Step 5: Filter servers, volumes, and firewalls by labels
const filteredServers = await myHetznerAccount.getServersByLabel({ purpose: 'test' });
console.log('Filtered servers:', filteredServers);

const filteredVolumes = await Volume.getVolumesByLabel(myHetznerAccount, { purpose: 'test-volume' });
console.log('Filtered volumes:', filteredVolumes);

const filteredFirewalls = await HetznerFirewall.getFirewallsByLabel(myHetznerAccount, { purpose: 'test-firewall' });
console.log('Filtered firewalls:', filteredFirewalls);

// Step 6: Cleanup - Delete created resources
for (const server of filteredServers) {
  await server.delete();
  console.log('Server deleted:', server.data);
}

for (const volume of filteredVolumes) {
  await volume.delete();
  console.log('Volume deleted:', volume.data);
}

for (const firewall of filteredFirewalls) {
  await firewall.delete();
  console.log('Firewall deleted:', firewall.data);
}
```

This comprehensive example demonstrates how you can manage your Hetzner resources using the `@apiclient.xyz/hetznercloud` package efficiently and effectively.
undefined