@voxgig/sdkgen 1.3.14 → 1.3.17

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

@@ -0,0 +1,104 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { scalaVarName, scalaPackage } from './utility_scala'
+
+
+// A type-correct Scala literal for a param: numeric/boolean/array/object params
+// render a typed literal; strings render the quoted placeholder. The SDK's
+// loose object model means all values live in java.util.Map[String, Object].
+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}"`
+}
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const SDK = model.const.Name + 'SDK'
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+
+  Content(`\`\`\`scala
+import ${scalaPackage(model)}.core.${SDK}
+
+`)
+
+  if (authActive) {
+    Content(`val options = new java.util.LinkedHashMap[String, Object]()
+options.put("apikey", System.getenv("${envName(model)}_APIKEY"))
+val client = new ${SDK}(options)
+
+`)
+  }
+  else {
+    Content(`val client = new ${SDK}()
+
+`)
+  }
+
+  if (exampleEntity) {
+    // Sanitise the local variable name — an entity whose camelCased name is a
+    // Scala keyword gets a trailing underscore (scalaVarName) so the snippet
+    // compiles.
+    const eVar = scalaVarName(exampleEntity.name)
+    const accessor = scalaVarName(exampleEntity.name)
+    const eNameLower = nom(exampleEntity, 'Name').toLowerCase()
+    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 an empty match.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`// List all ${eNameLower}s (returns Object, an aggregate list; raises on error)
+val ${eVar}List = client.${accessor}(null).list(null, null)
+println(${eVar}List)
+`)
+    }
+
+    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
+        ? `java.util.Map.of(${loadItems.map((it: any) =>
+          `"${it.name}", ${scalaLit(it.type,
+            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})
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

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

@@ -0,0 +1,77 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { scalaVarName } from './utility_scala'
+
+
+// A type-correct Scala literal for a field's canonical type.
+function scalaLit(type: any): 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 '"example"'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const SDK = model.const.Name + 'SDK'
+
+  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(`\`\`\`scala
+val client = ${SDK}.testSDK(null, null)
+`)
+
+  if (exampleEntity && primaryOp) {
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'null'
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's request type, so the block stays honest.
+      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
+        ? `java.util.Map.of(${items.map((it: any) =>
+          `"${it.name}", ${it.name === idF ? '"test01"' : scalaLit(it.type)}`).join(', ')})`
+        : 'null'
+    } 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 = `java.util.Map.of(${chosen.map((it: any) =>
+        `"${it.name}", ${scalaLit(it.type)}`).join(', ')})`
+    }
+    const eVar = scalaVarName(exampleEntity.name) + ('list' === primaryOp ? 'List' : '')
+    const accessor = scalaVarName(exampleEntity.name)
+    Content(`val ${eVar} = client.${accessor}(null).${primaryOp}(${arg}, null)
+println(${eVar})
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

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

@@ -17,6 +17,7 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
+  entityDataIdField,
 } from '@voxgig/sdkgen'
 
 
@@ -119,6 +120,23 @@ object ${EntityName}EntityTest {
     Content(`      val now = System.currentTimeMillis()
 `)
 
+    // Preamble bootstrap: a flow with no `create` step (e.g. a read-only
+    // load/list entity) has nothing to declare the standard `<ref>_data` var
+    // that a later load/update/remove reads its id from. Seed it from the
+    // shipped "existing" fixtures here, mirroring the ts generator. Guarded on a
+    // DATA id field — an entity that carries no id has no `.get("id")` to read.
+    const flowHasCreate = allSteps.some((s: any) => s.op === 'create')
+    const needsPreambleData = !flowHasCreate &&
+      null != entityDataIdField(entity) &&
+      allSteps.some((s: any) => ['load', 'update', 'remove'].includes(s.op))
+    if (needsPreambleData) {
+      const preambleData = scalaVarName(entity.name + '_ref01_data')
+      Content(`      val ${preambleData}Raw = Struct.items(Helpers.toMapAny(
+          Struct.getpath(entityData, "existing.${ENTLOWER}")))
+      val ${preambleData} = Helpers.toMapAny(${preambleData}Raw.get(0).get(1))
+`)
+    }
+
     // Model-driven step iteration (sorted-key order for byte-stable output).
     each(basicflow.step, (step: any, index: any) => {
       const opgen: OpGen = GENERATE_OP[step.op]
@@ -166,7 +184,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
       ${datavar} = Helpers.toMapAny(${datavar}Result)
       rep.check("${ENTLOWER}.create.map", ${datavar} != null, "expected create result to be a map")
 `)
-  if (null != entity.id) {
+  if (null != entityDataIdField(entity)) {
     Content(`      rep.check("${ENTLOWER}.create.id", ${datavar} != null && ${datavar}.get("id") != null, "expected created entity to have an id")
 `)
   }
@@ -199,8 +217,12 @@ const generateList: OpGen = (ctx, step, index) => {
 `)
   }
 
+  // Select-by-id assertions require the DATA type to carry an id field
+  // (entityDataIdField); an entity keyed only on a load-MATCH id it does not
+  // return as data has no `.get("id")` to compare, so skip them.
+  const hasDataId = null != entityDataIdField(entity)
   const allSteps = Object.values(flow.step) as any[]
-  const listvarUsed = !!step.valid?.some((v: any) => {
+  const listvarUsed = hasDataId && !!step.valid?.some((v: any) => {
     if ('ItemExists' !== v.apply && 'ItemNotExists' !== v.apply) return false
     const validRef = v.def?.ref
     return validRef && allSteps.some((s: any) => 'create' === s.op &&
@@ -222,12 +244,12 @@ const generateList: OpGen = (ctx, step, index) => {
         ((s.input.ref ?? entity.name + '_ref01') === validRef))
       const refDataVar = scalaVarName(validRef + '_data')
 
-      if ('ItemExists' === validator.apply && hasRefData) {
+      if ('ItemExists' === validator.apply && hasRefData && hasDataId) {
         Content(`      val ${listvar}Found = Struct.select(
           SdkTestSupport.entityListToData(${listvar}), SdkTestSupport.om("id" -> ${refDataVar}.get("id")))
       rep.check("${ENTLOWER}.list.exists", !Struct.isempty(${listvar}Found), "expected to find created entity in list")
 `)
-      } else if ('ItemNotExists' === validator.apply && hasRefData) {
+      } else if ('ItemNotExists' === validator.apply && hasRefData && hasDataId) {
         Content(`      val ${listvar}NotFound = Struct.select(
           SdkTestSupport.entityListToData(${listvar}), SdkTestSupport.om("id" -> ${refDataVar}.get("id")))
       rep.check("${ENTLOWER}.list.notexists", Struct.isempty(${listvar}NotFound), "expected removed entity to not be in list")
@@ -251,7 +273,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   const needsEnt = !priorSteps.some((s: any) =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
-  const hasEntId = null != entity.id
+  const hasDataId = null != entityDataIdField(entity)
 
   Content(`      // UPDATE
 `)
@@ -261,7 +283,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
   Content(`      val ${datavar}Up = new LinkedHashMap[String, Object]()
 `)
-  if (hasEntId) {
+  if (hasDataId) {
     Content(`      ${datavar}Up.put("id", ${srcdatavar}.get("id"))
 `)
   }
@@ -293,7 +315,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
       val ${resdatavar} = Helpers.toMapAny(${resdatavar}Result)
       rep.check("${ENTLOWER}.update.map", ${resdatavar} != null, "expected update result to be a map")
 `)
-  if (hasEntId) {
+  if (hasDataId) {
     Content(`      rep.eq("${ENTLOWER}.update.id", ${datavar}Up.get("id"), ${resdatavar}.get("id"))
 `)
   }
@@ -328,7 +350,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
       return false
     })
 
-  const hasEntId = null != entity.id
+  const hasDataId = null != entityDataIdField(entity)
 
   Content(`      // LOAD
 `)
@@ -336,7 +358,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     Content(`      val ${entvar} = client.${accessor}(null)
 `)
   }
-  if (!hasSrcData && hasEntId) {
+  if (!hasSrcData && hasDataId) {
     Content(`      val ${srcdatavar}Raw = Struct.items(Helpers.toMapAny(
           Struct.getpath(entityData, "existing.${ENTLOWER}")))
       val ${srcdatavar} = Helpers.toMapAny(${srcdatavar}Raw.get(0).get(1))
@@ -344,7 +366,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   }
   Content(`      val ${matchvar} = new LinkedHashMap[String, Object]()
 `)
-  if (hasEntId) {
+  if (hasDataId) {
     Content(`      ${matchvar}.put("id", ${srcdatavar}.get("id"))
       val ${datavar}Loaded = ${entvar}.load(${matchvar}, null)
       val ${datavar}LoadResult = Helpers.toMapAny(${datavar}Loaded)
@@ -366,6 +388,12 @@ const generateRemove: OpGen = (ctx, step, index) => {
   const matchvar = scalaVarName(step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? '')))
   const srcdatavar = scalaVarName(step.input.srcdatavar ?? (ref + '_data'))
 
+  // The remove-by-id match reads ${srcdatavar}.get("id"); skip the whole step
+  // when the DATA type has no id field (there is no created id to remove by).
+  if (null == entityDataIdField(entity)) {
+    return
+  }
+
   const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))

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

@@ -14,6 +14,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_scala'
 import { TestDirect } from './TestDirect_scala'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_scala'
 import { scalaPackage } from './utility_scala'
 
 
@@ -54,6 +55,11 @@ const Test = cmp(function Test(props: any) {
       }
     })
 
+    // Documentation scala-examples presence + structure gate over the root
+    // README, scala/README.md and scala/REFERENCE.md. Driven through the same
+    // shared report by the SdkEntityTestMain aggregator below.
+    ReadmeExamplesTest({ target, scalapackage })
+
     // Aggregating main: run every generated per-entity test through one
     // shared report and exit non-zero on any failure.
     File({ name: 'SdkEntityTestMain.' + target.ext }, () => {
@@ -79,6 +85,8 @@ object SdkEntityTestMain {
         }
       }
       Content(`
+    ReadmeExamplesTest.run(rep)
+
     rep.finish("ENTITY")
   }
 }

package/project/.sdk/src/cmp/swift/EntityTypes_swift.ts

@@ -0,0 +1,152 @@
+
+// Typed-model generator (Swift target). Port of EntityTypes_rust.ts /
+// EntityTypes_go.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file,
+// Sources/ProjectNameSDK/entity/<Name>Types.swift, with a `struct <Name>` per
+// entity plus a request/match struct per active op. Field/param sentinels
+// ($STRING, $INTEGER, ...) map to Swift types via the SHARED canonToType
+// 'swift' column (the single source of truth per language — do not keep a
+// local table here).
+//
+// DESIGN NOTE: the Swift runtime is fully DYNAMIC — every op takes and returns
+// the vendored `Value` enum (throws on error) and the op fragments emit no
+// typed wrappers. These typed models are therefore DOCUMENTARY: they mirror the
+// entity/op shapes for reference and IDE support, but are not wired into the op
+// signatures. They compile as part of the SwiftPM target (every .swift under
+// Sources/ProjectNameSDK is built) so they stay in sync with the model.
+//   * Optional (req:false) member -> `T?`.
+//   * Unknown/missing sentinel -> the dynamic `Value` (never fails), matching
+//     the runtime's open shape.
+
+import {
+  cmp, each, names,
+  File, Content, Folder,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { swiftVarName } from './utility_swift'
+
+
+const LANG = 'swift'
+
+
+// One Swift struct property line. `optional` -> `T?`. Property names are
+// keyword-safe + lowerCamelCase via swiftVarName; duplicates are dropped by the
+// caller so a struct never declares the same property twice.
+function propLine(name: string, sentinel: any, optional: boolean): string {
+  const st = canonToType(sentinel, LANG)
+  const typ = optional ? `${st}?` : st
+  return `  public var ${swiftVarName(name)}: ${typ}\n`
+}
+
+
+// Emit a `struct <typeName>` from {name, type, optional} items, dropping
+// duplicate Swift identifiers (two model names can collapse to one ident). An
+// empty struct is a valid, zero-property shape.
+function emitStruct(comment: string, typeName: string, items: any[]): void {
+  Content(`${comment}
+public struct ${typeName} {
+`)
+  const seen = new Set<string>()
+  items.forEach((it: any) => {
+    if (null == it || null == it.name) return
+    const ident = swiftVarName(it.name)
+    if (seen.has(ident)) return
+    seen.add(ident)
+    Content(propLine(it.name, it.type, !!it.optional))
+  })
+  Content(`}
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { target } = props
+  const { model, log } = props.ctx$
+
+  // 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 an entity file (filter on `name`, always
+  // present; derive `Name` here so the struct set is deterministic — parity
+  // with the rust/go emitter's fix).
+  const entityList = each(entity).filter((e: any) => e && null != e.name)
+  entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
+
+  // 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)
+
+  Folder({ name: 'Sources' }, () => {
+    Folder({ name: 'ProjectNameSDK' }, () => {
+      Folder({ name: 'entity' }, () => {
+
+        File({ name: model.const.Name + 'Types.' + target.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 are mapped
+// from the canonical type sentinels. Do not edit by hand.
+//
+// These are DOCUMENTARY: the SDK runtime is dynamic (ops take/return the
+// \`Value\` enum), so nothing consumes these structs yet — they mirror the
+// entity/op shapes for reference and IDE support.
+
+import Foundation
+
+`)
+
+          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 property per field. req:false -> optional.
+            emitStruct(
+              `/// ${Name} is the typed data model for the ${ent.name} entity.`,
+              Name,
+              fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req }))
+            )
+
+            // Per active op: a request/match struct. Members and their
+            // optionality 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)
+
+                emitStruct(
+                  `/// ${typeName} is the typed request payload for ${Name}.${opname}.`,
+                  typeName,
+                  items
+                )
+              })
+          })
+        })
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/swift/Main_swift.ts

@@ -24,6 +24,7 @@ import { Gitignore } from './Gitignore_swift'
 import { MainEntity } from './MainEntity_swift'
 import { SdkError } from './SdkError_swift'
 import { EntityBase } from './EntityBase_swift'
+import { EntityTypes } from './EntityTypes_swift'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -86,6 +87,10 @@ const Main = cmp(async function Main(props: any) {
       })
     })
   })
+
+  // entity/<Name>Types.swift — documentary typed models (one struct per entity
+  // + per op). Compiles with the SwiftPM target; nothing consumes it yet.
+  EntityTypes({ target })
 })
 
 

package/project/.sdk/src/cmp/swift/ReadmeEntity_swift.ts

@@ -0,0 +1,176 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { swiftVarName } from './utility_swift'
+
+
+// Type names come from the shared canonToType 'swift' column (single source of truth).
+
+// A type-correct Swift `Value` literal for a field's canonical type.
+function swiftLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '.int(1)'
+  if ('NUMBER' === k) return '.double(1.0)'
+  if ('BOOLEAN' === k) return '.bool(true)'
+  if ('ARRAY' === k) return '.list([])'
+  if ('OBJECT' === k) return '.map(VMap())'
+  return `.string("${placeholder}")`
+}
+
+
+// Operation method spelling for Swift: methods over the loose object model,
+// taking optional (reqmatch/reqdata, ctrl) and throwing on error. The op
+// descriptions are language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match, nil)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(nil, nil)',     desc: 'List entities, optionally matching the given criteria.' },
+  create: { method: 'create(data, nil)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data, nil)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match, nil)', 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 Swift keyword gets a
+    // trailing underscore (swiftVarName) so the snippet compiles.
+    const eVar = swiftVarName(entity.name)
+    const accessor = entity.Name
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`let ${eVar} = client.${accessor}()\`
+
+`)
+
+    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
+        ? `VMap([${loadItems.map((it: any) =>
+          `("${it.name}", ${swiftLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)})`).join(', ')}])`
+        : 'nil'
+      Content(`#### Example: Load
+
+\`\`\`swift
+let ${eVar} = try client.${accessor}().load(${loadArg}, nil)
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`swift
+let ${eVar}List = try client.${accessor}().list(nil, nil)
+\`\`\`
+
+`)
+    }
+
+    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
+
+\`\`\`swift
+let ${eVar} = try client.${accessor}().create(VMap([
+`)
+      createItems.map((it: any, i: number) => {
+        const comma = i < createItems.length - 1 ? ',' : ''
+        Content(`    ("${it.name}", ${swiftLit(it.type, 'example_' + it.name)})${comma}  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`]), nil)
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}