@uninspired/hetzner-dns-client

A TypeScript client for the Hetzner Cloud DNS API.

Installation

npm install @uninspired/hetzner-dns-client

Usage

Creating a client

import { HetznerDnsClient } from "@uninspired/hetzner-dns-client";

const client = new HetznerDnsClient("YOUR_API_TOKEN");

Using the client

const zones = await client.listZones();

Queries, params and request body can be defined by providing an object to the method. These object keys can be optional or required depending on the endpoint. See the API Docs for more information.

Error handling

Errors are automatically parsed and thrown as an Error object in accordance to the API definition.

The isError function can be used to check if an object is an Error object.

try {
  const zones = await client.listZones();
} catch (e) {
  if (isError(e)) {
    console.error(e.code, e.message, e.details);
  } else {
    console.error(e);
  }
}

Querying

Label Selector

Hetzner's Cloud API supports querying using the label_selector search parameter (see here) on some endpoints. A single label can be queried as a string, multiple labels can be querieds as an array of strings.

Single query example:

const zones = await client.listZones({
  query: {
    label_selector: "key=value",
  },
});

Multiple query example:

const zones = await client.listZones({
  query: {
    label_selector: ["key=value", "key2=value2"],
  },
});

Sorting

Hetzner's Cloud API also supports sorting using the sort search parameter (see here) on some endpoints.

The keys that are queryable are automatically extracted from the response type.

Single sort keys can be queried by using a string:

const zones = await client.listZones({
  query: {
    sort: "name:desc",
  },
});

Multiple sort keys can be queried by using an array of strings:

const zones = await client.listZones({
  query: {
    sort: ["name:desc", "created:asc"],
  },
});

Zones

List zones

const { zones, meta } = await client.listZones();

Create zone

const { zone } = await client.createZone({
  body: {
    name: "YOUR_ZONE_NAME",
    mode: "primary",
    ttl: 3600,
    labels: {
      key: "value",
    },
    primary_nameservers: [
      {
        address: "ns1.hetzner.de",
        port: 53,
        tsig_key: "YOUR_TSIG_KEY",
        tsig_algorithm: "hmac-md5",
      },
    ],
    rrsets: [],
    zonefile: "",
  },
});

Get zone

const { zone } = await client.getZone({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
});

Update zone

const { zone } = await client.updateZone({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
  body: {
    labels: {
      key: "value",
    },
  },
});

Delete zone

const { action } = await client.deleteZone({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
});

Export zone file

const { zonefile } = await client.exportZoneFile({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
});

Zone Actions

List all zone actions

const { actions, meta } = await client.listAllZoneActions();

Get zone action

const { action } = await client.getZoneAction({
  params: {
    id: 1234,
  },
});

List zone actions

const { actions, meta } = await client.listZoneActions({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
});

Get action for zone

const { action } = await client.getActionForZone({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    action_id: 1234,
  },
});

Change zone primary nameservers

const { action } = await client.changeZonePrimaryNameservers({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
  body: {
    primary_nameservers: [
      {
        address: "ns1.hetzner.de",
        port: 53,
        tsig_key: "YOUR_TSIG_KEY",
        tsig_algorithm: "hmac-md5",
      },
    ],
  },
});

Change zone protection

const { action } = await client.changeZoneProtection({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
  body: {
    delete: true,
  },
});

Change zone default ttl

const { action } = await client.changeZoneDefaultTtl({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
  body: {
    ttl: 3600,
  },
});

Import zone file

const { action } = await client.importZoneFile({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
  body: {
    zonefile: "YOUR_ZONEFILE",
  },
});

RR Sets

List RRSets

const { rrsets, meta } = await client.listRRSets({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
});

Create RRSet

const { rrset } = await client.createRRSet({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
  },
  body: {
    name: "YOUR_RRSET_NAME",
    type: "A",
    ttl: 3600,
    records: [
      {
        value: "127.0.0.1",
      },
    ],
    labels: {
      key: "value",
    },
  },
});

Get RRSet

const { rrset } = await client.getRRSet({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
});

Update RRSet

const { rrset } = await client.updateRRSet({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
  body: {
    labels: {
      key: "value",
    },
  },
});

Delete RRSet

const { action } = await client.deleteRRSet({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
});

RRSet Actions

Change RRSet protection

const { action } = await client.changeRRSetProtection({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
  body: {
    change: true,
  },
});

Change RRSet ttl

const { action } = await client.changeRRSetTtl({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
  body: {
    ttl: 3600,
  },
});

Set RRSet records

const { action } = await client.setRRSetRecords({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
  body: {
    records: [
      {
        value: "127.0.0.1",
      },
    ],
  },
});

Add RRSet records

const { action } = await client.addRRSetRecords({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
  body: {
    ttl: 3600,
    records: [
      {
        value: "127.0.0.1",
      },
    ],
  },
});

Remove RRSet records

const { action } = await client.removeRRSetRecords({
  params: {
    id_or_name: "YOUR_ZONE_ID_OR_NAME",
    rr_name: "YOUR_RRSET_NAME",
    rr_type: "A",
  },
  body: {
    records: [
      {
        value: "127.0.0.1",
      },
    ],
  },
});