@aoxborrow/registrar-client 0.5.0 → 0.7.0

package/README.md

@@ -51,6 +51,7 @@ npm install @aoxborrow/registrar-client
 | `godaddy`    | GoDaddy    | PAT, or key + secret       | ✓       | hybrid v3/v1; sandbox = OTE (v1 only)        |
 | `namebright` | NameBright | client ID + secret         | —       | OAuth2 bearer; production-only               |
 | `namecheap`  | Namecheap  | username + key + client IP | ✓       | XML API; IP allowlisting required            |
+| `namecom`    | Name.com   | username + API token       | ✓       | Core v1; separate sandbox host and token     |
 | `namesilo`   | NameSilo   | API key                    | ✓       | JSON/XML API; key sent in query string       |
 | `porkbun`    | Porkbun    | key + secret               | ✓       | sandbox via `pk1_sb_` key; per-domain opt-in |
 | `spaceship`  | Spaceship  | key + secret               | —       |                                              |
@@ -161,42 +162,46 @@ are the guaranteed contract; **extended** methods are opt-in per provider.
 **Legend:** ✓ implemented · ✗ not available via the provider's API (throws
 `NotImplementedError`) · a superscript marks a caveat noted below.
 
-| Core method         | CF  | DY  | GA  | GD  | NB  | NC  | NS  | PB  | SP  |
-| ------------------- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| `testConnection`    | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `listDomains`       | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `getDomain`         | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `checkAvailability` | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `getPricing`        | ✓   | ✓ᵃ  | ✓   | ✓ᵃ  | ✗ᵇ  | ✓   | ✓   | ✓   | ✗ᵇ  |
-| `registerDomain`    | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `renewDomain`       | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `setAutoRenew`      | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `transferIn`        | ✗ᶜ  | ✓   | ✓   | ✓   | ✗ᵈ  | ✓   | ✓   | ✓   | ✓   |
-| `updateNameservers` | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `getNameservers`    | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `lockDomain`        | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   |
-| `unlockDomain`      | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   |
-| `setPrivacy`        | ✓   | ✓   | ✓ᶠ  | ✓ᵍ  | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   |
-| `getContacts`       | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   |
-| `updateContacts`    | ✗ᶜ  | ✓   | ✓   | ✓   | ✗ᵈ  | ✓   | ✓   | ✓   | ✓   |
-| `getDnsRecords`     | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
-| `setDnsRecords`     | ✓   | ✓ʰ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓ʰ  |
-
-| Extended method       | CF  | DY  | GA  | GD  | NB  | NC  | NS  | PB  | SP  |
-| --------------------- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| `getAuthCode`         | ✗   | ✓   | ✓   | ✓   | ✓   | ✗ⁱ  | ✗ⁱ  | ✗   | ✓   |
-| `getDnssec`           | ✗   | ✓   | ✓   | ✗   | ✗   | ✗   | ✓   | ✓   | ✗   |
-| `disableDnssec`       | ✗   | ✓   | ✓   | ✗   | ✗   | ✗   | ✓   | ✓   | ✗   |
-| `getEmailForwarding`  | ✓   | ✓   | ✓   | ✗   | ✗   | ✓   | ✓   | ✗   | ✗   |
-| `setEmailForwarding`  | ✓   | ✓   | ✓   | ✗   | ✗   | ✓   | ✓   | ✗   | ✗   |
-| `getDomainForwarding` | ✓   | ✓ʲ  | ✓ᵏ  | ✓ˡ  | ✗   | ✓   | ✓ʲ  | ✓   | ✗   |
-| `setDomainForwarding` | ✓   | ✓ʲ  | ✓ᵏ  | ✓ˡ  | ✗   | ✓   | ✓ʲ  | ✓   | ✗   |
+| Core method         | CF  | DY  | GA  | GD  | NB  | NC  | NS  | PB  | SP  | NM  |
+| ------------------- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `testConnection`    | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `listDomains`       | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `getDomain`         | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `checkAvailability` | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `getPricing`        | ✓   | ✓ᵃ  | ✓   | ✓ᵃ  | ✗ᵇ  | ✓   | ✓   | ✓   | ✗ᵇ  | ✓   |
+| `registerDomain`    | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `renewDomain`       | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `setAutoRenew`      | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `transferIn`        | ✗ᶜ  | ✓   | ✓   | ✓   | ✗ᵈ  | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `updateNameservers` | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `getNameservers`    | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `lockDomain`        | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   | ✓   |
+| `unlockDomain`      | ✗ᶜ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   | ✓   |
+| `setPrivacy`        | ✓   | ✓   | ✓ᶠ  | ✓ᵍ  | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   | ✓   |
+| `getContacts`       | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✗ᵉ  | ✓   | ✓   |
+| `updateContacts`    | ✗ᶜ  | ✓   | ✓   | ✓   | ✗ᵈ  | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `getDnsRecords`     | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   |
+| `setDnsRecords`     | ✓   | ✓ʰ  | ✓   | ✓   | ✓   | ✓   | ✓   | ✓   | ✓ʰ  | ✓   |
+
+| Extended method       | CF  | DY  | GA  | GD  | NB  | NC  | NS  | PB  | SP  | NM  |
+| --------------------- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `getAuthCode`         | ✗   | ✓   | ✓   | ✓   | ✓   | ✗ⁱ  | ✗ⁱ  | ✗   | ✓   | ✓   |
+| `getDnssec`           | ✗   | ✓   | ✓   | ✗   | ✗   | ✗   | ✓   | ✓   | ✗   | ✗ᵐ  |
+| `disableDnssec`       | ✗   | ✓   | ✓   | ✗   | ✗   | ✗   | ✓   | ✓   | ✗   | ✗ᵐ  |
+| `getEmailForwarding`  | ✓   | ✓   | ✓   | ✗   | ✗   | ✓   | ✓   | ✗   | ✗   | ✗ᵐ  |
+| `setEmailForwarding`  | ✓   | ✓   | ✓   | ✗   | ✗   | ✓   | ✓   | ✗   | ✗   | ✗ᵐ  |
+| `getDomainForwarding` | ✓   | ✓ʲ  | ✓ᵏ  | ✓ˡ  | ✗   | ✓   | ✓ʲ  | ✓   | ✗   | ✗ᵐ  |
+| `setDomainForwarding` | ✓   | ✓ʲ  | ✓ᵏ  | ✓ˡ  | ✗   | ✓   | ✓ʲ  | ✓   | ✗   | ✗ᵐ  |
 
 `CF` Cloudflare · `DY` Dynadot · `GA` Gandi · `GD` GoDaddy · `NB` NameBright ·
-`NC` Namecheap · `NS` NameSilo · `PB` Porkbun · `SP` Spaceship.
+`NC` Namecheap · `NS` NameSilo · `PB` Porkbun · `SP` Spaceship · `NM` Name.com.
 
 **Caveats**
 
+- **ᵐ** Name.com DNSSEC and forwarding are not wired into this adapter yet;
+  they are not advertised as extended features. See [Name.com](#namecom-core-api)
+  for pricing, transfer and DNS limits.
+
 - **ᵃ** `getPricing` is per-domain only (pass a full name, not a bare TLD) —
   Dynadot and GoDaddy price via their availability endpoint and have no per-TLD
   price table.
@@ -330,6 +335,90 @@ most providers need only the auth code (`TransferDomainInput`).
 > per-TLD extended attributes, so TLDs that require them (`.us`, `.eu`, …) aren't
 > registrable there yet.
 
+## Name.com Core API
+
+```ts
+const namecom = createRegistrar(
+  'namecom',
+  {
+    username: 'your-username-test',
+    apiToken: 'your-development-test-token',
+  },
+  { environment: 'sandbox' }
+);
+
+await namecom.listDomains();
+await namecom.getPricing('example.com'); // exact domain prices, including premiums
+await namecom.getPricing('.co.uk'); // explicit compound TLD; 'com' also works
+```
+
+The adapter uses [Core v1](https://docs.name.com/api/v1/overview), with HTTP Basic
+Auth in the Authorization header. Production is `https://api.name.com/core/v1`;
+sandbox is `https://api.dev.name.com/core/v1`. Use the Development/Test token and
+`-test` username from [API settings](https://www.name.com/account/settings/api).
+The username is used exactly as supplied. For 2FA accounts, API Access must be
+enabled. New sandbox credentials can take up to 15 minutes to activate, per the
+[testing guide](https://docs.name.com/guides/testing-environment).
+
+All portfolio and DNS pages are consumed using `nextPage`, including short
+intermediate pages. Missing boolean fields are Core's default `false` values.
+`status` contains the returned registry lock statuses (lowercased, comma separated);
+Core has no lifecycle-status field. `renewalDate` remains null because Core does
+not report a scheduled renewal date. The shared `Domain` model has no price field:
+use `getPricing(domainName)` for renewal prices, rather than estimating them from
+TLD retail prices.
+
+Pricing uses account-level USD amounts before VAT. Domain registration and renewal
+quotes explicitly request one year; unavailable/null products remain undefined.
+Transfer prices cover the registry's transfer term, which may exceed one year.
+Bare compound strings such as `co.uk` are interpreted as domains; use `.co.uk` for
+TLD pricing. Availability is restricted to standard/registry-premium registration,
+batched in groups of 50; its discovery price covers the TLD minimum term, so no
+one-year `period` is inferred.
+
+Registration rechecks availability and obtains a quote for the requested term.
+Premium create/renew/transfer requests send the exact matching purchase, renewal,
+or transfer price; standard operations omit `purchasePrice`. Null/unavailable
+quotes stop the operation before purchase. Registration defaults to one year;
+pass the appropriate `years` for TLDs with a higher minimum. Aftermarket/backorder,
+claims acknowledgments, IDN language attributes, and other TLD-specific registration
+requirements are not exposed by the shared input types. Such registrations require
+a provider-specific workflow. Transfers accept `authCode` and optional `privacy`;
+explicit `years`, `contacts` or `autoRenew` are rejected before submission because
+Core cannot apply them in its transfer request. Update settings after completion.
+
+Mutations follow the shared [retry rules](#retries): a request Name.com may have
+received is never re-sent. Transport/parse failures after a purchase report an
+unknown outcome: inspect Name.com orders and domain/transfer status before retrying. An accepted order is
+reported as accepted, not proof of final registry completion. Read operations
+retain the shared retry policy and honor `Retry-After` / `X-RateLimit-Reset`.
+HTTP errors retain typed status information but omit provider response bodies,
+which may contain credentials, EPP codes or contact data.
+
+Contacts require complete objects for each supplied role (including state), and
+omitted roles are left unchanged on update. Postal code/company and EPP-style
+phone numbers are mapped to Core's `zip`, `companyName` and E.164 fields. DNS
+replacement reconciles individual record IDs, preserving unchanged records and
+creating/updating before removing stale records. This is **not atomic**; failures
+can leave a partial zone, which must be read before retrying. Supported DNS types
+are A, AAAA, ANAME, CNAME, MX, NS, SRV and TXT, with a minimum TTL of 300 seconds.
+Only auth-code retrieval is implemented as an extended feature in this version.
+
+Offline tests exercise the published API contract. Run the dedicated sandbox
+checks with credentials in `.env.testing`:
+
+```bash
+npm run test:integration -- test/integration/namecom.integration.test.ts
+```
+
+Read checks are credential-gated and always use sandbox. To exercise registration,
+renewal, flags, nameservers, contacts and DNS, additionally set
+`NAMECOM_TEST_DOMAIN=registrar-client-<unique-suffix>.com`. This must be a disposable
+sandbox name with that prefix. The test creates it if absent and leaves it in the
+sandbox (Name.com offers no domain deletion/reset there); it is excluded from the
+default offline suite. Transfer completion and production behavior need separate
+verification; sandbox transfers are not deterministic.
+
 ## Sandbox environments
 
 Providers that offer a test environment accept `{ environment: 'sandbox' }` at
@@ -393,8 +482,12 @@ implementations**:
 Extend `BaseRegistrar`, pass a `baseUrl` + auth headers to `super()`, add the
 static `displayName` / `configFields` / `helpText` metadata, override the
 operations the API supports (mapping payloads to the shared types in
-`src/types.ts`), and add the class to `src/registrars/index.ts`. The existing
-providers under `src/registrars/` are working references.
+`src/types.ts`), and add the class to `src/registrars/index.ts`. Forward the
+`opts` you are given into every `this.http` request: they carry the timeout and
+signal, and tell the [retry rules](#retries) whether the call reads or writes.
+For a REST API set `static safeMethods = REST_SAFE_METHODS`; otherwise wrap any
+lookup a write performs first in `asRead(opts)`. The existing providers under
+`src/registrars/` are working references.
 
 **New providers are welcome** — if you've wired up a registrar, open a PR.
 
@@ -404,6 +497,61 @@ All failures throw a typed subclass of `RegistrarError` (`AuthenticationError`,
 `NotFoundError`, `RateLimitError`, `TimeoutError`, `NotImplementedError`, …),
 each carrying an HTTP-style `status`.
 
+## Retries
+
+Requests retry with exponential backoff (`retries`, default 2). What may be
+re-sent depends on where the failure happened and on whether the call reads or
+writes, and is the same for every provider:
+
+| Failure                                                                    | Read  | Write                                  |
+| -------------------------------------------------------------------------- | ----- | -------------------------------------- |
+| The registrar never saw it: DNS failure, connection refused, TLS handshake | Retry | Retry                                  |
+| `429`, honoring `Retry-After`                                              | Retry | Retry                                  |
+| Outcome unknown: timeout, connection dropped mid-response, `5xx`           | Retry | **Not re-sent.** `OutcomeUnknownError` |
+| Any other response                                                         | Fail  | Fail                                   |
+
+Reads and writes are told apart by feature, not by HTTP method (`FEATURE_CALLS`
+lists every one). The method is no guide: Namecheap sends writes as `GET`, and
+Porkbun sends reads as `POST`. `getAuthCode` counts as a write because some
+registrars regenerate the code.
+
+A write often reads first: current DNS records, a price, a zone id. Those
+lookups changed nothing, so they are retried like any read and never reported as
+an unknown outcome. REST providers get this from the HTTP method
+(`static safeMethods = REST_SAFE_METHODS` treats `GET` and `HEAD` as reads);
+providers whose method means nothing wrap the lookup's options in `asRead(opts)`.
+
+A write whose outcome is unknown may have been applied, and a second renewal
+charges twice. So the library reports it and leaves the decision to you: re-read
+the domain, then retry if nothing changed. Providers that throw raise
+`OutcomeUnknownError`; providers that return an `OperationResult` set
+`outcome: 'unknown'` on it:
+
+```ts
+const result = await client.renewDomain('example.com', 1);
+if (!result.success && result.outcome === 'unknown') {
+  const domain = await client.getDomain('example.com'); // did it go through?
+}
+```
+
+Only positive evidence counts as "never sent": a pre-connection error code from
+Node's `fetch`, or an error a custom transport marked with `markNotSent`.
+Browsers and Workers report network failures opaquely, so there they count as
+unknown.
+
+### Custom transport
+
+Pass `fetch` to route every request through your own transport, such as a
+proxy:
+
+```ts
+const registrar = createRegistrar('namecheap', credentials, { fetch: proxiedFetch });
+```
+
+If the transport can fail before the request leaves, for instance a proxy that
+refuses the tunnel, throw `markNotSent(error)` so the failure is retried even
+for writes.
+
 ## Security
 
 Credentials are sent as request **headers** wherever the registrar's API