@aoxborrow/registrar-client 0.6.0 → 0.7.0

package/dist/index.js

@@ -55,11 +55,61 @@ var TimeoutError = class extends RetryableRegistrarError {
 var ConnectionError = class extends RetryableRegistrarError {
   status = 503;
   // Service Unavailable
-  constructor(message) {
+  // 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.
+  notSent;
+  constructor(message, details = {}) {
     super(message);
     this.name = "ConnectionError";
+    this.notSent = details.notSent ?? false;
   }
 };
+var OutcomeUnknownError = class extends RegistrarError {
+  status = 504;
+  // Gateway Timeout
+  feature;
+  cause;
+  constructor(message, details = {}) {
+    super(message);
+    this.name = "OutcomeUnknownError";
+    this.feature = details.feature;
+    this.cause = details.cause;
+  }
+};
+var NOT_SENT = /* @__PURE__ */ Symbol.for("registrar-client.notSent");
+function markNotSent(error) {
+  if (typeof error === "object" && error !== null) {
+    Object.defineProperty(error, NOT_SENT, { value: true, enumerable: false });
+  }
+  return error;
+}
+var PRE_SEND_CODES = /* @__PURE__ */ 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"
+]);
+function wasNotSent(error) {
+  for (let e = error, depth = 0; e && typeof e === "object" && depth < 5; depth++) {
+    if (e[NOT_SENT] === true) return true;
+    const code = e.code;
+    if (typeof code === "string" && PRE_SEND_CODES.has(code)) return true;
+    e = e.cause;
+  }
+  return false;
+}
 var AuthenticationError = class extends RegistrarError {
   status = 401;
   // Unauthorized
@@ -226,6 +276,9 @@ function createDomain(data = {}) {
     deleted: data.deleted ?? false
   };
 }
+function asRead(opts) {
+  return { ...opts, call: { ...opts?.call, intent: "read" } };
+}
 
 // src/client.ts
 var RegistrarClient = class {
@@ -376,6 +429,7 @@ var DEFAULT_OPTIONS = {
 var USER_AGENT = "@aoxborrow/registrar-client";
 
 // src/http.ts
+var REST_SAFE_METHODS = ["GET", "HEAD"];
 var HttpClient = class {
   constructor(config) {
     this.config = config;
@@ -399,7 +453,20 @@ var HttpClient = class {
   async requestText(req) {
     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.
   async withRetries(req, attemptFn) {
     const retries = req.retries ?? this.config.options.retries;
     const backoff = req.backoff ?? this.config.options.backoff;
@@ -409,6 +476,14 @@ var HttpClient = class {
         return await attemptFn();
       } 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;
+        }
         if (attempt >= retries || !lastError.shouldRetry()) {
           throw lastError;
         }
@@ -418,6 +493,14 @@ var HttpClient = class {
     }
     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.
+  intentOf(req) {
+    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
   buildUrl(req) {
     let base;
@@ -460,7 +543,8 @@ var HttpClient = class {
     try {
       let 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 !== void 0 ? JSON.stringify(req.body) : void 0,
@@ -471,7 +555,9 @@ var HttpClient = class {
           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) {
         throw await this.toStatusError(response, url);
@@ -479,7 +565,17 @@ var HttpClient = class {
       if (response.status === 204) {
         return "";
       }
-      return await response.text();
+      try {
+        return await response.text();
+      } catch (error) {
+        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);
@@ -515,6 +611,10 @@ var HttpClient = class {
     }
   }
 };
+function isOutcomeUnknown(error) {
+  if (error instanceof TimeoutError || error instanceof InvalidResponseError) return true;
+  return error instanceof ConnectionError && !error.notSent;
+}
 function isAbortError(error) {
   return typeof error === "object" && error !== null && "name" in error && error.name === "AbortError";
 }
@@ -611,6 +711,33 @@ var CORE_FEATURE_SET = new Set(CORE_FEATURES);
 function isCoreFeature(feature) {
   return CORE_FEATURE_SET.has(feature);
 }
+var FEATURE_CALLS = {
+  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 }
+};
 
 // src/registrar.ts
 function selectBaseUrl(registrar, environment, urls) {
@@ -636,6 +763,9 @@ var BaseRegistrar = class {
   static get features() {
     return [...CORE_FEATURES, ...this.extendedFeatures];
   }
+  // HTTP methods this provider's API reserves for reads; see
+  // `HttpClientConfig.safeMethods`. REST providers set `REST_SAFE_METHODS`.
+  static safeMethods = [];
   // instance mirror of the static `features`
   get features() {
     return this.constructor.features;
@@ -654,7 +784,39 @@ var BaseRegistrar = class {
     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.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.
+  threadFeatureCalls() {
+    const self = this;
+    for (const [feature, { intent, optsIndex }] of Object.entries(FEATURE_CALLS)) {
+      const original = self[feature];
+      if (typeof original !== "function") continue;
+      self[feature] = (...args) => {
+        const call = { intent, feature };
+        const next = [...args];
+        while (next.length <= optsIndex) next.push(void 0);
+        next[optsIndex] = { ...next[optsIndex], call };
+        const result = original.apply(this, next);
+        if (!(result instanceof Promise)) return result;
+        return result.then(
+          (value) => call.outcomeUnknown && value !== null && typeof value === "object" && value.success === false ? { ...value, outcome: "unknown" } : value
+        );
+      };
+    }
   }
   testConnection(_opts) {
     return Promise.reject(
@@ -745,6 +907,8 @@ var BaseRegistrar = class {
 // src/registrars/cloudflare.ts
 var CloudflareRegistrar = class _CloudflareRegistrar extends BaseRegistrar {
   name = "cloudflare";
+  // a REST API: GET and HEAD never change state
+  static safeMethods = REST_SAFE_METHODS;
   static displayName = "Cloudflare";
   static website = "cloudflare.com";
   static helpText = 'Create an API token in your Cloudflare dashboard under My Profile > API Tokens. The token needs "Account.Registrar" read/write permissions. Find your Account ID in the URL or on the Overview page of any zone.';
@@ -1602,6 +1766,8 @@ var SEARCH_BATCH_SIZE = 100;
 var SUPPORTED_DNS_TYPES = /* @__PURE__ */ new Set(["A", "AAAA", "CNAME", "MX", "TXT", "NS", "SRV", "CAA"]);
 var DynadotRegistrar = class extends BaseRegistrar {
   name = "dynadot";
+  // a REST API: GET and HEAD never change state
+  static safeMethods = REST_SAFE_METHODS;
   static displayName = "Dynadot";
   static website = "dynadot.com";
   static helpText = "Under Tools > API in your Dynadot account, generate an API Key and API Secret. The account must be unlocked with API access enabled. The key identifies you; the secret signs requests (X-Signature) and is never sent directly.";
@@ -2353,6 +2519,8 @@ var GANDI_TYPE_TO_FORWARD = {
 };
 var GandiRegistrar = class extends BaseRegistrar {
   name = "gandi";
+  // a REST API: GET and HEAD never change state
+  static safeMethods = REST_SAFE_METHODS;
   static displayName = "Gandi.net";
   static website = "gandi.net";
   static helpText = "Generate a Personal Access Token (PAT) in your Gandi account under Account Settings > Security. The token needs permission to manage domains. (Gandi has deprecated the legacy API Key; use a PAT.)";
@@ -3040,6 +3208,8 @@ var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var PRICE_MICRO_UNITS = 1e6;
 var GoDaddyRegistrar = class _GoDaddyRegistrar extends BaseRegistrar {
   name = "godaddy";
+  // a REST API: GET and HEAD never change state
+  static safeMethods = REST_SAFE_METHODS;
   static displayName = "GoDaddy";
   static website = "godaddy.com";
   static helpText = "Create a Personal Access Token (PAT) at https://developer.godaddy.com and paste it here. The PAT is GoDaddy's modern credential: it unlocks the v3 API (discovery, registration, DNS, nameservers) and also authenticates the legacy v1 API for management operations (renew, transfer, auto-renew, lock, privacy, contacts) \u2014 one token covers everything.";
@@ -3920,6 +4090,8 @@ function dnsFieldsDiffer(a, b) {
 var TOKEN_URL = "https://api.namebright.com/auth/token";
 var NameBrightRegistrar = class extends BaseRegistrar {
   name = "namebright";
+  // a REST API: GET and HEAD never change state
+  static safeMethods = REST_SAFE_METHODS;
   static displayName = "NameBright";
   static website = "namebright.com";
   static helpText = 'API access is not enabled by default \u2014 you must request it from NameBright (contact support / your account manager) before the API Management page is available. Once enabled, create an API Application under my.namebright.com > My Account > API Management. The Client ID is "<accountName>:<applicationName>"; NameBright issues the Client Secret. Note the application also enforces an IP whitelist.';
@@ -3958,7 +4130,8 @@ var NameBrightRegistrar = class 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");
@@ -4737,7 +4910,11 @@ var NamecheapRegistrar = class extends BaseRegistrar {
    * has no WhoisGuard allotted (e.g. TLDs that don't offer it).
    */
   async setPrivacy(domainName, enabled, opts) {
-    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`);
@@ -4977,7 +5154,7 @@ var NamecomHttpClient = class 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;
     }
   }
@@ -5002,6 +5179,8 @@ var NamecomHttpClient = class extends HttpClient {
 };
 var NamecomRegistrar = class extends BaseRegistrar {
   name = "namecom";
+  // a REST API: GET and HEAD never change state
+  static safeMethods = REST_SAFE_METHODS;
   static displayName = "Name.com";
   static website = "name.com";
   static supportsSandbox = true;
@@ -5030,7 +5209,11 @@ var NamecomRegistrar = class 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
+    });
   }
   async testConnection(opts) {
     try {
@@ -5258,7 +5441,6 @@ var NamecomRegistrar = class extends BaseRegistrar {
         const old = index >= 0 ? remaining.splice(index, 1)[0] : void 0;
         await this.http.request({
           ...opts,
-          retries: 0,
           method: old ? "PUT" : "POST",
           path: old ? `${path}/${old.id}` : path,
           body: record
@@ -5267,7 +5449,6 @@ var NamecomRegistrar = class extends BaseRegistrar {
       for (const old of remaining) {
         await this.http.request({
           ...opts,
-          retries: 0,
           method: "DELETE",
           path: `${path}/${old.id}`
         });
@@ -5331,7 +5512,7 @@ var NamecomRegistrar = class extends BaseRegistrar {
   }
   async mutate(req, opts) {
     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 };
@@ -5744,7 +5925,7 @@ var NameSiloRegistrar = class extends BaseRegistrar {
    */
   async disableDnssec(domainName, opts) {
     try {
-      const res = await this.call("dnsSecListRecords", { domain: domainName }, opts);
+      const res = await this.call("dnsSecListRecords", { domain: domainName }, asRead(opts));
       if (!replyOk(res)) return statusResult2(res);
       for (const d of ensureArray(res.reply?.ds_record)) {
         const del = await this.call(
@@ -5817,7 +5998,7 @@ var NameSiloRegistrar = class 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) {
         if (!desired.has(alias)) {
@@ -5908,7 +6089,7 @@ var NameSiloRegistrar = class extends BaseRegistrar {
    * delegation nameservers aren't part of this list (see `updateNameservers`).
    */
   async setDnsRecords(domainName, records, opts) {
-    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);
     const existingByKey = /* @__PURE__ */ new Map();
@@ -6435,7 +6616,7 @@ var PorkbunRegistrar = class extends BaseRegistrar {
    * renewals aren't supported via the API.
    */
   async renewDomain(domainName, _years = 1, opts) {
-    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}`);
     }
@@ -6466,7 +6647,7 @@ var PorkbunRegistrar = class extends BaseRegistrar {
    * aren't supported via the API.
    */
   async transferIn(domainName, input, opts) {
-    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}`);
     }
@@ -6759,6 +6940,8 @@ function toDnsRecord3(r, domainName) {
 var WRITABLE_DNS_TYPES = /* @__PURE__ */ new Set(["A", "AAAA", "CNAME", "NS", "TXT", "MX"]);
 var SpaceshipRegistrar = class extends BaseRegistrar {
   name = "spaceship";
+  // a REST API: GET and HEAD never change state
+  static safeMethods = REST_SAFE_METHODS;
   static displayName = "Spaceship";
   static website = "spaceship.com";
   static helpText = 'Generate your API key and secret in the API Manager at Spaceship using the "New API key" button. The API requires both X-API-Key and X-API-Secret headers.';
@@ -7279,6 +7462,6 @@ function createRegistrar(name, credentials, options) {
   return new RegistrarClass(credentials, options);
 }
 
-export { ALL_FEATURES, AbortError, AuthenticationError, AuthorizationError, BaseRegistrar, CORE_FEATURES, CloudflareRegistrar, ConfigurationError, ConnectionError, ConsentRequiredError, DEFAULT_OPTIONS, DynadotRegistrar, EXTENDED_FEATURES, Feature, GandiRegistrar, GoDaddyRegistrar, HttpClient, InvalidResponseError, MASKED_FORWARD_UNSUPPORTED, NameBrightRegistrar, NameSiloRegistrar, NamecheapRegistrar, NamecomRegistrar, NotFoundError, NotImplementedError, ParsingError, PorkbunRegistrar, RateLimitError, RegistrarClient, RegistrarError, RetryableRegistrarError, SpaceshipRegistrar, TimeoutError, USER_AGENT, backoffDelay, createDomain, createRegistrar, ensureArray, filterDomains, isCoreFeature, listPortfolio, normalizeDomain, normalizeNameservers, parseDate, parseXml, registrars, requireConsent, selectBaseUrl, settableForwards, sleep, toRegistrarError };
+export { ALL_FEATURES, AbortError, AuthenticationError, AuthorizationError, BaseRegistrar, CORE_FEATURES, CloudflareRegistrar, ConfigurationError, ConnectionError, ConsentRequiredError, DEFAULT_OPTIONS, DynadotRegistrar, EXTENDED_FEATURES, FEATURE_CALLS, Feature, GandiRegistrar, GoDaddyRegistrar, HttpClient, InvalidResponseError, MASKED_FORWARD_UNSUPPORTED, NameBrightRegistrar, NameSiloRegistrar, NamecheapRegistrar, NamecomRegistrar, NotFoundError, NotImplementedError, OutcomeUnknownError, ParsingError, PorkbunRegistrar, REST_SAFE_METHODS, RateLimitError, RegistrarClient, RegistrarError, RetryableRegistrarError, SpaceshipRegistrar, TimeoutError, USER_AGENT, asRead, backoffDelay, createDomain, createRegistrar, ensureArray, filterDomains, isCoreFeature, listPortfolio, markNotSent, normalizeDomain, normalizeNameservers, parseDate, parseXml, registrars, requireConsent, selectBaseUrl, settableForwards, sleep, toRegistrarError, wasNotSent };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map