@aoxborrow/registrar-client 0.1.0

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "@aoxborrow/registrar-client",
+  "version": "0.1.0",
+  "description": "One consistent, fully-typed TypeScript interface to many domain registrar APIs (GoDaddy, Cloudflare, Namecheap, Spaceship, Dynadot, Porkbun, and more) behind a single pluggable multi-provider client",
+  "author": {
+    "name": "Aaron Oxborrow",
+    "url": "https://github.com/aoxborrow"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://github.com/aoxborrow/registrar-client",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aoxborrow/registrar-client.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aoxborrow/registrar-client/issues"
+  },
+  "keywords": [
+    "registrar",
+    "registrar-api",
+    "domains",
+    "domain-registration",
+    "domain-management",
+    "dns",
+    "epp",
+    "whois",
+    "rdap",
+    "typescript",
+    "cloudflare",
+    "godaddy",
+    "namecheap",
+    "gandi",
+    "porkbun",
+    "dynadot",
+    "namesilo",
+    "spaceship",
+    "namebright"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "lint": "npm run tsc && npm run eslint && npm run prettier",
+    "lint:fix": "npm run eslint:fix && npm run prettier:fix",
+    "eslint": "eslint --cache --cache-location .eslintcache .",
+    "eslint:fix": "eslint --cache --cache-location .eslintcache . --fix",
+    "prettier": "prettier --check .",
+    "prettier:fix": "prettier --write --list-different .",
+    "ts": "npm run lint",
+    "ts:fix": "npm run lint:fix",
+    "tsc": "tsc --noEmit",
+    "typecheck": "npm run tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:integration:watch": "vitest --config vitest.integration.config.ts",
+    "clear:ts": "rm -rf tsconfig.tsbuildinfo tsconfig.build.tsbuildinfo",
+    "clear:eslint": "rm -rf .eslintcache",
+    "clear": "npm run clear:ts && npm run clear:eslint && rm -rf dist coverage",
+    "prepublishOnly": "npm run build",
+    "release:patch": "npm version patch && git push --follow-tags && gh release create v$(node -p \"require('./package.json').version\") --generate-notes",
+    "release:minor": "npm version minor && git push --follow-tags && gh release create v$(node -p \"require('./package.json').version\") --generate-notes",
+    "release:major": "npm version major && git push --follow-tags && gh release create v$(node -p \"require('./package.json').version\") --generate-notes"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.56.0",
+    "@typescript-eslint/parser": "^8.56.0",
+    "@vitest/coverage-v8": "^4.1.11",
+    "dotenv": "^17.4.2",
+    "eslint": "^10.9.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-plugin-import-x": "^4.17.1",
+    "globals": "^17.11.0",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.56.0",
+    "vitest": "^4.1.11"
+  },
+  "dependencies": {
+    "fast-xml-parser": "^5.11.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,200 @@
+import { normalizeDomain, normalizeNameservers } from './utils';
+import type {
+  ConnectionResult,
+  ContactSet,
+  DnsRecord,
+  Domain,
+  DomainAvailability,
+  DomainForward,
+  EmailForward,
+  ListDomainsOptions,
+  OperationResult,
+  Registrar,
+  RegisterDomainInput,
+  RequestOptions,
+  TldPricing,
+  TransferDomainInput,
+} from './types';
+
+// A thin, provider-agnostic facade over a single `Registrar`. Normalizes
+// domain names and delegates to the underlying provider.
+//
+//   const client = new RegistrarClient(createRegistrar('cloudflare', creds));
+//   await client.listDomains();
+export class RegistrarClient {
+  constructor(public readonly provider: Registrar) {}
+
+  testConnection(opts?: RequestOptions): Promise<ConnectionResult> {
+    return this.provider.testConnection(opts);
+  }
+
+  async listDomains(opts?: ListDomainsOptions): Promise<Domain[]> {
+    const domains = await this.provider.listDomains(opts);
+    if (!opts?.detailed) return domains;
+    return this.enrichWithDetail(domains, opts);
+  }
+
+  // Fills fields that a provider's list endpoint omits (nameservers, privacy,
+  // lock) by fetching each domain's detail and merging it over the summary.
+  // Runs with bounded concurrency; a per-domain detail failure leaves that
+  // domain's summary values untouched rather than failing the whole listing.
+  private async enrichWithDetail(domains: Domain[], opts: RequestOptions): Promise<Domain[]> {
+    const CONCURRENCY = 5;
+    const result = [...domains];
+    let next = 0;
+    const worker = async (): Promise<void> => {
+      while (next < domains.length) {
+        const index = next++;
+        const name = domains[index].domainName;
+        try {
+          const detail = await this.provider.getDomain(name, opts);
+          let merged = { ...domains[index], ...detail };
+          // Some providers expose nameservers only via a dedicated endpoint, not
+          // on the domain detail — fetch them separately when still empty.
+          if (merged.nameservers.length === 0) {
+            try {
+              const nameservers = normalizeNameservers(
+                await this.provider.getNameservers(name, opts)
+              );
+              if (nameservers.length > 0) merged = { ...merged, nameservers };
+            } catch {
+              // leave nameservers empty if this provider can't supply them
+            }
+          }
+          result[index] = merged;
+        } catch {
+          // keep the summary values for this domain on detail failure
+        }
+      }
+    };
+    const workers = Array.from({ length: Math.min(CONCURRENCY, domains.length) }, worker);
+    await Promise.all(workers);
+    return result;
+  }
+
+  getDomain(domainName: string, opts?: RequestOptions): Promise<Domain> {
+    return this.provider.getDomain(normalizeDomain(domainName), opts);
+  }
+
+  checkAvailability(domainNames: string[], opts?: RequestOptions): Promise<DomainAvailability[]> {
+    return this.provider.checkAvailability(domainNames.map(normalizeDomain), opts);
+  }
+
+  getPricing(tldOrDomain: string, opts?: RequestOptions): Promise<TldPricing> {
+    return this.provider.getPricing(normalizeDomain(tldOrDomain), opts);
+  }
+
+  registerDomain(
+    domainName: string,
+    input: RegisterDomainInput,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.registerDomain(normalizeDomain(domainName), input, opts);
+  }
+
+  renewDomain(domainName: string, years?: number, opts?: RequestOptions): Promise<OperationResult> {
+    return this.provider.renewDomain(normalizeDomain(domainName), years, opts);
+  }
+
+  setAutoRenew(
+    domainName: string,
+    enabled: boolean,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.setAutoRenew(normalizeDomain(domainName), enabled, opts);
+  }
+
+  transferIn(
+    domainName: string,
+    input: TransferDomainInput,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.transferIn(normalizeDomain(domainName), input, opts);
+  }
+
+  updateNameservers(
+    domainName: string,
+    nameservers: string[],
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.updateNameservers(normalizeDomain(domainName), nameservers, opts);
+  }
+
+  async getNameservers(domainName: string, opts?: RequestOptions): Promise<string[]> {
+    return normalizeNameservers(
+      await this.provider.getNameservers(normalizeDomain(domainName), opts)
+    );
+  }
+
+  lockDomain(domainName: string, opts?: RequestOptions): Promise<OperationResult> {
+    return this.provider.lockDomain(normalizeDomain(domainName), opts);
+  }
+
+  unlockDomain(domainName: string, opts?: RequestOptions): Promise<OperationResult> {
+    return this.provider.unlockDomain(normalizeDomain(domainName), opts);
+  }
+
+  setPrivacy(
+    domainName: string,
+    enabled: boolean,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.setPrivacy(normalizeDomain(domainName), enabled, opts);
+  }
+
+  getContacts(domainName: string, opts?: RequestOptions): Promise<ContactSet> {
+    return this.provider.getContacts(normalizeDomain(domainName), opts);
+  }
+
+  updateContacts(
+    domainName: string,
+    contacts: ContactSet,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.updateContacts(normalizeDomain(domainName), contacts, opts);
+  }
+
+  getDnsRecords(domainName: string, opts?: RequestOptions): Promise<DnsRecord[]> {
+    return this.provider.getDnsRecords(normalizeDomain(domainName), opts);
+  }
+
+  setDnsRecords(
+    domainName: string,
+    records: DnsRecord[],
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.setDnsRecords(normalizeDomain(domainName), records, opts);
+  }
+
+  // --- extended: forwarding ---
+  //
+  // Opt-in per provider (gate on `provider.supports(Feature.…)`); providers that
+  // don't declare the feature reject with NotImplementedError. Email forwarding
+  // (alias → address) and URL/domain forwarding (host → URL redirect) are
+  // unrelated capabilities with separate feature flags. Each `set…` is a full
+  // replace: any rule omitted is removed, an empty array clears forwarding.
+
+  getEmailForwarding(domainName: string, opts?: RequestOptions): Promise<EmailForward[]> {
+    return this.provider.getEmailForwarding(normalizeDomain(domainName), opts);
+  }
+
+  setEmailForwarding(
+    domainName: string,
+    forwards: EmailForward[],
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.setEmailForwarding(normalizeDomain(domainName), forwards, opts);
+  }
+
+  getDomainForwarding(domainName: string, opts?: RequestOptions): Promise<DomainForward[]> {
+    return this.provider.getDomainForwarding(normalizeDomain(domainName), opts);
+  }
+
+  setDomainForwarding(
+    domainName: string,
+    forwards: DomainForward[],
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.provider.setDomainForwarding(normalizeDomain(domainName), forwards, opts);
+  }
+}

package/src/constants.ts

@@ -0,0 +1,11 @@
+import type { RegistrarClientOptions } from './types';
+
+// default client-level options
+export const DEFAULT_OPTIONS: RegistrarClientOptions = {
+  timeout: 30_000, // 30s — registrar APIs can be slow, especially for registration
+  retries: 2,
+  backoff: 250,
+};
+
+// package identifier used in the default User-Agent header
+export const USER_AGENT = '@aoxborrow/registrar-client';

package/src/errors.ts

@@ -0,0 +1,192 @@
+// convert any thrown value to a RegistrarError (preserves existing RegistrarError instances)
+export function toRegistrarError(error: unknown): RegistrarError {
+  // already a RegistrarError, return as-is
+  if (error instanceof RegistrarError) {
+    return error;
+  }
+
+  // extract message from Error or convert unknown to string
+  const message =
+    error instanceof Error ? error.message : String(error) || 'An unknown error occurred';
+
+  // wrap in a concrete RegistrarError instance
+  const wrapped = new (class extends RegistrarError {})(message);
+
+  // preserve the original error's identity where possible
+  if (error instanceof Error) {
+    wrapped.name = error.name;
+    wrapped.stack = error.stack;
+  } else {
+    wrapped.name = 'RegistrarError';
+  }
+
+  return wrapped;
+}
+
+// base error class for registrar client errors
+// `status` mirrors an HTTP-style status code where meaningful
+export class RegistrarError extends Error {
+  public status: number;
+  // optional machine-readable code from the underlying registrar API
+  public providerCode?: string;
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'RegistrarError';
+    this.status = -1;
+
+    Object.setPrototypeOf(this, new.target.prototype);
+
+    // maintain proper stack trace (V8/Node only)
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  // determine if this error should trigger a retry
+  // overridden by subclasses for custom logic
+  shouldRetry(): boolean {
+    return false;
+  }
+}
+
+// base class for transient errors that are safe to retry
+export class RetryableRegistrarError extends RegistrarError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RetryableRegistrarError';
+  }
+
+  shouldRetry(): boolean {
+    return true;
+  }
+}
+
+// request timed out
+export class TimeoutError extends RetryableRegistrarError {
+  public status = 408; // Request Timeout
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'TimeoutError';
+  }
+}
+
+// network/connection failure reaching the registrar API
+export class ConnectionError extends RetryableRegistrarError {
+  public status = 503; // Service Unavailable
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConnectionError';
+  }
+}
+
+// registrar API rejected the credentials
+export class AuthenticationError extends RegistrarError {
+  public status = 401; // Unauthorized
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthenticationError';
+  }
+}
+
+// caller lacks permission for the requested operation
+export class AuthorizationError extends RegistrarError {
+  public status = 403; // Forbidden
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'AuthorizationError';
+  }
+}
+
+// requested resource (domain, contact, etc.) was not found
+export class NotFoundError extends RegistrarError {
+  public status = 404; // Not Found
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotFoundError';
+  }
+}
+
+// registrar API rate limit exceeded
+export class RateLimitError extends RetryableRegistrarError {
+  public status = 429; // Too Many Requests
+  // seconds to wait before retrying, if provided by the API
+  public retryAfter?: number;
+
+  constructor(message: string, retryAfter?: number) {
+    super(message);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+  }
+}
+
+// registrar API returned a response we couldn't understand
+export class InvalidResponseError extends RetryableRegistrarError {
+  public status = 502; // Bad Gateway
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'InvalidResponseError';
+  }
+}
+
+// failed to parse a response payload
+export class ParsingError extends RegistrarError {
+  public status = 422; // Unprocessable Entity
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ParsingError';
+  }
+}
+
+// invalid client configuration or arguments
+export class ConfigurationError extends RegistrarError {
+  public status = 500; // Internal Server Error
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConfigurationError';
+  }
+}
+
+// a registration/transfer was attempted without the consent the registrar
+// requires (accepting its registration agreements). Distinct from
+// NotImplementedError: the capability exists, but the caller must supply consent.
+export class ConsentRequiredError extends RegistrarError {
+  public status = 400; // Bad Request
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConsentRequiredError';
+  }
+}
+
+// the requested capability is not implemented by this provider
+export class NotImplementedError extends RegistrarError {
+  public status = 501; // Not Implemented
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'NotImplementedError';
+  }
+}
+
+// request was cancelled via an AbortSignal
+export class AbortError extends RegistrarError {
+  public status = 499; // Client Closed Request
+
+  constructor(message: string) {
+    super(message);
+    this.name = 'AbortError';
+  }
+
+  shouldRetry(): boolean {
+    return false;
+  }
+}

package/src/features.ts

@@ -0,0 +1,104 @@
+// Capability model for registrar providers.
+//
+// Features are identified by the string constants on `Feature`. Always reference
+// them through that object (e.g. `Feature.GetPricing`) rather than writing the
+// raw string — you get autocomplete and find-all-references, and typos become
+// compile errors.
+//
+// There are two kinds of feature:
+//
+//   - CORE — the contract every provider is expected to fulfil. A provider
+//     inherits the core surface by extending `BaseRegistrar`; it does not
+//     re-declare it. Core is a deliberate product decision about what this
+//     library guarantees, NOT the intersection of what today's registrars
+//     happen to expose — so a single registrar's missing/undocumented endpoint
+//     never demotes a feature out of core. Where a registrar's API path for a
+//     core feature isn't wired up yet (or hasn't been found — e.g. DNS via
+//     Cloudflare's separate Zones API), the method throws `NotImplementedError`
+//     until implemented. The contract is the promise; `NotImplementedError` is
+//     the "not yet".
+//
+//   - EXTENDED — opt-in capabilities a provider declares via its static
+//     `extendedFeatures`. This is where providers genuinely differ.
+//
+// A provider's full capability set is `CORE_FEATURES` ∪ its `extendedFeatures`,
+// exposed as `provider.features` (and statically as `Registrar.features`).
+
+// All feature identifiers. Reference these instead of string literals.
+export const Feature = {
+  // --- core (guaranteed contract; inherited from BaseRegistrar) ---
+  TestConnection: 'testConnection', // verify credentials
+  ListDomains: 'listDomains', // list domains in the account
+  GetDomain: 'getDomain', // fetch a single domain's details
+  CheckAvailability: 'checkAvailability', // check whether domains can be registered
+  GetPricing: 'getPricing', // TLD/domain pricing lookup
+  RegisterDomain: 'registerDomain', // register a new domain
+  RenewDomain: 'renewDomain', // renew a domain
+  SetAutoRenew: 'setAutoRenew', // toggle auto-renew
+  TransferIn: 'transferIn', // transfer a domain into the account
+  UpdateNameservers: 'updateNameservers', // replace a domain's nameservers
+  GetNameservers: 'getNameservers', // read a domain's nameservers
+  LockDomain: 'lockDomain', // enable the transfer lock
+  UnlockDomain: 'unlockDomain', // disable the transfer lock
+  SetPrivacy: 'setPrivacy', // toggle WHOIS privacy
+  GetContacts: 'getContacts', // read registrant/admin/tech contacts
+  UpdateContacts: 'updateContacts', // update registrant/admin/tech contacts
+  GetDnsRecords: 'getDnsRecords', // read DNS records
+  SetDnsRecords: 'setDnsRecords', // write DNS records
+
+  // --- extended (opt-in; declared per provider) ---
+  GetAuthCode: 'getAuthCode', // retrieve transfer auth/EPP code (transfer out)
+  GetDnssec: 'getDnssec', // read whether DNSSEC is enabled (DS / key records)
+  DisableDnssec: 'disableDnssec', // turn DNSSEC off (no enable / key management)
+  GetEmailForwarding: 'getEmailForwarding', // read alias-style email forwarding rules
+  SetEmailForwarding: 'setEmailForwarding', // alias-style email forwarding (redirect only)
+  GetDomainForwarding: 'getDomainForwarding', // read URL redirect / domain forwarding
+  SetDomainForwarding: 'setDomainForwarding', // URL redirect / domain forwarding
+} as const;
+
+// A registrar capability identifier — the value of one of the `Feature` members.
+export type RegistrarFeature = (typeof Feature)[keyof typeof Feature];
+
+// The guaranteed core contract: every provider is expected to support these.
+export const CORE_FEATURES = [
+  Feature.TestConnection,
+  Feature.ListDomains,
+  Feature.GetDomain,
+  Feature.CheckAvailability,
+  Feature.GetPricing,
+  Feature.RegisterDomain,
+  Feature.RenewDomain,
+  Feature.SetAutoRenew,
+  Feature.TransferIn,
+  Feature.UpdateNameservers,
+  Feature.GetNameservers,
+  Feature.LockDomain,
+  Feature.UnlockDomain,
+  Feature.SetPrivacy,
+  Feature.GetContacts,
+  Feature.UpdateContacts,
+  Feature.GetDnsRecords,
+  Feature.SetDnsRecords,
+] as const satisfies readonly RegistrarFeature[];
+
+// Every feature that is not part of the core contract. A provider opts into any
+// of these via its static `extendedFeatures`.
+export const EXTENDED_FEATURES = [
+  Feature.GetAuthCode,
+  Feature.GetDnssec,
+  Feature.DisableDnssec,
+  Feature.GetEmailForwarding,
+  Feature.SetEmailForwarding,
+  Feature.GetDomainForwarding,
+  Feature.SetDomainForwarding,
+] as const satisfies readonly RegistrarFeature[];
+
+// Every feature, core first.
+export const ALL_FEATURES = [...CORE_FEATURES, ...EXTENDED_FEATURES] as const;
+
+const CORE_FEATURE_SET: ReadonlySet<RegistrarFeature> = new Set(CORE_FEATURES);
+
+// true if `feature` is part of the guaranteed core contract
+export function isCoreFeature(feature: RegistrarFeature): boolean {
+  return CORE_FEATURE_SET.has(feature);
+}