@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/ocaml/Entity_ocaml.ts

@@ -22,7 +22,7 @@ const Entity = cmp(function Entity(props: any) {
 
   const opnames = Object.keys(entity.op || {})
 
-  const ops = ['load', 'list', 'create', 'update', 'remove']
+  const ops = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .map((opname: string) => entityOp(opname, opnames.includes(opname), entity.name))
     .join('')
 
@@ -83,6 +83,7 @@ let rec make (client : sdk_client) (entopts_in : value) : entity_obj =
     e_list = (fun _ _ -> failwith "op not installed");
     e_create = (fun _ _ -> failwith "op not installed");
     e_update = (fun _ _ -> failwith "op not installed");
+    e_patch = (fun _ _ -> failwith "op not installed");
     e_remove = (fun _ _ -> failwith "op not installed");
     e_deleted = false;
     e_mark_deleted = (fun () -> ());
@@ -116,7 +117,11 @@ let rec make (client : sdk_client) (entopts_in : value) : entity_obj =
    * and signal (a 0-arity fn -> Bool; iteration stops when it returns true). *)
   ent.e_stream <- (fun action args callopts ->
       let callopts = match to_map callopts with Map _ as m -> m | _ -> empty_map () in
-      let ctrl = match to_map (getp callopts "ctrl") with Map _ as m -> m | _ -> empty_map () in
+      (* A copy: the caller's ctrl gains no key, and explain stays its own record. *)
+      let ctrl = empty_map () in
+      (match to_map (getp callopts "ctrl") with
+       | Map _ as given -> List.iter (fun k -> setp ctrl k (getp given k)) (keysof given)
+       | _ -> ());
       setp ctrl "stream" callopts;
       let reqmatch = match to_map args with Map _ as m -> m | _ -> empty_map () in
       let ctx = utility.u_make_context
@@ -142,7 +147,7 @@ let rec make (client : sdk_client) (entopts_in : value) : entity_obj =
             (match result.rt_stream with
              | Some fn -> fn ()
              | None -> (match result.rt_resdata with List r -> !r | v when is_nullish v -> [] | v -> [v]))
-          | None -> []) with e -> unexpected ctx e) in
+          | None -> []) with e -> ignore (unexpected ctx e); []) in
       let rec seq_of l () = match l with
         | [] -> Seq.Nil
         | x :: rest -> if aborted () then Seq.Nil else Seq.Cons (x, seq_of rest) in

package/project/.sdk/src/cmp/ocaml/Main_ocaml.ts

@@ -3,6 +3,7 @@ import {
   cmp, each,
   File, Content, Copy, Folder,
   entityClassName,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -58,7 +59,7 @@ const Main = cmp(async function Main(props: any) {
     from: 'tm/' + target.name,
     exclude: [/src\//, /\.(cmi|cmo|cmx|cma|cmxa|o|a)$/, /a\.out$/,
       /run_sdk_test$/, /run_omni_smoke$/, /run_struct_corpus$/, /run_primary_corpus$/,
-      ...containerExcludes, ...pluginExcludes(model)],
+      ...containerExcludes, ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }

package/project/.sdk/src/cmp/ocaml/Package_ocaml.ts

@@ -5,10 +5,11 @@ import {
   cmp,
   packageVersion,
   authorInfo,
+  repoInfo,
 } from '@voxgig/sdkgen'
 
 
-import { packageName } from './utility_ocaml'
+import { ocamlString, packageName } from './utility_ocaml'
 import { secretsBuild } from './Config_ocaml'
 
 
@@ -38,17 +39,18 @@ depexts: [
   const author = authorInfo(model, target.name)
 
   const pkg = packageName(model)
+  const { repoUrl, issuesUrl } = repoInfo(model)
 
   File({ name: pkg + '.opam' }, () => {
     Content(`opam-version: "2.0"
 name: "${pkg}"
 version: "${packageVersion(model, target.name)}"
 synopsis: "${model.const.Name} SDK for OCaml (generated by @voxgig/sdkgen)"
-maintainer: "${author.name}"
-authors: "${author.name}"
+maintainer: "${ocamlString(author.name)}"
+authors: "${ocamlString(author.name)}"
 license: "MIT"
-homepage: "https://voxgig.com"
-bug-reports: "https://voxgig.com"
+homepage: "${repoUrl}"
+bug-reports: "${issuesUrl}"
 # The generated SDK is dependency-free: it compiles with the stock ocamlc
 # (see the Makefile). No opam packages, no dune.
 depends: [

package/project/.sdk/src/cmp/ocaml/PrepareAuth_ocaml.ts

@@ -131,7 +131,7 @@ function renderHeader(spec: AuthSpec, head: string): string {
 let option_apikey = "apikey"
 ${spec.basic ? `let option_secret = "secret"
 ` : ''}let not_found = "__NOTFOUND__"
-
+${authName(true)}
 let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
   match ctx.c_spec with
   | None -> (None, Some (ctx_make_error ctx "auth_no_spec" "Expected context spec property to be defined."))
@@ -143,17 +143,20 @@ let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
       * needs no auth omits the block entirely. Both land here. *)
      | Noval | Null -> ignore (delprop headers (Str cred_name)); (Some spec, None)
      | _ ->
+       let name = auth_name options in
+       (* A credential left under the declared name would travel beside the renamed one. *)
+       if name <> cred_name then ignore (delprop headers (Str cred_name));
        let apikey = getprop ~alt:(Str not_found) options (Str option_apikey) in
        let is_notfound = (match apikey with Str s -> s = not_found | _ -> false) in
        let no_apikey = is_notfound || is_noval apikey || apikey = Str "" in
 ${spec.basic ? BASIC : ''}       if no_apikey then
-         ignore (delprop headers (Str cred_name))
+         ignore (delprop headers (Str name))
        else begin
          let auth_prefix = match getpath_s options "auth.prefix" with Str s -> s | _ -> "" in
          let apikey_val = match apikey with Str s -> s | _ -> "" in
          (* Empty prefix (a raw apiKey credential) must not add a leading space. *)
          let authval = if auth_prefix <> "" then auth_prefix ^ " " ^ apikey_val else apikey_val in
-         setp headers cred_name (Str authval)
+         setp headers name (Str authval)
        end;
        (Some spec, None))
 `
@@ -168,7 +171,7 @@ function renderQuery(spec: AuthSpec, head: string): string {
   return head + `
 let option_apikey = "apikey"
 let not_found = "__NOTFOUND__"
-
+${authName(false)}
 let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
   match ctx.c_spec with
   | None -> (None, Some (ctx_make_error ctx "auth_no_spec" "Expected context spec property to be defined."))
@@ -180,16 +183,19 @@ let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
       * needs no auth omits the block entirely. Both land here. *)
      | Noval | Null -> ignore (delprop query (Str cred_name)); (Some spec, None)
      | _ ->
+       let name = auth_name options in
+       (* A credential left under the declared name would travel beside the renamed one. *)
+       if name <> cred_name then ignore (delprop query (Str cred_name));
        let apikey = getprop ~alt:(Str not_found) options (Str option_apikey) in
        let is_notfound = (match apikey with Str s -> s = not_found | _ -> false) in
        if is_notfound || is_noval apikey || apikey = Str "" then
-         ignore (delprop query (Str cred_name))
+         ignore (delprop query (Str name))
        else begin
          (* NO PREFIX IN A QUERY STRING. \`?${spec.name}=Bearer%20abc\` is not a
           * thing any API reads: the prefix is a header-value convention, so
           * it is dropped here deliberately rather than concatenated. *)
          let apikey_val = match apikey with Str s -> s | _ -> "" in
-         setp query cred_name (Str apikey_val)
+         setp query name (Str apikey_val)
        end;
        (Some spec, None))
 `
@@ -201,30 +207,13 @@ function renderCookie(spec: AuthSpec, head: string): string {
 let cookie_header = "cookie"
 let option_apikey = "apikey"
 let not_found = "__NOTFOUND__"
-
-(* Strip ASCII spaces and tabs from both ends of one cookie pair. *)
-let cookie_trim (s : string) : string =
-  let n = String.length s in
-  let b = ref 0 and e = ref n in
-  while !b < !e && (s.[!b] = ' ' || s.[!b] = '\\t') do incr b done;
-  while !e > !b && (s.[!e - 1] = ' ' || s.[!e - 1] = '\\t') do decr e done;
-  String.sub s !b (!e - !b)
-
-(* True for OUR pair only: the bare name, or the name followed by '='. A
- * cookie called "${ocamlString(spec.name)}_backup" must survive. *)
-let cookie_is_cred (pair : string) : bool =
-  let n = String.length cred_name in
-  pair = cred_name
-  || (String.length pair > n && String.sub pair 0 (n + 1) = cred_name ^ "=")
-
-(* Rewrite the cookie header with our pair set (Some v) or removed (None),
- * every other cookie kept in order. *)
-let cookie_set (headers : value) (v : string option) : unit =
+${authName(false)}
+(* Rewrite the cookie header with the named pair set (Some v) or removed
+ * (None), every other cookie kept in order. *)
+let cookie_set (headers : value) (name : string) (v : string option) : unit =
   let existing = match getp headers cookie_header with Str s -> s | _ -> "" in
-  let kept =
-    List.filter (fun p -> p <> "" && not (cookie_is_cred p))
-      (List.map cookie_trim (String.split_on_char ';' existing)) in
-  let kept = match v with None -> kept | Some x -> kept @ [cred_name ^ "=" ^ x] in
+  let kept = cookie_keep existing [name] in
+  let kept = match v with None -> kept | Some x -> kept @ [name ^ "=" ^ x] in
   if [] = kept then ignore (delprop headers (Str cookie_header))
   else setp headers cookie_header (Str (String.concat "; " kept))
 
@@ -237,23 +226,39 @@ let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
     (match getp options "auth" with
      (* \`auth: null\` is the documented suppression, and a public API that
       * needs no auth omits the block entirely. Both land here. *)
-     | Noval | Null -> cookie_set headers None; (Some spec, None)
+     | Noval | Null -> cookie_set headers cred_name None; (Some spec, None)
      | _ ->
+       let name = auth_name options in
+       (* A credential left under the declared name would travel beside the renamed one. *)
+       if name <> cred_name then cookie_set headers cred_name None;
        let apikey = getprop ~alt:(Str not_found) options (Str option_apikey) in
        let is_notfound = (match apikey with Str s -> s = not_found | _ -> false) in
        if is_notfound || is_noval apikey || apikey = Str "" then
-         cookie_set headers None
+         cookie_set headers name None
        else begin
          (* NO PREFIX IN A COOKIE either - a cookie carries a bare
           * \`name=value\` pair, not a header's scheme-prefixed credential. *)
          let apikey_val = match apikey with Str s -> s | _ -> "" in
-         cookie_set headers (Some apikey_val)
+         cookie_set headers name (Some apikey_val)
        end;
        (Some spec, None))
 `
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(header: boolean): string {
+  return `
+(* The client's auth.name option, when set, replaces the name the API declares. *)
+let auth_name (options : value) : string =
+  match getpath_s options "auth.name" with
+  | Str s when s <> "" -> ${header ? 'String.lowercase_ascii s' : 's'}
+  | _ -> cred_name
+`
+}
+
+
 const BASIC = `       if (match getpath_s options "auth.basic" with Bool b -> b | _ -> false) then begin
          (* True HTTP Basic Auth joins the two credentials, base64-encoded -
           * a single token in the header (the branch below) can never
@@ -266,7 +271,7 @@ const BASIC = `       if (match getpath_s options "auth.basic" with Bool b -> b
            (match secret with Str s -> s = not_found | _ -> false)
            || is_noval secret || secret = Str "" in
          if no_apikey then
-           ignore (delprop headers (Str cred_name))
+           ignore (delprop headers (Str name))
          else begin
            let auth_prefix = match getpath_s options "auth.prefix" with Str s -> s | _ -> "" in
            let apikey_val = match apikey with Str s -> s | _ -> "" in
@@ -275,7 +280,7 @@ const BASIC = `       if (match getpath_s options "auth.basic" with Bool b -> b
            (* The joined, encoded pair is a wire form neither credential's
             * own registration covers. base64_encode is Sdk_helpers'. *)
            (cu ctx).u_clean_add ctx joined;
-           setp headers cred_name
+           setp headers name
              (Str (if auth_prefix <> "" then auth_prefix ^ " " ^ joined else joined))
          end
        end

package/project/.sdk/src/cmp/ocaml/ReadmeEntity_ocaml.ts

@@ -1,18 +1,19 @@
 
-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 { ocamlVarName } from './utility_ocaml'
+import { ocamlVarName, ocamlListMatch } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal for a field's canonical type. Strings
 // render the quoted placeholder.
 function ocamlLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Null'
   if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
   if ('BOOLEAN' === k) return '(Bool true)'
   if ('ARRAY' === k) return '(empty_list ())'
@@ -43,6 +44,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'e_list reqmatch ctrl',   desc: 'List entities, optionally matching the given criteria. Resolves to one entity per record.' },
   create: { method: 'e_create reqdata ctrl',  desc: 'Create a new entity with the given data. Resolves to the entity.' },
   update: { method: 'e_update reqdata ctrl',  desc: 'Update an existing entity. Resolves to the entity.' },
+  patch:  { method: 'e_patch reqdata ctrl',   desc: 'Change part of an existing entity. Resolves to the entity.' },
   remove: { method: 'e_remove reqmatch ctrl', desc: 'Remove the matching entity. Resolves to the entity, marked deleted.' },
 }
 
@@ -68,6 +70,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 || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
@@ -123,7 +127,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       // The id key plus every REQUIRED match key (parent path params like
       // page_id) — the same shape the runtime resolves path params from.
       const loadItems = opRequestShape(entity, 'load').items
@@ -146,19 +150,19 @@ let ${fn}_data = ${fn}.e_data_get ()
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`ocaml
 (* One ENTITY per record. *)
-let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval
+let ${fn}s = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(entity)} Noval
 let ${fn}_datas = List.map (fun e -> e.e_data_get ()) ${fn}s
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create

package/project/.sdk/src/cmp/ocaml/ReadmeHowto_ocaml.ts

@@ -6,12 +6,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlListMatch, ocamlOpField, ocamlVarName } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal for a field's canonical type.
 function ocamlLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Null'
   if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
   if ('BOOLEAN' === k) return '(Bool true)'
   if ('ARRAY' === k) return '(empty_list ())'
@@ -30,19 +31,14 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const fn = exampleEntity ? ocamlVarName(exampleEntity.name) : 'entity'
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
-  const field = primaryOp
-    ? ('load' === primaryOp ? 'e_load' :
-      'list' === primaryOp ? 'e_list' :
-        'create' === primaryOp ? 'e_create' :
-          'update' === primaryOp ? 'e_update' : 'e_remove')
-    : ''
+  const field = primaryOp ? ocamlOpField(primaryOp) : ''
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'Noval'
   if (exampleEntity && 'list' === primaryOp) {
-    testArg = '(empty_map ())'
+    testArg = ocamlListMatch(exampleEntity)
   } else if (exampleEntity && isMatchOp) {
     testArg = idF ? `(jo [("${idF}", Str "test01")])` : '(empty_map ())'
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } 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)

package/project/.sdk/src/cmp/ocaml/ReadmeInstall_ocaml.ts

@@ -25,9 +25,9 @@ cd ${target.name} && make build
   // Publish pending: not yet on the opam registry. Build from the git release
   // tag or from a local source checkout. The generated library is
   // dependency-free — a plain `make build` (stock `ocamlc`) is all it needs.
-  const { releasesUrl } = repoInfo(model)
+  const { hostName, tagsUrl } = repoInfo(model)
   Content(`This package is not yet published to the opam registry. Install it from the
-GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl}))
+${hostName} release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl}))
 or from a source checkout. The SDK is dependency-free and compiles with the
 stock \`ocamlc\` — no opam packages, no dune:
 

package/project/.sdk/src/cmp/ocaml/ReadmeIntro_ocaml.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 { ocamlVarName } from './utility_ocaml'
 
 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
@@ -38,7 +38,7 @@ with the stock \`ocamlc\`).
   // 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/ocaml/ReadmeModel_ocaml.ts

@@ -25,9 +25,10 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     list: '| `e_list` | `value -> value -> entity_obj list` | List entities matching the criteria. Resolves to one entity per record. Raises on error. |',
     create: '| `e_create` | `value -> value -> entity_obj` | Create a new entity. Resolves to the entity. Raises on error. |',
     update: '| `e_update` | `value -> value -> entity_obj` | Update an existing entity. Resolves to the entity. Raises on error. |',
+    patch: '| `e_patch` | `value -> value -> entity_obj` | Change part of an existing entity. Resolves to the entity. Raises on error. |',
     remove: '| `e_remove` | `value -> value -> entity_obj` | Remove an entity. Resolves to the entity, marked deleted. Raises on error. |',
   }
-  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)
@@ -39,6 +40,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
 \`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let client = Sdk_client.make options
 \`\`\`

package/project/.sdk/src/cmp/ocaml/ReadmeQuick_ocaml.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlVarName, ocamlListMatch } from './utility_ocaml'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -37,6 +37,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 \`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let client = ${ctor}
 \`\`\`
@@ -56,6 +57,7 @@ let client = ${ctor}
     // A type-correct OCaml `value` literal for a param.
     const ocamlLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'Null'
       if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
       if ('BOOLEAN' === k) return '(Bool true)'
       if ('ARRAY' === k) return '(empty_list ())'
@@ -71,7 +73,7 @@ record with \`e_data_get\`.
 
 \`\`\`ocaml
 (try
-   let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+   let ${fn}s = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(exampleEntity)} Noval in
    List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) ${fn}s
  with Sdk_error.E err -> Printf.eprintf "list failed: %s\\n" (Sdk_error.message err))
 \`\`\`
@@ -158,10 +160,11 @@ record.
       return it && it.type
     }
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `(getp created "${dataIdF}")`
+      ? `(getp (created.e_data_get ()) "${dataIdF}")`
       : ocamlLit(idParamType(opname), 'example_id')
 
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`ocaml
@@ -178,6 +181,13 @@ print_endline (stringify (created.e_data_get ()));
         Content(`(* Update *)
 ignore ((Sdk_client.${fn} client Noval).e_update (jo [${updatePairs.join('; ')}]) Noval);
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`("${idF}", ${idValueFor('patch')})`] : []).concat(examplePairs('patch'))
+        Content(`(* Patch — sends only the fields given *)
+ignore ((Sdk_client.${fn} client Noval).e_patch (jo [${patchPairs.join('; ')}]) Noval);
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/ocaml/ReadmeRef_ocaml.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -7,12 +7,13 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlVarName, ocamlListMatch } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal. Strings render the quoted placeholder.
 function ocamlLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Null'
   if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
   if ('BOOLEAN' === k) return '(Bool true)'
   if ('ARRAY' === k) return '(empty_list ())'
@@ -39,27 +40,32 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
   load: {
     sig: 'e_load reqmatch ctrl : entity_obj',
     returns: 'the entity',
-    desc: 'Load a single entity matching the given criteria. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
+    desc: 'Load a single entity matching the given criteria. Resolves to the entity, whose record `e_data_get` reads, and raises on error.',
   },
   list: {
     sig: 'e_list reqmatch ctrl : entity_obj list',
     returns: 'one entity per record',
-    desc: 'List entities matching the given criteria. The match is optional \u2014 pass `(empty_map ())` to list all records. Resolves to one ENTITY per record and raises on error.',
+    desc: 'List entities matching the given criteria. The match is optional \u2014 pass `(empty_map ())` to list all records. Resolves to one entity per record and raises on error.',
   },
   create: {
     sig: 'e_create reqdata ctrl : entity_obj',
     returns: 'the created entity',
-    desc: 'Create a new entity with the given data. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
+    desc: 'Create a new entity with the given data. Resolves to the created entity and raises on error.',
   },
   update: {
     sig: 'e_update reqdata ctrl : entity_obj',
     returns: 'the updated entity',
-    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the ENTITY (read the record with `e_data_get`) and raises on error.',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the updated entity and raises on error.',
+  },
+  patch: {
+    sig: 'e_patch reqdata ctrl : entity_obj',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Resolves to the patched entity and raises on error.',
   },
   remove: {
     sig: 'e_remove reqmatch ctrl : entity_obj',
     returns: 'the removed entity',
-    desc: 'Remove the entity matching the given criteria. Resolves to the ENTITY, marked deleted (`e_deleted`); it keeps the data it held. Raises on error.',
+    desc: 'Remove the entity matching the given criteria. Resolves to the entity, marked as deleted (`e_deleted`); it keeps the data it held. Raises on error.',
   },
 }
 
@@ -90,6 +96,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
     Content(`\`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let client = Sdk_client.make options
 \`\`\`
@@ -221,7 +228,7 @@ let ${fn} = Sdk_client.${fn} client Noval
         // 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']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -262,6 +269,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             const matchItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
@@ -282,7 +293,7 @@ let result_data = result.e_data_get ()
           else if ('list' === opname) {
             Content(`\`\`\`ocaml
 (* One ENTITY per record; the record is reached with e_data_get. *)
-let results = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+let results = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(ent)} Noval in
 List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) results
 \`\`\`
 
@@ -304,8 +315,8 @@ let result_data = result.e_data_get ()
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            const updateItems = 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))
@@ -313,14 +324,21 @@ let result_data = result.e_data_get ()
               `    ("${it.name}", ${ocamlLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)});\n`).join('')
             Content(`\`\`\`ocaml
-let result = (Sdk_client.${fn} client Noval).e_update (jo [
-${updateLines}    (* Fields to update *)
+let result = (Sdk_client.${fn} client Noval).e_${opname} (jo [
+${updateLines}    (* ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'} *)
 ]) Noval
 let result_data = result.e_data_get ()
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `Str` holding the bytes',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/ocaml/ReadmeTopQuick_ocaml.ts

@@ -6,13 +6,14 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { ocamlVarName } from './utility_ocaml'
+import { ocamlVarName, ocamlListMatch } from './utility_ocaml'
 
 
 // A type-correct OCaml `value` literal for a param: numeric/boolean/array/
 // object params render a typed literal; strings render the quoted placeholder.
 function ocamlLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Null'
   if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
   if ('BOOLEAN' === k) return '(Bool true)'
   if ('ARRAY' === k) return '(empty_list ())'
@@ -36,6 +37,7 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   Content(`\`\`\`ocaml
 open Voxgig_struct
 open Sdk_helpers
+open Sdk_types
 
 let () =
   let client = ${ctor} in
@@ -50,7 +52,7 @@ let () =
 
     if (opnames.includes('list')) {
       Content(`  (* List all ${fn} records (one ENTITY per record; raises on error) *)
-  let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+  let ${fn}s = (Sdk_client.${fn} client Noval).e_list ${ocamlListMatch(exampleEntity)} Noval in
   List.iter (fun e -> print_endline (stringify (e.e_data_get ()))) ${fn}s;
 `)
     }