Your TypeScript client works, and another team needs the same calls from Go. The client carries
conventions no document records: a bearer token, an x-client header, one idempotency key per
write, retries that honor Retry-After, and ids escaped as one path segment. Translated line by
line, its retry loop keeps a plain timer, so a cancelled Go caller still waits out the backoff.
What you get
You will end up with a Go port of a TypeScript client, its tests translated first, and a script that compares both clients’ requests on the wire under a stated rule. This is for you if you own an integration in one language and need it in another.
Short answer
Give a coding agent the TypeScript client, its tests and the OpenAPI document, and have it
translate the tests to Go before the client. Name the Go idioms you expect: a context.Context on
every call, http.NewRequestWithContext, and a backoff that waits on ctx.Done(). Then run both
clients against one recording stand-in and compare their requests by method, path, body, and
the headers your conventions set.
You will need
Node 22 with TypeScript type stripping, which runs the
original .ts files as they are, and Go 1.24 or later. Verified 2026-11-22 against Node 22.23.5,
Go 1.24.7, @voxgig/sdkgen 4.44.3, OpenAPI Generator 7.27.0 and @hey-api/openapi-python
0.0.24.
The port in port/ is one specimen, written in one pass by the AI coding agent that wrote this
page. Its three inputs were original/client.ts, original/client.test.ts and api.json. It wrote
port/client_test.go first, then port/client.go, which passed those tests on its first run.
Nothing in the sample calls a model.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Agent port from source | A working client whose conventions no generator knows, with tests to translate | It ports the original’s bugs too, and an idiom you do not name can come back literal | The client is mostly glue over a generated one |
Hey API openapi-python | The target is Python and your TypeScript side already runs on Hey API | No Go generator, and release 0.0.24 wrote Python methods that take no arguments | The target is Go, or you need a working Python client |
| OpenAPI Generator go with hand glue | You want idiomatic Go with a context.Context on every call | Your conventions come back as glue you write and test, here an http.RoundTripper | The conventions are most of what the client does |
| sdkgen target add go | The TypeScript client is already sdkgen output, with retry and keys as features | Go operations take no context.Context, and a token set in headers is dropped | Callers must cancel, or the original was written by hand |
Voxgig maintains sdkgen, one of the four routes measured here, and the page recommends none of them.
The agent port keeps every convention and inherits every bug, and it is only as idiomatic as the request. OpenAPI Generator writes idiomatic Go but leaves out your conventions, so the glue is yours to write. sdkgen carries retry and idempotency as features, at the cost of Go calls you cannot cancel. Hey API generates TypeScript and Python clients but not Go.
Ask for the Go idioms by name
The original’s retry loop waits on a timer its AbortSignal can end. The port’s loop waits on the context, and
builds every request with it, so a cancel ends the backoff and the request in flight alike:
retryable := res.StatusCode == 429 || res.StatusCode == 503
if !retryable || attempt >= c.Retries {
return &APIError{Status: res.StatusCode, Body: string(data)}
}
if err := c.Sleep(ctx, RetryDelay(res.Header.Get("retry-after"), attempt, c.MaxDelay)); err != nil {
return err
}
Two conventions needed more than a translation. encodeURIComponent escapes : and @, while
Go’s url.PathEscape leaves them, so the port escapes
the segment itself.1 Go’s JSON encoder writes an int of zero like any other number, so
published is a pointer, and a book with no year sends no field.
Compare the requests on the wire
wire.mjs runs one scenario with each client against a fresh standin.mjs, a recording stand-in
held to api.json. Unknown paths get 404, other methods 405, a write must be JSON, and every Book
field is type-checked. Its one scripted fault is a 503 on the first POST.
This page did not run Prism, the mock server Stoplight publishes for OpenAPI documents. Prism’s request validation guide answers a request that breaks the document with a 422 when the operation declares no 400 or 422. Its responses come from the document’s examples and schemas, so it stores no book and scripts no 503. The stand-in checks the same parts of a request, answers with 400 instead, and keeps the state the scenario needs.
The script states its rule for the same request, and it refuses an empty original recording. Two
requests match when they share the method, the
path as sent with its escapes, the query, the body as a parsed JSON value, and the values of
authorization, x-client and content-type. An idempotency-key is compared as a pattern: none, a new
key, or the key of the request before. Every other header belongs to the HTTP library and is
ignored.
node wire.mjs
original TypeScript client: 6 requests
list: 1 book(s)
get b1: Dune
get a/b: error, HTTP 404
get isbn:9780141439518: error, HTTP 404
get ..: error, refused before sending
create: b2 Emma
Go port: 6 requests, 0 differences, 0 outcomes differ
OpenAPI Generator go: 6 requests, 7 differences, 2 outcomes differ
GET /v1/books: authorization missing, x-client missing
GET /v1/books/b1: authorization missing, x-client missing
GET /v1/books/a%2Fb: authorization missing, x-client missing
GET /v1/books/isbn%3A9780141439518: sent as /v1/books/isbn:9780141439518, authorization missing, x-client missing
GET /v1/books/..: not sent by the original
POST /v1/books: authorization missing, x-client missing, idempotency-key none
POST /v1/books: not sent
outcome: get ..: error, HTTP 404
outcome: create: error, HTTP 503
OpenAPI Generator go + glue: 6 requests, 1 difference, 0 outcomes differ
GET /v1/books/isbn%3A9780141439518: sent as /v1/books/isbn:9780141439518
sdkgen go, token in headers: 6 requests, 6 differences, 0 outcomes differ
GET /v1/books: authorization missing, content-type added
GET /v1/books/b1: authorization missing, content-type added
GET /v1/books/a%2Fb: authorization missing, content-type added
GET /v1/books/isbn%3A9780141439518: authorization missing, content-type added
POST /v1/books: authorization missing
POST /v1/books: authorization missing
sdkgen go, token as apikey: 6 requests, 4 differences, 0 outcomes differ
GET /v1/books: content-type added
GET /v1/books/b1: content-type added
GET /v1/books/a%2Fb: content-type added
GET /v1/books/isbn%3A9780141439518: content-type added
The port sends the original’s six requests under the rule and gets its six outcomes. The stock
OpenAPI Generator client sends none of the conventions, sends the .. id, and does not retry the
503. The glue in glue/glue.go closes all of that but the escaping of :, which the generated code
decides with url.PathEscape.
Keep the cancellation model in the retry loop
A literal translation turns AbortSignal into a flag and its timer into a sleep followed
by a check:
func sleep(ms int, signal *Signal) error {
time.Sleep(time.Duration(ms) * time.Millisecond)
if signal.Aborted() {
return ErrAborted
}
return nil
}
cmd/cancel cancels a list call 100 ms into a one-second Retry-After backoff in four clients, and
counts a return within 400 ms of the cancel as prompt.
go run ./cmd/cancel
Go port context.Context returned promptly: yes requests: 1 error: context canceled
literal translation Signal checked after sleep returned promptly: no requests: 1 error: aborted
OpenAPI Generator + glue context.Context returned promptly: yes requests: 1 error: context canceled
sdkgen go target no context parameter returned promptly: no requests: 3 error: other: BookshelfSDK: list: request: 503: Service Unavailable
The literal port stops only once its one-second sleep has run out. The sdkgen client has no way to receive the cancel, so it made all three attempts.
Generate the client in the target language instead
OpenAPI Generator’s go generator wrote the client in generated/oaggo, with
--package-name bookshelf. Every operation takes a context.Context and builds its request with
it, which is why the glue’s retry, a RoundTripper set as cfg.HTTPClient, can wait on
req.Context().2
Hey API’s documentation index, its llms.txt, lists TypeScript and
Python generators and no Go one. @hey-api/openapi-python 0.0.24 ran
on the same document, and its methods take no parameters and pass the path template through as it
is:
def get_book(self):
return self.client.get("/books/{bookId}")
That is release 0.0.24 of the Python generator, and it says nothing about Hey API’s TypeScript
client. Hey API’s home page labels Python soon and offers early access to
it, while the get-started page documents the package.
In an sdkgen project the route is npx voxgig-sdkgen target add go, then npm run generate,
inside .sdk. The Go SDK carries retry and idempotency as features switched on in the
constructor. Its generated REFERENCE.md describes options["headers"] as “Custom headers for all
requests.” Even so, utility/prepare_auth.go deletes an authorization header unless the options
hold an auth block and an apikey, and then writes the header from those two. The port sends
the same header through the same net/http and it arrives, so the drop is the SDK’s own. Neither
the Go README nor REFERENCE.md names apikey. @voxgig/sdkgen 4.45.0 writes the same Go files,
byte for byte.
Check it worked
node --test wire.test.mjs
1..9
# tests 9
# suites 0
# pass 9
# fail 0
# cancelled 0
# skipped 0
# todo 0
The tests record every client again and assert the differences in the wire output, run the original suite and
go test ./port, and run cmd/cancel. One test feeds the rule each kind of difference, and one
holds the stand-in to the document with a bad escape, a wrong type and a non-JSON body.
When it goes wrong
The token never arrives from the sdkgen client. A header named authorization passed in headers
is removed before the request goes out. Pass the token as apikey with an auth.prefix, and
compare the wire again.
The port passes its tests and ignores a cancel. Only a test that cancels during the backoff tells
the two loops apart, which is why the original suite has one and cmd/cancel runs the same check
on each Go client. Add one to your suite before the translation.
A path differs by one character. url.PathEscape and encodeURIComponent escape different sets,
so ids with : or @ reach the server in two spellings. The stand-in decodes both to one id, but
a server that compares raw paths, to sign a request or to cache it, sees two.
When not to do this
Do not port by hand or by agent a client that is mostly generated glue. Generate the Go client
from the document and port only the conventions, as glue/glue.go does for OpenAPI Generator.
Do not use the sdkgen Go target where callers need to cancel. Its operations take no
context.Context, so a cancel cannot reach a retry in progress. OpenAPI Generator suits that
reader better, because every call it generates takes one.
Do not take an agent port without the original suite translated first and the wire compared. One
pass produced a port with no wire differences here, which is one specimen and not a rate. Hey API suits a team that
regenerates its TypeScript side too, because @hey-api/openapi-ts puts conventions in client
interceptors.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, Go 1.24.7, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0 on OpenJDK 21, and
@hey-api/openapi-python 0.0.24 with TypeScript 5.9.3. The generators ran once, in record.sh,
and their output is committed under generated/. Prism was not run. Every output block is what the command preceding
it printed.
Footnotes
-
RFC 3986 defines a path segment as a run of
pchar, andpcharadmits the sub-delimiters,:and@without escaping. Go’surl.PathEscapeleaves:,@,$,&,+and=as they are, and escapes!,',(,),*,,and;.encodeURIComponentescapes everything outside letters, digits and-_.!~*'(), so among the sub-delimiters the two functions treat only,and;alike. ↩︎ Back to text -
The idiom is older in Go than in its standard library. The Go blog post that introduced it, dated July 29, 2014, opens with Google having developed a context package to carry request-scoped values, cancellation signals and deadlines across API boundaries. The Go 1.7 release notes then move
golang.org/x/net/contextinto the standard library ascontext. ↩︎ Back to text