@aoxborrow/registrar-client 0.5.0 → 0.7.0

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)

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;
+}