@voxgig/sdkgen 1.2.0 → 1.3.1

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -16,32 +18,53 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   // Find the first published entity for examples
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,\n})`
+    : `new ${model.const.Name}SDK()`
 
   Content(`
 ### Create a Client
 
 \`\`\`js
-const { ${model.const.Name}SDK } = require('${target.module.name}')
+const { ${model.const.Name}SDK } = require('${packageName(model, target.name)}')
 
-const client = new ${model.const.Name}SDK({${apikeyArg}})
+const client = ${ctor}
 \`\`\`
 `)
 
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
     const opnames = Object.keys(exampleEntity.op || {})
 
+    // Model-driven example fields, in parity with the ts target: derive the
+    // create/update body from the op shape (opRequestShape) so the docs show
+    // REAL writable fields, not a hardcoded field the entity may not have.
+    // `idF` is the entity's id-like field name, or null when it has none —
+    // then load/remove match on no argument and update omits the id.
+    const idF = entityIdField(exampleEntity)
+    // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+    const eVar = safeVarName(exampleEntity.name, 'js')
+    const exampleFields = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      // create needs ALL required fields for parity with the typed ts target.
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : items.slice(0, 2)
+      return chosen.map((it: any) =>
+        `  ${it.name}: ${exampleValue(exampleEntity, exampleEntity.op[opname], it.name, 'example_' + it.name)},`)
+    }
+
     if (opnames.includes('load')) {
       Content(`
-### Load a ${eName}
+### Load ${article} ${eName}
 
 \`\`\`js
-const ${exampleEntity.name} = await client.${eName}().load({ id: '${exampleEntity.name}_id' })
-console.log(${exampleEntity.name})
+const ${eVar} = await client.${eName}().load(${idF ? `{ ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, idF, exampleEntity.name + '_id')} }` : ''})
+console.log(${eVar})
 \`\`\`
 `)
     }
@@ -51,34 +74,37 @@ console.log(${exampleEntity.name})
 ### List ${eName} Records
 
 \`\`\`js
-const ${exampleEntity.name}s = await client.${eName}().list()
-console.log(${exampleEntity.name}s)
+const ${eVar}s = await client.${eName}().list()
+for (const ${eVar} of ${eVar}s) {
+  console.log(${eVar})
+}
 \`\`\`
 `)
     }
 
     if (opnames.includes('create')) {
+      const createLines = exampleFields('create')
+      const createBody = createLines.length ? '\n' + createLines.join('\n') + '\n' : ''
       Content(`
 ### Create a ${eName}
 
 \`\`\`js
-const created = await client.${eName}().create({
-  // Provide ${exampleEntity.name} fields
-})
+const created = await client.${eName}().create({${createBody}})
 console.log(created)
 \`\`\`
 `)
     }
 
     if (opnames.includes('update')) {
+      const updateLines = (idF
+        ? [`  ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.update, idF, exampleEntity.name + '_id')},`]
+        : []).concat(exampleFields('update'))
+      const updateBody = updateLines.length ? '\n' + updateLines.join('\n') + '\n' : ''
       Content(`
 ### Update a ${eName}
 
 \`\`\`js
-const updated = await client.${eName}().update({
-  id: '${exampleEntity.name}_id',
-  // Fields to update
-})
+const updated = await client.${eName}().update({${updateBody}})
 console.log(updated)
 \`\`\`
 `)
@@ -89,7 +115,7 @@ console.log(updated)
 ### Remove a ${eName}
 
 \`\`\`js
-await client.${eName}().remove({ id: '${exampleEntity.name}_id' })
+await client.${eName}().remove(${idF ? `{ ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.remove, idF, exampleEntity.name + '_id')} }` : ''})
 \`\`\`
 `)
     }

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

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
@@ -70,8 +72,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`options\` | \`object\` | SDK configuration options. |
-| \`options.apikey\` | \`string\` | API key for authentication. |
-| \`options.base\` | \`string\` | Base URL for API requests. |
+${isAuthActive(model) ? '| \`options.apikey\` | \`string\` | API key for authentication. |\n' : ''}| \`options.base\` | \`string\` | Base URL for API requests. |
 | \`options.prefix\` | \`string\` | URL prefix appended after base. |
 | \`options.suffix\` | \`string\` | URL suffix appended after path. |
 | \`options.headers\` | \`object\` | Custom headers for all requests. |
@@ -180,6 +181,11 @@ Alias for \`${model.Name}SDK.test()\`.
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
+      // Model-driven id key: null when this entity has no id-like field, in
+      // which case load/remove match on no argument and update omits the id.
+      const idF = entityIdField(ent)
+      // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+      const eVar = safeVarName(ent.name, 'js')
 
       Content(`
 ---
@@ -195,7 +201,7 @@ Alias for \`${model.Name}SDK.test()\`.
       }
 
       Content(`\`\`\`ts
-const ${ent.name} = client.${ent.Name}()
+const ${eVar} = client.${ent.Name}()
 \`\`\`
 
 `)
@@ -211,7 +217,7 @@ const ${ent.name} = client.${ent.Name}()
         each(fields, (field: any) => {
           const req = field.req ? 'Yes' : 'No'
           const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${req} | ${desc} |
+          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -221,15 +227,18 @@ const ${ent.name} = client.${ent.Name}()
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
+          // Only emit columns for operations this entity actually exposes —
+          // never advertise a create/update/remove column the entity lacks.
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
-| Field | load | list | create | update | remove |
-| --- | --- | --- | --- | --- | --- |
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
 `)
           each(fields, (field: any) => {
             const fops = field.op || {}
-            const cols = ['load', 'list', 'create', 'update', 'remove'].map((op: string) => {
-              if (!opnames.includes(op)) return '-'
+            const cols = opcols.map((op: string) => {
               const fop = fops[op]
               if (null == fop) return '-'
               if (fop.active === false) return '-'
@@ -264,7 +273,7 @@ ${info.desc}
           // Show example
           if ('load' === opname || 'remove' === opname) {
             Content(`\`\`\`ts
-const result = await client.${ent.Name}().${opname}({ id: '${ent.name}_id' })
+const result = await client.${ent.Name}().${opname}(${idF ? `{ ${idF}: ${exampleValue(ent, ent.op && ent.op[opname], idF, ent.name + '_id')} }` : ''})
 \`\`\`
 
 `)
@@ -282,7 +291,7 @@ const result = await client.${ent.Name}().create({
 `)
             each(fields, (field: any) => {
               if ('id' !== field.name && field.req) {
-                Content(`  ${field.name}: /* ${field.type || 'value'} */,
+                Content(`  ${field.name}: /* ${canonToType(field.type, target.name)} */,
 `)
               }
             })
@@ -292,10 +301,12 @@ const result = await client.${ent.Name}().create({
 `)
           }
           else if ('update' === opname) {
+            const updateIdLine = idF
+              ? `  ${idF}: ${exampleValue(ent, ent.op && ent.op.update, idF, ent.name + '_id')},\n`
+              : ''
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().update({
-  id: '${ent.name}_id',
-  // Fields to update
+${updateIdLine}  // Fields to update
 })
 \`\`\`
 

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

@@ -12,6 +12,9 @@ const result = await client.direct({
   method: 'GET',
   params: { id: 'example' },
 })
+if (result instanceof Error) {
+  throw result
+}
 console.log(result.data)
 \`\`\`
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -14,24 +16,28 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,\n})`
+    : `new ${model.const.Name}SDK()`
 
   Content(`\`\`\`js
-const { ${model.const.Name}SDK } = require('${target.module.name}')
+const { ${model.const.Name}SDK } = require('${packageName(model, target.name)}')
 
-const client = new ${model.const.Name}SDK({${apikeyArg}})
+const client = ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    const eVar = safeVarName(eName.toLowerCase(), 'js')
     const opnames = Object.keys(exampleEntity.op || {})
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s
-const ${eName.toLowerCase()}s = await client.${eName}().list()
+      Content(`// List all ${eName.toLowerCase()}s (returns an array)
+const ${eVar}s = await client.${eName}().list()
+for (const ${eVar} of ${eVar}s) {
+  console.log(${eVar})
+}
 `)
     }
 
@@ -42,16 +48,26 @@ const ${eName.toLowerCase()}s = await client.${eName}().list()
 
     if (nestedEntity && opnames.includes('load')) {
       const neName = nom(nestedEntity, 'Name')
+      const neVar = safeVarName(neName.toLowerCase(), 'js')
       const parentFields = (nestedEntity.fields || [])
         .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
       const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
+      const loadOp = nestedEntity.op && nestedEntity.op.load
+
+      // Model-driven id key: only emit an id match line if the nested entity
+      // has an id-like key field.
+      const neIdF = entityIdField(nestedEntity)
+      const neMatchLines = [`  ${parentParam}: ${exampleValue(nestedEntity, loadOp, parentParam, 'example')},`]
+      if (neIdF) {
+        neMatchLines.push(`  ${neIdF}: ${exampleValue(nestedEntity, loadOp, neIdF, 'example_id')},`)
+      }
 
       Content(`
-// Load a specific ${neName.toLowerCase()}
-const ${neName.toLowerCase()} = await client.${neName}().load({
-  ${parentParam}: 'example',
-  id: 'example_id',
+// Load a specific ${neName.toLowerCase()} (returns the entity)
+const ${neVar} = await client.${neName}().load({
+${neMatchLines.join('\n')}
 })
+console.log(${neVar})
 `)
     }
   }

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
@@ -20,8 +22,26 @@ const client = ${model.const.Name}SDK.test()
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`const result = await client.${eName}().load({ id: 'test01' })
-// result.ok === true, result.data contains mock data
+    const eVar = safeVarName(eName.toLowerCase(), 'js')
+    // 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 primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
+    const idF = entityIdField(exampleEntity)
+    let arg = ''
+    if ('load' === primaryOp || 'remove' === primaryOp) {
+      arg = idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, 'test01')} }` : ''
+    } 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 = `{ ${chosen.map((it: any) =>
+        `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`).join(', ')} }`
+    }
+    Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
+// ${eVar} is a bare entity populated with mock data
+console.log(${eVar})
 `)
   }
 

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameCreateData} [reqdata]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async create(reqdata, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameListMatch} [reqmatch]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName[]>}
+   */
   async list(reqmatch, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameLoadMatch} [reqmatch]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async load(reqmatch, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameRemoveMatch} [reqmatch]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async remove(reqmatch, ctrl) {
 
     const utility = this._utility

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

@@ -4,6 +4,11 @@ class EntityOperation {
 
   // EJECT-START
 
+  /**
+   * @param {EntityNameUpdateData} [reqdata]
+   * @param {Object} [ctrl]
+   * @returns {Promise<EntityName>}
+   */
   async update(reqdata, ctrl) {
 
     const utility = this._utility

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

@@ -2,12 +2,68 @@
 import * as Path from 'node:path'
 
 
+import {
+  canonKey,
+  each,
+} from '@voxgig/sdkgen'
+
 import {
   clone,
   walk,
 } from '@voxgig/struct'
 
 
+// --- Model-driven example literals -----------------------------------------
+// Doc snippets must use example values whose TYPE matches the generated
+// types, or the snippet misrepresents the API. The id/match params of
+// load/remove/update are the common trap: their generated
+// `<Name><Op>Match` / `<Name><Op>Data` type is built from the op's params
+// (see EntityTypes_js.ts), so a numeric id shown as a quoted string is
+// wrong. These helpers derive the example literal from the SAME model
+// source, so the docs and the generated types can never disagree.
+
+// The declared canon-type sentinel of a named parameter of an op — looked up
+// in the op's `points[].args.params[]` exactly as the typed-model generator
+// does. Falls back to the entity field of the same name (used when the op
+// has no params). Returns undefined when neither is present.
+function paramCanonType(entity: any, op: any, paramName: string): unknown {
+  const points = op && op.points ? each(op.points) : []
+  for (const pt of points as any[]) {
+    const params = pt && pt.args && pt.args.params ? each(pt.args.params) : []
+    const found = (params as any[]).find((p: any) => p && p.name === paramName)
+    if (found) {
+      return found.type
+    }
+  }
+  const field = (entity && entity.fields ? each(entity.fields) : [])
+    .find((f: any) => f && f.name === paramName) as any
+  return field && field.type
+}
+
+
+// A type-correct example literal for a named match/data parameter of an op,
+// derived entirely from the model. INTEGER/NUMBER render as the bare number
+// `1`, BOOLEAN as `true`, ARRAY as the empty `[]` and OBJECT as the empty
+// `{}`, everything else (STRING, unknown, missing) as the quoted
+// `placeholder`.
+function exampleValue(entity: any, op: any, paramName: string, placeholder: string): string {
+  const key = canonKey(paramCanonType(entity, op, paramName))
+  if ('INTEGER' === key || 'NUMBER' === key) {
+    return '1'
+  }
+  if ('BOOLEAN' === key) {
+    return 'true'
+  }
+  if ('ARRAY' === key) {
+    return '[]'
+  }
+  if ('OBJECT' === key) {
+    return '{}'
+  }
+  return `'${placeholder}'`
+}
+
+
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
 }
@@ -61,4 +117,5 @@ export {
   formatJSONSrc,
   formatJson,
   projectPath,
+  exampleValue,
 }

package/project/.sdk/src/cmp/lua/EntityTypes_lua.ts

@@ -0,0 +1,113 @@
+
+
+// Typed-model generator (Lua target).
+//
+// Lua is dynamically typed, so the "types" are LuaLS annotations
+// (---@class / ---@field) for editor/tooling DX only — no runtime effect.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file, <sdk>_types.lua,
+// with a `---@class <Name>` per active entity plus a request/match ---@class
+// per active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned
+// into LuaLS types by the shared sdkgen helper `canonToType` ('lua' column).
+//
+// Keeps the SAME type-name scheme as the TS reference (<Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch). The op fragments reference these class names via
+// ---@param / ---@return.
+
+import {
+  cmp, each,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'lua'
+
+
+// A bare LuaLS field key, or a bracketed string literal for anything that is
+// not a plain Lua identifier.
+function propKey(name: string): string {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name) ? name : '[' + JSON.stringify(name) + ']'
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  File({ name: model.name + '_types.' + (target.ext || LANG) }, () => {
+
+    Content(`-- Typed models for the ${model.const.Name} SDK (LuaLS annotations).
+--
+-- 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). Annotations only — no runtime effect. Do not
+-- edit by hand.
+
+`)
+
+    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 ---@field per field, `req:false` -> optional (?).
+      Content(`---@class ${Name}
+`)
+      fields.forEach((f: any) => {
+        const opt = false === f.req ? '?' : ''
+        Content(`---@field ${propKey(f.name)}${opt} ${canonToType(f.type, LANG)}
+`)
+      })
+      Content(`
+`)
+
+      // Per active op: a request/match class. Members and their optionality
+      // come from the shared partiality policy (opRequestShape); this file only
+      // renders them as LuaLS ---@field lines.
+      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(`---@class ${typeName}
+`)
+        items.forEach((it: any) => {
+          const opt = it.optional ? '?' : ''
+          Content(`---@field ${propKey(it.name)}${opt} ${canonToType(it.type, LANG)}
+`)
+        })
+        Content(`
+`)
+      })
+    })
+
+    // Make the file a require-able (empty) module. The blank line above keeps
+    // LuaLS from binding the last ---@class to this local.
+    Content(`local M = {}
+
+return M
+`)
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/lua/MainEntity_lua.ts

@@ -8,8 +8,16 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { model } = props.ctx$
 
   Content(`
+-- Idiomatic facade: client:${entity.Name}():list() / client:${entity.Name}():load({ id = ... })
+-- Entity access is capitalised (PascalCase) for parity with the other SDKs.
 function ${model.const.Name}SDK:${entity.Name}(data)
   local EntityMod = require("entity.${entity.name}_entity")
+  if data == nil then
+    if self._${entity.name} == nil then
+      self._${entity.name} = EntityMod.new(self, nil)
+    end
+    return self._${entity.name}
+  end
   return EntityMod.new(self, data)
 end
 

package/project/.sdk/src/cmp/lua/Main_lua.ts

@@ -22,6 +22,7 @@ import { Package } from './Package_lua'
 import { Config } from './Config_lua'
 import { Gitignore } from './Gitignore_lua'
 import { MainEntity } from './MainEntity_lua'
+import { EntityTypes } from './EntityTypes_lua'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -79,6 +80,9 @@ self._utility.feature_hook(self._rootctx, "${name}")
       })
   })
 
+  // Generate typed-model annotations (LuaLS ---@class / ---@field)
+  EntityTypes({ target })
+
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })