@aoxborrow/registrar-client 0.1.0

package/src/http.ts

@@ -0,0 +1,230 @@
+import { USER_AGENT } from './constants';
+import {
+  AbortError,
+  AuthenticationError,
+  AuthorizationError,
+  ConnectionError,
+  InvalidResponseError,
+  NotFoundError,
+  ParsingError,
+  RateLimitError,
+  RegistrarError,
+  TimeoutError,
+  toRegistrarError,
+} from './errors';
+import type { RegistrarClientOptions } from './types';
+import { backoffDelay, sleep } from './utils';
+
+// configuration for an HttpClient instance
+export interface HttpClientConfig {
+  // base URL for all requests, e.g. "https://api.example.com/v2"
+  baseUrl: string;
+  // default headers applied to every request (e.g. Authorization) — never logged
+  headers?: Record<string, string>;
+  // request/retry behavior
+  options: RegistrarClientOptions;
+}
+
+// options for a single request
+export interface RequestConfig {
+  method?: string;
+  // path appended to baseUrl, or an absolute URL
+  path: string;
+  // query parameters (never used for secrets)
+  query?: Record<string, string | number | boolean | undefined>;
+  // JSON body; serialized with JSON.stringify
+  body?: unknown;
+  headers?: Record<string, string>;
+  // per-request overrides
+  timeout?: number;
+  retries?: number;
+  backoff?: number;
+  signal?: AbortSignal;
+}
+
+// a small, browser/edge-safe fetch wrapper with timeout, abort linking,
+// retry-with-backoff, and registrar error mapping. No Node built-ins.
+export class HttpClient {
+  constructor(protected config: HttpClientConfig) {}
+
+  // perform a request and parse a JSON response body
+  async request<T = unknown>(req: RequestConfig): Promise<T> {
+    return this.withRetries(req, async () => {
+      const text = await this.send(req);
+      if (text.length === 0) return undefined as T;
+      try {
+        return JSON.parse(text) as T;
+      } catch (error) {
+        throw new ParsingError(
+          `Failed to parse JSON response from '${this.buildUrl(req)}': ${errorMessage(error)}`
+        );
+      }
+    });
+  }
+
+  // perform a request and return the raw response body text (e.g. XML APIs)
+  async requestText(req: RequestConfig): Promise<string> {
+    return this.withRetries(req, () => this.send(req));
+  }
+
+  // shared retry-with-backoff wrapper around a single-attempt operation
+  protected async withRetries<T>(req: RequestConfig, attemptFn: () => Promise<T>): Promise<T> {
+    const retries = req.retries ?? this.config.options.retries;
+    const backoff = req.backoff ?? this.config.options.backoff;
+
+    let lastError: RegistrarError | undefined;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      try {
+        return await attemptFn();
+      } catch (error) {
+        lastError = toRegistrarError(error);
+
+        // out of attempts, or the error is not retryable
+        if (attempt >= retries || !lastError.shouldRetry()) {
+          throw lastError;
+        }
+
+        // honor Retry-After for rate limits when present, else exponential backoff
+        const delay =
+          lastError instanceof RateLimitError && lastError.retryAfter != null
+            ? lastError.retryAfter * 1000
+            : backoffDelay(backoff, attempt);
+        await sleep(delay);
+      }
+    }
+
+    // unreachable: the loop always returns or throws
+    throw lastError ?? new RegistrarError('Request failed');
+  }
+
+  // build the full URL for a request, applying query parameters
+  protected buildUrl(req: RequestConfig): string {
+    let base: string;
+    if (/^https?:\/\//.test(req.path)) {
+      // absolute URL
+      base = req.path;
+    } else if (req.path === '') {
+      // empty path: the baseUrl is itself the full endpoint (e.g. Namecheap/Dynadot)
+      base = this.config.baseUrl;
+    } else {
+      base = `${this.config.baseUrl.replace(/\/$/, '')}/${req.path.replace(/^\//, '')}`;
+    }
+    const url = new URL(base);
+    if (req.query) {
+      for (const [key, value] of Object.entries(req.query)) {
+        if (value !== undefined) url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+
+  // send a single request (no retries), map errors, and return the raw body text
+  protected async send(req: RequestConfig): Promise<string> {
+    const timeout = req.timeout ?? this.config.options.timeout;
+    const externalSignal = req.signal ?? this.config.options.signal;
+
+    // abort controller for this request, linked to any external signal
+    const controller = new AbortController();
+    if (externalSignal?.aborted) {
+      throw new AbortError('Request was aborted');
+    }
+    const onAbort = () => controller.abort();
+    externalSignal?.addEventListener('abort', onAbort);
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    const url = this.buildUrl(req);
+    const headers: Record<string, string> = {
+      'User-Agent': USER_AGENT,
+      'Accept': 'application/json',
+      ...this.config.headers,
+      ...req.headers,
+    };
+    if (req.body !== undefined && headers['Content-Type'] === undefined) {
+      headers['Content-Type'] = 'application/json';
+    }
+
+    try {
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          method: req.method ?? 'GET',
+          headers,
+          body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+          signal: controller.signal,
+        });
+      } catch (error) {
+        // distinguish abort/timeout from a genuine network failure
+        if (isAbortError(error)) {
+          if (externalSignal?.aborted) throw new AbortError('Request was aborted');
+          throw new TimeoutError(`Request to '${url}' timed out after ${timeout}ms`);
+        }
+        throw new ConnectionError(`Failed to reach '${url}': ${errorMessage(error)}`);
+      }
+
+      if (!response.ok) {
+        throw await this.toStatusError(response, url);
+      }
+
+      // 204 No Content yields an empty string
+      if (response.status === 204) {
+        return '';
+      }
+      return await response.text();
+    } finally {
+      clearTimeout(timeoutId);
+      externalSignal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  // map a non-2xx response to a typed RegistrarError
+  protected async toStatusError(response: Response, url: string): Promise<RegistrarError> {
+    // read the body defensively; it may aid debugging but must not be assumed JSON
+    let detail = '';
+    try {
+      detail = (await response.text()).slice(0, 500);
+    } catch {
+      // ignore body read failures
+    }
+    const message = `Request to '${url}' failed with ${response.status} ${response.statusText}${
+      detail ? `: ${detail}` : ''
+    }`;
+
+    switch (response.status) {
+      case 401:
+        return new AuthenticationError(message);
+      case 403:
+        return new AuthorizationError(message);
+      case 404:
+        return new NotFoundError(message);
+      case 429: {
+        const retryAfter = Number(response.headers.get('retry-after'));
+        return new RateLimitError(message, Number.isFinite(retryAfter) ? retryAfter : undefined);
+      }
+      default: {
+        if (response.status >= 500) {
+          return new InvalidResponseError(message);
+        }
+        // preserve the real status for 4xx codes without a dedicated class
+        // (400, 402, 409, 422, …) so callers can branch on it
+        const err = new RegistrarError(message);
+        err.status = response.status;
+        return err;
+      }
+    }
+  }
+}
+
+// detect an AbortController/fetch abort across environments
+function isAbortError(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    'name' in error &&
+    (error as { name?: string }).name === 'AbortError'
+  );
+}
+
+// safely extract a message from an unknown thrown value
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+// Public API surface.
+
+export { RegistrarClient } from './client';
+export { listPortfolio } from './portfolio';
+export type { DomainSource, PortfolioError, PortfolioResult } from './portfolio';
+export { HttpClient } from './http';
+export type { HttpClientConfig, RequestConfig } from './http';
+
+// core registrar abstraction (the `Registrar` interface itself is exported via
+// `export * from './types'` below)
+export { BaseRegistrar, selectBaseUrl } from './registrar';
+
+// built-in providers lookup + factory
+export { registrars, createRegistrar } from './registrars/index';
+export type { RegistrarName } from './registrars/index';
+
+// capability model: feature constants, the core contract, and helpers
+export { Feature, CORE_FEATURES, EXTENDED_FEATURES, ALL_FEATURES, isCoreFeature } from './features';
+export type { RegistrarFeature } from './features';
+
+// bundled providers
+export { CloudflareRegistrar } from './registrars/cloudflare';
+export { DynadotRegistrar } from './registrars/dynadot';
+export { GandiRegistrar } from './registrars/gandi';
+export { GoDaddyRegistrar } from './registrars/godaddy';
+export { NameBrightRegistrar } from './registrars/namebright';
+export { NamecheapRegistrar } from './registrars/namecheap';
+export { NameSiloRegistrar } from './registrars/namesilo';
+export { PorkbunRegistrar } from './registrars/porkbun';
+export { SpaceshipRegistrar } from './registrars/spaceship';
+
+// XML parsing helpers for XML-based registrar APIs
+export { parseXml, ensureArray } from './xml';
+
+// shared types, constants, utils, and errors
+export * from './types';
+export * from './constants';
+export * from './utils';
+export * from './errors';

package/src/portfolio.ts

@@ -0,0 +1,65 @@
+// Aggregate domains across multiple registrars into one combined portfolio.
+//
+// Each source is queried concurrently and failures are isolated per-registrar
+// (one provider being down never sinks the whole view). Every returned Domain
+// already carries its `registrar`, so the flattened list stays attributable.
+
+import type { RegistrarClient } from './client';
+import type { Domain, ListDomainsOptions, Registrar } from './types';
+import { toRegistrarError } from './errors';
+
+// anything that can list domains: a raw Registrar or the RegistrarClient facade
+export type DomainSource = Registrar | RegistrarClient;
+
+// a per-registrar failure from a portfolio fetch
+export interface PortfolioError {
+  // the registrar id that failed, e.g. "godaddy"
+  registrar: string;
+  error: Error;
+}
+
+// the outcome of a portfolio fetch: all domains that loaded, plus any errors
+export interface PortfolioResult {
+  domains: Domain[];
+  errors: PortfolioError[];
+}
+
+// resolve a source's registrar id, whether it's a client facade or a provider
+function sourceName(source: DomainSource): string {
+  return 'provider' in source ? source.provider.name : source.name;
+}
+
+/**
+ * List domains across many registrars at once. Queries every source in parallel
+ * and collects results with per-registrar error isolation.
+ *
+ * `opts` (including `search`) is passed to EACH source. Every source returns its
+ * full account; order of the returned `domains` follows the order of `sources`.
+ *
+ *   const { domains, errors } = await listPortfolio(
+ *     [godaddyClient, namecheapClient, gandiClient],
+ *     { search: 'acme' }
+ *   );
+ */
+export async function listPortfolio(
+  sources: DomainSource[],
+  opts?: ListDomainsOptions
+): Promise<PortfolioResult> {
+  const settled = await Promise.allSettled(sources.map(source => source.listDomains(opts)));
+
+  const domains: Domain[] = [];
+  const errors: PortfolioError[] = [];
+
+  settled.forEach((result, i) => {
+    if (result.status === 'fulfilled') {
+      domains.push(...result.value);
+    } else {
+      errors.push({
+        registrar: sourceName(sources[i]),
+        error: toRegistrarError(result.reason),
+      });
+    }
+  });
+
+  return { domains, errors };
+}

package/src/registrar.ts

@@ -0,0 +1,240 @@
+import { DEFAULT_OPTIONS } from './constants';
+import { ConfigurationError, NotImplementedError } from './errors';
+import { HttpClient, type HttpClientConfig } from './http';
+import { CORE_FEATURES, type RegistrarFeature } from './features';
+import type {
+  ConnectionResult,
+  ContactSet,
+  DnsRecord,
+  Domain,
+  DomainAvailability,
+  DomainForward,
+  DnssecStatus,
+  EmailForward,
+  ListDomainsOptions,
+  OperationResult,
+  Registrar,
+  RegisterDomainInput,
+  RegistrarClientOptions,
+  RegistrarCredentials,
+  RegistrarEnvironment,
+  RegistrarOptions,
+  RequestOptions,
+  TldPricing,
+  TransferDomainInput,
+} from './types';
+
+// pick the base URL for the requested environment. Throws if `sandbox` is
+// requested but the provider defines no sandbox URL — so integration tests
+// fail loudly rather than silently hitting production.
+export function selectBaseUrl(
+  registrar: string,
+  environment: RegistrarEnvironment | undefined,
+  urls: { production: string; sandbox?: string }
+): string {
+  if (environment === 'sandbox') {
+    if (!urls.sandbox) {
+      throw new ConfigurationError(`${registrar} does not provide a sandbox environment`);
+    }
+    return urls.sandbox;
+  }
+  return urls.production;
+}
+
+// Abstract base for registrar providers. Owns the shared HTTP/auth/retry
+// plumbing (via `HttpClient`) and provides `NotImplementedError`-rejecting
+// defaults for every operation. Concrete providers extend this, build their
+// base URL + auth from the credentials passed to `super()`, and override the
+// operations their API supports.
+export abstract class BaseRegistrar implements Registrar {
+  abstract readonly name: string;
+
+  protected http: HttpClient;
+  protected credentials: RegistrarCredentials;
+  protected options: RegistrarClientOptions;
+  readonly environment: RegistrarEnvironment;
+
+  // Extended capabilities this provider opts into, beyond the core contract.
+  // Subclasses override this; core features are inherited and not re-declared.
+  static readonly extendedFeatures: readonly RegistrarFeature[] = [];
+
+  // The provider's full capability set: the core contract plus its extended
+  // features. Available statically (no instance/credentials needed) for catalog
+  // UIs and MCP tooling.
+  static get features(): readonly RegistrarFeature[] {
+    return [...CORE_FEATURES, ...this.extendedFeatures];
+  }
+
+  // instance mirror of the static `features`
+  get features(): readonly RegistrarFeature[] {
+    return (this.constructor as typeof BaseRegistrar).features;
+  }
+
+  // whether this provider supports a given capability
+  supports(feature: RegistrarFeature): boolean {
+    return this.features.includes(feature);
+  }
+
+  constructor(
+    credentials: RegistrarCredentials,
+    httpConfig: Omit<HttpClientConfig, 'options'>,
+    options?: RegistrarOptions
+  ) {
+    const { environment = 'production', ...clientOptions } = options ?? {};
+    this.credentials = credentials;
+    this.environment = environment;
+    this.options = { ...DEFAULT_OPTIONS, ...clientOptions };
+    this.http = new HttpClient({ ...httpConfig, options: this.options });
+  }
+
+  testConnection(_opts?: RequestOptions): Promise<ConnectionResult> {
+    return Promise.reject(
+      new NotImplementedError(`${this.name}: testConnection is not implemented`)
+    );
+  }
+
+  listDomains(_opts?: ListDomainsOptions): Promise<Domain[]> {
+    return Promise.reject(new NotImplementedError(`${this.name}: listDomains is not implemented`));
+  }
+
+  renewDomain(
+    _domainName: string,
+    _years?: number,
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return Promise.reject(new NotImplementedError(`${this.name}: renewDomain is not implemented`));
+  }
+
+  updateNameservers(
+    _domainName: string,
+    _nameservers: string[],
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return Promise.reject(
+      new NotImplementedError(`${this.name}: updateNameservers is not implemented`)
+    );
+  }
+
+  lockDomain(_domainName: string, _opts?: RequestOptions): Promise<OperationResult> {
+    return Promise.reject(new NotImplementedError(`${this.name}: lockDomain is not implemented`));
+  }
+
+  unlockDomain(_domainName: string, _opts?: RequestOptions): Promise<OperationResult> {
+    return Promise.reject(new NotImplementedError(`${this.name}: unlockDomain is not implemented`));
+  }
+
+  getDomain(_domainName: string, _opts?: RequestOptions): Promise<Domain> {
+    return this.notImplemented('getDomain');
+  }
+
+  checkAvailability(_domainNames: string[], _opts?: RequestOptions): Promise<DomainAvailability[]> {
+    return this.notImplemented('checkAvailability');
+  }
+
+  getPricing(_tldOrDomain: string, _opts?: RequestOptions): Promise<TldPricing> {
+    return this.notImplemented('getPricing');
+  }
+
+  registerDomain(
+    _domainName: string,
+    _input: RegisterDomainInput,
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('registerDomain');
+  }
+
+  setAutoRenew(
+    _domainName: string,
+    _enabled: boolean,
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('setAutoRenew');
+  }
+
+  transferIn(
+    _domainName: string,
+    _input: TransferDomainInput,
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('transferIn');
+  }
+
+  getNameservers(_domainName: string, _opts?: RequestOptions): Promise<string[]> {
+    return this.notImplemented('getNameservers');
+  }
+
+  setPrivacy(
+    _domainName: string,
+    _enabled: boolean,
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('setPrivacy');
+  }
+
+  getContacts(_domainName: string, _opts?: RequestOptions): Promise<ContactSet> {
+    return this.notImplemented('getContacts');
+  }
+
+  updateContacts(
+    _domainName: string,
+    _contacts: ContactSet,
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('updateContacts');
+  }
+
+  getDnsRecords(_domainName: string, _opts?: RequestOptions): Promise<DnsRecord[]> {
+    return this.notImplemented('getDnsRecords');
+  }
+
+  setDnsRecords(
+    _domainName: string,
+    _records: DnsRecord[],
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('setDnsRecords');
+  }
+
+  // --- extended capabilities (opt-in; default to NotImplementedError) ---
+
+  getEmailForwarding(_domainName: string, _opts?: RequestOptions): Promise<EmailForward[]> {
+    return this.notImplemented('getEmailForwarding');
+  }
+
+  setEmailForwarding(
+    _domainName: string,
+    _forwards: EmailForward[],
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('setEmailForwarding');
+  }
+
+  getDomainForwarding(_domainName: string, _opts?: RequestOptions): Promise<DomainForward[]> {
+    return this.notImplemented('getDomainForwarding');
+  }
+
+  setDomainForwarding(
+    _domainName: string,
+    _forwards: DomainForward[],
+    _opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.notImplemented('setDomainForwarding');
+  }
+
+  getAuthCode(_domainName: string, _opts?: RequestOptions): Promise<string> {
+    return this.notImplemented('getAuthCode');
+  }
+
+  getDnssec(_domainName: string, _opts?: RequestOptions): Promise<DnssecStatus> {
+    return this.notImplemented('getDnssec');
+  }
+
+  disableDnssec(_domainName: string, _opts?: RequestOptions): Promise<OperationResult> {
+    return this.notImplemented('disableDnssec');
+  }
+
+  // shared rejection for a capability a provider hasn't wired up yet
+  protected notImplemented(method: string): Promise<never> {
+    return Promise.reject(new NotImplementedError(`${this.name}: ${method} is not implemented`));
+  }
+}