@voxgig/sdkgen 4.34.0 → 4.34.2

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

@@ -14,23 +14,24 @@ 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>()
   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` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria. |',
-    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. |',
-    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
+    load: '| `load` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria, and return it. |',
+    list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria, one per record. |',
+    create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity, and return it. |',
+    update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity, and return it. |',
+    patch: '| `patch` | `patch(reqdata?, ctrl?): Promise<Entity>` | Change part of an existing entity, and return it. |',
+    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<Entity>` | Remove an entity, and return it 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 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) {
@@ -43,7 +44,7 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     retBullets.push('- `list` resolves to an **array** of entity objects (iterate it directly;\n  there is no `.data` and no `.ok`).')
   }
   if (opUnion.has('remove')) {
-    retBullets.push('- `remove` resolves to `void`.')
+    retBullets.push('- `remove` resolves to the entity, marked as deleted.')
   }
   const returnBullets = retBullets.join('\n')
 
@@ -133,8 +134,8 @@ ${opRows}
 
 #### Return values
 
-Entity operations resolve to the entity data directly — there is no
-result envelope:
+Entity operations resolve to the entity itself — there is no result
+envelope, and an entity's \`data()\` reads its record:
 
 ${returnBullets}
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, isHttpBasicAuth, packageName, envName, serverVariables, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, isHttpBasicAuth, packageName, envName, serverVariables, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,12 +10,6 @@ import {
 import { exampleValue } from './utility_ts'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -80,10 +74,10 @@ resolves to entities, not raw records. Iterate them directly, and call
 \`.data()\` on one for the record it holds:
 
 \`\`\`ts
-const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
+const ${eVar}s = await client.${eName}().list(${listMatchArg('ts', exampleEntity)})
 
 for (const ${eVar} of ${eVar}s) {
-  console.log(${eVar})
+  console.log(${eVar}.data())
 }
 \`\`\`
 
@@ -111,14 +105,14 @@ for (const ${eVar} of ${eVar}s) {
       Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
 
 ${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the entity directly and throws on failure:
+\`load()\` returns the entity and throws on failure; \`.data()\` reads its record:
 
 \`\`\`ts
 try {
   const ${neVar} = await client.${neName}().load({
 ${neMatchLines.join('\n')}
   })
-  console.log(${neVar})
+  console.log(${neVar}.data())
 } catch (err) {
   console.error('load failed:', err)
 }
@@ -139,12 +133,12 @@ ${neMatchLines.join('\n')}
 
       Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
-\`load()\` returns the entity directly and throws on failure:
+\`load()\` returns the entity and throws on failure; \`.data()\` reads its record:
 
 \`\`\`ts
 try {
   const ${eVar} = await client.${eName}().load(${loadArg})
-  console.log(${eVar})
+  console.log(${eVar}.data())
 } catch (err) {
   console.error('load failed:', err)
 }
@@ -158,7 +152,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 +209,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, targetFeatures, opNeedsAction, bodyNote, listMatchArg } from '@voxgig/sdkgen'
 import { ReadmeRefFeatures } from '@voxgig/sdkgen'
 
 import {
@@ -10,37 +10,36 @@ import {
 import { exampleValue } from './utility_ts'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
     sig: 'load(match: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Load a single entity matching the given criteria.',
+    returns: 'Promise<Entity>',
+    desc: 'Load a single entity matching the given criteria. Resolves to the entity, whose record `data()` reads.',
   },
   list: {
     sig: 'list(match: object, ctrl?: object)',
-    returns: 'Promise<object[]>',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    returns: 'Promise<Entity[]>',
+    desc: 'List entities matching the given criteria. Resolves to an array of entities, one per record.',
   },
   create: {
     sig: 'create(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Create a new entity with the given data.',
+    returns: 'Promise<Entity>',
+    desc: 'Create a new entity with the given data. Resolves to the created entity.',
   },
   update: {
     sig: 'update(data: object, ctrl?: object)',
-    returns: 'Promise<object>',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    returns: 'Promise<Entity>',
+    desc: 'Update an existing entity. The data must include the entity `id`. Resolves to the updated entity.',
+  },
+  patch: {
+    sig: 'patch(data: object, ctrl?: object)',
+    returns: 'Promise<Entity>',
+    desc: 'Change part of an existing entity: only the fields given are sent. The data must include the entity `id`. Resolves to the patched entity.',
   },
   remove: {
     sig: 'remove(match: object, ctrl?: object)',
-    returns: 'Promise<void>',
-    desc: 'Remove the entity matching the given criteria.',
+    returns: 'Promise<Entity>',
+    desc: 'Remove the entity matching the given criteria. Resolves to the entity, marked as deleted.',
   },
 }
 
@@ -165,8 +164,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 +182,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 +245,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 +316,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
@@ -328,7 +342,7 @@ const result = await client.${ent.Name}().${opname}(${arg})
           }
           else if ('list' === opname) {
             Content(`\`\`\`ts
-const results = await client.${ent.Name}().${opname}(${listMatchArg(ent)})
+const results = await client.${ent.Name}().${opname}(${listMatchArg('ts', ent)})
 \`\`\`
 
 `)
@@ -352,24 +366,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)
+          }
         })
       }
 
@@ -447,8 +469,6 @@ const client = new ${model.Name}SDK({
 })
 
 
-
-
 export {
   ReadmeRef
 }

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/ReadmeTopQuick_ts.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, isHttpBasicAuth, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral , serverVariables} from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, isHttpBasicAuth, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, serverVariables, listMatchArg } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,12 +10,6 @@ import {
 import { exampleValue } from './utility_ts'
 
 
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
 const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -57,10 +51,10 @@ const client = ${ctor}
     let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}Entity[] — .data() for the record)
-const ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)})
+      Content(`// List all ${eName.toLowerCase()}s (returns ${eName}Entity[], one entity per record)
+const ${eVar}s = await client.${eName}().list(${listMatchArg('ts', exampleEntity)})
 for (const ${eVar} of ${eVar}s) {
-  console.log(${eVar})
+  console.log(${eVar}.data())
 }
 `)
       hasCall = true
@@ -92,19 +86,19 @@ for (const ${eVar} of ${eVar}s) {
             it.name === neIdF ? 'example_id' : 'example_' + it.name)},`)
 
       Content(`
-// Load a specific ${neName.toLowerCase()} (returns a ${neName})
+// Load a specific ${neName.toLowerCase()} (returns the entity, ${/^[aeiou]/i.test(neName) ? 'an' : 'a'} ${neName}Entity)
 const ${neVar} = await client.${neName}().load({
 ${neMatchLines.join('\n')}
 })
-console.log(${neVar})
+console.log(${neVar}.data())
 `)
       hasCall = true
     }
 
     if (!hasCall && opnames.includes('load')) {
-      Content(`// Load ${eName.toLowerCase()} data (returns a ${eName})
+      Content(`// Load a specific ${eName.toLowerCase()} (returns the entity, ${/^[aeiou]/i.test(eName) ? 'an' : 'a'} ${eName}Entity)
 const ${eVar} = await client.${eName}().load()
-console.log(${eVar})
+console.log(${eVar}.data())
 `)
       hasCall = true
     }

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape, requiredItems, safeVarName, exampleVarName, jsKey } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -25,11 +25,22 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
       .slice(0, 3) : []
 
   const seedId = 'test01'
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isIdField = (it: any) => it.name === idF || it.name === 'id'
+
+  // A list matches its required parameters against the record, so the seed
+  // carries the values the call below sends, and an id is the record's key.
+  const listItems = 'list' === primaryOp ? requiredItems(exampleEntity, 'list') : []
+  const listed = (it: any) => listItems.some((li: any) => li.name === it.name)
+  const listLit = (it: any): string => exampleValue(exampleEntity, exampleEntity.op.list,
+    it.name, isIdField(it) ? seedId : 'example_' + it.name)
+
   const seedBody = [
     `${jsKey('id')}: '${seedId}'`,
-    ...seedFields
+    ...[...seedFields, ...listItems.filter((it: any) =>
+      !seedFields.some((sf: any) => sf.name === it.name))]
       .filter((it: any) => 'id' !== it.name)
-      .map((it: any) => `${jsKey(it.name)}: ${exampleValue(
+      .map((it: any) => `${jsKey(it.name)}: ${listed(it) ? listLit(it) : exampleValue(
         exampleEntity, exampleEntity.op && exampleEntity.op.create, it.name,
         'example_' + it.name)}`),
   ].join(', ')
@@ -52,22 +63,23 @@ const client = ${model.const.Name}SDK.test({
     const eVar = exampleVarName(eName.toLowerCase(), 'ts') +
       ('list' === primaryOp ? 's' : '')
     const primaryOpDef = exampleEntity.op && exampleEntity.op[primaryOp]
-    const idF = entityIdField(exampleEntity)
     let arg = ''
-    if ('load' === primaryOp || 'remove' === primaryOp) {
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    if (isMatchOp || 'list' === primaryOp) {
       // Every REQUIRED match key (id first) — the same shape that generates
       // the op's Match type, so the block type-checks.
-      const items = opRequestShape(exampleEntity, primaryOp).items
-        .filter((it: any) => !it.optional || it.name === idF)
+      const items = (isMatchOp ? opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF) : [...listItems])
         .sort((a: any, b: any) =>
           (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const lit = (it: any): string => isMatchOp
+        ? exampleValue(exampleEntity, primaryOpDef, it.name,
+          it.name === idF ? 'test01' : 'example_' + it.name)
+        : listLit(it)
       arg = 0 < items.length
-        ? `{ ${items.map((it: any) =>
-          `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
-            it.name === idF ? 'test01' : 'example_' + it.name)}`).join(', ')} }`
+        ? `{ ${items.map((it: any) => `${jsKey(it.name)}: ${lit(it)}`).join(', ')} }`
         : ''
-    } else if ('create' === primaryOp || 'update' === primaryOp) {
-      const isIdField = (it: any) => it.name === idF || it.name === 'id'
+    } else if ('create' === primaryOp || 'update' === primaryOp || 'patch' === primaryOp) {
       const items = opRequestShape(exampleEntity, primaryOp).items
         .filter((it: any) => !isIdField(it) || !it.optional)
       const required = items.filter((it: any) => !it.optional)
@@ -78,10 +90,13 @@ const client = ${model.const.Name}SDK.test({
         `${jsKey(it.name)}: ${exampleValue(exampleEntity, primaryOpDef, it.name,
           isIdField(it) ? seedId : 'example_' + it.name)}`).join(', ')} }`
     }
+    const one = exampleVarName(eName.toLowerCase(), 'ts')
     Content(`const ${eVar} = await client.${eName}().${primaryOp}(${arg})
-// ${eVar} is ${'list' === primaryOp ? `an array of ${eName} entities` : `the ${eName} entity`}, populated with mock data
-// — call ${eVar}${'list' === primaryOp ? '[0]' : ''}.data() for the record itself
-console.log(${eVar})
+${'list' === primaryOp
+    ? `// ${eVar} is an array of ${eName} entities, one per mock record
+console.log(${eVar}.map((${one}) => ${one}.data()))`
+    : `// ${eVar} is the ${eName} entity; .data() reads its mock record
+console.log(${eVar}.data())`}
 `)
   }
 

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

@@ -148,10 +148,34 @@ const SCENARIOS: Scenario[] = [
   { name: 'coded', respond: (_url: string, _fetchdef: any, ctx: any) => {
     throw ctx.error('denied_' + CANARY.apikey, 'coded failure')
   } },
+  // fetch rejects a timed-out or aborted request with a DOMException, whose
+  // message is a getter with no setter.
+  { name: 'timeout', respond: (url: string) => {
+    throw new DOMException('timed out sending ' + CANARY.apikey + ' (URL was: "' + url + '")', 'TimeoutError')
+  } },
 ]
 
 
-function makeSdk(scenario: Scenario, sinks: Sink[], cleanopts?: any, extra?: any[]): any {
+// Offline, as every generated suite is: the test OPTION resolves a required
+// server variable to test-<name>, and installs no transport.
+function offline(opts: any): any {
+  return { ...opts, test: { active: true } }
+}
+
+
+// A client the sweep cannot build leaves nothing swept: a harness error, not a leak.
+function construct(opts: any): any {
+  try {
+    return new (SDK as any)(offline(opts))
+  }
+  catch (err: any) {
+    throw new Error('clean harness: the client could not be constructed, so nothing was swept: ' +
+      (err?.message ?? String(err)))
+  }
+}
+
+
+function makeSdk(scenario: Scenario, sinks: Sink[], cleanopts?: any, extra?: any[], auth?: any): any {
   const capture = (name: string) => (rec: any) => { sinks.push(...forms(name, rec)) }
   const feature: any = {}
   if (hasFeature('log')) {
@@ -180,7 +204,8 @@ function makeSdk(scenario: Scenario, sinks: Sink[], cleanopts?: any, extra?: any
   }
   // null builds the client with no clean block at all, as most callers do.
   if (null !== cleanopts) opts.clean = { values: CANARY.value, ...(cleanopts || {}) }
-  return new (SDK as any)(opts)
+  if (null != auth) opts.auth = auth
+  return construct(opts)
 }
 
 
@@ -189,7 +214,7 @@ function makeSdk(scenario: Scenario, sinks: Sink[], cleanopts?: any, extra?: any
 type Target = { accessor: string, op: string, match: any }
 
 async function usableOp(): Promise<Target | null> {
-  const plain = new (SDK as any)({
+  const plain = construct({
     apikey: CANARY.apikey,
     utility: { fetcher: async () => response(200, { id: 'i1' }) },
   })
@@ -268,16 +293,19 @@ class StreamOkFeature extends BaseFeature {
 async function drive(sdk: any, target: Target, ctrl: any, sinks: Sink[]) {
   // A caller may keep the record it passed rather than read ctrl.explain.
   const held = ctrl.explain
+  const entity = sdk[target.accessor]()
   let out: any = undefined
   let err: any = undefined
   try {
-    out = await sdk[target.accessor]()[target.op]({ ...target.match }, ctrl)
+    out = await entity[target.op]({ ...target.match }, ctrl)
   }
   catch (e: any) {
     err = e
   }
   if (undefined !== err) sinks.push(...forms('error', err))
   if (undefined !== out) sinks.push(...forms('result', out))
+  // Raw, as a caller copying the match into another query reads it.
+  sinks.push(...forms('match', entity.match()))
   if (null != ctrl.explain) sinks.push(...forms('explain', ctrl.explain))
   if (null != held && held !== ctrl.explain) sinks.push(...forms('explain:held', held))
   return err
@@ -312,12 +340,17 @@ describe('clean', () => {
       }
     }
 
+    // A name given at run time replaces the declared one: the match leaves
+    // out whichever name prepareAuth placed.
+    await drive(makeSdk(SCENARIOS[0], sinks, undefined, undefined, { name: 'zzcred' }),
+      target, {}, sinks)
+
     // A credential mistyped as an object is rejected by validation, whose
     // message quotes the value it rejected; with and without a clean block.
     for (const cleanblock of [{ clean: { values: CANARY.value } }, {}]) {
       let rejected: any = undefined
       try {
-        new (SDK as any)({ apikey: { value: CANARY.apikey }, ...cleanblock })
+        new (SDK as any)(offline({ apikey: { value: CANARY.apikey }, ...cleanblock }))
       }
       catch (e: any) {
         rejected = e
@@ -369,15 +402,22 @@ describe('clean', () => {
 
     // A feature's name is not a field name: only the sensitive names inside
     // its settings register. An entity block, of per-entity settings or seeded
-    // records keyed by entity name and id, is not read at all.
-    const featured: any = new (SDK as any)({ apikey: CANARY.apikey, feature: {
+    // records keyed by entity name and id, is not read at all, and nor are
+    // rbac's rules, keyed by entity and operation names.
+    const featured: any = construct({ apikey: CANARY.apikey, feature: {
       zzsecrets: { active: false, kind: 'PLAINSETTING-q8w2e4r6' },
       zzfeat: { active: false, apitoken: 'FEATTOKEN-z9y8x7w6' },
+      rbac: { active: false, rules: { 'zztoken.load': 'PLAINRULE-k7j5h3g1' } },
       test: { active: false, entity: { zztoken: { ZZTOKEN01: { note: 'PLAINRECORD-t5r3e1w9' } } } },
     }, entity: { zztoken: { alias: { zzkey: 'PLAINALIAS-m2n4b6v8' } } } })
     const fctx = { options: featured._options }
 
-    // The raw path returns its failure rather than throwing it.
+    // The raw path returns its failure rather than throwing it, a
+    // DOMException's included.
+    const timedout = await makeSdk(SCENARIOS[SCENARIOS.length - 1], sinks).direct({ path: 'raw' })
+    ok(false === timedout.ok && 'TimeoutError' === timedout.err?.name,
+      'a timed-out transport should fail direct() with its own error')
+    sinks.push(...forms('direct:timeout', timedout.err))
     const raw = await makeSdk(SCENARIOS[3], sinks).direct({ path: 'raw' })
     ok(false === raw.ok && null != raw.err, 'a transport failure should fail direct()')
     sinks.push(...forms('direct', raw.err))
@@ -391,6 +431,9 @@ describe('clean', () => {
     equal(leaked.length, 0, 'credential leaked through: ' +
       leaked.map((l) => l.name + ' [' + l.found.join(', ') + ']').join('; '))
 
+    // A DOMException is masked in place, and stays the error it was.
+    equal(errors['timeout/throw']?.name, 'TimeoutError', 'a timed-out operation should throw its own error')
+
     // The positive half: the slot the credential travelled in is masked,
     // and an unregistered token in a response header is masked by name.
     const notfound = errors['notfound/throw']
@@ -419,6 +462,7 @@ describe('clean', () => {
     equal(featured.utility().clean(fctx, 'token FEATTOKEN-z9y8x7w6'), 'token ' + MASK)
     equal(featured.utility().clean(fctx, 'record PLAINRECORD-t5r3e1w9'), 'record PLAINRECORD-t5r3e1w9')
     equal(featured.utility().clean(fctx, 'alias PLAINALIAS-m2n4b6v8'), 'alias PLAINALIAS-m2n4b6v8')
+    equal(featured.utility().clean(fctx, 'rule PLAINRULE-k7j5h3g1'), 'rule PLAINRULE-k7j5h3g1')
 
     const coded = errors['coded/throw']
     ok(null != coded, 'the coded scenario must throw')