@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/src/cmp/js/ReadmeQuick_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,12 +10,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -84,7 +78,7 @@ const client = ${ctor}
 
 \`\`\`js
 const ${eVar} = await client.${eName}().load(${matchArg('load')})
-console.log(${eVar})
+console.log(${eVar}.data())
 \`\`\`
 `)
     }
@@ -94,9 +88,9 @@ console.log(${eVar})
 ### List ${eName} Records
 
 \`\`\`js
-const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
+const ${eVar}s = await client.${eName}().list(${listMatchArg('js', exampleEntity)})
 for (const ${eVar} of ${eVar}s) {
-  console.log(${eVar})
+  console.log(${eVar}.data())
 }
 \`\`\`
 `)
@@ -110,7 +104,7 @@ for (const ${eVar} of ${eVar}s) {
 
 \`\`\`js
 const created = await client.${eName}().create({${createBody}})
-console.log(created)
+console.log(created.data())
 \`\`\`
 `)
     }
@@ -125,7 +119,7 @@ console.log(created)
 
 \`\`\`js
 const updated = await client.${eName}().update({${updateBody}})
-console.log(updated)
+console.log(updated.data())
 \`\`\`
 `)
     }
@@ -142,7 +136,7 @@ Sends only the fields given.
 
 \`\`\`js
 const patched = await client.${eName}().patch({${patchBody}})
-console.log(patched)
+console.log(patched.data())
 \`\`\`
 `)
     }

package/project/.sdk/src/cmp/js/ReadmeRef_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey , targetFeatures, opNeedsAction, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -13,34 +13,33 @@ import { exampleValue } from './utility_js'
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(match: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Load a single entity matching the given criteria.',
+    returns: 'Promise<Entity>',
+    desc: 'Load a single entity matching the given criteria. Resolves to the entity, whose record `data()` reads.',
   },
   list: {
     sig: 'list(match: object, ctrl?: object)',
-    returns: 'Promise<object[]>',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    returns: 'Promise<Entity[]>',
+    desc: 'List entities matching the given criteria. Resolves to an array of entities, one per record.',
   },
   create: {
     sig: 'create(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Create a new entity with the given data.',
+    returns: 'Promise<Entity>',
+    desc: 'Create a new entity with the given data. Resolves to the created entity.',
   },
   update: {
     sig: 'update(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    returns: 'Promise<Entity>',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the updated entity.',
   },
   patch: {
     sig: 'patch(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Change part of an existing entity: only the fields given are sent. ' +
-      'The data must include the entity `id`.',
+    returns: 'Promise<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.',
   },
   remove: {
     sig: 'remove(match: object, ctrl?: object)',
-    returns: 'Promise<void>',
-    desc: 'Remove the entity matching the given criteria.',
+    returns: 'Promise<Entity>',
+    desc: 'Remove the entity matching the given criteria. Resolves to the entity, marked as deleted.',
   },
 }
 
@@ -312,7 +311,7 @@ const result = await client.${ent.Name}().${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`ts
-const results = await client.${ent.Name}().${opname}()
+const results = await client.${ent.Name}().${opname}(${listMatchArg('js', ent)})
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/js/ReadmeTopQuick_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,12 +10,6 @@ import {
 import { exampleValue } from './utility_js'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -38,13 +32,16 @@ const client = ${ctor}
     const eVar = exampleVarName(eName.toLowerCase(), 'js')
     const opnames = entityOps(exampleEntity)
 
+    let hasCall = false
+
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns an array)
-const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
+      Content(`// List all ${eName.toLowerCase()}s (an array of entities, one per record)
+const ${eVar}s = await client.${eName}().list(${listMatchArg('js', exampleEntity)})
 for (const ${eVar} of ${eVar}s) {
-  console.log(${eVar})
+  console.log(${eVar}.data())
 }
 `)
+      hasCall = true
     }
 
     // Find a nested entity for a more interesting example: one with a parent
@@ -81,7 +78,15 @@ for (const ${eVar} of ${eVar}s) {
 const ${neVar} = await client.${neName}().load({
 ${neMatchLines.join('\n')}
 })
-console.log(${neVar})
+console.log(${neVar}.data())
+`)
+      hasCall = true
+    }
+
+    if (!hasCall && opnames.includes('load')) {
+      Content(`// Load a specific ${eName.toLowerCase()} (returns the entity)
+const ${eVar} = await client.${eName}().load()
+console.log(${eVar}.data())
 `)
     }
   }

package/project/.sdk/src/cmp/js/ReadmeTopTest_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey, requiredItems } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -30,11 +30,12 @@ const client = ${model.const.Name}SDK.test()
     const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
     const idF = entityIdField(exampleEntity)
     let arg = ''
-    if ('load' === primaryOp || 'remove' === primaryOp) {
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    if (isMatchOp || 'list' === primaryOp) {
       // Every REQUIRED match key (id first, then parent path params like
       // page_id) — the same shape the runtime resolves path params from.
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : requiredItems(exampleEntity, 'list'))
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       arg = 0 < items.length
@@ -50,10 +51,13 @@ const client = ${model.const.Name}SDK.test()
       arg = `{ ${chosen.map((it: any) =>
         `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
     }
+    const one = exampleVarName(eName.toLowerCase(), 'js')
     Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
-// ${eVar} is ${'list' === primaryOp ? 'an array of entities' : 'the entity'}, populated with mock data
-// — call ${eVar}${'list' === primaryOp ? '[0]' : ''}.data() for the record itself
-console.log(${eVar})
+${'list' === primaryOp
+    ? `// ${eVar} is an array of ${eName} entities, one per mock record
+console.log(${eVar}.map((${one}) => ${one}.data()))`
+    : `// ${eVar} is the ${eName} entity; .data() reads its mock record
+console.log(${eVar}.data())`}
 `)
   }
 

package/project/.sdk/src/cmp/js/fragment/EntityCreateOp.fragment.js

@@ -7,7 +7,7 @@ class EntityOperation {
   /**
    * @param {EntityNameCreateData} [reqdata]
    * @param {Object} [ctrl]
-   * @returns {Promise<EntityName>}
+   * @returns {Promise<EntyClass>}
    */
   async create(reqdata, ctrl) {
 

package/project/.sdk/src/cmp/js/fragment/EntityListOp.fragment.js

@@ -7,7 +7,7 @@ class EntityOperation {
   /**
    * @param {EntityNameListMatch} [reqmatch]
    * @param {Object} [ctrl]
-   * @returns {Promise<EntityName[]>}
+   * @returns {Promise<EntyClass[]>}
    */
   async list(reqmatch, ctrl) {
 

package/project/.sdk/src/cmp/js/fragment/EntityLoadOp.fragment.js

@@ -7,7 +7,7 @@ class EntityOperation {
   /**
    * @param {EntityNameLoadMatch} [reqmatch]
    * @param {Object} [ctrl]
-   * @returns {Promise<EntityName>}
+   * @returns {Promise<EntyClass>}
    */
   async load(reqmatch, ctrl) {
 

package/project/.sdk/src/cmp/js/fragment/EntityPatchOp.fragment.js

@@ -7,7 +7,7 @@ class EntityOperation {
   /**
    * @param {EntityNameUpdateData} [reqdata]
    * @param {Object} [ctrl]
-   * @returns {Promise<EntityName>}
+   * @returns {Promise<EntyClass>}
    */
   async patch(reqdata, ctrl) {
 

package/project/.sdk/src/cmp/js/fragment/EntityRemoveOp.fragment.js

@@ -7,7 +7,7 @@ class EntityOperation {
   /**
    * @param {EntityNameRemoveMatch} [reqmatch]
    * @param {Object} [ctrl]
-   * @returns {Promise<EntityName>}
+   * @returns {Promise<EntyClass>}
    */
   async remove(reqmatch, ctrl) {
 

package/project/.sdk/src/cmp/js/fragment/EntityUpdateOp.fragment.js

@@ -7,7 +7,7 @@ class EntityOperation {
   /**
    * @param {EntityNameUpdateData} [reqdata]
    * @param {Object} [ctrl]
-   * @returns {Promise<EntityName>}
+   * @returns {Promise<EntyClass>}
    */
   async update(reqdata, ctrl) {
 

package/project/.sdk/src/cmp/js/utility_js.ts

@@ -7,6 +7,7 @@ import {
   canonScalarKey,
   each,
   opParams,
+  jsQuote,
 } from '@voxgig/sdkgen'
 
 import {
@@ -54,7 +55,7 @@ function exampleValue(entity: any, op: any, paramName: string, placeholder: stri
   if ('NULL' === key) {
     return 'null'
   }
-  return `'${placeholder}'`
+  return jsQuote(placeholder)
 }
 
 

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

@@ -6,13 +6,14 @@ 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).
 
 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'
@@ -141,7 +142,7 @@ val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
       Content(`#### Example: List
 
 \`\`\`kotlin
-val ${eVar}List = client.${accessor}(null).list(null, null)
+val ${eVar}List = client.${accessor}(null).list(${kotlinListMatch(entity)}, null)
 \`\`\`
 
 `)

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 && '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/ReadmeModel_kotlin.ts

@@ -24,12 +24,12 @@ 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. |',
-    patch: '| `patch` | `(reqdata, ctrl) -> Any?` | Change part of 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', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -94,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)

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

@@ -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,33 +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 data',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Returns the patched entity data and raises on error.',
+    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.',
   },
 }
 
@@ -285,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())
+}
 \`\`\`
 
 `)

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

@@ -7,7 +7,7 @@ import {
   nom,
 } from '@voxgig/apidef'
 
-import { kotlinVarName, kotlinPackage } from './utility_kotlin'
+import { kotlinVarName, kotlinPackage, kotlinListMatch } from './utility_kotlin'
 
 
 // A type-correct Kotlin literal for a param: numeric/boolean/array/object
@@ -15,6 +15,7 @@ import { kotlinVarName, kotlinPackage } from './utility_kotlin'
 // SDK's loose object model means all values live in MutableMap<String, Any?>.
 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'
@@ -35,9 +36,12 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const authActive = isAuthActive(model)
 
+  const shown = null != exampleEntity &&
+    ['list', 'load'].some((op: string) => Object.keys(exampleEntity.op || {}).includes(op))
+
   Content(`\`\`\`kotlin
 import ${kotlinPackage(model)}.core.${SDK}
-
+${shown ? `import ${kotlinPackage(model)}.core.SdkEntity\n` : ''}
 `)
 
   if (authActive) {
@@ -61,9 +65,11 @@ import ${kotlinPackage(model)}.core.${SDK}
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eNameLower}s (returns Any?, an aggregate list; raises on error)
-val ${eVar}List = client.${accessor}(null).list(null, null)
-println(${eVar}List)
+      Content(`// List all ${eNameLower}s (a list of entities, one per record; raises on error)
+val ${eVar}List = client.${accessor}(null).list(${kotlinListMatch(exampleEntity)}, null) as List<*>
+for (${eVar}Item in ${eVar}List) {
+    println((${eVar}Item as SdkEntity).data())
+}
 `)
     }
 
@@ -81,9 +87,9 @@ println(${eVar}List)
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')})`
         : 'null'
       Content(`
-// Load a specific ${eNameLower} (returns the record, raises on error)
-val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
-println(${eVar})
+// Load a specific ${eNameLower} (returns the entity, raises on error)
+val ${eVar} = client.${accessor}(null).load(${loadArg}, null) as SdkEntity
+println(${eVar}.data())
 `)
     }
   }