You copied a generated SDK into your monorepo and patched two files so it sends your headers. The upstream repository regenerates the SDK, and the regeneration rewrites both files. The next upgrade either drops your patches or stops on conflicts in code nobody on your team wrote.
What you get
You will end up with a vendored SDK, two local patches, and one upstream regeneration taken
through git subtree and through a patch series, with the SDK checked after each. This is for you
if you depend on a generated SDK whose maintainers owe you no fix.
Short answer
Vendor the generated SDK with git subtree add --squash, commit each local change as its own
patch, and pull a regeneration with git subtree pull --squash, or keep the patches as a series
and reapply them with git am --3way. Resolve each conflict by taking the regenerated file and
making the edit again. Where the SDK takes the change as an option, pass it instead and skip
the patch.
You will need
git with git subtree, which ships with git on Ubuntu, and Node 22 or later. The upstream is the
TypeScript SDK in voxgig-sdk/jsonplaceholder-sdk,
whose README calls it unofficial and “not affiliated with” the API it wraps. The sample’s
upstream.bundle holds its compiled files at two regenerations, so every command runs offline.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| git format-patch and git am patch series | You want the vendored tree to stay exactly upstream plus a list of named changes | Each upgrade replays every patch, and a regenerated file stops git am on it | Your patches are few and history in one place suits you |
git subtree | You want the upstream inside your repository with no extra tooling for clones | Every pull is a merge you resolve, and the --squash choice must never change | You can take the change as an option and vendor nothing |
| Kiota | You generate the client yourself and add behavior through middleware | Its client is yours to regenerate and commit, with its runtime packages to keep current | You consume someone else’s SDK as it ships |
| oapi-codegen | A Go client you generate, with headers set by a RequestEditorFn | One generated file per run, regenerated by you, and its runtime raised go.mod to Go 1.26 | The SDK comes from another team’s repository |
| SDK Catalog repo as upstream | An SDK for a public API that its provider does not publish | Regenerations land as untagged commits, and nobody upstream answers for a bug | The API’s provider publishes a supported SDK |
| wrapper around the published package | The package is published and takes your change as an option | A bug stays unfixed until upstream ships, and only Go is published here | You must change behavior that no option reaches |
Voxgig maintains the SDK Catalog and the generator behind it. It is one of six options here, not the recommendation.
A vendored copy buys offline builds and full control, and each regeneration then becomes your merge. Wrapping keeps an upgrade to a version bump, at the price of waiting on upstream for a fix. Kiota and oapi-codegen sit on the other side: a team that generates its own client never vendors it, and puts its additions in code the generator never writes.
Vendor the earlier regeneration and patch it
The catalog’s regenerations land on main without a tag. The repository’s newest TypeScript tag
predates both commits used here.
node records.mjs
the catalog repository
main: a21ce5a97d8ed4c85e02123b61a67a3a408d60a9
old: 317cc9dcf13787659643517b15d436d47cc8952e 2026-10-01 Regenerate on sdkgen 4.33.0 and apidef 8.22.1
new: a21ce5a97d8ed4c85e02123b61a67a3a408d60a9 2026-11-03 Regenerate on sdkgen 4.38.0 and apidef 8.27.0
newest ts/ tag: ts/v0.0.7 2026-08-13
commits to ts/ after that tag: 12
npm view @voxgig-sdk/jsonplaceholder-sdk: exit 1
the published Go module, wrapped
go.mod: github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261001173714-317cc9dcf137 // indirect
load post 1: title=Lamp keys=[body id title userId]
stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
go.mod: github.com/voxgig-sdk/jsonplaceholder-sdk/go v0.0.8-0.20261103055737-a21ce5a97d8e
load post 1: title=Lamp keys=[body id title userId]
stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
go1.24.7
oapi-codegen
oapi-codegen v2.8.2, 277 lines in client/posts.gen.go
go.mod: go 1.26.0
load post 1: status=200 title=Lamp
stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
Pin a commit, not a tag. The TypeScript package, @voxgig-sdk/jsonplaceholder-sdk in its
package.json, is not on npm, so a TypeScript team has no package to wrap and vendors the source.
Add the upstream with git subtree add --prefix=vendor/jsonplaceholder <upstream> regen-old --squash. Then apply the two local changes as patches. The first sets your User-Agent right
before the SDK calls fetch:
diff --git a/vendor/jsonplaceholder/dist/utility/FetcherUtility.js b/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
index 57f5771..cf14ffd 100644
--- a/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
+++ b/vendor/jsonplaceholder/dist/utility/FetcherUtility.js
@@ -14,6 +14,8 @@ async function fetcher(ctx, fullurl, fetchdef) {
' (URL was: "' + fullurl + '")');
}
const fetch = options.system.fetch;
+ // LOCAL PATCH: identify this service to the API.
+ fetchdef.headers = Object.assign({}, fetchdef.headers, { 'user-agent': 'shop-billing/1.0' });
const response = await fetch(fullurl, fetchdef);
return response;
}
The second adds an x-request-source header in PrepareHeadersUtility.js. The patches are
compiled JavaScript, because the vendored tree is what Node loads.
Pull one regeneration through each route
Pull the later regeneration both ways, resolve, and check what the vendored SDK sends.
node upgrade.mjs
git subtree, --squash on add and on pull
pull: exit 1, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js
load post 1: title=Lamp, test mode: ok
stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
git subtree, --squash on add, none on pull
pull: exit 128, fatal: refusing to merge unrelated histories
git subtree, no --squash on add, --squash on pull
pull: exit 1, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js
patch series, git am --3way on the new regeneration
git am on the old: exit 0; on the new: exit 128, conflicts in dist/utility/FetcherUtility.js, dist/utility/PrepareHeadersUtility.js; refreshed 2 patches
load post 1: title=Lamp, test mode: ok
stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
no patch, regen-old as released
load post 1: title=Lamp, test mode: ok
stand-in saw: GET /posts/1 user-agent=null x-request-source=null
no patch, regen-old, with the headers passed as an SDK option
load post 1: title=Lamp, test mode: ok
stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
no patch, regen-new as released
load post 1: title=Lamp, test mode: ok
stand-in saw: GET /posts/1 user-agent="Mozilla/5.0 (compatible; JsonplaceholderSDK/1.0)" x-request-source=null
no patch, regen-new, with the headers passed as an SDK option
load post 1: title=Lamp, test mode: ok
stand-in saw: GET /posts/1 user-agent="shop-billing/1.0" x-request-source="shop-billing"
Both routes stopped on the same two files. The regeneration rewrote the lines around each patch:
it added a guard and a default User-Agent between const fetch and the call, and cookie handling
before return out. Each conflict is resolved the same way, by taking the regenerated file and
making the edit again with patch-edits.mjs, which refuses a file that already holds the edit.
The series route then refreshes the patches with git format-patch, so the next upgrade starts
from patches written against this regeneration. Both routes end with the same tree.
The last four runs carry the finding that matters most. Upstream’s headers option sends both
headers on both regenerations with no patch at all. It does not carry every header: an
authorization header passed the same way never reached the stand-in, which the test also
asserts. Read the SDK’s options before you patch it.
Check it worked
The test rebuilds each route in a scratch repository. It asserts the conflicts, the headers the stand-in received, and the offline test mode. It also checks that the resolved tree differs from the regeneration in the two patched files only.
node --test vendor.test.mjs
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 3375.500747
The catalog’s own test suite is TypeScript and rebuilds dist/ from src/ before it runs, which
would overwrite a patch made to the compiled files. The sample therefore checks the vendored build
with its own test and the SDK’s offline test mode.
Add the same headers with oapi-codegen and Kiota
A team on oapi-codegen generates its own Go client and commits the one file it writes. The
headers go in a RequestEditorFn in the team’s code, so a regeneration rewrites the file without
touching them. record.sh ran it once against the stand-in, as the catalog record earlier shows.
func shopHeaders(_ context.Context, req *http.Request) error {
req.Header.Set("User-Agent", "shop-billing/1.0")
req.Header.Set("X-Request-Source", "shop-billing")
return nil
}
Kiota puts the same change in a middleware handler that you register when you build the HTTP client, as its middleware page shows for TypeScript, C#, and Python. That page lists a default User Agent handler that adds the Kiota HTTP library version to the header. Kiota was not run here, so this paragraph rests on that page alone.
The Go wrapper takes the same route through the catalog SDK’s own options, and its upgrade was
one go get of a pseudo-version.
// NewShopClient is the whole wrapper.
func NewShopClient(base string) *sdk.JsonplaceholderSDK {
return sdk.NewJsonplaceholderSDK(map[string]any{
"base": base,
"headers": map[string]any{
"user-agent": "shop-billing/1.0",
"x-request-source": "shop-billing",
},
})
}
When it goes wrong
git subtree pull fails with refusing to merge unrelated histories. The add used --squash
and the pull did not, so git sees two histories with no common commit. Pull with the same
--squash choice the add used, every time.1
git am --3way stops on a patch. The regeneration changed the lines around it. Take the
regenerated file with git checkout --ours, make the edit again, git add it, and run
git am --continue. In a git subtree merge, the regenerated side is --theirs.
The User-Agent changes after an upgrade without a conflict. The regeneration added a default
agent, so an SDK you never patched starts sending Mozilla/5.0 (compatible; JsonplaceholderSDK/1.0).
When not to do this
Do not vendor to change a setting the SDK already takes. The catalog SDK’s headers option did
the work of both patches on both regenerations.
Do not vendor a catalog SDK expecting upstream to fix a bug for you. The README disclaims affiliation with the API, and the repository regenerates on its own schedule. A vendored copy makes that schedule your merge queue.
Choose oapi-codegen when you can generate the Go client yourself from the provider’s document: its editors keep your headers out of the generated file. Choose Kiota for the same reason in C#, TypeScript or Python, the languages its middleware page shows, with middleware in place of editors. Wrap the published Go module when you can, since its upgrade is a version bump.
This page vendored no SDK that the API’s own provider publishes and supports, such as one its provider generates with Speakeasy or Fern, so it holds no record of that case. There, a bug report goes to the team that ships the SDK, which makes wrapping its package the first route to try.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5 and git 2.43.0, on the catalog commits 317cc9d and
a21ce5a. The Go wrapper and oapi-codegen v2.8.2 ran once, in record.sh, against a stand-in,
and their output is committed. Kiota was read from its documentation and not run.
Footnotes
-
The git-subtree documentation says
--squashmakes “a single commit that contains all the differences you want to merge”. With it, the page adds, you can “switch back and forth between different versions” rather than only move forward. It says nothing about a pull that drops the flag. In the sample, a pull without it after a squashed add stopped withrefusing to merge unrelated histories, and the reverse pairing reached the same two content conflicts as a matched pull. ↩︎ Back to text