@voxgig/sdkgen 1.3.4 → 1.3.5

package/project/.sdk/src/cmp/rb/ReadmeRef_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -172,6 +172,9 @@ same parameters as \`direct()\`. Raises on error.
       // 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)
+      // Sanitise the local variable name — an entity whose lowercased name is
+      // a Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
+      const eVar = safeVarName(ent.name, 'rb')
 
       Content(`
 ---
@@ -187,7 +190,7 @@ same parameters as \`direct()\`. Raises on error.
       }
 
       Content(`\`\`\`ruby
-${ent.name} = client.${ent.Name}
+${eVar} = client.${ent.Name}
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/rb/ReadmeTopQuick_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -43,6 +43,9 @@ client = ${ctor}
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    // Sanitise the local variable name — an entity whose lowercased name is a
+    // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(eName.toLowerCase(), 'rb')
     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.
@@ -52,8 +55,8 @@ client = ${ctor}
 
     if (opnames.includes('list')) {
       Content(`# List all ${eName.toLowerCase()}s (returns an Array; raises on error)
-${eName.toLowerCase()}s = client.${eName}.list
-puts ${eName.toLowerCase()}s
+${eVar}s = client.${eName}.list
+puts ${eVar}s
 `)
       hasCall = true
     }
@@ -73,8 +76,8 @@ puts ${eName.toLowerCase()}s
         : ''
       Content(`
 # Load a specific ${eName.toLowerCase()} (returns the bare record; raises on error)
-${eName.toLowerCase()} = client.${eName}.load(${loadArg})
-puts ${eName.toLowerCase()}
+${eVar} = client.${eName}.load(${loadArg})
+puts ${eVar}
 `)
       hasCall = true
     }

package/project/.sdk/src/cmp/rb/ReadmeTopTest_rb.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -24,17 +24,16 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
-  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
 
-  if (exampleEntity) {
+  if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
     const ename = eName.toLowerCase()
     // Model-driven id key: null when the entity has no id-like field, so the
     // seeded record carries no id and a match op takes no argument.
     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 = ''
@@ -56,8 +55,11 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
       const chosen = required.length ? required : items.slice(0, 3)
       callArg = `{ ${chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type)}`).join(', ')} }`
     }
-    // A list result is an Array — name the variable accordingly.
-    const eVar = ename + ('list' === primaryOp ? 's' : '')
+    // A list result is an Array — name the variable accordingly. Sanitise the
+    // base name — an entity whose lowercased name is a Ruby keyword (e.g.
+    // `self`) would otherwise emit uncompilable code. The fixture KEY (`ename`)
+    // stays raw so the mock lookup resolves.
+    const eVar = safeVarName(ename, 'rb') + ('list' === primaryOp ? 's' : '')
     Content(`\`\`\`ruby
 # Seed fixture data so offline calls resolve without a live server.
 client = ${model.const.Name}SDK.test({

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

@@ -3,7 +3,7 @@
 require_relative '../utility/struct/voxgig_struct'
 require_relative '../core/helpers'
 
-class EntityNameEntity
+class EntyClass
   def initialize(client, entopts = nil)
     entopts ||= {}
     if entopts["active"].nil?
@@ -35,7 +35,7 @@ class EntityNameEntity
 
   def make
     opts = @_entopts.dup
-    EntityNameEntity.new(@_client, opts)
+    EntyClass.new(@_client, opts)
   end
 
   def data_set(args)

package/project/.sdk/src/cmp/ts/Entity_ts.ts

@@ -4,9 +4,14 @@ import * as Path from 'node:path'
 import {
   cmp, each, camelify, names,
   File, Content, Folder, Fragment, Line, FeatureHook, Slot,
-  opTypeName,
+  opTypeName, entityClassName,
 } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
 import { EntityOperation } from './EntityOperation_ts'
 // import { EntityTest } from './EntityTest_ts'
 
@@ -15,6 +20,13 @@ const Entity = cmp(function Entity(props: any) {
   const { model, stdrep } = props.ctx$
   const { target, entity } = props
 
+  // Collision-free entity CLASS name (see entityClassName): normally
+  // `<Name>Entity`, disambiguated when it would clash with another entity's
+  // data-type name. The DATA type stays `<Name>`. The class file name and the
+  // Main import path both use this, so they always agree.
+  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const cls = entityClassName(entity, entityColl)
+
   const entrep = {
     ...stdrep,
   }
@@ -38,7 +50,7 @@ const Entity = cmp(function Entity(props: any) {
 
   Folder({ name: 'src/entity' }, () => {
 
-    File({ name: entity.Name + 'Entity.' + target.name }, () => {
+    File({ name: cls + '.' + target.name }, () => {
 
       const opnames = Object.keys(entity.op)
 
@@ -58,6 +70,10 @@ const Entity = cmp(function Entity(props: any) {
           SdkName: model.const.Name,
           EntityName: entity.Name,
 
+          // Class token decoupled from the EntityName data-type token in
+          // Entity.fragment.ts so the class can be renamed independently.
+          EntyClass: cls,
+
           '#TypeImports': ({ indent }: any) => Content({ indent }, typeImport),
 
           '#Feature-Hook': ({ name, indent }: any) =>

package/project/.sdk/src/cmp/ts/MainEntity_ts.ts

@@ -1,16 +1,26 @@
 
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
 
 
 const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
+  const { model } = props.ctx$
+
+  // Return the collision-free class TYPE (entityClassName); the accessor METHOD
+  // name (entity.Name) is unchanged so callers still write client.<Name>().
+  const cls = entityClassName(entity, getModelPath(model, `main.${KIT}.entity`))
 
   Content(`
   // Entity access: \`client.${entity.Name}().list()\` / \`client.${entity.Name}().load({ id })\`.
   ${entity.Name}(data?: any) {
     const self = this
-    return new ${entity.Name}Entity(self,data)
+    return new ${cls}(self,data)
   }
 
 `)

package/project/.sdk/src/cmp/ts/Main_ts.ts

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+  entityClassName,
 } from '@voxgig/sdkgen'
 
 
@@ -55,8 +56,10 @@ const Main = cmp(async function Main(props: any) {
 
       Line(`// ${model.const.Name} ${target.Name} SDK\n`)
 
-      List({ item: entity }, ({ item }: any) =>
-        Line(`import { ${item.Name}Entity } from './entity/${item.Name}Entity'`))
+      List({ item: entity }, ({ item }: any) => {
+        const cls = entityClassName(item, entity)
+        return Line(`import { ${cls} } from './entity/${cls}'`)
+      })
 
       // Re-export the generated typed models so consumers can
       // `import { Advice, AdviceLoadMatch } from '<pkg>'`.

package/project/.sdk/src/cmp/ts/ReadmeEntity_ts.ts

@@ -131,10 +131,10 @@ const ${eVar}s = await client.${entity.Name}().list()
     }
 
     if (opnames.includes('create')) {
-      // Members come from the SAME shape that generates <Name>CreateData:
-      // every required member must appear (the /* type */ placeholders also
-      // mark the block as an illustration for the doc gates); an
-      // all-optional create renders an empty — still assignable — literal.
+      // Members come from the SAME shape that generates <Name>CreateData
+      // (every required member appears), with a type-correct example VALUE
+      // via exampleValue — a `name: /* type */` comment is not a value and
+      // yields invalid TS (TS1109), so the example must carry a real literal.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -143,7 +143,7 @@ const ${eVar}s = await client.${entity.Name}().list()
 const ${eVar} = await client.${entity.Name}().create({
 `)
       createItems.map((it: any) => {
-        Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
+        Content(`  ${it.name}: ${exampleValue(entity, entity.op && entity.op.create, it.name, 'example_' + it.name)},
 `)
       })
       Content(`})

package/project/.sdk/src/cmp/ts/ReadmeHowto_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,15 +14,15 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const exampleEntity = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`. primaryOp is null
+  // only when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
   const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
   // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
   const eVar = safeVarName(eName.toLowerCase(), 'ts')
 
-  // Drive the test-mode / stateful examples off the entity's PRIMARY op — an op
-  // it actually exposes — never a hardcoded `load` a create-only entity lacks.
-  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
-  const primaryOpDef = exampleEntity && exampleEntity.op && exampleEntity.op[primaryOp]
+  const primaryOpDef = exampleEntity && primaryOp && exampleEntity.op && exampleEntity.op[primaryOp]
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   // Model-driven id key: `idF` is the entity's id-like MATCH field name, or null
   // when it has none. `dataIdF` is the id on the RETURNED record's data type —
@@ -32,7 +32,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
 
   // A type-correct, language-idiomatic argument for the primary op call.
   const primaryArg = (idPlaceholder: string): string => {
-    if (!exampleEntity) return ''
+    if (!exampleEntity || !primaryOp) return ''
     if ('list' === primaryOp) return ''
     if (isMatchOp) {
       return idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, idPlaceholder)} }` : ''
@@ -53,6 +53,33 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     ? `console.log(data.${dataIdF})`
     : `console.log(data)`
 
+  // The op-driven example lines, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() test call instead.
+  const testModeExample = primaryOp
+    ? `const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
+// ${eVar} is a bare entity populated with mock response data
+console.log(${eVar})`
+    : `const result = await client.direct({ path: '/api/resource', method: 'GET' })
+console.log(result)`
+  const stateSection = primaryOp
+    ? `### Retain entity state across calls
+
+Entity instances remember their last match and data:
+
+\`\`\`ts
+const entity = client.${eName}()
+
+// First call runs the operation and stores its result
+await entity.${primaryOp}(${stateCallArg})
+
+// Subsequent calls reuse the stored state
+const data = entity.data()
+${stateDataLine}
+\`\`\`
+
+`
+    : ''
+
   const authActive = isAuthActive(model)
   const apikeyTesterCtor = authActive
     ? `new ${model.const.Name}SDK({ apikey: '...' })`
@@ -102,9 +129,7 @@ Create a mock client for unit testing \u2014 no server required:
 \`\`\`ts
 const client = ${model.const.Name}SDK.test()
 
-const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
-// ${eVar} is a bare entity populated with mock response data
-console.log(${eVar})
+${testModeExample}
 \`\`\`
 
 You can also use the instance method:
@@ -114,22 +139,7 @@ const client = ${apikeyTesterCtor}
 const testClient = client.tester()
 \`\`\`
 
-### Retain entity state across calls
-
-Entity instances remember their last match and data:
-
-\`\`\`ts
-const entity = client.${eName}()
-
-// First call runs the operation and stores its result
-await entity.${primaryOp}(${stateCallArg})
-
-// Subsequent calls reuse the stored state
-const data = entity.data()
-${stateDataLine}
-\`\`\`
-
-### Add custom middleware
+${stateSection}### Add custom middleware
 
 Pass features via the \`extend\` option:
 

package/project/.sdk/src/cmp/ts/ReadmeRef_ts.ts

@@ -299,17 +299,16 @@ const results = await client.${ent.Name}().${opname}()
           }
           else if ('create' === opname) {
             // Members come from the SAME shape that generates
-            // <Name>CreateData: every required member must appear (the
-            // /* type */ placeholders also mark the block as an illustration
-            // for the doc gates); an all-optional create renders an empty —
-            // still assignable — literal.
+            // <Name>CreateData (every required member appears), each with a
+            // type-correct example VALUE via exampleValue — a `name: /* type */`
+            // comment is not a value and yields invalid TS (TS1109).
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`ts
 const result = await client.${ent.Name}().create({
 `)
             createItems.map((it: any) => {
-              Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
+              Content(`  ${it.name}: ${exampleValue(ent, ent.op && ent.op.create, it.name, 'example_' + it.name)},
 `)
             })
             Content(`})

package/project/.sdk/src/cmp/ts/ReadmeTopTest_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,17 +14,16 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity like Cloudsmith's `Abort`.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
 
   Content(`\`\`\`ts
 const client = ${model.const.Name}SDK.test()
 `)
 
-  if (exampleEntity) {
+  if (exampleEntity && primaryOp) {
     const eName = nom(exampleEntity, 'Name')
-    // 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'
     // A list() result is an array — name the variable accordingly.
     const eVar = safeVarName(eName.toLowerCase(), 'ts') +
       ('list' === primaryOp ? 's' : '')

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

@@ -18,7 +18,7 @@ import type {
 
 
 // TODO: needs Entity superclass
-class EntityNameEntity extends ProjectNameEntityBase<EntityName> {
+class EntyClass extends ProjectNameEntityBase<EntityName> {
 
   constructor(client: ProjectNameSDK, entopts: any) {
     super(client, entopts)
@@ -28,8 +28,8 @@ class EntityNameEntity extends ProjectNameEntityBase<EntityName> {
   }
 
 
-  make(this: EntityNameEntity) {
-    return new EntityNameEntity(this._client, this.entopts())
+  make(this: EntyClass) {
+    return new EntyClass(this._client, this.entopts())
   }
 
 
@@ -47,5 +47,5 @@ class EntityNameEntity extends ProjectNameEntityBase<EntityName> {
 
 
 export {
-  EntityNameEntity
+  EntyClass
 }

package/src/cmp/ReadmeErrors.ts

@@ -6,7 +6,7 @@ import {
   getModelPath
 } from '../types'
 
-import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { entityIdField, pickExampleEntity } from '../helpers/opShape'
 import { primaryOpCall } from '../helpers/opExample'
 import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
 import { safeVarName } from '../helpers/naming'
@@ -224,29 +224,28 @@ const ReadmeErrors = cmp(function ReadmeErrors(props: any) {
 
   const lang = LANGS[target.name] || DEFAULT_LANG
 
-  // Derive a real example entity from the model (the same way the sibling
-  // Readme components do) so the snippet never references a phantom entity.
+  // Pick a real example entity WITH a real op (prefer a read op) so the
+  // error-handling snippet never references a phantom entity or fabricates a
+  // `.load()` on an op-less one (e.g. Cloudsmith's `Abort`). primaryOp is null
+  // only when NO entity exposes any op — then the entity example is skipped
+  // and only the direct() error handling (which every SDK has) is shown.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
-  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
-  // Sanitise the variable name against the target's reserved words (a `Delete`
-  // entity must not bind `const delete = ...`).
-  const eLower = safeVarName(eName.toLowerCase(), target.name)
-
-  // The entity's id-like key field name, or null when it has none.
-  const idF = entityIdField(ex)
-  // The entity's PRIMARY op — an op it actually exposes (prefer list/load, else
-  // create/update/remove). A create-only entity therefore never shows a
-  // phantom `.load()`.
-  const primaryOp = entityPrimaryOp(ex) || 'load'
-  const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+  const { entity: ex, primaryOp } = pickExampleEntity(entity || {})
 
   Content(`
 ## Error handling
 
 `)
 
-  Content(lang.entity(call, primaryOp))
+  if (ex && primaryOp) {
+    const eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
+    // Sanitise the variable name against the target's reserved words (a
+    // `Delete` entity must not bind `const delete = ...`).
+    const eLower = safeVarName(eName.toLowerCase(), target.name)
+    const idF = entityIdField(ex)
+    const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+    Content(lang.entity(call, primaryOp))
+  }
 
   Content(lang.direct)
 })

package/src/cmp/ReadmeExplanation.ts

@@ -8,7 +8,7 @@ import {
 
 import { requirePath } from '../utility'
 
-import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { entityIdField, pickExampleEntity } from '../helpers/opShape'
 import { idLiteral, matchArg, dataArg } from '../helpers/opExample'
 import type { ExampleLang } from '../helpers/opExample'
 import { safeVarName } from '../helpers/naming'
@@ -225,39 +225,40 @@ const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
   const feature = getModelPath(model, `main.${KIT}.feature`)
   const lang = LANGS[target.name] || DEFAULT_LANG
 
-  // Derive a real example entity from the model (the same way the sibling
-  // Readme components do) so the entity-state example never references a
-  // phantom entity.
+  // Pick a real example entity WITH a real op (prefer a read op) so the
+  // entity-state example never references a phantom entity or fabricates a
+  // `.load()` on an op-less one (e.g. Cloudsmith's `Abort`). primaryOp is null
+  // only when NO entity exposes any op — then the entity-state section is
+  // skipped (a direct()-only SDK has no entity op to illustrate).
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
-  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
-  // Sanitise against the target's reserved words (a `Delete` entity must not
-  // bind `const delete = ...`).
-  const eLower = safeVarName(eName.toLowerCase(), target.name)
+  const { entity: ex, primaryOp } = pickExampleEntity(entity || {})
   const lname = target.name as ExampleLang
-  // The entity's id-like key field name, or null when it has none (a
-  // response-wrapped spec can model an entity with no id). Drives whether the
-  // state example keys on an id at all.
-  const idF = entityIdField(ex)
-  // The entity's PRIMARY op — an op it actually exposes (never a hardcoded
-  // `load` a create-only entity lacks).
-  const primaryOp = entityPrimaryOp(ex) || 'load'
-  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
-  // Type-correct example id literal (numeric when the id param is integer-typed),
-  // derived from the OP's param type so an id carried only in the match compiles.
-  const idLit = idLiteral(ex, primaryOp, idF)
-  // Language-correct call argument for the primary op: a match for load/remove,
-  // a required-field body for create/update, nothing for list.
-  let stateArg: string
-  if ('list' === primaryOp) {
-    stateArg = 'go' === target.name ? 'nil' : ''
-  } else if (isMatchOp) {
-    stateArg = matchArg(lname, idF, idLit)
-  } else {
-    stateArg = dataArg(lname, ex, primaryOp, idF)
+  const hasEntityExample = !!(ex && primaryOp)
+
+  let eName = 'Entity', eLower = 'entity', stateArg = '', matchIdF: string | null = null, idLit = ''
+  if (hasEntityExample) {
+    eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
+    // Sanitise against the target's reserved words (a `Delete` entity must
+    // not bind `const delete = ...`).
+    eLower = safeVarName(eName.toLowerCase(), target.name)
+    const idF = entityIdField(ex)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    // Type-correct example id literal (numeric when the id param is integer-
+    // typed), derived from the OP's param type so an id carried only in the
+    // match compiles.
+    idLit = idLiteral(ex, primaryOp as string, idF)
+    // Language-correct call argument for the primary op: a match for
+    // load/remove, a required-field body for create/update, nothing for list.
+    if ('list' === primaryOp) {
+      stateArg = 'go' === target.name ? 'nil' : ''
+    } else if (isMatchOp) {
+      stateArg = matchArg(lname, idF, idLit)
+    } else {
+      stateArg = dataArg(lname, ex, primaryOp as string, idF)
+    }
+    // Only a match op keys the `.match()` comment on `{ id: ... }`.
+    matchIdF = isMatchOp ? idF : null
   }
-  // Only a match op keys the `.match()` comment on `{ id: ... }`.
-  const matchIdF = isMatchOp ? idF : null
 
   Content(`
 ## Advanced
@@ -327,12 +328,13 @@ were added, so later features can override earlier ones.
   }
 
 
-  // Entity state
-  Content(`### Entity state
+  // Entity state — only when the SDK actually has an entity op to show.
+  if (hasEntityExample) {
+    Content(`### Entity state
 
 `)
-
-  Content(lang.entityState(eName, eLower, primaryOp, stateArg, matchIdF, idLit))
+    Content(lang.entityState(eName, eLower, primaryOp as string, stateArg, matchIdF, idLit))
+  }
 
 
   // Direct vs entity access

package/src/helpers/naming.ts

@@ -11,8 +11,11 @@
 // words a `const` binding trips on). Go lists its 25 keywords — a var named
 // `type`/`func`/`range` fails `go build`; Go builtins like `delete`/`len` are
 // NOT keywords and are legal identifiers, so they are intentionally omitted.
-// py/php/rb/lua rarely collide on a lowercased entity name and are not treated
-// here (add a set if a real collision surfaces).
+// rb/py/lua list the keywords that are illegal as a local-variable binding
+// (e.g. a `Self` entity -> `self = client.Self` is a Ruby SyntaxError, an
+// `End` entity -> `end = ...` a Lua one). PHP variables are `$`-prefixed so a
+// lowercased entity name never collides (only `$this` is special, and no
+// entity is named `this`), so PHP is not treated.
 
 const JS_RESERVED = new Set<string>([
   'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
@@ -32,10 +35,37 @@ const GO_RESERVED = new Set<string>([
   'var',
 ])
 
+// Ruby keywords — illegal as a local-variable name (e.g. `self`, `end`).
+const RB_RESERVED = new Set<string>([
+  'alias', 'and', 'begin', 'break', 'case', 'class', 'def', 'defined?',
+  'do', 'else', 'elsif', 'end', 'ensure', 'false', 'for', 'if', 'in',
+  'module', 'next', 'nil', 'not', 'or', 'redo', 'rescue', 'retry', 'return',
+  'self', 'super', 'then', 'true', 'undef', 'unless', 'until', 'when',
+  'while', 'yield', '__FILE__', '__LINE__', '__ENCODING__', 'BEGIN', 'END',
+])
+
+// Python keywords — illegal as a variable name.
+const PY_RESERVED = new Set<string>([
+  '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',
+])
+
+// Lua keywords — illegal as a variable name. (`self` is NOT reserved in Lua.)
+const LUA_RESERVED = new Set<string>([
+  'and', 'break', 'do', 'else', 'elseif', 'end', 'false', 'for', 'function',
+  'goto', 'if', 'in', 'local', 'nil', 'not', 'or', 'repeat', 'return',
+  'then', 'true', 'until', 'while',
+])
+
 const RESERVED: Record<string, Set<string>> = {
   ts: JS_RESERVED,
   js: JS_RESERVED,
   go: GO_RESERVED,
+  rb: RB_RESERVED,
+  py: PY_RESERVED,
+  lua: LUA_RESERVED,
 }