@aoxborrow/registrar-client 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aoxborrow/registrar-client",
-  "version": "0.11.0",
+  "version": "0.12.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/registrars/gandi.ts

@@ -19,6 +19,7 @@ import type {
   RequestOptions,
   TldPricing,
   TransferDomainInput,
+  TransferOut,
 } from '../types';
 import { REST_SAFE_METHODS } from '../http';
 import {
@@ -78,6 +79,8 @@ interface GandiDomain {
   contacts?: GandiContacts;
   nameserver?: { current?: string; hosts?: string[] };
   nameservers?: string[];
+  // the transfer auth code (detail endpoint only)
+  authinfo?: string;
 }
 
 // one record set from `GET /v5/livedns/domains/{fqdn}/records`; a set can hold
@@ -192,9 +195,9 @@ export class GandiRegistrar extends BaseRegistrar {
   ];
   // Gandi's v5 API offers a sandbox at api.sandbox.gandi.net (separate account)
   static readonly supportsSandbox = true;
-  // On top of core: transfer-out auth code (`authinfo`), DNSSEC read/disable
-  // (LiveDNS keys), email forwarding, and web/URL forwarding (webredirs;
-  // per host, apex included). Note core `setPrivacy` disabling is a no-op for
+  // On top of core: transfer-out auth code (`authinfo`) and approval, DNSSEC
+  // read/disable (LiveDNS keys), email forwarding, and web/URL forwarding
+  // (webredirs; per host, apex included). Note core `setPrivacy` disabling is a no-op for
   // individual (natural-person) registrants — Gandi keeps WHOIS obfuscation on
   // for GDPR regardless of the request.
   static readonly extendedFeatures: readonly RegistrarFeature[] = [
@@ -205,6 +208,9 @@ export class GandiRegistrar extends BaseRegistrar {
     Feature.SetEmailForwarding,
     Feature.GetDomainForwarding,
     Feature.SetDomainForwarding,
+    Feature.GetTransferOut,
+    Feature.ApproveTransferOut,
+    Feature.RejectTransferOut,
   ];
 
   constructor(credentials: RegistrarCredentials, options?: RegistrarOptions) {
@@ -500,6 +506,75 @@ export class GandiRegistrar extends BaseRegistrar {
     return d.authinfo ?? '';
   }
 
+  /**
+   * The domain's pending outbound transfer. Gandi has no transfer-out resource
+   * to read: a domain in the account carries the documented `pendingTransfer`
+   * EPP status while another registrar's request waits (inbound transfers live
+   * under /domain/transferin, so on a domain you hold it's outbound — inferred,
+   * not documented). Gandi reports no dates for it, and nothing once it's
+   * answered or done, so this reads `pending` or null.
+   */
+  override async getTransferOut(
+    domainName: string,
+    opts?: RequestOptions
+  ): Promise<TransferOut | null> {
+    const d = await this.http.request<GandiDomain>({
+      path: `/domain/domains/${domainName}`,
+      ...opts,
+    });
+    return pendingTransferOut(d);
+  }
+
+  /**
+   * Approves the pending outbound transfer, releasing the domain now instead of
+   * after Gandi's five days: POST .../transferout with `accept: true` and the
+   * domain's current auth code, which Gandi requires back (→ 202).
+   */
+  override async approveTransferOut(
+    domainName: string,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.answerTransferOut(domainName, true, opts);
+  }
+
+  // Declines the pending outbound transfer (`accept: false`, no reason); the
+  // domain stays in the account.
+  override async rejectTransferOut(
+    domainName: string,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.answerTransferOut(domainName, false, opts);
+  }
+
+  // One read for both the pending status and the auth code the answer needs.
+  private async answerTransferOut(
+    domainName: string,
+    accept: boolean,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    let d: GandiDomain;
+    try {
+      d = await this.http.request<GandiDomain>({
+        path: `/domain/domains/${domainName}`,
+        ...opts,
+      });
+    } catch (error) {
+      return { success: false, message: toRegistrarError(error).message };
+    }
+    if (!pendingTransferOut(d)) {
+      return { success: false, message: `No transfer-out of ${domainName} to answer` };
+    }
+    return this.mutate(
+      {
+        method: 'POST',
+        path: `/domain/domains/${domainName}/transferout`,
+        body: { accept, authinfo: d.authinfo ?? '' },
+      },
+      `Transfer of ${domainName} ${accept ? 'approved' : 'rejected'}`,
+      opts
+    );
+  }
+
   /**
    * DNSSEC status via Gandi LiveDNS keys (GET /livedns/domains/{fqdn}/keys). A
    * non-deleted key means DNSSEC is enabled; each key's `ds` field is the full DS
@@ -939,6 +1014,19 @@ export class GandiRegistrar extends BaseRegistrar {
   }
 }
 
+// A pending outbound transfer, from the domain's `pendingTransfer` EPP status.
+function pendingTransferOut(d: GandiDomain): TransferOut | null {
+  const statuses = Array.isArray(d.status) ? d.status : d.status ? [d.status] : [];
+  if (!statuses.includes('pendingTransfer')) return null;
+  return {
+    status: 'pending',
+    rawStatus: 'pendingTransfer',
+    requestedDate: null,
+    expirationDate: null,
+    completedDate: null,
+  };
+}
+
 // map a Gandi contact into the normalized Contact shape. Gandi has no distinct
 // second address line, so `address2` is left undefined.
 // map the normalized Contact to Gandi's contact shape (given/family/streetaddr/…).

package/src/registrars/godaddy.ts

@@ -16,9 +16,11 @@ import type {
   RequestOptions,
   TldPricing,
   TransferDomainInput,
+  TransferOut,
+  TransferOutStatus,
 } from '../types';
 import { REST_SAFE_METHODS } from '../http';
-import { createDomain, filterDomains, settableForwards } from '../utils';
+import { createDomain, filterDomains, parseDate, settableForwards } from '../utils';
 import {
   ConfigurationError,
   ConsentRequiredError,
@@ -112,6 +114,19 @@ interface GoDaddyForward {
   mask?: { title?: string; description?: string; keywords?: string };
 }
 
+// One entry of the v2 recent-actions list,
+// GET /v2/customers/{customerId}/domains/{domain}/actions (`[]` when there are
+// none, verified live 2026-10-31). An outbound transfer shows as a TRANSFER_OUT
+// action while it's in progress; answering it logs TRANSFER_OUT_ACCEPT or
+// TRANSFER_OUT_REJECT. `status` is ACCEPTED / AWAITING / PENDING / SUCCESS /
+// FAILED / CANCELLED.
+interface GoDaddyAction {
+  type?: string;
+  status?: string;
+  createdAt?: string;
+  completedAt?: string;
+}
+
 // normalized DomainForwardType → the token the v2 write endpoint expects
 const GD_FORWARD_TYPE: Record<'temporary' | 'permanent', string> = {
   permanent: 'REDIRECT_PERMANENT',
@@ -299,17 +314,22 @@ export class GoDaddyRegistrar extends BaseRegistrar {
   ];
   // GoDaddy's OTE ("Operational Test Environment") is its sandbox
   static readonly supportsSandbox = true;
-  // Beyond core: domain forwarding and transfer-out auth code (the `authCode`
-  // field on the v1 domain-detail response). Forwarding uses the v2
-  // customer-scoped route /v2/customers/{customerId}/domains/forwards/{fqdn}
-  // (the old v1 /v1/domains/forwards routes now 404); it requires `customerId`
-  // to be configured — verified live 2026-08-29. DNSSEC has no dedicated
+  // Beyond core: domain forwarding, transfer-out auth code (the `authCode`
+  // field on the v1 domain-detail response) and transfer-out approval.
+  // Forwarding uses the v2 customer-scoped route
+  // /v2/customers/{customerId}/domains/forwards/{fqdn} (the old v1
+  // /v1/domains/forwards routes now 404); it requires `customerId` to be
+  // configured — verified live 2026-08-29. Transfer-out approval is v2
+  // customer-scoped too, so it needs `customerId` as well. DNSSEC has no dedicated
   // endpoint (DS records go through the generic DNS API), and there's no
   // glue-record, email, or push-webhook API.
   static readonly extendedFeatures: readonly RegistrarFeature[] = [
     Feature.GetAuthCode,
     Feature.GetDomainForwarding,
     Feature.SetDomainForwarding,
+    Feature.GetTransferOut,
+    Feature.ApproveTransferOut,
+    Feature.RejectTransferOut,
   ];
 
   // true → prefer the v3 API (production + PAT). false → all calls use v1
@@ -1046,8 +1066,9 @@ export class GoDaddyRegistrar extends BaseRegistrar {
     const configured = this.credentials.customerId?.trim();
     if (!configured) {
       throw new ConfigurationError(
-        `${this.name}: domain forwarding uses the v2 customer-scoped API, which ` +
-          'requires a customer ID. Set `customerId` to your GoDaddy customer UUID ' +
+        `${this.name}: domain forwarding and transfer-out approval use the v2 ` +
+          'customer-scoped API, which requires a customer ID. Set `customerId` to ' +
+          'your GoDaddy customer UUID ' +
           '(or your numeric shopper/account ID, which will be resolved to the UUID).'
       );
     }
@@ -1167,6 +1188,71 @@ export class GoDaddyRegistrar extends BaseRegistrar {
     return `/v2/customers/${encodeURIComponent(customerId)}/domains/forwards/${encodeURIComponent(fqdn)}`;
   }
 
+  // the v2 customer-scoped path for a domain
+  private domainPathV2(customerId: string, domainName: string): string {
+    return `/v2/customers/${encodeURIComponent(customerId)}/domains/${encodeURIComponent(domainName)}`;
+  }
+
+  /**
+   * The domain's latest outbound transfer, read from its recent actions
+   * (GET /v2/customers/{customerId}/domains/{domain}/actions): the TRANSFER_OUT
+   * action, and an accept or reject logged after it. Null when there is no
+   * TRANSFER_OUT on record. GoDaddy reports no expiry; left alone, it releases
+   * the domain within seven days. Shapes from the published v2 spec; a real
+   * transfer-out is not yet seen live.
+   */
+  override async getTransferOut(
+    domainName: string,
+    opts?: RequestOptions
+  ): Promise<TransferOut | null> {
+    const customerId = await this.resolveCustomerId(opts);
+    const actions = await this.http.request<GoDaddyAction[]>({
+      path: `${this.domainPathV2(customerId, domainName)}/actions`,
+      ...opts,
+    });
+    return toTransferOut(Array.isArray(actions) ? actions : []);
+  }
+
+  /**
+   * Approves the pending outbound transfer, releasing the domain now
+   * (POST .../transferOutAccept → 202). GoDaddy answers 409 when none is
+   * pending.
+   */
+  override async approveTransferOut(
+    domainName: string,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.answerTransferOut(domainName, 'transferOutAccept', 'approved', opts);
+  }
+
+  // Rejects the pending outbound transfer (POST .../transferOutReject, with no
+  // reason); the domain stays in the account.
+  override async rejectTransferOut(
+    domainName: string,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    return this.answerTransferOut(domainName, 'transferOutReject', 'rejected', opts);
+  }
+
+  private async answerTransferOut(
+    domainName: string,
+    action: 'transferOutAccept' | 'transferOutReject',
+    answer: string,
+    opts?: RequestOptions
+  ): Promise<OperationResult> {
+    let customerId: string;
+    try {
+      customerId = await this.resolveCustomerId(opts);
+    } catch (error) {
+      return { success: false, message: toRegistrarError(error).message };
+    }
+    return this.mutate(
+      { method: 'POST', path: `${this.domainPathV2(customerId, domainName)}/${action}` },
+      `Transfer of ${domainName} ${answer}`,
+      opts
+    );
+  }
+
   /**
    * Transfer authorization (EPP) code. GoDaddy exposes it as the `authCode`
    * field on the v1 domain-detail response; transfers were never moved to v3,
@@ -1231,6 +1317,48 @@ export class GoDaddyRegistrar extends BaseRegistrar {
   }
 }
 
+// --- transfer-out mapping ---
+
+// GoDaddy's recent actions → the domain's latest transfer-out. The TRANSFER_OUT
+// action carries the transfer; while it's open, the latest accept or reject
+// logged after it (unless that failed) says how it was answered.
+function toTransferOut(actions: GoDaddyAction[]): TransferOut | null {
+  const time = (a: GoDaddyAction) => parseDate(a.createdAt)?.getTime() ?? 0;
+  const byLatest = (types: string[]) =>
+    actions.filter(a => types.includes(a.type ?? '')).sort((a, b) => time(b) - time(a));
+  const transfer = byLatest(['TRANSFER_OUT'])[0];
+  if (!transfer) return null;
+  const answer = byLatest(['TRANSFER_OUT_ACCEPT', 'TRANSFER_OUT_REJECT']).find(
+    a => time(a) >= time(transfer) && !/^(FAILED|CANCELLED)$/i.test(a.status ?? '')
+  );
+  const rejected = answer?.type === 'TRANSFER_OUT_REJECT';
+  const rawStatus = transfer.status ?? '';
+  let status: TransferOutStatus;
+  switch (rawStatus.toUpperCase()) {
+    case 'ACCEPTED':
+    case 'AWAITING':
+    case 'PENDING':
+      status = !answer ? 'pending' : rejected ? 'rejected' : 'approved';
+      break;
+    case 'SUCCESS':
+      status = 'completed';
+      break;
+    case 'FAILED':
+    case 'CANCELLED':
+      status = rejected ? 'rejected' : 'cancelled';
+      break;
+    default:
+      status = 'unknown';
+  }
+  return {
+    status,
+    rawStatus,
+    requestedDate: parseDate(transfer.createdAt),
+    expirationDate: null,
+    completedDate: status === 'completed' ? parseDate(transfer.completedAt) : null,
+  };
+}
+
 // --- contact mapping between GoDaddy's shape and the normalized Contact ---
 
 function fromGoDaddyContact(c: GoDaddyContact | undefined): Contact | undefined {