@kud/gandi

Typed Gandi v5 REST API client — the headless core shared by @kud/gandi-cli, a future @kud/gandi-ink browser UI, and potentially an MCP server.

It talks to Gandi's domain, LiveDNS, and token-introspection endpoints and returns plain typed data. It has no CLI, no UI, and no opinion about how you present the result — that's every consumer's own job.

Features

• Domains — list, fetch, availability check, renew, toggle autorenew.
• LiveDNS records — list, get, set (replace), add a value to an existing rrset, delete, export the whole zone as a BIND master file.
• Web redirects — list (auto-paginated, so a domain with more redirects than a single page never gets silently truncated), add, update, delete.
• Token introspection — check what a token can do and when it expires, before you find out the hard way.
• API key resolution — GANDI_API_KEY env var first, ~/.config/gandi/config.toml as a fallback.
• Injectable client — the same functions wrapped as a GandiAPI object, so a consumer can accept api?: GandiAPI as a prop and swap in a mock for tests.
• ESM-only, fully typed, zero runtime dependencies beyond a TOML parser.

Install

npm install @kud/gandi

Requires Node >=20.

Usage

API key

import { getApiKey } from "@kud/gandi"

const apiKey = getApiKey()
// throws an Error tagged { kind: "no-token" } if nothing is configured

Resolution order: GANDI_API_KEY env var, then ~/.config/gandi/config.toml:

api_key = "..."

Calling functions directly

Every function takes the API key as its first argument — there's no client to construct.

import { getApiKey, listDomains, listDnsRecords, addRedirect } from "@kud/gandi"

const apiKey = getApiKey()

const domains = await listDomains(apiKey)

const records = await listDnsRecords(apiKey, "example.com")

await addRedirect(apiKey, "example.com", "www", "https://example.com", "301")

Using the injectable client

gandiAPI bundles the same functions into a single object implementing GandiAPI. Reach for this shape when a consumer needs to accept the client as a prop — an Ink component, for instance — and substitute a mock in tests.

import { gandiAPI, type GandiAPI } from "@kud/gandi"

const run = async (api: GandiAPI, apiKey: string) => {
  const domain = await api.getDomain(apiKey, "example.com")
  return domain.status
}

await run(gandiAPI, apiKey)

// in a test
const fakeApi: GandiAPI = {
  ...gandiAPI,
  listDomains: vi.fn().mockResolvedValue([]),
}

Handling auth errors

Errors from expired/invalid tokens and a missing token are both tagged so callers can branch without string-matching messages.

import { authErrorKind } from "@kud/gandi"

try {
  await listDomains(apiKey)
} catch (error) {
  const kind = authErrorKind(error) // "no-token" | "unauthorized" | null
  if (kind === "unauthorized") {
    // token exists but Gandi rejected it — prompt for a new one
  }
}

API reference

src/api.ts — request functions

Every function's first parameter is apiKey: string, omitted below for brevity.

| Function | Signature | Description | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | listDomains | () => Promise<Domain[]> | List all domains on the account. | | getDomain | (domain: string) => Promise<Domain> | Fetch a single domain. | | checkDomain | (name: string) => Promise<DomainCheck> | Check availability and pricing for a domain name. | | renewDomain | (domain: string, duration: number) => Promise<void> | Renew a domain for duration years. | | setAutorenew | (domain: string, enabled: boolean) => Promise<void> | Toggle autorenew. | | listRedirects | (domain: string) => Promise<WebRedir[]> | List all web redirects, paginating until a short page confirms the list is complete. | | addRedirect | (domain: string, host: string, url: string, type: string) => Promise<void> | Create a web redirect. | | updateRedirect | (domain: string, host: string, patch: RedirectPatch) => Promise<void> | Patch an existing redirect. | | deleteRedirect | (domain: string, host: string) => Promise<void> | Delete a redirect. | | toRedirectHost | (domain: string, host: string) => string | Normalise a bare label or FQDN to the host form Gandi's redirect endpoints require. Pure, no network call. | | listDnsRecords | (domain: string) => Promise<DnsRecord[]> | List all LiveDNS records for a domain. | | getDnsRecord | (domain: string, type: string, name: string) => Promise<DnsRecord \| null> | Fetch one record, or null if it doesn't exist. | | setDnsRecord | (domain: string, type: string, name: string, values: string[], ttl?: number) => Promise<void> | Replace an rrset's values (and optionally TTL). Default TTL 10800. | | addDnsValue | (domain: string, type: string, name: string, value: string, ttl?: number) => Promise<{ added: boolean; values: string[] }> | Append a value to an existing rrset instead of replacing it; no-ops if the value is already present. | | deleteDnsRecord | (domain: string, type: string, name: string) => Promise<void> | Delete an rrset. | | exportZone | (domain: string) => Promise<string> | Export the whole zone as a BIND-format master file (RFC 1035). | | getTokenInfo | () => Promise<TokenInfo> | Introspect the API key itself — name, scopes, expiry. Hits id.gandi.net, not api.gandi.net, and needs no extra scope. |

src/config.ts

| Export | Signature | Description | | ----------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | getApiKey | () => string | Resolves the API key from GANDI_API_KEY, falling back to ~/.config/gandi/config.toml. Throws a no-token auth error if neither is present. |

src/errors.ts

| Export | Signature | Description | | --------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | authError | (kind: AuthErrorKind, message: string) => Error | Builds an Error tagged with { kind } so callers can branch on failure type without string-matching. | | authErrorKind | (error: unknown) => AuthErrorKind \| null | Extracts the kind tag from an unknown thrown value, if present. | | AuthErrorKind | "no-token" \| "unauthorized" | The two auth failure kinds. |

src/types.ts

| Type | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Domain | A domain resource — FQDN, nameservers, autorenew state, status, dates, TLD. | | DomainCheck | Result of an availability check — products, prices, currency. | | DnsRecord | A LiveDNS rrset — name, type, TTL, values. | | WebRedir | A web redirect — host, target URL, type, protocol, override flag. | | RedirectPatch | The PATCH body for updating a redirect. Every field optional; an omitted key is left untouched, so override absent differs from override: false. host is deliberately not patchable — Gandi can't move a redirect to a different source. | | GandiError | Shape of an error response from the Gandi API. | | TokenInfo | Result of token introspection — name, scopes, entities, expiry. |

src/client.ts

| Export | Description | | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GandiAPI | Interface with one method per api.ts export, typed via typeof. | | gandiAPI | An object implementing GandiAPI by delegating straight to the api.ts functions. Exists so a consumer can accept the client as an injectable api?: GandiAPI prop and hand tests a { listDomains: vi.fn(), ... } façade instead of hitting the network. |

Development

npm install
npm test          # vitest run
npm run typecheck  # tsc --noEmit
npm run lint       # eslint .
npm run build      # tsup → dist/

npm run test:watch, npm run lint:fix, and npm run build:watch are also available. CI runs typecheck, lint, test, and build on every push and pull request against main.

Licence

MIT © kud