Your services reach a parcel carrier through a Seneca provider that someone wrote by hand two versions of the carrier’s API ago. The carrier has since added a cancel route and a quote route, which the plugin does not have. Each change to the vendor’s OpenAPI document means another afternoon of porting, and the plugin’s entities drift further from what the API offers.
What you get
You will end up with a Seneca provider plugin generated from the vendor’s document, tested against a stand-in for the vendor’s sandbox. A guard refuses the commands the API lacks. This is for you if you wrap vendor APIs as Seneca providers.
Short answer
Scaffold an sdkgen project from the vendor’s OpenAPI document with the ts target, install
@voxgig/sdkgen-infrapack, run voxgig-sdkgen package add to bring in the seneca-provider
target, and generate. The plugin exposes each entity in the model as provider/<vendor>/<entity>.
Read the model first, and refuse the Seneca commands the API has no operation for, which
seneca-entity otherwise answers from memory.
You will need
Node 22 or later, the vendor’s OpenAPI 3 document, and a Seneca service with seneca-entity
and @seneca/provider. Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, @voxgig/sdkgen-infrapack 0.0.20, and Seneca 3.38.0.
The document here, vendor.json, describes an invented carrier, parcelpoint in every generated name, with shipments,
tracking events, a cancel route, and a quote route, behind an X-Api-Key header. The
seneca-entity README covers the entity API the plugin
speaks.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| NSwag | You already generate NSwag clients for C# and want one toolchain | A hand-written plugin over its client, and the key added through your own fetch | The vendor changes its document often |
OpenAPI Generator typescript-fetch | You want its typed Api classes and wide option set | A Java runtime to generate, and the entity mapping written by hand | You would rather not run Java in the build |
openapi-typescript with openapi-fetch | You want control of each call, with paths checked by TypeScript | Every entity, command, and 404 rule written and updated by hand | The vendor’s document grows by several operations a release |
| sdkgen seneca-provider target | The vendor’s document classifies into entities, and you regenerate on each release | A second package to install, and a guard for commands the API lacks | The vendor’s operations are actions rather than resources |
Voxgig maintains sdkgen and the package that adds this target. It is the subject of this page, and the last column of its row says when to pick something else.
The trade-off is regeneration against control. The generated plugin follows the vendor’s document on every run, but its shape is whatever the model made of that document. The hand-written plugins over NSwag or openapi-fetch take 41 and 45 lines here and decide every operation themselves, so each vendor change is yours to port.
Generate the provider from the vendor’s document
seneca-provider is not bundled with sdkgen. It ships in @voxgig/sdkgen-infrapack, which
sdkgen’s out-of-tree targets page
says to add with package add. The target wraps the ts SDK, so scaffold with --target ts
first.
npx --yes @voxgig/create-sdkgen@0.31.9 parcelpoint --def vendor.json --target ts
cd parcelpoint-sdk/.sdk
npm install --save-dev @voxgig/sdkgen-infrapack@0.0.20
npx voxgig-sdkgen package add @voxgig/sdkgen-infrapack --only target:seneca-provider
npm run generate
package add reported that it added the target seneca-provider, and npm run generate wrote the plugin to
parcelpoint-sdk/seneca-provider/ beside ts/. That folder is the default while
main: kit: target: 'seneca-provider': output: path is unset. Set that key in
.sdk/model/project.aontu to generate into the provider’s own repository.
The generated package is @seneca/parcelpoint-provider, and it depends on
@voxgig-sdk/parcelpoint-sdk, the SDK from the same run. Neither is on npm, so generate.sh
builds the SDK and installs it into the provider by path. The generated package.json declares
Node 24 or later, and everything here ran on Node 22.
Read the model before you trust the plugin
Every Seneca command in the plugin comes from the entity model apidef extracted. model.cjs reads
it from the compiled SDK that the plugin calls through.
node model.cjs
quote (id field: no)
create POST /quote
no list, no load, no remove, no update
shipment (id field: yes)
create POST /shipments/{shipmentId}/cancel (action$: cancel)
create POST /shipments
list GET /shipments
load GET /shipments/{shipmentId}
no remove, no update
tracking_event (id field: yes, under shipment)
list GET /shipments/{shipmentId}/events
no create, no load, no remove, no update
Two operations did not classify as resources. POST /quote became an entity, quote, with no
id field, so pricing a parcel is a save$ on provider/parcelpoint/quote. The cancel route is a
second point of the shipment’s create, reached with an action$ directive, as the
infrapack README describes. On this document, every
operation landed on some entity, so none was left for the SDK’s direct() call.
Load the plugin and call the vendor
The plugin takes its key from the keymap of @seneca/provider and hands it to the SDK, which sends it
as X-Api-Key, as vendor.json declares. seneca.cjs sets up Seneca the way the generated
README does, except that it passes the key as a literal where the README reads
$PARCELPOINT_APIKEY through @seneca/env.
async function makeSeneca(plugin, pluginopts, key) {
const seneca = Seneca({ legacy: false })
.quiet()
.use('promisify')
.use('entity')
.use('provider', { provider: { parcelpoint: { keys: { apikey: { value: key } } } } })
.use(plugin, pluginopts)
await seneca.ready()
return seneca
}
sandbox.cjs stands in for the vendor’s sandbox on 127.0.0.1. It answers the six operations in
vendor.json and nothing else, and refuses a request without the key.
node demo.cjs
loaded parcelpoint provider 0.0.1, sdk @voxgig-sdk/parcelpoint-sdk 0.0.1
list$ -> 2 provider/parcelpoint/shipment: shp_1 in_transit, shp_2 created
load$ -> shp_1 ORD-1001 in_transit
events -> PICKED_UP, IN_TRANSIT
save$ -> shp_3 created
cancel -> shp_3 cancelled
requests the sandbox received:
GET /v2/shipments X-Api-Key ok
GET /v2/shipments/shp_1 X-Api-Key ok
GET /v2/shipments/shp_1/events X-Api-Key ok
POST /v2/shipments X-Api-Key ok
POST /v2/shipments/shp_3/cancel X-Api-Key ok
The cancel is make$({ id }).directive$({ action$: 'cancel' }).save$(). A list$ without a
shipment_id on tracking_event throws before any request, because the path needs the parent.
Write the same provider over NSwag or openapi-fetch
Neither NSwag nor openapi-fetch has a Seneca target, so both routes end in a plugin you write with
@seneca/provider’s entityBuilder. NSwag’s openapi2tsclient wrote a Client class with one
method per operation. Its constructor falls back to window when given no http object, which
throws in Node, so pass one that adds the key.
this.prepare(async function () {
const res = await this.post('sys:provider,get:keymap,provider:parcelpoint')
const key = res.keymap.apikey.value
// The client NSwag wrote for vendor.json sends no X-Api-Key, so the header goes on here.
const http = { fetch: (url, init = {}) => fetch(url, { ...init, headers: { ...init.headers, 'X-Api-Key': key } }) }
this.shared.client = new Client(options.base, http)
})
openapi-fetch takes baseUrl and headers in
createClient, and its calls name the path as the document spells it, such as
client.GET('/shipments/{shipmentId}', { params: { path: { shipmentId } } }). The types that
openapi-typescript generated check those paths in a
TypeScript build. compare.cjs makes the same calls through all three plugins.
node compare.cjs
plugin list$ load$ shp_1 load$ missing events lines you write
sdkgen seneca-provider 2 in_transit null 2 0
NSwag client, by hand 2 in_transit null 2 41
openapi-fetch, by hand 2 in_transit null 2 45
Both hand-written plugins check each id with segment.cjs. NSwag and openapi-fetch both encode
an id with encodeURIComponent, which leaves .. intact, and a test shows both requests reaching
/v2/ itself.1 The generated SDK refuses . and .. before sending.
Check it worked
node --test provider.test.cjs
1..18
# tests 18
# suites 0
# pass 18
# fail 0
# cancelled 0
# skipped 0
# todo 0
The suite loads the plugin, lists shipments through the sandbox with the key, and expects a 401 with a wrong one. It books and cancels a shipment, runs the plugin offline in the SDK’s test mode, and holds both hand-written plugins to the same calls.
When it goes wrong
A remove$ returns null, and the shipment is still there. The API has no remove, so the plugin
registers none, and seneca-entity hands the command to its default store, mem-store.2
The generated doc/reference.md says such a canon has no remove$, which is true of the plugin
but not of the Seneca instance around it. guard.cjs, loaded after the plugin, refuses every
command the model has no operation for.
node pitfall.cjs
generated provider alone
remove$('shp_2') returned null, sandbox got nothing
load$, edit, save$ returned shp_3, sandbox got POST /v2/shipments
quote list$() returned [0], sandbox got nothing
sandbox shipments with reference ORD-1001: shp_1, shp_3
with guard.cjs
remove$('shp_2') threw: provider/parcelpoint/shipment remove$: the API has no remove operation
load$, edit, save$ threw: provider/parcelpoint/shipment save$: the record has an id and the API has no update, so save$ would book another
quote list$() threw: provider/parcelpoint/quote list$: the API has no list operation
sandbox shipments with reference ORD-1001: shp_1
A loaded shipment saved again books a second one. The API has no update, so save$ always
creates, which the generated doc/reference.md states. The guard refuses a plain save$ of a
record with an id and lets an action$ through.
An entity’s canon changes after an upgrade with no change to the document. With
@voxgig/sdkgen 4.45.0 and @voxgig/apidef 8.33.1, the events entity is named event, so
provider/parcelpoint/tracking_event falls through to mem-store and lists nothing. The guard
refuses any canon of the vendor that the model does not hold, so the old name throws instead. Pin
the generator’s versions, and diff the model on every upgrade.
When not to do this
Do not generate a provider for a vendor whose API is a set of actions. The model files them under
whatever entity fits, as quote shows, and callers then save$ a price.
Do not deploy the sdkgen provider without a guard, or tests, for the commands its API lacks.
mem-store answers them, and the caller sees success.
Do not choose sdkgen to wrap a vendor that changes its document once a year. A 45-line plugin over openapi-fetch is smaller than an sdkgen project, an SDK, and a second package. Pick NSwag when your team already generates its C# clients and reviews its output. Pick OpenAPI Generator when its options cover a client feature you need and Java is already in the build.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@voxgig/apidef 8.32.4, @voxgig/sdkgen-infrapack 0.0.20, Seneca 3.38.0, seneca-entity 28.1.0,
@seneca/provider 4.0.0, NSwag 14.8.0, openapi-typescript 7.13.0, and openapi-fetch 0.17.0. Every
output block is what the command preceding it printed. generate.sh ran once, and its output is
committed under generated/, including one model step with @voxgig/sdkgen 4.45.0 and
@voxgig/apidef 8.33.1. The generated suite passed 13 of its 14 tests after the same commands. The
fourteenth, maintain, reads the plugin’s .git/config and wants a main branch in it, which a
scratch folder lacks. NSwag ran once on the ASP.NET Core 10 runtime.
OpenAPI Generator was not run; its row comes from its documentation. The vendor sandbox is a local
stand-in.
Footnotes
-
RFC 3986 puts the full stop among the unreserved characters, which need no percent-encoding, and its section 5.2.4 removes
.and..segments when a reference is resolved.encodeURIComponentfollows the first rule and the URL parser inside fetch follows the second. An id of..therefore reaches the parent path, by two rules that are each correct. ↩︎ Back to text -
The seneca-entity README says the default store,
@seneca/mem-store, is installed with the package. It also says the package is named@seneca/entityfrom 29.0.0, and npm answered 404 for that name on the day this page was verified. The generated plugin declaresseneca-entityas a peer, and npm installed 28.1.0 for it in the generated project. ↩︎ Back to text