Wrapping endpoints is the easy half of an SDK. It is mechanical, and a generator has always been able to do it.
The other half is what your customers file tickets about. Retries that back off properly instead of hammering a struggling server. A cache that does not hand back a response body somebody already read. Idempotency keys that stay the same across a retry, which is what they exist to do, and a detail that is easy to miss. Pagination that knows the difference between "there is a cursor" and "there is another page", so it stops instead of looping forever on the last one.
None of that is hard exactly. It is just fiddly, easy to get subtly wrong, and you get to write it again for every language you ship. Six languages means six retry policies, six chances to invert a condition, and six code reviews by people who each know one of those languages well.
So we generate it. Nineteen features, opt-in, configured from the constructor, implemented once per language and regenerated whenever your spec changes.
Add the ones you want. Each is off until you switch it on, and an unactivated feature is never constructed.
retry backs off exponentially, adds jitter, and honours a Retry-After when the server sends one. timeout puts a deadline on a request and aborts the transport. ratelimit is a token bucket that keeps you inside the quota instead of discovering it through 429s. cache serves safe reads from a bounded TTL store.
idempotency stamps a key on every mutating call, generated before the request is built so it stays the same across every retry of that call. This is the feature that stops a retried order becoming three orders. Turn it on the same day you turn on retry.
paging reads whichever convention the API picked, a Link header, X-Next-Page, a body cursor, a GraphQL Relay connection, and hands you one normalised answer. streaming iterates a list result item by item, so you are not holding the whole array in memory.
telemetry opens a span per operation and propagates W3C traceparent. metrics counts calls and latency, in total and per operation. audit writes one structured record per call: actor, entity, operation, outcome, correlation id. debug keeps a ring buffer of recent calls with secrets already redacted. clienttrack and log fill in the rest.
rbac checks the caller's permissions locally and fails fast, before the request leaves the process, so your UI never offers an action the user cannot perform. cost prices every call, attributes the spend to an operation and a caller, and can refuse a call once a budget is gone. proxy routes outbound calls through the corporate proxy, from options or the standard environment variables. secrets resolves the API credential through a provider chain rather than taking it as a literal, and exchanges a refresh token for short-lived access tokens when one expires.
test is an in-memory mock of your own API, seeded from data you supply, so the test suite needs no server. netsim injects latency, transient failures, 429s and total outages, deterministically. Together they let you prove your retry logic works without a network and without a wall clock.
Two steps, at two different times. Add the feature to your project once, then activate it per client.
# once, in your project
voxgig-sdkgen feature add retry,timeout,idempotency// wherever you construct a client
const client = new MyapiSDK({
apikey: process.env.MYAPI_APIKEY,
feature: {
retry: { active: true, retries: 4, maxDelay: 5000 },
timeout: { active: true, ms: 10000 },
idempotency: { active: true },
},
})That is all of it. Every feature takes an active flag and its own options, all with defaults that are reasonable on their own.
Eight of the features work by wrapping the transport, and each wraps whatever is already installed, so the order you list them in is the order they nest:
call → timeout → secrets → retry → ratelimit → proxy → netsim → cost → cache → HTTPWhich matters more than it looks. In that default chain one timeout deadline covers the whole retry sequence. If you want a deadline per attempt, list timeout first and it nests inside. The reference documents the default chain.
One default to override. Map order is alphabetical, so cache lands inside cost, exactly as the chain above shows. That means a response served from cache still passes through cost and gets charged for money nobody spent. Using both? List them in array form with cost first, so cache wraps it and a hit never reaches the meter:
feature: [
{ name: 'cost', active: true, unit: 0.002 }, // inner: real calls only
{ name: 'cache', active: true, ttl: 30000 },
]
// call → … → cache → cost → HTTPThe newest of the nineteen, built for metered APIs.
Metered APIs bill per call, and increasingly per token. Once an agent is driving your SDK, the question stops being "did that work" and becomes "what did that just spend, and who spent it".
cost prices each call from whichever source your API provides: a rate table you write, a cost header the server returns, a usage figure in the response body, or a flat per-call unit. It then attributes the spend two ways, to the operation and to the caller, so an invoice can be read as either.
const client = new MyapiSDK({
feature: [
{ name: 'cost', active: true,
path: 'usage.total_tokens', perUnit: 0.00001,
budget: 5.00, onBudget: 'deny' },
{ name: 'retry', active: true, retries: 3 },
],
})
await client.Completion().create({ prompt }, { actor: 'agent:planner' })
client._cost.total // { calls: 1, attempts: 1, amount: 0.0134, ... }
client._cost.actors // { 'agent:planner': { calls: 1, amount: 0.0134 } }Set a budget and, with onBudget: 'deny', the next operation is refused before an endpoint is resolved, so a runaway loop stops costing money at the point it stops being useful.
The budget is a cutoff, not a hard cap. The check asks whether you have already spent the budget, not whether this call will exceed it, because what a call costs is usually not known until after it has been made. A reported figure arrives with the response; a retried call is charged per attempt. So the last admitted call can carry you past the number: give it a budget of 2 and hand it one call that prices at 5, and you spend 5. It bounds a run, it does not guarantee a maximum. Size it a call's worth below the number you cannot exceed.
One detail to know: money is spent per HTTP attempt, but it is owed by an operation. A call that retried twice cost you three times, because your provider charged three times, and it should still show up as one call. So cost works at both seams, pricing at the transport and attributing at the end of the pipeline. That also means the order matters. Put cost inside cache, as the array above does, or a response served from cache is charged for money nobody spent.
| Feature | What it does for you |
|---|---|
retry | Retries transient failures with exponential backoff and jitter. Honours Retry-After. Does not retry a 404 or a 422, because the server understood you and said no. |
timeout | A deadline per request. Signals an AbortController, so a live fetch is cancelled rather than left running. |
ratelimit | A token bucket at a rate and burst you choose. Requests wait for a token instead of being rejected. |
cache | TTL cache for safe reads, bounded and keyed by method plus URL. Normalises one-shot response bodies, so a hit is readable more than once. |
idempotency | An Idempotency-Key on mutating calls, set once per operation and stable across retries. Never overwrites a key you supplied. |
paging | Writes page, limit or cursor on the way out. Reads Link, X-Next-Page, X-Total-Count, body cursors and GraphQL Relay pageInfo on the way back. |
streaming | An async iterator over list results. Optional chunking, and an AbortSignal to stop early. |
telemetry | A span per operation with W3C traceparent, X-Trace-Id and X-Span-Id headers. Export each finished span wherever you keep traces. |
metrics | Counts and latency: total, and broken down by entity and operation. Failed calls counted once, not twice. |
audit | One record per operation: sequence, timestamp, actor, entity, operation, outcome, status, correlation id. Push them to a SIEM as they happen. |
debug | A bounded ring buffer of recent calls: method, URL, status, duration. Authorization, cookies and API keys are masked, so a trace is safe to paste into a ticket. |
clienttrack | A stable per-client session id and a fresh id on every request, plus a descriptive User-Agent, so your server can correlate traffic. |
rbac | Required permissions per entity and operation, checked before the endpoint is even resolved. Optional default-deny. |
cost | Prices every HTTP attempt from a rate table, a response header, a body usage figure or a flat unit. Attributes the spend per operation and per caller, and enforces a budget. |
proxy | Outbound proxy routing from options or HTTPS_PROXY. Bypass list included. |
secrets | Resolves the API credential through a provider chain instead of a literal in the constructor. Optionally exchanges a refresh token for a short-lived access token, and retries the call that hit the 401. |
log | Structured logging at every pipeline stage. Verbose by design, for diagnosis. |
test | An in-memory mock of your API, seeded from your own data. Serves reads and writes, and understands your response envelopes. |
netsim | Latency, first-N failures, every-Nth failures, seeded random failures, 429s with Retry-After, and hard outages. |
Parity between targets is tested on every build.
Every feature on this page is implemented for every language target the generator supports, with the same option names, the same defaults, and the same inspectable state. Your Go customers get the same retry policy your TypeScript customers get.
Each target ships a feature test suite that runs offline, and the generator's own suite drives every feature's template source through a simulated pipeline. A target that diverges fails the build.
Resilience code that has never failed is not tested code. So two of the nineteen exist to make failure cheap to reproduce.
const client = new MyapiSDK({
feature: [
{ name: 'test', active: true, entity: seedData },
{ name: 'netsim', active: true, failTimes: 2, failStatus: 503 },
{ name: 'retry', active: true, retries: 3, minDelay: 10,
jitter: false, sleep: (ms) => sleeps.push(ms) },
],
})
await client.Product().load({ id: 'p1' })
// sleeps === [10, 20], client._retry.attempts === 2No server, no network, no wall clock, and an exact assertion on the backoff. Every feature that measures time or generates an id takes an injectable version of it for exactly this reason.
rbac is not a security boundary. It gives fast local failures, so a UI can hide actions the caller cannot perform. Your server still has to authorize.cache is a plain TTL cache. It does not read Cache-Control or revalidate with ETag.ratelimit is per client instance. Two processes get two buckets.log is a diagnosis tool, not a production logger. Use telemetry, metrics or audit in production.Every one of them, in every language target we generate. The behaviour, the option names and the inspectable state are the same across languages; only syntax and idiom differ. That is the reason to generate them rather than hand-write them: a hand-written retry policy is one more chance to get the backoff wrong in every language you ship.
No. You add the features you want, and only those get copied into your project. Each one is then off until you activate it in the constructor. A project that wants retries and nothing else carries retries and nothing else.
They compose, and the order decides what you get. Seven features work by wrapping the transport, and each wraps whatever is already installed. By default timeout ends up outside retry, so one deadline covers the whole retry sequence. Pass the features as an ordered array instead of a map and you can put timeout inside retry for a per-attempt deadline. The feature reference lists the default chain.
Yes. The test feature mocks your API in memory, netsim injects the failures on a counter, and every feature that measures time or generates an id takes an injectable clock or generator. So a test asserts on exact backoff delays rather than sleeping and hoping.
Yes. A feature is a model file plus per-language source that implements the pipeline hooks it declares, or wraps the transport. You can keep it in your own project, or publish it as an sdkgen package for other people to install. The nineteen shipped features are written against the same interface yours would use.
A feature you have not activated is not constructed, so it costs nothing. An active one costs what it does: a token bucket does arithmetic, a cache holds a bounded map, telemetry allocates a span per call. Nothing here phones home, and nothing polls.
retry to cost, all opt-inTwo minutes from a clean checkout. Add the features you want, activate the ones you need.