@voxgig/sdkgen 1.2.0 → 1.3.1

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

@@ -1,16 +1,29 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
 
 
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
-  const { target } = props
+  const { target, ctx$ } = props
+  const { model } = ctx$
 
-  Content('```bash')
-  Content(`
-npm install ${target.module.name}
+  if (isPublished(model, target.name)) {
+    Content('```bash')
+    Content(`
+${installCommand(model, target.name)}
 `)
-  Content('```')
+    Content('```')
+    return
+  }
 
+  // Publish pending: the package is not yet on npm, so install from the
+  // git release tag instead of a `npm install` that would 404.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to npm. Install it from the GitHub
+release tag (\`${target.name}/vX.Y.Z\`):
+
+- Releases: [${releasesUrl}](${releasesUrl})
+
+`)
 })
 
 

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

@@ -1,13 +1,51 @@
 
 import { cmp, Content } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
 
   Content(`# ${model.Name} ${target.title} SDK
 
-The ${target.title} SDK for the ${model.Name} API. Provides a type-safe, entity-oriented interface with full async/await support.
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — a type-safe, entity-oriented client with full async/await support.
+
+The API is exposed as capitalised, semantic **Entities** — e.g.
+\`client.${eName}()\` — each with a small set of operations (${opList})
+instead of raw URL paths and query parameters. This keeps the surface
+predictable and low-friction for both humans and AI agents.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
 
 `)
 })

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

@@ -13,6 +13,43 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
+  // Model-driven op rows for the shared entity interface: emit a
+  // load/list/create/update/remove row only for operations at least one active
+  // entity actually exposes (a read-only entity has just list+load) — never
+  // document an operation no entity has.
+  const opUnion = new Set<string>()
+  entityList.forEach((e: any) => Object.keys(e.op || {})
+    .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
+  const opRowDefs: Record<string, string> = {
+    load: '| `load` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria. |',
+    list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria. |',
+    create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity. |',
+    update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity. |',
+    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  // Model-driven return-value bullets: describe only the operations that
+  // actually exist (single-object ops among load/create/update, plus
+  // list/remove) — never document return semantics for a missing op.
+  const singleOps = ['load', 'create', 'update'].filter((o) => opUnion.has(o))
+    .map((o) => '`' + o + '`')
+  const retBullets: string[] = []
+  if (singleOps.length) {
+    const joined = singleOps.length > 1
+      ? singleOps.slice(0, -1).join(', ') + ' and ' + singleOps[singleOps.length - 1]
+      : singleOps[0]
+    retBullets.push(`- ${joined} ${singleOps.length > 1 ? 'resolve' : 'resolves'} to a single entity object.`)
+  }
+  if (opUnion.has('list')) {
+    retBullets.push('- `list` resolves to an **array** of entity objects (iterate it directly;\n  there is no `.data` and no `.ok`).')
+  }
+  if (opUnion.has('remove')) {
+    retBullets.push('- `remove` resolves to `void`.')
+  }
+  const returnBullets = retBullets.join('\n')
+
   const authActive = isAuthActive(model)
   const apikeyOptionType = authActive ? `\n  apikey?: string` : ''
   const apikeyOptionRow = authActive
@@ -52,7 +89,8 @@ ${apikeyOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
 `)
 
   each(entityList, (ent: any) => {
-    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
 `)
   })
 
@@ -72,29 +110,23 @@ All entities share the same interface.
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| \`load\` | \`load(reqmatch?, ctrl?): Promise<Result>\` | Load a single entity by match criteria. |
-| \`list\` | \`list(reqmatch?, ctrl?): Promise<Result>\` | List entities matching the criteria. |
-| \`create\` | \`create(reqdata?, ctrl?): Promise<Result>\` | Create a new entity. |
-| \`update\` | \`update(reqdata?, ctrl?): Promise<Result>\` | Update an existing entity. |
-| \`remove\` | \`remove(reqmatch?, ctrl?): Promise<Result>\` | Remove an entity. |
-| \`data\` | \`data(data?): any\` | Get or set entity data. |
-| \`match\` | \`match(match?): any\` | Get or set entity match criteria. |
+${opRows}
+| \`data\` | \`data(data?: Partial<Entity>): Entity\` | Get or set entity data. |
+| \`match\` | \`match(match?: Partial<Entity>): Partial<Entity>\` | Get or set entity match criteria. |
 | \`make\` | \`make(): Entity\` | Create a new instance with the same options. |
 | \`client\` | \`client(): ${model.const.Name}SDK\` | Return the parent SDK client. |
 | \`entopts\` | \`entopts(): object\` | Return a copy of the entity options. |
 
-#### Result shape
+#### Return values
 
-All entity operations return a Result object:
+Entity operations resolve to the entity data directly — there is no
+result envelope:
 
-\`\`\`ts
-{
-  ok: boolean      // true if the HTTP status is 2xx
-  status: number   // HTTP status code
-  headers: object  // response headers
-  data: any        // parsed JSON response body
-}
-\`\`\`
+${returnBullets}
+
+On a failed request these methods **throw**, so wrap calls in
+\`try\`/\`catch\` to handle errors. Only \`direct()\` returns the result
+envelope described below.
 
 ### DirectResult shape
 

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

@@ -1,12 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
 
 
 const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  const publishedOptions = each(target.options).filter((option: any) => option.publish)
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
   if (0 === publishedOptions.length) {
     return
   }
@@ -25,7 +26,7 @@ const client = new ${model.Name}SDK({
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
+      Content(`  ${option.name}: process.env.${envName(model)}_APIKEY,
 `)
     }
     else {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, packageName, envName, opRequestShape, entityIdField, entityDataIdField, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_ts'
+
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -21,16 +23,16 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     e.active !== false && e.ancestors && e.ancestors.length > 0
   ) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,\n})`
+    : `new ${model.const.Name}SDK()`
 
   Content(`### 1. Create a client
 
 \`\`\`ts
-import { ${model.const.Name}SDK } from '${target.module.name}'
+import { ${model.const.Name}SDK } from '${packageName(model, target.name)}'
 
-const client = new ${model.const.Name}SDK({${apikeyArg}})
+const client = ${ctor}
 \`\`\`
 
 `)
@@ -38,18 +40,30 @@ const client = new ${model.const.Name}SDK({${apikeyArg}})
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    // Variable-safe lowercase name — a `Delete`/`Class` entity must not bind a
+    // reserved word (`const delete = ...` is a TS1109 syntax error).
+    const eVar = safeVarName(eName.toLowerCase(), 'ts')
+    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
     const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: `idF` is the entity's id-like MATCH field name, or
+    // null when it has none (then load/remove match on no argument).
+    const idF = entityIdField(exampleEntity)
+    // The id field on the RETURNED record's data type, or null. DISTINCT from
+    // idF (the match key): an entity can key its load-match on an id it does not
+    // carry as a data field, so `.id` off a returned record must be guarded on
+    // this — reading `created.id` when the data type has no id is a TS2339.
+    const dataIdF = entityDataIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`### 2. List ${eName.toLowerCase()}s
+      Content(`### 2. List ${eName.toLowerCase()} records
+
+\`list()\` resolves to an array of ${eName} objects — iterate it directly:
 
 \`\`\`ts
-const result = await client.${eName}().list()
+const ${eVar}s = await client.${eName}().list()
 
-if (result.ok) {
-  for (const item of result.data) {
-    console.log(item.id, item.name)
-  }
+for (const ${eVar} of ${eVar}s) {
+  console.log(${eVar})
 }
 \`\`\`
 
@@ -58,70 +72,111 @@ if (result.ok) {
 
     if (nestedEntity) {
       const neName = nom(nestedEntity, 'Name')
+      const neVar = safeVarName(neName.toLowerCase(), 'ts')
+      const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
       const parentFields = (nestedEntity.fields || [])
         .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
       const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
+      const loadOp = nestedEntity.op && nestedEntity.op.load
+
+      // Model-driven id key: only emit an id match line if this nested entity
+      // actually has an id-like key field (some response-wrapped specs do not).
+      const neIdF = entityIdField(nestedEntity)
+      const neMatchLines = [`    ${parentParam}: ${exampleValue(nestedEntity, loadOp, parentParam, 'example')},`]
+      if (neIdF) {
+        neMatchLines.push(`    ${neIdF}: ${exampleValue(nestedEntity, loadOp, neIdF, 'example_id')},`)
+      }
 
-      Content(`### 3. Load a ${neName.toLowerCase()}
+      Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
-${neName} is nested under ${eName}, so provide the \`${parentParam}\`:
+${neName} is nested under ${eName}, so provide the \`${parentParam}\`.
+\`load()\` returns the entity directly and throws on failure:
 
 \`\`\`ts
-const ${neName.toLowerCase()} = client.${neName}()
-const result = await ${neName.toLowerCase()}.load({
-  ${parentParam}: 'example',
-  id: 'example_id',
-})
-
-if (result.ok) {
-  console.log(result.data)
+try {
+  const ${neVar} = await client.${neName}().load({
+${neMatchLines.join('\n')}
+  })
+  console.log(${neVar})
+} catch (err) {
+  console.error('load failed:', err)
 }
 \`\`\`
 
 `)
     }
     else if (opnames.includes('load')) {
-      Content(`### 3. Load a ${eName.toLowerCase()}
+      Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`\`\`ts
-const result = await client.${eName}().load({ id: 'example_id' })
+\`load()\` returns the entity directly and throws on failure:
 
-if (result.ok) {
-  console.log(result.data)
+\`\`\`ts
+try {
+  const ${eVar} = await client.${eName}().load(${idF ? `{ ${idF}: ${exampleValue(exampleEntity, exampleEntity.op && exampleEntity.op.load, idF, 'example_id')} }` : ''})
+  console.log(${eVar})
+} catch (err) {
+  console.error('load failed:', err)
 }
 \`\`\`
 
 `)
     }
 
-    // CRUD operations
+    // CRUD operations. The create/update example payloads are derived from the
+    // SAME op shapes that generate the <Name>CreateData / <Name>UpdateData types
+    // (opRequestShape), so the snippet always type-checks. Prefer writable
+    // non-id fields and render a type-correct literal per field via
+    // exampleValue — never a hardcoded field the entity may not have.
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      // Writable non-id example fields for an op body. For create the REQUIRED
+      // fields must all appear or the literal is not assignable to the typed
+      // <Name>CreateData (a TS2345); update is a patch, so a couple of fields
+      // suffice.
+      const exampleFields = (opname: string): string[] => {
+        const items = opRequestShape(exampleEntity, opname).items
+          .filter((it: any) => it.name !== idF && it.name !== 'id')
+        const required = items.filter((it: any) => !it.optional)
+        const chosen = 'create' === opname
+          ? (required.length ? required : items.slice(0, 2))
+          : items.slice(0, 2)
+        return chosen.map((it: any) =>
+          `  ${it.name}: ${exampleValue(exampleEntity, exampleEntity.op[opname], it.name, 'example_' + it.name)},`)
+      }
+
+      // The id VALUE for an update/remove match. When the entity's DATA type
+      // carries the id (dataIdF) AND a `created` record exists, take it off the
+      // returned record; otherwise use a type-correct literal — reading
+      // `created.id` off an id-less data type is a TS2339.
+      const canUseCreatedId = null != dataIdF && opnames.includes('create')
+      const idValueFor = (opname: string): string => canUseCreatedId
+        ? `created.${dataIdF}!`
+        : exampleValue(exampleEntity, exampleEntity.op[opname], idF as string, 'example_id')
+
       Content(`### 4. Create, update, and remove
 
 \`\`\`ts
 `)
       if (opnames.includes('create')) {
-        Content(`// Create
-const created = await client.${eName}().create({
-  name: 'Example',
-})
+        const createLines = exampleFields('create')
+        const createBody = createLines.length ? '\n' + createLines.join('\n') + '\n' : ''
+        Content(`// Create — returns the created ${eName}
+const created = await client.${eName}().create({${createBody}})
 
 `)
       }
       if (opnames.includes('update')) {
-        Content(`// Update
-const updated = await client.${eName}().update({
-  id: created.data.id,
-  name: 'Example-Renamed',
-})
+        // Match on the id (from the returned `created` record when the data
+        // type carries one, else a literal), plus a couple of patch fields.
+        const updateLines = (idF ? [`  ${idF}: ${idValueFor('update')},`] : []).concat(exampleFields('update'))
+        const updateBody = updateLines.length ? '\n' + updateLines.join('\n') + '\n' : ''
+        Content(`// Update${canUseCreatedId ? ' — the id comes straight off the returned entity' : ''}
+const updated = await client.${eName}().update({${updateBody}})
 
 `)
       }
       if (opnames.includes('remove')) {
         Content(`// Remove
-const removed = await client.${eName}().remove({
-  id: created.data.id,
-})
+await client.${eName}().remove(${idF ? `{\n  ${idF}: ${idValueFor('remove')},\n}` : ''})
 `)
       }
       Content(`\`\`\`

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

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

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

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

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, packageName, envName, entityIdField, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,8 @@ import {
   nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_ts'
+
 
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
@@ -14,25 +16,33 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
-    : ''
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,\n})`
+    : `new ${model.const.Name}SDK()`
 
   Content(`\`\`\`ts
-import { ${model.const.Name}SDK } from '${target.module.name}'
+import { ${model.const.Name}SDK } from '${packageName(model, target.name)}'
 
-const client = new ${model.const.Name}SDK({${apikeyArg}})
+const client = ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    const eVar = safeVarName(eName.toLowerCase(), 'ts')
     const opnames = Object.keys(exampleEntity.op || {})
 
+    let hasCall = false
+
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s
-const ${eName.toLowerCase()}s = await client.${eName}().list()
+      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}[])
+const ${eVar}s = await client.${eName}().list()
+for (const ${eVar} of ${eVar}s) {
+  console.log(${eVar})
+}
 `)
+      hasCall = true
     }
 
     // Find a nested entity for a more interesting example
@@ -42,17 +52,39 @@ const ${eName.toLowerCase()}s = await client.${eName}().list()
 
     if (nestedEntity && opnames.includes('load')) {
       const neName = nom(nestedEntity, 'Name')
+      const neVar = safeVarName(neName.toLowerCase(), 'ts')
       const parentFields = (nestedEntity.fields || [])
         .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
       const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
+      const loadOp = nestedEntity.op && nestedEntity.op.load
+
+      // Model-driven id key: only emit an id match line if the nested entity
+      // has an id-like key field.
+      const neIdF = entityIdField(nestedEntity)
+      const neMatchLines = [`  ${parentParam}: ${exampleValue(nestedEntity, loadOp, parentParam, 'example')},`]
+      if (neIdF) {
+        neMatchLines.push(`  ${neIdF}: ${exampleValue(nestedEntity, loadOp, neIdF, 'example_id')},`)
+      }
 
       Content(`
-// Load a specific ${neName.toLowerCase()}
-const ${neName.toLowerCase()} = await client.${neName}().load({
-  ${parentParam}: 'example',
-  id: 'example_id',
+// Load a specific ${neName.toLowerCase()} (returns a ${neName})
+const ${neVar} = await client.${neName}().load({
+${neMatchLines.join('\n')}
 })
+console.log(${neVar})
+`)
+      hasCall = true
+    }
+
+    // Fallback: APIs with only `load` (no list, no nested) — most public
+    // read-only services. Still show one concrete call. `load()` with no
+    // match is always valid (the match arg is optional).
+    if (!hasCall && opnames.includes('load')) {
+      Content(`// Load ${eName.toLowerCase()} data (returns a ${eName})
+const ${eVar} = await client.${eName}().load()
+console.log(${eVar})
 `)
+      hasCall = true
     }
   }