@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/py/fragment/EntityPatchOp.fragment.py

@@ -0,0 +1,27 @@
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.core import helpers
+
+entity_patch_op = None
+
+# EJECT-START
+
+    def patch(self, reqdata: EntityNamePatchData, ctrl=None) -> EntityName:
+        utility = self._utility
+        ctx = utility.make_context({
+            "opname": "patch",
+            "ctrl": ctrl,
+            "match": self._match,
+            "data": self._data,
+            "reqdata": reqdata,
+        }, self._entctx)
+
+        def post_done():
+            if ctx.result is not None:
+                if ctx.result.resmatch is not None:
+                    self._match = ctx.result.resmatch
+                if ctx.result.resdata is not None:
+                    self._data = helpers.to_map(vs.clone(ctx.result.resdata)) or {}
+
+        return self._run_op(ctx, post_done)
+
+# EJECT-END

package/project/.sdk/src/cmp/py/fragment/Main.fragment.py

@@ -4,6 +4,8 @@ from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 from projectname_sdk.core.utility_type import ProjectNameUtility
 from projectname_sdk.core.spec import ProjectNameSpec
 from projectname_sdk.core import helpers
+from projectname_sdk.utility.prepare_method import allowed
+from projectname_sdk.utility.result_body import unreadable_body
 
 # Load utility registration (populates Utility._registrar)
 from projectname_sdk.utility import register
@@ -140,6 +142,13 @@ class ProjectNameSDK:
         method = vs.getprop(fetchargs, "method") or "GET"
         if not isinstance(method, str):
             method = "GET"
+        method = method.upper()
+
+        allow_method = vs.getpath(options, "allow.method")
+        if not allowed(allow_method, method):
+            raise ctx.make_error("spec_method_allow",
+                'Method "' + method +
+                '" not allowed by SDK option allow.method value: "' + str(allow_method) + '"')
 
         params = helpers.to_map(vs.getprop(fetchargs, "params"))
         if params is None:
@@ -200,8 +209,7 @@ class ProjectNameSDK:
 
     # Is this raw-access op permitted by the SDK's allow.op option?
     def _op_allowed(self, op):
-        allow_op = vs.getpath(self.options, "allow.op")
-        return isinstance(allow_op, str) and op in allow_op
+        return allowed(vs.getpath(self.options, "allow.op"), op)
 
     def _op_denied(self, op):
         allow_op = vs.getpath(self.options, "allow.op")
@@ -262,6 +270,7 @@ class ProjectNameSDK:
             no_body = status in (204, 304) or str(content_length) == "0"
 
             json_data = None
+            body_err = None
             if not no_body:
                 jf = vs.getprop(fetched, "json")
                 if callable(jf):
@@ -271,13 +280,22 @@ class ProjectNameSDK:
                         # Non-JSON body (e.g. text/plain, text/html). Surface
                         # status + headers but leave data as None.
                         json_data = None
-
-            return {
-                "ok": status >= 200 and status < 300,
+                if vs.getprop(fetched, "unreadable") is True:
+                    failed = None if 200 <= status < 300 else ctx.make_error(
+                        "request_status",
+                        "request: " + str(status) + ": " + str(vs.getprop(fetched, "statusText")))
+                    body_err = unreadable_body(ctx, status, headers, vs.getprop(fetched, "body"),
+                                               fetchdef.get("headers"), failed)
+
+            out = {
+                "ok": body_err is None and status >= 200 and status < 300,
                 "status": status,
                 "headers": headers,
                 "data": json_data,
             }
+            if body_err is not None:
+                out["err"] = utility.clean(ctx, body_err)
+            return out
 
         return {
             "ok": False,

package/project/.sdk/src/cmp/py-data/Main_py-data.ts

@@ -726,7 +726,7 @@ This package is generated from the API model by
 [@voxgig/sdkgen](https://github.com/voxgig/sdkgen). Edits to these files are
 overwritten on the next regeneration — change the model, not the output.
 
-${model.main[KIT].info?.about_md ? '' : ''}MIT licensed. Unofficial: not
+MIT licensed. Unofficial: not
 affiliated with or endorsed by the upstream API provider.
 `))
 })

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

@@ -6,7 +6,7 @@ import {
   File, Content,
 } from '@voxgig/sdkgen'
 
-import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames, rbSafeTypeName } from '@voxgig/sdkgen'
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions , deriveEntityNames, rbTypeName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -81,7 +81,7 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
 
     entityList.forEach((ent: any) => {
       const Name = ent.Name
-      const TypeName = rbSafeTypeName(Name)
+      const TypeName = rbTypeName(ent, entityCollection(model))
       const fields = (ent.fields ? each(ent.fields) : [])
         .filter((f: any) => f.a !== false)
 
@@ -92,7 +92,7 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
       )
 
       const ops = ent.op || {}
-      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+      ;['load', 'list', 'create', 'update', 'patch', 'remove'].forEach((opname: string) => {
         if (null == ops[opname]) {
           return
         }

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

@@ -40,7 +40,7 @@ const Entity = cmp(function Entity(props: any) {
       const opnames = Object.keys(entity.op || {})
 
       const opfrags =
-        (['load', 'list', 'create', 'update', 'remove']
+        (['load', 'list', 'create', 'update', 'patch', 'remove']
           .reduce((a: any, opname: string) =>
           (a['# #' + camelify(opname) + 'Op'] =
             !opnames.includes(opname) ? '' : ({ indent }: any) => {

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

@@ -4,6 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
   TEST_CONTROL_EXCLUDE
@@ -48,12 +49,10 @@ const Main = cmp(async function Main(props: any) {
   // Copy tm/rb files with replacements
   Copy({
     from: 'tm/' + target.name,
-    // pluginExcludes: the generate-time plugin trim (an INACTIVE plugin
-    // group's declared files stay out of the tree - the model's `path`
-    // entries are target-root-relative, which is this Copy's root). The
-    // FEATURE-level trim for rb stays an add-time concern (vendor-tag
-    // rollout, Decision 5).
-    exclude: [/src\//, TEST_CONTROL_EXCLUDE, ...pluginExcludes(model)],
+    // The generate-time trim: a declared feature that is off, and an inactive
+    // plugin group, whose `path` entries are relative to this Copy's root.
+    exclude: [/src\//, TEST_CONTROL_EXCLUDE,
+      ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }

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

@@ -15,6 +15,8 @@ import type {
   Model,
 } from '@voxgig/apidef'
 
+import { formatRubyValue } from './utility_rb'
+
 
 const Package = cmp(async function Package(props: any) {
   const ctx$ = props.ctx$
@@ -40,7 +42,7 @@ const Package = cmp(async function Package(props: any) {
     Content(`Gem::Specification.new do |spec|
   spec.name          = "${gemName}"
   spec.version       = "${packageVersion(model, target.name)}"
-  spec.authors       = ["${author.name}"]
+  spec.authors       = [${formatRubyValue(author.name)}]
   spec.summary       = "${pkgDescription(model, target.name)}"
   spec.description   = "${pkgDescription(model, target.name)}"
   spec.license       = "MIT"

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

@@ -38,7 +38,7 @@ function render(spec: {
 }): string {
   const head = `# ${spec.Name} SDK utility: prepare_auth
 require_relative 'struct/voxgig_struct'
-module ${spec.Name}Utilities
+${'cookie' === spec.where ? "require_relative 'prepare_headers'\n" : ''}module ${spec.Name}Utilities
 `
 
   const guard = `  PrepareAuth = ->(ctx) {
@@ -93,12 +93,12 @@ end
     : `    headers = spec.headers
 `
 
-  const dropCookie = !cookie ? '' : `
-    # Our own pair, and only ours: another cookie the caller set survives.
-    drop_cookie = ->(hs) {
+  const setCookie = !cookie ? '' : `
+    # The named pair, and only that one: another cookie the caller set survives.
+    set_cookie = ->(hs, cname, value) {
       cookie = hs[HEADER_COOKIE]
-      return unless cookie.is_a?(String)
-      rest = cookie.split("; ").reject { |pair| pair.start_with?("#{COOKIE_AUTH}=") }
+      rest = cookie.is_a?(String) ? ${spec.Name}Utilities.cookie_keep(cookie, [cname]) : []
+      rest << "#{cname}=#{value}" unless value.nil?
       if rest.empty?
         hs.delete(HEADER_COOKIE)
       else
@@ -107,19 +107,26 @@ end
     }
 `
 
-  const clear = cookie ? 'drop_cookie.call(headers)'
-    : query ? `query.delete(${CRED})`
-      : `headers.delete(${CRED})`
+  const clear = (name: string) => cookie ? `set_cookie.call(headers, ${name}, nil)`
+    : query ? `query.delete(${name})`
+      : `headers.delete(${name})`
 
   const preamble = guard + `
 ` + bag + `    options = ctx.client.options_map
-` + dropCookie + `
+` + setCookie + `
     # Public APIs that need no auth omit the options.auth block entirely.
     if options["auth"].nil?
-      ${clear}
+      ${clear(CRED)}
       return spec, nil
     end
 
+    # The client's auth.name option, when set, replaces the name the API declares.
+    auth_name = VoxgigStruct.getpath(options, "auth.name")
+    name = auth_name.is_a?(String) && !auth_name.empty? ? auth_name${query || cookie ? '' : '.downcase'} : ${CRED}
+
+    # A credential left under the declared name would travel beside the renamed one.
+    ${clear(CRED)} unless name == ${CRED}
+
     apikey = VoxgigStruct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 `
 
@@ -135,7 +142,7 @@ end
       no_secret = secret.nil? || !secret.is_a?(String) || secret == NOT_FOUND || secret == ""
 
       if no_apikey
-        headers.delete(HEADER_AUTH)
+        headers.delete(name)
       else
         auth_prefix = VoxgigStruct.getpath(options, "auth.prefix") || ""
         # \`pack("m0")\` rather than \`Base64.strict_encode64\`: base64 left
@@ -144,7 +151,7 @@ end
         # The joined, encoded pair is a wire form neither credential's own
         # registration covers.
         ctx.utility.clean_add.call(ctx, b64)
-        headers[HEADER_AUTH] =
+        headers[name] =
           auth_prefix.empty? ? b64 : "#{auth_prefix} #{b64}"
       end
 
@@ -152,7 +159,7 @@ end
     end
 `
 
-  return head + consts + preamble + basicBlock + place(spec.where, clear) + `
+  return head + consts + preamble + basicBlock + place(spec.where, clear('name')) + `
     return spec, nil
   }
 end
@@ -171,26 +178,21 @@ function place(where: string, clear: string): string {
       apikey_val = apikey.is_a?(String) ? apikey : ""
       # NO PREFIX IN A QUERY STRING: \`?token=Bearer%20abc\` is not a thing
       # any API reads, so options.auth.prefix is dropped rather than joined.
-      query[QUERY_AUTH] = apikey_val
+      query[name] = apikey_val
     end
 `
   }
 
   if ('cookie' === where) {
     return `
-    # Dropped before writing, so a retry cannot accumulate the pair and a
-    # withdrawn credential leaves no stale cookie behind.
-    ${clear}
-
-    unless apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
+    if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
+      ${clear}
+    else
       apikey_val = apikey.is_a?(String) ? apikey : ""
-      # A cookie IS a header, so the pair is appended to the cookie header
-      # rather than clobbering it. No prefix: \`token=Bearer abc\` is not a
-      # cookie value any API reads.
-      existing = headers[HEADER_COOKIE]
-      pair = "#{COOKIE_AUTH}=#{apikey_val}"
-      headers[HEADER_COOKIE] =
-        (existing.is_a?(String) && !existing.empty?) ? "#{existing}; #{pair}" : pair
+      # Spliced in, replacing an earlier pair of the same name, so a retry
+      # cannot accumulate it. No prefix: \`token=Bearer abc\` is not a cookie
+      # value any API reads.
+      set_cookie.call(headers, name, apikey_val)
     end
 `
   }
@@ -202,7 +204,7 @@ function place(where: string, clear: string): string {
       auth_prefix = VoxgigStruct.getpath(options, "auth.prefix") || ""
       apikey_val = apikey.is_a?(String) ? apikey : ""
       # Empty prefix (raw apiKey credential) must not add a leading space.
-      headers[HEADER_AUTH] =
+      headers[name] =
         auth_prefix.empty? ? apikey_val : "#{auth_prefix} #{apikey_val}"
     end
 `

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, safeVarName, exampleVarName, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -25,6 +25,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
   create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
   update: { method: 'update(data)',  desc: 'Update an existing entity.' },
+  patch:  { method: 'patch(data)',   desc: 'Change part of an existing entity.' },
   remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
 }
 
@@ -50,6 +51,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     const idF = entityIdField(entity)
     // Sanitise the local variable name — an entity whose lowercased name is a
@@ -106,7 +109,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       const loadItems = opRequestShape(entity, 'load').items
         .filter((it: any) => !it.optional || it.name === idF)
         .sort((a: any, b: any) =>
@@ -126,18 +129,19 @@ ${eVar} = client.${entity.Name}.load(${loadArg})
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`ruby
-# list returns an Array of ${entity.Name} records (raises on error).
+# list returns an Array of ${entity.Name} entities, one per record (raises on error).
 ${eVar}s = client.${entity.Name}.list
+${eVar}s.each { |item| puts item.data_get }
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // 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

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

@@ -33,7 +33,7 @@ const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
 #   1. SYNTAX — 'ruby -c' on every block. Every documented ruby example must
 #      parse.
 #   2. RUN — every RUNNABLE block (one that constructs the SDK, drives client.,
-#      or performs an entity op load/list/create/update/remove) is EXECUTED
+#      or performs an entity op load/list/create/update/patch/remove) is EXECUTED
 #      offline in seeded test mode (${model.const.Name}SDK.test) against the real
 #      SDK. The captured output is scanned for a real Ruby-level error (undefined
 #      method, wrong number of arguments, NameError, ...) REGARDLESS of exit
@@ -75,6 +75,10 @@ ${entityLines}
   # signature/method-table "illustration" class.
   METHODS = %w[options_map get_utility prepare direct data_get data_set match_get match_set make get_name]
 
+  # The client VARIABLE, not the word: a gem or package name carries the word
+  # between hyphens (voxgig-sdk-multifon-client-sdk).
+  CLIENT = /(?<![\\w\\-.\\/"'])client(?![\\w\\-\\/"'])/
+
   # Ruby-level errors that indicate a real bug in a documented example (as
   # opposed to an expected not-found / domain error, which is tolerated).
   FATAL = /NoMethodError|NameError|ArgumentError|undefined method|undefined local variable|uninitialized constant|wrong number of arguments/
@@ -102,8 +106,8 @@ ${entityLines}
   # an entity operation. Every runnable block MUST be executed.
   def runnable?(b)
     b =~ /#{Regexp.escape(SDK_CLASS)}\\.(?:new|test)\\b/ ||
-      b =~ /\\bclient\\./ ||
-      b =~ /\\.(?:load|list|create|update|remove)\\b/ ? true : false
+      b =~ /#{CLIENT}\\./ ||
+      b =~ /\\.(?:load|list|create|update|patch|remove)\\b/ ? true : false
   end
 
   # A block "mentions the SDK" when it references the client variable, the SDK
@@ -111,9 +115,9 @@ ${entityLines}
   # mentions the SDK but is not a signature illustration is an uncovered
   # runnable-looking block and must fail the completeness gate.
   def looks_sdk?(b)
-    return true if b =~ /\\bclient\\b/
+    return true if b =~ CLIENT
     return true if b =~ /\\b#{Regexp.escape(SDK_CLASS)}\\b/
-    return true if b =~ /\\.(?:load|list|create|update|remove)\\b/
+    return true if b =~ /\\.(?:load|list|create|update|patch|remove)\\b/
     ENTITIES.each_key { |name| return true if b =~ /\\.#{Regexp.escape(name)}\\b/ }
     false
   end
@@ -124,7 +128,7 @@ ${entityLines}
   # catch-all — so an unexecuted block that uses a client variable cannot hide here.
   def illustration?(b)
     return false if runnable?(b)
-    return false if b =~ /\\bclient\\b/
+    return false if b =~ CLIENT
     return true if b =~ /\\b#{Regexp.escape(SDK_CLASS)}\\b/
     METHODS.each { |m| return true if b =~ /\\b#{Regexp.escape(m)}\\s*\\(/ }
     false
@@ -152,6 +156,7 @@ ${entityLines}
         f.write(blk[:code])
         f.flush
         out, status = Open3.capture2e("ruby", "-c", f.path)
+        out.force_encoding(Encoding::UTF_8)
         failures << "#{blk[:doc]} ##{blk[:n]}:\\n#{out}\\n#{blk[:code]}" unless status.success?
       end
     end
@@ -161,7 +166,7 @@ ${entityLines}
   # Build the SDK 'entity' fixture option (as Ruby source) for the entities a
   # block references, falling back to seeding all entities when none are named.
   def fixtures_literal(block)
-    refs = ENTITIES.select { |name, _| block =~ /\\bclient\\.#{Regexp.escape(name)}\\b/ }
+    refs = ENTITIES.select { |name, _| block =~ /#{CLIENT}\\.#{Regexp.escape(name)}\\b/ }
     refs = ENTITIES if refs.empty?
     entity = {}
     refs.each_value { |storage| entity[storage] = { "test01" => { "id" => "test01" } } }
@@ -224,12 +229,15 @@ ${entityLines}
         driver = File.join(dir, "_driver.rb")
         File.write(driver, batch_driver(paths))
         out, status = Open3.capture2e("ruby", driver)
+        # A pipe is tagged with the locale's encoding; the snippets wrote UTF-8.
+        out.force_encoding(Encoding::UTF_8)
 
         runnable.each_with_index do |blk, i|
           seg = batch_segment(out, i)
           code = status.exitstatus
           if seg.nil?
             solo, sstatus = Open3.capture2e("ruby", paths[i])
+            solo.force_encoding(Encoding::UTF_8)
             seg = solo
             code = sstatus.exitstatus
           end
@@ -264,7 +272,7 @@ ${entityLines}
         puts
         puts "@@VOXBEGIN \\#{i}"
         begin
-          Module.new.module_eval(File.read(path), path)
+          Module.new.module_eval(File.read(path, encoding: "UTF-8"), path)
         rescue Exception => e
           puts "FATAL: \\#{e.class}: \\#{e.message}"
         end

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

@@ -45,7 +45,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     testCallArg = 0 < items.length
       ? `{ ${items.map((it: any) => `"${it.name}" => ${it.name === idF ? '"test01"' : rbLit(it.type)}`).join(', ')} }`
       : ''
-  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
+  } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')
     const required = items.filter((it: any) => !it.optional)

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

@@ -29,9 +29,9 @@ bundle install
 
   // Publish pending: not yet on RubyGems. Install from the git release tag,
   // or from a clone through Bundler, since a tag may not exist.
-  const { releasesUrl, repoUrl, repo } = repoInfo(model)
+  const { hostName, tagsUrl, repoUrl, repo } = repoInfo(model)
   Content(`This package is not yet published to RubyGems. Install it from the
-GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})), or
+${hostName} release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})), or
 from a clone:
 
 \`\`\`bash

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,7 +10,7 @@ import {
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
-  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const info = modelText(model)
   const tagline = info.tagline || ''
 
   // Derive a representative entity (and its operations) from the model so the
@@ -21,7 +21,7 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   // Model-driven op list — union of the operations the active entities
   // actually expose (a read-only entity has just list+load), in canonical
   // order; never claim create/update/remove exist when no entity has them.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'patch', 'remove']
   const opSet = new Set<string>()
   Object.values(entity || {}).forEach((e: any) => {
     if (!e || e.active === false) return

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

@@ -22,12 +22,13 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     .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. |',
+    list: '| `list` | `(reqmatch = nil, ctrl) -> Array` | List entities matching the criteria (call with no argument to list all). Resolves to one entity per record. 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. |',
+    patch: '| `patch` | `(reqdata, ctrl) -> any` | Change part of an existing entity. Raises on error. |',
     remove: '| `remove` | `(reqmatch, ctrl) -> any` | Remove an entity. Raises on error. |',
   }
-  const opRows = ['load', 'list', 'create', 'update', 'remove']
+  const opRows = ['load', 'list', 'create', 'update', 'patch', 'remove']
     .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
 
   const apikeyOptionRow = isAuthActive(model)

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

@@ -71,18 +71,19 @@ client = ${ctor}
       fields.find((f: any) => f && f.n !== 'id' && f.t === '$STRING') ||
       fields.find((f: any) => f && f.n !== 'id') ||
       null
-    const idCol = dataIdF ? `#{item[${JSON.stringify(dataIdF)}]}` : null
-    const dispCol = displayField ? `#{item[${JSON.stringify(displayField.n)}]}` : null
-    const itemPrint = [idCol, dispCol].filter(Boolean).join(' ') || '#{item}'
+    const idCol = dataIdF ? `#{record[${JSON.stringify(dataIdF)}]}` : null
+    const dispCol = displayField ? `#{record[${JSON.stringify(displayField.n)}]}` : null
+    const itemPrint = [idCol, dispCol].filter(Boolean).join(' ') || '#{record}'
 
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
 \`\`\`ruby
 begin
-  # list returns an Array of ${eName} records — iterate directly.
+  # list returns an Array of ${eName} entities, one per record; data_get reads the record.
   ${eVar}s = client.${eName}.list
   ${eVar}s.each do |item|
+    record = item.data_get
     puts "${itemPrint}"
   end
 rescue => err
@@ -175,7 +176,8 @@ end
       ? `created.data_get["${dataIdF}"]`
       : rbLit(idParamType(opname), 'example_id')
 
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`ruby
@@ -192,6 +194,13 @@ created = client.${eName}.create({ ${examplePairs('create').join(', ')} })
         Content(`# Update${fromCreated ? ` — index the record via data_get (created.data_get["${dataIdF}"]).` : ''}
 client.${eName}.update({ ${updatePairs.join(', ')} })
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`"${idF}" => ${idValueFor('patch')}`] : []).concat(examplePairs('patch'))
+        Content(`# Patch — sends only the fields given
+client.${eName}.patch({ ${patchPairs.join(', ')} })
+
 `)
       }
       if (opnames.includes('remove')) {