sdkgen

Add the targets and features you want

Run from the directory holding .sdk/. Names are comma-separated, so several arrive at once. target add copies the target model, its generator components and its templates, and registers it in the index; it also pulls in the test feature, because every target's generated suite depends on it. -y plans the work and writes nothing.

voxgig-sdkgen target add ts,py,go
voxgig-sdkgen feature add retry,timeout,secrets
voxgig-sdkgen -y target add rust        # dry run: log the plan, write nothing

npm run generate                        # this is what generates; the CLI does not

A target reference can also name a package, so voxgig-sdkgen target add @voxgig/sdkgen-haskell/haskell adds a language the generator does not bundle.

Call the API as entities

from solardemo

solardemo has two entities, and Moon is nested under Planet, so a moon call carries the planet_id it is nested by. Operations resolve to entities rather than raw records; .data() gets you the record inside.

import { SolardemoSDK } from '@voxgig-sdk/solardemo'

const client = new SolardemoSDK()

// list() resolves to an array of Moon entities
const moons = await client.Moon().list({ planet_id: 'example' })

// load() returns the entity and throws on failure
const moon = await client.Moon().load({
  planet_id: 'example_planet_id',
  id: 'example_id',
})

// create() returns the created entity; the id comes off its data()
const created = await client.Moon().create({
  planet_id: 'example_planet_id',
  diameter: 1,
  id: 'example_id',
  kind: 'example_kind',
  name: 'example_name',
})

await client.Moon().remove({
  id: created.data().id!,
  planet_id: 'example_planet_id',
})

Configure a client that needs a server variable and features

from elementdemo

elementdemo's base URL is templated on an account_id, so server is required rather than optional. Features are named in the client options and are inactive until they appear there. Every option below has a default; naming one overrides only that one.

import { ElementdemoSDK } from '@voxgig-sdk/elementdemo'

const client = new ElementdemoSDK({
  apikey: process.env.ELEMENTDEMO_APIKEY,

  // Required: this API's server URL is a template over these.
  server: { account_id: '<account_id>' },

  feature: {
    // Defaults: 2 retries, 50ms to 2000ms, factor 2,
    // on 408, 425, 429, 500, 502, 503 and 504.
    retry: { active: true, retries: 3 },

    // Default 30000ms. Wraps the transport, so it wraps retry above it.
    timeout: { active: true, ms: 5000 },
  },
})

const elements = await client.Element().list()

retry and timeout both wrap the transport, so the order they are activated in decides which one sees the other's attempts.

The same SDK, in Python

from elementdemo

The model is the same, so the surface is the same; what changes is what each language calls idiomatic. Python returns records as dicts and raises on error, where TypeScript resolves entities and throws.

import os
from elementdemo_sdk import ElementdemoSDK

client = ElementdemoSDK({
    "apikey": os.environ.get("ELEMENTDEMO_APIKEY"),
    "server": {
        "account_id": "<account_id>",
    },
})

for element in client.Element().list():
    print(element)

Test with no server and no credentials

from solardemo

test swaps the transport for an in-memory mock. It starts empty, so seed it with the records the test needs, keyed by entity name and then by id. This is what makes a generated SDK's own suite runnable in CI without a sandbox account.

// Shape: { entity: { <entity-name>: { <id>: <record> } } }
const client = SolardemoSDK.test({
  entity: {
    moon: {
      test01: { id: 'test01', planet_id: 'example_planet_id', diameter: 1 },
    },
  },
})

const moon = await client.Moon().load({
  planet_id: 'example_planet_id',
  id: 'test01',
})

Pair it with netsim to make the mock fail on purpose: { netsim: { active: true, failTimes: 2, failStatus: 503 } } proves your retry policy rather than assuming it.

Write a feature the generator does not ship

from elementdemo

elementdemo carries a feature of its own, elementcard, which renders an element-shaped result as an ASCII periodic-table tile. It lives in the project's own sdkgen package under ext/, and it is declared in the model exactly the way a bundled feature is. It is shape-triggered rather than bound to an entity: any single-record result carrying number, symbol, name and mass gets a card.

main: kit: feature: elementcard: {

  name: key()
  title: "ASCII periodic-table tile for element-shaped results"
  version: '0.1.0'
  active: true
  base: '../ext/.sdk'
  package: '@voxgig-sdk/sdkgen-elementdemo-ext'
  transport: 'none'

  config: {
    # Off by default, like every optional feature.
    options: {
      active: false
      print: false
    }
  }

  hook: {
    PreResult: { active: true }
  }
}

transport: 'none' says this one does not wrap the transport, so it carries none of the ordering constraints retry and timeout do. The ext/ package supplies an implementation per language, which is why the same card renders from TypeScript, Python, Go, Java and Bash.