@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/rust/ReadmeTopQuick_rust.ts

@@ -0,0 +1,95 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { crateIdent, rustVarName } from './utility_rust'
+
+
+// A type-correct rust expression constructing a voxgig struct Value for a
+// param. Strings render the quoted placeholder; numeric/boolean/array/object
+// render a typed literal.
+function rustLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
+  if ('BOOLEAN' === k) return 'Value::Bool(true)'
+  if ('ARRAY' === k) return 'Value::empty_list()'
+  if ('OBJECT' === k) return 'Value::empty_map()'
+  return `Value::str("${placeholder}")`
+}
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const rustcrate = crateIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `${model.const.Name}SDK::new(jo(vec![\n    ("apikey", Value::str(std::env::var("${envName(model)}_APIKEY").unwrap_or_default())),\n]))`
+    : `${model.const.Name}SDK::new(Value::Noval)`
+
+  Content(`\`\`\`rust
+use ${rustcrate}::{jo, ${model.const.Name}SDK, Value};
+
+let client = ${ctor};
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const eVar = rustVarName(exampleEntity.name)
+    const method = rustVarName(exampleEntity.name)
+    const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`// List all ${eName.toLowerCase()}s (returns a Value::List, Err on failure)
+let ${eVar}s = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
+if let Value::List(items) = &${eVar}s {
+    for ${eVar} in items.borrow().iter() {
+        println!("{:?}", ${eVar});
+    }
+}
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `jo(vec![${loadItems.map((it: any) =>
+          `("${it.name}", ${rustLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)})`).join(', ')}])`
+        : 'Value::Noval'
+      Content(`
+// Load a specific ${eName.toLowerCase()} (returns the record, Err on failure)
+let ${eVar} = client.${method}(Value::Noval).load(${loadArg}, Value::Noval).unwrap();
+println!("{:?}", ${eVar});
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/rust/ReadmeTopTest_rust.ts

@@ -0,0 +1,81 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { crateIdent, rustVarName } from './utility_rust'
+
+
+// A type-correct rust expression constructing a voxgig struct Value for a
+// field's canonical type.
+function rustLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
+  if ('BOOLEAN' === k) return 'Value::Bool(true)'
+  if ('ARRAY' === k) return 'Value::empty_list()'
+  if ('OBJECT' === k) return 'Value::empty_map()'
+  return 'Value::str("example")'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const rustcrate = crateIdent(model)
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`rust
+use ${rustcrate}::{jo, test_sdk, Value};
+
+let client = test_sdk(Value::Noval, Value::Noval);
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eName = nom(exampleEntity, 'Name')
+    const method = rustVarName(exampleEntity.name)
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'Value::Noval'
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's request match.
+      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))
+      arg = 0 < items.length
+        ? `jo(vec![${items.map((it: any) =>
+          `("${it.name}", ${it.name === idF ? 'Value::str("test01")' : rustLit(it.type)})`).join(', ')}])`
+        : 'Value::Noval'
+    } 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)
+      arg = 0 < chosen.length
+        ? `jo(vec![${chosen.map((it: any) => `("${it.name}", ${rustLit(it.type)})`).join(', ')}])`
+        : 'Value::empty_map()'
+    }
+    const eVar = rustVarName(exampleEntity.name) + ('list' === primaryOp ? 's' : '')
+    Content(`let ${eVar} = client.${method}(Value::Noval).${primaryOp}(${arg}, Value::Noval).unwrap();
+println!("{:?}", ${eVar});
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/rust/TestDirect_rust.ts

@@ -73,7 +73,7 @@ const TestDirect = cmp(function TestDirect(props: any) {
     ? `("apikey", getp(&env, "${PROJECTNAME}_APIKEY"))`
     : ''
 
-  const opnames = Object.keys(entity.op)
+  const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
 
@@ -81,8 +81,8 @@ const TestDirect = cmp(function TestDirect(props: any) {
     return
   }
 
-  const loadOp = (entity.op as any).load
-  const listOp = (entity.op as any).list
+  const loadOp = (entity.op as any)?.load
+  const listOp = (entity.op as any)?.list
 
   // Load point info.
   const loadPoint = loadOp?.points?.[0]

package/project/.sdk/src/cmp/rust/TestEntity_rust.ts

@@ -104,7 +104,14 @@ fn ${evar}_entity_instance() {
     let ent = testsdk.${method}(Value::Noval);
     assert_eq!(ent.get_name(), "${entity.name}");
 }
+`)
 
+    // The stream test drives the list op; only emit it when the entity has a
+    // list op (a create/load-only entity has no list endpoint, so
+    // stream("list") panics with point_no_points).
+    const flowHasList = allSteps.some((s: any) => 'list' === s.op)
+    if (flowHasList) {
+      Content(`
 #[test]
 fn ${evar}_entity_stream() {
     // stream() runs the list op through the full pipeline and yields each
@@ -144,7 +151,10 @@ fn ${evar}_entity_stream() {
         .collect();
     assert_eq!(plain_items.len(), 2, "fallback stream should yield both items");
 }
+`)
+    }
 
+    Content(`
 #[test]
 fn ${evar}_entity_basic() {
     let setup = ${evar}_basic_setup(Value::Noval);

package/project/.sdk/src/cmp/rust/Test_rust.ts

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_rust'
 import { TestDirect } from './TestDirect_rust'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_rust'
 import { crateIdent } from './utility_rust'
 
 
@@ -42,6 +43,9 @@ fn exists_test_mode() {
       TestEntity({ target, entity, rustcrate })
       TestDirect({ target, entity, rustcrate })
     })
+
+    // Validate the documented rust examples in the READMEs are well-formed.
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/scala/EntityTypes_scala.ts

@@ -0,0 +1,201 @@
+
+
+// Typed-model generator (Scala target). Port of EntityTypes_java.ts /
+// EntityTypes_py.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits ONE file, core/<Name>Types.scala,
+// holding an `object <Name>Types` with a nested `final case class` per active
+// entity plus a request/match case class per active op.
+//
+// WHY A CONTAINER OBJECT: keeps the whole reference model in one file whatever
+// the entity count and matches the java target's single-container layout
+// (<Name>Types.java). Scala permits multiple top-level types per file, but a
+// container object mirrors the JVM sibling and keeps the generated core/ dir
+// tidy.
+//
+// TYPE CHOICE: reference `case class` types with BOXED (nullable) component
+// types, NOT the wired runtime type. The generated ops take/return the loose
+// object model (java.util.Map[String, Object] / Object), so these case classes
+// are NOT wired into the op signatures — they are documentation/DX reference
+// shapes a caller may use to describe a payload before converting it to a map.
+// This mirrors the java target's reference records and the JS target's JSDoc
+// typedefs (annotation only, no runtime effect). Emitting unused case classes
+// is harmless — they compile and have no runtime effect.
+//
+// OPTIONAL FIELDS: every component is a boxed reference type, hence inherently
+// nullable, so a `req:false` field/param needs no distinct rendering in Scala.
+//
+// Sentinels map to Scala types via the SHARED canonToType 'scala' column (the
+// single source of truth per language — do not keep a local table here).
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch (via the shared opTypeName helper).
+
+import {
+  cmp, each, names,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { scalaPackage } from './utility_scala'
+
+
+const LANG = 'scala'
+
+
+// Scala reserved words that cannot be a case-class parameter name.
+const SCALA_KEYWORDS = new Set<string>([
+  'abstract', 'case', 'catch', 'class', 'def', 'do', 'else', 'enum', 'export',
+  'extends', 'false', 'final', 'finally', 'for', 'forSome', 'given', 'if',
+  'implicit', 'import', 'lazy', 'match', 'new', 'null', 'object', 'override',
+  'package', 'private', 'protected', 'return', 'sealed', 'super', 'then',
+  'this', 'throw', 'trait', 'true', 'try', 'type', 'val', 'var', 'while',
+  'with', 'yield',
+])
+
+
+// A field/param name that has a safe Scala identifier rendering. Names that are
+// not valid identifiers (hyphens, leading digits) have no clean parameter form
+// and are skipped — they remain reachable via the runtime map.
+function scalaIdent(name: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) && !SCALA_KEYWORDS.has(name)
+}
+
+
+// Emit a nested `final case class <typeName>(...)` from {name, type} items. An
+// item whose name is not a legal identifier is skipped (WITH a warning — the
+// key stays reachable via the runtime map, but its absence from the typed
+// model should be visible, not silent); a duplicate component name (after the
+// identifier filter) is dropped. An empty case class is a valid,
+// zero-parameter shape.
+function emitCaseClass(typeName: string, items: any[], log?: any): void {
+  const seen = new Set<string>()
+  const usable = items.filter((it: any) => {
+    if (!it || null == it.name) {
+      return false
+    }
+    if (!scalaIdent(it.name)) {
+      if (log && log.warn) {
+        log.warn({
+          point: 'entity-types-skip-field', typeName, field: it.name,
+          note: `scala: field "${it.name}" of ${typeName} has no legal ` +
+            `Scala identifier form; omitted from the typed model (still ` +
+            `reachable via the runtime map)`,
+        })
+      }
+      return false
+    }
+    if (seen.has(it.name)) {
+      return false
+    }
+    seen.add(it.name)
+    return true
+  })
+
+  if (0 === usable.length) {
+    Content(`  final case class ${typeName}()
+
+`)
+    return
+  }
+
+  const params = usable
+    .map((it: any) => `${it.name}: ${canonToType(it.type, LANG)}`)
+    .join(', ')
+  Content(`  final case class ${typeName}(${params})
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model, log } = props.ctx$
+  const target = props.target || {}
+  const ext = target.ext || 'scala'
+
+  const scalapackage = props.scalapackage || scalaPackage(model)
+
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  // Emit for EVERY entity that gets generated entity code: the consumer
+  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
+  // filter, so inactive entities still get class files referencing these
+  // typed names. Filter on `name` (always present), NOT `active` — parity
+  // with the go emitter's fix.
+  const entityList = deriveEntityNames(entity)
+  // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
+  // entity not yet named (e.g. a fieldless placeholder) would otherwise read
+  // `Name = undefined` below. Parity with the go/py/java/csharp emitter's fix.
+
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
+  File({ name: model.const.Name + 'Types.' + ext }, () => {
+
+    Content(`package ${scalapackage}.core
+
+// Typed reference 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 (source of truth: @voxgig/apidef VALID_CANON). Do
+// not edit by hand.
+//
+// These case classes are documentation/DX reference shapes ONLY. The SDK ops
+// take and return the loose object model (java.util.Map[String, Object] /
+// Object) at runtime, so these types are not wired into the op signatures —
+// use them to describe a payload before converting it to a map. Every
+// component is a boxed (nullable) type, so an optional (req:false) key needs
+// no distinct rendering.
+
+object ${model.const.Name}Types {
+
+`)
+
+    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 component per field.
+      emitCaseClass(Name, fields.map((f: any) => ({
+        name: f.name, type: f.type,
+      })), log)
+
+      // Per active op: a request/match case class. Members come from the shared
+      // partiality policy (opRequestShape).
+      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)
+
+        emitCaseClass(typeName, items, log)
+      })
+    })
+
+    Content(`}
+`)
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/scala/Entity_scala.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, camelify, names,
   File, Content, Folder, Fragment,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 import {
@@ -23,7 +23,7 @@ const Entity = cmp(function Entity(props: any) {
   const scalapackage = scalaPackage(model)
 
   // Collision-free entity CLASS name.
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
   const entrep = {
@@ -39,7 +39,7 @@ const Entity = cmp(function Entity(props: any) {
 
     File({ name: cls + '.' + target.ext }, () => {
 
-      const opnames = Object.keys(entity.op)
+      const opnames = Object.keys(entity.op || {})
 
       // For each CRUD op: if the spec defines it, splice in the real
       // implementation. Otherwise emit a stub that satisfies the SdkEntity

package/project/.sdk/src/cmp/scala/MainEntity_scala.ts

@@ -1,6 +1,6 @@
 
 
-import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -18,7 +18,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { model } = props.ctx$
 
   const scalapackage = scalaPackage(model)
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
   const accessor = scalaVarName(entity.name)
 

package/project/.sdk/src/cmp/scala/Main_scala.ts

@@ -23,6 +23,7 @@ import { Config } from './Config_scala'
 import { Gitignore } from './Gitignore_scala'
 import { MainEntity } from './MainEntity_scala'
 import { EntityBase } from './EntityBase_scala'
+import { EntityTypes } from './EntityTypes_scala'
 import { scalaPackage } from './utility_scala'
 
 
@@ -83,6 +84,11 @@ const Main = cmp(async function Main(props: any) {
     })
 
     Config({ target })
+
+    // Generate the typed reference-model file (<Name>Types.scala) beside the
+    // other generated core files. Documentation/DX shapes only — not wired
+    // into the loose-object-model op signatures.
+    EntityTypes({ target, scalapackage })
   })
 
 })

package/project/.sdk/src/cmp/scala/ReadmeEntity_scala.ts

@@ -0,0 +1,175 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { scalaVarName } from './utility_scala'
+
+
+// Type names come from the shared canonToType 'scala' column (single source of truth).
+
+// A type-correct Scala literal for a field's canonical type.
+function scalaLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'java.util.List.of()'
+  if ('OBJECT' === k) return 'java.util.Map.of()'
+  return `"${placeholder}"`
+}
+
+
+// Operation method spelling for Scala: camelCase methods over the loose object
+// model. The op descriptions are language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match, null)',   desc: 'Load a single entity by match criteria.' },
+  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.' },
+  remove: { method: 'remove(match, null)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // Sanitise the local variable name — a camelCased Scala keyword gets a
+    // trailing underscore (scalaVarName) so the snippet compiles.
+    const eVar = scalaVarName(entity.name)
+    const accessor = scalaVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`val ${eVar} = client.${accessor}(null)\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.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.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `java.util.Map.of(${loadItems.map((it: any) =>
+          `"${it.name}", ${scalaLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')})`
+        : 'null'
+      Content(`#### Example: Load
+
+\`\`\`scala
+val ${eVar} = client.${accessor}(null).load(${loadArg}, null)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`scala
+val ${eVar}List = client.${accessor}(null).list(null, null)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.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.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`scala
+val ${eVar} = client.${accessor}(null).create(java.util.Map.of(
+`)
+      createItems.map((it: any, i: number) => {
+        const comma = i < createItems.length - 1 ? ',' : ''
+        Content(`    "${it.name}", ${scalaLit(it.type, 'example_' + it.name)}${comma}  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`), null)
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}