@voxgig/sdkgen 4.34.0 → 4.34.2

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

@@ -84,7 +84,8 @@ Spec* prepare_auth_util(Context* ctx, PNError** err) {
   // the base64 form of every registered value.
   const withBasic = spec.basic && 'header' === spec.where
 
-  const withStdio = 'query' !== spec.where
+  const header = 'header' === spec.where
+  const cookie = 'cookie' === spec.where
 
   const bag = bagName(spec.where)
 
@@ -96,30 +97,48 @@ Spec* prepare_auth_util(Context* ctx, PNError** err) {
 
 #include "sdk.h"
 
-${withStdio ? `#include <stdio.h>
-` : ''}#include <string.h>
+${header ? `#include <stdio.h>
+` : ''}#include <stdlib.h>
+#include <string.h>
 
 #define CRED_NAME "${cstr(credLiteral(spec.where, spec.name))}"
-${'cookie' === spec.where ? `#define COOKIE_HEADER "cookie"
+${cookie ? `#define COOKIE_HEADER "cookie"
 ` : ''}#define OPTION_APIKEY "apikey"
 ${withBasic ? `#define OPTION_SECRET "secret"
 ` : ''}#define NOT_FOUND "__NOTFOUND__"
 
-Spec* prepare_auth_util(Context* ctx, PNError** err) {
-  *err = NULL;
-  Spec* spec = ctx->spec;
-  if (!spec) {
-    *err = context_make_error(ctx, "auth_no_spec", "Expected context spec property to be defined.");
-    return NULL;
+${header ? `// The client's auth.name option, when set, replaces the name the API
+// declares. A run-time name is lower-cased into *owned, which the caller
+// frees; NULL when that copy cannot be allocated.
+static const char* auth_name(voxgig_value* options, char** owned) {
+  *owned = NULL;
+  voxgig_value* v = getpath2(options, "auth", "name");
+  const char* name = voxgig_is_string(v) ? voxgig_as_string(v) : NULL;
+  if (NULL == name || '\\0' == name[0]) return CRED_NAME;
+  size_t n = strlen(name);
+  char* lower = (char*)malloc(n + 1);
+  if (NULL == lower) return NULL;
+  // ASCII rules, as a field name is ASCII: tolower follows the C locale.
+  for (size_t i = 0; i <= n; i++) {
+    char c = name[i];
+    lower[i] = ('A' <= c && c <= 'Z') ? (char)(c - 'A' + 'a') : c;
   }
-
-  voxgig_value* ${bag} = spec->${bag};
-  voxgig_value* options = ctx->client ? sdk_options_map(ctx->client) : ctx->options;
-
-  voxgig_value* auth = getp(options, "auth");
-  if (v_is_noval(auth) || v_is_null(auth)) {
-${clear(spec.where, 4)}
-    return spec;
+  *owned = lower;
+  return lower;
+}` : `// The client's auth.name option, when set, replaces the name the API declares.
+static const char* auth_name(voxgig_value* options) {
+  voxgig_value* v = getpath2(options, "auth", "name");
+  const char* name = voxgig_is_string(v) ? voxgig_as_string(v) : NULL;
+  return (NULL == name || '\\0' == name[0]) ? CRED_NAME : name;
+}`}
+${header ? JOIN_HELPER : ''}${cookie ? COOKIE_HELPER : ''}
+// Places or clears the credential under name, the one in effect.
+static Spec* prepare_auth_as(Context* ctx, Spec* spec, voxgig_value* ${bag},
+                             voxgig_value* options,${withBasic ? ' voxgig_value* auth,' : ''} const char* name,
+                             PNError** err) {
+  // A credential left under the declared name would travel beside the renamed one.
+  if (0 != strcmp(name, CRED_NAME)) {
+${clear(spec.where, 'CRED_NAME', 4)}
   }
 
   voxgig_value* akey_key = voxgig_new_string(OPTION_APIKEY);
@@ -165,25 +184,23 @@ ${clear(spec.where, 4)}
     }
 
     if (skip) {
-${clear(spec.where, 6)}
+${clear(spec.where, 'name', 6)}
     } else {
       voxgig_value* prefix_v = getpath2(options, "auth", "prefix");
       const char* auth_prefix = voxgig_is_string(prefix_v) ? voxgig_as_string(prefix_v) : "";
-      char pair[1024];
-      snprintf(pair, sizeof(pair), "%s:%s",
-               voxgig_is_string(apikey) ? voxgig_as_string(apikey) : "",
-               !no_secret && voxgig_is_string(secret) ? voxgig_as_string(secret) : "");
+      const char* user = voxgig_is_string(apikey) ? voxgig_as_string(apikey) : "";
+      const char* pass = !no_secret && voxgig_is_string(secret) ? voxgig_as_string(secret) : "";
+      char* pair = auth_join(user, ":", pass);
+      if (NULL == pair) {
+        *err = context_make_error(ctx, "auth_alloc", "Could not allocate the credential.");
+        return NULL;
+      }
       char* b64 = clean_base64(pair);
+      free(pair);
       // The joined, encoded pair is a wire form neither credential's own
       // registration covers.
       clean_add_util(ctx, b64);
-      if (auth_prefix[0] == '\\0') {
-        setp(headers, CRED_NAME, v_str(b64));
-      } else {
-        char buf[1536];
-        snprintf(buf, sizeof(buf), "%s %s", auth_prefix, b64);
-        setp(headers, CRED_NAME, v_str(buf));
-      }
+${setHeader('b64', 6)}
     }
 
     return spec;
@@ -192,17 +209,104 @@ ${clear(spec.where, 6)}
 
   return head + basicBlock + `
   if (skip) {
-${clear(spec.where, 4)}
+${clear(spec.where, 'name', 4)}
   } else {
 ${place(spec.where)}
   }
 
   return spec;
 }
+
+Spec* prepare_auth_util(Context* ctx, PNError** err) {
+  *err = NULL;
+  Spec* spec = ctx->spec;
+  if (!spec) {
+    *err = context_make_error(ctx, "auth_no_spec", "Expected context spec property to be defined.");
+    return NULL;
+  }
+
+  voxgig_value* ${bag} = spec->${bag};
+  voxgig_value* options = ctx->client ? sdk_options_map(ctx->client) : ctx->options;
+
+  voxgig_value* auth = getp(options, "auth");
+  if (v_is_noval(auth) || v_is_null(auth)) {
+${clear(spec.where, 'CRED_NAME', 4)}
+    return spec;
+  }
+${header ? `
+  char* owned = NULL;
+  const char* name = auth_name(options, &owned);
+  if (NULL == name) {
+    *err = context_make_error(ctx, "auth_alloc", "Could not allocate the credential name.");
+    return NULL;
+  }
+
+  Spec* out = prepare_auth_as(ctx, spec, ${bag}, options,${withBasic ? ' auth,' : ''} name, err);
+  free(owned);
+  return out;` : `
+  return prepare_auth_as(ctx, spec, ${bag}, options, auth_name(options), err);`}
+}
 `
 }
 
 
+const JOIN_HELPER = `
+// a, sep and b joined, in a buffer allocated to fit; NULL when it cannot be.
+static char* auth_join(const char* a, const char* sep, const char* b) {
+  size_t n = strlen(a) + strlen(sep) + strlen(b) + 1;
+  char* out = (char*)malloc(n);
+  if (NULL != out) snprintf(out, n, "%s%s%s", a, sep, b);
+  return out;
+}
+`
+
+
+// Spliced rather than appended, in a buffer sized to fit the whole header.
+const COOKIE_HELPER = `
+static bool cred_named(const char* name, size_t nlen, void* ud) {
+  const char* cred = (const char*)ud;
+  return strlen(cred) == nlen && 0 == strncmp(cred, name, nlen);
+}
+
+// Rewrite the cookie header with the named pair removed, then set to value
+// when value is not NULL; every other cookie is kept in order. False only
+// when the new header could not be allocated.
+static bool auth_cookie_set(voxgig_value* headers, const char* name, const char* value) {
+  const char* existing = get_str(headers, COOKIE_HEADER);
+  char* kept = NULL == existing ? NULL : cookie_keep(existing, cred_named, (void*)name);
+  size_t klen = NULL == kept ? 0 : strlen(kept);
+  size_t name_len = strlen(name);
+  size_t value_len = NULL == value ? 0 : strlen(value);
+  char* out = (char*)malloc(klen + name_len + value_len + 4);
+  if (NULL == out) {
+    free(kept);
+    return false;
+  }
+  size_t used = klen;
+  if (0 != klen) memcpy(out, kept, klen);
+  free(kept);
+  if (NULL != value) {
+    if (0 != used) { out[used++] = ';'; out[used++] = ' '; }
+    memcpy(out + used, name, name_len);
+    used += name_len;
+    out[used++] = '=';
+    memcpy(out + used, value, value_len);
+    used += value_len;
+  }
+  out[used] = '\\0';
+  if (0 != used) {
+    setp(headers, COOKIE_HEADER, v_str(out));
+  } else {
+    voxgig_value* k = voxgig_new_string(COOKIE_HEADER);
+    voxgig_delprop(headers, k);
+    voxgig_release(k);
+  }
+  free(out);
+  return true;
+}
+`
+
+
 function credLiteral(where: string, name: string): string {
   return 'header' === where ? String(name).toLowerCase() : String(name)
 }
@@ -217,44 +321,58 @@ function bagName(where: string): string {
 }
 
 
-function clear(where: string, indent: number): string {
+function clear(where: string, name: string, indent: number): string {
   const pad = ' '.repeat(indent)
-  return `${pad}voxgig_value* k = voxgig_new_string(CRED_NAME);
+  if ('cookie' === where) {
+    return cookieCall(name, 'NULL', pad)
+  }
+  return `${pad}voxgig_value* k = voxgig_new_string(${name});
 ${pad}voxgig_delprop(${bagName(where)}, k);
 ${pad}voxgig_release(k);`
 }
 
 
+function cookieCall(name: string, value: string, pad: string): string {
+  return `${pad}if (!auth_cookie_set(headers, ${name}, ${value})) {
+${pad}  *err = context_make_error(ctx, "auth_alloc", "Could not allocate the cookie header.");
+${pad}  return NULL;
+${pad}}`
+}
+
+
+// A raw credential (empty prefix, e.g. an apiKey scheme) goes in as-is;
+// only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
+function setHeader(value: string, indent: number): string {
+  const pad = ' '.repeat(indent)
+  return `${pad}if (auth_prefix[0] == '\\0') {
+${pad}  setp(headers, name, v_str(${value}));
+${pad}} else {
+${pad}  char* joined = auth_join(auth_prefix, " ", ${value});
+${pad}  if (NULL == joined) {
+${pad}    *err = context_make_error(ctx, "auth_alloc", "Could not allocate the credential.");
+${pad}    return NULL;
+${pad}  }
+${pad}  setp(headers, name, v_str(joined));
+${pad}  free(joined);
+${pad}}`
+}
+
+
 function place(where: string): string {
   if ('query' === where) {
     return `    const char* apikey_val = voxgig_is_string(apikey) ? voxgig_as_string(apikey) : "";
-    setp(query, CRED_NAME, v_str(apikey_val));`
+    setp(query, name, v_str(apikey_val));`
   }
 
   if ('cookie' === where) {
     return `    const char* apikey_val = voxgig_is_string(apikey) ? voxgig_as_string(apikey) : "";
-    const char* existing = get_str(headers, COOKIE_HEADER);
-    char buf[2048];
-    if (existing && existing[0] != '\\0') {
-      snprintf(buf, sizeof(buf), "%s; %s=%s", existing, CRED_NAME, apikey_val);
-    } else {
-      snprintf(buf, sizeof(buf), "%s=%s", CRED_NAME, apikey_val);
-    }
-    setp(headers, COOKIE_HEADER, v_str(buf));`
+${cookieCall('name', 'apikey_val', '    ')}`
   }
 
   return `    voxgig_value* prefix_v = getpath2(options, "auth", "prefix");
     const char* auth_prefix = voxgig_is_string(prefix_v) ? voxgig_as_string(prefix_v) : "";
     const char* apikey_val = voxgig_is_string(apikey) ? voxgig_as_string(apikey) : "";
-    // A raw credential (empty prefix, e.g. an apiKey scheme) must go in
-    // as-is; only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
-    if (auth_prefix[0] == '\\0') {
-      setp(headers, CRED_NAME, v_str(apikey_val));
-    } else {
-      char buf[1024];
-      snprintf(buf, sizeof(buf), "%s %s", auth_prefix, apikey_val);
-      setp(headers, CRED_NAME, v_str(buf));
-    }`
+${setHeader('apikey_val', 4)}`
 }
 
 

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

@@ -1,12 +1,12 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { cIdent, cVarName } from './utility_c'
+import { cIdent, cVarName, cListMatch } from './utility_c'
 
 
 // Canonical type sentinel -> a C type name for the field/param tables. The
@@ -27,6 +27,7 @@ function cType(type: any): string {
 // A type-correct C expression constructing a voxgig struct Value.
 function cLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'v_null()'
   if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
   if ('BOOLEAN' === k) return 'v_bool(true)'
   if ('ARRAY' === k) return 'v_list()'
@@ -43,11 +44,12 @@ function cmapExpr(pairs: string[]): string {
 
 // Operation vtable descriptions (language-agnostic wording, C signatures).
 const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load:   { method: 'vt->load(e, reqmatch, ctrl, &err)',   desc: 'Load a single entity by match criteria.' },
-  list:   { method: 'vt->list(e, reqmatch, ctrl, &err)',   desc: 'List entities, optionally matching the given criteria.' },
-  create: { method: 'vt->create(e, reqdata, ctrl, &err)',  desc: 'Create a new entity with the given data.' },
-  update: { method: 'vt->update(e, reqdata, ctrl, &err)',  desc: 'Update an existing entity.' },
-  remove: { method: 'vt->remove(e, reqmatch, ctrl, &err)', desc: 'Remove the matching entity.' },
+  load:   { method: 'Entity* vt->load(e, reqmatch, ctrl, &err)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'Entity** vt->list(e, reqmatch, ctrl, &err)',  desc: 'List entities, optionally matching the given criteria: a `NULL`-terminated array, one per record.' },
+  create: { method: 'Entity* vt->create(e, reqdata, ctrl, &err)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'Entity* vt->update(e, reqdata, ctrl, &err)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'Entity* vt->patch(e, reqdata, ctrl, &err)',  desc: 'Change part of an existing entity.' },
+  remove: { method: 'Entity* vt->remove(e, reqmatch, ctrl, &err)', desc: 'Remove the matching entity, which is returned marked as deleted.' },
 }
 
 
@@ -73,6 +75,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     const evar = cVarName(entity.name)
@@ -128,7 +132,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -140,24 +144,30 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
 \`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${evar}_rec = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+Entity* loaded = ${evar}->vt->load(${evar}, ${loadArg}, NULL, &err);
+if (loaded) {
+    printf("%s\\n", voxgig_to_json(loaded->vt->data(loaded, NULL)));
+}
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`c
 Entity* ${evar} = ${acc}(client, NULL);
-voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
+Entity** ${evar}s = ${evar}->vt->list(${evar}, ${cListMatch(entity)}, NULL, &err);
+for (size_t i = 0; ${evar}s && ${evar}s[i]; i++) {
+    printf("%s\\n", voxgig_to_json(${evar}s[i]->vt->data(${evar}s[i], NULL)));
+}
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -166,10 +176,10 @@ voxgig_value* ${evar}s = ${evar}->vt->list(${evar}, NULL, NULL, &err);
 Entity* ${evar} = ${acc}(client, NULL);
 `)
       if (0 === createItems.length) {
-        Content(`voxgig_value* ${evar}_rec = ${evar}->vt->create(${evar}, NULL, NULL, &err);
+        Content(`Entity* created = ${evar}->vt->create(${evar}, NULL, NULL, &err);
 `)
       } else {
-        Content(`voxgig_value* ${evar}_rec = ${evar}->vt->create(${evar}, cmap(${createItems.length},
+        Content(`Entity* created = ${evar}->vt->create(${evar}, cmap(${createItems.length},
 `)
         createItems.map((it: any, i: number) => {
           const comma = i < createItems.length - 1 ? ',' : ')'

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,12 +7,13 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { cIdent, cVarName } from './utility_c'
+import { cIdent, cVarName, cString } from './utility_c'
 
 
 // A type-correct C expression constructing a voxgig struct Value.
 function cLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'v_null()'
   if ('INTEGER' === k || 'NUMBER' === k) return 'v_num(1)'
   if ('BOOLEAN' === k) return 'v_bool(true)'
   if ('ARRAY' === k) return 'v_list()'
@@ -43,20 +44,28 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'NULL'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `cmap(1, "${idF}", v_str("test01"))` : 'NULL'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && 'list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length) {
+    const chosen = requiredItems(exampleEntity, 'list')
+    testArg = cmapExpr(chosen.map((it: any) => `${cString(it.name)}, ${cLit(it.type)}`))
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === 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)}`))
+    testArg = cmapExpr(chosen.map((it: any) => `${cString(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.
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns one entity per mock record, and sets *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`
+Entity** ${evar}s = ${evar}->vt->list(${evar}, ${testArg}, NULL, &err);
+// ${evar}s[i]->vt->data(${evar}s[i], NULL) is a mock record`
+    : primaryOp
+    ? `// Entity ops return the entity and set *err on failure.
+Entity* ${evar} = ${acc}(client, NULL);
+Entity* result = ${evar}->vt->${primaryOp}(${evar}, ${testArg}, NULL, &err);
+// result->vt->data(result, NULL) is the mock response record`
     : `voxgig_value* result = sdk_direct(client, cmap(2,
     "path", v_str("/api/resource"),
     "method", v_str("GET")), &err);

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

@@ -24,9 +24,9 @@ cd ${target.name} && make
   // 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)
+  const { tagsUrl } = 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
+(\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})). 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:

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ 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 info = modelText(model)
   const tagline = info.tagline || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -37,7 +37,7 @@ The ${target.title} SDK for the ${model.Name} API — an entity-oriented client
   // 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 CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

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

@@ -23,13 +23,14 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   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. |',
+    load: '| `load` | `(Entity*, reqmatch, ctrl, PNError**) -> Entity*` | Load a single entity by match criteria. |',
+    list: '| `list` | `(Entity*, reqmatch, ctrl, PNError**) -> Entity**` | List entities matching the criteria: a `NULL`-terminated array, one per record. |',
+    create: '| `create` | `(Entity*, reqdata, ctrl, PNError**) -> Entity*` | Create a new entity. |',
+    update: '| `update` | `(Entity*, reqdata, ctrl, PNError**) -> Entity*` | Update an existing entity. |',
+    patch: '| `patch` | `(Entity*, reqdata, ctrl, PNError**) -> Entity*` | Change part of an existing entity. |',
+    remove: '| `remove` | `(Entity*, reqmatch, ctrl, PNError**) -> Entity*` | Remove an entity, which is returned marked as deleted. |',
   }
-  const opRows = ['load', 'list', 'create', 'update', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
   const apikeyOptionRow = isAuthActive(model)
@@ -93,10 +94,10 @@ ${opRows}
 
 ### 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.
+Entity operations return the entity, and \`list\` a \`NULL\`-terminated array
+of entities, one per record; \`vt->data\` reads an entity's record. On
+failure they return \`NULL\` and set \`*err\` to a \`PNError*\`. 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")\`: