@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,16 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct PHP literal for a field's canonical type.
+function phpLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k || 'OBJECT' === k) return '[]'
+  return '"example"'
+}
+
+
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -15,20 +25,51 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  Content(`\`\`\`php
-$client = ${model.const.Name}SDK::test(null, null);
-`)
-
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`[$result, $err] = $client->${eName}(null)->load(
-    ["id" => "test01"], null
-);
+    const ename = eName.toLowerCase()
+    // Model-driven id key: null when the entity has no id-like field.
+    const idF = entityIdField(exampleEntity)
+    // Drive the test-mode example off the entity's PRIMARY op (never a hardcoded
+    // `load` a create-only entity lacks).
+    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    const recBody = idF ? `["${idF}" => "test01"]` : '[]'
+    let callArg = ''
+    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
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: 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(', ')}]`
+        : ''
+    } else if ('create' === primaryOp || 'update' === 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(', ')}]`
+    }
+    // A list result is an array — name the variable accordingly.
+    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}]],
+]);
+$${eVar} = $client->${eName}()->${primaryOp}(${callArg});
+\`\`\`
 `)
-  }
-
-  Content(`\`\`\`
+  } else {
+    Content(`\`\`\`php
+$client = ${model.const.Name}SDK::test();
+\`\`\`
 `)
+  }
 
 })
 

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

@@ -190,7 +190,7 @@ ${listSkipBlock}        $client = $setup["client"];
 `)
         }
         Content(`
-        [$result, $err] = $client->direct([
+        $result = $client->direct([
             "path" => "${listPath}",
             "method" => "GET",
             "params" => $params,
@@ -198,7 +198,7 @@ ${listSkipBlock}        $client = $setup["client"];
 `)
       } else {
         Content(`
-        [$result, $err] = $client->direct([
+        $result = $client->direct([
             "path" => "${listPath}",
             "method" => "GET",
             "params" => [],
@@ -210,8 +210,8 @@ ${listSkipBlock}        $client = $setup["client"];
             // Live mode is lenient: synthetic IDs frequently 4xx and the
             // list-response shape varies wildly across public APIs. Skip
             // rather than fail when the call doesn't return a usable list.
-            if ($err !== null) {
-                $this->markTestSkipped("list call failed (likely synthetic IDs against live API): " . (string)$err);
+            if (!empty($result["err"])) {
+                $this->markTestSkipped("list call failed (likely synthetic IDs against live API): " . (string)$result["err"]);
                 return;
             }
             if (empty($result["ok"])) {
@@ -224,7 +224,7 @@ ${listSkipBlock}        $client = $setup["client"];
                 return;
             }
         } else {
-            $this->assertNull($err);
+            $this->assertArrayNotHasKey("err", $result);
             $this->assertTrue($result["ok"]);
             $this->assertEquals(200, Helpers::to_int($result["status"]));
             $this->assertIsArray($result["data"]);
@@ -300,7 +300,7 @@ ${loadLiveQueryLines}
       }
 
       Content(`
-        [$result, $err] = $client->direct([
+        $result = $client->direct([
             "path" => "${loadPath}",
             "method" => "GET",
 `)
@@ -317,8 +317,8 @@ ${loadLiveQueryLines}
             // Live mode is lenient: synthetic IDs frequently 4xx. Skip
             // rather than fail when the load endpoint isn't reachable
             // with the IDs we can construct from setup.idmap.
-            if ($err !== null) {
-                $this->markTestSkipped("load call failed (likely synthetic IDs against live API): " . (string)$err);
+            if (!empty($result["err"])) {
+                $this->markTestSkipped("load call failed (likely synthetic IDs against live API): " . (string)$result["err"]);
                 return;
             }
             if (empty($result["ok"])) {
@@ -331,7 +331,7 @@ ${loadLiveQueryLines}
                 return;
             }
         } else {
-            $this->assertNull($err);
+            $this->assertArrayNotHasKey("err", $result);
             $this->assertTrue($result["ok"]);
             $this->assertEquals(200, Helpers::to_int($result["status"]));
             $this->assertNotNull($result["data"]);

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

@@ -278,8 +278,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        [$${datavar}_result, $err] = $${entvar}->create($${datavar}, null);
-        $this->assertNull($err);
+        $${datavar}_result = $${entvar}->create($${datavar}, null);
         $${datavar} = Helpers::to_map($${datavar}_result);
         $this->assertNotNull($${datavar});
 `)
@@ -324,8 +323,7 @@ const generateList: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        [$${listvar}_result, $err] = $${entvar}->list($${matchvar}, null);
-        $this->assertNull($err);
+        $${listvar}_result = $${entvar}->list($${matchvar}, null);
         $this->assertIsArray($${listvar}_result);
 `)
 
@@ -413,8 +411,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-        [$${resdatavar}_result, $err] = $${entvar}->update($${datavar}_up, null);
-        $this->assertNull($err);
+        $${resdatavar}_result = $${entvar}->update($${datavar}_up, null);
         $${resdatavar} = Helpers::to_map($${resdatavar}_result);
         $this->assertNotNull($${resdatavar});
 `)
@@ -479,8 +476,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     Content(`        $${matchvar} = [
             "id" => $${srcdatavar}["id"],
         ];
-        [$${datavar}_loaded, $err] = $${entvar}->load($${matchvar}, null);
-        $this->assertNull($err);
+        $${datavar}_loaded = $${entvar}->load($${matchvar}, null);
         $${datavar}_load_result = Helpers::to_map($${datavar}_loaded);
         $this->assertNotNull($${datavar}_load_result);
         $this->assertEquals($${datavar}_load_result["id"], $${srcdatavar}["id"]);
@@ -488,8 +484,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   }
   else {
     Content(`        $${matchvar} = [];
-        [$${datavar}_loaded, $err] = $${entvar}->load($${matchvar}, null);
-        $this->assertNull($err);
+        $${datavar}_loaded = $${entvar}->load($${matchvar}, null);
         $this->assertNotNull($${datavar}_loaded);
 `)
   }
@@ -517,8 +512,7 @@ const generateRemove: OpGen = (ctx, step, index) => {
   Content(`        $${matchvar} = [
             "id" => $${srcdatavar}["id"],
         ];
-        [$_, $err] = $${entvar}->remove($${matchvar}, null);
-        $this->assertNull($err);
+        $${entvar}->remove($${matchvar}, null);
 `)
 }
 

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

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_php'
 import { TestDirect } from './TestDirect_php'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_php'
 
 
 const Test = cmp(function Test(props: any) {
@@ -47,6 +48,9 @@ class ExistsTest extends TestCase
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // README example snippet test (syntax + offline test-mode run).
+    ReadmeExamplesTest({ target })
   })
 })
 

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

@@ -55,6 +55,9 @@ class EntityNameEntity
         return new EntityNameEntity($this->_client, $opts);
     }
 
+    /**
+     * @param EntityName|array $args EntityName data (assoc-array) to store.
+     */
     public function data_set($args): void
     {
         if ($args) {
@@ -63,12 +66,18 @@ class EntityNameEntity
         }
     }
 
+    /**
+     * @return EntityName|array The current EntityName data as an assoc-array.
+     */
     public function data_get()
     {
         ($this->_utility->feature_hook)($this->_entctx, "GetData");
         return Struct::clone($this->_data);
     }
 
+    /**
+     * @param array $args Match filter (any subset of EntityName fields).
+     */
     public function match_set($args): void
     {
         if ($args) {
@@ -77,6 +86,9 @@ class EntityNameEntity
         }
     }
 
+    /**
+     * @return array The current match filter (any subset of EntityName fields).
+     */
     public function match_get()
     {
         ($this->_utility->feature_hook)($this->_entctx, "GetMatch");
@@ -93,7 +105,7 @@ class EntityNameEntity
 
     // #RemoveOp
 
-    private function _run_op($ctx, callable $post_done): array
+    private function _run_op($ctx, callable $post_done): mixed
     {
         $utility = $this->_utility;
 

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

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function create($reqdata, $ctrl = null): array
+    /**
+     * Create a new EntityName.
+     *
+     * @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).
+     */
+    public function create(?array $reqdata = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

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

@@ -1,6 +1,15 @@
 // EJECT-START
 
-    public function list($reqmatch, $ctrl = null): array
+    /**
+     * List EntityName items matching the given filter.
+     *
+     * @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).
+     */
+    public function list(?array $reqmatch = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

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

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function load($reqmatch, $ctrl = null): array
+    /**
+     * Load a single EntityName.
+     *
+     * @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).
+     */
+    public function load(?array $reqmatch = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

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

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function remove($reqmatch, $ctrl = null): array
+    /**
+     * Remove an EntityName matching the given criteria.
+     *
+     * @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).
+     */
+    public function remove(?array $reqmatch = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

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

@@ -3,7 +3,16 @@ require_once __DIR__ . '/../core/Helpers.php';
 
 // EJECT-START
 
-    public function update($reqdata, $ctrl = null): array
+    /**
+     * Update an existing EntityName.
+     *
+     * @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).
+     */
+    public function update(?array $reqdata = null, $ctrl = null): mixed
     {
         $utility = $this->_utility;
         $ctx = ($utility->make_context)([

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

@@ -103,7 +103,7 @@ class ProjectNameSDK
         return $this->_rootctx;
     }
 
-    public function prepare(array $fetchargs = []): array
+    public function prepare(array $fetchargs = []): mixed
     {
         $utility = $this->_utility;
         $fetchargs = $fetchargs ?? [];
@@ -149,19 +149,27 @@ class ProjectNameSDK
 
         [$_, $err] = ($utility->prepare_auth)($ctx);
         if ($err) {
-            return [null, $err];
+            return ($utility->make_error)($ctx, $err);
         }
 
-        return ($utility->make_fetch_def)($ctx);
+        [$fetchdef, $fd_err] = ($utility->make_fetch_def)($ctx);
+        if ($fd_err) {
+            return ($utility->make_error)($ctx, $fd_err);
+        }
+        return $fetchdef;
     }
 
-    public function direct(array $fetchargs = []): array
+    public function direct(array $fetchargs = []): mixed
     {
         $utility = $this->_utility;
 
-        [$fetchdef, $err] = $this->prepare($fetchargs);
-        if ($err) {
-            return [["ok" => false, "err" => $err], null];
+        // direct() is the raw-HTTP escape hatch: it never throws, it returns
+        // an {ok, err, ...} dict. prepare() now raises on error, so catch it
+        // and surface the failure through the dict instead.
+        try {
+            $fetchdef = $this->prepare($fetchargs);
+        } catch (\Throwable $err) {
+            return ["ok" => false, "err" => $err];
         }
 
         $fetchargs = $fetchargs ?? [];
@@ -176,14 +184,14 @@ class ProjectNameSDK
         [$fetched, $fetch_err] = ($utility->fetcher)($ctx, $url, $fetchdef);
 
         if ($fetch_err) {
-            return [["ok" => false, "err" => $fetch_err], null];
+            return ["ok" => false, "err" => $fetch_err];
         }
 
         if ($fetched === null) {
-            return [[
+            return [
                 "ok" => false,
                 "err" => $ctx->make_error("direct_no_response", "response: undefined"),
-            ], null];
+            ];
         }
 
         if (is_array($fetched)) {
@@ -208,18 +216,18 @@ class ProjectNameSDK
                 }
             }
 
-            return [[
+            return [
                 "ok" => $status >= 200 && $status < 300,
                 "status" => $status,
                 "headers" => Struct::getprop($fetched, "headers"),
                 "data" => $json_data,
-            ], null];
+            ];
         }
 
-        return [[
+        return [
             "ok" => false,
             "err" => $ctx->make_error("direct_invalid", "invalid response type"),
-        ], null];
+        ];
     }
 
     // <[SLOT]>

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

@@ -10,6 +10,7 @@ import {
   cmp,
   each,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -39,8 +40,8 @@ const Config = cmp(async function Config(props: any) {
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  let authPrefix = ''
-  try { authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`) } catch (_e) { }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }

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

@@ -0,0 +1,184 @@
+
+
+// Typed-model generator (Python target). Port of EntityTypes_ts.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one module, <sdk>_types.py,
+// with a `class <Name>(TypedDict):` per active entity plus a request/match type
+// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned into
+// real Python types by the shared sdkgen helper `canonToType` (source of truth:
+// @voxgig/apidef VALID_CANON).
+//
+// TYPE CHOICE: `TypedDict`, not `@dataclass`. The generated ops return/accept
+// plain runtime dicts (data_get/match_get return `vs.clone(self._data)`; ops
+// take/return dicts), so a `@dataclass` annotation is only aspirational — a
+// strict checker at a call site would see dict-vs-dataclass. A TypedDict *is* a
+// dict shape, so annotating these dict-returning/-accepting ops with TypedDict
+// makes the TYPES MATCH the runtime. Runtime behaviour is unchanged.
+//
+// OPTIONAL FIELDS: a `req:false` field/param is a key that MAY be absent, which
+// is exactly TypedDict `total=False` (key optionality), not `Optional[T]` (a
+// None value). To express required AND optional keys on py>=3.8 WITHOUT a
+// typing_extensions dependency (no `NotRequired`), a type with both splits into
+// a required base `class <Name>Required(TypedDict): ...` and a `total=False`
+// subclass `class <Name>(<Name>Required, total=False): ...` that carries the
+// public name and adds the optional keys. Degenerate shapes collapse to a
+// single class (all-required, all-optional, or empty). The all-optional
+// collapse also serves the match-mirror types (the Python analogue of TS
+// `Partial<${Name}>`).
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch.
+
+import {
+  cmp, each,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'py'
+
+
+// Python keywords that cannot be used as class-syntax TypedDict field names.
+const PY_KEYWORDS = new Set([
+  'False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await', 'break',
+  'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally',
+  'for', 'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal',
+  'not', 'or', 'pass', 'raise', 'return', 'try', 'while', 'with', 'yield',
+])
+
+
+// A name usable as a class-syntax TypedDict key (valid identifier, not a
+// keyword). Non-identifier/keyword field names have no safe class-syntax
+// rendering, so they are skipped (they remain reachable via the runtime dict).
+function pyIdent(name: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !PY_KEYWORDS.has(name)
+}
+
+
+// Emit a TypedDict named `typeName` from a list of {name, type, optional}
+// items (optionality already decided by the caller — the shared partiality
+// policy for op types, or `req` for the entity data type). Required items
+// become required keys; optional items become not-required keys via a
+// `total=False` extension.
+//
+// Shape selection (see file header for the rationale):
+//   both required + optional -> `<typeName>Required` base + `total=False` sub
+//   only required            -> single `class <typeName>(TypedDict):`
+//   only optional            -> single `class <typeName>(TypedDict, total=False):`
+//   no usable keys           -> single `class <typeName>(TypedDict): pass`
+function emitTypedDict(typeName: string, items: any[]): void {
+  const usable = items.filter((it: any) => it && null != it.name && pyIdent(it.name))
+
+  const required = usable.filter((it: any) => !it.optional)
+  const optional = usable.filter((it: any) => it.optional)
+
+  const field = (it: any) => `    ${it.name}: ${canonToType(it.type, LANG)}
+`
+
+  if (0 === usable.length) {
+    Content(`class ${typeName}(TypedDict):
+    pass
+`)
+    return
+  }
+
+  if (0 === required.length) {
+    Content(`class ${typeName}(TypedDict, total=False):
+`)
+    optional.forEach((it: any) => Content(field(it)))
+    return
+  }
+
+  if (0 === optional.length) {
+    Content(`class ${typeName}(TypedDict):
+`)
+    required.forEach((it: any) => Content(field(it)))
+    return
+  }
+
+  Content(`class ${typeName}Required(TypedDict):
+`)
+  required.forEach((it: any) => Content(field(it)))
+  Content(`
+
+class ${typeName}(${typeName}Required, total=False):
+`)
+  optional.forEach((it: any) => Content(field(it)))
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model } = props.ctx$
+  const target = props.target || {}
+  const ext = target.ext || LANG
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  File({ name: model.const.Name.toLowerCase() + '_types.' + ext }, () => {
+
+    Content(`# Typed models for the ${model.const.Name} SDK.
+#
+# GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+# params (op.<name>.points[].args.params[]). Field/param types come from the
+# canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+# @voxgig/apidef VALID_CANON). Do not edit by hand.
+#
+# These are TypedDicts, not dataclasses: the SDK ops return/accept plain dicts
+# at runtime, and a TypedDict IS a dict shape, so the types match the runtime.
+# Optional (req:false) keys are modelled as TypedDict key-optionality
+# (total=False), split into a required base + total=False subclass when a type
+# has both required and optional keys.
+
+from __future__ import annotations
+
+from typing import TypedDict, Any
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one key per field, `req:false` -> optional key.
+      Content(`
+
+`)
+      emitTypedDict(Name, fields.map((f: any) => ({
+        name: f.name, type: f.type, optional: false === f.req,
+      })))
+
+      // Per active op: a request/match type. Members and their optionality come
+      // from the shared partiality policy (opRequestShape); this file only
+      // renders them as a TypedDict.
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        Content(`
+
+`)
+        emitTypedDict(typeName, items)
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}