Introducing the DNScale TypeScript SDK

The official DNScale TypeScript SDK 1.0.0 is now available on npm as @dnscale/dnscale. It brings DNS operations into Node.js services, scripts, and background jobs, with typed requests and responses, async pagination, and a shared client for authentication and error handling.

The package supports Node.js 20.19 and newer and uses ES modules. TypeScript declarations are included, and JavaScript applications use the same API. Find the source in dnscaleou/dnscale-typescript.

DNS operations inside your application

A service onboarding a customer might create a verification TXT record. A deployment job might provision an environment's DNS records. An inventory script might read every zone and record before a migration.

The SDK gives these workflows a common API client, so each application does not have to build its own authentication headers, pagination loop, and error parser. It uses the same API keys, permissions, endpoints, and account limits as the DNScale REST API.

Start with a read-only request

Install the package in your Node.js project:

npm install @dnscale/dnscale@1.0.0

Create an API key with zones:read permission and supply it through the DNSCALE_API_KEY environment variable. Keep the key on the server; it should never be included in a browser bundle. See the authentication reference for scopes and zone restrictions.

Save this example as list-zones.mjs and run node list-zones.mjs:

import { DNScale } from "@dnscale/dnscale";
 
const dns = new DNScale();
const signal = AbortSignal.timeout(60_000);
 
for await (const zone of dns.zones.iter({ pageSize: 100, signal })) {
  console.log(zone.id, zone.name);
}

new DNScale() reads the key from the environment. The async iterator fetches pages as you consume them; breaking out of the loop stops additional requests. The signal gives the listing a one-minute budget, while each request also has the client's default ten-second timeout.

This code also works in TypeScript. The learning guide includes a complete TypeScript project setup, compiler configuration, and runnable examples.

Types for the operations you use

The zone and record helpers provide list, iter, get, create, update, and delete. Types describe the request bodies and returned resources, and generated types cover the wider public API contract.

For example, CreateRecord describes a record request, including its name, type, content, and optional TTL. TypeScript can flag a missing required field or an unsupported record type before a script runs. The server still validates permissions and request data; compile-time types do not validate arbitrary runtime input.

Record IDs are content-derived. After an update, retain the ID returned by the API for subsequent reads or deletion. The guide demonstrates the full lifecycle with a disposable TXT record.

Predictable request and error handling

APIError exposes the HTTP status, API error code, message, request ID, and optional details. RateLimitError adds the Retry-After header. Network failures and cancellation remain native fetch errors, and helpers can raise ProtocolError for malformed success responses.

Safe reads can retry transient failures, with up to two retries by default. DNS changes are never automatically retried. If a create or update times out, inspect the current state before deciding whether to repeat it.

Every convenience helper accepts an AbortSignal, so a request can follow your application's cancellation or deadline. Use timeoutMs, maxRetries, and retryBackoffMs to configure the client for a particular job.

Beyond zones and records

dns.api exposes typed operations for the full public contract, including DNSSEC, usage, billing, and account resources. It shares the same authentication, timeout, retry, and throwing error policy as the convenience helpers.

The package includes generated declarations, so consumers do not need to generate a client or install a separate types package for DNScale.

Choose the right workflow

Use this SDK for application-driven changes and procedural Node.js jobs. Use Terraform or DNSControl when DNS is managed as declared configuration with a review-and-apply workflow. An SDK does not provide a desired-state plan or automatically reconcile drift.

TypeScript joins the Python and Go clients in the SDKs learning section. Start with the TypeScript SDK guide for installation, zone and record examples, and error handling.