@voxgig/sdkgen 4.34.0 → 4.34.2

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

@@ -146,38 +146,12 @@ class EntyClass
       end
       begin
         catch(:stream_stop) do
-          utility.feature_hook.call(ctx, "PrePoint")
-          point, err = utility.make_point.call(ctx)
-          ctx.out["point"] = point
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreSpec")
-          spec, err = utility.make_spec.call(ctx)
-          ctx.out["spec"] = spec
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreRequest")
-          resp, err = utility.make_request.call(ctx)
-          ctx.out["request"] = resp
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreResponse")
-          resp2, err = utility.make_response.call(ctx)
-          ctx.out["response"] = resp2
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreResult")
-          result, err = utility.make_result.call(ctx)
-          ctx.out["result"] = result
-          throw :stream_stop if err
-
-          utility.feature_hook.call(ctx, "PreDone")
-
+          failed = _stream_steps(ctx)
           result = ctx.result
 
           # Inbound: prefer the streaming feature's incremental Enumerator;
           # else fall back to the materialised items so stream always yields.
-          stream_enum = result ? result.stream : nil
+          stream_enum = failed.nil? && result ? result.stream : nil
           if stream_enum
             # done does not run on this path, so its record is cleaned here.
             utility.clean_explain.call(ctx)
@@ -186,7 +160,8 @@ class EntyClass
               give.call(item)
             end
           else
-            data = utility.done.call(ctx)
+            # A failed step leaves through make_error, as an operation's does.
+            data = failed.nil? ? utility.done.call(ctx) : utility.make_error.call(ctx, failed)
             items = data.is_a?(Array) ? data : (data.nil? ? [] : [data])
             items.each do |item|
               throw :stream_stop if aborted.call
@@ -197,12 +172,55 @@ class EntyClass
       rescue StandardError => operr
         raise if inblock
         ctx.ctrl.err = operr
+
+        # What a hook raises here must not escape the cleaning below.
+        begin
+          utility.feature_hook.call(ctx, "PreUnexpected")
+        rescue StandardError => hookerr
+          operr = hookerr
+          ctx.ctrl.err = operr
+        end
+
         e = _unexpected(ctx, operr)
         raise e, cause: nil unless e.nil?
       end
     end
   end
 
+  # The steps an operation runs, with their hooks; the first that fails hands
+  # back its error.
+  private def _stream_steps(ctx)
+    utility = @_utility
+
+    utility.feature_hook.call(ctx, "PrePoint")
+    point, err = utility.make_point.call(ctx)
+    ctx.out["point"] = point
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreSpec")
+    spec, err = utility.make_spec.call(ctx)
+    ctx.out["spec"] = spec
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreRequest")
+    resp, err = utility.make_request.call(ctx)
+    ctx.out["request"] = resp
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreResponse")
+    resp2, err = utility.make_response.call(ctx)
+    ctx.out["response"] = resp2
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreResult")
+    result, err = utility.make_result.call(ctx)
+    ctx.out["result"] = result
+    return err if err
+
+    utility.feature_hook.call(ctx, "PreDone")
+    nil
+  end
+
   # #LoadOp
 
   # #ListOp
@@ -211,6 +229,8 @@ class EntyClass
 
   # #UpdateOp
 
+  # #PatchOp
+
   # #RemoveOp
 
   private

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

@@ -7,7 +7,8 @@ require_relative '../core/helpers'
   #
   # @param reqdata [EntityNameCreateData, Hash, nil] body data
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the created EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the created EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
   def create(reqdata, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

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

@@ -5,7 +5,8 @@
   # @param reqmatch [EntityNameListMatch, Hash, nil] match filter (any subset of
   #   EntityName fields); defaults to nil, treated as an empty match that lists all.
   # @param ctrl [Object, nil] optional per-call control
-  # @return [Array<EntityName>, Array] the matching EntityName items; raises ProjectNameError on failure
+  # @return [Array<EntyClass>] the matching EntityName items, one entity per
+  #   record (data_get reads the record); raises ProjectNameError on failure
   def list(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({
@@ -22,16 +23,6 @@
       end
     end
 
-    # list yields the BARE Array of records — each an accessible Hash — so
-    # callers can index item["id"] directly, matching py/lua/go. make_result
-    # wraps each entry as an Entity instance for internal use; unwrap those
-    # back to their bare record Hashes here (load/create/etc. are unaffected).
-    if records.is_a?(Array)
-      records = records.map do |item|
-        item.respond_to?(:data_get) ? item.data_get : item
-      end
-    end
-
     records
   end
 

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

@@ -9,7 +9,8 @@ require_relative '../core/helpers'
   #   optional — an entity with no id-like key loads with no match (nil is treated
   #   as an empty match, so client.EntityName.load works with no args).
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the loaded EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the loaded EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
   def load(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

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

@@ -0,0 +1,32 @@
+require_relative '../utility/struct/voxgig_struct'
+require_relative '../core/helpers'
+
+# EJECT-START
+
+  # Change part of an existing EntityName: only the fields given are sent.
+  #
+  # @param reqdata [EntityNamePatchData, Hash, nil] body data
+  # @param ctrl [Object, nil] optional per-call control
+  # @return [EntyClass] the patched EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
+  def patch(reqdata, ctrl = nil)
+    utility = @_utility
+    ctx = utility.make_context.call({
+      "opname" => "patch",
+      "ctrl" => ctrl,
+      "match" => @_match,
+      "data" => @_data,
+      "reqdata" => reqdata,
+    }, @_entctx)
+
+    _run_op(ctx) do
+      if ctx.result
+        @_match = ctx.result.resmatch if ctx.result.resmatch
+        if ctx.result.resdata
+          @_data = ProjectNameHelpers.to_map(VoxgigStruct.clone(ctx.result.resdata)) || {}
+        end
+      end
+    end
+  end
+
+# EJECT-END

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

@@ -7,7 +7,8 @@ require_relative '../core/helpers'
   #
   # @param reqmatch [EntityNameRemoveMatch, Hash, nil] match criteria (id/query fields)
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the removed EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the removed EntityName entity, marked as deleted; raises
+  #   ProjectNameError on failure
   def remove(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

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

@@ -7,7 +7,8 @@ require_relative '../core/helpers'
   #
   # @param reqdata [EntityNameUpdateData, Hash, nil] body data
   # @param ctrl [Object, nil] optional per-call control
-  # @return [EntityName, Hash] the updated EntityName; raises ProjectNameError on failure
+  # @return [EntyClass] the updated EntityName entity (data_get reads its record);
+  #   raises ProjectNameError on failure
   def update(reqdata, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

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

@@ -121,7 +121,13 @@ class ProjectNameSDK
     path = VoxgigStruct.getprop(fetchargs, "path") || ""
     path = "" unless path.is_a?(String)
     method_val = VoxgigStruct.getprop(fetchargs, "method") || "GET"
-    method_val = "GET" unless method_val.is_a?(String)
+    method_val = "GET" unless method_val.is_a?(String) && "" != method_val
+    method_val = method_val.upcase
+    allow_method = VoxgigStruct.getpath(opts, "allow.method")
+    unless ProjectNameUtilities.allowed(allow_method, method_val)
+      raise ctx.make_error("spec_method_allow",
+        "Method \"#{method_val}\" not allowed by SDK option allow.method value: \"#{allow_method}\"")
+    end
     params = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "params")) || {}
     query = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "query")) || {}
     headers = utility.prepare_headers.call(ctx)
@@ -171,8 +177,7 @@ class ProjectNameSDK
 
   # Is this raw-access op permitted by the SDK's allow.op option?
   def op_allowed?(op)
-    allow_op = VoxgigStruct.getpath(@options, "allow.op")
-    allow_op.is_a?(String) && allow_op.include?(op)
+    ProjectNameUtilities.allowed(VoxgigStruct.getpath(@options, "allow.op"), op)
   end
 
   def op_denied(op)
@@ -232,6 +237,7 @@ class ProjectNameSDK
       no_body = status == 204 || status == 304 || content_length.to_s == "0"
 
       json_data = nil
+      body_err = nil
       unless no_body
         jf = VoxgigStruct.getprop(fetched, "json")
         if jf.is_a?(Proc)
@@ -242,14 +248,22 @@ class ProjectNameSDK
             json_data = nil
           end
         end
+        if true == VoxgigStruct.getprop(fetched, "unreadable")
+          failed = status >= 200 && status < 300 ? nil : ctx.make_error("request_status",
+            "request: #{status}: #{VoxgigStruct.getprop(fetched, 'statusText')}")
+          body_err = ProjectNameUtilities::UnreadableBody.call(ctx, status, headers,
+            VoxgigStruct.getprop(fetched, "body"), fetchdef["headers"], failed)
+        end
       end
 
-      return {
-        "ok" => status >= 200 && status < 300,
+      out = {
+        "ok" => body_err.nil? && status >= 200 && status < 300,
         "status" => status,
         "headers" => headers,
         "data" => json_data,
       }
+      out["err"] = utility.clean.call(ctx, body_err) unless body_err.nil?
+      return out
     end
 
     return {

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

@@ -6,6 +6,15 @@ import {
   walk,
 } from '@voxgig/struct'
 
+import { listMatchArg } from '@voxgig/sdkgen'
+
+
+// A list's required route and query parameters, as its call's arguments.
+function rbListArgs(entity: any): string {
+  const arg = listMatchArg('rb', entity)
+  return '' === arg ? '' : `(${arg})`
+}
+
 
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
@@ -112,4 +121,5 @@ export {
   formatRubyHash,
   formatRubyValue,
   projectPath,
+  rbListArgs,
 }

package/project/.sdk/src/cmp/rust/EntityTypes_rust.ts

@@ -92,7 +92,7 @@ use crate::utility::voxgigstruct::Value;
         )
 
         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/rust/Entity_rust.ts

@@ -39,12 +39,12 @@ 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) => {
-                const arg = ('create' === opname || 'update' === opname) ?
+                const arg = ('create' === opname || 'update' === opname || 'patch' === opname) ?
                   'reqdata' : 'reqmatch'
                 // The stub mirrors the real signature: ops resolve to the
                 // ENTITY (`list` to a vector of them), so an unsupported op

package/project/.sdk/src/cmp/rust/Main_rust.ts

@@ -5,6 +5,7 @@ import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
   entityClassName,
+  inactiveFeatureExcludes,
   pluginExcludes,
   targetFeatures,
   TEST_CONTROL_EXCLUDE
@@ -56,11 +57,10 @@ const Main = cmp(async function Main(props: any) {
   // here exactly like the go target.
   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 rust stays an add-time concern, as go's does.
-    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,
       RUSTCRATE: rustcrate,
@@ -198,7 +198,7 @@ pub use crate::core::context::{Context, CtxSpec, OpMap};
 pub use crate::core::control::Control;
 pub use crate::core::error::${model.const.Name}Error;
 pub use crate::core::helpers::{
-    call_json, call_vfn, ja, jo, json_thunk, unsupported_op, vfn,
+    call_json, call_vfn, getp, ja, jo, json_thunk, to_map, unsupported_op, vfn,
 };
 pub use crate::core::operation::Operation;
 pub use crate::core::point::Point;
@@ -212,6 +212,7 @@ pub use crate::core::types::{
 pub use crate::core::utility_type::Utility;
 pub use crate::feature::base::BaseFeature;
 pub use crate::utility::jsonparse::json_parse;
+pub use crate::utility::media::bytes_value;
 pub use crate::utility::voxgigstruct::Value;
 
 // No-argument convenience constructors: \`${rustcrate}::new()\` /

package/project/.sdk/src/cmp/rust/PrepareAuth_rust.ts

@@ -81,8 +81,6 @@ pub fn prepare_auth_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ${spec.
   // the base64 form of every registered value.
   const withBasic = spec.basic && 'header' === spec.where
 
-  const withGetpath = 'header' === spec.where
-
   const bag = bagName(spec.where)
 
   const head = `// prepare_auth utility.
@@ -96,9 +94,10 @@ use std::rc::Rc;
 
 use crate::core::context::Context;
 use crate::core::error::${spec.errtype};
-use crate::core::helpers::{getp, ${withGetpath ? 'getpath, ' : ''}setp};
+use crate::core::helpers::{getp, getpath, setp};
 use crate::core::spec::Spec;
 ${withBasic ? `use crate::utility::clean::{base64_encode, clean_add};
+` : ''}${'cookie' === spec.where ? `use crate::utility::prepare_headers::cookie_keep;
 ` : ''}use crate::utility::voxgigstruct as vs;
 use crate::utility::voxgigstruct::Value;
 
@@ -109,6 +108,14 @@ ${'cookie' === spec.where ? `const COOKIE_HEADER: &str = "cookie";
 ${withBasic ? `const OPTION_SECRET: &str = "secret";
 ` : ''}const NOT_FOUND: &str = "__NOTFOUND__";
 
+/// The client's \`auth.name\` option, when set, replaces the name the API declares.
+fn auth_name(options: &Value) -> String {
+    match getpath(&["auth", "name"], options) {
+        Value::Str(s) if !s.is_empty() => ${'header' === spec.where ? 's.to_lowercase()' : 's'},
+        _ => CRED_NAME.to_string(),
+    }
+}
+${'cookie' === spec.where ? COOKIE_HELPER : ''}
 pub fn prepare_auth_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ${spec.errtype}> {
     let spec = ctx.spec.borrow().clone().ok_or_else(|| {
         ctx.make_error("auth_no_spec", "Expected context spec property to be defined.")
@@ -123,10 +130,17 @@ pub fn prepare_auth_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ${spec.
     // Public APIs that need no auth omit the options.auth block entirely.
     let auth = getp(&options, "auth");
     if auth.is_noval() || auth.is_null() {
-        ${clear(spec.where)};
+        ${clear(spec.where, 'CRED_NAME')};
         return Ok(spec);
     }
 
+    let name = auth_name(&options);
+
+    // A credential left under the declared name would travel beside the renamed one.
+    if name != CRED_NAME {
+        ${clear(spec.where, 'CRED_NAME')};
+    }
+
     let apikey = vs::get_prop(&options, &Value::str(OPTION_APIKEY), Value::str(NOT_FOUND));
 
     let skip = match &apikey {
@@ -152,7 +166,7 @@ pub fn prepare_auth_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ${spec.
         };
 
         if skip {
-            vs::del_prop(headers, &Value::str(CRED_NAME));
+            ${clear(spec.where, '&name')};
         } else {
             let apikey_val = match &apikey {
                 Value::Str(s) => s.clone(),
@@ -173,11 +187,11 @@ pub fn prepare_auth_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ${spec.
             };
             // Empty prefix (raw apiKey credential) must not add a leading space.
             if auth_prefix.is_empty() {
-                setp(&headers, CRED_NAME, Value::str(b64));
+                setp(&headers, &name, Value::str(b64));
             } else {
                 setp(
                     &headers,
-                    CRED_NAME,
+                    &name,
                     Value::str(format!("{} {}", auth_prefix, b64)),
                 );
             }
@@ -189,7 +203,7 @@ pub fn prepare_auth_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ${spec.
 
   const tail = `
     if skip {
-        ${clear(spec.where)};
+        ${clear(spec.where, '&name')};
     } else {
 ${place(spec.where)}
     }
@@ -223,9 +237,35 @@ function bagName(where: string): string {
 }
 
 
-function clear(where: string): string {
-  return `vs::del_prop(${bagName(where)}, &Value::str(CRED_NAME))`
+// A cookie credential is a pair inside the `cookie` header, not a header.
+function clear(where: string, name: string): string {
+  if ('cookie' === where) {
+    return `set_cookie(&headers, ${name}, None)`
+  }
+  return `vs::del_prop(${bagName(where)}.clone(), &Value::str(${name}))`
+}
+
+
+// The caller's other cookies stay; only the credential's pair is spliced.
+const COOKIE_HELPER = `
+/// Rewrites the cookie header with the named pair removed, then set to the
+/// value when there is one; every other cookie is kept in order.
+fn set_cookie(headers: &Value, name: &str, value: Option<&str>) {
+    let existing = match getp(headers, COOKIE_HEADER) {
+        Value::Str(s) => s,
+        _ => String::new(),
+    };
+    let mut kept = cookie_keep(&existing, &[name.to_string()]);
+    if let Some(value) = value {
+        kept.push(format!("{}={}", name, value));
+    }
+    if kept.is_empty() {
+        vs::del_prop(headers.clone(), &Value::str(COOKIE_HEADER));
+    } else {
+        setp(headers, COOKIE_HEADER, Value::str(kept.join("; ")));
+    }
 }
+`
 
 
 function place(where: string): string {
@@ -235,7 +275,7 @@ function place(where: string): string {
             _ => String::new(),
         };
         // No prefix: a query parameter carries the raw credential.
-        setp(&query, CRED_NAME, Value::str(apikey_val));`
+        setp(&query, &name, Value::str(apikey_val));`
   }
 
   if ('cookie' === where) {
@@ -243,22 +283,9 @@ function place(where: string): string {
             Value::Str(s) => s.clone(),
             _ => String::new(),
         };
-        let pair = format!("{}={}", CRED_NAME, apikey_val);
-        // APPEND: the cookie header may already carry pairs this SDK did not
-        // set, and replacing it outright would drop them.
-        let existing = match getp(&headers, COOKIE_HEADER) {
-            Value::Str(s) => s,
-            _ => String::new(),
-        };
-        if existing.is_empty() {
-            setp(&headers, COOKIE_HEADER, Value::str(pair));
-        } else {
-            setp(
-                &headers,
-                COOKIE_HEADER,
-                Value::str(format!("{}; {}", existing, pair)),
-            );
-        }`
+        // Spliced in, replacing an earlier pair of the same name, beside any
+        // cookie the caller set.
+        set_cookie(&headers, &name, Some(apikey_val.as_str()));`
   }
 
   return `        let auth_prefix = match getpath(&["auth", "prefix"], &options) {
@@ -271,11 +298,11 @@ function place(where: string): string {
         };
         // Empty prefix (raw apiKey credential) must not add a leading space.
         if auth_prefix.is_empty() {
-            setp(&headers, CRED_NAME, Value::str(apikey_val));
+            setp(&headers, &name, Value::str(apikey_val));
         } else {
             setp(
                 &headers,
-                CRED_NAME,
+                &name,
                 Value::str(format!("{} {}", auth_prefix, apikey_val)),
             );
         }`

package/project/.sdk/src/cmp/rust/ReadmeEntity_rust.ts

@@ -1,12 +1,12 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
-import { rustVarName, rustMethodName } from './utility_rust'
+import { rustVarName, rustMethodName, rustListMatch } from './utility_rust'
 
 
 // Type names come from the shared canonToType 'rust' column (single source of truth).
@@ -14,6 +14,7 @@ import { rustVarName, rustMethodName } from './utility_rust'
 // A type-correct rust expression constructing a voxgig struct Value.
 function rustLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'Value::Null'
   if ('INTEGER' === k || 'NUMBER' === k) return 'Value::Num(1.0)'
   if ('BOOLEAN' === k) return 'Value::Bool(true)'
   if ('ARRAY' === k) return 'Value::empty_list()'
@@ -24,11 +25,12 @@ function rustLit(type: any, placeholder: string = 'example'): string {
 
 // Operation method descriptions (language-agnostic wording, rust signatures).
 const OP_DESC: Record<string, { method: string, desc: string }> = {
-  load:   { method: 'load(reqmatch, ctrl)',   desc: 'Load a single entity by match criteria.' },
-  list:   { method: 'list(reqmatch, ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
-  create: { method: 'create(reqdata, ctrl)',  desc: 'Create a new entity with the given data.' },
-  update: { method: 'update(reqdata, ctrl)',  desc: 'Update an existing entity.' },
-  remove: { method: 'remove(reqmatch, ctrl)', desc: 'Remove the matching entity.' },
+  load:   { method: 'load(reqmatch, ctrl)',   desc: 'Load a single entity by match criteria. `Ok` is the entity.' },
+  list:   { method: 'list(reqmatch, ctrl)',   desc: 'List entities, optionally matching the given criteria. `Ok` is a `Vec` of entities, one per record.' },
+  create: { method: 'create(reqdata, ctrl)',  desc: 'Create a new entity with the given data. `Ok` is the entity.' },
+  update: { method: 'update(reqdata, ctrl)',  desc: 'Update an existing entity. `Ok` is the entity.' },
+  patch:  { method: 'patch(reqdata, ctrl)',  desc: 'Change part of an existing entity. `Ok` is the entity.' },
+  remove: { method: 'remove(reqmatch, ctrl)', desc: 'Remove the matching entity. `Ok` is the entity, marked as deleted.' },
 }
 
 
@@ -53,6 +55,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)
     const eVar = rustVarName(entity.name)
@@ -108,7 +112,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) =>
@@ -122,22 +126,26 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
 \`\`\`rust
 let ${eVar} = client.${method}(Value::Noval).load(${loadArg}, Value::Noval).unwrap();
+println!("{:?}", ${eVar}.data(None));
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`rust
-let ${eVar}s = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
+let ${eVar}s = client.${method}(Value::Noval).list(${rustListMatch(entity)}, Value::Noval).unwrap();
+for ${eVar} in &${eVar}s {
+    println!("{:?}", ${eVar}.data(None));
+}
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       const createItems = opRequestShape(entity, 'create').items
         .filter((it: any) => !it.optional)
       Content(`#### Example: Create