node-powerdns

node-powerdns (Node.js + TypeScript)

A typed PowerDNS Authoritative HTTP API client for Node.js.

This library wraps the PowerDNS API with a small, fetch-based client and exposes TypeScript types for the main Authoritative server resources. You can import the client as either the default export or the named Client export.

Features

API coverage

• Servers, config, metrics, zones, RRsets, views, networks, metadata, TSIG keys, cryptokeys, autoprimaries, search, statistics, and cache flush endpoints.
• Versioned API base path support through the version client option.
• Default server selection with automatic fallback to localhost.

Type safety

• Typed request and response models for common PowerDNS resources.
• Exported enums and helper types for zones, records, statistics, and related API payloads.
• Generic extra config field for attaching caller-specific metadata to a client instance.

Runtime model

• Uses the built-in fetch() available in modern Node.js.
• Allows an optional fetch override for custom transport behavior.
• Minimal abstraction over raw PowerDNS endpoints.
• JSON, text, and void response helpers for the different endpoint behaviors.

Package output

• ESM and CommonJS builds.
• Bundled declaration files.
• TypeDoc generation for hosted API docs.

Installation

npm install node-powerdns

Node.js 18 or newer is recommended because the client relies on the built-in fetch() API.

Quick start

1. Create a client

import { Client, Versions } from 'node-powerdns';

const client = new Client({
  baseUrl: 'http://127.0.0.1:8081',
  apiKey: process.env.POWERDNS_API_KEY!,
  version: '/api/v1',
  server: { id: 'localhost' }
});

Default import is also supported:

import PowerDNS, { Versions } from 'node-powerdns';

const client = new PowerDNS({
  baseUrl: 'http://127.0.0.1:8081',
  apiKey: process.env.POWERDNS_API_KEY!,
  version: '/api/v1'
});

2. Read server information

const server = await client.servers.get();

console.log(server.id);
console.log(server.version);

3. List zones

const zones = await client.zones().list({ dnssec: false });

for (const zone of zones) {
  console.log(zone.name, zone.kind);
}

4. More examples

• examples/create-record.example.ts
• examples/create-zone-with-record-comment.example.ts
• examples/delete-record.example.ts
• examples/list-zones.example.ts
• examples/update-record.example.ts
• examples/update-zone.example.ts

API Reference (high level)

new Client(config)

type ClientConfig<E = unknown> = {
  baseUrl: string;
  apiKey: string;
  version?: string;
  server?: { id: string };
  extra?: E;
  fetch?: typeof fetch;
  logger?: {
    error?: (error: { error: string; errors?: string[] }) => void;
  };
};

The client trims a trailing slash from baseUrl, defaults version to '/api/v1', and uses server.id = 'localhost' when no server is provided.

client.servers

await client.servers.list();
await client.servers.get();

Use this to enumerate available PowerDNS servers or inspect the configured default server.

client.zones(server?)

import { ZoneType } from 'node-powerdns';

const zones = client.zones();

await zones.list();
await zones.get({ id: 'example.org.' });
await zones.create({
  name: 'example.org.',
  kind: ZoneType.Native
});

The zone API also exposes helpers for updates, deletes, AXFR retrieval, notifications, export, rectify, and RRSet-level operations.

client.zones().rrset(zone, target)

await client
  .zones()
  .rrset({ id: 'example.org.' }, { name: 'www.example.org.', type: 'A', ttl: 300 })
  .create({
    record: { content: '203.0.113.10', disabled: false }
  });

Use the RRSet helper to create, update, or delete records inside an existing zone.

client.metrics.get()

const metrics = await client.metrics.get();
console.log(metrics);

This calls the webserver metrics endpoint and returns the raw text response.

Options

import { Versions, ZoneType, type ZoneCreateRequest, type ZoneUpdateRequest } from 'node-powerdns';

Notes

• baseUrl should point at the PowerDNS webserver root, for example http://127.0.0.1:8081.
• version defaults to '/api/v1'; set it explicitly if your deployment uses a different API path.
• server.id defaults to localhost if omitted.
• fetch can be supplied to override the internal HTTP implementation for all requests, including metrics.
• logger.error can be supplied to observe PowerDNS error payloads without forcing library-level console logging.
• Most methods throw the JSON error payload returned by PowerDNS when the API responds with a non-2xx status.

Common endpoints

This client exposes grouped API helpers:

• client.config
• client.servers
• client.metrics
• client.zones(server?)
• client.views
• client.networks
• client.cryptokeys
• client.metadata
• client.tsigkeys
• client.autoprimaries
• client.search
• client.statistics
• client.cache

Minimal example with manual inspection

import { Client, Versions } from 'node-powerdns';

const client = new Client({
  baseUrl: 'http://127.0.0.1:8081',
  apiKey: process.env.POWERDNS_API_KEY!,
  version: '/api/v1'
});

const zone = await client.zones().get({ id: 'example.org.' }, { rrsets: true });

console.log(zone.rrsets.length);

Error handling

import { Client, Versions, type Error as PowerDNSError } from 'node-powerdns';

const client = new Client({
  baseUrl: 'http://127.0.0.1:8081',
  apiKey: process.env.POWERDNS_API_KEY!,
  version: '/api/v1'
});

try {
  await client.servers.get();
} catch (error) {
  const apiError = error as PowerDNSError;
  console.error(apiError.error);
  console.error(apiError.errors);
}

Runtime requirements

• Node.js 18+.
• A reachable PowerDNS Authoritative API endpoint.
• A valid PowerDNS API key supplied through X-API-Key.

Documentation

• README: github.com/AlexanderSlaa/node-powerdns
• Generated API docs: alexanderslaa.github.io/node-powerdns
• PowerDNS API reference: doc.powerdns.com/authoritative/http-api

License

Apache 2.0. See LICENSE.