@voxgig/sdkgen 1.3.14 → 1.3.17

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

@@ -0,0 +1,225 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const ident = cIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  // Find a nested entity if available: one with a parent chain
+  // (relations.ancestors), an active load op, and a required non-id load
+  // param to demonstrate (the parent key, e.g. page_id).
+  const nestedEntity = Object.values(entity).find((e: any) =>
+    e.active !== false &&
+    e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+    entityOps(e).includes('load') &&
+    opRequestShape(e, 'load').items.some((it: any) =>
+      !it.optional && it.name !== entityIdField(e))
+  ) as any
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `${ident}_sdk_new(cmap(1,\n    "apikey", v_str(getenv("${envName(model)}_APIKEY"))))`
+    : `${ident}_sdk_new(NULL)`
+
+  // A type-correct C expression constructing a voxgig struct Value.
+  const cLit = (type: any, placeholder: string = 'example'): 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("${placeholder}")`
+  }
+
+  // cmap(...) for a set of pairs, or NULL when empty.
+  const cmapExpr = (pairs: string[]): string =>
+    pairs.length ? `cmap(${pairs.length}, ${pairs.join(', ')})` : 'NULL'
+
+  Content(`### 1. Create a client
+
+\`\`\`c
+#include "core/api.h"
+
+${model.const.Name}SDK* client = ${ctor};
+PNError* err = NULL;
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
+    const evar = cVarName(exampleEntity.name)
+    const acc = `${ident}_${evar}`
+    const opnames = entityOps(exampleEntity)
+    // Model-driven id key: `idF` is the entity's id-like MATCH field name, or
+    // null. `dataIdF` is the id on the RETURNED record's data type.
+    const idF = entityIdField(exampleEntity)
+    const dataIdF = entityDataIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()} records
+
+\`list()\` returns a List of records and sets \`*err\` on failure — check
+\`err\` after the call.
+
+\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+if (err) {
+    fprintf(stderr, "list failed: %s\\n", err->msg);
+} else {
+    for (size_t i = 0; i < (size_t)voxgig_size(${evar}s); i++) {
+        printf("%s\\n", voxgig_to_json(voxgig_getelem(${evar}s, v_int(i), NULL)));
+    }
+}
+\`\`\`
+
+`)
+    }
+
+    if (nestedEntity) {
+      const neName = nom(nestedEntity, 'Name')
+      const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
+      const neVar = cVarName(nestedEntity.name)
+      const neAcc = `${ident}_${neVar}`
+
+      const neIdF = entityIdField(nestedEntity)
+      const neRequired = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+      const parentItem = neRequired.find((it: any) => it.name !== neIdF) as any
+      const parentParam = parentItem && parentItem.name
+      const parentName = parentParam ? parentParam.replace(/_id$/, '') : 'its parent'
+      const neMatch = cmapExpr(neRequired.map((it: any) =>
+        `"${it.name}", ${cLit(it.type,
+          it.name === neIdF ? 'example_id' : 'example_' + it.name)}`))
+
+      Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
+
+${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
+\`load()\` returns the bare record and sets \`*err\` on failure.
+
+\`\`\`c
+Entity* ${neVar} = ${neAcc}(client, NULL);
+voxgig_value* ${neVar}_rec = ${neVar}->vt->load(${neVar}, ${neMatch}, NULL, &err);
+if (err) {
+    fprintf(stderr, "load failed: %s\\n", err->msg);
+} else {
+    printf("%s\\n", voxgig_to_json(${neVar}_rec));
+}
+\`\`\`
+
+`)
+    }
+    else if (opnames.includes('load')) {
+      const loadRequired = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = cmapExpr(loadRequired.map((it: any) =>
+        `"${it.name}", ${cLit(it.type,
+          it.name === idF ? 'example_id' : 'example_' + it.name)}`))
+      const acquire = opnames.includes('list')
+        ? ''
+        : `Entity* ${evar} = ${acc}(client, NULL);\n`
+
+      Content(`### 3. Load ${article} ${eName.toLowerCase()}
+
+\`load()\` returns the bare record and sets \`*err\` on failure.
+
+\`\`\`c
+${acquire}voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+if (err) {
+    fprintf(stderr, "load failed: %s\\n", err->msg);
+} else {
+    printf("%s\\n", voxgig_to_json(${evar}_rec));
+}
+\`\`\`
+
+`)
+    }
+
+    // Model-driven example fields: derive the create/update body from the op
+    // shape so the docs reference REAL writable fields.
+    const examplePairs = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
+          ('create' === opname && !it.optional))
+      const required = items.filter((it: any) => !it.optional)
+      const optional = items.filter((it: any) => it.optional)
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : required.concat(optional).slice(0, Math.max(2, required.length))
+      return chosen.map((it: any) => `"${it.name}", ${cLit(it.type, 'example_' + it.name)}`)
+    }
+
+    const idParamType = (opname: string): any => {
+      const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
+      return it && it.type
+    }
+    // The id VALUE for an update/remove match: read it off the returned
+    // `created` record with getp when its data type carries the id AND a
+    // create ran; otherwise a type-correct literal.
+    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
+      ? `getp(created, "${dataIdF}")`
+      : cLit(idParamType(opname), 'example_id')
+
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      const acquire = (opnames.includes('list') || opnames.includes('load'))
+        ? ''
+        : `Entity* ${evar} = ${acc}(client, NULL);\n`
+      Content(`### 4. Create, update, and remove
+
+\`\`\`c
+${acquire}`)
+      if (opnames.includes('create')) {
+        Content(`// Create — returns the bare created record
+voxgig_value* created = ${evar}->vt->create(${evar}, ${cmapExpr(examplePairs('create'))}, NULL, &err);
+
+`)
+      }
+      if (opnames.includes('update')) {
+        const updatePairs = (idF ? [`"${idF}", ${idValueFor('update')}`] : []).concat(examplePairs('update'))
+        Content(`// Update
+${evar}->vt->update(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        const removePairs = opRequestShape(exampleEntity, 'remove').items
+          .filter((it: any) => !it.optional || it.name === idF)
+          .sort((a: any, b: any) =>
+            (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+          .map((it: any) => it.name === idF
+            ? `"${it.name}", ${idValueFor('remove')}`
+            : `"${it.name}", ${cLit(it.type, 'example_' + it.name)}`)
+        Content(`// Remove
+${evar}->vt->remove(${evar}, ${cmapExpr(removePairs)}, NULL, &err);
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeQuick
+}

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

@@ -0,0 +1,398 @@
+
+import { cmp, each, Content, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cIdent, cVarName } from './utility_c'
+
+
+// Canonical type sentinel -> a C type name for the field/param tables.
+function cType(type: any): string {
+  const k = canonKey(type)
+  if ('STRING' === k) return 'char*'
+  if ('INTEGER' === k) return 'int64_t'
+  if ('NUMBER' === k) return 'double'
+  if ('BOOLEAN' === k) return 'bool'
+  if ('ARRAY' === k) return 'voxgig_value* (list)'
+  if ('OBJECT' === k) return 'voxgig_value* (map)'
+  return 'voxgig_value*'
+}
+
+
+// A type-correct C expression constructing a voxgig struct Value.
+function cLit(type: any, placeholder: string = 'example'): 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("${placeholder}")`
+}
+
+
+// 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 ReadmeRef = cmp(function ReadmeRef(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const ident = cIdent(model)
+  const Name = model.const.Name
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  const publishedEntities = each(entity).filter((e: any) => e.active !== false)
+
+  const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
+    load: {
+      sig: 'vt->load(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'Load a single entity matching the given criteria. Returns the entity data and sets `*err` on failure.',
+    },
+    list: {
+      sig: 'vt->list(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'List entities matching the given criteria. The match is optional — pass `NULL` to list all records. Returns a List.',
+    },
+    create: {
+      sig: 'vt->create(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Create a new entity with the given data. Returns the created entity data and sets `*err` on failure.',
+    },
+    update: {
+      sig: 'vt->update(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err)',
+      desc: 'Update an existing entity. The data must include the entity id. Returns the updated entity data.',
+    },
+    remove: {
+      sig: 'vt->remove(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err)',
+      desc: 'Remove the entity matching the given criteria. Sets `*err` on failure.',
+    },
+  }
+
+
+  File({ name: 'REFERENCE.md' }, () => {
+
+    Content(`# ${model.Name} ${target.title} SDK Reference
+
+Complete API reference for the ${model.Name} ${target.title} SDK.
+
+
+## ${Name}SDK
+
+### Constructor
+
+`)
+
+    Content(`\`\`\`c
+#include "core/api.h"
+
+${Name}SDK* client = ${ident}_sdk_new(options);
+\`\`\`
+
+Create a new SDK client instance. \`options\` is a \`voxgig_value*\` map
+(\`NULL\` for none).
+
+**Parameters (\`options\` map keys):**
+
+| Key | Value type | Description |
+| --- | --- | --- |
+${isAuthActive(model) ? '| `apikey` | `string` | API key for authentication. |\n' : ''}| \`base\` | \`string\` | Base URL for API requests. |
+| \`prefix\` | \`string\` | URL prefix appended after base. |
+| \`suffix\` | \`string\` | URL suffix appended after path. |
+| \`headers\` | \`map\` | Custom headers for all requests. |
+| \`feature\` | \`map\` | Feature configuration. |
+| \`system\` | \`map\` | System overrides. |
+
+`)
+
+
+    Content(`
+### Test Constructor
+
+`)
+
+    Content(`#### \`${Name}SDK* test_sdk(voxgig_value* testopts, voxgig_value* sdkopts)\`
+
+Create a test client with mock features active. Both arguments may be
+\`NULL\`.
+
+\`\`\`c
+${Name}SDK* client = test_sdk(NULL, NULL);
+\`\`\`
+
+`)
+
+
+    Content(`
+### Entity Accessors
+
+`)
+
+
+    // Entity accessor functions
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`Entity* ${ident}_${cVarName(ent.name)}(${Name}SDK* client, voxgig_value* entopts)\`
+
+Create a new \`${ent.Name}\` entity instance. Pass \`NULL\` for no initial
+options.
+
+`)
+    })
+
+
+    Content(`#### \`voxgig_value* sdk_direct(${Name}SDK* client, voxgig_value* fetchargs, PNError** err)\`
+
+Make a direct HTTP request to any API endpoint. Returns a result map with
+\`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This escape
+hatch never sets \`*err\` for a non-2xx response — branch on
+\`getp(result, "ok")\`.
+
+**Parameters (\`fetchargs\` map keys):**
+
+| Key | Value type | Description |
+| --- | --- | --- |
+| \`path\` | \`string\` | URL path with optional \`{param}\` placeholders. |
+| \`method\` | \`string\` | HTTP method (default: \`"GET"\`). |
+| \`params\` | \`map\` | Path parameter values. |
+| \`query\` | \`map\` | Query string parameters. |
+| \`headers\` | \`map\` | Request headers (merged with defaults). |
+| \`body\` | \`any\` | Request body (maps are JSON-serialized). |
+
+#### \`voxgig_value* sdk_prepare(${Name}SDK* client, voxgig_value* fetchargs, PNError** err)\`
+
+Prepare a fetch definition without sending. Returns the fetchdef and sets
+\`*err\` on failure.
+
+`)
+
+
+    // Entity reference sections
+    publishedEntities.map((ent: any) => {
+      const opnames = Object.keys(ent.op || {})
+      const fields = ent.fields || []
+      const idF = entityIdField(ent)
+      const evar = cVarName(ent.name)
+      const acc = `${ident}_${evar}`
+
+      Content(`
+---
+
+## ${ent.Name}
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+\`\`\`
+
+`)
+
+
+      // Field schema
+      if (fields.length > 0) {
+        Content(`### Fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+`)
+        each(fields, (field: any) => {
+          const req = field.req ? 'Yes' : 'No'
+          const desc = field.short || ''
+          Content(`| \`${field.name}\` | \`${cType(field.type)}\` | ${req} | ${desc} |
+`)
+        })
+
+        Content(`
+`)
+
+        // Field operations breakdown
+        const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
+        if (hasFieldOps) {
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
+          Content(`### Field Usage by Operation
+
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
+`)
+          each(fields, (field: any) => {
+            const fops = field.op || {}
+            const cols = opcols.map((op: string) => {
+              const fop = fops[op]
+              if (null == fop) return '-'
+              if (fop.active === false) return '-'
+              return 'Yes'
+            })
+            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+`)
+          })
+
+          Content(`
+`)
+        }
+      }
+
+
+      // Operation details
+      if (opnames.length > 0) {
+        Content(`### Operations
+
+`)
+
+        opnames.map((opname: string) => {
+          const info = OP_SIGNATURES[opname]
+          if (!info) return
+
+          Content(`#### \`${info.sig}\`
+
+${info.desc}
+
+`)
+
+          if ('load' === opname || 'remove' === opname) {
+            const matchItems = opRequestShape(ent, opname).items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const arg = cmapExpr(matchItems.map((it: any) =>
+              `"${it.name}", ${cLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)}`))
+            Content(`\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* result = ${evar}->vt->${opname}(${evar}, ${arg}, NULL, &err);
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* results = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+for (size_t i = 0; i < (size_t)voxgig_size(results); i++) {
+    printf("%s\\n", voxgig_to_json(voxgig_getelem(results, v_int(i), NULL)));
+}
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+`)
+            if (0 === createItems.length) {
+              Content(`voxgig_value* result = ${evar}->vt->create(${evar}, NULL, NULL, &err);
+`)
+            } else {
+              Content(`voxgig_value* result = ${evar}->vt->create(${evar}, cmap(${createItems.length},
+`)
+              createItems.map((it: any, i: number) => {
+                const comma = i < createItems.length - 1 ? ',' : ')'
+                Content(`    "${it.name}", ${cLit(it.type, 'example_' + it.name)}${comma}  // ${cType(it.type)}
+`)
+              })
+              Content(`, NULL, &err);
+`)
+            }
+            Content(`\`\`\`
+
+`)
+          }
+          else if ('update' === opname) {
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updatePairs = updateItems.map((it: any) =>
+              `"${it.name}", ${cLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)}`)
+            Content(`\`\`\`c
+Entity* ${evar} = ${acc}(client, NULL);
+voxgig_value* result = ${evar}->vt->update(${evar}, ${cmapExpr(updatePairs)}, NULL, &err);
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common methods
+      Content(`### Common Methods
+
+#### \`voxgig_value* vt->data(Entity* e, voxgig_value* args)\`
+
+Get the entity data. Pass a map to set it.
+
+#### \`voxgig_value* vt->matchv(Entity* e, voxgig_value* args)\`
+
+Get the entity match criteria. Pass a map to set it.
+
+#### \`Entity* vt->make(Entity* e)\`
+
+Create a new \`${ent.Name}\` entity instance with the same options.
+
+#### \`const char* vt->get_name(Entity* e)\`
+
+Return the entity name.
+
+`)
+    })
+
+
+    // Features section
+    const activeFeatures = each(feature).filter((f: any) => f.active)
+    if (activeFeatures.length > 0) {
+      Content(`
+---
+
+## Features
+
+| Feature | Version | Description |
+| --- | --- | --- |
+`)
+
+      activeFeatures.map((f: any) => {
+        Content(`| \`${f.name}\` | ${f.version || '0.0.1'} | ${f.title || ''} |
+`)
+      })
+
+      Content(`
+
+Features are activated via the \`feature\` option:
+
+`)
+
+      Content(`\`\`\`c
+${Name}SDK* client = ${ident}_sdk_new(cmap(1,
+    "feature", cmap(${activeFeatures.length},
+`)
+      activeFeatures.map((f: any, i: number) => {
+        const comma = i < activeFeatures.length - 1 ? ',' : ')'
+        Content(`        "${f.name}", cmap(1, "active", v_bool(true))${comma}
+`)
+      })
+      Content(`));
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+export {
+  ReadmeRef
+}

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

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**C:**
+\`\`\`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);
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}