@voxgig/sdkgen 4.34.1 → 4.34.2

package/project/.sdk/src/cmp/php/EntityOperation_php.ts

@@ -1,7 +1,8 @@
 
 import {
   cmp, camelify,
-  Content, Fragment
+  Content, Fragment,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -29,6 +30,7 @@ const EntityOperation = cmp(function Operation(props: any) {
       ProjectName: model.const.Name,
       EntityName: entity.Name,
       entityname: entity.name,
+      EntyClass: entityClassName(entity, entityCollection(model), true),
       '#Feature-Hook': ({ name, indent }: any) =>
         Content({ indent }, `
 ($u->feature_hook)($ctx, "${name}");

package/project/.sdk/src/cmp/php/ReadmeEntity_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor, opNeedsAction } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor, opNeedsAction, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,7 @@ import {
 // parse).
 function phpLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -133,8 +134,8 @@ $${entity.name} = $client->${phpEntityAccessor(entity.Name)}()->load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`php
-// list() returns an array of ${entity.Name} records (throws on error).
-$${entity.name}s = $client->${phpEntityAccessor(entity.Name)}()->list();
+// list() returns an array of ${entity.Name} entities, one per record (throws on error).
+$${entity.name}s = $client->${phpEntityAccessor(entity.Name)}()->list(${listMatchArg('php', entity)});
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/php/ReadmeHowto_php.ts

@@ -1,11 +1,12 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor, seededList, litPair } from '@voxgig/sdkgen'
 
 import { KIT, getModelPath, nom } from '@voxgig/apidef'
 
 
 function phpLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -27,29 +28,34 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { entity: exampleEntity, primaryOp } = pickExampleEntity(
     Object.keys(seedable).length ? seedable : entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
-  // Model-driven id key: null when the entity has no id-like field.
+  // Model-driven id key (null when the entity has none); the seed is keyed by model name.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  const listed = exampleEntity && 'list' === primaryOp
+    ? seededList('php', exampleEntity, idF, 'test01') : null
   const seedSentence = idF
     ? '. Seed fixture\ndata via the `entity` option so offline calls resolve without a live server'
     : ''
+  const record = idF ? (listed ? listed.record : [litPair('php', idF, '"test01"')]).join(', ') : ''
   const testCtor = idF
-    ? `${model.const.Name}SDK::test([\n    "entity" => ["${eName.toLowerCase()}" => ["test01" => ["${idF}" => "test01"]]],\n])`
+    ? `${model.const.Name}SDK::test([\n    "entity" => ["${exampleEntity.name}" => ["test01" => [${record}]]],\n])`
     : `${model.const.Name}SDK::test()`
   let testCallArg = ''
-  if (exampleEntity && isMatchOp) {
+  if (listed) {
+    testCallArg = 0 < listed.call.length ? `[${listed.call.join(', ')}]` : ''
+  } else if (exampleEntity && isMatchOp) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => !it.optional || it.name === idF)
       .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
     testCallArg = 0 < items.length
-      ? `[${items.map((it: any) => `"${it.name}" => ${it.name === idF ? '"test01"' : phpLit(it.type)}`).join(', ')}]`
+      ? `[${items.map((it: any) => litPair('php', it.name, it.name === idF ? '"test01"' : phpLit(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)
-    testCallArg = `[${chosen.map((it: any) => `"${it.name}" => ${phpLit(it.type)}`).join(', ')}]`
+    testCallArg = `[${chosen.map((it: any) => litPair('php', it.name, phpLit(it.type))).join(', ')}]`
   }
 
   // The op-driven test-mode line, shown only when the SDK has an entity op.

package/project/.sdk/src/cmp/php/ReadmeModel_php.ts

@@ -21,12 +21,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): array` | Load a single entity by match criteria. |',
-    list: '| `list` | `(?array $reqmatch = null, $ctrl): array` | List entities matching the criteria (call with no argument to list all). |',
-    create: '| `create` | `($reqdata, $ctrl): array` | Create a new entity. |',
-    update: '| `update` | `($reqdata, $ctrl): array` | Update an existing entity. |',
-    patch: '| `patch` | `($reqdata, $ctrl): array` | Change part of an existing entity. |',
-    remove: '| `remove` | `($reqmatch, $ctrl): array` | Remove an entity. |',
+    load: '| `load` | `($reqmatch, $ctrl): mixed` | Load a single entity by match criteria, and return it. |',
+    list: '| `list` | `(?array $reqmatch = null, $ctrl): mixed` | List entities matching the criteria (call with no argument to list all), one per record. |',
+    create: '| `create` | `($reqdata, $ctrl): mixed` | Create a new entity, and return it. |',
+    update: '| `update` | `($reqdata, $ctrl): mixed` | Update an existing entity, and return it. |',
+    patch: '| `patch` | `($reqdata, $ctrl): mixed` | Change part of an existing entity, and return it. |',
+    remove: '| `remove` | `($reqmatch, $ctrl): mixed` | Remove an entity, and return it marked as deleted. |',
   }
   const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
@@ -94,9 +94,9 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data_get() for the record) (an \`array\` for single-entity
-ops, a \`list\` for \`list\`) and throw on error. Wrap calls in
-\`try\`/\`catch\` to handle failures.
+Entity operations return the entity, and \`list\` an \`array\` of entities, one
+per record; an entity's \`data_get()\` reads its record (an \`array\`). They
+throw on error, so wrap calls in \`try\`/\`catch\` to handle failures.
 
 The \`direct()\` escape hatch never throws — it returns a result \`array\`
 you branch on via \`$result["ok"]\`:

package/project/.sdk/src/cmp/php/ReadmeQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, phpEntityAccessor, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -55,6 +55,7 @@ $client = ${ctor};
     // placeholder would not parse).
     const phpLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'null'
       if ('INTEGER' === k || 'NUMBER' === k) return '1'
       if ('BOOLEAN' === k) return 'true'
       if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -79,7 +80,7 @@ $client = ${ctor};
 \`\`\`php
 try {
     // list() returns entity instances; data_get() reads each record.
-    $${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
+    $${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list(${listMatchArg('php', exampleEntity)});
     foreach ($${eName.toLowerCase()}s as $record) {
         $item = $record->data_get();
         echo ${itemPrint} . "\\n";

package/project/.sdk/src/cmp/php/ReadmeRef_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, phpEntityAccessor , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape, phpEntityAccessor, targetFeatures, opNeedsAction, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -14,6 +14,7 @@ import {
 // parse).
 function phpLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -24,33 +25,33 @@ function phpLit(type: any, placeholder: string = 'example'): string {
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(array $reqmatch, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Load a single entity matching the given criteria. Throws on error.',
+    returns: 'mixed — the entity; throws on error',
+    desc: 'Load a single entity matching the given criteria. Returns the entity, whose record `data_get()` reads, and throws on error.',
   },
   list: {
     sig: 'list(?array $reqmatch = null, ?array $ctrl = null): mixed',
-    returns: 'array — the list of results; throws on error',
-    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array. Throws on error.',
+    returns: 'array — the entities, one per record; throws on error',
+    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array of entities, one per record, and throws on error.',
   },
   create: {
     sig: 'create(array $reqdata, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Create a new entity with the given data. Throws on error.',
+    returns: 'mixed — the created entity; throws on error',
+    desc: 'Create a new entity with the given data. Returns the created entity and throws on error.',
   },
   update: {
     sig: 'update(array $reqdata, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Update an existing entity. The data must include the entity `id`. Throws on error.',
+    returns: 'mixed — the updated entity; throws on error',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity and throws on error.',
   },
   patch: {
     sig: 'patch(array $reqdata, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Throws on error.',
+    returns: 'mixed — the patched entity; throws on error',
+    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 throws on error.',
   },
   remove: {
     sig: 'remove(array $reqmatch, ?array $ctrl = null): mixed',
-    returns: 'mixed — the result data; throws on error',
-    desc: 'Remove the entity matching the given criteria. Throws on error.',
+    returns: 'mixed — the entity, marked as deleted; throws on error',
+    desc: 'Remove the entity matching the given criteria. Returns the entity, marked as deleted, and throws on error.',
   },
 }
 
@@ -285,7 +286,7 @@ $result = $client->${phpEntityAccessor(ent.Name)}()->${opname}(${arg});
           }
           else if ('list' === opname) {
             Content(`\`\`\`php
-$results = $client->${phpEntityAccessor(ent.Name)}()->list();
+$results = $client->${phpEntityAccessor(ent.Name)}()->list(${listMatchArg('php', ent)});
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/php/ReadmeTopQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, opRequestShape, phpEntityAccessor, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -13,6 +13,7 @@ import {
 // doc test EXECUTES this block, so a comment placeholder would break it).
 function phpLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -50,8 +51,8 @@ $client = ${ctor};
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns an array; throws on error)
-$${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list();
+      Content(`// List all ${eName.toLowerCase()}s (an array of entities, one per record; throws on error)
+$${eName.toLowerCase()}s = $client->${phpEntityAccessor(eName)}()->list(${listMatchArg('php', exampleEntity)});
 print_r(array_map(fn($item) => $item->data_get(), $${eName.toLowerCase()}s));
 `)
       hasCall = true
@@ -71,7 +72,7 @@ print_r(array_map(fn($item) => $item->data_get(), $${eName.toLowerCase()}s));
             it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}]`
         : ''
       Content(`
-// Load a specific ${eName.toLowerCase()} (returns the ENTITY; call data_get() for the record; throws on error)
+// Load a specific ${eName.toLowerCase()} (returns the entity; data_get() reads its record; throws on error)
 $${eName.toLowerCase()} = $client->${phpEntityAccessor(eName)}()->load(${loadArg});
 print_r($${eName.toLowerCase()}->data_get());
 `)

package/project/.sdk/src/cmp/php/ReadmeTopTest_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, phpEntityAccessor, seededList, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,6 +11,7 @@ import {
 // A type-correct PHP literal for a field's canonical type.
 function phpLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'null'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k || 'OBJECT' === k) return '[]'
@@ -33,9 +34,13 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
     // Model-driven id key: null when the entity has no id-like field.
     const idF = entityIdField(exampleEntity)
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
-    const recBody = idF ? `["${idF}" => "test01"]` : '[]'
+    const listed = 'list' === primaryOp ? seededList('php', exampleEntity, idF, 'test01') : null
+    const recPairs = listed ? listed.record : idF ? [litPair('php', idF, '"test01"')] : []
+    const recBody = `[${recPairs.join(', ')}]`
     let callArg = ''
-    if (isMatchOp) {
+    if (listed) {
+      callArg = 0 < listed.call.length ? `[${listed.call.join(', ')}]` : ''
+    } else if (isMatchOp) {
       // 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
@@ -44,21 +49,22 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
       callArg = 0 < items.length
         ? `[${items.map((it: any) =>
-          `"${it.name}" => ${it.name === idF ? '"test01"' : phpLit(it.type)}`).join(', ')}]`
+          litPair('php', it.name, it.name === idF ? '"test01"' : phpLit(it.type))).join(', ')}]`
         : ''
     } else if ('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)
-      callArg = `[${chosen.map((it: any) => `"${it.name}" => ${phpLit(it.type)}`).join(', ')}]`
+      callArg = `[${chosen.map((it: any) => litPair('php', it.name, phpLit(it.type))).join(', ')}]`
     }
-    // A list result is an array — name the variable accordingly.
+    // A list result is an array — name the variable accordingly. The fixture
+    // key is the model name, which the mock looks the entity up by.
     const eVar = ename + ('list' === primaryOp ? 's' : '')
     Content(`\`\`\`php
 // Seed fixture data so offline calls resolve without a live server.
 $client = ${model.const.Name}SDK::test([
-    "entity" => ["${ename}" => ["test01" => ${recBody}]],
+    "entity" => ["${exampleEntity.name}" => ["test01" => ${recBody}]],
 ]);
 $${eVar} = $client->${phpEntityAccessor(eName)}()->${primaryOp}(${callArg});
 \`\`\`

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

@@ -9,8 +9,8 @@ require_once __DIR__ . '/../core/Helpers.php';
      * @param EntityNameCreateData|array|null $reqdata Body data as an assoc-array;
      *   a typed EntityNameCreateData names the shape.
      * @param mixed $ctrl Optional per-call control overrides.
-     * @return EntityName|array The created EntityName as an assoc-array at the
-     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     * @return EntyClass The created EntityName entity, whose data_get() reads
+     *   its record; throws ProjectNameError on failure (item-5 convention).
      */
     public function create(?array $reqdata = null, $ctrl = null): mixed
     {

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

@@ -6,8 +6,8 @@
      * @param EntityNameListMatch|array|null $reqmatch Match filter (any subset
      *   of EntityName fields) as an assoc-array; EntityNameListMatch names the shape.
      * @param mixed $ctrl Optional per-call control overrides.
-     * @return EntityName[]|array A list of EntityName items as assoc-arrays at
-     *   the SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     * @return EntyClass[] The EntityName entities, one per record, each read
+     *   with data_get(); throws ProjectNameError on failure (item-5 convention).
      */
     public function list(?array $reqmatch = null, $ctrl = null): mixed
     {

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

@@ -9,8 +9,8 @@ require_once __DIR__ . '/../core/Helpers.php';
      * @param EntityNameLoadMatch|array|null $reqmatch Match criteria (id/query
      *   fields) as an assoc-array; a typed EntityNameLoadMatch names the shape.
      * @param mixed $ctrl Optional per-call control overrides.
-     * @return EntityName|array The loaded EntityName as an assoc-array at the
-     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     * @return EntyClass The loaded EntityName entity, whose data_get() reads
+     *   its record; throws ProjectNameError on failure (item-5 convention).
      */
     public function load(?array $reqmatch = null, $ctrl = null): mixed
     {

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

@@ -9,8 +9,8 @@ require_once __DIR__ . '/../core/Helpers.php';
      * @param EntityNamePatchData|array|null $reqdata Body data as an assoc-array;
      *   a typed EntityNamePatchData names the shape.
      * @param mixed $ctrl Optional per-call control overrides.
-     * @return EntityName|array The patched EntityName as an assoc-array at the
-     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     * @return EntyClass The patched EntityName entity, whose data_get() reads
+     *   its record; throws ProjectNameError on failure (item-5 convention).
      */
     public function patch(?array $reqdata = null, $ctrl = null): mixed
     {

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

@@ -9,8 +9,8 @@ require_once __DIR__ . '/../core/Helpers.php';
      * @param EntityNameRemoveMatch|array|null $reqmatch Match criteria (id/query
      *   fields) as an assoc-array; EntityNameRemoveMatch names the shape.
      * @param mixed $ctrl Optional per-call control overrides.
-     * @return EntityName|array The removed EntityName as an assoc-array at the
-     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     * @return EntyClass The removed EntityName entity, marked as deleted; throws
+     *   ProjectNameError on failure (item-5 convention).
      */
     public function remove(?array $reqmatch = null, $ctrl = null): mixed
     {

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

@@ -9,8 +9,8 @@ require_once __DIR__ . '/../core/Helpers.php';
      * @param EntityNameUpdateData|array|null $reqdata Body data as an assoc-array;
      *   a typed EntityNameUpdateData names the shape.
      * @param mixed $ctrl Optional per-call control overrides.
-     * @return EntityName|array The updated EntityName as an assoc-array at the
-     *   SDK boundary; throws ProjectNameError on failure (item-5 convention).
+     * @return EntyClass The updated EntityName entity, whose data_get() reads
+     *   its record; throws ProjectNameError on failure (item-5 convention).
      */
     public function update(?array $reqdata = null, $ctrl = null): mixed
     {

package/project/.sdk/src/cmp/py/EntityOperation_py.ts

@@ -1,7 +1,8 @@
 
 import {
   cmp, camelify,
-  Content, Fragment
+  Content, Fragment,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 
@@ -29,6 +30,7 @@ const EntityOperation = cmp(function Operation(props: any) {
       ProjectName: model.const.Name,
       EntityName: entity.Name,
       entityname: entity.name,
+      EntyClass: entityClassName(entity, entityCollection(model)),
       '#Feature-Hook': ({ name, indent }: any) =>
         Content({ indent }, `
 u.feature_hook(ctx, "${name}")

package/project/.sdk/src/cmp/py/ReadmeEntity_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, matchArg, idLiteral, opNeedsAction } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, opNeedsAction, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,6 +9,7 @@ import {
 
 function pyLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -17,12 +18,6 @@ function pyLit(type: any, placeholder: string = 'example'): string {
 }
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const OP_DESC: Record<string, { method: string, desc: string }> = {
   load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
   list:   { method: 'list()',        desc: 'List entities, optionally matching the given criteria.' },
@@ -139,7 +134,7 @@ ${eVar} = client.${entity.Name}().load(${loadArg})
       Content(`#### Example: List
 
 \`\`\`python
-${eVar}s = client.${entity.Name}().list(${listMatchArg(entity)})
+${eVar}s = client.${entity.Name}().list(${listMatchArg('py', entity)})
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/py/ReadmeHowto_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, canonScalarKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, requiredItems, litPair } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,6 +10,7 @@ import {
 
 function pyLit(type: any): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'None'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'True'
   if ('ARRAY' === k) return '[]'
@@ -33,28 +34,27 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = ''
-  if (exampleEntity && isMatchOp) {
-    const items = opRequestShape(exampleEntity, primaryOp).items
-      .filter((it: any) => !it.optional || it.name === idF)
+  if (exampleEntity && (isMatchOp || ('list' === primaryOp && 0 < requiredItems(exampleEntity, 'list').length))) {
+    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))
     testArg = 0 < items.length
-      ? `{${items.map((it: any) => `"${it.name}": ${it.name === idF ? '"test01"' : pyLit(it.type)}`).join(', ')}}`
+      ? `{${items.map((it: any) => litPair('py', it.name, isMatchOp && it.name === idF ? '"test01"' : pyLit(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 = `{${chosen.map((it: any) => `"${it.name}": ${pyLit(it.type)}`).join(', ')}}`
+    testArg = `{${chosen.map((it: any) => litPair('py', it.name, pyLit(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_get() for the record.
+    ? `# Entity ops return the entity, and list one per record; they raise on error.
 ${eVar} = client.${eName}().${primaryOp}(${testArg})
-# ${eVar} contains the mock response record`
+# data_get() on an entity reads its mock response record`
     : `result = client.direct({"path": "/api/resource", "method": "GET"})
 print(result)`
 

package/project/.sdk/src/cmp/py/ReadmeModel_py.ts

@@ -21,12 +21,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) -> list` | List entities matching the criteria. 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) -> list` | 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')
@@ -95,9 +95,9 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return the ENTITY (call data_get() for the record) (a \`dict\` for single-entity
-ops, a \`list\` for \`list\`) and raise on error. Wrap calls in
-\`try\`/\`except\` to handle failures.
+Entity operations return the entity, and \`list\` a \`list\` of entities, one
+per record; an entity's \`data_get()\` reads its record (a \`dict\`). They raise
+on error, so wrap calls in \`try\`/\`except\` to handle failures.
 
 The \`direct()\` escape hatch never raises — it returns a result \`dict\`
 you branch on via \`result["ok"]\`:

package/project/.sdk/src/cmp/py/ReadmeQuick_py.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, matchArg, idLiteral , serverVariables} from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,12 +8,6 @@ import {
 } from '@voxgig/apidef'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('py', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -75,6 +69,7 @@ client = ${ctor}
     // placeholder would not parse).
     const pyLit = (type: any, placeholder: string = 'example'): string => {
       const k = canonScalarKey(type)
+      if ('NULL' === k) return 'None'
       if ('INTEGER' === k || 'NUMBER' === k) return '1'
       if ('BOOLEAN' === k) return 'True'
       if ('ARRAY' === k) return '[]'
@@ -85,14 +80,14 @@ client = ${ctor}
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns a \`list\` of records (each a \`dict\`) and raises on
-error — iterate it directly.
+\`list()\` returns a \`list\` of entities, one per record, and raises on
+error; an entity's \`data_get()\` reads its record (a \`dict\`).
 
 \`\`\`python
 try:
-    ${eVar}s = client.${eName}().list(${listMatchArg(exampleEntity)})
+    ${eVar}s = client.${eName}().list(${listMatchArg('py', exampleEntity)})
     for ${eVar} in ${eVar}s:
-        print(${eVar})
+        print(${eVar}.data_get())
 except Exception as err:
     print(f"list failed: {err}")
 \`\`\`
@@ -125,7 +120,7 @@ ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
 \`\`\`python
 try:
     ${neVar} = client.${neName}().load({${neMatch.join(', ')}})
-    print(${neVar})
+    print(${neVar}.data_get())
 except Exception as err:
     print(f"load failed: {err}")
 \`\`\`
@@ -150,7 +145,7 @@ except Exception as err:
 \`\`\`python
 try:
     ${eVar} = client.${eName}().load(${loadArg})
-    print(${eVar})
+    print(${eVar}.data_get())
 except Exception as err:
     print(f"load failed: {err}")
 \`\`\`
@@ -196,7 +191,7 @@ created = client.${eName}().create({${examplePairs('create').join(', ')}})
       if (opnames.includes('update')) {
         const updatePairs = (idF ? [`"${idF}": ${idValueFor('update')}`] : []).concat(examplePairs('update'))
         const fromCreated = null != dataIdF && opnames.includes('create')
-        Content(`# Update${fromCreated ? " — the created record's id is a plain dict key" : ''}
+        Content(`# Update${fromCreated ? " — the created entity's record holds its id" : ''}
 client.${eName}().update({${updatePairs.join(', ')}})
 
 `)