The hard parts, generated in

The part nobody budgets for#

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 actually 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 the entire point of them and the detail most implementations 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. Eighteen features, opt-in, configured from the constructor, implemented once per language and regenerated whenever your spec changes.

What using them looks like#

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 the whole API. Every feature takes an active flag and its own options, all with defaults that are reasonable on their own.

Seven 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 → retry → ratelimit → proxy → netsim → cost → cache → HTTP

Which 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. We document the default rather than leaving you to find it in production.

One place the default is wrong, and you should override it. 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 → HTTP

Knowing what a call costs#

The newest feature, and the one that changed shape while we built it.

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 actually gives you: 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.

Be clear about what that is, though: 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 actually cannot exceed.

The detail worth knowing: 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.

The same in every language#

This is the claim worth checking before you believe any of the above.

A lot of tooling ships a rich TypeScript client and a thin wrapper everywhere else. Ours does not. 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.

We keep it that way with tests rather than intentions. Each target ships a feature test suite that runs offline, and the generator's own suite drives the real template source for every feature through a simulated pipeline. Parity is a build failure, not a promise.