@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue, goVarName } from './utility_go'
+
 
 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\` | \`map[string]any\` | 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"]\` | \`map[string]any\` | Custom headers for all requests. |
@@ -86,12 +87,20 @@ Create a new SDK client instance.
 
 `)
 
-    Content(`#### \`TestSDK(testopts, sdkopts map[string]any) *${model.const.Name}SDK\`
+    Content(`#### \`Test() *${model.const.Name}SDK\`
+
+No-arg convenience constructor for the common no-options test case.
+
+\`\`\`go
+client := sdk.Test()
+\`\`\`
+
+#### \`TestSDK(testopts, sdkopts map[string]any) *${model.const.Name}SDK\`
 
-Create a test client with mock features active. Both arguments may be \`nil\`.
+Test client with options. Both arguments may be \`nil\`.
 
 \`\`\`go
-client := sdk.TestSDK(nil, nil)
+client := sdk.TestSDK(testopts, sdkopts)
 \`\`\`
 
 `)
@@ -151,8 +160,16 @@ same parameters as \`Direct()\`.
 
     // Entity reference sections
     publishedEntities.map((ent: any) => {
-      const opnames = Object.keys(ent.op || {})
+      // ACTIVE ops only — an inactive op generates no method, so an example
+      // calling it would not compile.
+      const opnames = entityOps(ent)
       const fields = ent.fields || []
+      // Model-driven id key: null when this entity has no id-like field, in
+      // which case load/remove pass a nil match and update omits the id.
+      const idF = entityIdField(ent)
+      // camelCase Go identifier (a `status_embed_config` entity must not bind
+      // a snake_case Go variable).
+      const eVar = goVarName(ent.name)
 
       Content(`
 ---
@@ -168,7 +185,8 @@ same parameters as \`Direct()\`.
       }
 
       Content(`\`\`\`go
-${ent.name} := client.${ent.Name}(nil)
+${eVar} := client.${ent.Name}(nil)
+fmt.Println(${eVar}.GetName()) // "${ent.name}"
 \`\`\`
 
 `)
@@ -184,7 +202,7 @@ ${ent.name} := client.${ent.Name}(nil)
         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} |
 `)
         })
 
@@ -194,15 +212,19 @@ ${ent.name} := client.${ent.Name}(nil)
         // 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
+          // (opnames already carries active ops only).
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op))
           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 '-'
@@ -234,11 +256,29 @@ ${info.desc}
 
 `)
 
-          // Show example
+          // Show example. Every compiled example is self-consuming — check
+          // `err` and print the result — so the doc gate builds it without
+          // unused-variable repairs, and readers see the idiomatic pattern.
           if ('load' === opname || 'remove' === opname) {
             const goOpName = opname.charAt(0).toUpperCase() + opname.slice(1)
+            // The id key plus every REQUIRED match key (parent path params
+            // like page_id) — the same shape that generates the op's request
+            // match, so the example always carries the keys the route needs.
+            const matchItems = opRequestShape(ent, opname).items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const arg = 0 < matchItems.length
+              ? `map[string]any{${matchItems.map((it: any) =>
+                `"${it.name}": ${exampleValue(ent, ent.op && ent.op[opname], it.name,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')}}`
+              : 'nil'
             Content(`\`\`\`go
-result, err := client.${ent.Name}(nil).${goOpName}(map[string]any{"id": "${ent.name}_id"}, nil)
+result, err := client.${ent.Name}(nil).${goOpName}(${arg}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)
@@ -246,31 +286,57 @@ result, err := client.${ent.Name}(nil).${goOpName}(map[string]any{"id": "${ent.n
           else if ('list' === opname) {
             Content(`\`\`\`go
 results, err := client.${ent.Name}(nil).List(nil, nil)
+if err != nil {
+    panic(err)
+}
+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.
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`go
 result, err := client.${ent.Name}(nil).Create(map[string]any{
 `)
-            each(fields, (field: any) => {
-              if ('id' !== field.name && field.req) {
-                Content(`    "${field.name}": /* ${field.type || 'value'} */,
+            createItems.map((it: any) => {
+              Content(`    "${it.name}": /* ${canonToType(it.type, target.name)} */,
 `)
-              }
             })
             Content(`}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)
           }
           else if ('update' === opname) {
+            // The id key plus every REQUIRED data member — the same shape
+            // that generates the op's request data — then the patch-fields
+            // note.
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateLines = updateItems.map((it: any) =>
+              `    "${it.name}": ${exampleValue(ent, ent.op && ent.op.update, it.name,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`go
 result, err := client.${ent.Name}(nil).Update(map[string]any{
-    "id": "${ent.name}_id",
-    // Fields to update
+${updateLines}    // Fields to update
 }, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)

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

@@ -12,6 +12,10 @@ result, err := client.Direct(map[string]any{
     "method": "GET",
     "params": map[string]any{"id": "example"},
 })
+if err != nil {
+    panic(err)
+}
+fmt.Println(result)
 \`\`\`
 
 `)

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityOps, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,54 +7,113 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue, goVarName } from './utility_go'
+
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  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
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n    "apikey": os.Getenv("${model.NAME}_APIKEY"),\n`
-    : ''
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `sdk.New${model.const.Name}SDK(map[string]any{\n    "apikey": os.Getenv("${envName(model)}_APIKEY"),\n})`
+    : `sdk.New()`
 
   Content(`\`\`\`go
 import sdk "${gomodule}"
 
-client := sdk.New${model.const.Name}SDK(map[string]any{${apikeyArg}})
+client := ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const opnames = Object.keys(exampleEntity.op || {})
+    // camelCase Go identifier (never snake_case, never a Go keyword).
+    const eVar = goVarName(exampleEntity.name)
+    // ACTIVE ops only — an inactive op generates no method, so an example
+    // calling it would not compile.
+    const opnames = entityOps(exampleEntity)
+
+    let hasCall = false
 
     if (opnames.includes('list')) {
       Content(`// List all ${eName.toLowerCase()}s
-${eName.toLowerCase()}s, err := client.${eName}(nil).List(nil, nil)
+${eVar}s, err := client.${eName}(nil).List(nil, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(${eVar}s)
 `)
+      hasCall = true
     }
 
-    // Find a nested entity for a more interesting example
+    // Find a nested entity for a more interesting example: one with a parent
+    // chain (relations.ancestors), an active load op, and a required non-id
+    // load param to demonstrate (the parent key, e.g. page_id).
     const nestedEntity = Object.values(entity).find((e: any) =>
-      e.active !== false && e.ancestors && e.ancestors.length > 0
+      e.active !== false &&
+      e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+      entityOps(e).includes('load') &&
+      opRequestShape(e, 'load').items.some((it: any) =>
+        !it.optional && it.name !== entityIdField(e))
     ) as any
 
-    if (nestedEntity && opnames.includes('load')) {
+    if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
-      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 neVar = goVarName(nestedEntity.name)
+      // Model-driven match: every REQUIRED load-match key — the same shape
+      // that generates the op's request match, so the example always carries
+      // the keys the route needs. Parent keys (e.g. page_id) first, the
+      // entity's own id last, each value a type-correct Go literal.
+      const neIdF = entityIdField(nestedEntity)
+      const neLoadOp = nestedEntity.op && nestedEntity.op.load
+      const neMatchPairs = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+        .map((it: any) =>
+          `"${it.name}": ${exampleValue(nestedEntity, neLoadOp, it.name,
+            it.name === neIdF ? 'example_id' : 'example_' + it.name)}`)
 
       Content(`
 // Load a specific ${neName.toLowerCase()}
-${neName.toLowerCase()}, err := client.${neName}(nil).Load(
-    map[string]any{"${parentParam}": "example", "id": "example_id"}, nil,
+${neVar}, err := client.${neName}(nil).Load(
+    map[string]any{${neMatchPairs.join(', ')}}, nil,
 )
+if err != nil {
+    panic(err)
+}
+fmt.Println(${neVar})
+`)
+      hasCall = true
+    }
+
+    // Fallback: APIs with only `load` (no list, no nested) — still show one call.
+    if (!hasCall && opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first) — nil when there are none.
+      const idF = entityIdField(exampleEntity)
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `map[string]any{${loadItems.map((it: any) =>
+          `"${it.name}": ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, it.name,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
+        : 'nil'
+      Content(`// Load ${eName.toLowerCase()} data
+${eVar}, err := client.${eName}(nil).Load(${loadArg}, nil)
+if err != nil {
+    panic(err)
+}
+fmt.Println(${eVar})
 `)
+      hasCall = true
     }
   }
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,23 +8,53 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct Go literal for a field's canonical type.
+function goLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '[]any{}'
+  if ('OBJECT' === k) return 'map[string]any{}'
+  return '"example"'
+}
+
+function cap(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1)
+}
+
+
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  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
 
   Content(`\`\`\`go
-client := sdk.TestSDK(nil, nil)
+client := sdk.Test()
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`result, err := client.${eName}(nil).Load(
-    map[string]any{"id": "test01"}, nil,
+    // 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) {
+      arg = idF ? `map[string]any{"${idF}": "test01"}` : 'nil'
+    } 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 = `map[string]any{${chosen.map((it: any) => `"${it.name}": ${goLit(it.type)}`).join(', ')}}`
+    }
+    Content(`result, err := client.${eName}(nil).${cap(primaryOp)}(
+    ${arg}, nil,
 )
 `)
   }

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

@@ -107,7 +107,7 @@ import (
 	sdk "${gomodule}"
 	"${gomodule}/core"
 
-	vs "github.com/voxgig/struct"
+	vs "${gomodule}/utility/struct"
 )
 
 func Test${entity.Name}Entity(t *testing.T) {

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

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_go'
 import { TestDirect } from './TestDirect_go'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_go'
 
 
 const Test = cmp(function Test(props: any) {
@@ -21,7 +22,7 @@ const Test = cmp(function Test(props: any) {
 
   // Module name: concatenated lowercase
   // Go module path == repo path on GitHub (org from model.origin).
-  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk`
+  const gomodule = `github.com/${model.origin || 'voxgig-sdk'}/${model.name}-sdk/go`
 
   Folder({ name: 'test' }, () => {
 
@@ -51,6 +52,9 @@ func TestExists(t *testing.T) {
       TestEntity({ target, entity, gomodule })
       TestDirect({ target, entity, gomodule })
     })
+
+    // README ```go example snippets must compile against the real SDK.
+    ReadmeExamplesTest({ target })
   })
 })
 

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

@@ -85,6 +85,27 @@ func (e *EntityNameEntity) Match(args ...any) any {
 	return out
 }
 
+// DataTyped is the statically-typed accessor for this entity's data. With no
+// 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 {
+	if len(data) > 0 {
+		return typedFrom[EntityName](e.Data(asMap(data[0])))
+	}
+	return typedFrom[EntityName](e.Data())
+}
+
+// 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 {
+	if len(match) > 0 {
+		return typedFrom[EntityName](e.Match(asMap(match[0])))
+	}
+	return typedFrom[EntityName](e.Match())
+}
+
 // #LoadOp
 
 // #ListOp

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

@@ -32,4 +32,15 @@ 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) {
+	res, err := e.Create(asMap(reqdata), ctrl)
+	if err != nil {
+		return EntityName{}, err
+	}
+	return typedFrom[EntityName](res), nil
+}
+
 // EJECT-END

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

@@ -23,4 +23,15 @@ 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) {
+	res, err := e.List(asMap(reqmatch), ctrl)
+	if err != nil {
+		return nil, err
+	}
+	return typedSliceFrom[EntityName](res), nil
+}
+
 // EJECT-END

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

@@ -35,4 +35,15 @@ 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) {
+	res, err := e.Load(asMap(reqmatch), ctrl)
+	if err != nil {
+		return EntityName{}, err
+	}
+	return typedFrom[EntityName](res), nil
+}
+
 // EJECT-END

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

@@ -35,4 +35,15 @@ 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) {
+	res, err := e.Remove(asMap(reqmatch), ctrl)
+	if err != nil {
+		return EntityName{}, err
+	}
+	return typedFrom[EntityName](res), nil
+}
+
 // EJECT-END

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

@@ -35,4 +35,15 @@ 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) {
+	res, err := e.Update(asMap(reqdata), ctrl)
+	if err != nil {
+		return EntityName{}, err
+	}
+	return typedFrom[EntityName](res), nil
+}
+
 // EJECT-END

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

@@ -2,6 +2,13 @@
 import * as Path from 'node:path'
 
 
+import {
+  camelify,
+  canonKey,
+  each,
+  safeVarName,
+} from '@voxgig/sdkgen'
+
 import {
   clone,
   walk,
@@ -13,6 +20,67 @@ function projectPath(suffix?: string): string {
 }
 
 
+// --- Model-driven example literals -----------------------------------------
+// Doc snippets must use example values whose TYPE matches the model's
+// declared param/field type — a number id shown as a quoted string documents
+// a call the API would reject. These helpers derive the example literal from
+// the SAME model source the request shapes are built from (opRequestShape),
+// so the docs and the model can never disagree. Go twin of the ts
+// exampleValue (cmp/ts/utility_ts.ts), rendering Go literals.
+
+// 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 and the request shape mirrors the entity fields). 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 Go 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 `[]any{}` and OBJECT as
+// the empty `map[string]any{}`, 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 '[]any{}'
+  }
+  if ('OBJECT' === key) {
+    return 'map[string]any{}'
+  }
+  return `"${placeholder}"`
+}
+
+
+// A camelCase Go identifier for a snake_case model name
+// (`status_embed_config` -> `statusEmbedConfig`) — Go variables are
+// camelCase, never snake_case — with the reserved-word guard applied (a
+// `type`/`range` entity must not bind a Go keyword).
+function goVarName(name: string): string {
+  const pascal = camelify(name)
+  return safeVarName(pascal.charAt(0).toLowerCase() + pascal.slice(1), 'go')
+}
+
+
 function formatGoMap(obj: any, indent: number = 0): string {
   if (obj == null) {
     return 'nil'
@@ -82,7 +150,9 @@ function clean(o: any) {
 
 export {
   clean,
+  exampleValue,
   formatGoMap,
   formatGoValue,
+  goVarName,
   projectPath,
 }