@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/c/ReadmeHowto_c.ts

@@ -0,0 +1,168 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+// A type-correct C expression constructing a voxgig struct Value.
+function cLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
+  if ('BOOLEAN' === k) return 'v_bool(true)'
+  if ('ARRAY' === k) return 'v_list()'
+  if ('OBJECT' === k) return 'v_map()'
+  return 'v_str("example")'
+}
+
+
+// cmap(...) for a set of pairs, or NULL when empty.
+function cmapExpr(pairs: string[]): string {
+  return pairs.length ? `cmap(${pairs.length}, ${pairs.join(', ')})` : 'NULL'
+}
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const ident = cIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // Pick an entity with a real op (prefer a read op). primaryOp is null only
+  // when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  const evar = exampleEntity ? cVarName(exampleEntity.name) : 'entity'
+  const acc = `${ident}_${evar}`
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArg = 'NULL'
+  if (exampleEntity && isMatchOp) {
+    testArg = idF ? `cmap(1, "${idF}", v_str("test01"))` : 'NULL'
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => it.name !== idF && it.name !== 'id')
+    const required = items.filter((it: any) => !it.optional)
+    const chosen = required.length ? required : items.slice(0, 3)
+    testArg = cmapExpr(chosen.map((it: any) => `"${it.name}", ${cLit(it.type)}`))
+  }
+
+  // The op-driven test-mode line. A direct()-only SDK shows a direct() call.
+  const testModeExample = primaryOp
+    ? `// Entity ops return the bare record and set *err on failure.
+Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* ${evar}_rec = ${evar}->vt->${primaryOp}(${evar}, ${testArg}, NULL, &err);
+// ${evar}_rec contains the mock response record`
+    : `voxgig_value* result = sdk_direct(client, cmap(2,
+    "path", v_str("/api/resource"),
+    "method", v_str("GET")), &err);
+printf("%s\\n", voxgig_to_json(result));`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity operations:
+
+\`\`\`c
+PNError* err = NULL;
+voxgig_value* result = sdk_direct(client, cmap(3,
+    "path", v_str("/api/resource/{id}"),
+    "method", v_str("GET"),
+    "params", cmap(1, "id", v_str("example"))), &err);
+
+if (voxgig_as_bool(getp(result, "ok"))) {
+    printf("%lld\\n", (long long)to_int(getp(result, "status")));  // 200
+    printf("%s\\n", voxgig_to_json(getp(result, "data")));         // response body
+} else {
+    // A non-2xx response carries status + data (the error body); a
+    // transport-level failure carries err instead. Only one is present.
+    printf("%s\\n", voxgig_to_json(getp(result, "err")));
+}
+\`\`\`
+
+\`sdk_direct()\` never sets \`*err\` for a non-2xx response — it always returns
+a result map you branch on via \`getp(result, "ok")\`.
+
+### Prepare a request without sending it
+
+\`\`\`c
+PNError* err = NULL;
+voxgig_value* fetchdef = sdk_prepare(client, cmap(3,
+    "path", v_str("/api/resource/{id}"),
+    "method", v_str("DELETE"),
+    "params", cmap(1, "id", v_str("example"))), &err);
+
+printf("%s\\n", get_str(fetchdef, "url"));
+printf("%s\\n", get_str(fetchdef, "method"));
+printf("%s\\n", voxgig_to_json(getp(fetchdef, "headers")));
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`c
+${model.const.Name}SDK* client = test_sdk(NULL, NULL);
+PNError* err = NULL;
+
+${testModeExample}
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function (the same shape the test
+transport uses):
+
+\`\`\`c
+static voxgig_value* mock_fetch(void* ud, voxgig_value* args) {
+    (void)ud; (void)args;
+    return cmap(4,
+        "status", v_num(200),
+        "statusText", v_str("OK"),
+        "headers", v_map(),
+        "json", json_thunk(cmap(1, "id", v_str("mock01"))));
+}
+
+${model.const.Name}SDK* client = ${ident}_sdk_new(cmap(2,
+    "base", v_str("http://localhost:8080"),
+    "system", cmap(1, "fetch", vfn(mock_fetch, NULL))));
+\`\`\`
+
+### Point at a different server
+
+Override the base URL to reach a local or staging server:
+
+\`\`\`c
+${model.const.Name}SDK* client = ${ident}_sdk_new(cmap(1,
+    "base", v_str("http://localhost:8080")));
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd ${target.name} && make test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

package/project/.sdk/src/cmp/c/ReadmeInstall_c.ts

@@ -0,0 +1,52 @@
+
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  if (isPublished(model, target.name)) {
+    Content(`\`\`\`bash
+${installCommand(model, target.name)}
+\`\`\`
+
+Or build it from a source checkout with the bundled \`Makefile\`:
+
+\`\`\`bash
+cd ${target.name} && make
+\`\`\`
+
+`)
+    return
+  }
+
+  // Publish pending: C has no central package registry — the release IS the
+  // git tag. Build from a source checkout (the vendored voxgig struct means
+  // there are no external dependencies to fetch).
+  const { releasesUrl } = repoInfo(model)
+  Content(`C has no central package registry — a release is the git tag
+(\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})). Build from a
+source checkout with the bundled \`Makefile\`; the voxgig struct library is
+vendored under \`utility/struct\`, so there are no external dependencies to
+fetch:
+
+\`\`\`bash
+cd ${target.name} && make          # builds libsdk.a
+cd ${target.name} && make test     # builds + runs the test binaries
+\`\`\`
+
+Link your program against \`libsdk.a\` and include \`core/api.h\`:
+
+\`\`\`bash
+cc -I ${target.name}/core -I ${target.name}/utility/struct \\
+   myapp.c ${target.name}/libsdk.a -lm -o myapp
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

package/project/.sdk/src/cmp/c/ReadmeIntro_c.ts

@@ -0,0 +1,67 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client following idiomatic C conventions (explicit structs, function-pointer vtables, and a trailing \`PNError**\` out-param for errors).
+
+`)
+
+  // Emphasise the entity-oriented design: the SDK surfaces the API as
+  // capitalised, semantic Entities with a small, uniform verb set rather
+  // than raw URL paths and query strings. The example entity name is
+  // derived from the model, never hardcoded.
+  const ident = cIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {})
+    .find((e: any) => e.active !== false) as any
+  const example = exampleEntity
+    ? `for example \`${ident}_${cVarName(exampleEntity.name)}(client, NULL)\` — each`
+    : 'each'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
+
+  Content(`The SDK exposes the API as capitalised, semantic **Entities** — ${example}
+carrying a small, uniform set of operations (${opList}) instead of raw URL
+paths and query strings. You work with named resources and verbs, which
+keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}

package/project/.sdk/src/cmp/c/ReadmeModel_c.ts

@@ -0,0 +1,151 @@
+
+import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+const ReadmeModel = cmp(function ReadmeModel(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const ident = cIdent(model)
+  const Name = model.const.Name
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  // Model-driven op rows for the shared entity vtable: emit a row only for
+  // operations at least one active entity actually exposes.
+  const opUnion = new Set<string>()
+  entityList.forEach((e: any) => Object.keys(e.op || {})
+    .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
+  const opRowDefs: Record<string, string> = {
+    load: '| `load` | `(Entity*, reqmatch, ctrl, PNError**) -> voxgig_value*` | Load a single entity by match criteria. |',
+    list: '| `list` | `(Entity*, reqmatch, ctrl, PNError**) -> voxgig_value*` | List entities matching the criteria (a List). |',
+    create: '| `create` | `(Entity*, reqdata, ctrl, PNError**) -> voxgig_value*` | Create a new entity. |',
+    update: '| `update` | `(Entity*, reqdata, ctrl, PNError**) -> voxgig_value*` | Update an existing entity. |',
+    remove: '| `remove` | `(Entity*, reqmatch, ctrl, PNError**) -> voxgig_value*` | Remove an entity. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  const apikeyOptionRow = isAuthActive(model)
+    ? '| `apikey` | `string` | API key for authentication. |\n'
+    : ''
+
+  Content(`### ${Name}SDK
+
+\`\`\`c
+#include "core/api.h"
+
+${Name}SDK* client = ${ident}_sdk_new(options);
+\`\`\`
+
+Creates a new SDK client. \`options\` is a \`voxgig_value*\` map (\`NULL\` for
+none) carrying any of the following keys:
+
+| Option | Value type | Description |
+| --- | --- | --- |
+${apikeyOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
+| \`prefix\` | \`string\` | URL path prefix prepended to all requests. |
+| \`suffix\` | \`string\` | URL path suffix appended to all requests. |
+| \`feature\` | \`map\` | Feature activation flags. |
+| \`system\` | \`map\` | System overrides (e.g. a custom \`fetch\`). |
+
+### test_sdk
+
+\`\`\`c
+${Name}SDK* client = test_sdk(testopts, sdkopts);
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be
+\`NULL\`.
+
+### ${Name}SDK functions
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| \`sdk_prepare\` | \`(${Name}SDK*, fetchargs, PNError**) -> voxgig_value*\` | Build an HTTP request definition without sending. |
+| \`sdk_direct\` | \`(${Name}SDK*, fetchargs, PNError**) -> voxgig_value*\` | Build and send an HTTP request. Returns a result map (branch on \`ok\`). |
+`)
+
+  each(entityList, (ent: any) => {
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ident}_${cVarName(ent.name)}\` | \`(${Name}SDK*, entopts) -> Entity*\` | Create ${article} ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface (vtable)
+
+All entities share the same \`EntityVT\` vtable, reached via \`e->vt->...\`.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+${opRows}
+| \`data\` | \`(Entity*, args) -> voxgig_value*\` | Get entity data (pass a map to set). |
+| \`matchv\` | \`(Entity*, args) -> voxgig_value*\` | Get entity match criteria (pass a map to set). |
+| \`make\` | \`(Entity*) -> Entity*\` | Create a new instance with the same options. |
+| \`get_name\` | \`(Entity*) -> const char*\` | Return the entity name. |
+
+### Result shape
+
+Entity operations return the bare result data (a \`voxgig_value\` map for
+single-entity ops, a List for \`list\`) and set \`*err\` to a \`PNError*\` on
+failure. Always initialise \`PNError* err = NULL;\` and check it after the
+call.
+
+The \`sdk_direct()\` escape hatch never sets \`*err\` for a non-2xx response —
+it returns a result map you branch on via \`getp(result, "ok")\`:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`bool\` | \`true\` if the HTTP status is 2xx. |
+| \`status\` | \`number\` | HTTP status code. |
+| \`headers\` | \`map\` | Response headers. |
+| \`data\` | \`any\` | Parsed JSON response body. |
+
+On error, \`ok\` is \`false\` and \`err\` carries the error value.
+
+`)
+
+  // Entities summary
+  Content(`### Entities
+
+`)
+  each(entityList, (ent: any) => {
+    const fields = ent.fields || []
+    const opnames = Object.keys(ent.op || {})
+    const ops = ent.op || {}
+    const points = each(ops).map((op: any) =>
+      op.points ? each(op.points) : []
+    ).flat()
+    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+
+    Content(`#### ${ent.Name}
+
+| Field | Description |
+| --- | --- |
+`)
+    each(fields, (field: any) => {
+      Content(`| \`${field.name}\` | ${field.short || ''} |
+`)
+    })
+
+    Content(`
+Operations: ${opnames.map((n: string) => n.charAt(0).toUpperCase() + n.slice(1)).join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

package/project/.sdk/src/cmp/c/ReadmeOptions_c.ts

@@ -0,0 +1,65 @@
+
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
+
+import { cIdent } from './utility_c'
+
+
+const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const ident = cIdent(model)
+
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
+  if (0 === publishedOptions.length) {
+    return
+  }
+
+  Content(`
+
+## Options
+
+Pass an options map (a \`voxgig_value*\`) when creating a client instance:
+
+`)
+
+  Content(`\`\`\`c
+voxgig_value* opts = cmap(${publishedOptions.length},
+`)
+
+  publishedOptions.map((option: any, i: number) => {
+    const comma = i < publishedOptions.length - 1 ? ',' : ');'
+    if ('apikey' === option.name) {
+      Content(`  "${option.name}", v_str(getenv("${envName(model)}_APIKEY"))${comma}
+`)
+    }
+    else {
+      const val = option.kind === 'string' ? 'v_str("...")' : 'v_null()'
+      Content(`  "${option.name}", ${val}${comma}
+`)
+    }
+  })
+
+  Content(`${model.const.Name}SDK* client = ${ident}_sdk_new(opts);
+\`\`\`
+
+`)
+
+  Content(`| Option | Type | Description |
+| --- | --- | --- |
+`)
+
+  publishedOptions.map((option: any) => {
+    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
+`)
+  })
+
+  Content(`
+`)
+})
+
+
+export {
+  ReadmeOptions
+}