@voxgig/sdkgen 4.33.0 → 4.34.1

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,5 +1,5 @@
 
-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,
@@ -24,11 +24,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 +54,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 +111,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 +125,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();
+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

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

@@ -37,7 +37,7 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   let testArg = 'Value::Noval'
   if (exampleEntity && isMatchOp) {
     testArg = idF ? `jo(vec![("${idF}", Value::str("test01"))])` : 'Value::Noval'
-  } 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)
@@ -48,10 +48,15 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   }
 
   // The op-driven test-mode line. A direct()-only SDK shows a direct() call.
-  const testModeExample = primaryOp
-    ? `// Entity ops return the bare record on Ok and Err on failure.
+  const testModeExample = 'list' === primaryOp
+    ? `// list returns one entity per mock record on Ok, and Err on failure.
+for ${eVar} in client.${method}(Value::Noval).list(${testArg}, Value::Noval).unwrap() {
+    println!("{:?}", ${eVar}.data(None));
+}`
+    : primaryOp
+    ? `// Entity ops return the entity on Ok and Err on failure.
 let ${eVar} = client.${method}(Value::Noval).${primaryOp}(${testArg}, Value::Noval).unwrap();
-// ${eVar} contains the mock response record`
+// ${eVar}.data(None) is the mock response record`
     : `let result = client.direct(jo(vec![
     ("path", Value::str("/api/resource")),
     ("method", Value::str("GET")),
@@ -103,6 +108,8 @@ println!("{:?}", getp(&fetchdef, "headers"));
 Create a mock client for unit testing — no server required:
 
 \`\`\`rust
+use ${rustcrate}::{jo, test_sdk, ${model.const.Name}Entity, Entity, Value};
+
 let client = test_sdk(Value::Noval, Value::Noval);
 
 ${testModeExample}

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

@@ -26,9 +26,9 @@ ${crateName(model)} = { path = "../${target.name}" }
 
   // Publish pending: not yet on crates.io. Depend on the git release tag or
   // on a local source checkout via a path dependency.
-  const { releasesUrl } = repoInfo(model)
-  Content(`This crate is not yet published to crates.io. Depend on it from the GitHub
-release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or
+  const { hostName, tagsUrl } = repoInfo(model)
+  Content(`This crate is not yet published to crates.io. Depend on it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})) or
 from a source checkout by adding it to your \`Cargo.toml\`:
 
 \`\`\`toml

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, modelText } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -11,7 +11,7 @@ import { rustVarName, rustMethodName } from './utility_rust'
 
 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 || ''
 
   Content(`# ${model.Name} ${target.title} SDK
@@ -36,7 +36,7 @@ The ${target.title} SDK for the ${model.Name} API — an entity-oriented client
   // Model-driven op list — only the operations the active entities actually
   // expose (a read-only entity has just list+load); never claim
   // create/update/remove exist when no entity has them.
-  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const 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/rust/ReadmeModel_rust.ts

@@ -22,13 +22,14 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   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: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Load a single entity by match criteria. |',
-    list: '| `list` | `(reqmatch: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | List entities matching the criteria (Ok is a `Value::List`). |',
-    create: '| `create` | `(reqdata: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Create a new entity. |',
-    update: '| `update` | `(reqdata: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Update an existing entity. |',
-    remove: '| `remove` | `(reqmatch: Value, ctrl: Value) -> Result<Value, ' + model.const.Name + 'Error>` | Remove an entity. |',
+    load: '| `load` | `(reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ' + model.const.Name + 'Error>` | Load a single entity by match criteria. |',
+    list: '| `list` | `(reqmatch: Value, ctrl: Value) -> Result<Vec<Rc<Self>>, ' + model.const.Name + 'Error>` | List entities matching the criteria, one per record. |',
+    create: '| `create` | `(reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ' + model.const.Name + 'Error>` | Create a new entity. |',
+    update: '| `update` | `(reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ' + model.const.Name + 'Error>` | Update an existing entity. |',
+    patch: '| `patch` | `(reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ' + model.const.Name + 'Error>` | Change part of an existing entity. |',
+    remove: '| `remove` | `(reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ' + model.const.Name + 'Error>` | Remove an entity, which is returned marked as deleted. |',
   }
-  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)
@@ -96,9 +97,11 @@ ${opRows}
 
 ### Result shape
 
-Entity operations return \`Result<Value, ${model.const.Name}Error>\` — the
-bare result data on \`Ok\` (a \`Value::Map\` for single-entity ops, a
-\`Value::List\` for \`list\`) and the branded error on \`Err\`.
+Entity operations return the entity on \`Ok\`, and \`list\` a \`Vec\` of
+entities, one per record; \`data(None)\` reads an entity's record. \`Err\` is
+the branded error. The operations are methods of the
+\`${model.const.Name}Entity\` trait and \`data\` of the \`Entity\` trait, so
+import both.
 
 The \`direct()\` escape hatch resolves to \`Ok\` even on a non-2xx response —
 it returns a result \`Value::Map\` you branch on via \`getp(&result, "ok")\`:

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

@@ -47,7 +47,7 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   Content(`### 1. Create a client
 
 \`\`\`rust
-use ${rustcrate}::{getp, jo, ${model.const.Name}SDK, Value};
+use ${rustcrate}::{getp, jo, ${model.const.Name}Entity, ${model.const.Name}SDK, Entity, Value};
 
 let client = ${ctor};
 \`\`\`
@@ -68,16 +68,14 @@ let client = ${ctor};
     if (opnames.includes('list')) {
       Content(`### 2. List ${eName.toLowerCase()} records
 
-\`list()\` returns a \`Value::List\` of records and returns \`Err\` on
-failure — match on the \`Result\`.
+\`list()\` returns one entity per record, and \`Err\` on failure — match on
+the \`Result\`. \`data(None)\` reads an entity's record.
 
 \`\`\`rust
 match client.${method}(Value::Noval).list(Value::Noval, Value::Noval) {
     Ok(${eVar}s) => {
-        if let Value::List(items) = &${eVar}s {
-            for ${eVar} in items.borrow().iter() {
-                println!("{:?}", ${eVar});
-            }
+        for ${eVar} in &${eVar}s {
+            println!("{:?}", ${eVar}.data(None));
         }
     }
     Err(err) => eprintln!("list failed: {}", err),
@@ -108,11 +106,12 @@ match client.${method}(Value::Noval).list(Value::Noval, Value::Noval) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the bare record and returns \`Err\` on failure.
+\`load()\` returns the entity, and \`Err\` on failure; \`data(None)\` reads its
+record.
 
 \`\`\`rust
 match client.${neMethod}(Value::Noval).load(jo(vec![${neMatch.join(', ')}]), Value::Noval) {
-    Ok(${neVar}) => println!("{:?}", ${neVar}),
+    Ok(${neVar}) => println!("{:?}", ${neVar}.data(None)),
     Err(err) => eprintln!("load failed: {}", err),
 }
 \`\`\`
@@ -132,11 +131,12 @@ match client.${neMethod}(Value::Noval).load(jo(vec![${neMatch.join(', ')}]), Val
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the bare record and returns \`Err\` on failure.
+\`load()\` returns the entity, and \`Err\` on failure; \`data(None)\` reads its
+record.
 
 \`\`\`rust
 match client.${method}(Value::Noval).load(${loadArg}, Value::Noval) {
-    Ok(${eVar}) => println!("{:?}", ${eVar}),
+    Ok(${eVar}) => println!("{:?}", ${eVar}.data(None)),
     Err(err) => eprintln!("load failed: {}", err),
 }
 \`\`\`
@@ -162,20 +162,21 @@ match client.${method}(Value::Noval).load(${loadArg}, Value::Noval) {
       const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
       return it && it.type
     }
-    // The id VALUE for an update/remove match: read it off the returned
-    // `created` record with getp when its data type carries the id AND a
-    // create ran; otherwise a type-correct literal.
+    // The id VALUE for an update/remove match: read it off the created
+    // entity's record with getp when its data type carries the id AND a create
+    // ran; otherwise a type-correct literal.
     const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
-      ? `getp(&created, "${dataIdF}")`
+      ? `getp(&created.data(None), "${dataIdF}")`
       : rustLit(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
 
 \`\`\`rust
 `)
       if (opnames.includes('create')) {
-        Content(`// Create — returns the bare created record
+        Content(`// Create — returns the created entity
 let created = client.${method}(Value::Noval).create(jo(vec![${examplePairs('create').join(', ')}]), Value::Noval).unwrap();
 
 `)
@@ -185,6 +186,13 @@ let created = client.${method}(Value::Noval).create(jo(vec![${examplePairs('crea
         Content(`// Update
 client.${method}(Value::Noval).update(jo(vec![${updatePairs.join(', ')}]), Value::Noval).unwrap();
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchPairs = (idF ? [`("${idF}", ${idValueFor('patch')})`] : []).concat(examplePairs('patch'))
+        Content(`// Patch — sends only the fields given
+client.${method}(Value::Noval).patch(jo(vec![${patchPairs.join(', ')}]), Value::Noval).unwrap();
+
 `)
       }
       if (opnames.includes('remove')) {

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, canonScalarKey, File, isAuthActive, entityIdField, opRequestShape , targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -36,24 +36,28 @@ const ReadmeRef = cmp(function ReadmeRef(props: any) {
   const errType = `${model.const.Name}Error`
   const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
     load: {
-      sig: `load(reqmatch: Value, ctrl: Value) -> Result<Value, ${errType}>`,
-      desc: 'Load a single entity matching the given criteria. Returns the entity data on `Ok` and `Err` on failure.',
+      sig: `load(reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ${errType}>`,
+      desc: 'Load a single entity matching the given criteria. `Ok` is the entity, whose record `data(None)` reads, and `Err` a failure.',
     },
     list: {
-      sig: `list(reqmatch: Value, ctrl: Value) -> Result<Value, ${errType}>`,
-      desc: 'List entities matching the given criteria. The match is optional — pass `Value::Noval` to list all records. `Ok` is a `Value::List`.',
+      sig: `list(reqmatch: Value, ctrl: Value) -> Result<Vec<Rc<Self>>, ${errType}>`,
+      desc: 'List entities matching the given criteria. The match is optional — pass `Value::Noval` to list all records. `Ok` is a `Vec` of entities, one per record.',
     },
     create: {
-      sig: `create(reqdata: Value, ctrl: Value) -> Result<Value, ${errType}>`,
-      desc: 'Create a new entity with the given data. Returns the created entity data on `Ok` and `Err` on failure.',
+      sig: `create(reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ${errType}>`,
+      desc: 'Create a new entity with the given data. `Ok` is the created entity, and `Err` a failure.',
     },
     update: {
-      sig: `update(reqdata: Value, ctrl: Value) -> Result<Value, ${errType}>`,
-      desc: 'Update an existing entity. The data must include the entity id. Returns the updated entity data on `Ok`.',
+      sig: `update(reqdata: Value, ctrl: Value) -> Result<Rc<Self>, ${errType}>`,
+      desc: 'Update an existing entity. The data must include the entity id. `Ok` is the updated entity.',
+    },
+    patch: {
+      sig: `patch(reqdata: Value, ctrl: Value) -> Result<Value, ${errType}>`,
+      desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity id. Returns the patched entity data on `Ok`.',
     },
     remove: {
-      sig: `remove(reqmatch: Value, ctrl: Value) -> Result<Value, ${errType}>`,
-      desc: 'Remove the entity matching the given criteria. `Err` on failure.',
+      sig: `remove(reqmatch: Value, ctrl: Value) -> Result<Rc<Self>, ${errType}>`,
+      desc: 'Remove the entity matching the given criteria. `Ok` is the entity, marked as deleted, and `Err` a failure.',
     },
   }
 
@@ -72,7 +76,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
 `)
 
     Content(`\`\`\`rust
-use ${rustcrate}::{${model.const.Name}SDK, Value};
+use ${rustcrate}::{jo, ${model.const.Name}Entity, ${model.const.Name}SDK, Entity, Value};
 
 let client = ${model.const.Name}SDK::new(options);
 \`\`\`
@@ -211,7 +215,7 @@ let ${eVar} = client.${method}(Value::Noval);
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         if (hasFieldOps) {
-          const opcols = ['load', 'list', 'create', 'update', 'remove']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -252,6 +256,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           if ('load' === opname || 'remove' === opname) {
             const matchItems = opRequestShape(ent, opname).items
               .filter((it: any) => !it.optional || it.name === idF)
@@ -264,6 +272,7 @@ ${info.desc}
               : 'Value::Noval'
             Content(`\`\`\`rust
 let result = client.${method}(Value::Noval).${opname}(${arg}, Value::Noval).unwrap();
+println!("{:?}", result.data(None));
 \`\`\`
 
 `)
@@ -271,10 +280,8 @@ let result = client.${method}(Value::Noval).${opname}(${arg}, Value::Noval).unwr
           else if ('list' === opname) {
             Content(`\`\`\`rust
 let results = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
-if let Value::List(items) = &results {
-    for ${eVar} in items.borrow().iter() {
-        println!("{:?}", ${eVar});
-    }
+for ${eVar} in &results {
+    println!("{:?}", ${eVar}.data(None));
 }
 \`\`\`
 
@@ -295,8 +302,8 @@ let result = client.${method}(Value::Noval).create(jo(vec![
 
 `)
           }
-          else if ('update' === opname) {
-            const updateItems = opRequestShape(ent, 'update').items
+          else if ('update' === opname || 'patch' === opname) {
+            const updateItems = 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))
@@ -304,13 +311,20 @@ let result = client.${method}(Value::Noval).create(jo(vec![
               `    ("${it.name}", ${rustLit(it.type,
                 it.name === idF ? ent.name + '_id' : it.name)}),\n`).join('')
             Content(`\`\`\`rust
-let result = client.${method}(Value::Noval).update(jo(vec![
-${updateLines}    // Fields to update
+let result = client.${method}(Value::Noval).${opname}(jo(vec![
+${updateLines}    // ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 ]), Value::Noval).unwrap();
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a string, or bytes as `bytes_value(&[u8])`',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

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

@@ -37,7 +37,7 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
     : `${model.const.Name}SDK::new(Value::Noval)`
 
   Content(`\`\`\`rust
-use ${rustcrate}::{jo, ${model.const.Name}SDK, Value};
+use ${rustcrate}::{jo, ${model.const.Name}Entity, ${model.const.Name}SDK, Entity, Value};
 
 let client = ${ctor};
 
@@ -53,12 +53,10 @@ let client = ${ctor};
     const idF = entityIdField(exampleEntity)
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns a Value::List, Err on failure)
+      Content(`// List all ${eName.toLowerCase()}s (one entity per record, Err on failure)
 let ${eVar}s = client.${method}(Value::Noval).list(Value::Noval, Value::Noval).unwrap();
-if let Value::List(items) = &${eVar}s {
-    for ${eVar} in items.borrow().iter() {
-        println!("{:?}", ${eVar});
-    }
+for ${eVar} in &${eVar}s {
+    println!("{:?}", ${eVar}.data(None));
 }
 `)
     }
@@ -77,9 +75,9 @@ if let Value::List(items) = &${eVar}s {
             it.name === idF ? 'example_id' : 'example_' + it.name)})`).join(', ')}])`
         : 'Value::Noval'
       Content(`
-// Load a specific ${eName.toLowerCase()} (returns the record, Err on failure)
+// Load a specific ${eName.toLowerCase()} (returns the entity, Err on failure)
 let ${eVar} = client.${method}(Value::Noval).load(${loadArg}, Value::Noval).unwrap();
-println!("{:?}", ${eVar});
+println!("{:?}", ${eVar}.data(None));
 `)
     }
   }