@voxgig/sdkgen

Voxgig SDK Generator — generate idiomatic, multi-language client SDKs (plus a CLI, an MCP server, an analyst-oriented data package and a Seneca plugin) from a single API definition.

Point it at an OpenAPI spec and it produces consistent SDKs across 23 languages — TypeScript, JavaScript, Go, Python, PHP, Ruby, Lua and the rest — each with the same operation pipeline, the same feature model, generated docs, and an offline test suite.

OpenAPI spec ──▶ model ──┬─▶ 22 bundled language SDKs
                         │     ts  js  go  py  php  rb  lua  csharp  java
                         │     kotlin  scala  swift  dart  rust  c  cpp
                         │     zig  perl  clojure  elixir  ocaml  lean
                         │
                         ├─▶ more from packages
                         │     haskell (@voxgig/sdkgen-haskell)
                         │
                         └─▶ 4 consumer targets, each wrapping one of them
                               go-cli, go-mcp (go)   py-data (py)
                               seneca-provider (ts — into its own repo)

Just want to build an SDK for your API? Start with create-sdkgen — its AGENTS.md walks an agent (or you) from an OpenAPI spec to a tested SDK end-to-end. This README is about the generator itself.

How it works in one minute

• An OpenAPI definition is parsed into a structured model by @voxgig/apidef.
• The model is unified (by aontu) with language-target and feature definitions.
• A code generator (jostraca + this package) walks the model and emits SDK source for each target.

Each language target is built from two layers: templates (plain source copied with placeholder substitution — the parts that are the same for every API) and components (TypeScript that generates the API-specific parts — one class per entity, the constructor, the README, the tests).

See Architecture for the full picture.

Install

npm install @voxgig/sdkgen

This package is normally consumed through a scaffolded project (created with create-sdkgen) rather than installed directly. It provides:

• the voxgig-sdkgen CLI (target add, feature add);
• the generation engine (SdkGen.makeBuild, used by @voxgig/model);
• the component toolkit that per-language generators are written against.

Quick start

# scaffold a project from an OpenAPI spec (uses create-sdkgen)
npm create @voxgig/sdkgen@latest -- mysdk -o mysdk -d ./openapi.yaml

# add a language and generate
cd mysdk/.sdk
voxgig-sdkgen target add ts
voxgig-sdkgen feature add test
npm run build && npm run generate      # → ../ts

# build and test the generated SDK
cd ../ts && npm install && npm run build && npm test

The full walkthrough is in the Tutorial.

Documentation

Comprehensive docs live in docs/:

Tutorial	Generate your first SDK, end to end.
How-to guides	Add a target/feature, customize templates, author a language, debug, use the API.
Reference	Features · CLI · API · Model schema · Layout · Hooks.
Explanation	Architecture · Components vs templates · Operation pipeline.

Automated coding agents: start with AGENTS.md.

What a generated SDK gives you

• One entity class per API entity, with load / list / create / update / remove where supported.
• A staged operation pipeline (PrePoint → PreSpec → PreRequest → PreResponse → PreResult → PreDone) that features plug into — without forking the SDK.
• Eighteen features, in every language (see below).
• direct() / prepare() escape hatches for endpoints outside the entity model.
• Generated README.md and REFERENCE.md, and an offline test suite.

Features: the production behaviour, generated in

The parts of a client library that take the longest to get right are not the endpoint wrappers. They are retries that back off properly, a cache that does not serve a consumed response body, idempotency keys that stay stable across a retry, pagination that stops at the last page, a spend ceiling an agent cannot blow through. sdkgen ships those as features: opt-in, configurable, and implemented once per language rather than once per API.

Resilience	retry timeout ratelimit cache
Correct writes	idempotency
Large result sets	paging streaming
Observability	telemetry metrics audit debug log clienttrack
Governance	rbac proxy cost
Testing	test netsim

voxgig-sdkgen feature add retry,timeout,idempotency

const client = new MyapiSDK({
  feature: {
    retry:       { active: true, retries: 4, maxDelay: 5000 },
    timeout:     { active: true, ms: 10000 },
    idempotency: { active: true },
  },
})

Every feature is off until you switch it on, and every one of them is implemented for every bundled language target — so retry means the same thing in Go as it does in TypeScript.

→ The feature catalogue documents each one in full: options, defaults, hooks, what it records, and how they compose.

Develop this package

The npm package root is ts/. Run npm there, or use the top-level Makefile (make build, make test) which wraps it.

cd ts && npm install
cd ts && npm run build   # tsc --build src test  (→ ts/dist/, ts/dist-test/)
cd ts && npm test        # Node test runner over dist-test/**/*.test.js
cd ts && npm run test-some --pattern="<name>"   # run a subset by test name
cd ts && npm run watch   # incremental compile

ts/ is the self-contained npm package root: package.json, bin/, build/, node_modules/, and the shipped project/ scaffold live under it, alongside the tool's own TypeScript (ts/src/ source, ts/test/ tests, compiled to ts/dist/ and ts/dist-test/). The canonical model lives at top-level model/ and is mirrored into ts/model/ (npm can only ship files under the package root) — edit model/, then make sync-model. Always build before testing — tests run against ts/dist-test/. ts/dist/ is committed; ts/dist-test/ is not.

Related projects

• @voxgig/apidef — parses OpenAPI into the model.
• create-sdkgen — scaffolds new SDK projects.
• @voxgig/model — orchestrates a build (calls SdkGen.makeBuild).
• jostraca — the code-generation engine.
• aontu — data unification.

License

MIT © Richard Rodger