domeneshop-mcp 1.0.4 → 1.1.1

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # domeneshop-mcp
 
+## 1.1.1
+
+### Patch Changes
+
+- [#37](https://github.com/martinzachariassen/domeneshop-mcp/pull/37) [`d24cf89`](https://github.com/martinzachariassen/domeneshop-mcp/commit/d24cf89e1f90d4db3f6d6ff4f28d732e19700224) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Install with Homebrew: `brew install martinzachariassen/tap/domeneshop-mcp`. Every release now also updates the Homebrew tap.
+
+## 1.1.0
+
+### Minor Changes
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`511a6e9`](https://github.com/martinzachariassen/domeneshop-mcp/commit/511a6e948ec7a8ab0e6b7eb78f9bd7182d082281) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Add access control and CLI polish. `DOMENESHOP_READ_ONLY` exposes only read-only tools, `DOMENESHOP_TOOLS` / `DOMENESHOP_DISABLED_TOOLS` allow- or deny-list individual tools (misspelled names fail at startup), `DOMENESHOP_TIMEOUT_MS` sets the request timeout and `DOMENESHOP_DEBUG` logs API requests to stderr. The CLI gains `--help`, rejects unknown arguments with exit code 2, trims whitespace around credentials and shuts down cleanly on SIGINT/SIGTERM.
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`7c690b3`](https://github.com/martinzachariassen/domeneshop-mcp/commit/7c690b38aed2ab85a73e8cf62403f70eb476cc0a) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Add two DNS helper tools:
+  
+  - `patch_dns_record` changes only the fields you pass. It reads the record first, so `ttl`, `priority` and the other fields are no longer reset by accident the way they can be with `update_dns_record`.
+  - `upsert_dns_record` updates the single record for a host and type, or creates it if there is none. When the host has several records of that type (common for MX and TXT), it refuses and lists their IDs instead of guessing.
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`872be45`](https://github.com/martinzachariassen/domeneshop-mcp/commit/872be455fcfb4e4ea279ddd2478e0f6d498353eb) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Polish the MCP surface:
+  
+  - Every tool now has a human-readable title and the `openWorldHint` annotation, and the server sends usage instructions on initialize.
+  - Inputs are validated before anything reaches Domeneshop: TTL range and multiple of 60, `http(s)` forward URLs, IP addresses for dynamic DNS (now including comma-separated IPv4/IPv6 lists), enums for the `list_dns_records` type and `list_invoices` status filters, and the fields each record type requires (e.g. `priority` for MX).
+  - Read-only tools declare an `outputSchema` and return `structuredContent`; lists are wrapped as `{ domains }`, `{ records }`, `{ forwards }` and `{ invoices }` there, while the text content stays the plain array.
+  - `create_dns_record` and `update_dns_record` return the record as stored instead of just an ID or a confirmation, and delete/dyndns messages say what was changed.
+  - Cancelling a tool call from the client now aborts the underlying API request.
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`1727632`](https://github.com/martinzachariassen/domeneshop-mcp/commit/17276320bb0447a5e54f5bed251a652a041f372d) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Make the API client more robust: requests now time out after 30 seconds, `GET`/`PUT`/`DELETE` are retried on 429/502/503/504 and network errors (honouring `Retry-After`, never retrying `POST`), a `User-Agent` header identifies the server, and error messages explain common statuses (401/403/404/409/429/5xx) with HTML bodies stripped and long bodies truncated. Network failures and timeouts surface as `DomeneshopNetworkError`. Node 20.3 or newer is now required.
+
+### Patch Changes
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`855be46`](https://github.com/martinzachariassen/domeneshop-mcp/commit/855be46840521455ec79ceb9755b016506841b9c) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Publish to the official MCP Registry as `io.github.martinzachariassen/domeneshop-mcp` and attach a one-click Claude Desktop bundle (`.mcpb`) to each GitHub Release. The package is now published with `publishConfig` (public, provenance) and requires at least the MCP SDK and zod versions it is tested against.
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`87163b5`](https://github.com/martinzachariassen/domeneshop-mcp/commit/87163b52dd897ee4f598fe25f825ccb55d8cee6e) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - `update_dyndns` now tells the model it can update several comma-separated hostnames in one call, as the Domeneshop API allows. The `Invoice` type marks `due_date` and `paid_date` as nullable, matching what the API returns for unpaid invoices.
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`7f86965`](https://github.com/martinzachariassen/domeneshop-mcp/commit/7f86965e1fad7f949f728b472c863e210f5ee540) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Fixes from a review pass:
+  
+  - `update_dyndns` strips spaces around commas in `hostname` and `myip` before calling the API, and treats an empty `myip` as omitted.
+  - `upsert_dns_record` keeps the stored `ttl`, `priority` and other optional fields when it updates an existing record and they are left out, instead of resetting them.
+  - A create that times out or loses its connection now says it may still have been applied, so the model checks before retrying and does not create a duplicate.
+  - A `DELETE` retried after a lost connection treats a `404` as success, since the first attempt already removed the resource.
+  - The server logs a warning when the tool filters hide an allowlisted tool (e.g. a write tool in read-only mode) or leave no tools at all.
+  - Clearer messages for a `412` from the forwards API and for `update_forward`, which cannot change a forward's host.
+
+- [#34](https://github.com/martinzachariassen/domeneshop-mcp/pull/34) [`a584d13`](https://github.com/martinzachariassen/domeneshop-mcp/commit/a584d1344ecba45f60526b15b42dd0708e0c1ac1) Thanks [@martinzachariassen](https://github.com/martinzachariassen)! - Require `@modelcontextprotocol/sdk` 1.32.1 or newer, which fixes several security advisories (GHSA-22jm-h49p-29qw, GHSA-6prh-2h8m-c8cw, GHSA-46jr-4wx8-v453, GHSA-rvq5-wwqv-78pq).
+
 ## 1.0.4
 
 ### Patch Changes

package/README.md

@@ -1,25 +1,34 @@
 <h1 align="center">domeneshop-mcp</h1>
 
 <p align="center">
-  Manage your Domeneshop domains, DNS records, HTTP forwards and invoices from any AI assistant.
+  Manage your Domeneshop domains, DNS records, HTTP forwards, dynamic DNS and invoices from any AI assistant.
 </p>
 
 <p align="center">
   <a href="https://github.com/martinzachariassen/domeneshop-mcp/actions/workflows/ci.yml"><img src="https://github.com/martinzachariassen/domeneshop-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/domeneshop-mcp"><img src="https://img.shields.io/npm/v/domeneshop-mcp" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/domeneshop-mcp"><img src="https://img.shields.io/npm/dm/domeneshop-mcp" alt="npm downloads"></a>
+  <a href="package.json"><img src="https://img.shields.io/node/v/domeneshop-mcp" alt="Node.js version"></a>
+  <a href="https://github.com/martinzachariassen/domeneshop-mcp/actions/workflows/codeql.yml"><img src="https://github.com/martinzachariassen/domeneshop-mcp/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/martinzachariassen/domeneshop-mcp"><img src="https://api.scorecard.dev/projects/github.com/martinzachariassen/domeneshop-mcp/badge" alt="OpenSSF Scorecard"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/domeneshop-mcp" alt="License"></a>
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/domeneshop-mcp"><b>npm package</b></a>
   &nbsp;·&nbsp;
+  <a href="https://github.com/martinzachariassen/homebrew-tap"><b>Homebrew tap</b></a>
+  &nbsp;·&nbsp;
   <a href="https://api.domeneshop.no/docs/"><b>Domeneshop API</b></a>
   &nbsp;·&nbsp;
   <a href="https://www.domeneshop.no/admin?view=api"><b>Get API credentials</b></a>
+  &nbsp;·&nbsp;
+  <a href="https://registry.modelcontextprotocol.io/v0/servers?search=io.github.martinzachariassen/domeneshop-mcp"><b>MCP Registry</b></a>
 </p>
 
 An [MCP](https://modelcontextprotocol.io) server that turns the
 [Domeneshop API](https://api.domeneshop.no/docs/) into tools an assistant can call.
-Every operation the API offers is covered — 15 tools across domains, DNS, HTTP
+Every operation the API offers is covered — 17 tools across domains, DNS, HTTP
 forwarding, dynamic DNS and invoices.
 
 It talks MCP over stdio, so it works with **any MCP-compatible client**: Claude
@@ -27,7 +36,8 @@ Code, Claude Desktop, Cursor, VS Code, Codex, Windsurf, Cline and others.
 
 ## Quick start
 
-You need Node.js 20 or newer and a Domeneshop account.
+You need a Domeneshop account, plus either Node.js 20.3 or newer (for `npx`) or
+[Homebrew](https://brew.sh).
 
 **1. Create an API token and secret** at
 [domeneshop.no/admin?view=api](https://www.domeneshop.no/admin?view=api).
@@ -43,6 +53,13 @@ claude mcp add domeneshop \
 
 **3. Ask for something.** "List my domains" is enough to confirm the tools loaded.
 
+**Using Homebrew instead of npx?** Install once, then register the binary in
+step 2 with `-- domeneshop-mcp` in place of `-- npx -y domeneshop-mcp`:
+
+```sh
+brew install martinzachariassen/tap/domeneshop-mcp
+```
+
 Using a different client? See [Client setup](#client-setup) below.
 
 ## Client setup
@@ -55,6 +72,17 @@ credentials from two environment variables:
 | `DOMENESHOP_API_TOKEN` | API token from the Domeneshop control panel |
 | `DOMENESHOP_API_SECRET` | The matching API secret |
 
+Optional settings (see [Access control](#access-control) and
+[Troubleshooting](#troubleshooting)):
+
+| Variable | Description |
+| --- | --- |
+| `DOMENESHOP_READ_ONLY` | `true` to expose only read-only tools |
+| `DOMENESHOP_TOOLS` | Comma-separated allowlist of tool names to expose |
+| `DOMENESHOP_DISABLED_TOOLS` | Comma-separated tool names to hide |
+| `DOMENESHOP_TIMEOUT_MS` | Per-request timeout in milliseconds (default `30000`) |
+| `DOMENESHOP_DEBUG` | `true` to log every API request to stderr |
+
 Most clients take the same **standard config**. Swap in your real token and
 secret wherever you see the placeholders.
 
@@ -98,7 +126,12 @@ Or write the standard config straight into `<your-project>/.mcp.json`.
 <details>
 <summary><strong>Claude Desktop</strong></summary>
 
-Add the standard config to `claude_desktop_config.json`, reachable from
+The easiest route is the one-click bundle: download `domeneshop-mcp-<version>.mcpb`
+from the [latest release](https://github.com/martinzachariassen/domeneshop-mcp/releases/latest)
+and open it. Claude Desktop asks for your token and secret, stores them securely,
+and offers a read-only toggle.
+
+To configure it by hand instead, add the standard config to `claude_desktop_config.json`, reachable from
 Settings → Developer → Edit Config:
 
 | Platform | Full path |
@@ -191,15 +224,41 @@ it at:
 </details>
 
 <details>
-<summary><strong>Skipping npx</strong></summary>
+<summary><strong>Skipping npx (npm or Homebrew)</strong></summary>
 
 To avoid resolving the package on every launch, install it once and use
-`domeneshop-mcp` as the command with no args:
+`domeneshop-mcp` as the command with no args. With npm:
 
 ```sh
 npm install -g domeneshop-mcp
 ```
 
+Or with [Homebrew](https://brew.sh) on macOS or Linux, which also installs
+Node.js for you if it is missing:
+
+```sh
+brew install martinzachariassen/tap/domeneshop-mcp
+```
+
+`brew upgrade domeneshop-mcp` picks up new releases. GUI apps such as Claude
+Desktop usually do not see Homebrew's `PATH`, so give them the full path
+(`brew --prefix` prints the prefix: `/opt/homebrew` on Apple silicon,
+`/usr/local` on Intel Macs, `/home/linuxbrew/.linuxbrew` on Linux):
+
+```json
+{
+  "mcpServers": {
+    "domeneshop": {
+      "command": "/opt/homebrew/bin/domeneshop-mcp",
+      "env": {
+        "DOMENESHOP_API_TOKEN": "your-token",
+        "DOMENESHOP_API_SECRET": "your-secret"
+      }
+    }
+  }
+}
+```
+
 </details>
 
 ## What you can ask for
@@ -209,6 +268,7 @@ npm install -g domeneshop-mcp
 | Domains | "Which domains are on my account, and when do they renew?" |
 | DNS | "Show every DNS record for example.no" |
 | DNS | "Point blog.example.no at 203.0.113.10" |
+| DNS | "Lower the TTL on the www record for example.no to 5 minutes" |
 | DNS | "Add the TXT record Google gave me for domain verification" |
 | DNS | "Set up Fastmail's MX records on example.no" |
 | Forwarding | "Forward old.example.no to https://example.no" |
@@ -217,8 +277,11 @@ npm install -g domeneshop-mcp
 
 ## Tools
 
-Every tool declares MCP annotations, so clients know which ones are safe to run
-without asking you first. The Access column below mirrors those annotations.
+Every tool declares MCP annotations and a title, so clients know which ones are
+safe to run without asking you first. The Access column below mirrors those
+annotations. Arguments are validated before anything is sent to Domeneshop (TTL
+range, URL scheme, IP addresses, and the fields each record type requires), and
+read-only tools also return structured output for clients that support it.
 
 ### Domains
 
@@ -233,14 +296,17 @@ without asking you first. The Access column below mirrors those annotations.
 | --- | --- | --- |
 | `list_dns_records` | Read-only | List a domain's records, optionally filtered by host and type |
 | `get_dns_record` | Read-only | Get a single record by ID |
-| `create_dns_record` | Adds | Create a record |
-| `update_dns_record` | Overwrites | Replace a record — see the warning below |
+| `create_dns_record` | Adds | Create a record and return it as stored |
+| `update_dns_record` | Overwrites | Replace a record and return it as stored — see the warning below |
+| `patch_dns_record` | Overwrites | Change only the given fields of a record; the rest keep their stored values |
+| `upsert_dns_record` | Overwrites | Update the single record for a host and type, or create it if there is none |
 | `delete_dns_record` | Deletes | Delete a record |
 
 > **Heads up:** `update_dns_record` replaces the whole record rather than
 > patching it. Any field left out is dropped, and omitting `ttl` resets it to
-> the default 3600 seconds. Read the record first if you are only changing part
-> of it.
+> the default 3600 seconds. Use `patch_dns_record` to change only some fields.
+> `upsert_dns_record` refuses to act when a host has several records of the
+> same type (typical for `MX` and `TXT`) and lists their IDs instead.
 
 ### HTTP forwarding
 
@@ -256,7 +322,7 @@ without asking you first. The Access column below mirrors those annotations.
 
 | Tool | Access | Description |
 | --- | --- | --- |
-| `update_dyndns` | Overwrites | Point a hostname at a given IP, or at the caller's apparent IP |
+| `update_dyndns` | Overwrites | Point one or more comma-separated hostnames at up to nine IPv4/IPv6 addresses, or at the caller's apparent IP; creates the record if missing |
 
 ### Invoices
 
@@ -265,6 +331,42 @@ without asking you first. The Access column below mirrors those annotations.
 | `list_invoices` | Read-only | List invoices from the past three years, optionally filtered by status |
 | `get_invoice` | Read-only | Get a single invoice |
 
+## Access control
+
+The Domeneshop API has no scoped tokens: a token can do everything the account
+can. To limit what the assistant can do, limit which tools the server exposes.
+Hidden tools are not registered at all, so the model never sees them.
+
+- **Read-only mode.** Set `DOMENESHOP_READ_ONLY=true` to expose only the eight
+  read-only tools. This is a good default if you mainly ask questions about your
+  domains, DNS and invoices.
+- **Allowlist.** Set `DOMENESHOP_TOOLS=list_domains,list_dns_records,patch_dns_record`
+  to expose exactly those tools.
+- **Denylist.** Set `DOMENESHOP_DISABLED_TOOLS=delete_dns_record,delete_forward`
+  to hide specific tools.
+
+The settings combine, and a misspelled tool name stops the server at startup
+instead of being silently ignored.
+
+Most clients ask before running a tool not annotated read-only. Keep that
+confirmation on for this server: write tools change live DNS, and a wrong
+record can take a site or mailbox offline.
+
+## Troubleshooting
+
+- **`API returned status 401`**: the token or secret is wrong. Copy both again
+  from [domeneshop.no/admin?view=api](https://www.domeneshop.no/admin?view=api).
+  Surrounding whitespace is trimmed automatically.
+- **`API returned status 404`**: the domain or record ID does not exist on this
+  account. Ask the assistant to list domains or records first.
+- **Timeouts**: requests give up after 30 seconds. Idempotent requests are
+  retried on rate limiting and temporary errors. Raise the limit with
+  `DOMENESHOP_TIMEOUT_MS` if needed.
+- **The tools do not show up**: run `npx -y domeneshop-mcp --version` to check
+  that Node.js 20.3+ and npx work, then check your client's MCP logs. With
+  `DOMENESHOP_DEBUG=true` the server logs every API request (method, path,
+  status and duration, never credentials) to stderr, which most clients capture.
+
 ## Reference
 
 <details>
@@ -300,7 +402,8 @@ spec, but are supported and used by their own client libraries:
 - `GET /invoices` accepts a `status` filter, which domeneshop.js uses.
 - `POST /forwards/` answers `201` with an empty body and names the new forward
   only in the `Location` header.
-- `GET /dyndns/update` answers with a plain-text status line, not JSON.
+- `GET /dyndns/update` answers `204` with no body rather than JSON, so the
+  client does not try to decode it.
 
 </details>
 
@@ -338,7 +441,8 @@ test/
 ## Contributing
 
 Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md)
-for the development workflow and changelog conventions.
+for the development workflow and changelog conventions. Everyone taking part is
+expected to follow the [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## Security
 

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+/** Thrown for invalid configuration; the CLI prints the message and exits with code 1. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+export interface Config {
+    token: string;
+    secret: string;
+    /** Only register tools annotated read-only. */
+    readOnly: boolean;
+    /** When set, only these tools are registered. */
+    tools: ReadonlySet<string> | undefined;
+    /** These tools are never registered. */
+    disabledTools: ReadonlySet<string>;
+    timeoutMs: number | undefined;
+    debug: boolean;
+}
+export declare const ENV_HELP = "Environment variables:\n  DOMENESHOP_API_TOKEN       API token (required), from https://www.domeneshop.no/admin?view=api\n  DOMENESHOP_API_SECRET      API secret (required)\n  DOMENESHOP_READ_ONLY       \"true\" or \"1\" to expose only read-only tools\n  DOMENESHOP_TOOLS           comma-separated allowlist of tool names to expose\n  DOMENESHOP_DISABLED_TOOLS  comma-separated tool names to hide\n  DOMENESHOP_TIMEOUT_MS      per-request timeout in milliseconds (default 30000)\n  DOMENESHOP_DEBUG           \"true\" or \"1\" to log each API request to stderr";
+export declare function loadConfig(env: NodeJS.ProcessEnv): Config;
+export declare function isTruthy(value: string | undefined): boolean;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;IAClB,iDAAiD;IACjD,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAAC;IACvC,wCAAwC;IACxC,aAAa,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,eAAO,MAAM,QAAQ,qjBAOwD,CAAC;AAK9E,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAmBzD;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE3D"}

package/dist/config.js

@@ -0,0 +1,64 @@
+/** Thrown for invalid configuration; the CLI prints the message and exits with code 1. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ConfigError";
+    }
+}
+export const ENV_HELP = `Environment variables:
+  DOMENESHOP_API_TOKEN       API token (required), from https://www.domeneshop.no/admin?view=api
+  DOMENESHOP_API_SECRET      API secret (required)
+  DOMENESHOP_READ_ONLY       "true" or "1" to expose only read-only tools
+  DOMENESHOP_TOOLS           comma-separated allowlist of tool names to expose
+  DOMENESHOP_DISABLED_TOOLS  comma-separated tool names to hide
+  DOMENESHOP_TIMEOUT_MS      per-request timeout in milliseconds (default 30000)
+  DOMENESHOP_DEBUG           "true" or "1" to log each API request to stderr`;
+const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+const FALSE_VALUES = new Set(["", "0", "false", "no", "off"]);
+export function loadConfig(env) {
+    const token = env["DOMENESHOP_API_TOKEN"]?.trim();
+    const secret = env["DOMENESHOP_API_SECRET"]?.trim();
+    if (!token || !secret) {
+        throw new ConfigError("DOMENESHOP_API_TOKEN and DOMENESHOP_API_SECRET must be set " +
+            "(create credentials at https://www.domeneshop.no/admin?view=api)");
+    }
+    return {
+        token,
+        secret,
+        readOnly: parseBoolean(env, "DOMENESHOP_READ_ONLY"),
+        tools: env["DOMENESHOP_TOOLS"]?.trim() ? parseList(env["DOMENESHOP_TOOLS"]) : undefined,
+        disabledTools: parseList(env["DOMENESHOP_DISABLED_TOOLS"]),
+        timeoutMs: parseTimeout(env["DOMENESHOP_TIMEOUT_MS"]),
+        debug: parseBoolean(env, "DOMENESHOP_DEBUG"),
+    };
+}
+export function isTruthy(value) {
+    return TRUE_VALUES.has((value ?? "").trim().toLowerCase());
+}
+function parseBoolean(env, name) {
+    const value = (env[name] ?? "").trim().toLowerCase();
+    if (TRUE_VALUES.has(value)) {
+        return true;
+    }
+    if (FALSE_VALUES.has(value)) {
+        return false;
+    }
+    throw new ConfigError(`${name} must be true or false, got "${env[name] ?? ""}"`);
+}
+function parseList(value) {
+    return new Set((value ?? "")
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item !== ""));
+}
+function parseTimeout(value) {
+    if (value === undefined || value.trim() === "") {
+        return undefined;
+    }
+    const ms = Number(value);
+    if (!Number.isInteger(ms) || ms <= 0) {
+        throw new ConfigError(`DOMENESHOP_TIMEOUT_MS must be a positive whole number of milliseconds, got "${value}"`);
+    }
+    return ms;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/domeneshop/client.d.ts

@@ -1,11 +1,11 @@
+import { type HttpTransportOptions } from "./http.js";
 import { DnsResource } from "./resources/dns.js";
 import { DomainsResource } from "./resources/domains.js";
 import { DynDnsResource } from "./resources/dyndns.js";
 import { ForwardsResource } from "./resources/forwards.js";
 import { InvoicesResource } from "./resources/invoices.js";
-export interface DomeneshopClientOptions {
-    baseUrl?: string;
-}
+/** See HttpTransportOptions for timeout, retry and logging defaults. */
+export type DomeneshopClientOptions = HttpTransportOptions;
 /** Authenticate with a token/secret pair from https://www.domeneshop.no/admin?view=api. */
 export declare class DomeneshopClient {
     readonly domains: DomainsResource;

package/dist/domeneshop/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/domeneshop/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,2FAA2F;AAC3F,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;gBAExB,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B;CAQjF"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/domeneshop/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,wEAAwE;AACxE,MAAM,MAAM,uBAAuB,GAAG,oBAAoB,CAAC;AAE3D,2FAA2F;AAC3F,qBAAa,gBAAgB;IAC3B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;gBAExB,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,uBAA4B;CAQjF"}

package/dist/domeneshop/client.js

@@ -12,7 +12,7 @@ export class DomeneshopClient {
     dynDns;
     invoices;
     constructor(token, secret, options = {}) {
-        const transport = new HttpTransport(token, secret, options.baseUrl);
+        const transport = new HttpTransport(token, secret, options);
         this.domains = new DomainsResource(transport);
         this.dns = new DnsResource(transport);
         this.forwards = new ForwardsResource(transport);

package/dist/domeneshop/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/domeneshop/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAM3D,2FAA2F;AAC3F,MAAM,OAAO,gBAAgB;IAClB,OAAO,CAAkB;IACzB,GAAG,CAAc;IACjB,QAAQ,CAAmB;IAC3B,MAAM,CAAiB;IACvB,QAAQ,CAAmB;IAEpC,YAAY,KAAa,EAAE,MAAc,EAAE,UAAmC,EAAE;QAC9E,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;QACpE,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;CACF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/domeneshop/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAA6B,MAAM,WAAW,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAK3D,2FAA2F;AAC3F,MAAM,OAAO,gBAAgB;IAClB,OAAO,CAAkB;IACzB,GAAG,CAAc;IACjB,QAAQ,CAAmB;IAC3B,MAAM,CAAiB;IACvB,QAAQ,CAAmB;IAEpC,YAAY,KAAa,EAAE,MAAc,EAAE,UAAmC,EAAE;QAC9E,MAAM,SAAS,GAAG,IAAI,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5D,IAAI,CAAC,OAAO,GAAG,IAAI,eAAe,CAAC,SAAS,CAAC,CAAC;QAC9C,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;QAChD,IAAI,CAAC,MAAM,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;QAC5C,IAAI,CAAC,QAAQ,GAAG,IAAI,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/domeneshop/http.d.ts

@@ -1,13 +1,47 @@
 export declare class DomeneshopApiError extends Error {
     readonly statusCode: number;
     readonly body: string;
+    /** Human-readable advice for the status code, when there is any. */
+    readonly hint: string | undefined;
     constructor(statusCode: number, body: string);
 }
+/** The request never produced an HTTP response: timeout, DNS failure, refused connection… */
+export declare class DomeneshopNetworkError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface HttpTransportOptions {
+    baseUrl?: string | undefined;
+    /** Per-attempt timeout. Defaults to 30 seconds. */
+    timeoutMs?: number | undefined;
+    /** Retries for 429/502/503/504 and network errors on idempotent methods. Defaults to 2. */
+    maxRetries?: number | undefined;
+    userAgent?: string | undefined;
+    /** Base delay for exponential backoff when the server sends no Retry-After. */
+    retryBaseDelayMs?: number | undefined;
+    /** Called after every attempt, e.g. for debug logging. Never receives credentials. */
+    onResponse?: ((event: RequestEvent) => void) | undefined;
+}
+export interface RequestEvent {
+    method: string;
+    path: string;
+    /** Undefined when the attempt failed without a response. */
+    status: number | undefined;
+    durationMs: number;
+    attempt: number;
+}
 export interface RequestOptions {
     query?: Record<string, string | undefined>;
     body?: unknown;
     /** Set false for endpoints with a non-JSON body, e.g. the dynamic DNS update protocol. */
     decodeJson?: boolean;
+    /** Aborts the request, including any pending retry wait. */
+    signal?: AbortSignal | undefined;
+}
+/** Passed through every resource method so a caller can cancel in-flight requests. */
+export interface CallOptions {
+    signal?: AbortSignal | undefined;
 }
 export interface ApiResponse<T> {
     data: T | undefined;
@@ -17,7 +51,18 @@ export interface ApiResponse<T> {
 export declare class HttpTransport {
     private readonly baseUrl;
     private readonly authorization;
-    constructor(token: string, secret: string, baseUrl?: string);
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly userAgent;
+    private readonly retryBaseDelayMs;
+    private readonly onResponse;
+    /** The third argument may be a bare base URL for backwards compatibility. */
+    constructor(token: string, secret: string, options?: HttpTransportOptions | string);
     request<T>(method: string, path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    private attemptSignal;
+    private backoffDelay;
+    private emit;
 }
+/** Accepts both delta-seconds and an HTTP date, per RFC 9110. */
+export declare function parseRetryAfter(value: string | null): number | undefined;
 //# sourceMappingURL=http.d.ts.map

package/dist/domeneshop/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/domeneshop/http.ts"],"names":[],"mappings":"AAEA,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAU7C;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0FAA0F;IAC1F,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,qGAAqG;IACrG,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,MAAyB;IAKvE,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CA8B3B"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/domeneshop/http.ts"],"names":[],"mappings":"AAwBA,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;gBAEtB,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAgB7C;AAID,6FAA6F;AAC7F,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAI3D;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,mDAAmD;IACnD,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,2FAA2F;IAC3F,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,sFAAsF;IACtF,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1D;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0FAA0F;IAC1F,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC;IACpB,qGAAqG;IACrG,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA8C;IAEzE,6EAA6E;gBACjE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAoB,GAAG,MAAW;IAWhF,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAmF1B,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;IAUpB,OAAO,CAAC,IAAI;CAeb;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAUxE"}