@aoxborrow/registrar-client 0.1.0

package/src/types.ts

@@ -0,0 +1,446 @@
+// Shared, provider-agnostic types for the registrar client.
+
+import type { RegistrarFeature } from './features';
+
+// client-level request options
+export interface RegistrarClientOptions {
+  // request timeout in milliseconds
+  timeout: number;
+  // number of retry attempts for retryable errors
+  retries: number;
+  // base delay for exponential backoff, in milliseconds
+  backoff: number;
+  // optional AbortSignal to cancel in-flight requests
+  signal?: AbortSignal;
+}
+
+// per-request options that can override client-level options
+export type RequestOptions = Partial<RegistrarClientOptions>;
+
+// options for `listDomains`. Extends `RequestOptions` so timeout/retries/signal
+// still flow through a single argument. `listDomains` always returns the full
+// account, paginating internally at each provider's maximum page size.
+export interface ListDomainsOptions extends RequestOptions {
+  // case-insensitive substring to match against the domain name. Applied
+  // server-side where the API supports it (Namecheap `SearchTerm`, Gandi
+  // `fqdn`) and client-side otherwise.
+  search?: string;
+  // Fetch full per-domain detail after listing. Several providers' list
+  // endpoints return only a summary and omit fields like `nameservers`,
+  // `privacy`, or the transfer `locked` flag, which then read as their defaults
+  // (`[]` / `false`). With `detailed: true`, the client follows up with a
+  // `getDomain` call per domain (bounded concurrency) and merges the detail,
+  // so those fields are accurate. Costs one extra request per domain, so it is
+  // opt-in — leave it off for a fast summary listing. Honored by the
+  // `RegistrarClient` facade (and `listPortfolio` over facade sources).
+  detailed?: boolean;
+}
+
+// which API environment a provider targets. "sandbox" covers registrar test
+// environments (GoDaddy calls theirs "OTE") so integration tests never touch
+// real domains. Requesting "sandbox" on a provider without one throws.
+export type RegistrarEnvironment = 'production' | 'sandbox';
+
+// options passed when constructing a registrar provider
+export interface RegistrarOptions extends Partial<RegistrarClientOptions> {
+  environment?: RegistrarEnvironment;
+}
+
+// result of a connection/credential test
+export interface ConnectionResult {
+  success: boolean;
+  message: string;
+}
+
+// result of a mutating operation (renew, nameserver update, lock/unlock)
+export interface OperationResult {
+  success: boolean;
+  message: string;
+}
+
+// a configuration field a registrar needs (used to build credential UIs generically)
+export interface ConfigField {
+  // property name on the credentials object
+  name: string;
+  // human-readable label
+  label: string;
+  // input type
+  type: 'text' | 'password' | 'select';
+  // whether the field is required
+  required: boolean;
+  // allowed values for `select` fields
+  options?: string[];
+  // default value
+  default?: string;
+}
+
+// normalized, cross-registrar view of a domain
+export interface Domain {
+  domainName: string;
+  // id of the registrar that owns this record, e.g. "cloudflare"
+  registrar: string;
+  // registry/registrar status, always lowercased
+  status: string;
+  createdDate: Date | null;
+  expirationDate: Date | null;
+  renewalDate: Date | null;
+  autoRenew: boolean;
+  locked: boolean;
+  privacy: boolean;
+  nameservers: string[];
+  // when this record was fetched
+  syncedAt: Date;
+  // whether the domain has been removed at the registrar
+  deleted: boolean;
+}
+
+// loose input accepted by `createDomain`; providers pass raw-ish API values
+export interface DomainInput {
+  domainName?: string;
+  registrar?: string;
+  status?: string;
+  createdDate?: Date | string | number | null;
+  expirationDate?: Date | string | number | null;
+  renewalDate?: Date | string | number | null;
+  autoRenew?: boolean;
+  locked?: boolean;
+  privacy?: boolean;
+  // accepts string[], objects with a `hosts` array, or objects with ServerName
+  nameservers?: unknown;
+  syncedAt?: Date;
+  deleted?: boolean;
+}
+
+// A normalized registrant/admin/tech/billing contact, mapped to and from each
+// registrar's own contact shape.
+export interface Contact {
+  firstName: string;
+  lastName: string;
+  organization?: string;
+  email: string;
+  // international phone format, e.g. "+1.4805551234"
+  phone: string;
+  fax?: string;
+  address1: string;
+  address2?: string;
+  city: string;
+  // state / province / region; may be empty where the country has none
+  state?: string;
+  postalCode: string;
+  // ISO 3166-1 alpha-2 country code, e.g. "US"
+  country: string;
+}
+
+// The set of contacts on a domain. `registrant` is the legal owner; most
+// registrars also track admin, tech, and billing roles (often the same person).
+export interface ContactSet {
+  registrant?: Contact;
+  admin?: Contact;
+  tech?: Contact;
+  billing?: Contact;
+}
+
+// A single DNS record in provider-agnostic form.
+export interface DnsRecord {
+  // record type, uppercased: "A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "CAA", …
+  type: string;
+  // host/subdomain relative to the zone apex; "@" denotes the apex
+  name: string;
+  // record data / value (target host, IP address, text, etc.)
+  value: string;
+  // time-to-live in seconds
+  ttl?: number;
+  // priority, for MX and SRV records
+  priority?: number;
+  // SRV-only fields
+  weight?: number;
+  port?: number;
+}
+
+// Result of an availability check for a single domain.
+export interface DomainAvailability {
+  domainName: string;
+  available: boolean;
+  // whether the name is a premium/aftermarket registration
+  premium?: boolean;
+  // registration price in major currency units (e.g. 11.99), when the API reports it
+  price?: number;
+  // ISO 4217 currency code, e.g. "USD"
+  currency?: string;
+  // the registration period the price covers, in years
+  period?: number;
+}
+
+// Pricing for a TLD (or a specific domain), in major currency units. Fields are
+// optional because not every registrar exposes all three price points.
+export interface TldPricing {
+  // the TLD the prices apply to, without a leading dot, e.g. "com"
+  tld: string;
+  // ISO 4217 currency code, e.g. "USD"
+  currency: string;
+  registration?: number;
+  renewal?: number;
+  transfer?: number;
+}
+
+// Consent to a registrar's registration agreements, supplied per registration.
+// Registering a domain forms a legal contract with the registry, so providers
+// that require it reject `registerDomain` without this. The provider fetches the
+// specific per-TLD agreement documents itself; the caller only affirms who is
+// consenting (and optionally when).
+export interface RegistrationConsent {
+  // identifier of the consenting party. Registrars that record an "agreed by"
+  // value expect the consenting user's IP address here (e.g. GoDaddy).
+  agreedBy: string;
+  // ISO 8601 timestamp of when consent was given; defaults to the current time.
+  agreedAt?: string;
+}
+
+// Input for transferring a domain in. `authCode` (the EPP/auth code from the
+// losing registrar) is always required; the rest mirror registration and are
+// used by the registrars that need them (GoDaddy/Spaceship want contacts +
+// consent, Namecheap/Dynadot rely on account defaults and just need the code).
+export interface TransferDomainInput {
+  // the EPP / authorization code obtained from the current registrar
+  authCode: string;
+  // registration length to add as part of the transfer, in years
+  years?: number;
+  // contacts for the transferred domain, where the registrar requires them
+  contacts?: ContactSet;
+  // consent to the registrar's transfer agreements, where required (e.g. GoDaddy)
+  consent?: RegistrationConsent;
+  // enable WHOIS privacy on transfer, where supported
+  privacy?: boolean;
+  // enable auto-renew on transfer
+  autoRenew?: boolean;
+}
+
+// Input for registering a new domain.
+export interface RegisterDomainInput {
+  // registration length in years (defaults to 1)
+  years?: number;
+  // contacts for the registration; every registrar requires at least a registrant
+  contacts: ContactSet;
+  // initial nameservers; omitting them uses the registrar's defaults
+  nameservers?: string[];
+  // enable WHOIS privacy at registration, where supported
+  privacy?: boolean;
+  // enable auto-renew at registration
+  autoRenew?: boolean;
+  // consent to the registrar's registration agreements; required by providers
+  // that gate registration behind an explicit legal agreement (e.g. GoDaddy).
+  // Omitting it where required throws `ConsentRequiredError`.
+  consent?: RegistrationConsent;
+}
+
+// credentials for a registrar, as a flat string map keyed by `ConfigField.name`
+export type RegistrarCredentials = Record<string, string>;
+
+// --- extended-feature payloads ---
+
+// An alias-style email forward: mail sent to `alias`@domain is redirected to
+// `forwardTo`. This is redirect-only forwarding — no real mailbox is provisioned.
+export interface EmailForward {
+  // the local part of the source address at the domain, e.g. "hello" for
+  // hello@example.com. Where the registrar supports it, "@" or "*" denotes a
+  // catch-all.
+  alias: string;
+  // the destination address mail is forwarded to
+  forwardTo: string;
+}
+
+// The redirect style for a DomainForward:
+//   - "temporary" temporary (302) redirect; the destination URL shows in the bar
+//   - "permanent" permanent (301) redirect; the destination URL shows in the bar
+//   - "masked"    masked/framed/"cloaked" redirect: an iframe keeps the source
+//                 URL in the address bar. READ-ONLY — `getDomainForwarding` reports
+//                 it for forwards a provider already has, but `setDomainForwarding`
+//                 rejects it. Masking breaks HTTPS, SEO, and modern browser
+//                 protections, and several registrars (e.g. Cloudflare) can't do
+//                 it at all, so the library never creates one.
+export type DomainForwardType = 'temporary' | 'permanent' | 'masked';
+
+// A URL/domain forwarding rule: requests to `host` at the domain are redirected
+// to `url`.
+export interface DomainForward {
+  // the source host at the domain, relative to the apex; "@" denotes the apex,
+  // "www" the www subdomain, etc.
+  host: string;
+  // the destination URL requests are forwarded to
+  url: string;
+  // the redirect style
+  type: DomainForwardType;
+}
+
+// A DNSSEC delegation-signer (DS) record published at the parent zone. Fields
+// mirror the DS RR (RFC 4034). Registrars that expose DNSSEC only as DNSKEY data
+// may not populate every field; `digest` is the hex delegation digest.
+export interface DsRecord {
+  // the key tag identifying the DNSKEY this DS refers to
+  keyTag: number;
+  // DNSSEC algorithm number (e.g. 8 = RSA/SHA-256, 13 = ECDSA P-256)
+  algorithm: number;
+  // digest type (1 = SHA-1, 2 = SHA-256, 4 = SHA-384)
+  digestType: number;
+  // the delegation digest, hex-encoded
+  digest: string;
+}
+
+// DNSSEC status for a domain. `enabled` is the headline signal (is DNSSEC turned
+// on at the registrar); `dsRecords` carries the published DS records when the
+// registrar exposes them (may be empty even when enabled).
+export interface DnssecStatus {
+  enabled: boolean;
+  dsRecords: DsRecord[];
+}
+
+// The core interface every registrar implementation fulfils. `BaseRegistrar`
+// (src/registrar.ts) provides the shared plumbing and `NotImplementedError`
+// defaults; concrete providers under src/registrars/ extend it.
+export interface Registrar {
+  // a short identifier for the provider, e.g. "cloudflare"
+  readonly name: string;
+
+  // the API environment this instance targets
+  readonly environment: RegistrarEnvironment;
+
+  // the capabilities this provider supports (core contract + its extended features)
+  readonly features: readonly RegistrarFeature[];
+
+  // whether this provider supports a given capability
+  supports(feature: RegistrarFeature): boolean;
+
+  // verify the configured credentials work
+  testConnection(opts?: RequestOptions): Promise<ConnectionResult>;
+
+  // list domains in the account (capped and optionally filtered via `opts`)
+  listDomains(opts?: ListDomainsOptions): Promise<Domain[]>;
+
+  // fetch a single domain's details
+  getDomain(domainName: string, opts?: RequestOptions): Promise<Domain>;
+
+  // check whether one or more domains are available to register
+  checkAvailability(domainNames: string[], opts?: RequestOptions): Promise<DomainAvailability[]>;
+
+  // look up pricing for a TLD (or a specific domain)
+  getPricing(tldOrDomain: string, opts?: RequestOptions): Promise<TldPricing>;
+
+  // register a new domain
+  registerDomain(
+    domainName: string,
+    input: RegisterDomainInput,
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // renew a domain for `years` years
+  renewDomain(domainName: string, years?: number, opts?: RequestOptions): Promise<OperationResult>;
+
+  // toggle auto-renew for a domain
+  setAutoRenew(
+    domainName: string,
+    enabled: boolean,
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // transfer a domain into the account using its auth/EPP code (+ any contacts /
+  // consent the registrar requires, via `TransferDomainInput`)
+  transferIn(
+    domainName: string,
+    input: TransferDomainInput,
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // replace the nameservers for a domain
+  updateNameservers(
+    domainName: string,
+    nameservers: string[],
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // read the nameservers currently set on a domain
+  getNameservers(domainName: string, opts?: RequestOptions): Promise<string[]>;
+
+  // lock a domain against transfers
+  lockDomain(domainName: string, opts?: RequestOptions): Promise<OperationResult>;
+
+  // unlock a domain
+  unlockDomain(domainName: string, opts?: RequestOptions): Promise<OperationResult>;
+
+  // toggle WHOIS privacy for a domain
+  setPrivacy(domainName: string, enabled: boolean, opts?: RequestOptions): Promise<OperationResult>;
+
+  // read the registrant/admin/tech/billing contacts for a domain
+  getContacts(domainName: string, opts?: RequestOptions): Promise<ContactSet>;
+
+  // update the contacts for a domain
+  updateContacts(
+    domainName: string,
+    contacts: ContactSet,
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // read the DNS records for a domain
+  getDnsRecords(domainName: string, opts?: RequestOptions): Promise<DnsRecord[]>;
+
+  // replace the DNS records for a domain
+  setDnsRecords(
+    domainName: string,
+    records: DnsRecord[],
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // --- extended capabilities ---
+  //
+  // Opt-in operations beyond the core contract. A provider genuinely supports one
+  // only if it declares the matching Feature (see `features`/`supports`); every
+  // other provider inherits BaseRegistrar's default, which rejects with
+  // NotImplementedError. Callers should gate on `supports(...)` before use.
+
+  // read the alias-style email forwarding rules for a domain
+  getEmailForwarding(domainName: string, opts?: RequestOptions): Promise<EmailForward[]>;
+
+  // replace the alias-style email forwarding rules for a domain (full replace: any
+  // rule not included is removed; an empty array clears all forwarding)
+  setEmailForwarding(
+    domainName: string,
+    forwards: EmailForward[],
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // read the URL/domain forwarding rules for a domain
+  getDomainForwarding(domainName: string, opts?: RequestOptions): Promise<DomainForward[]>;
+
+  // replace the URL/domain forwarding rules for a domain (full replace: any rule
+  // not included is removed; an empty array clears all forwarding)
+  setDomainForwarding(
+    domainName: string,
+    forwards: DomainForward[],
+    opts?: RequestOptions
+  ): Promise<OperationResult>;
+
+  // retrieve the transfer authorization (EPP/auth) code used to transfer the
+  // domain away to another registrar
+  getAuthCode(domainName: string, opts?: RequestOptions): Promise<string>;
+
+  // read DNSSEC status for a domain (whether it's enabled, plus any DS records)
+  getDnssec(domainName: string, opts?: RequestOptions): Promise<DnssecStatus>;
+
+  // disable/turn off DNSSEC for a domain (removes the registrar's DS records at
+  // the parent). Enabling DNSSEC is intentionally not part of this interface.
+  disableDnssec(domainName: string, opts?: RequestOptions): Promise<OperationResult>;
+}
+
+// static side of a registrar class: the constructor plus discovery metadata
+// (display name, the credential fields it needs, where to get them, and whether
+// it offers a sandbox/test environment).
+export interface RegistrarConstructor {
+  new (credentials: RegistrarCredentials, options?: RegistrarOptions): Registrar;
+  readonly displayName: string;
+  readonly configFields: ConfigField[];
+  readonly helpText: string;
+  readonly supportsSandbox: boolean;
+  // extended capabilities this provider opts into, beyond the core contract
+  readonly extendedFeatures: readonly RegistrarFeature[];
+  // the full capability set: the core contract plus `extendedFeatures`
+  readonly features: readonly RegistrarFeature[];
+}

package/src/utils.ts

@@ -0,0 +1,135 @@
+import type { DomainForward, Domain, DomainInput, RegistrationConsent } from './types';
+import { ConsentRequiredError } from './errors';
+
+// sleep helper for retry backoff
+export function sleep(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+// a DomainForward that is safe to write: masked/framed forwarding is read-only.
+export type SettableDomainForward = DomainForward & { type: 'temporary' | 'permanent' };
+
+export const MASKED_FORWARD_UNSUPPORTED =
+  'masked/framed forwarding is not supported by this library; use "temporary" or "permanent"';
+
+// Guard for `setDomainForwarding`: reject any masked/framed forward up front (so
+// no partial write happens) and narrow the list to the settable types. Providers
+// call this before writing.
+export function settableForwards(forwards: DomainForward[]): SettableDomainForward[] {
+  for (const f of forwards) {
+    if (f.type === 'masked') throw new Error(MASKED_FORWARD_UNSUPPORTED);
+  }
+  return forwards as SettableDomainForward[];
+}
+
+// guard for register/transfer: registration forms a legal contract with the
+// registry, so a provider must be given explicit consent. Throws
+// ConsentRequiredError (distinct from NotImplementedError) when it's absent.
+export function requireConsent(
+  provider: string,
+  consent: RegistrationConsent | undefined
+): RegistrationConsent {
+  if (!consent) {
+    throw new ConsentRequiredError(
+      `${provider}: this operation requires consent — supply \`consent\` ` +
+        '(accepting the registrar’s registration agreements)'
+    );
+  }
+  return consent;
+}
+
+// filter a domain list by a case-insensitive substring of the domain name.
+// Providers that filter server-side still call this — the re-filter is a
+// harmless no-op there — so every provider applies `search` consistently.
+export function filterDomains(domains: Domain[], search?: string): Domain[] {
+  const q = search?.trim().toLowerCase();
+  if (!q) return domains;
+  return domains.filter(d => d.domainName.toLowerCase().includes(q));
+}
+
+// normalize a domain name: trim, lowercase, strip a single trailing dot
+export function normalizeDomain(domain: string): string {
+  return domain.trim().toLowerCase().replace(/\.$/, '');
+}
+
+// exponential backoff delay: backoff * 2^attempt
+export function backoffDelay(backoff: number, attempt: number): number {
+  return backoff * Math.pow(2, attempt);
+}
+
+// parse a variety of date representations into a Date (or null)
+// handles ISO strings, epoch millis (as number or numeric string), and Date
+export function parseDate(value: Date | string | number | null | undefined): Date | null {
+  if (value == null || value === '') return null;
+  if (value instanceof Date) return isNaN(value.getTime()) ? null : value;
+
+  // numeric epoch millis (e.g. Dynadot returns ms timestamps)
+  if (typeof value === 'number') {
+    const d = new Date(value);
+    return isNaN(d.getTime()) ? null : d;
+  }
+
+  // numeric string that looks like an epoch-millis timestamp
+  const asNumber = Number(value);
+  if (!isNaN(asNumber) && asNumber > 1_000_000_000_000) {
+    const d = new Date(asNumber);
+    return isNaN(d.getTime()) ? null : d;
+  }
+
+  const d = new Date(value);
+  return isNaN(d.getTime()) ? null : d;
+}
+
+// normalize nameservers into a flat array of hostname strings.
+// accepts: string[], { hosts: string[] } (Spaceship), or objects with a
+// ServerName property (Dynadot), falling back to String() for anything else.
+// Hostnames are trimmed and lowercased (they're case-insensitive, but providers
+// return mixed case), and blanks are dropped.
+export function normalizeNameservers(nameservers: unknown): string[] {
+  if (!nameservers) return [];
+
+  let raw: unknown[];
+
+  // object with a `hosts` array (Spaceship shape)
+  if (
+    typeof nameservers === 'object' &&
+    !Array.isArray(nameservers) &&
+    Array.isArray((nameservers as { hosts?: unknown }).hosts)
+  ) {
+    raw = (nameservers as { hosts: unknown[] }).hosts;
+  } else if (Array.isArray(nameservers)) {
+    raw = nameservers;
+  } else {
+    return [];
+  }
+
+  return raw
+    .map(ns => {
+      if (typeof ns === 'string') return ns;
+      if (ns && typeof ns === 'object' && 'ServerName' in ns) {
+        return String(ns.ServerName);
+      }
+      return String(ns);
+    })
+    .map(host => host.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+// build a normalized Domain from loose provider input:
+// lowercases status, normalizes nameservers, and coerces dates.
+export function createDomain(data: DomainInput = {}): Domain {
+  return {
+    domainName: data.domainName ?? '',
+    registrar: data.registrar ?? '',
+    status: (data.status ?? '').toLowerCase(),
+    createdDate: parseDate(data.createdDate),
+    expirationDate: parseDate(data.expirationDate),
+    renewalDate: parseDate(data.renewalDate),
+    autoRenew: data.autoRenew ?? false,
+    locked: data.locked ?? false,
+    privacy: data.privacy ?? false,
+    nameservers: normalizeNameservers(data.nameservers),
+    syncedAt: data.syncedAt ?? new Date(),
+    deleted: data.deleted ?? false,
+  };
+}

package/src/xml.ts

@@ -0,0 +1,39 @@
+import { XMLParser, type X2jOptions } from 'fast-xml-parser';
+import { ParsingError } from './errors';
+
+// Shared XML parsing for registrar APIs that speak XML (e.g. Namecheap, Enom).
+// fast-xml-parser is pure JS with no Node built-ins, so this stays safe in
+// browsers, Cloudflare Workers, Deno, Bun, and Node.
+
+// default options applied to all registrar XML responses:
+// - attributes are kept (prefixed with `@_`)
+// - values are left as raw strings; providers coerce them explicitly, so a
+//   ZIP like "01234" or a flag like "true" never changes type unexpectedly
+const DEFAULT_XML_OPTIONS: Partial<X2jOptions> = {
+  ignoreAttributes: false,
+  attributeNamePrefix: '@_',
+  textNodeName: '#text',
+  parseAttributeValue: false,
+  parseTagValue: false,
+  trimValues: true,
+};
+
+// parse an XML string into a plain object, throwing ParsingError on failure
+export function parseXml<T = unknown>(xml: string, options?: Partial<X2jOptions>): T {
+  try {
+    const parser = new XMLParser({ ...DEFAULT_XML_OPTIONS, ...options });
+    return parser.parse(xml) as T;
+  } catch (error) {
+    throw new ParsingError(
+      `Failed to parse XML: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+// coerce a value that may be a single item or an array into an array.
+// XML parsers collapse a single repeated element into one object; this
+// normalizes both cases to an array.
+export function ensureArray<T>(value: T | T[] | undefined | null): T[] {
+  if (value == null) return [];
+  return Array.isArray(value) ? value : [value];
+}