@aoxborrow/registrar-client 0.6.0 → 0.8.0

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;
     }
   }
@@ -108,18 +108,14 @@ class NamecomHttpClient extends HttpClient {
       }),
       url
     );
-    if (error instanceof RateLimitError) {
-      const retryAfter = response.headers.get('retry-after');
-      const seconds = retryAfter == null ? NaN : Number(retryAfter);
-      const date = retryAfter == null ? NaN : Date.parse(retryAfter);
-      const reset = response.headers.get('x-ratelimit-reset');
-      error.retryAfter = Number.isFinite(seconds)
-        ? Math.max(0, seconds)
-        : Number.isFinite(date)
-          ? Math.max(0, (date - Date.now()) / 1000)
-          : reset != null && Number.isFinite(Number(reset))
-            ? Math.max(0, Number(reset) - Date.now() / 1000)
-            : undefined;
+    // The shared client has already read Retry-After. Without a usable one,
+    // fall back to X-RateLimit-Reset (Unix seconds); otherwise leave it unset
+    // so the configured backoff applies.
+    if (error instanceof RateLimitError && error.retryAfter === undefined) {
+      const reset = response.headers.get('x-ratelimit-reset')?.trim();
+      if (reset && /^\d+(?:\.\d+)?$/.test(reset)) {
+        error.retryAfter = Math.max(0, Math.ceil(Number(reset) - Date.now() / 1000));
+      }
     }
     return error;
   }
@@ -127,6 +123,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 +156,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 +446,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 +454,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 +532,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';

package/src/types.ts

@@ -12,10 +12,34 @@ export interface RegistrarClientOptions {
   backoff: number;
   // optional AbortSignal to cancel in-flight requests
   signal?: AbortSignal;
+  // fetch implementation used for every request, e.g. one that routes through a
+  // proxy. Defaults to the global `fetch`. A transport that fails before the
+  // request leaves (proxy refused, tunnel not established) should throw an
+  // error marked with `markNotSent` so the failure is retried for any call.
+  fetch?: typeof globalThis.fetch;
+}
+
+// whether a call only reads registrar state or may change it. Decides what is
+// safe to re-send after a failure; see `FEATURE_CALLS` in features.ts.
+export type RequestIntent = 'read' | 'write';
+
+// per-call bookkeeping the library threads through `RequestOptions` from a
+// feature method down to the HTTP layer. Set by `BaseRegistrar`; callers never
+// need to supply it.
+export interface FeatureCall {
+  intent: RequestIntent;
+  // the feature method being served, e.g. "renewDomain"
+  feature?: string;
+  // set by the HTTP layer when a write's outcome could not be determined, so
+  // it survives providers that fold errors into an `OperationResult`
+  outcomeUnknown?: Error;
 }
 
 // per-request options that can override client-level options
-export type RequestOptions = Partial<RegistrarClientOptions>;
+export interface RequestOptions extends Partial<RegistrarClientOptions> {
+  // library-internal; see `FeatureCall`
+  call?: FeatureCall;
+}
 
 // options for `listDomains`. Extends `RequestOptions` so timeout/retries/signal
 // still flow through a single argument. `listDomains` always returns the full
@@ -56,6 +80,11 @@ export interface ConnectionResult {
 export interface OperationResult {
   success: boolean;
   message: string;
+  // Present only on a failed write whose request may have reached the
+  // registrar (timed out, connection dropped mid-response, or a 5xx). The
+  // change may or may not have been applied: re-read the domain before trying
+  // again. The library never re-sends such a request itself.
+  outcome?: 'unknown';
 }
 
 // a configuration field a registrar needs (used to build credential UIs generically)
@@ -165,6 +194,9 @@ export interface DomainAvailability {
   premium?: boolean;
   // registration price in major currency units (e.g. 11.99), when the API reports it
   price?: number;
+  // annual renewal price in major currency units, when the API reports one for
+  // this specific name (e.g. a premium name's renewal)
+  renewalPrice?: number;
   // ISO 4217 currency code, e.g. "USD"
   currency?: string;
   // the registration period the price covers, in years

package/src/utils.ts

@@ -1,4 +1,10 @@
-import type { DomainForward, Domain, DomainInput, RegistrationConsent } from './types';
+import type {
+  DomainForward,
+  Domain,
+  DomainInput,
+  RegistrationConsent,
+  RequestOptions,
+} from './types';
 import { ConsentRequiredError } from './errors';
 
 // sleep helper for retry backoff
@@ -133,3 +139,12 @@ export function createDomain(data: DomainInput = {}): Domain {
     deleted: data.deleted ?? false,
   };
 }
+
+// Marks a request made inside a write feature as a read: a lookup the write
+// needs first (current records, a price, an auth token). It is retried like any
+// read, and its failure is never reported as a write of unknown outcome. For
+// APIs whose HTTP method can't tell reads from writes; REST providers get this
+// from `safeMethods`.
+export function asRead<T extends RequestOptions>(opts?: T): T {
+  return { ...opts, call: { ...opts?.call, intent: 'read' } } as T;
+}