@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/src/cmp/ts/PrepareAuth_ts.ts

@@ -36,7 +36,8 @@ function render(spec: {
 }): string {
   const head = `
 import { Context, Spec } from '../types'
-
+` + ('cookie' === spec.where && !spec.suppressed ? `import { cookieKeep } from './PrepareHeadersUtility'
+` : '') + `
 `
 
 
@@ -73,6 +74,12 @@ const OPTION_secret = 'secret'
 const NOTFOUND = '__NOTFOUND__'
 
 
+// The client's \`auth.name\` option, when set, replaces the name the API declares.
+function credName(name: any): string {
+  return 'string' === typeof name && '' !== name ? ${caseFold(spec.where, 'name')} : CRED_name
+}
+
+
 function prepareAuth(ctx: Context): Spec | Error {
   const utility = ctx.utility
 
@@ -94,11 +101,17 @@ ${cookieHelper(spec.where)}
 
   // Public APIs that need no auth omit the options.auth block entirely.
   if (null == options.auth) {
-    ${clear(spec.where)}
+    ${clear(spec.where, 'CRED_name')}
     return spec
   }
 
   const prefix = options.auth.prefix
+  const name = credName(options.auth.name)
+
+  // A credential left under the declared name would travel beside the renamed one.
+  if (CRED_name !== name) {
+    ${clear(spec.where, 'CRED_name')}
+  }
 
   const apikey = getprop(options, OPTION_apikey, NOTFOUND)
 `
@@ -119,14 +132,14 @@ ${cookieHelper(spec.where)}
     const pass = NOTFOUND === secret || null == secret ? '' : secret
 
     if (noApikey) {
-      delprop(headers, CRED_name)
+      delprop(headers, name)
     }
     else {
       const b64 = Buffer.from(apikey + ':' + pass).toString('base64')
       // The joined, encoded pair is a wire form neither credential's own
       // registration covers.
       utility.cleanAdd(ctx, b64)
-      setprop(headers, CRED_name, prefix ? prefix + ' ' + b64 : b64)
+      setprop(headers, name, prefix ? prefix + ' ' + b64 : b64)
     }
 
     return spec
@@ -135,10 +148,10 @@ ${cookieHelper(spec.where)}
 
   return head + preamble + basicBlock + `
   if (NOTFOUND === apikey || null == apikey || '' === apikey) {
-    ${clear(spec.where)}
+    ${clear(spec.where, 'name')}
   }
   else {
-${place(spec.where)}
+${place(spec.where, 'name')}
   }
 
   return spec
@@ -157,18 +170,24 @@ function target(where: string): string {
 }
 
 
+// Header names travel lower-cased; query and cookie names are case-sensitive.
+function caseFold(where: string, expr: string): string {
+  return 'header' === where ? expr + '.toLowerCase()' : expr
+}
+
+
 // A cookie has no header of its own: place() writes it into `cookie` as
-// `CRED_name=value`, so clear() must free that slot, not CRED_name.
-function clear(where: string): string {
+// `name=value`, so clear() frees that pair, not a header of that name.
+function clear(where: string, name: string): string {
   if ('query' === where) {
-    return 'delprop(query, CRED_name)'
+    return `delprop(query, ${name})`
   }
 
   if ('cookie' === where) {
-    return 'cookieSet(headers, null)'
+    return `cookieSet(headers, ${name}, null)`
   }
 
-  return 'delprop(headers, CRED_name)'
+  return `delprop(headers, ${name})`
 }
 
 
@@ -178,22 +197,12 @@ function cookieHelper(where: string): string {
   }
 
   return `
-  function cookieSet(headers: any, value: any) {
+  function cookieSet(headers: any, name: string, value: any) {
     const existing = getprop(headers, COOKIE_header, '')
-    const kept: string[] = []
-
-    if ('string' === typeof existing && '' !== existing) {
-      for (const part of existing.split(';')) {
-        const piece = part.trim()
-        if ('' === piece || piece === CRED_name || piece.startsWith(CRED_name + '=')) {
-          continue
-        }
-        kept.push(piece)
-      }
-    }
+    const kept: string[] = 'string' === typeof existing ? cookieKeep(existing, [name]) : []
 
     if (null != value) {
-      kept.push(CRED_name + '=' + value)
+      kept.push(name + '=' + value)
     }
 
     if (0 === kept.length) {
@@ -207,18 +216,18 @@ function cookieHelper(where: string): string {
 }
 
 
-function place(where: string): string {
+function place(where: string, name: string): string {
   if ('query' === where) {
-    return `    setprop(query, CRED_name, apikey)`
+    return `    setprop(query, ${name}, apikey)`
   }
 
   if ('cookie' === where) {
-    return `    cookieSet(headers, apikey)`
+    return `    cookieSet(headers, ${name}, apikey)`
   }
 
   return `    // A raw credential (empty prefix, e.g. an apiKey scheme) must go in
     // as-is; only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
-    setprop(headers, CRED_name, prefix ? prefix + ' ' + apikey : apikey)`
+    setprop(headers, ${name}, prefix ? prefix + ' ' + apikey : apikey)`
 }
 
 

package/project/.sdk/src/cmp/ts/ReadmeEntity_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -20,6 +20,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.' },
 }
 
@@ -45,6 +46,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 || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
@@ -100,7 +103,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       // The id key plus every REQUIRED match key (parent path params like
       // page_id) — the same shape that generates <Name>LoadMatch, so the
       // example always type-checks.
@@ -122,7 +125,7 @@ const ${eVar} = await client.${entity.Name}().load(${loadArg})
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`ts
@@ -132,7 +135,7 @@ const ${eVar}s = await client.${entity.Name}().list(${listMatchArg(entity)})
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape that generates <Name>CreateData
       // (every required member appears), with a type-correct example VALUE
       // via exampleValue — a `name: /* type */` comment is not a value and

package/project/.sdk/src/cmp/ts/ReadmeExamplesTest_ts.ts

@@ -52,6 +52,7 @@ const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
 import { describe, it } from 'node:test'
 import assert from 'node:assert'
 import * as Fs from 'node:fs'
+import * as Os from 'node:os'
 import * as Path from 'node:path'
 import { createRequire } from 'node:module'
 import { spawnSync } from 'node:child_process'
@@ -61,12 +62,20 @@ import { ${Name}SDK } from '..'
 
 const SDK_NAME = '${Name}SDK'
 
+// The package root, by absolute path: the snippets compile outside the SDK.
+const SDK_ROOT = Path.join(__dirname, '..').split(Path.sep).join('/')
+
 // A fixture for every entity, so list()/load() resolve offline with no
 // network. Snippet client construction is rewritten to seed this.
 const TEST_SEED = ${seedLiteral}
 const SEED_ARG = JSON.stringify(TEST_SEED)
 const SEEDED_CTOR = SDK_NAME + '.test(' + SEED_ARG + ')'
 
+// The client VARIABLE, not the word: a package name carries the word between
+// hyphens (@voxgig-sdk/multifon-client-sdk).
+const CLIENT = /(?<![\\w$.\\-\\/'"\`])client(?![\\w$\\-\\/'"\`])/
+const CLIENT_CALL = new RegExp(CLIENT.source + '\\\\s*\\\\.')
+
 
 // The three docs this gate covers, resolved relative to dist-test/.
 const DOCS: Array<{ label: string; key: string; path: string }> = [
@@ -132,7 +141,7 @@ function isRunnable(code: string): boolean {
   return (
     /new\\s+${Name}SDK\\b/.test(code) ||
     /\\b${Name}SDK\\.test\\b/.test(code) ||
-    /\\bclient\\s*\\./.test(code)
+    CLIENT_CALL.test(code)
   )
 }
 
@@ -142,7 +151,7 @@ function isRunnable(code: string): boolean {
 function buildSnippetModule(block: string): string {
   const inner = stripImports(block).split('\\n').map((l) => '    ' + l).join('\\n')
   return [
-    "import { " + SDK_NAME + " } from '..'",
+    'import { ' + SDK_NAME + ' } from ' + JSON.stringify(SDK_ROOT),
     '',
     'async function __ex() {',
     // Shared client for snippets that reference \`client\` without constructing
@@ -169,20 +178,23 @@ function compileBatch(indices: number[], blocks: string[], key: string): {
   errored: Set<number>; raw: string; unattributed: boolean
 } {
   const tsDir = Path.join(__dirname, '..')
-  const testDir = Path.join(tsDir, 'test')
-  // Leading dot: TypeScript wildcard includes skip dot-files, so these temp
-  // files are never swept into the normal build.
+  // Outside the SDK's tree, so a run leaves nothing there even when it is
+  // interrupted. \`.cts\` keeps them CommonJS whatever package.json is above.
+  const dir = Fs.mkdtempSync(Path.join(Os.tmpdir(), 'readme-examples-'))
   const files: string[] = []
 
   try {
     for (const i of indices) {
-      const f = Path.join(testDir, '.examples_' + key + '_snippet' + i + '.gen.ts')
+      const f = Path.join(dir, 'examples_' + key + '_snippet' + i + '.gen.cts')
       Fs.writeFileSync(f, buildSnippetModule(blocks[i]), 'utf8')
       files.push(f)
     }
 
     const requireFrom = createRequire(__filename)
-    const tsc = requireFrom.resolve('typescript/bin/tsc')
+    // Every TypeScript exports its package.json; TypeScript 7 exports no
+    // ./bin/tsc, so the binary is found through the manifest's bin.
+    const tsPackage = requireFrom.resolve('typescript/package.json')
+    const tsc = Path.join(Path.dirname(tsPackage), requireFrom(tsPackage).bin.tsc)
 
     const res = spawnSync(process.execPath, [
       tsc,
@@ -205,7 +217,7 @@ function compileBatch(indices: number[], blocks: string[], key: string): {
 
     if (0 !== res.status) {
       for (const line of raw.split('\\n')) {
-        const m = /_snippet(\\d+)\\.gen\\.ts\\(\\d+,\\d+\\):\\s*error/.exec(line)
+        const m = /_snippet(\\d+)\\.gen\\.cts\\(\\d+,\\d+\\):\\s*error/.exec(line)
         if (null == m) {
           // A genuine error diagnostic not attributable to a snippet file
           // (e.g. inside the SDK itself) is an anomaly.
@@ -220,9 +232,7 @@ function compileBatch(indices: number[], blocks: string[], key: string): {
 
     return { errored, raw, unattributed }
   } finally {
-    for (const f of files) {
-      Fs.rmSync(f, { force: true })
-    }
+    Fs.rmSync(dir, { recursive: true, force: true })
   }
 }
 
@@ -270,7 +280,7 @@ function rewriteForRun(code: string): string {
   let out = stripImports(code)
   out = out.replace(/new\\s+${Name}SDK\\s*\\([^)]*\\)/g, () => SEEDED_CTOR)
   out = out.replace(/${Name}SDK\\.test\\s*\\([^)]*\\)/g, () => SEEDED_CTOR)
-  if (/\\bclient\\b/.test(out) && !/\\b(?:const|let|var)\\s+client\\b/.test(out)) {
+  if (CLIENT.test(out) && !/\\b(?:const|let|var)\\s+client\\b/.test(out)) {
     out = 'const client = ' + SEEDED_CTOR + '\\n' + out
   }
   return out
@@ -281,7 +291,13 @@ function rewriteForRun(code: string): string {
 // test mode. Returns a list of failure descriptions (empty === all passed).
 async function executeBlocks(blocks: string[]): Promise<string[]> {
   const requireFrom = createRequire(__filename)
-  const ts = requireFrom('typescript')
+  // Node strips a snippet's types itself from 22.13; before that TypeScript 5
+  // does, through an API TypeScript 7 no longer ships.
+  const strip = requireFrom('node:module').stripTypeScriptTypes
+  const ts = 'function' === typeof strip ? null : requireFrom('typescript')
+  if (null == strip && 'function' !== typeof ts.transpileModule) {
+    throw new Error('running the examples needs node 22.13 or TypeScript 5 to strip their types')
+  }
 
   const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor
   const silentConsole = { log() {}, error() {}, warn() {}, info() {} }
@@ -299,14 +315,16 @@ async function executeBlocks(blocks: string[]): Promise<string[]> {
       continue
     }
 
-    // Compile the snippet to JS (strips type annotations) so it runs under
-    // node exactly as a real caller would.
-    const js = ts.transpileModule(src, {
-      compilerOptions: {
-        target: ts.ScriptTarget.ES2020,
-        module: ts.ModuleKind.ESNext,
-      },
-    }).outputText
+    // Strip the snippet's types so it runs under node exactly as a real
+    // caller would.
+    const js = null != strip
+      ? strip(src, { mode: 'transform' })
+      : ts.transpileModule(src, {
+        compilerOptions: {
+          target: ts.ScriptTarget.ES2020,
+          module: ts.ModuleKind.ESNext,
+        },
+      }).outputText
 
     let runner: any
     try {

package/project/.sdk/src/cmp/ts/ReadmeHowto_ts.ts

@@ -109,9 +109,6 @@ const result = await client.direct({
   params: { id: 'example' },
 })
 
-if (result instanceof Error) {
-  throw result
-}
 if (result.ok) {
   console.log(result.status)  // 200
   console.log(result.data)    // response body

package/project/.sdk/src/cmp/ts/ReadmeInstall_ts.ts

@@ -19,9 +19,9 @@ ${installCommand(model, target.name)}
   // git release tag instead of a `npm install` that would 404. A repository
   // may have no tag at all, and npm cannot install a subdirectory of a git
   // URL, so a clone is always offered too. It carries the compiled dist/.
-  const { releasesUrl, repoUrl, repo } = repoInfo(model)
-  Content(`This package is not yet published to npm. Install it from the GitHub
-release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})), or from a
+  const { hostName, tagsUrl, repoUrl, repo } = repoInfo(model)
+  Content(`This package is not yet published to npm. Install it from the ${hostName}
+release tag (\`${target.name}/vX.Y.Z\`, see [Tags](${tagsUrl})), or from a
 clone, which carries the compiled \`dist/\`:
 
 \`\`\`bash

package/project/.sdk/src/cmp/ts/ReadmeIntro_ts.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 || ''
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
@@ -20,7 +20,7 @@ const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   // 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/ts/ReadmeModel_ts.ts

@@ -14,7 +14,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   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
+  // load/list/create/update/patch/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>()
@@ -25,12 +25,13 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria. |',
     create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity. |',
     update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity. |',
+    patch: '| `patch` | `patch(reqdata?, ctrl?): Promise<Entity>` | Change part of an existing entity. |',
     remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
   }
-  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 singleOps = ['load', 'create', 'update'].filter((o) => opUnion.has(o))
+  const singleOps = ['load', 'create', 'update', 'patch'].filter((o) => opUnion.has(o))
     .map((o) => '`' + o + '`')
   const retBullets: string[] = []
   if (singleOps.length) {

package/project/.sdk/src/cmp/ts/ReadmeQuick_ts.ts

@@ -158,7 +158,8 @@ try {
     // (opRequestShape), so the snippet always type-checks. Prefer writable
     // non-id fields and render a type-correct literal per field via
     // exampleValue — never a hardcoded field the entity may not have.
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('patch') ||
+      opnames.includes('remove')) {
       const exampleFields = (opname: string): string[] => {
         const items = opRequestShape(exampleEntity, opname).items
           .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
@@ -214,6 +215,14 @@ const created = await client.${eName}().create({${createBody}})
         Content(`// Update${usesCreatedId('update') ? ' — the id comes off the returned entity\'s data()' : ''}
 const updated = await client.${eName}().update({${updateBody}})
 
+`)
+      }
+      if (opnames.includes('patch')) {
+        const patchLines = (idF ? [`  ${idF}: ${idValueFor('patch')},`] : []).concat(exampleFields('patch'))
+        const patchBody = patchLines.length ? '\n' + patchLines.join('\n') + '\n' : ''
+        Content(`// Patch — sends only the fields given${usesCreatedId('patch') ? '; the id comes off the returned entity\'s data()' : ''}
+const patched = await client.${eName}().patch({${patchBody}})
+
 `)
       }
       if (opnames.includes('remove')) {

package/project/.sdk/src/cmp/ts/ReadmeRef_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, canonToType, File, isAuthActive, isHttpBasicAuth, entityIdField, entityActions, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral, targetFeatures } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, isHttpBasicAuth, entityIdField, entityActions, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral, targetFeatures, opNeedsAction, bodyNote } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -37,6 +37,12 @@ const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string
     returns: 'Promise<object>',
     desc: 'Update an existing entity. The data must include the entity `id`.',
   },
+  patch: {
+    sig: 'patch(data: object, ctrl?: object)',
+    returns: 'Promise<object>',
+    desc: 'Change part of an existing entity: only the fields given are sent. ' +
+      'The data must include the entity `id`.',
+  },
   remove: {
     sig: 'remove(match: object, ctrl?: object)',
     returns: 'Promise<void>',
@@ -165,8 +171,10 @@ Make a direct HTTP request to any API endpoint.
 | \`fetchargs.headers\` | \`object\` | Request headers (merged with defaults). |
 | \`fetchargs.body\` | \`any\` | Request body (objects are JSON-serialized). |
 | \`fetchargs.ctrl\` | \`object\` | Control options (e.g. \`{ explain: true }\`). |
+| \`fetchargs.ctrl.signal\` | \`AbortSignal\` | Aborts the request in flight: \`ok\` is then \`false\` and \`err.code\` is \`request_aborted\`. |
 
-**Returns:** \`Promise<{ ok, status, headers, data } | Error>\`
+**Returns:** \`Promise<{ ok, status, headers, data }>\`. On a failure
+\`ok\` is \`false\` and \`err\` holds the error.
 
 #### \`prepare(fetchargs?: object)\`
 
@@ -181,6 +189,15 @@ Alias for \`${model.Name}SDK.test()\`.
 
 **Returns:** \`${model.Name}SDK\` instance in test mode.
 
+#### Cancelling a call
+
+Every entity operation takes an optional \`ctrl\` object after its match or
+data, and an \`AbortSignal\` in \`ctrl.signal\` cancels the request in flight.
+The operation then rejects with an error whose \`code\` is
+\`request_aborted\` and whose \`cause\` is the signal's reason. A request
+whose signal has already aborted is not sent. \`stream()\` takes the signal
+as \`callopts.signal\`, and ends when it aborts.
+
 `)
 
 
@@ -235,7 +252,7 @@ const ${eVar} = client.${ent.Name}()
         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']
+          const opcols = ['load', 'list', 'create', 'update', 'patch', 'remove']
             .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
@@ -306,6 +323,10 @@ ${info.desc}
 
 `)
 
+          if (opNeedsAction(ent.op[opname])) {
+            return
+          }
+
           // Show example
           if ('load' === opname || 'remove' === opname) {
             // The id key plus every REQUIRED match key (parent path params
@@ -352,24 +373,32 @@ const result = await client.${ent.Name}().create({
 
 `)
           }
-          else if ('update' === opname) {
+          else if ('update' === opname || 'patch' === opname) {
             // The id key plus every REQUIRED data member — the same shape
             // that generates <Name>UpdateData — then the patch-fields note.
-            const updateItems = opRequestShape(ent, 'update').items
+            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))
             const updateLines = updateItems.map((it: any) =>
-              `  ${jsKey(it.name)}: ${exampleValue(ent, ent.op && ent.op.update, it.name,
+              `  ${jsKey(it.name)}: ${exampleValue(ent, ent.op && ent.op[opname], it.name,
                 it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
             Content(`\`\`\`ts
-const result = await client.${ent.Name}().update({
-${updateLines}  // Fields to update
+const result = await client.${ent.Name}().${opname}({
+${updateLines}  // ${'patch' === opname ? 'Only the fields to change' : 'Fields to update'}
 })
 \`\`\`
 
 `)
           }
+
+          if ('create' === opname || 'update' === opname || 'patch' === opname) {
+            const note = bodyNote(ent.op[opname], {
+              values: 'a `Buffer`, `Uint8Array`, `ArrayBuffer`, `Blob`, stream or string',
+              once: 'a stream',
+            })
+            if ('' !== note) Content(note)
+          }
         })
       }
 

package/project/.sdk/src/cmp/ts/ReadmeTopHowto_ts.ts

@@ -12,10 +12,9 @@ const result = await client.direct({
   method: 'GET',
   params: { id: 'example' },
 })
-if (result instanceof Error) {
-  throw result
+if (result.ok) {
+  console.log(result.data)
 }
-console.log(result.data)
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/ts/ReadmeTopTest_ts.ts

@@ -66,7 +66,7 @@ const client = ${model.const.Name}SDK.test({
           `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
             it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const isIdField = (it: any) => it.name === idF || it.name === 'id'
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => !isIdField(it) || !it.optional)