@aoxborrow/registrar-client 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aoxborrow/registrar-client",
-  "version": "0.5.0",
+  "version": "0.7.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",

package/src/errors.ts

@@ -75,11 +75,79 @@ export class TimeoutError extends RetryableRegistrarError {
 // network/connection failure reaching the registrar API
 export class ConnectionError extends RetryableRegistrarError {
   public status = 503; // Service Unavailable
+  // true when the failure is known to have happened before the request left:
+  // DNS, connection refused, TLS handshake, or a proxy that never opened its
+  // tunnel. The registrar cannot have acted on it, so it is safe to re-send
+  // even for a write.
+  public notSent: boolean;
 
-  constructor(message: string) {
+  constructor(message: string, details: { notSent?: boolean } = {}) {
     super(message);
     this.name = 'ConnectionError';
+    this.notSent = details.notSent ?? false;
+  }
+}
+
+// A write failed in a way that leaves its result unknown: the request timed
+// out, the connection dropped mid-response, or the registrar answered 5xx. It
+// may have been applied. Never retried by the library; re-read the domain
+// before trying again.
+export class OutcomeUnknownError extends RegistrarError {
+  public status = 504; // Gateway Timeout
+  public feature?: string;
+  public override cause?: unknown;
+
+  constructor(message: string, details: { feature?: string; cause?: unknown } = {}) {
+    super(message);
+    this.name = 'OutcomeUnknownError';
+    this.feature = details.feature;
+    this.cause = details.cause;
+  }
+}
+
+const NOT_SENT = Symbol.for('registrar-client.notSent');
+
+// For custom `fetch` transports: mark an error as having occurred before the
+// request was sent (proxy unreachable, proxy auth refused, tunnel TLS failed).
+// Returns the same error for `throw markNotSent(err)`.
+export function markNotSent<T>(error: T): T {
+  if (typeof error === 'object' && error !== null) {
+    Object.defineProperty(error, NOT_SENT, { value: true, enumerable: false });
+  }
+  return error;
+}
+
+// error codes Node's fetch (undici) reports, via `error.cause.code`, for
+// failures that happen before any request bytes are written
+const PRE_SEND_CODES = new Set([
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ECONNREFUSED',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'EADDRNOTAVAIL',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'CERT_HAS_EXPIRED',
+  'CERT_NOT_YET_VALID',
+  'DEPTH_ZERO_SELF_SIGNED_CERT',
+  'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
+  'UNABLE_TO_GET_ISSUER_CERT_LOCALLY',
+  'ERR_TLS_CERT_ALTNAME_INVALID',
+]);
+
+// Whether a fetch rejection is known to have happened before the request was
+// sent. Only positive evidence counts: an explicit `markNotSent`, or a
+// pre-connection error code. Runtimes that expose no code (browsers, Workers)
+// yield false, which is the safe answer.
+export function wasNotSent(error: unknown): boolean {
+  for (let e: unknown = error, depth = 0; e && typeof e === 'object' && depth < 5; depth++) {
+    if ((e as Record<symbol, unknown>)[NOT_SENT] === true) return true;
+    const code = (e as { code?: unknown }).code;
+    if (typeof code === 'string' && PRE_SEND_CODES.has(code)) return true;
+    e = (e as { cause?: unknown }).cause;
   }
+  return false;
 }
 
 // registrar API rejected the credentials

package/src/features.ts

@@ -102,3 +102,45 @@ const CORE_FEATURE_SET: ReadonlySet<RegistrarFeature> = new Set(CORE_FEATURES);
 export function isCoreFeature(feature: RegistrarFeature): boolean {
   return CORE_FEATURE_SET.has(feature);
 }
+
+// How each feature method is served: whether it only reads registrar state or
+// may change it, and which positional argument carries its `RequestOptions`.
+//
+// The intent decides what may be re-sent after a failure (see `HttpClient`). It
+// is keyed by feature rather than by HTTP method because the method says
+// nothing reliable: Namecheap sends every command, writes included, as a GET,
+// and Porkbun sends reads as POSTs.
+//
+// Typed as a total record so adding a feature without classifying it fails to
+// compile. `getAuthCode` is a write: several registrars regenerate the code,
+// invalidating the previous one.
+export const FEATURE_CALLS: Record<
+  RegistrarFeature,
+  { intent: 'read' | 'write'; optsIndex: number }
+> = {
+  testConnection: { intent: 'read', optsIndex: 0 },
+  listDomains: { intent: 'read', optsIndex: 0 },
+  getDomain: { intent: 'read', optsIndex: 1 },
+  checkAvailability: { intent: 'read', optsIndex: 1 },
+  getPricing: { intent: 'read', optsIndex: 1 },
+  registerDomain: { intent: 'write', optsIndex: 2 },
+  renewDomain: { intent: 'write', optsIndex: 2 },
+  setAutoRenew: { intent: 'write', optsIndex: 2 },
+  transferIn: { intent: 'write', optsIndex: 2 },
+  updateNameservers: { intent: 'write', optsIndex: 2 },
+  getNameservers: { intent: 'read', optsIndex: 1 },
+  lockDomain: { intent: 'write', optsIndex: 1 },
+  unlockDomain: { intent: 'write', optsIndex: 1 },
+  setPrivacy: { intent: 'write', optsIndex: 2 },
+  getContacts: { intent: 'read', optsIndex: 1 },
+  updateContacts: { intent: 'write', optsIndex: 2 },
+  getDnsRecords: { intent: 'read', optsIndex: 1 },
+  setDnsRecords: { intent: 'write', optsIndex: 2 },
+  getAuthCode: { intent: 'write', optsIndex: 1 },
+  getDnssec: { intent: 'read', optsIndex: 1 },
+  disableDnssec: { intent: 'write', optsIndex: 1 },
+  getEmailForwarding: { intent: 'read', optsIndex: 1 },
+  setEmailForwarding: { intent: 'write', optsIndex: 2 },
+  getDomainForwarding: { intent: 'read', optsIndex: 1 },
+  setDomainForwarding: { intent: 'write', optsIndex: 2 },
+};

package/src/http.ts

@@ -6,13 +6,15 @@ import {
   ConnectionError,
   InvalidResponseError,
   NotFoundError,
+  OutcomeUnknownError,
   ParsingError,
   RateLimitError,
   RegistrarError,
   TimeoutError,
   toRegistrarError,
+  wasNotSent,
 } from './errors';
-import type { RegistrarClientOptions } from './types';
+import type { FeatureCall, RegistrarClientOptions } from './types';
 import { backoffDelay, sleep } from './utils';
 
 // configuration for an HttpClient instance
@@ -23,8 +25,16 @@ export interface HttpClientConfig {
   headers?: Record<string, string>;
   // request/retry behavior
   options: RegistrarClientOptions;
+  // HTTP methods this API reserves for requests that never change state. A
+  // REST API sets `REST_SAFE_METHODS`, so a lookup made in the middle of a
+  // write (a zone list, a price check) is still retried like any read. Leave
+  // unset for APIs where the method means nothing: Namecheap and NameSilo send
+  // writes as GET. Those mark their nested reads with `asRead` instead.
+  safeMethods?: readonly string[];
 }
 
+export const REST_SAFE_METHODS: readonly string[] = ['GET', 'HEAD'];
+
 // options for a single request
 export interface RequestConfig {
   method?: string;
@@ -40,6 +50,11 @@ export interface RequestConfig {
   retries?: number;
   backoff?: number;
   signal?: AbortSignal;
+  fetch?: typeof globalThis.fetch;
+  // which feature this request serves and whether it reads or writes; arrives
+  // with the caller's `RequestOptions`. A request without one is treated as a
+  // write, the safe assumption.
+  call?: FeatureCall;
 }
 
 // a small, browser/edge-safe fetch wrapper with timeout, abort linking,
@@ -67,7 +82,20 @@ export class HttpClient {
     return this.withRetries(req, () => this.send(req));
   }
 
-  // shared retry-with-backoff wrapper around a single-attempt operation
+  // Shared retry-with-backoff wrapper around a single-attempt operation.
+  //
+  // What may be re-sent depends on where the failure happened and on whether
+  // the call reads or writes:
+  //
+  //   failure                                        read    write
+  //   never sent (DNS, refused, TLS, proxy stage)    retry   retry
+  //   429                                            retry   retry
+  //   unknown (timeout, dropped mid-response, 5xx)   retry   OutcomeUnknownError
+  //   any other response                             fail    fail
+  //
+  // A write whose outcome is unknown may have been applied, so it is never
+  // re-sent: a second renewal charges twice, a second record-create leaves a
+  // duplicate. The caller re-reads the domain instead.
   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;
@@ -79,6 +107,16 @@ export class HttpClient {
       } catch (error) {
         lastError = toRegistrarError(error);
 
+        if (this.intentOf(req) === 'write' && isOutcomeUnknown(lastError)) {
+          const unknown = new OutcomeUnknownError(
+            `The registrar did not confirm this change, so it may or may not have been applied. ` +
+              `Check the domain before trying again. (${lastError.message})`,
+            { feature: req.call?.feature, cause: lastError }
+          );
+          if (req.call) req.call.outcomeUnknown = unknown;
+          throw unknown;
+        }
+
         // out of attempts, or the error is not retryable
         if (attempt >= retries || !lastError.shouldRetry()) {
           throw lastError;
@@ -97,6 +135,15 @@ export class HttpClient {
     throw lastError ?? new RegistrarError('Request failed');
   }
 
+  // Whether a request only reads. A method the API reserves for reads wins;
+  // otherwise it is whatever the feature being served is, and a request that
+  // says nothing is assumed to write.
+  protected intentOf(req: RequestConfig): 'read' | 'write' {
+    const method = (req.method ?? 'GET').toUpperCase();
+    if (this.config.safeMethods?.includes(method)) return 'read';
+    return req.call?.intent ?? 'write';
+  }
+
   // build the full URL for a request, applying query parameters
   protected buildUrl(req: RequestConfig): string {
     let base: string;
@@ -146,7 +193,8 @@ export class HttpClient {
     try {
       let response: Response;
       try {
-        response = await fetch(url, {
+        const doFetch = req.fetch ?? this.config.options.fetch ?? fetch;
+        response = await doFetch(url, {
           method: req.method ?? 'GET',
           headers,
           body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
@@ -158,7 +206,9 @@ export class HttpClient {
           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)}`);
+        throw new ConnectionError(`Failed to reach '${url}': ${errorMessage(error)}`, {
+          notSent: wasNotSent(error),
+        });
       }
 
       if (!response.ok) {
@@ -169,7 +219,20 @@ export class HttpClient {
       if (response.status === 204) {
         return '';
       }
-      return await response.text();
+      try {
+        return await response.text();
+      } catch (error) {
+        // The registrar answered, then the body was cut off. The request was
+        // certainly sent, so for a write the outcome is unknown; a read can
+        // simply be retried.
+        if (isAbortError(error)) {
+          if (externalSignal?.aborted) throw new AbortError('Request was aborted');
+          throw new TimeoutError(`Response from '${url}' timed out after ${timeout}ms`);
+        }
+        throw new ConnectionError(
+          `Connection to '${url}' was lost while reading the response: ${errorMessage(error)}`
+        );
+      }
     } finally {
       clearTimeout(timeoutId);
       externalSignal?.removeEventListener('abort', onAbort);
@@ -214,6 +277,14 @@ export class HttpClient {
   }
 }
 
+// A retryable failure that leaves a write's result unknown: the request may
+// have reached the registrar. A rate limit is an explicit rejection, and a
+// connection error known to precede sending never reached it.
+function isOutcomeUnknown(error: RegistrarError): boolean {
+  if (error instanceof TimeoutError || error instanceof InvalidResponseError) return true;
+  return error instanceof ConnectionError && !error.notSent;
+}
+
 // detect an AbortController/fetch abort across environments
 function isAbortError(error: unknown): boolean {
   return (

package/src/index.ts

@@ -3,7 +3,7 @@
 export { RegistrarClient } from './client';
 export { listPortfolio } from './portfolio';
 export type { DomainSource, PortfolioError, PortfolioResult } from './portfolio';
-export { HttpClient } from './http';
+export { HttpClient, REST_SAFE_METHODS } from './http';
 export type { HttpClientConfig, RequestConfig } from './http';
 
 // core registrar abstraction (the `Registrar` interface itself is exported via
@@ -15,7 +15,14 @@ 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 {
+  Feature,
+  CORE_FEATURES,
+  EXTENDED_FEATURES,
+  ALL_FEATURES,
+  FEATURE_CALLS,
+  isCoreFeature,
+} from './features';
 export type { RegistrarFeature } from './features';
 
 // bundled providers
@@ -25,6 +32,7 @@ export { GandiRegistrar } from './registrars/gandi';
 export { GoDaddyRegistrar } from './registrars/godaddy';
 export { NameBrightRegistrar } from './registrars/namebright';
 export { NamecheapRegistrar } from './registrars/namecheap';
+export { NamecomRegistrar } from './registrars/namecom';
 export { NameSiloRegistrar } from './registrars/namesilo';
 export { PorkbunRegistrar } from './registrars/porkbun';
 export { SpaceshipRegistrar } from './registrars/spaceship';

package/src/registrar.ts

@@ -1,7 +1,7 @@
 import { DEFAULT_OPTIONS } from './constants';
 import { ConfigurationError, NotImplementedError } from './errors';
 import { HttpClient, type HttpClientConfig } from './http';
-import { CORE_FEATURES, type RegistrarFeature } from './features';
+import { CORE_FEATURES, FEATURE_CALLS, type RegistrarFeature } from './features';
 import type {
   ConnectionResult,
   ContactSet,
@@ -18,6 +18,7 @@ import type {
   RegistrarClientOptions,
   RegistrarCredentials,
   RegistrarEnvironment,
+  FeatureCall,
   RegistrarOptions,
   RequestOptions,
   TldPricing,
@@ -65,6 +66,10 @@ export abstract class BaseRegistrar implements Registrar {
     return [...CORE_FEATURES, ...this.extendedFeatures];
   }
 
+  // HTTP methods this provider's API reserves for reads; see
+  // `HttpClientConfig.safeMethods`. REST providers set `REST_SAFE_METHODS`.
+  static readonly safeMethods: readonly string[] = [];
+
   // instance mirror of the static `features`
   get features(): readonly RegistrarFeature[] {
     return (this.constructor as typeof BaseRegistrar).features;
@@ -90,7 +95,47 @@ export abstract class BaseRegistrar implements Registrar {
     this.credentials = credentials;
     this.environment = environment;
     this.options = { ...DEFAULT_OPTIONS, ...clientOptions };
-    this.http = new HttpClient({ ...httpConfig, options: this.options });
+    this.http = new HttpClient({
+      safeMethods: (this.constructor as typeof BaseRegistrar).safeMethods,
+      ...httpConfig,
+      options: this.options,
+    });
+    this.threadFeatureCalls();
+  }
+
+  // Wrap each feature method so its `RequestOptions` carry a `FeatureCall`:
+  // the read/write intent the HTTP layer needs to decide what may be re-sent,
+  // and a slot where it reports a write whose outcome is unknown. Providers
+  // already forward their options into every request, so nothing else changes.
+  //
+  // A feature calling another feature (a write re-reading the domain, say)
+  // goes through that feature's own wrapper, so the inner read is still a read.
+  // Providers fold most failures into an `OperationResult`; the unknown outcome
+  // is copied onto that result so it is not lost along with the error.
+  private threadFeatureCalls(): void {
+    const self = this as unknown as Record<string, unknown>;
+    for (const [feature, { intent, optsIndex }] of Object.entries(FEATURE_CALLS)) {
+      const original = self[feature];
+      if (typeof original !== 'function') continue;
+      // Not `async`: a provider that validates its arguments by throwing
+      // synchronously keeps doing so.
+      self[feature] = (...args: unknown[]): unknown => {
+        const call: FeatureCall = { intent, feature };
+        const next = [...args];
+        while (next.length <= optsIndex) next.push(undefined);
+        next[optsIndex] = { ...(next[optsIndex] as RequestOptions | undefined), call };
+        const result: unknown = (original as (...a: unknown[]) => unknown).apply(this, next);
+        if (!(result instanceof Promise)) return result;
+        return result.then((value: unknown) =>
+          call.outcomeUnknown &&
+          value !== null &&
+          typeof value === 'object' &&
+          (value as OperationResult).success === false
+            ? { ...value, outcome: 'unknown' }
+            : value
+        );
+      };
+    }
   }
 
   testConnection(_opts?: RequestOptions): Promise<ConnectionResult> {

package/src/registrars/cloudflare.ts

@@ -15,6 +15,7 @@ import type {
   RequestOptions,
   TldPricing,
 } from '../types';
+import { REST_SAFE_METHODS } from '../http';
 import { createDomain, filterDomains, normalizeDomain, settableForwards } from '../utils';
 import { NotImplementedError, toRegistrarError } from '../errors';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
@@ -173,6 +174,8 @@ interface CfDnsRecord {
  */
 export class CloudflareRegistrar extends BaseRegistrar {
   readonly name = 'cloudflare';
+  // a REST API: GET and HEAD never change state
+  static override readonly safeMethods = REST_SAFE_METHODS;
 
   static readonly displayName = 'Cloudflare';
   static readonly website = 'cloudflare.com';

package/src/registrars/dynadot.ts

@@ -17,6 +17,7 @@ import type {
   TldPricing,
   TransferDomainInput,
 } from '../types';
+import { REST_SAFE_METHODS } from '../http';
 import { createDomain, filterDomains, requireConsent, settableForwards } from '../utils';
 import { NotFoundError, NotImplementedError, toRegistrarError } from '../errors';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
@@ -178,6 +179,8 @@ const SUPPORTED_DNS_TYPES = new Set(['A', 'AAAA', 'CNAME', 'MX', 'TXT', 'NS', 'S
  */
 export class DynadotRegistrar extends BaseRegistrar {
   readonly name = 'dynadot';
+  // a REST API: GET and HEAD never change state
+  static override readonly safeMethods = REST_SAFE_METHODS;
 
   static readonly displayName = 'Dynadot';
   static readonly website = 'dynadot.com';

package/src/registrars/gandi.ts

@@ -19,6 +19,7 @@ import type {
   TldPricing,
   TransferDomainInput,
 } from '../types';
+import { REST_SAFE_METHODS } from '../http';
 import { createDomain, filterDomains, settableForwards } from '../utils';
 import { toRegistrarError } from '../errors';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
@@ -159,6 +160,8 @@ const GANDI_TYPE_TO_FORWARD: Record<string, DomainForwardType> = {
  */
 export class GandiRegistrar extends BaseRegistrar {
   readonly name = 'gandi';
+  // a REST API: GET and HEAD never change state
+  static override readonly safeMethods = REST_SAFE_METHODS;
 
   static readonly displayName = 'Gandi.net';
   static readonly website = 'gandi.net';

package/src/registrars/godaddy.ts

@@ -17,6 +17,7 @@ import type {
   TldPricing,
   TransferDomainInput,
 } from '../types';
+import { REST_SAFE_METHODS } from '../http';
 import { createDomain, filterDomains, settableForwards } from '../utils';
 import {
   ConfigurationError,
@@ -267,6 +268,8 @@ interface GdV3Operation {
  */
 export class GoDaddyRegistrar extends BaseRegistrar {
   readonly name = 'godaddy';
+  // a REST API: GET and HEAD never change state
+  static override readonly safeMethods = REST_SAFE_METHODS;
 
   static readonly displayName = 'GoDaddy';
   static readonly website = 'godaddy.com';

package/src/registrars/index.ts

@@ -10,6 +10,7 @@ import { GandiRegistrar } from './gandi';
 import { GoDaddyRegistrar } from './godaddy';
 import { NameBrightRegistrar } from './namebright';
 import { NamecheapRegistrar } from './namecheap';
+import { NamecomRegistrar } from './namecom';
 import { NameSiloRegistrar } from './namesilo';
 import { PorkbunRegistrar } from './porkbun';
 import { SpaceshipRegistrar } from './spaceship';
@@ -22,6 +23,7 @@ export const registrars = {
   godaddy: GoDaddyRegistrar,
   namebright: NameBrightRegistrar,
   namecheap: NamecheapRegistrar,
+  namecom: NamecomRegistrar,
   namesilo: NameSiloRegistrar,
   porkbun: PorkbunRegistrar,
   spaceship: SpaceshipRegistrar,

package/src/registrars/namebright.ts

@@ -13,12 +13,13 @@ import type {
   RequestOptions,
   TldPricing,
 } from '../types';
-import { createDomain, filterDomains } from '../utils';
+import { asRead, createDomain, filterDomains } from '../utils';
 import { AuthenticationError, NotImplementedError, toRegistrarError } from '../errors';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
 import { Feature, type RegistrarFeature } from '../features';
 import type { RegistrarCredentials } from '../types';
 import type { RequestConfig } from '../http';
+import { REST_SAFE_METHODS } from '../http';
 
 const TOKEN_URL = 'https://api.namebright.com/auth/token';
 
@@ -196,6 +197,8 @@ interface NbAvailability {
  */
 export class NameBrightRegistrar extends BaseRegistrar {
   readonly name = 'namebright';
+  // a REST API: GET and HEAD never change state
+  static override readonly safeMethods = REST_SAFE_METHODS;
 
   static readonly displayName = 'NameBright';
   static readonly website = 'namebright.com';
@@ -243,7 +246,8 @@ export class NameBrightRegistrar extends BaseRegistrar {
         client_id: this.credentials.clientId,
         client_secret: this.credentials.clientSecret,
       },
-      ...opts,
+      // issuing a token changes nothing on the account, whatever it precedes
+      ...asRead(opts),
     });
     if (!res.access_token) {
       throw new AuthenticationError('NameBright: token endpoint returned no access_token');

package/src/registrars/namecheap.ts

@@ -18,6 +18,7 @@ import type {
   TransferDomainInput,
 } from '../types';
 import {
+  asRead,
   createDomain,
   filterDomains,
   normalizeDomain,
@@ -580,7 +581,11 @@ export class NamecheapRegistrar extends BaseRegistrar {
     enabled: boolean,
     opts?: RequestOptions
   ): Promise<OperationResult> {
-    const cr = await this.command('namecheap.domains.getInfo', { DomainName: domainName }, opts);
+    const cr = await this.command(
+      'namecheap.domains.getInfo',
+      { DomainName: domainName },
+      asRead(opts)
+    );
     const id = cr.DomainGetInfoResult?.Whoisguard?.ID;
     if (id == null || String(id) === '0') {
       throw new Error(`${this.name}: ${domainName} has no WhoisGuard subscription to toggle`);