@voxgig/sdkgen 1.3.2 → 1.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "1.3.2",
+  "version": "1.3.5",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "types": "dist/sdkgen.d.ts",

package/project/.sdk/src/cmp/go/EntityOperation_go.ts

@@ -10,7 +10,7 @@ import { formatGoMap } from './utility_go'
 
 const EntityOperation = cmp(function Operation(props: any) {
   const { model } = props.ctx$
-  const { ff, opname, entity, entrep, gomodule } = props
+  const { ff, opname, entity, entrep, gomodule, cls } = props
 
   let { indent } = props
 
@@ -34,6 +34,13 @@ const EntityOperation = cmp(function Operation(props: any) {
       ProjectName: model.const.Name,
       EntityName: entity.Name,
       entityname: entity.name,
+
+      // Class receiver tokens are decoupled from the EntityName data-type token
+      // in the Entity<Op>Op.fragment.go files (receiver -> cls; the per-op
+      // EntityName<Op>Match/Data data types stay derived from EntityName).
+      EntyClass: cls,
+      NewEntyClass: 'New' + cls,
+
       '#Feature-Hook': ({ name, indent }: any) =>
         Content({ indent }, `
 u.FeatureHook(ctx, "${name}")

package/project/.sdk/src/cmp/go/Entity_go.ts

@@ -3,9 +3,15 @@ import * as Path from 'node:path'
 
 import {
   cmp, each, camelify, names,
-  File, Content, Folder, Fragment, Line, FeatureHook, Slot
+  File, Content, Folder, Fragment, Line, FeatureHook, Slot,
+  entityClassName,
 } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
 import { EntityOperation } from './EntityOperation_go'
 
 
@@ -17,6 +23,12 @@ const Entity = cmp(function Entity(props: any) {
   // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
+  // Collision-free entity CLASS name (see entityClassName): normally
+  // `<Name>Entity`, but disambiguated (e.g. `<Name>EntityClient`) when it would
+  // clash with another entity's data-type name. The DATA type stays `<Name>`.
+  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const cls = entityClassName(entity, entityColl)
+
   const entrep = {
     ...stdrep,
   }
@@ -43,13 +55,13 @@ const Entity = cmp(function Entity(props: any) {
             !opnames.includes(opname) ?
               ({ indent }: any) => {
                 const Method = camelify(opname)
-                Content({ indent }, `func (e *${entity.Name}Entity) ${Method}(_ map[string]any, _ map[string]any) (any, error) {
+                Content({ indent }, `func (e *${cls}) ${Method}(_ map[string]any, _ map[string]any) (any, error) {
 	return core.UnsupportedOp("${opname}", e.name)
 }
 `)
               } :
               ({ indent }: any) => {
-                EntityOperation({ ff, opname, indent, entity, entrep, gomodule })
+                EntityOperation({ ff, opname, indent, entity, entrep, gomodule, cls })
               }, a), {}))
 
       Fragment({
@@ -62,6 +74,11 @@ const Entity = cmp(function Entity(props: any) {
           EntityName: entity.Name,
           entityname: entity.name,
 
+          // Class/constructor tokens are decoupled from the EntityName data-type
+          // token in Entity.fragment.go so the class can be renamed independently.
+          EntyClass: cls,
+          NewEntyClass: 'New' + cls,
+
           '#Entity-Hook': ({ name, indent }: any) =>
             Content({ indent }, `utility.FeatureHook(ctx, "${name}")`),
 

package/project/.sdk/src/cmp/go/Main_go.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'
 
 
@@ -187,7 +188,7 @@ func init() {
     // Register entity constructors
     each(entity, (ent: any) => {
       Content(`	core.New${ent.Name}EntityFunc = func(client *core.${model.const.Name}SDK, entopts map[string]any) core.${model.const.Name}Entity {
-		return entity.New${ent.Name}Entity(client, entopts)
+		return entity.New${entityClassName(ent, entity)}(client, entopts)
 	}
 `)
     })

package/project/.sdk/src/cmp/go/ReadmeEntity_go.ts

@@ -143,10 +143,10 @@ fmt.Println(${eVar}s) // the array of records
 
     if (opnames.includes('create')) {
       // Members come from the SAME shape that generates the op's request
-      // data: every required member must appear — including a required id
-      // (the /* type */ placeholders also mark the block as an illustration
-      // for the doc gates); an all-optional create renders an empty — still
-      // valid — literal, and the compiled example is self-consuming.
+      // data (every required member appears, including a required id), each
+      // with a type-correct example VALUE via exampleValue — a
+      // `"name": /* type */` comment is not a value and yields uncompilable
+      // Go, so the example must carry a real literal.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -155,7 +155,7 @@ fmt.Println(${eVar}s) // the array of records
 result, err := client.${entity.Name}(nil).Create(map[string]any{
 `)
       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(`}, nil)

package/project/.sdk/src/cmp/go/ReadmeHowto_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -32,16 +32,16 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
   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'
   // camelCase Go identifier (never snake_case or flattened lowercase,
   // never a Go keyword).
   const eLower = exampleEntity ? goVarName(exampleEntity.name) : 'entity'
   // Model-driven id key: null when the entity has no id-like field.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
-  // Drive the test-mode example off the entity's PRIMARY op — never a hardcoded
-  // `Load` a create-only entity lacks.
-  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'nil'
   if (exampleEntity && isMatchOp) {
@@ -54,6 +54,23 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testArg = `map[string]any{${chosen.map((it: any) => `"${it.name}": ${goLit(it.type)}`).join(', ')}}`
   }
 
+  // The op-driven test-mode block, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a Direct() call instead — never
+  // a fabricated method (`cap(primaryOp)` would also fail on a null op).
+  const testModeExample = primaryOp
+    ? `${eLower}, err := client.${eName}(nil).${cap(primaryOp)}(
+    ${testArg}, nil,
+)
+if err != nil {
+    panic(err)
+}
+fmt.Println(${eLower}) // the returned mock data`
+    : `result, err := client.Direct(map[string]any{"path": "/api/resource", "method": "GET"})
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)`
+
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
@@ -102,13 +119,7 @@ Create a mock client for unit testing \u2014 no server required:
 \`\`\`go
 client := sdk.Test()
 
-${eLower}, err := client.${eName}(nil).${cap(primaryOp)}(
-    ${testArg}, nil,
-)
-if err != nil {
-    panic(err)
-}
-fmt.Println(${eLower}) // the returned mock data
+${testModeExample}
 \`\`\`
 
 ### Use a custom fetch function

package/project/.sdk/src/cmp/go/ReadmeModel_go.ts

@@ -50,23 +50,41 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     ? '| `"apikey"` | `string` | API key for authentication. |\n'
     : ''
 
-  // First published entity name, for the Result shape illustration.
-  const firstEntityName = (entityList[0] as any)?.Name || 'Entity'
+  // Illustrate the Result shape with the first entity that ACTUALLY exposes an
+  // op — never fabricate a `Load` on an op-less first entity (e.g. Cloudsmith's
+  // `Abort`). firstPrimaryOp is null only when NO active entity has any op (a
+  // direct()-only SDK), in which case the call illustration is omitted.
+  const firstWithOp = entityList.find((e: any) => entityPrimaryOp(e) != null)
+  const firstPrimaryOp = firstWithOp ? entityPrimaryOp(firstWithOp) : null
+  const firstEntityName = firstWithOp ? ((firstWithOp as any).Name || 'Entity') : 'Entity'
   // camelCase Go identifier (never snake_case or flattened lowercase,
   // never a Go keyword).
-  const firstEntityVar = goVarName((entityList[0] as any)?.name || 'entity')
+  const firstEntityVar = goVarName((firstWithOp as any)?.name || 'entity')
   // Model-driven id key: null when the example entity has no id-like field, so
   // the Result-shape illustration passes a nil match.
-  const firstIdF = entityIdField(entityList[0] || {})
-  // The example entity's PRIMARY op — an op it actually exposes (never a
-  // hardcoded `Load` a create-only entity lacks).
-  const firstPrimaryOp = entityList[0] ? (entityPrimaryOp(entityList[0]) || 'load') : 'load'
-  const firstPrimaryMethod = firstPrimaryOp.charAt(0).toUpperCase() + firstPrimaryOp.slice(1)
+  const firstIdF = firstWithOp ? entityIdField(firstWithOp) : null
+  const firstPrimaryMethod = firstPrimaryOp
+    ? firstPrimaryOp.charAt(0).toUpperCase() + firstPrimaryOp.slice(1)
+    : ''
   const firstIsMatchOp = 'load' === firstPrimaryOp || 'remove' === firstPrimaryOp
   const firstOpArg = firstIsMatchOp
     ? (firstIdF ? `map[string]any{"${firstIdF}": "example_id"}` : 'nil')
     : 'map[string]any{/* fields */}'
 
+  // The Result-shape call illustration, shown only when some entity exposes an
+  // op. A direct()-only SDK (no entity ops) omits it — there is no op to call.
+  const resultCallExample = firstPrimaryOp
+    ? `Check \`err\` first, then use the value directly (or the typed
+\`...Typed\` variants, which return the entity's model struct and a typed
+slice):
+
+    ${firstEntityVar}, err := client.${firstEntityName}(nil).${firstPrimaryMethod}(${firstOpArg}, nil)
+    if err != nil { /* handle */ }
+    // ${firstEntityVar} is the returned record
+
+`
+    : ''
+
   Content(`### New${model.const.Name}SDK
 
 \`\`\`go
@@ -130,15 +148,7 @@ operation's data **directly** — there is no wrapper:
 | --- | --- |
 ${resultShapeRows}
 
-Check \`err\` first, then use the value directly (or the typed
-\`...Typed\` variants, which return the entity's model struct and a typed
-slice):
-
-    ${firstEntityVar}, err := client.${firstEntityName}(nil).${firstPrimaryMethod}(${firstOpArg}, nil)
-    if err != nil { /* handle */ }
-    // ${firstEntityVar} is the returned record
-
-Only \`Direct()\` returns a response envelope — a \`map[string]any\` with
+${resultCallExample}Only \`Direct()\` returns a response envelope — a \`map[string]any\` with
 \`"ok"\`, \`"status"\`, \`"headers"\`, and \`"data"\` keys.
 
 `)

package/project/.sdk/src/cmp/go/ReadmeRef_go.ts

@@ -296,17 +296,17 @@ fmt.Println(results)
           }
           else if ('create' === opname) {
             // Members come from the SAME shape that generates the op's
-            // request data: every required member must appear — including a
-            // required id (the /* type */ placeholders also mark the block
-            // as an illustration for the doc gates); an all-optional create
-            // renders an empty — still valid — literal.
+            // request data (every required member appears, including a
+            // required id), each with a type-correct example VALUE via
+            // exampleValue — a `"name": /* type */` comment is not a value
+            // and yields uncompilable Go.
             const createItems = opRequestShape(ent, 'create').items
               .filter((it: any) => !it.optional)
             Content(`\`\`\`go
 result, err := client.${ent.Name}(nil).Create(map[string]any{
 `)
             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(`}, nil)

package/project/.sdk/src/cmp/go/ReadmeTopTest_go.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -30,18 +30,17 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   // Go module path == repo path on GitHub (org from model.origin).
   const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
-  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(`\`\`\`go
 client := 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 idF = entityIdField(exampleEntity)
-    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
     const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
     let arg = 'nil'
     if (isMatchOp) {

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

@@ -6,7 +6,7 @@ import (
 	vs "github.com/voxgig/struct"
 )
 
-type EntityNameEntity struct {
+type EntyClass struct {
 	name    string
 	client  *core.ProjectNameSDK
 	utility *core.Utility
@@ -16,7 +16,7 @@ type EntityNameEntity struct {
 	entctx  *core.Context
 }
 
-func NewEntityNameEntity(client *core.ProjectNameSDK, entopts map[string]any) *EntityNameEntity {
+func NewEntyClass(client *core.ProjectNameSDK, entopts map[string]any) *EntyClass {
 	if entopts == nil {
 		entopts = map[string]any{}
 	}
@@ -28,7 +28,7 @@ func NewEntityNameEntity(client *core.ProjectNameSDK, entopts map[string]any) *E
 		entopts["active"] = true
 	}
 
-	e := &EntityNameEntity{
+	e := &EntyClass{
 		name:    "entityname",
 		client:  client,
 		utility: client.GetUtility(),
@@ -47,17 +47,17 @@ func NewEntityNameEntity(client *core.ProjectNameSDK, entopts map[string]any) *E
 	return e
 }
 
-func (e *EntityNameEntity) GetName() string { return e.name }
+func (e *EntyClass) GetName() string { return e.name }
 
-func (e *EntityNameEntity) Make() core.Entity {
+func (e *EntyClass) Make() core.Entity {
 	opts := map[string]any{}
 	for k, v := range e.entopts {
 		opts[k] = v
 	}
-	return NewEntityNameEntity(e.client, opts)
+	return NewEntyClass(e.client, opts)
 }
 
-func (e *EntityNameEntity) Data(args ...any) any {
+func (e *EntyClass) Data(args ...any) any {
 	if len(args) > 0 && args[0] != nil {
 		e.data = core.ToMapAny(vs.Clone(args[0]))
 		if e.data == nil {
@@ -71,7 +71,7 @@ func (e *EntityNameEntity) Data(args ...any) any {
 	return out
 }
 
-func (e *EntityNameEntity) Match(args ...any) any {
+func (e *EntyClass) Match(args ...any) any {
 	if len(args) > 0 && args[0] != nil {
 		e.match = core.ToMapAny(vs.Clone(args[0]))
 		if e.match == nil {
@@ -89,7 +89,7 @@ func (e *EntityNameEntity) Match(args ...any) any {
 // argument it returns the current data as an EntityName; with an argument it
 // sets the data and returns the stored value. It delegates to the untyped Data
 // (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) DataTyped(data ...EntityName) EntityName {
+func (e *EntyClass) DataTyped(data ...EntityName) EntityName {
 	if len(data) > 0 {
 		return typedFrom[EntityName](e.Data(asMap(data[0])))
 	}
@@ -99,7 +99,7 @@ func (e *EntityNameEntity) DataTyped(data ...EntityName) EntityName {
 // MatchTyped mirrors DataTyped for the entity's match filter. The match is a
 // partial of the entity, so it round-trips through EntityName (all fields
 // optional at the wire level).
-func (e *EntityNameEntity) MatchTyped(match ...EntityName) EntityName {
+func (e *EntyClass) MatchTyped(match ...EntityName) EntityName {
 	if len(match) > 0 {
 		return typedFrom[EntityName](e.Match(asMap(match[0])))
 	}
@@ -116,7 +116,7 @@ func (e *EntityNameEntity) MatchTyped(match ...EntityName) EntityName {
 
 // #RemoveOp
 
-func (e *EntityNameEntity) runOp(ctx *core.Context, postDone func()) (any, error) {
+func (e *EntyClass) runOp(ctx *core.Context, postDone func()) (any, error) {
 	utility := e.utility
 
 	// #PrePoint-Hook

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

@@ -10,7 +10,7 @@ type entityCreateOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Create(reqdata map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Create(reqdata map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":  "create",
@@ -35,7 +35,7 @@ func (e *EntityNameEntity) Create(reqdata map[string]any, ctrl map[string]any) (
 // CreateTyped is the statically-typed variant of Create: it takes an
 // EntityNameCreateData and returns an EntityName. It delegates to the untyped
 // Create (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) CreateTyped(reqdata EntityNameCreateData, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) CreateTyped(reqdata EntityNameCreateData, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Create(asMap(reqdata), ctrl)
 	if err != nil {
 		return EntityName{}, err

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

@@ -4,7 +4,7 @@ type entityListOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) List(reqmatch map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) List(reqmatch map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":   "list",
@@ -26,7 +26,7 @@ func (e *EntityNameEntity) List(reqmatch map[string]any, ctrl map[string]any) (a
 // ListTyped is the statically-typed variant of List: it takes an
 // EntityNameListMatch and returns []EntityName. It delegates to the untyped
 // List (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) ListTyped(reqmatch EntityNameListMatch, ctrl map[string]any) ([]EntityName, error) {
+func (e *EntyClass) ListTyped(reqmatch EntityNameListMatch, ctrl map[string]any) ([]EntityName, error) {
 	res, err := e.List(asMap(reqmatch), ctrl)
 	if err != nil {
 		return nil, err

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

@@ -10,7 +10,7 @@ type entityLoadOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Load(reqmatch map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Load(reqmatch map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":   "load",
@@ -38,7 +38,7 @@ func (e *EntityNameEntity) Load(reqmatch map[string]any, ctrl map[string]any) (a
 // LoadTyped is the statically-typed variant of Load: it takes an
 // EntityNameLoadMatch and returns an EntityName. It delegates to the untyped
 // Load (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) LoadTyped(reqmatch EntityNameLoadMatch, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) LoadTyped(reqmatch EntityNameLoadMatch, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Load(asMap(reqmatch), ctrl)
 	if err != nil {
 		return EntityName{}, err

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

@@ -10,7 +10,7 @@ type entityRemoveOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Remove(reqmatch map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Remove(reqmatch map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":   "remove",
@@ -38,7 +38,7 @@ func (e *EntityNameEntity) Remove(reqmatch map[string]any, ctrl map[string]any)
 // RemoveTyped is the statically-typed variant of Remove: it takes an
 // EntityNameRemoveMatch and returns an EntityName. It delegates to the untyped
 // Remove (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) RemoveTyped(reqmatch EntityNameRemoveMatch, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) RemoveTyped(reqmatch EntityNameRemoveMatch, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Remove(asMap(reqmatch), ctrl)
 	if err != nil {
 		return EntityName{}, err

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

@@ -10,7 +10,7 @@ type entityUpdateOp struct{}
 
 // EJECT-START
 
-func (e *EntityNameEntity) Update(reqdata map[string]any, ctrl map[string]any) (any, error) {
+func (e *EntyClass) Update(reqdata map[string]any, ctrl map[string]any) (any, error) {
 	utility := e.utility
 	ctx := utility.MakeContext(map[string]any{
 		"opname":  "update",
@@ -38,7 +38,7 @@ func (e *EntityNameEntity) Update(reqdata map[string]any, ctrl map[string]any) (
 // UpdateTyped is the statically-typed variant of Update: it takes an
 // EntityNameUpdateData and returns an EntityName. It delegates to the untyped
 // Update (identical runtime) and converts at the typed boundary.
-func (e *EntityNameEntity) UpdateTyped(reqdata EntityNameUpdateData, ctrl map[string]any) (EntityName, error) {
+func (e *EntyClass) UpdateTyped(reqdata EntityNameUpdateData, ctrl map[string]any) (EntityName, error) {
 	res, err := e.Update(asMap(reqdata), ctrl)
 	if err != nil {
 		return EntityName{}, err

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

@@ -3,9 +3,15 @@ import * as Path from 'node:path'
 
 import {
   cmp, each, camelify, names,
-  File, Content, Folder, Fragment, Line, FeatureHook, Slot
+  File, Content, Folder, Fragment, Line, FeatureHook, Slot,
+  entityClassName,
 } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
 import { EntityOperation } from './EntityOperation_js'
 
 
@@ -13,6 +19,12 @@ 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 class file name and the Main require path both use this.
+  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const cls = entityClassName(entity, entityColl)
+
   const entrep = {
     ...stdrep,
   }
@@ -23,7 +35,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)
 
@@ -43,6 +55,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.js so the class can be renamed independently.
+          EntyClass: cls,
+
           '#Feature-Hook': ({ name, indent }: any) =>
             Content({ indent }, `
 fres = featureHook(ctx, '${name}')

package/project/.sdk/src/cmp/js/MainEntity_js.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 (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) {
     const self = this
-    return new ${entity.Name}Entity(self,data)
+    return new ${cls}(self,data)
   }
 
 `)

package/project/.sdk/src/cmp/js/Main_js.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(`const { ${item.Name}Entity } = require('./entity/${item.Name}Entity')`))
+      List({ item: entity }, ({ item }: any) => {
+        const cls = entityClassName(item, entity)
+        return Line(`const { ${cls} } = require('./entity/${cls}')`)
+      })
 
       Fragment(
         {

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

@@ -132,10 +132,10 @@ const ${eVar}s = await client.${entity.Name}().list()
 
     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 (the /* type */
-      // placeholders mark the block as an illustration); an all-optional
-      // create renders an empty — still valid — literal.
+      // (opRequestShape): every required member appears — including a
+      // required id and parent keys like page_id — each with a type-correct
+      // example VALUE via exampleValue — a `name: /* type */` comment is not
+      // a value and yields invalid code.
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create
@@ -144,7 +144,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(`})