@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,78 +14,216 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  // Find a nested entity if available: 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
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  "apikey" => ENV["${model.NAME}_APIKEY"],\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `${model.const.Name}SDK.new({\n  "apikey" => ENV["${envName(model)}_APIKEY"],\n})`
+    : `${model.const.Name}SDK.new`
 
   Content(`### 1. Create a client
 
 \`\`\`ruby
 require_relative "${model.const.Name}_sdk"
 
-client = ${model.const.Name}SDK.new({${apikeyArg}})
+client = ${ctor}
 \`\`\`
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    const opnames = Object.keys(exampleEntity.op || {})
+    const article = /^[aeiou]/i.test(eName) ? "an" : "a"
+    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
+    // take no argument. `dataIdF` is the id on the RETURNED record's data type —
+    // an entity can key its match on an id it does not carry as data, so both a
+    // listed record's id column and a `created["id"]` read must be guarded on
+    // this, not the match key.
+    const idF = entityIdField(exampleEntity)
+    const dataIdF = entityDataIdField(exampleEntity)
+
+    // A type-correct, executable Ruby literal for a param: numeric/boolean/
+    // array/hash params render a typed literal; strings render the quoted
+    // placeholder (the doc test EXECUTES these blocks, so a comment
+    // placeholder would not parse).
+    const rbLit = (type: any, placeholder: string = 'example'): string => {
+      const k = canonKey(type)
+      if ('INTEGER' === k || 'NUMBER' === k) return '1'
+      if ('BOOLEAN' === k) return 'true'
+      if ('ARRAY' === k) return '[]'
+      if ('OBJECT' === k) return '{}'
+      return `"${placeholder}"`
+    }
+
+    // Model-driven display field: the entity's first non-id string field
+    // (falling back to any non-id field), so the list example prints a real
+    // column instead of a hardcoded "name" the entity may not have.
+    const fields = exampleEntity.fields || []
+    const displayField =
+      fields.find((f: any) => f && f.name !== 'id' && f.type === '$STRING') ||
+      fields.find((f: any) => f && f.name !== 'id') ||
+      null
+    const idCol = dataIdF ? `#{item[${JSON.stringify(dataIdF)}]}` : null
+    const dispCol = displayField ? `#{item[${JSON.stringify(displayField.name)}]}` : null
+    const itemPrint = [idCol, dispCol].filter(Boolean).join(' ') || '#{item}'
 
     if (opnames.includes('list')) {
-      Content(`### 2. List ${eName.toLowerCase()}s
+      Content(`### 2. List ${eName.toLowerCase()} records
 
 \`\`\`ruby
-result, err = client.${eName}(nil).list(nil, nil)
-raise err if err
-
-if result.is_a?(Array)
-  result.each do |item|
-    d = item.data_get
-    puts "#{d["id"]} #{d["name"]}"
+begin
+  # list returns an Array of ${eName} records — iterate directly.
+  ${eName.toLowerCase()}s = client.${eName}.list
+  ${eName.toLowerCase()}s.each do |item|
+    puts "${itemPrint}"
   end
+rescue => err
+  warn "list failed: #{err}"
 end
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('load')) {
-      Content(`### 3. Load a ${eName.toLowerCase()}
+    if (nestedEntity) {
+      const neName = nom(nestedEntity, 'Name')
+      const neArticle = /^[aeiou]/i.test(neName) ? "an" : "a"
+      const neVar = neName.toLowerCase()
+
+      // Model-driven match: every REQUIRED load-match key — the same shape
+      // the runtime resolves path params from, so the example always works.
+      // Parent keys (e.g. page_id) first, the entity's own id last.
+      const neIdF = entityIdField(nestedEntity)
+      const neRequired = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+      const parentItem = neRequired.find((it: any) => it.name !== neIdF) as any
+      const parentParam = parentItem && parentItem.name
+      const parentName = parentParam ? parentParam.replace(/_id$/, '') : 'its parent'
+      const neMatch = neRequired.map((it: any) =>
+        `"${it.name}" => ${rbLit(it.type,
+          it.name === neIdF ? 'example_id' : 'example_' + it.name)}`)
+
+      Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
+
+${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
+
+\`\`\`ruby
+begin
+  # load returns the bare ${neName} record (raises on error).
+  ${neVar} = client.${neName}.load({ ${neMatch.join(', ')} })
+  puts ${neVar}
+rescue => err
+  warn "load failed: #{err}"
+end
+\`\`\`
+
+`)
+    }
+    else if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadRequired = 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 < loadRequired.length
+        ? `{ ${loadRequired.map((it: any) =>
+          `"${it.name}" => ${rbLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+
+      Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
 \`\`\`ruby
-result, err = client.${eName}(nil).load({ "id" => "example_id" }, nil)
-raise err if err
-puts result
+begin
+  # load returns the bare ${eName} record (raises on error).
+  ${eName.toLowerCase()} = client.${eName}.load(${loadArg})
+  puts ${eName.toLowerCase()}
+rescue => err
+  warn "load failed: #{err}"
+end
 \`\`\`
 
 `)
     }
 
+    // Model-driven example fields: derive the create/update body from the op
+    // shape (opRequestShape) so the docs reference REAL writable fields, not a
+    // hardcoded "name" the entity may not have. Literals are Ruby-typed by the
+    // field's canonical type. ids are rendered separately as the match key for
+    // update/remove; a REQUIRED create id stays (the call is invalid without
+    // it).
+    const examplePairs = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
+          ('create' === opname && !it.optional))
+      const required = items.filter((it: any) => !it.optional)
+      const optional = items.filter((it: any) => it.optional)
+      // create needs ALL required fields; update is a patch, so the required
+      // members plus a sample optional field or two suffice.
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : required.concat(optional).slice(0, Math.max(2, required.length))
+      return chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type, 'example_' + it.name)}`)
+    }
+
+    // The id VALUE for an update/remove match: off the returned `created`
+    // record only when its data type carries the id AND a create ran, else a
+    // type-correct literal (so an update-without-create never references an
+    // undefined `created`).
+    const idParamType = (opname: string): any => {
+      const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
+      return it && it.type
+    }
+    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
+      ? `created["${dataIdF}"]`
+      : rbLit(idParamType(opname), 'example_id')
+
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`ruby
 `)
       if (opnames.includes('create')) {
-        Content(`# Create
-created, _ = client.${eName}(nil).create({ "name" => "Example" }, nil)
+        Content(`# create returns the bare created ${eName} record.
+created = client.${eName}.create({ ${examplePairs('create').join(', ')} })
 
 `)
       }
       if (opnames.includes('update')) {
-        Content(`# Update
-client.${eName}(nil).update({ "id" => created["id"], "name" => "Example-Renamed" }, nil)
+        const updatePairs = (idF ? [`"${idF}" => ${idValueFor('update')}`] : []).concat(examplePairs('update'))
+        const fromCreated = null != dataIdF && opnames.includes('create')
+        Content(`# Update${fromCreated ? ` — index the bare record directly (created["${dataIdF}"]).` : ''}
+client.${eName}.update({ ${updatePairs.join(', ')} })
 
 `)
       }
       if (opnames.includes('remove')) {
+        // Every REQUIRED remove-match key: the id (off the created record
+        // when possible) plus parent keys like page_id.
+        const removePairs = opRequestShape(exampleEntity, 'remove').items
+          .filter((it: any) => !it.optional || it.name === idF)
+          .sort((a: any, b: any) =>
+            (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+          .map((it: any) => it.name === idF
+            ? `"${it.name}" => ${idValueFor('remove')}`
+            : `"${it.name}" => ${rbLit(it.type, 'example_' + it.name)}`)
         Content(`# Remove
-client.${eName}(nil).remove({ "id" => created["id"] }, nil)
+client.${eName}.remove(${removePairs.length ? `{ ${removePairs.join(', ')} }` : ''})
 `)
       }
       Content(`\`\`\`

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,31 +7,44 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct Ruby literal for a field's canonical type — the create body
+// is EXECUTED by the doc test, so it must carry a real value per field.
+// Strings render the quoted placeholder.
+function rbLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return `"${placeholder}"`
+}
+
+
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load(reqmatch, ctrl = nil) -> result, err',
-    returns: 'result, err',
-    desc: 'Load a single entity matching the given criteria.',
+    sig: 'load(reqmatch, ctrl = nil) -> result',
+    returns: 'result',
+    desc: 'Load a single entity matching the given criteria. Raises on error.',
   },
   list: {
-    sig: 'list(reqmatch, ctrl = nil) -> result, err',
-    returns: 'result, err',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    sig: 'list(reqmatch = nil, ctrl = nil) -> Array',
+    returns: 'Array',
+    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array. Raises on error.',
   },
   create: {
-    sig: 'create(reqdata, ctrl = nil) -> result, err',
-    returns: 'result, err',
-    desc: 'Create a new entity with the given data.',
+    sig: 'create(reqdata, ctrl = nil) -> result',
+    returns: 'result',
+    desc: 'Create a new entity with the given data. Raises on error.',
   },
   update: {
-    sig: 'update(reqdata, ctrl = nil) -> result, err',
-    returns: 'result, err',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    sig: 'update(reqdata, ctrl = nil) -> result',
+    returns: 'result',
+    desc: 'Update an existing entity. The data must include the entity `id`. Raises on error.',
   },
   remove: {
-    sig: 'remove(reqmatch, ctrl = nil) -> result, err',
-    returns: 'result, err',
-    desc: 'Remove the entity matching the given criteria.',
+    sig: 'remove(reqmatch, ctrl = nil) -> result',
+    returns: 'result',
+    desc: 'Remove the entity matching the given criteria. Raises on error.',
   },
 }
 
@@ -60,7 +73,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
 `)
 
     Content(`\`\`\`ruby
-require_relative '${model.name}_sdk'
+require_relative '${model.const.Name}_sdk'
 
 client = ${model.const.Name}SDK.new(options)
 \`\`\`
@@ -72,8 +85,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`options\` | \`Hash\` | 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"]\` | \`Hash\` | Custom headers for all requests. |
@@ -123,9 +135,11 @@ Return a deep copy of the current SDK options.
 
 Return a copy of the SDK utility object.
 
-#### \`direct(fetchargs = {}) -> Hash, err\`
+#### \`direct(fetchargs = {}) -> Hash\`
 
-Make a direct HTTP request to any API endpoint.
+Make a direct HTTP request to any API endpoint. Returns a result hash
+(\`{ "ok" => ..., "status" => ..., "data" => ..., "err" => ... }\`); it
+does not raise — inspect \`result["ok"]\`.
 
 **Parameters:**
 
@@ -139,14 +153,14 @@ Make a direct HTTP request to any API endpoint.
 | \`fetchargs["body"]\` | \`any\` | Request body (hashes are JSON-serialized). |
 | \`fetchargs["ctrl"]\` | \`Hash\` | Control options (e.g. \`{ "explain" => true }\`). |
 
-**Returns:** \`Hash, err\`
+**Returns:** \`Hash\`
 
-#### \`prepare(fetchargs = {}) -> Hash, err\`
+#### \`prepare(fetchargs = {}) -> Hash\`
 
 Prepare a fetch definition without sending the request. Accepts the
-same parameters as \`direct()\`.
+same parameters as \`direct()\`. Raises on error.
 
-**Returns:** \`Hash, err\`
+**Returns:** \`Hash\` (the fetch definition; raises on error)
 
 `)
 
@@ -155,6 +169,9 @@ same parameters as \`direct()\`.
     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)
 
       Content(`
 ---
@@ -186,7 +203,7 @@ ${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} |
 `)
         })
 
@@ -196,15 +213,18 @@ ${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 '-'
@@ -238,28 +258,45 @@ ${info.desc}
 
           // Show example
           if ('load' === opname || 'remove' === opname) {
+            // The id key plus every REQUIRED match key (parent path params
+            // like page_id) — the same shape the runtime resolves path
+            // params from, so the example always works.
+            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
+              ? `{ ${matchItems.map((it: any) =>
+                `"${it.name}" => ${rbLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
+              : ''
             Content(`\`\`\`ruby
-result, err = client.${ent.Name}.${opname}({ "id" => "${ent.name}_id" })
+result = client.${ent.Name}.${opname}(${arg})
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`ruby
-results, err = client.${ent.Name}.list(nil)
+results = client.${ent.Name}.list
 \`\`\`
 
 `)
           }
           else if ('create' === opname) {
+            // 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 — with a real,
+            // executable literal (the doc test RUNS this block, so a comment
+            // placeholder would break it).
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
             Content(`\`\`\`ruby
-result, err = client.${ent.Name}.create({
+result = client.${ent.Name}.create({
 `)
-            each(fields, (field: any) => {
-              if ('id' !== field.name && field.req) {
-                Content(`  "${field.name}" => # ${field.type || 'value'},
+            createItems.map((it: any) => {
+              Content(`  "${it.name}" => ${rbLit(it.type, 'example_' + it.name)}, # ${canonToType(it.type, target.name)}
 `)
-              }
             })
             Content(`})
 \`\`\`
@@ -267,10 +304,18 @@ result, err = client.${ent.Name}.create({
 `)
           }
           else if ('update' === opname) {
+            // The id key plus every REQUIRED data member — the same shape the
+            // runtime validates — 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}" => ${rbLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ruby
-result, err = client.${ent.Name}.update({
-  "id" => "${ent.name}_id",
-  # Fields to update
+result = client.${ent.Name}.update({
+${updateLines}  # Fields to update
 })
 \`\`\`
 

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

@@ -7,7 +7,7 @@ const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
 
   Content(`**Ruby:**
 \`\`\`ruby
-result, err = client.direct({
+result = client.direct({
   "path" => "/api/resource/{id}",
   "method" => "GET",
   "params" => { "id" => "example" },

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,20 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct, executable Ruby literal for a param: numeric/boolean/
+// array/hash params render a typed literal; strings render the quoted
+// placeholder (the doc test EXECUTES this block, so a comment placeholder
+// would break it).
+function rbLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return `"${placeholder}"`
+}
+
+
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -15,34 +29,54 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n  "apikey" => ENV["${model.NAME}_APIKEY"],\n`
-    : ''
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `${model.const.Name}SDK.new({\n  "apikey" => ENV["${envName(model)}_APIKEY"],\n})`
+    : `${model.const.Name}SDK.new`
 
   Content(`\`\`\`ruby
 require_relative "${model.const.Name}_sdk"
 
-client = ${model.const.Name}SDK.new({${apikeyArg}})
+client = ${ctor}
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     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.
+    const idF = entityIdField(exampleEntity)
+
+    let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`# List all ${eName.toLowerCase()}s
-${eName.toLowerCase()}s, err = client.${eName}(nil).list(nil, nil)
+      Content(`# List all ${eName.toLowerCase()}s (returns an Array; raises on error)
+${eName.toLowerCase()}s = client.${eName}.list
+puts ${eName.toLowerCase()}s
 `)
+      hasCall = true
     }
 
     if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      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
+        ? `{ ${loadItems.map((it: any) =>
+          `"${it.name}" => ${rbLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
       Content(`
-# Load a specific ${eName.toLowerCase()}
-${eName.toLowerCase()}, err = client.${eName}(nil).load(
-  { "id" => "example_id" }, nil
-)
+# Load a specific ${eName.toLowerCase()} (returns the bare record; raises on error)
+${eName.toLowerCase()} = client.${eName}.load(${loadArg})
+puts ${eName.toLowerCase()}
 `)
+      hasCall = true
     }
   }
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,17 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct Ruby literal for a field's canonical type.
+function rbLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return '"example"'
+}
+
+
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -15,20 +26,52 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  Content(`\`\`\`ruby
-client = ${model.const.Name}SDK.test(nil, nil)
-`)
-
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`result, err = client.${eName}(nil).load(
-  { "id" => "test01" }, nil
-)
+    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 = ''
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from.
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      callArg = 0 < items.length
+        ? `{ ${items.map((it: any) =>
+          `"${it.name}" => ${it.name === idF ? '"test01"' : rbLit(it.type)}`).join(', ')} }`
+        : ''
+    } 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)
+      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' : '')
+    Content(`\`\`\`ruby
+# Seed fixture data so offline calls resolve without a live server.
+client = ${model.const.Name}SDK.test({
+  "entity" => { "${ename}" => { "test01" => ${recBody} } },
+})
+${eVar} = client.${eName}.${primaryOp}(${callArg})
+\`\`\`
 `)
-  }
-
-  Content(`\`\`\`
+  } else {
+    Content(`\`\`\`ruby
+client = ${model.const.Name}SDK.test
+\`\`\`
 `)
+  }
 
 })