@voxgig/sdkgen 1.2.0 → 1.3.1

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

@@ -13,6 +13,23 @@ 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` | `(reqmatch, ctrl) -> any` | Load a single entity by match criteria. Raises on error. |',
+    list: '| `list` | `(reqmatch = nil, ctrl) -> Array` | List entities matching the criteria (call with no argument to list all). Raises on error. |',
+    create: '| `create` | `(reqdata, ctrl) -> any` | Create a new entity. Raises on error. |',
+    update: '| `update` | `(reqdata, ctrl) -> any` | Update an existing entity. Raises on error. |',
+    remove: '| `remove` | `(reqmatch, ctrl) -> any` | Remove an entity. Raises on error. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
   const apikeyOptionRow = isAuthActive(model)
     ? '| `apikey` | `String` | API key for authentication. |\n'
     : ''
@@ -49,12 +66,13 @@ Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
 | --- | --- | --- |
 | \`options_map\` | \`() -> Hash\` | Deep copy of current SDK options. |
 | \`get_utility\` | \`() -> Utility\` | Copy of the SDK utility object. |
-| \`prepare\` | \`(fetchargs) -> [Hash, err]\` | Build an HTTP request definition without sending. |
-| \`direct\` | \`(fetchargs) -> [Hash, err]\` | Build and send an HTTP request. |
+| \`prepare\` | \`(fetchargs) -> Hash\` | Build an HTTP request definition without sending. Raises on error. |
+| \`direct\` | \`(fetchargs) -> Hash\` | Build and send an HTTP request. Returns a result hash (\`result["ok"]\`); does not raise. |
 `)
 
   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. |
 `)
   })
 
@@ -65,11 +83,7 @@ All entities share the same interface.
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| \`load\` | \`(reqmatch, ctrl) -> [any, err]\` | Load a single entity by match criteria. |
-| \`list\` | \`(reqmatch, ctrl) -> [any, err]\` | List entities matching the criteria. |
-| \`create\` | \`(reqdata, ctrl) -> [any, err]\` | Create a new entity. |
-| \`update\` | \`(reqdata, ctrl) -> [any, err]\` | Update an existing entity. |
-| \`remove\` | \`(reqmatch, ctrl) -> [any, err]\` | Remove an entity. |
+${opRows}
 | \`data_get\` | \`() -> Hash\` | Get entity data. |
 | \`data_set\` | \`(data)\` | Set entity data. |
 | \`match_get\` | \`() -> Hash\` | Get entity match criteria. |
@@ -79,8 +93,12 @@ All entities share the same interface.
 
 ### Result shape
 
-Entity operations return \`[any, err]\`. The first value is a
-\`Hash\` with these keys:
+Entity operations return the result data directly. On failure they
+raise a \`${model.const.Name}Error\` (a \`StandardError\` subclass), so wrap
+calls in \`begin\`/\`rescue\` where you need to handle errors.
+
+The \`direct\` escape hatch is the exception: it never raises and instead
+returns a result \`Hash\` with these keys:
 
 | Key | Type | Description |
 | --- | --- | --- |
@@ -88,8 +106,7 @@ Entity operations return \`[any, err]\`. The first value is a
 | \`status\` | \`Integer\` | HTTP status code. |
 | \`headers\` | \`Hash\` | Response headers. |
 | \`data\` | \`any\` | Parsed JSON response body. |
-
-On error, \`ok\` is \`false\` and \`err\` contains the error value.
+| \`err\` | \`Error\` | Present when \`ok\` is \`false\`. |
 
 `)
 

package/project/.sdk/src/cmp/rb/ReadmeOptions_rb.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 @@ client = ${model.Name}SDK.new({
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`  "${option.name}" => ENV["${model.NAME}_APIKEY"],
+      Content(`  "${option.name}" => ENV["${envName(model)}_APIKEY"],
 `)
     }
     else {

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 } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -18,36 +18,57 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     e.active !== false && e.ancestors && e.ancestors.length > 0
   ) 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 article = /^[aeiou]/i.test(eName) ? "an" : "a"
     const opnames = Object.keys(exampleEntity.op || {})
+    // 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)
+
+    // 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
 \`\`\`
 
@@ -55,37 +76,79 @@ end
     }
 
     if (opnames.includes('load')) {
-      Content(`### 3. Load a ${eName.toLowerCase()}
+      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(${idF ? `{ "${idF}" => "example_id" }` : ''})
+  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.
+    const idField = (exampleEntity.id && exampleEntity.id.field) || 'id'
+    const 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 examplePairs = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => it.name !== idField && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      // create needs ALL required fields; update is a patch, so a couple suffice.
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : items.slice(0, 2)
+      return chosen.map((it: any) => `"${it.name}" => ${rbLit(it.type)}`)
+    }
+
+    // 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))
+
     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')) {
         Content(`# Remove
-client.${eName}(nil).remove({ "id" => created["id"] }, nil)
+client.${eName}.remove(${idF ? `{ "${idF}" => ${idValueFor('remove')} }` : ''})
 `)
       }
       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 } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,31 +7,43 @@ 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.
+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 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 +72,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 +84,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 +134,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 +152,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 +168,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 +202,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 +212,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 '-'
@@ -239,25 +258,25 @@ ${info.desc}
           // Show example
           if ('load' === opname || 'remove' === opname) {
             Content(`\`\`\`ruby
-result, err = client.${ent.Name}.${opname}({ "id" => "${ent.name}_id" })
+result = client.${ent.Name}.${opname}(${idF ? `{ "${idF}" => "${ent.name}_id" }` : ''})
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`ruby
-results, err = client.${ent.Name}.list(nil)
+results = client.${ent.Name}.list
 \`\`\`
 
 `)
           }
           else if ('create' === opname) {
             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'},
+                Content(`  "${field.name}" => ${rbLit(field.type)}, # ${canonToType(field.type, target.name)}
 `)
               }
             })
@@ -267,10 +286,10 @@ result, err = client.${ent.Name}.create({
 `)
           }
           else if ('update' === opname) {
+            const updateIdLine = idF ? `  "${idF}" => "${ent.name}_id",\n` : ''
             Content(`\`\`\`ruby
-result, err = client.${ent.Name}.update({
-  "id" => "${ent.name}_id",
-  # Fields to update
+result = client.${ent.Name}.update({
+${updateIdLine}  # 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, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -15,34 +15,42 @@ 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')) {
       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(${idF ? `{ "${idF}" => "example_id" }` : ''})
+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,41 @@ 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) {
+      callArg = idF ? `{ "${idF}" => "test01" }` : ''
+    } 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(', ')} }`
+    }
+    Content(`\`\`\`ruby
+# Seed fixture data so offline calls resolve without a live server.
+client = ${model.const.Name}SDK.test({
+  "entity" => { "${ename}" => { "test01" => ${recBody} } },
+})
+${ename} = client.${eName}.${primaryOp}(${callArg})
+\`\`\`
 `)
-  }
-
-  Content(`\`\`\`
+  } else {
+    Content(`\`\`\`ruby
+client = ${model.const.Name}SDK.test
+\`\`\`
 `)
+  }
 
 })