Evaluate replacing the vendored spec + codegen with the official name.com Core SDK

[patramsey]

name.com now publishes an official Go SDK for the Core API:
https://github.com/namedotcom/core-api-go (MIT, Fern-generated, v1.33.2).
It did not exist when this CLI was built, which is why internal/api/gen exists
at all. It is worth evaluating whether adopting it lets us delete most of that.

What it could replace

Today	With the SDK
internal/api/gen/zz_generated.go — 23,381 generated lines	github.com/namedotcom/core-api-go
namecom.api.yaml vendored spec + make verify-spec SHA pin	upstream's problem
scripts/spec_to_30.py — the OpenAPI 3.1 → 3.0 preprocessor	gone
make generate + oapi-codegen	gone
retry/backoff in internal/api/transport.go	built in (exponential, configurable limit, default 2)
parseError() in internal/api/apierror.go	core.APIError, errors.As-compatible

The preprocessor is the part worth highlighting. It exists solely because
oapi-codegen v2.4.x lacks OpenAPI 3.1 support, and it carries three documented
workarounds: nullable type: [T, null] unions, bare - type: null oneOf
members, and 33 *Response schema names renamed to *ResponseSchema to avoid
colliding with generated operation wrappers. All of that is scaffolding for a
problem the SDK does not have.

It should also retire the "Key generated type gotchas" section of CLAUDE.md —
Record.Ttl being int64 while body Ttl is *int64, Record.Type being
*string while create/update need a gen.DNSCreateRecordBodyType(str) cast,
DomainResponsePayload.Locked being a bool alias rather than *bool. Those
are artifacts of our codegen path, and every one of them is a place a
contributor has to be told something non-obvious.

Endpoint coverage looks complete

The SDK's service packages line up with our command groups, with room to spare:

domains  dns  dnssecs  emailforwardings  urlforwardings  vanitynameservers
transfers  orders  refunds  contactverification  tldpricing  premiumdomains
accountinfo  domaininfo  accounts  webhooknotifications

webhooknotifications, premiumdomains, and accounts are endpoints we do not
currently surface. Coverage still needs verifying call-by-call against what
cmd/ actually invokes — this list is a directory listing, not a guarantee.

What does not come for free

These are the reasons this is an evaluation issue and not a straightforward
swap. Each needs an answer before committing.

1. Client-side rate limiting. We run a x/time/rate limiter at 10 req/s
   with burst 5 in internal/api/transport.go. The SDK documents retries but
   not rate limiting. Probably preserved by passing our own instrumented
   *http.Client via option.WithHTTPClient — needs confirming.

2. Idempotency-key gating on POST retries. Our transport retries a POST
   only when X-Idempotency-Key is set, which is what keeps a retried
   registration from becoming two registrations. The SDK's legacy retry
   profile retries 408/429/5XX; we need to know whether it applies that to
   unsafe methods, and whether --idempotency-key can be threaded through. This
   is the highest-stakes item on the list — getting it wrong costs real money.

3. Auth shape. We set an Authorization header directly (client.go:134)
   and deliberately let namecom api --header 'Authorization: …' override it.
   The SDK exposes option.WithBasicAuth(username, password) and
   option.WithToken. Need to confirm which one name.com Core expects and that
   the escape hatch survives.

4. Flags that reach into the transport. --base-url maps cleanly onto
   option.WithBaseURL, and --sandbox onto the SDK's environments. --debug
   / --debug-file and the User-Agent both live in our http.Client, so they
   ride along with item 1.

5. namecom api raw passthrough. cmd/apicmd uses Client.HTTPClient()
   directly and does not care about generated types. It needs whatever
   configured *http.Client we end up with, not the typed surface.

Risk

The SDK is new — repo created 2026-07-02, last pushed 2026-08-18. One star,
and Fern regenerates it, so expect version churn and the possibility of
breaking changes between minor tags. Dependencies are light (google/uuid,
testify) and go.mod declares go 1.22, so nothing conflicts with our
1.26.6 toolchain. MIT on both sides.

Worth weighing against the status quo, which is not free either: we currently
own a spec pin, a Python preprocessor, and a codegen step that no upstream
maintains for us.

Suggested first step

Spike one command group — dns is a good candidate, since it exercises reads,
the read-modify-write update path, and typed enums — against the SDK on a
branch, without deleting anything. That answers items 1–3 concretely and gives
a real diff to judge the ergonomics from, before committing to a migration that
touches every command.

[patramsey]

Decision on item 1 of "what does not come for free": the SDK's retry profile is
acceptable as-is. We do not need to reproduce our own backoff — adopting
legacy (408 / 429 / 5XX, exponential, default limit 2) is fine, and dropping
that half of internal/api/transport.go is part of the win.

Worth separating two things that item ran together, though, because only one of
them is settled:

• Which status codes get retried, and how — settled, use theirs.
• Whether an unsafe method gets retried at all without an idempotency key —
  still open, and still the highest-stakes question on the list.

Our transport retries a POST only when X-Idempotency-Key is set. That is not
a preference about backoff; it is what keeps a retried domain register from
becoming two registrations against a real balance. Accepting the SDK's retry
profile does not answer whether it applies that profile to POSTs unconditionally.
The spike needs to establish, concretely:

1. Does the SDK retry a POST that has no idempotency key?
2. Can --idempotency-key be threaded onto the requests that take one?
3. If the answer to 1 is yes and 2 is awkward, can retries be disabled per-call
   so we keep the guarantee even at the cost of the built-in behaviour?

Also agreed on the dns spike branch as the first step — no deletions, just
enough of a real diff to answer the above along with rate limiting and auth.

[patramsey]

Correction to the retry framing above. A bug hunt through internal/api
turned up that the premise I stated in the issue body and in the previous
comment is wrong.

I wrote that "our transport retries a POST only when X-Idempotency-Key is
set." It does not. idempotent() in internal/api/transport.go returns true
only for GET/HEAD/PUT/DELETE — POST is never retried on a 5xx, key or no
key — and transport_test.go:149 asserts exactly that, with the comment
"key does not make POST idempotent for 5xx". The code is deliberate and safe;
the claim came from CLAUDE.md:66, which describes behaviour that does not
exist. That doc line is its own bug and is being fixed separately.

This inverts the risk for the migration rather than removing it:

• What I said: we retry keyed POSTs, so check the SDK preserves the gating.
• What is actually true: we never retry POSTs at all, and the SDK's
  legacy profile retries 408/429/5XX. Unless it excludes unsafe methods, the
  migration would introduce POST-on-5xx retries where today there are none.

429 is not affected — the transport already retries any method on a 429, since
a rejected request was never processed.

So the spike question sharpens to: does the SDK retry a POST on a 5xx, and
can that be turned off per-call? If it cannot, adopting its retry profile is
a behaviour change on domain register and domain renew that needs a
deliberate decision, not a default inherited from the generator.

One more thing the hunt surfaced that belongs on this issue: root.go mints
one idempotency key per invocation, not per operation, so dns import
sends the same key on every record's POST. Whatever the SDK does with keys,
that scoping needs fixing on our side first — otherwise it migrates along with
everything else.

[patramsey]

Sandbox result: the records endpoint does not honour idempotency keys, so the
scoping bug was latent rather than active. Correcting my own overstatement
from the comment above.

Method: --idempotency-key pins every write in an invocation to one key, which
reproduces the pre-fix behaviour exactly. Run against an empty sandbox zone.

Two different bodies, one shared key — both created:

POST …/records  body={"answer":"10.0.0.1","host":"dedupe-a",…}
← 200  {"host":"dedupe-a","id":13368551,…}
POST …/records  body={"answer":"10.0.0.2","host":"dedupe-b",…}
← 200  {"host":"dedupe-b","id":13368552,…}
Imported 2 record(s)

Distinct IDs, no replay. Had the key been honoured, the second POST would have
returned record 1's response.

Identical body, same key — rejected on content, not on key:

← 400  {"message":"Parameter Value Error - Record already exists"}

A 400 is the tell. An endpoint honouring the key would have replayed the
original 200; this is ordinary uniqueness validation.

Consistent with the spec: only five operations declare X-Idempotency-Key
in namecom.api.yaml — CreateDomain, PurchasePrivacy, ProcessRefund,
VerifyContact, ResendContactVerificationEmail. CreateRecord is not one of
them, and no single CLI invocation performs more than one of those five writes
today.

So the dns import failure mode I described — records 2..N silently collapsing
onto record 1 while the CLI reports success — would not have happened. The
scoping was still wrong and #41 fixes it, but the fix is a correctness
precondition, not a data-loss repair. It matters the moment a command batches
registrations, privacy purchases, or refunds.

For this issue that sharpens one thing: since only five operations take a key
and the CLI never batches them, whatever the SDK does with key plumbing is a
smaller question than it looked. The POST-on-5xx retry question is the one
that carries the money risk, and it is unchanged — CreateDomain and
ProcessRefund are exactly the calls where an inherited retry profile would
change behaviour.

Test records were deleted; the zone is back to empty.

[patramsey]

Evaluation

Read against v1.33.2 at namedotcom/core-api-go@main, from source rather than
the README. Answers to the five open questions, plus one thing the issue did not
anticipate.

Coverage: complete

All 53 operations the CLI calls have an SDK equivalent. Eight looked missing
on a name match; all eight are Fern renames, not gaps:

CLI	SDK
CreateDNSSEC / GetDNSSEC / DeleteDNSSEC	CreateDnssec / GetDnssec / DeleteDnssec
ListDNSSECs	ListDnsseCs (sic)
GetURLForwardingById etc.	GetURLForwardingByID etc.
Hello	on the root Namecom client

Q1 — rate limiting: solved

core.HTTPClient is a one-method interface:

type HTTPClient interface {
	Do(*http.Request) (*http.Response, error)
}

Our rate-limited client satisfies it as-is and goes in via
option.WithHTTPClient. Nothing to rebuild.

Q2 — POST retries: risk confirmed, and worse than expected

internal/retrier.go:168 decides purely on status code:

func (r *Retrier) shouldRetry(response *http.Response) bool {
	return response.StatusCode == http.StatusTooManyRequests ||
		response.StatusCode == http.StatusRequestTimeout ||
		response.StatusCode >= http.StatusInternalServerError
}

No method check. A POST is retried on a 5xx, which is precisely what
idempotent() refuses to do today, and it lands on CreateDomain,
RenewDomain, and ProcessRefund.

option.WithoutRetries() exists and is a per-request option, so it is
controllable.

New: the SDK's backoff ignores the request context

Not in the original list, and it is the finding that changes the shape of the
migration. internal/retrier.go:146:

time.Sleep(delay)

A bare sleep — no select on ctx.Done(). Combined with honouring
Retry-After up to maxRetryDelay = 60s, one 429 blocks the process for a
minute regardless of --timeout, and the call is uninterruptible while it
waits.

This is a straight regression against what #41 just shipped: our transport
returns the response rather than sleeping past the deadline, so a 429 stays a
429 at exit 5 instead of decaying into a timeout. Adopting the SDK's retry layer
would undo that.

Q3 — auth: byte-identical

core/request_option.go:56 builds "Basic " + base64(username + ":" + password)
— the same header internal/api/client.go:128 constructs today. WithBasicAuth
is a drop-in.

Q4 — environment and transport flags: all covered

Environments.Sandbox and .Production are the same two constants we hardcode.
WithBaseURL covers --base-url and --sandbox; WithHTTPHeader covers the
User-Agent and the namecom api --header 'Authorization: …' escape hatch;
--debug stays in our own *http.Client.

Q5 — namecom api: unaffected

It uses whatever *http.Client we build, and we still build it.

Recommendation: adopt the client, keep our transport

The migration is worth doing, but not as "adopt their retries and delete
ours". Invert it — turn their retry layer off and keep ours:

client.NewNamecom(
    option.WithBasicAuth(creds.Username, creds.Token),
    option.WithHTTPClient(ourRateLimitedRetryingClient), // transport.go, unchanged
    option.WithoutRetries(),                             // theirs off; ours already inside
)

retryTransport is an http.RoundTripper inside the client we hand over, so
every property #41 established survives untouched: the rate limiter, the
POST-on-5xx refusal, the deadline guard, the Retry-After clamp. The SDK never
sees a retryable failure because our transport has already resolved it.

That keeps internal/api/transport.go (298 lines) and still deletes the part
that actually costs us:

Goes	Lines
internal/api/gen/zz_generated.go	23,381
namecom.api.yaml + its SHA pin	16,202
scripts/spec_to_30.py	214
make generate, verify-spec, verify-generate	—
Total	~39,800

Plus the "Key generated type gotchas" section of CLAUDE.md, which exists
entirely because of oapi-codegen's 3.1 handling.

Revised spike scope

Smaller than proposed, because Q1/Q3/Q4/Q5 are now answered from source and need
no experiment. What the dns spike still has to prove:

1. WithoutRetries() genuinely suppresses the retrier when set on the client,
   not just per call — a test that a 500 produces exactly one request.
2. Pagination: the SDK's list responses expose nextPage/lastPage in a form
   cmdutil.NextPage can still gate on.
3. Type ergonomics on the read-modify-write path — whether dns update gets
   simpler or merely different.

If WithoutRetries() does not hold at client scope, the fallback is passing it
per call, which is mechanical but touches every call site and is worth knowing
before committing.

[patramsey]

Spike results — #42 (draft)

Ported the dns read and read-modify-write paths onto the SDK in
internal/sdkspike, wired as recommended. All three questions answered, and two
claims I made earlier turned out to be wrong.

1. WithoutRetries() does not hold at client scope — SDK defect

internal/retrier.go's NewRetrier reads only attempts from the options it is
given and discards disabled. Run honours disabled only from per-call
options, and every generated method rebuilds its options from scratch, so the
client-scoped value never arrives. Measured against a 500:

wiring	requests
WithoutRetries() on the client	2
WithoutRetries() per call	1
no option	2

The per-call fallback works, so the migration is still possible — but it means
all ~53 call sites carry the option, and anything added later that forgets it
silently regains POST-on-5xx retries. That is a standing hazard, not a one-time
cost. Worth raising upstream before committing to the migration.

Confirmed alongside it: the SDK sent a CreateRecord POST twice on a 500, and a
call with a 100ms deadline took 2s against a Retry-After: 2, because the
backoff is a bare time.Sleep.

2. Correction — the type gotchas do NOT disappear

The issue body claimed migrating would retire the "Key generated type gotchas"
section of CLAUDE.md. It would not. Those shapes come from the spec, not from
oapi-codegen, and the SDK reproduces them exactly: Record.TTL is a value while
the update body's is a pointer; Record.Type is a *string while the body's is
a named enum needing a cast. The SDK adds one — Host is a string on the
create body and a *string on the update body.

3. Correction — cmdutil.NextPage does not port unchanged

The SDK reports nextPage/lastPage as *int where the generated client used
*int32. Every paginated walk needs the same re-typing. Minor, but it is ten
call sites, not zero.

What held

Coverage of all 53 operations; auth byte-identical to client.go; and the
*http.Client we supply surviving into every request — that last one asserted
explicitly with a counting RoundTripper, since it is what the whole
recommendation rests on and it depends on a fallback in caller.Call that the
retry flag did not get.

Where this leaves the decision

The ~39,800 lines of generated client, vendored spec, and Python preprocessor
are still the prize, and the recommended wiring still works. But the case is
weaker than the issue body implied: the ergonomic win is smaller (the gotchas
stay), and the retry layer needs per-call suppression on every call until the
SDK is fixed.

Suggested next step is to file the WithoutRetries() bug upstream and see how
it lands before committing. If it is fixed, this becomes straightforwardly worth
doing. If not, the per-call discipline needs a lint rule or a wrapper that makes
forgetting it impossible — and that cost belongs in the decision.