How-to › Run message-based services

How to generate a provider plugin from an OpenAPI document#

Add the seneca-provider target to an sdkgen project, generate a Seneca plugin from a vendor OpenAPI document, and guard the commands the API lacks.

Audience
API consumer
Level
intermediate
Topic
Wrap external APIs as providers
Languages
TypeScript
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
NSwagYou already generate NSwag clients for C# and want one toolchainA hand-written plugin over its client, and the key added through your own fetchThe vendor changes its document often
OpenAPI Generator typescript-fetchYou want its typed Api classes and wide option setA Java runtime to generate, and the entity mapping written by handYou would rather not run Java in the build
openapi-typescript with openapi-fetchYou want control of each call, with paths checked by TypeScriptEvery entity, command, and 404 rule written and updated by handThe vendor’s document grows by several operations a release
sdkgen seneca-provider targetThe vendor’s document classifies into entities, and you regenerate on each releaseA second package to install, and a guard for commands the API lacksThe 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.

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

  1. 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. encodeURIComponent follows 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

  2. The seneca-entity README says the default store, @seneca/mem-store, is installed with the package. It also says the package is named @seneca/entity from 29.0.0, and npm answered 404 for that name on the day this page was verified. The generated plugin declares seneca-entity as a peer, and npm installed 28.1.0 for it in the generated project. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.