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.

src/config.ts

src/errors.ts

src/types.ts

src/client.ts

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