@aoxborrow/registrar-client 0.6.0 → 0.7.0

package/package.json

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

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/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`);

package/src/registrars/namecom.ts

@@ -9,7 +9,7 @@ import {
   toRegistrarError,
 } from '../errors';
 import { Feature, type RegistrarFeature } from '../features';
-import { HttpClient, type RequestConfig } from '../http';
+import { HttpClient, type RequestConfig, REST_SAFE_METHODS } from '../http';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
 import type {
   ConfigField,
@@ -94,7 +94,7 @@ class NamecomHttpClient extends HttpClient {
     } catch (error) {
       if (error instanceof ParsingError) throw new ParsingError('namecom: invalid JSON response');
       if (error instanceof ConnectionError)
-        throw new ConnectionError('namecom: network request failed');
+        throw new ConnectionError('namecom: network request failed', { notSent: error.notSent });
       throw error;
     }
   }
@@ -127,6 +127,8 @@ class NamecomHttpClient extends HttpClient {
 
 export class NamecomRegistrar extends BaseRegistrar {
   readonly name = 'namecom';
+  // a REST API: GET and HEAD never change state
+  static override readonly safeMethods = REST_SAFE_METHODS;
   static readonly displayName = 'Name.com';
   static readonly website = 'name.com';
   static readonly supportsSandbox = true;
@@ -158,7 +160,11 @@ export class NamecomRegistrar extends BaseRegistrar {
       headers: { Authorization: `Basic ${auth}` },
     };
     super(credentials, config, options);
-    this.http = new NamecomHttpClient({ ...config, options: this.options });
+    this.http = new NamecomHttpClient({
+      ...config,
+      safeMethods: REST_SAFE_METHODS,
+      options: this.options,
+    });
   }
 
   override async testConnection(opts?: RequestOptions): Promise<ConnectionResult> {
@@ -444,7 +450,6 @@ export class NamecomRegistrar extends BaseRegistrar {
         const old = index >= 0 ? remaining.splice(index, 1)[0] : undefined;
         await this.http.request({
           ...opts,
-          retries: 0,
           method: old ? 'PUT' : 'POST',
           path: old ? `${path}/${old.id!}` : path,
           body: record,
@@ -453,7 +458,6 @@ export class NamecomRegistrar extends BaseRegistrar {
       for (const old of remaining) {
         await this.http.request({
           ...opts,
-          retries: 0,
           method: 'DELETE',
           path: `${path}/${old.id!}`,
         });
@@ -532,7 +536,7 @@ export class NamecomRegistrar extends BaseRegistrar {
   }
   private async mutate(req: RequestConfig, opts?: RequestOptions): Promise<OperationResult> {
     try {
-      await this.http.request({ ...req, ...opts, retries: 0 });
+      await this.http.request({ ...req, ...opts });
       return { success: true, message: 'Domain updated successfully' };
     } catch (error) {
       return { success: false, message: toRegistrarError(error).message };

package/src/registrars/namesilo.ts

@@ -18,7 +18,7 @@ import type {
   TldPricing,
   TransferDomainInput,
 } from '../types';
-import { createDomain, filterDomains, settableForwards } from '../utils';
+import { asRead, createDomain, filterDomains, settableForwards } from '../utils';
 import { NotFoundError, toRegistrarError } from '../errors';
 import { ensureArray, parseXml } from '../xml';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
@@ -486,7 +486,7 @@ export class NameSiloRegistrar extends BaseRegistrar {
     opts?: RequestOptions
   ): Promise<OperationResult> {
     try {
-      const res = await this.call('dnsSecListRecords', { domain: domainName }, opts);
+      const res = await this.call('dnsSecListRecords', { domain: domainName }, asRead(opts));
       if (!replyOk(res)) return statusResult(res);
       for (const d of ensureArray<NsDsRecord>(res.reply?.ds_record)) {
         const del = await this.call(
@@ -574,7 +574,7 @@ export class NameSiloRegistrar extends BaseRegistrar {
         desired.set(f.alias, list);
       }
       const currentAliases = new Set(
-        (await this.listEmailForwards(domainName, opts)).map(r => r.alias).filter(Boolean)
+        (await this.listEmailForwards(domainName, asRead(opts))).map(r => r.alias).filter(Boolean)
       );
 
       for (const alias of currentAliases) {
@@ -696,7 +696,7 @@ export class NameSiloRegistrar extends BaseRegistrar {
     records: DnsRecord[],
     opts?: RequestOptions
   ): Promise<OperationResult> {
-    const listRes = await this.call('dnsListRecords', { domain: domainName }, opts);
+    const listRes = await this.call('dnsListRecords', { domain: domainName }, asRead(opts));
     if (!replyOk(listRes)) return { success: false, message: replyDetail(listRes) };
     const existing = ensureArray(listRes.reply?.resource_record);
 

package/src/registrars/porkbun.ts

@@ -17,7 +17,7 @@ import type {
   TldPricing,
   TransferDomainInput,
 } from '../types';
-import { createDomain, filterDomains, normalizeDomain, settableForwards } from '../utils';
+import { asRead, createDomain, filterDomains, normalizeDomain, settableForwards } from '../utils';
 import { NotFoundError, NotImplementedError, toRegistrarError } from '../errors';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
 import { Feature, type RegistrarFeature } from '../features';
@@ -520,7 +520,7 @@ export class PorkbunRegistrar extends BaseRegistrar {
     _years = 1,
     opts?: RequestOptions
   ): Promise<OperationResult> {
-    const pricing = await this.tldPricing(extractTld(domainName), opts);
+    const pricing = await this.tldPricing(extractTld(domainName), asRead(opts));
     if (pricing.renewal == null) {
       throw new Error(`${this.name}: could not determine the renewal price for ${domainName}`);
     }
@@ -563,7 +563,7 @@ export class PorkbunRegistrar extends BaseRegistrar {
     input: TransferDomainInput,
     opts?: RequestOptions
   ): Promise<OperationResult> {
-    const pricing = await this.tldPricing(extractTld(domainName), opts);
+    const pricing = await this.tldPricing(extractTld(domainName), asRead(opts));
     if (pricing.transfer == null) {
       throw new Error(`${this.name}: could not determine the transfer price for ${domainName}`);
     }

package/src/registrars/spaceship.ts

@@ -14,6 +14,7 @@ import type {
   TldPricing,
   TransferDomainInput,
 } from '../types';
+import { REST_SAFE_METHODS } from '../http';
 import { createDomain, filterDomains, requireConsent, sleep } from '../utils';
 import { NotImplementedError, toRegistrarError } from '../errors';
 import { BaseRegistrar, selectBaseUrl } from '../registrar';
@@ -131,6 +132,8 @@ const WRITABLE_DNS_TYPES = new Set(['A', 'AAAA', 'CNAME', 'NS', 'TXT', 'MX']);
  */
 export class SpaceshipRegistrar extends BaseRegistrar {
   readonly name = 'spaceship';
+  // a REST API: GET and HEAD never change state
+  static override readonly safeMethods = REST_SAFE_METHODS;
 
   static readonly displayName = 'Spaceship';
   static readonly website = 'spaceship.com';