@voxgig/sdkgen 1.2.0 → 1.3.1

package/project/.sdk/src/cmp/php/ReadmeOptions_php.ts

@@ -1,12 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
 
 
 const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  const publishedOptions = each(target.options).filter((option: any) => option.publish)
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
   if (0 === publishedOptions.length) {
     return
   }
@@ -25,7 +26,7 @@ $client = new ${model.Name}SDK([
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`    "${option.name}" => getenv("${model.NAME}_APIKEY"),
+      Content(`    "${option.name}" => getenv("${envName(model)}_APIKEY"),
 `)
     }
     else {

package/project/.sdk/src/cmp/php/ReadmeQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -18,9 +18,9 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     e.active !== false && e.ancestors && e.ancestors.length > 0
   ) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n    "apikey" => getenv("${model.NAME}_APIKEY"),\n`
-    : ''
+  const ctor = isAuthActive(model)
+    ? `new ${model.const.Name}SDK([\n    "apikey" => getenv("${envName(model)}_APIKEY"),\n])`
+    : `new ${model.const.Name}SDK()`
 
   Content(`### 1. Create a client
 
@@ -28,27 +28,46 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
 <?php
 require_once '${model.const.Name.toLowerCase()}_sdk.php';
 
-$client = new ${model.const.Name}SDK([${apikeyArg}]);
+$client = ${ctor};
 \`\`\`
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
+    const article = /^[aeiou]/i.test(eName) ? "an" : "a"
     const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: `idF` is the MATCH key (null when none). `dataIdF` is
+    // the id on the RETURNED record's data type — an entity can key its match on
+    // an id it does not carry as data, so `["id"]` off a returned record must be
+    // guarded on this, not the match key.
+    const idF = entityIdField(exampleEntity)
+    const dataIdF = entityDataIdField(exampleEntity)
+
+    // Model-driven display field: the entity's first non-id string field
+    // (falling back to any non-id field), so the list example prints a real
+    // column instead of a hardcoded "name" the entity may not have.
+    const fields = exampleEntity.fields || []
+    const displayField =
+      fields.find((f: any) => f && f.name !== 'id' && f.type === '$STRING') ||
+      fields.find((f: any) => f && f.name !== 'id') ||
+      null
+    const idCol = dataIdF ? `$item[${JSON.stringify(dataIdF)}]` : null
+    const dispCol = displayField ? `$item[${JSON.stringify(displayField.name)}]` : null
+    const itemPrint = [idCol, dispCol].filter(Boolean).join(' . " " . ') || 'json_encode($item)'
 
     if (opnames.includes('list')) {
-      Content(`### 2. List ${eName.toLowerCase()}s
+      Content(`### 2. List ${eName.toLowerCase()} records
 
 \`\`\`php
-[$result, $err] = $client->${eName}(null)->list(null, null);
-if ($err) { throw new \\Exception($err); }
-
-if (is_array($result)) {
-    foreach ($result as $item) {
-        $d = $item->data_get();
-        echo $d["id"] . " " . $d["name"] . "\\n";
+try {
+    // list() returns an array of ${eName} records — iterate directly.
+    $${eName.toLowerCase()}s = $client->${eName}()->list();
+    foreach ($${eName.toLowerCase()}s as $item) {
+        echo ${itemPrint} . "\\n";
     }
+} catch (\\Throwable $err) {
+    echo "Error: " . $err->getMessage();
 }
 \`\`\`
 
@@ -56,37 +75,76 @@ if (is_array($result)) {
     }
 
     if (opnames.includes('load')) {
-      Content(`### 3. Load a ${eName.toLowerCase()}
+      Content(`### 3. Load ${article} ${eName.toLowerCase()}
 
 \`\`\`php
-[$result, $err] = $client->${eName}(null)->load(["id" => "example_id"], null);
-if ($err) { throw new \\Exception($err); }
-print_r($result);
+try {
+    // load() returns the bare ${eName} record (throws on error).
+    $${eName.toLowerCase()} = $client->${eName}()->load(${idF ? `["${idF}" => "example_id"]` : ''});
+    print_r($${eName.toLowerCase()});
+} catch (\\Throwable $err) {
+    echo "Error: " . $err->getMessage();
+}
 \`\`\`
 
 `)
     }
 
+    // Model-driven example fields: derive the create/update body from the op
+    // shape (opRequestShape) so the docs reference REAL writable fields, not a
+    // hardcoded "name" the entity may not have. Literals are PHP-typed by the
+    // field's canonical type.
+    const idField = (exampleEntity.id && exampleEntity.id.field) || 'id'
+    const phpLit = (type: any): string => {
+      const k = canonKey(type)
+      if ('INTEGER' === k || 'NUMBER' === k) return '1'
+      if ('BOOLEAN' === k) return 'true'
+      if ('ARRAY' === k || 'OBJECT' === k) return '[]'
+      return '"example"'
+    }
+    const examplePairs = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => it.name !== idField && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : items.slice(0, 2)
+      return chosen.map((it: any) => `"${it.name}" => ${phpLit(it.type)}`)
+    }
+
+    // The id VALUE for an update/remove match: off the returned `$created`
+    // record only when its data type carries the id AND a create ran, else a
+    // type-correct literal.
+    const idParamType = (opname: string): any => {
+      const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
+      return it && it.type
+    }
+    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
+      ? `$created["${dataIdF}"]`
+      : phpLit(idParamType(opname))
+
     if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
       Content(`### 4. Create, update, and remove
 
 \`\`\`php
 `)
       if (opnames.includes('create')) {
-        Content(`// Create
-[$created, $_] = $client->${eName}(null)->create(["name" => "Example"], null);
+        Content(`// create() returns the bare created ${eName} record.
+$created = $client->${eName}()->create([${examplePairs('create').join(', ')}]);
 
 `)
       }
       if (opnames.includes('update')) {
-        Content(`// Update
-$client->${eName}(null)->update(["id" => $created["id"], "name" => "Example-Renamed"], null);
+        const updatePairs = (idF ? [`"${idF}" => ${idValueFor('update')}`] : []).concat(examplePairs('update'))
+        const fromCreated = null != dataIdF && opnames.includes('create')
+        Content(`// Update${fromCreated ? ` — index the bare record directly ($created["${dataIdF}"]).` : ''}
+$client->${eName}()->update([${updatePairs.join(', ')}]);
 
 `)
       }
       if (opnames.includes('remove')) {
         Content(`// Remove
-$client->${eName}(null)->remove(["id" => $created["id"]], null);
+$client->${eName}()->remove(${idF ? `["${idF}" => ${idValueFor('remove')}]` : ''});
 `)
       }
       Content(`\`\`\`

package/project/.sdk/src/cmp/php/ReadmeRef_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -9,29 +9,29 @@ import {
 
 const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
   load: {
-    sig: 'load(array $reqmatch, ?array $ctrl = null): array',
-    returns: 'array [$result, $err]',
-    desc: 'Load a single entity matching the given criteria.',
+    sig: 'load(array $reqmatch, ?array $ctrl = null): mixed',
+    returns: 'mixed — the result data; throws on error',
+    desc: 'Load a single entity matching the given criteria. Throws on error.',
   },
   list: {
-    sig: 'list(array $reqmatch, ?array $ctrl = null): array',
-    returns: 'array [$result, $err]',
-    desc: 'List entities matching the given criteria. Returns an array.',
+    sig: 'list(?array $reqmatch = null, ?array $ctrl = null): mixed',
+    returns: 'array — the list of results; throws on error',
+    desc: 'List entities matching the given criteria (call with no argument to list all). Returns an array. Throws on error.',
   },
   create: {
-    sig: 'create(array $reqdata, ?array $ctrl = null): array',
-    returns: 'array [$result, $err]',
-    desc: 'Create a new entity with the given data.',
+    sig: 'create(array $reqdata, ?array $ctrl = null): mixed',
+    returns: 'mixed — the result data; throws on error',
+    desc: 'Create a new entity with the given data. Throws on error.',
   },
   update: {
-    sig: 'update(array $reqdata, ?array $ctrl = null): array',
-    returns: 'array [$result, $err]',
-    desc: 'Update an existing entity. The data must include the entity `id`.',
+    sig: 'update(array $reqdata, ?array $ctrl = null): mixed',
+    returns: 'mixed — the result data; throws on error',
+    desc: 'Update an existing entity. The data must include the entity `id`. Throws on error.',
   },
   remove: {
-    sig: 'remove(array $reqmatch, ?array $ctrl = null): array',
-    returns: 'array [$result, $err]',
-    desc: 'Remove the entity matching the given criteria.',
+    sig: 'remove(array $reqmatch, ?array $ctrl = null): mixed',
+    returns: 'mixed — the result data; throws on error',
+    desc: 'Remove the entity matching the given criteria. Throws on error.',
   },
 }
 
@@ -60,7 +60,7 @@ Complete API reference for the ${model.Name} ${target.title} SDK.
 `)
 
     Content(`\`\`\`php
-require_once __DIR__ . '/${model.name}_sdk.php';
+require_once __DIR__ . '/${model.const.Name.toLowerCase()}_sdk.php';
 
 $client = new ${model.const.Name}SDK($options);
 \`\`\`
@@ -72,8 +72,7 @@ Create a new SDK client instance.
 | Name | Type | Description |
 | --- | --- | --- |
 | \`$options\` | \`array\` | SDK configuration options. |
-| \`$options["apikey"]\` | \`string\` | API key for authentication. |
-| \`$options["base"]\` | \`string\` | Base URL for API requests. |
+${isAuthActive(model) ? '| \`$options["apikey"]\` | \`string\` | API key for authentication. |\n' : ''}| \`$options["base"]\` | \`string\` | Base URL for API requests. |
 | \`$options["prefix"]\` | \`string\` | URL prefix appended after base. |
 | \`$options["suffix"]\` | \`string\` | URL suffix appended after path. |
 | \`$options["headers"]\` | \`array\` | Custom headers for all requests. |
@@ -115,17 +114,20 @@ Create a new \`${ent.Name}Entity\` instance. Pass \`null\` for no initial data.
     })
 
 
-    Content(`#### \`optionsMap(): array\`
+    Content(`#### \`options_map(): array\`
 
 Return a deep copy of the current SDK options.
 
-#### \`getUtility(): ProjectNameUtility\`
+#### \`get_utility(): ${model.const.Name}Utility\`
 
 Return a copy of the SDK utility object.
 
 #### \`direct(array $fetchargs = []): array\`
 
-Make a direct HTTP request to any API endpoint. Returns \`[$result, $err]\`.
+Make a direct HTTP request to any API endpoint. This is the raw-HTTP escape
+hatch: it does **not** throw. It returns a result array
+\`["ok" => bool, "status" => int, "headers" => array, "data" => mixed]\`, or
+\`["ok" => false, "err" => \\Exception]\` on failure. Branch on \`$result["ok"]\`.
 
 **Parameters:**
 
@@ -139,11 +141,12 @@ Make a direct HTTP request to any API endpoint. Returns \`[$result, $err]\`.
 | \`$fetchargs["body"]\` | \`mixed\` | Request body (arrays are JSON-serialized). |
 | \`$fetchargs["ctrl"]\` | \`array\` | Control options. |
 
-**Returns:** \`array [$result, $err]\`
+**Returns:** \`array\` — the result dict (see above); never throws.
 
-#### \`prepare(array $fetchargs = []): array\`
+#### \`prepare(array $fetchargs = []): mixed\`
 
-Prepare a fetch definition without sending the request. Returns \`[$fetchdef, $err]\`.
+Prepare a fetch definition without sending the request. Returns the
+\`$fetchdef\` array. Throws on error.
 
 `)
 
@@ -152,6 +155,9 @@ Prepare a fetch definition without sending the request. Returns \`[$fetchdef, $e
     publishedEntities.map((ent: any) => {
       const opnames = Object.keys(ent.op || {})
       const fields = ent.fields || []
+      // Model-driven id key: null when this entity has no id-like field, in
+      // which case load/remove match on no argument and update omits the id.
+      const idF = entityIdField(ent)
 
       Content(`
 ---
@@ -183,7 +189,7 @@ $${ent.name} = $client->${ent.Name}();
         each(fields, (field: any) => {
           const req = field.req ? 'Yes' : 'No'
           const desc = field.short || ''
-          Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${req} | ${desc} |
+          Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
 `)
         })
 
@@ -193,15 +199,18 @@ $${ent.name} = $client->${ent.Name}();
         // Field operations breakdown
         const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
         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']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
           Content(`### Field Usage by Operation
 
-| Field | load | list | create | update | remove |
-| --- | --- | --- | --- | --- | --- |
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
 `)
           each(fields, (field: any) => {
             const fops = field.op || {}
-            const cols = ['load', 'list', 'create', 'update', 'remove'].map((op: string) => {
-              if (!opnames.includes(op)) return '-'
+            const cols = opcols.map((op: string) => {
               const fop = fops[op]
               if (null == fop) return '-'
               if (fop.active === false) return '-'
@@ -236,25 +245,25 @@ ${info.desc}
           // Show example
           if ('load' === opname || 'remove' === opname) {
             Content(`\`\`\`php
-[$result, $err] = $client->${ent.Name}()->${opname}(["id" => "${ent.name}_id"]);
+$result = $client->${ent.Name}()->${opname}(${idF ? `["${idF}" => "${ent.name}_id"]` : ''});
 \`\`\`
 
 `)
           }
           else if ('list' === opname) {
             Content(`\`\`\`php
-[$results, $err] = $client->${ent.Name}()->list([]);
+$results = $client->${ent.Name}()->list();
 \`\`\`
 
 `)
           }
           else if ('create' === opname) {
             Content(`\`\`\`php
-[$result, $err] = $client->${ent.Name}()->create([
+$result = $client->${ent.Name}()->create([
 `)
             each(fields, (field: any) => {
               if ('id' !== field.name && field.req) {
-                Content(`  "${field.name}" => /* ${field.type || 'value'} */,
+                Content(`  "${field.name}" => null, // ${canonToType(field.type, target.name)}
 `)
               }
             })
@@ -264,10 +273,10 @@ ${info.desc}
 `)
           }
           else if ('update' === opname) {
+            const updateIdLine = idF ? `  "${idF}" => "${ent.name}_id",\n` : ''
             Content(`\`\`\`php
-[$result, $err] = $client->${ent.Name}()->update([
-  "id" => "${ent.name}_id",
-  // Fields to update
+$result = $client->${ent.Name}()->update([
+${updateIdLine}  // Fields to update
 ]);
 \`\`\`
 
@@ -280,19 +289,19 @@ ${info.desc}
       // Common methods
       Content(`### Common Methods
 
-#### \`dataGet(): array\`
+#### \`data_get(): array\`
 
 Get the entity data. Returns a copy of the current data.
 
-#### \`dataSet($data): void\`
+#### \`data_set($data): void\`
 
 Set the entity data.
 
-#### \`matchGet(): array\`
+#### \`match_get(): array\`
 
 Get the entity match criteria.
 
-#### \`matchSet($match): void\`
+#### \`match_set($match): void\`
 
 Set the entity match criteria.
 
@@ -301,7 +310,7 @@ Set the entity match criteria.
 Create a new \`${ent.Name}Entity\` instance with the same client and
 options.
 
-#### \`getName(): string\`
+#### \`get_name(): string\`
 
 Return the entity name.
 

package/project/.sdk/src/cmp/php/ReadmeTopHowto_php.ts

@@ -7,7 +7,7 @@ const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
 
   Content(`**PHP:**
 \`\`\`php
-[$result, $err] = $client->direct([
+$result = $client->direct([
     "path" => "/api/resource/{id}",
     "method" => "GET",
     "params" => ["id" => "example"],

package/project/.sdk/src/cmp/php/ReadmeTopQuick_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -15,35 +15,43 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  const apikeyArg = isAuthActive(model)
-    ? `\n    "apikey" => getenv("${model.NAME}_APIKEY"),\n`
-    : ''
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `new ${model.const.Name}SDK([\n    "apikey" => getenv("${envName(model)}_APIKEY"),\n])`
+    : `new ${model.const.Name}SDK()`
 
   Content(`\`\`\`php
 <?php
 require_once '${model.const.Name.toLowerCase()}_sdk.php';
 
-$client = new ${model.const.Name}SDK([${apikeyArg}]);
+$client = ${ctor};
 
 `)
 
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
     const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    let hasCall = false
 
     if (opnames.includes('list')) {
-      Content(`// List all ${eName.toLowerCase()}s
-[$${eName.toLowerCase()}s, $err] = $client->${eName}(null)->list(null, null);
+      Content(`// List all ${eName.toLowerCase()}s (returns an array; throws on error)
+$${eName.toLowerCase()}s = $client->${eName}()->list();
+print_r($${eName.toLowerCase()}s);
 `)
+      hasCall = true
     }
 
     if (opnames.includes('load')) {
       Content(`
-// Load a specific ${eName.toLowerCase()}
-[$${eName.toLowerCase()}, $err] = $client->${eName}(null)->load(
-    ["id" => "example_id"], null
-);
+// Load a specific ${eName.toLowerCase()} (returns the bare record; throws on error)
+$${eName.toLowerCase()} = $client->${eName}()->load(${idF ? `["${idF}" => "example_id"]` : ''});
+print_r($${eName.toLowerCase()});
 `)
+      hasCall = true
     }
   }
 

package/project/.sdk/src/cmp/php/ReadmeTopTest_php.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, canonKey, entityIdField, entityPrimaryOp, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -8,6 +8,16 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct PHP literal for a field's canonical type.
+function phpLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k || 'OBJECT' === k) return '[]'
+  return '"example"'
+}
+
+
 const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
   const { target, ctx$: { model } } = props
 
@@ -15,20 +25,40 @@ const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
 
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  Content(`\`\`\`php
-$client = ${model.const.Name}SDK::test(null, null);
-`)
-
   if (exampleEntity) {
     const eName = nom(exampleEntity, 'Name')
-    Content(`[$result, $err] = $client->${eName}(null)->load(
-    ["id" => "test01"], null
-);
+    const ename = eName.toLowerCase()
+    // Model-driven id key: null when the entity has no id-like field.
+    const idF = entityIdField(exampleEntity)
+    // Drive the test-mode example off the entity's PRIMARY op (never a hardcoded
+    // `load` a create-only entity lacks).
+    const primaryOp = entityPrimaryOp(exampleEntity) || 'load'
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    const recBody = idF ? `["${idF}" => "test01"]` : '[]'
+    let callArg = ''
+    if (isMatchOp) {
+      callArg = idF ? `["${idF}" => "test01"]` : ''
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      callArg = `[${chosen.map((it: any) => `"${it.name}" => ${phpLit(it.type)}`).join(', ')}]`
+    }
+    Content(`\`\`\`php
+// Seed fixture data so offline calls resolve without a live server.
+$client = ${model.const.Name}SDK::test([
+    "entity" => ["${ename}" => ["test01" => ${recBody}]],
+]);
+$${ename} = $client->${eName}()->${primaryOp}(${callArg});
+\`\`\`
 `)
-  }
-
-  Content(`\`\`\`
+  } else {
+    Content(`\`\`\`php
+$client = ${model.const.Name}SDK::test();
+\`\`\`
 `)
+  }
 
 })
 

package/project/.sdk/src/cmp/php/TestDirect_php.ts

@@ -190,7 +190,7 @@ ${listSkipBlock}        $client = $setup["client"];
 `)
         }
         Content(`
-        [$result, $err] = $client->direct([
+        $result = $client->direct([
             "path" => "${listPath}",
             "method" => "GET",
             "params" => $params,
@@ -198,7 +198,7 @@ ${listSkipBlock}        $client = $setup["client"];
 `)
       } else {
         Content(`
-        [$result, $err] = $client->direct([
+        $result = $client->direct([
             "path" => "${listPath}",
             "method" => "GET",
             "params" => [],
@@ -210,8 +210,8 @@ ${listSkipBlock}        $client = $setup["client"];
             // Live mode is lenient: synthetic IDs frequently 4xx and the
             // list-response shape varies wildly across public APIs. Skip
             // rather than fail when the call doesn't return a usable list.
-            if ($err !== null) {
-                $this->markTestSkipped("list call failed (likely synthetic IDs against live API): " . (string)$err);
+            if (!empty($result["err"])) {
+                $this->markTestSkipped("list call failed (likely synthetic IDs against live API): " . (string)$result["err"]);
                 return;
             }
             if (empty($result["ok"])) {
@@ -224,7 +224,7 @@ ${listSkipBlock}        $client = $setup["client"];
                 return;
             }
         } else {
-            $this->assertNull($err);
+            $this->assertArrayNotHasKey("err", $result);
             $this->assertTrue($result["ok"]);
             $this->assertEquals(200, Helpers::to_int($result["status"]));
             $this->assertIsArray($result["data"]);
@@ -300,7 +300,7 @@ ${loadLiveQueryLines}
       }
 
       Content(`
-        [$result, $err] = $client->direct([
+        $result = $client->direct([
             "path" => "${loadPath}",
             "method" => "GET",
 `)
@@ -317,8 +317,8 @@ ${loadLiveQueryLines}
             // Live mode is lenient: synthetic IDs frequently 4xx. Skip
             // rather than fail when the load endpoint isn't reachable
             // with the IDs we can construct from setup.idmap.
-            if ($err !== null) {
-                $this->markTestSkipped("load call failed (likely synthetic IDs against live API): " . (string)$err);
+            if (!empty($result["err"])) {
+                $this->markTestSkipped("load call failed (likely synthetic IDs against live API): " . (string)$result["err"]);
                 return;
             }
             if (empty($result["ok"])) {
@@ -331,7 +331,7 @@ ${loadLiveQueryLines}
                 return;
             }
         } else {
-            $this->assertNull($err);
+            $this->assertArrayNotHasKey("err", $result);
             $this->assertTrue($result["ok"]);
             $this->assertEquals(200, Helpers::to_int($result["status"]));
             $this->assertNotNull($result["data"]);