@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/kotlin/PrepareAuth_kotlin.ts

@@ -112,7 +112,7 @@ private const val HEADER_AUTH = "${ktstr(spec.name)}"
 private const val OPTION_APIKEY = "apikey"
 ` + (basicBranch ? `private const val OPTION_SECRET = "secret"
 ` : '') + `private const val NOT_FOUND = "__NOTFOUND__"
-
+` + authName('HEADER_AUTH', true) + `
 fun prepareAuth(ctx: Context): Spec {
   val spec = ctx.spec
     ?: throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
@@ -126,11 +126,18 @@ fun prepareAuth(ctx: Context): Spec {
     return spec
   }
 
+  val name = prepareAuthName(options)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if (name != HEADER_AUTH) {
+    headers.remove(HEADER_AUTH)
+  }
+
   val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 ` + basicBlock(spec) + `
 ` + SKIP + `
   if (skip) {
-    headers.remove(HEADER_AUTH)
+    headers.remove(name)
   } else {
     var authPrefix = ""
     val ap = Struct.getpath(options, listOf("auth", "prefix"))
@@ -140,9 +147,9 @@ fun prepareAuth(ctx: Context): Spec {
     val apikeyVal = if (apikey is String) apikey else ""
     // Empty prefix (raw apiKey credential) must not add a leading space.
     if ("" == authPrefix) {
-      headers[HEADER_AUTH] = apikeyVal
+      headers[name] = apikeyVal
     } else {
-      headers[HEADER_AUTH] = "\$authPrefix \$apikeyVal"
+      headers[name] = "\$authPrefix \$apikeyVal"
     }
   }
 
@@ -170,7 +177,7 @@ function basicBlock(spec: AuthSpec): string {
       (secret is String && (NOT_FOUND == secret || "" == secret))
 
     if (noApikey) {
-      headers.remove(HEADER_AUTH)
+      headers.remove(name)
     } else {
       var basicPrefix = ""
       val bp = Struct.getpath(options, listOf("auth", "prefix"))
@@ -183,9 +190,9 @@ function basicBlock(spec: AuthSpec): string {
       // registration covers.
       ctx.utility!!.cleanAdd(ctx, b64)
       if ("" == basicPrefix) {
-        headers[HEADER_AUTH] = b64
+        headers[name] = b64
       } else {
-        headers[HEADER_AUTH] = "\$basicPrefix \$b64"
+        headers[name] = "\$basicPrefix \$b64"
       }
     }
 
@@ -203,7 +210,7 @@ import ${spec.kotlinpackage}.utility.struct.Struct
 private const val QUERY_AUTH = "${ktstr(spec.name)}"
 private const val OPTION_APIKEY = "apikey"
 private const val NOT_FOUND = "__NOTFOUND__"
-
+` + authName('QUERY_AUTH', false) + `
 fun prepareAuth(ctx: Context): Spec {
   val spec = ctx.spec
     ?: throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
@@ -217,18 +224,25 @@ fun prepareAuth(ctx: Context): Spec {
     return spec
   }
 
+  val name = prepareAuthName(options)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if (name != QUERY_AUTH) {
+    query.remove(QUERY_AUTH)
+  }
+
   val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
 ` + SKIP + `
   if (skip) {
-    query.remove(QUERY_AUTH)
+    query.remove(name)
   } else {
     val apikeyVal = if (apikey is String) apikey else ""
     // NO PREFIX IN A QUERY STRING. \`?${spec.name}=Bearer%20abc\` is not a
     // thing any API reads; the prefix is a header convention, so
     // options.auth.prefix is dropped here deliberately rather than silently
     // concatenated.
-    query[QUERY_AUTH] = apikeyVal
+    query[name] = apikeyVal
   }
 
   return spec
@@ -246,30 +260,21 @@ private const val COOKIE_HEADER = "cookie"
 private const val COOKIE_AUTH = "${ktstr(spec.name)}"
 private const val OPTION_APIKEY = "apikey"
 private const val NOT_FOUND = "__NOTFOUND__"
-
-// The cookie header minus our own pair, every other cookie untouched.
-private fun cookiesWithoutCred(headers: MutableMap<String, Any?>): String {
+` + authName('COOKIE_AUTH', false) + `
+// The cookie header minus the named pair, every other cookie untouched.
+private fun cookiesWithoutCred(headers: MutableMap<String, Any?>, name: String): String {
   val existing = headers[COOKIE_HEADER]
   if (existing !is String || "" == existing) {
     return ""
   }
 
-  val kept = mutableListOf<String>()
-  for (part in existing.split(";")) {
-    val piece = part.trim()
-    if ("" == piece || COOKIE_AUTH == piece || piece.startsWith("\$COOKIE_AUTH=")) {
-      continue
-    }
-    kept.add(piece)
-  }
-
-  return kept.joinToString("; ")
+  return cookieKeep(existing, listOf(name)).joinToString("; ")
 }
 
-// Set (a value) or remove (null) our pair, leaving every other cookie in
-// place.
-private fun applyCookie(headers: MutableMap<String, Any?>, value: String?) {
-  val rest = cookiesWithoutCred(headers)
+// Set (a value) or remove (null) the named pair, leaving every other cookie
+// in place.
+private fun applyCookie(headers: MutableMap<String, Any?>, name: String, value: String?) {
+  val rest = cookiesWithoutCred(headers, name)
 
   if (value == null) {
     if ("" == rest) {
@@ -280,7 +285,7 @@ private fun applyCookie(headers: MutableMap<String, Any?>, value: String?) {
     return
   }
 
-  val pair = "\$COOKIE_AUTH=\$value"
+  val pair = "\$name=\$value"
   headers[COOKIE_HEADER] = if ("" == rest) pair else "\$rest; \$pair"
 }
 
@@ -293,20 +298,27 @@ fun prepareAuth(ctx: Context): Spec {
 
   // Public APIs that need no auth omit the options.auth block entirely.
   if (options["auth"] == null) {
-    applyCookie(headers, null)
+    applyCookie(headers, COOKIE_AUTH, null)
     return spec
   }
 
+  val name = prepareAuthName(options)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if (name != COOKIE_AUTH) {
+    applyCookie(headers, COOKIE_AUTH, null)
+  }
+
   val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
 ` + SKIP + `
   if (skip) {
-    applyCookie(headers, null)
+    applyCookie(headers, name, null)
   } else {
     val apikeyVal = if (apikey is String) apikey else ""
     // NO PREFIX IN A COOKIE either - a cookie carries a bare \`name=value\`
     // pair, not a header's scheme-prefixed credential.
-    applyCookie(headers, apikeyVal)
+    applyCookie(headers, name, apikeyVal)
   }
 
   return spec
@@ -315,6 +327,19 @@ fun prepareAuth(ctx: Context): Spec {
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(declared: string, header: boolean): string {
+  return `
+// The client's auth.name option, when set, replaces the name the API declares.
+private fun prepareAuthName(options: Any?): String {
+  val name = Struct.getpath(options, listOf("auth", "name"))
+  return if (name is String && "" != name) ${header ? 'name.lowercase()' : 'name'} else ${declared}
+}
+`
+}
+
+
 // A Kotlin double-quoted string literal body. These names come from the
 // API's own securityScheme, so they are not guaranteed to be bare
 // identifiers — and `$` has to go too, because Kotlin reads it as a string

package/project/.sdk/src/cmp/kotlin/ReadmeEntity_kotlin.ts

@@ -1,18 +1,19 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { kotlinVarName } from './utility_kotlin'
+import { kotlinVarName, kotlinListMatch } from './utility_kotlin'
 
 
 // Type names come from the shared canonToType 'kotlin' column (single source of truth).
 
 function kotlinLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -29,6 +30,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(null, null)',    desc: 'List entities, optionally matching the given criteria.' },
   create: { method: 'create(data, null)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data, null)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data, null)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(match, null)', desc: 'Remove the matching entity.' },
 }
 
@@ -54,6 +56,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)
@@ -112,7 +116,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, so
       // the example always works.
@@ -134,17 +138,17 @@ val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`kotlin
-val ${eVar}List = client.${accessor}(null).list(null, null)
+val ${eVar}List = client.${accessor}(null).list(${kotlinListMatch(entity)}, null)
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear — including a
       // required id and parent keys like page_id — with a real literal.

package/project/.sdk/src/cmp/kotlin/ReadmeHowto_kotlin.ts

@@ -1,17 +1,18 @@
 
-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,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { kotlinVarName } from './utility_kotlin'
+import { kotlinVarName, kotlinString } from './utility_kotlin'
 
 
 // A type-correct Kotlin literal for a field's canonical type.
 function kotlinLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -39,23 +40,32 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'null'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `mutableMapOf<String, Any?>("${idF}" to "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 = `mutableMapOf<String, Any?>(${chosen.map((it: any) =>
+      `${kotlinString(it.name)} to ${kotlinLit(it.type)}`).join(', ')})`
+  } 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 = `mutableMapOf<String, Any?>(${chosen.map((it: any) =>
-      `"${it.name}" to ${kotlinLit(it.type)}`).join(', ')})`
+      `${kotlinString(it.name)} to ${kotlinLit(it.type)}`).join(', ')})`
   }
 
   // The op-driven test-mode line, shown only when the SDK has an entity op.
   // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
-  const testModeExample = primaryOp
-    ? `// Entity ops return the ENTITY and raises on error;
-// call data() for the record.
-val ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null)
-// ${eVar} holds the mock response record
-println(${eVar})`
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns a list of entities, one per mock record; it raises on error.
+val ${eVar}List = client.${accessor}(null).list(${testArg}, null) as List<*>
+for (${eVar}Item in ${eVar}List) {
+    println((${eVar}Item as SdkEntity).data())
+}`
+    : primaryOp
+    ? `// Entity ops return the entity; they raise on error.
+val ${eVar} = client.${accessor}(null).${primaryOp}(${testArg}, null) as SdkEntity
+// data() reads the entity's mock record
+println(${eVar}.data())`
     : `val result = client.direct(mutableMapOf<String, Any?>(
     "path" to "/api/resource",
     "method" to "GET"))

package/project/.sdk/src/cmp/kotlin/ReadmeInstall_kotlin.ts

@@ -32,9 +32,9 @@ cd kotlin && gradle build
 
   // Publish pending: not yet on Maven Central. Install from the git release
   // tag or from a local source checkout built with Gradle.
-  const { releasesUrl } = repoInfo(model)
-  Content(`This package is not yet published to Maven Central. Install it from the GitHub
-release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or
+  const { hostName, tagsUrl } = repoInfo(model)
+  Content(`This package is not yet published to Maven Central. Install it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) or
 from a source checkout — build the library with Gradle:
 
 \`\`\`bash

package/project/.sdk/src/cmp/kotlin/ReadmeIntro_kotlin.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 { kotlinVarName } from './utility_kotlin'
 
 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
@@ -36,7 +36,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/kotlin/ReadmeModel_kotlin.ts

@@ -24,13 +24,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` | `(reqmatch, ctrl) -> Any?` | Load a single entity by match criteria. Raises on error. |',
-    list: '| `list` | `(reqmatch, ctrl) -> Any?` | List entities matching the criteria (an aggregate list). Raises on error. |',
-    create: '| `create` | `(reqdata, ctrl) -> Any?` | Create a new entity. Raises on error. |',
-    update: '| `update` | `(reqdata, ctrl) -> Any?` | Update an existing entity. Raises on error. |',
-    remove: '| `remove` | `(reqmatch, ctrl) -> Any?` | Remove an entity. Raises on error. |',
+    load: '| `load` | `(reqmatch, ctrl) -> Any?` | Load a single entity by match criteria, and return it. Raises on error. |',
+    list: '| `list` | `(reqmatch, ctrl) -> Any?` | List entities matching the criteria, one per record. Raises on error. |',
+    create: '| `create` | `(reqdata, ctrl) -> Any?` | Create a new entity, and return it. Raises on error. |',
+    update: '| `update` | `(reqdata, ctrl) -> Any?` | Update an existing entity, and return it. Raises on error. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> Any?` | Change part of an existing entity, and return it. Raises on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> Any?` | Remove an entity, and return it marked as 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)
@@ -93,9 +94,10 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data() for the record) (a \`Map\` for single-entity
-ops, an aggregate \`List\` for \`list\`) as \`Any?\` and raise on error. Wrap
-calls in \`try\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`list\` a list of entities, one per
+record, as \`Any?\`; an entity is an \`SdkEntity\`, whose \`data()\` reads its
+record. They raise on error, so wrap calls in \`try\`/\`catch\` to handle
+failures.
 
 The \`direct()\` escape hatch never raises — it returns a result
 \`MutableMap<String, Any?>\` you branch on via \`result["ok"]\`:

package/project/.sdk/src/cmp/kotlin/ReadmeQuick_kotlin.ts

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { kotlinVarName, kotlinPackage } from './utility_kotlin'
+import { kotlinVarName, kotlinPackage, kotlinListMatch } from './utility_kotlin'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
@@ -36,6 +36,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // all values live in a MutableMap<String, Any?>.
   const kotlinLit = (type: any, placeholder: string = 'example'): string => {
     const k = canonScalarKey(type)
+    if ('NULL' === k) return 'null'
     if ('INTEGER' === k) return '1L'
     if ('NUMBER' === k) return '1.0'
     if ('BOOLEAN' === k) return 'true'
@@ -49,6 +50,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 
 \`\`\`kotlin
 import ${kotlinPackage(model)}.core.${SDK}
+import ${kotlinPackage(model)}.core.SdkEntity
 
 val client = ${SDK}(mutableMapOf<String, Any?>(
     "apikey" to System.getenv("${envName(model)}_APIKEY"),
@@ -62,6 +64,7 @@ val client = ${SDK}(mutableMapOf<String, Any?>(
 
 \`\`\`kotlin
 import ${kotlinPackage(model)}.core.${SDK}
+import ${kotlinPackage(model)}.core.SdkEntity
 
 val client = ${SDK}()
 \`\`\`
@@ -84,13 +87,15 @@ val client = ${SDK}()
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list(null, null)\` returns an aggregate list of records (as \`Any?\`, an
-aggregate list) and raises on error.
+\`list(null, null)\` returns a list of entities, one per record (as \`Any?\`),
+and raises on error; an entity's \`data()\` reads its record.
 
 \`\`\`kotlin
 try {
-    val ${eVar}List = client.${accessor}(null).list(null, null)
-    println(${eVar}List)
+    val ${eVar}List = client.${accessor}(null).list(${kotlinListMatch(exampleEntity)}, null) as List<*>
+    for (${eVar}Item in ${eVar}List) {
+        println((${eVar}Item as SdkEntity).data())
+    }
 }
 catch (err: RuntimeException) {
     println("list failed: " + err.message)
@@ -127,8 +132,8 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 
 \`\`\`kotlin
 try {
-    val ${neVar} = client.${neAccessor}(null).load(mutableMapOf<String, Any?>(${neMatch.join(', ')}), null)
-    println(${neVar})
+    val ${neVar} = client.${neAccessor}(null).load(mutableMapOf<String, Any?>(${neMatch.join(', ')}), null) as SdkEntity
+    println(${neVar}.data())
 }
 catch (err: RuntimeException) {
     println("load failed: " + err.message)
@@ -155,8 +160,8 @@ catch (err: RuntimeException) {
 
 \`\`\`kotlin
 try {
-    val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
-    println(${eVar})
+    val ${eVar} = client.${accessor}(null).load(${loadArg}, null) as SdkEntity
+    println(${eVar}.data())
 }
 catch (err: RuntimeException) {
     println("load failed: " + err.message)
@@ -185,7 +190,8 @@ catch (err: RuntimeException) {
       return it && it.type
     }
 
-    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
 
 \`\`\`kotlin
@@ -202,6 +208,14 @@ val created = client.${accessor}(null).create(mutableMapOf<String, Any?>(${examp
         Content(`// Update — supply the id in the match/data
 client.${accessor}(null).update(mutableMapOf<String, Any?>(${updatePairs.join(', ')}), null)
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}" to ${kotlinLit(idParamType('patch'), 'example_id')}`] : [])
+          .concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+client.${accessor}(null).patch(mutableMapOf<String, Any?>(${patchPairs.join(', ')}), null)
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/kotlin/ReadmeRef_kotlin.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -7,7 +7,7 @@ import {
   getModelPath,
 } from '@voxgig/apidef'
 
-import { kotlinVarName } from './utility_kotlin'
+import { kotlinVarName, kotlinListMatch } from './utility_kotlin'
 
 
 // Type names come from the shared canonToType 'kotlin' column (single source of truth).
@@ -15,6 +15,7 @@ import { kotlinVarName } from './utility_kotlin'
 // A type-correct Kotlin literal for a field's canonical type.
 function kotlinLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k) return '1L'
   if ('NUMBER' === k) return '1.0'
   if ('BOOLEAN' === k) return 'true'
@@ -27,28 +28,33 @@ function kotlinLit(type: any, placeholder: string = 'example'): string {
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(reqmatch, ctrl) -> Any?',
-    returns: 'the entity data',
-    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+    returns: 'the entity',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data()` reads, and raises on error.',
   },
   list: {
     sig: 'list(reqmatch, ctrl) -> Any?',
-    returns: 'an aggregate list of entities',
-    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns an aggregate list and raises on error.',
+    returns: 'a list of entities, one per record',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(null, null)` to list all records. Returns a list of entities, one per record, and raises on error.',
   },
   create: {
     sig: 'create(reqdata, ctrl) -> Any?',
-    returns: 'the created entity data',
-    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+    returns: 'the created entity',
+    desc: 'Create a new entity with the given data. Returns the created entity and raises on error.',
   },
   update: {
     sig: 'update(reqdata, ctrl) -> Any?',
-    returns: 'the updated entity data',
-    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+    returns: 'the updated entity',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and raises on error.',
+  },
+  patch: {
+    sig: 'patch(reqdata, ctrl) -> Any?',
+    returns: 'the patched entity',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity and raises on error.',
   },
   remove: {
     sig: 'remove(reqmatch, ctrl) -> Any?',
-    returns: 'the removed entity data',
-    desc: 'Remove the entity matching the given criteria. Raises on error.',
+    returns: 'the removed entity',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and raises on error.',
   },
 }
 
@@ -217,7 +223,7 @@ val ${eVar} = client.${accessor}(null)
         // 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
 
@@ -258,6 +264,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)
@@ -276,8 +286,10 @@ val result = client.${accessor}(null).${opname}(${arg}, null)
           }
           else if ('list' === opname) {
             Content(`\`\`\`kotlin
-val results = client.${accessor}(null).list(null, null)
-println(results)
+val results = client.${accessor}(null).list(${kotlinListMatch(ent)}, null) as List<*>
+for (item in results) {
+    println((item as SdkEntity).data())
+}
 \`\`\`
 
 `)
@@ -298,8 +310,8 @@ val result = client.${accessor}(null).create(mutableMapOf<String, Any?>(
 
 `)
           }
-          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))
@@ -309,12 +321,20 @@ val result = client.${accessor}(null).create(mutableMapOf<String, Any?>(
                 it.name === idF ? ent.name + '_id' : it.name)}${comma}\n`
             }).join('')
             Content(`\`\`\`kotlin
-val result = client.${accessor}(null).update(mutableMapOf<String, Any?>(
+val result = client.${accessor}(null).${opname}(mutableMapOf<String, Any?>(
 ${updateLines}), null)
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `ByteArray`, a `String` or an `InputStream`',
+              once: 'an `InputStream`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }