@voxgig/sdkgen 1.3.2 → 1.3.5

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -56,6 +56,9 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     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 — an entity whose lowercased name is a
+    // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code.
+    const eVar = safeVarName(entity.name, 'rb')
 
     Content(`
 ### ${entity.Name}
@@ -68,7 +71,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`${entity.name} = client.${entity.Name}\`
+    Content(`Create an instance: \`${eVar} = client.${entity.Name}\`
 
 `)
 
@@ -124,7 +127,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
 \`\`\`ruby
 # load returns the bare ${entity.Name} record (raises on error).
-${entity.name} = client.${entity.Name}.load(${loadArg})
+${eVar} = client.${entity.Name}.load(${loadArg})
 \`\`\`
 
 `)
@@ -135,7 +138,7 @@ ${entity.name} = client.${entity.Name}.load(${loadArg})
 
 \`\`\`ruby
 # list returns an Array of ${entity.Name} records (raises on error).
-${entity.name}s = client.${entity.Name}.list
+${eVar}s = client.${entity.Name}.list
 \`\`\`
 
 `)
@@ -152,7 +155,7 @@ ${entity.name}s = client.${entity.Name}.list
       Content(`#### Example: Create
 
 \`\`\`ruby
-${entity.name} = client.${entity.Name}.create({
+${eVar} = client.${entity.Name}.create({
 `)
       createItems.map((it: any) => {
         Content(`  "${it.name}" => ${rbLit(it.type, 'example_' + it.name)}, # ${canonToType(it.type, target.name)}

package/project/.sdk/src/cmp/rb/ReadmeHowto_rb.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, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -23,15 +23,20 @@ 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'
+  // Sanitise the local variable name — an entity whose lowercased name is a
+  // Ruby keyword (e.g. `self`) would otherwise emit uncompilable code. The
+  // fixture KEY (`"${eName.toLowerCase()}"`) stays raw — it must match the
+  // entity's registered name for the mock lookup to resolve.
+  const eVar = safeVarName(eName.toLowerCase(), 'rb')
   // Model-driven id key: null when the entity has no id-like field (a
   // response-wrapped spec). When null the fixture seeds no id and a match op
   // takes no argument.
   const idF = exampleEntity ? entityIdField(exampleEntity) : null
-  // Drive the test-mode example 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 isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   const seedSentence = idF
     ? '. Seed fixture\ndata via the `entity` option so offline calls resolve without a live server'
@@ -52,6 +57,15 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testCallArg = `{ ${chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type)}`).join(', ')} }`
   }
 
+  // The op-driven test-mode line, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
+  const testModeExample = primaryOp
+    ? `# Entity ops return the bare mock record (raises on error).
+${eVar} = client.${eName}.${primaryOp}(${testCallArg})
+puts ${eVar}`
+    : `result = client.direct({ "path" => "/api/resource", "method" => "GET" })
+puts result`
+
   const apikeyEnvLine = isAuthActive(model)
     ? `\n${envName(model)}_APIKEY=<your-key>`
     : ''
@@ -101,9 +115,7 @@ Create a mock client for unit testing — no server required${seedSentence}:
 \`\`\`ruby
 client = ${testCtor}
 
-# Entity ops return the bare mock record (raises on error).
-${eName.toLowerCase()} = client.${eName}.${primaryOp}(${testCallArg})
-puts ${eName.toLowerCase()}
+${testModeExample}
 \`\`\`
 
 ### Use a custom fetch function

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -43,6 +43,9 @@ client = ${ctor}
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const article = /^[aeiou]/i.test(eName) ? "an" : "a"
+    // 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 = entityOps(exampleEntity)
     // Model-driven id keys: `idF` is the load-MATCH key (null when the entity
     // has no id-like field — a response-wrapped spec); when null, load/remove
@@ -84,8 +87,8 @@ client = ${ctor}
 \`\`\`ruby
 begin
   # list returns an Array of ${eName} records — iterate directly.
-  ${eName.toLowerCase()}s = client.${eName}.list
-  ${eName.toLowerCase()}s.each do |item|
+  ${eVar}s = client.${eName}.list
+  ${eVar}s.each do |item|
     puts "${itemPrint}"
   end
 rescue => err
@@ -99,7 +102,7 @@ end
     if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
       const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
-      const neVar = neName.toLowerCase()
+      const neVar = safeVarName(neName.toLowerCase(), 'rb')
 
       // Model-driven match: every REQUIRED load-match key — the same shape
       // the runtime resolves path params from, so the example always works.
@@ -151,8 +154,8 @@ end
 \`\`\`ruby
 begin
   # load returns the bare ${eName} record (raises on error).
-  ${eName.toLowerCase()} = client.${eName}.load(${loadArg})
-  puts ${eName.toLowerCase()}
+  ${eVar} = client.${eName}.load(${loadArg})
+  puts ${eVar}
 rescue => err
   warn "load failed: #{err}"
 end

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/project/.sdk/tm/go/utility/prepare_auth.go

@@ -47,7 +47,12 @@ func prepareAuthUtil(ctx *core.Context) (*core.Spec, error) {
 		if av, ok := apikey.(string); ok {
 			apikeyVal = av
 		}
-		headers[headerAuth] = authPrefix + " " + apikeyVal
+		// Empty prefix (raw apiKey credential) must not add a leading space.
+		if authPrefix == "" {
+			headers[headerAuth] = apikeyVal
+		} else {
+			headers[headerAuth] = authPrefix + " " + apikeyVal
+		}
 	}
 
 	return spec, nil

package/project/.sdk/tm/js/src/utility/PrepareAuthUtility.js

@@ -36,7 +36,9 @@ function prepareAuth(ctx) {
     delprop(headers, HEADER_auth)
   }
   else {
-    setprop(headers, HEADER_auth, options.auth.prefix + ' ' + apikey)
+    // Empty prefix (raw apiKey credential) must not add a leading space.
+    setprop(headers, HEADER_auth,
+      options.auth.prefix ? options.auth.prefix + ' ' + apikey : apikey)
   }
 
   return spec

package/project/.sdk/tm/lua/utility/prepare_auth.lua

@@ -38,7 +38,12 @@ local function prepare_auth_util(ctx)
     if type(apikey) == "string" then
       apikey_val = apikey
     end
-    headers[HEADER_AUTH] = auth_prefix .. " " .. apikey_val
+    -- Empty prefix (raw apiKey credential) must not add a leading space.
+    if auth_prefix == "" then
+      headers[HEADER_AUTH] = apikey_val
+    else
+      headers[HEADER_AUTH] = auth_prefix .. " " .. apikey_val
+    end
   end
 
   return spec, nil

package/project/.sdk/tm/php/utility/PrepareAuth.php

@@ -35,7 +35,9 @@ class ProjectNamePrepareAuth
         } else {
             $auth_prefix = \Voxgig\Struct\Struct::getpath($options, 'auth.prefix') ?? '';
             $apikey_val = is_string($apikey) ? $apikey : '';
-            $headers[self::HEADER_AUTH] = "{$auth_prefix} {$apikey_val}";
+            // Empty prefix (raw apiKey credential) must not add a leading space.
+            $headers[self::HEADER_AUTH] = $auth_prefix === ''
+                ? $apikey_val : "{$auth_prefix} {$apikey_val}";
         }
 
         return [$spec, null];