@voxgig/sdkgen 4.30.2 → 4.31.0

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/Prepare.swift

@@ -64,22 +64,40 @@ func prepareParamsUtil(_ ctx: Context) -> VMap {
 func prepareQueryUtil(_ ctx: Context) -> VMap {
   let reqmatch = ctx.reqmatch
 
-  var paramnames: VList = VList()
-  if let pl = gp(ctx.point, "params").asList { paramnames = pl }
+  var paramnames: [Value] = []
+  if let pl = gp(ctx.point, "params").asList { paramnames.append(contentsOf: pl.items) }
+  // A path parameter travels in the path. The generated config lists them as
+  // args.params, which prepareParams reads; params is the older list of names.
+  if let apl = gpath(ctx.point, "args", "params").asList {
+    for pd in apl.items {
+      paramnames.append(gp(pd, "name"))
+    }
+  }
+
+  // A query parameter travels under the name the definition gives it, its
+  // orig, which the model may have renamed for the caller.
+  var wire: [String: String] = [:]
+  if let aql = gpath(ctx.point, "args", "query").asList {
+    for qd in aql.items {
+      if let name = gp(qd, "name").asString, let orig = gp(qd, "orig").asString, !orig.isEmpty {
+        wire[name] = orig
+      }
+    }
+  }
 
   let query = VMap()
   for item in items(.map(reqmatch)) {
     let key = item[0].asString ?? ""
     let val = item[1]
     if !isNil(val) && "$action" != key && !containsStr(paramnames, key) {
-      query.entries[key] = val
+      query.entries[wire[key] ?? key] = val
     }
   }
   return query
 }
 
-private func containsStr(_ list: VList, _ s: String) -> Bool {
-  return list.items.contains { $0.asString == s }
+private func containsStr(_ list: [Value], _ s: String) -> Bool {
+  return list.contains { $0.asString == s }
 }
 
 func prepareBodyUtil(_ ctx: Context) -> Value {

package/project/.sdk/tm/ts/src/utility/PrepareQueryUtility.ts

@@ -14,10 +14,24 @@ function prepareQuery(ctx: Context) {
   params = params || []
   reqmatch = reqmatch || {}
 
+  // A path parameter travels in the path. The generated config lists them as
+  // args.params, which prepareParams reads; params is the older list of names.
+  const inpath: string[] = params.concat(
+    (point.args?.params || []).map((p: any) => p?.name))
+
+  // A query parameter travels under the name the definition gives it, its
+  // orig, which the model may have renamed for the caller.
+  const wire: Record<string, string> = Object.create(null)
+  for (const q of (point.args?.query || [])) {
+    if ('string' === typeof q?.name && 'string' === typeof q?.orig && '' !== q.orig) {
+      wire[q.name] = q.orig
+    }
+  }
+
   const out: any = {}
   for (let [key, val] of items(reqmatch)) {
-    if (null != val && '$action' !== key && !params.includes(key)) {
-      out[key] = val
+    if (null != val && '$action' !== key && !inpath.includes(key)) {
+      out[wire[key] ?? key] = val
     }
   }
 

package/project/.sdk/tm/ts/test/definition-runner.ts

@@ -0,0 +1,179 @@
+// Checks one operation against the API definition rather than the model the
+// SDK was generated from. A mock transport answers with the definition's own
+// response example, so nothing here depends on how the model reads it.
+
+import assert from 'node:assert/strict'
+
+
+type Credential = { in: string, name: string, scheme?: string }
+
+type DefinitionPoint = {
+  entity: string
+  accessor: string
+  op: string
+  method: string
+  path: string
+  action?: string
+  args: { name: string, wire: string, value: any }[]
+  select: Record<string, any>
+  query: string[]
+  auth: Credential[][] | null
+  status: number
+  sample: any
+  idField: string
+}
+
+
+const KEY = 'definition-test-key'
+const BASE = 'http://definition.test'
+
+
+async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<void> {
+  const sent: { url: URL, init: any }[] = []
+  const body = null == point.sample ? null : JSON.stringify(point.sample)
+
+  const client = new SDK({
+    apikey: KEY,
+    base: BASE,
+    feature: { test: { active: false } },
+    system: {
+      fetch: async (url: any, init: any) => {
+        sent.push({ url: new URL(String(url)), init: init || {} })
+        return new Response(204 === point.status ? null : body, {
+          status: point.status,
+          headers: { 'content-type': 'application/json' },
+        })
+      },
+    },
+  })
+
+  const input: any = { ...point.select }
+  for (const arg of point.args) input[arg.name] = arg.value
+  if (null != point.action) input.$action = point.action
+
+  let result: any
+  let error: any
+  try {
+    result = await client[point.accessor]()[point.op](input)
+  }
+  catch (err) {
+    error = err
+  }
+
+  assert.equal(sent.length, 1, 'expected one request, sent ' + sent.length +
+    (error ? ': ' + (error as any).message : ''))
+  const { url, init } = sent[0]
+
+  assert.equal(String(init.method || 'GET').toUpperCase(), point.method, 'method')
+
+  const route = point.path.replace(/\{([^}]+)\}/g, (_: string, name: string) => {
+    const arg = point.args.find((a) => a.wire === name)
+    return null == arg ? '{' + name + '}' : encodeURIComponent(String(arg.value))
+  })
+  assert.equal(url.pathname, route, 'route')
+
+  // Only what the definition declares, so never a path parameter again.
+  const credentialQuery = (point.auth || []).flat()
+    .filter((c) => 'query' === c.in).map((c) => c.name)
+  for (const key of url.searchParams.keys()) {
+    assert(point.query.includes(key) || credentialQuery.includes(key),
+      'query parameter not in the definition: ' + key)
+  }
+
+  // From the apikey alone, placed as the definition's security scheme says.
+  if (null != point.auth && 0 < point.auth.length) {
+    const headers = new Headers(init.headers)
+    assert(point.auth.some((set) => set.every((c) => placed(c, headers, url))),
+      'credential not sent as the definition declares it: ' + JSON.stringify(point.auth))
+  }
+
+  if (null != error) {
+    throw error
+  }
+
+  if (null == point.sample) {
+    return
+  }
+
+  if ('list' === point.op) {
+    const records = recordsOf(point.sample)
+    if (null != records) {
+      assert(Array.isArray(result), 'list did not return a list')
+      assert.equal(result.length, records.length,
+        'list read ' + result.length + ' records where the definition example holds ' +
+        records.length)
+    }
+  }
+  else if ('load' === point.op || 'create' === point.op || 'update' === point.op) {
+    const record = recordOf(point.sample, point.idField)
+    if (null != record) {
+      assert.equal(result?.data?.()?.[point.idField], record[point.idField],
+        'the entity does not hold the record the definition example returns')
+    }
+  }
+}
+
+
+function placed(cred: Credential, headers: Headers, url: URL): boolean {
+  if ('query' === cred.in) {
+    return KEY === url.searchParams.get(cred.name)
+  }
+
+  if ('cookie' === cred.in) {
+    return String(headers.get('cookie') || '').split(';')
+      .some((part) => cred.name + '=' + KEY === part.trim())
+  }
+
+  const value = headers.get(cred.name)
+  if (null == value) {
+    return false
+  }
+
+  const [kind, token] = value.split(' ')
+
+  // The client carries no secret, so the password must be empty.
+  if ('basic' === cred.scheme) {
+    return 'basic' === String(kind).toLowerCase() &&
+      Buffer.from(String(token), 'base64').toString('utf8') === KEY + ':'
+  }
+
+  if ('bearer' === cred.scheme) {
+    return 'bearer' === String(kind).toLowerCase() && KEY === token
+  }
+
+  return value.includes(KEY)
+}
+
+
+// The records a list response holds: the body itself, or its one property
+// that is a non-empty list of objects. Anything else proves nothing.
+function recordsOf(sample: any): any[] | null {
+  if (Array.isArray(sample)) {
+    return sample
+  }
+  if (null == sample || 'object' !== typeof sample) {
+    return null
+  }
+  const lists = Object.values(sample).filter((v: any) => Array.isArray(v) && 0 < v.length &&
+    v.every((x: any) => null != x && 'object' === typeof x && !Array.isArray(x)))
+  return 1 === lists.length ? lists[0] as any[] : null
+}
+
+
+// The record a single-item response returns: the body, or its one property
+// holding an object with the identity field.
+function recordOf(sample: any, idField: string): any {
+  if (null == sample || 'object' !== typeof sample || Array.isArray(sample)) {
+    return null
+  }
+  if (null != sample[idField]) {
+    return sample
+  }
+  const inner = Object.values(sample).filter((v: any) => null != v && 'object' === typeof v &&
+    !Array.isArray(v) && null != v[idField])
+  return 1 === inner.length ? inner[0] : null
+}
+
+
+export { runDefinitionPoint, recordsOf, recordOf }
+export type { DefinitionPoint }

package/project/.sdk/tm/ts/test/pipeline.test.ts

@@ -333,9 +333,9 @@ describe('pipeline:prepareAuth', () => {
   }
 
   // `basic: false` is explicit: an HTTP Basic API's generated config carries
-  // `auth.basic: true`, and a client that merges it in takes a branch needing
-  // a secret as well. With none supplied that branch writes nothing, which
-  // the probe below would then read as a public API.
+  // `auth.basic: true`, and a client that merges it in takes the Basic
+  // branch, which base64-joins the key with a password rather than placing
+  // the key as it is.
   function auth(prefix: string): any {
     return { prefix, basic: false }
   }
@@ -423,6 +423,46 @@ describe('pipeline:prepareAuth', () => {
   test('a missing apikey option drops the credential', () => {
     strictEqual(placed({ auth: auth('Bearer') }, 'stale'), undefined)
   })
+
+  // HTTP Basic joins the key with a password, which may be empty (RFC 7617):
+  // Lob documents its key as the user with a blank password. An SDK for an
+  // API that is not HTTP Basic has no such branch, and the first placement
+  // below tells the two apart.
+  test('HTTP Basic sends the key with a blank password', () => {
+    if (null == CRED || 'headers' !== CRED.where || '' !== CRED.pair) return
+    const basic = { prefix: 'Basic', basic: true }
+    const b64 = (s: string) => Buffer.from(s).toString('base64')
+    if (placed({ apikey: 'K', secret: 'S', auth: basic }) !== 'Basic ' + b64('K:S')) return
+    strictEqual(placed({ apikey: 'K', auth: basic }), 'Basic ' + b64('K:'))
+    strictEqual(placed({ apikey: 'K', secret: '', auth: basic }), 'Basic ' + b64('K:'))
+    strictEqual(placed({ apikey: '', secret: 'S', auth: basic }, 'stale'), undefined)
+  })
+})
+
+
+describe('pipeline:prepareQuery', () => {
+
+  // The generated config lists path parameters as args.params. A match field
+  // that fills the path must not be sent again as a query parameter, which a
+  // strict server rejects.
+  test('a path parameter stays out of the query', () => {
+    const point = { args: { params: [{ name: 'id', kind: 'param' }] } }
+    const ctx = base({ point, reqmatch: { id: 'i1', q: 'x' } })
+    deepStrictEqual((stdutil as any).prepareQuery(ctx), { q: 'x' })
+  })
+
+  test('an action is never a query parameter', () => {
+    const ctx = base({ point: { args: { params: [] } }, reqmatch: { $action: 'go', q: 'x' } })
+    deepStrictEqual((stdutil as any).prepareQuery(ctx), { q: 'x' })
+  })
+
+  // A query argument's orig is the name the API definition gives it, which
+  // the model may have renamed for the caller.
+  test('a query argument goes out under its orig', () => {
+    const point = { args: { query: [{ name: 'item_id', orig: 'itemIds', kind: 'query' }] } }
+    const ctx = base({ point, reqmatch: { item_id: ['i1'], q: 'x' } })
+    deepStrictEqual((stdutil as any).prepareQuery(ctx), { itemIds: ['i1'], q: 'x' })
+  })
 })
 
 

package/project/.sdk/tm/ts/test/sdk-test-control.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "_doc": "Per-SDK test control. Lists tests/operations to skip in unit and live modes; tunes per-test pacing. Edit by hand. Loaded by ts/test/utility.ts.",
+  "_doc": "Per-SDK test control. Lists tests/operations to skip in unit, live and definition modes; tunes per-test pacing. Edit by hand. Loaded by ts/test/utility.ts.",
   "test": {
     "skip": {
       "live": {
@@ -10,6 +10,9 @@
       "unit": {
         "direct": [],
         "entityOp": []
+      },
+      "definition": {
+        "entityOp": []
       }
     },
     "live": {

package/project/.sdk/tm/ts/test/utility.ts

@@ -77,6 +77,7 @@ type TestControl = {
     skip?: {
       live?: { direct?: any[], entityOp?: any[] }
       unit?: { direct?: any[], entityOp?: any[] }
+      definition?: { direct?: any[], entityOp?: any[] }
     }
     live?: { delayMs?: number }
     client?: { options?: Record<string, any> }
@@ -105,11 +106,11 @@ function loadTestControl(): TestControl {
 
 // Returns the skip decision for a given test name from sdk-test-control.json.
 // `kind` is 'direct' (matches by `test` field) or 'entityOp' (matches by
-// `entity` + `op`). `mode` is 'live' or 'unit'.
+// `entity` + `op`). `mode` is 'live', 'unit' or 'definition'.
 function isControlSkipped(
   kind: 'direct' | 'entityOp',
   name: string,
-  mode: 'live' | 'unit'
+  mode: 'live' | 'unit' | 'definition'
 ): { skip: boolean, reason?: string } {
   const ctrl = loadTestControl()
   const list = ctrl?.test?.skip?.[mode]?.[kind] ?? []

package/project/.sdk/tm/zig/core/utility.zig

@@ -1104,6 +1104,12 @@ pub fn prepare_query_util(ctx: *Context) Value {
         .array => h.getp(point, "params"),
         else => h.olist(),
     };
+    // A path parameter travels in the path. The generated config lists them
+    // as args.params, which prepare_params reads; params is the older list.
+    const aparams: Value = h.getpath(&.{ "args", "params" }, point);
+    // A query parameter travels under the name the definition gives it, its
+    // orig, which the model may have renamed for the caller.
+    const aquery: Value = h.getpath(&.{ "args", "query" }, point);
 
     const out = h.omap();
     if (reqmatch == .object) {
@@ -1120,7 +1126,29 @@ pub fn prepare_query_util(ctx: *Context) Value {
                     }
                 }
             }
-            if (!h.is_noval(val) and !std.mem.eql(u8, key, "$action") and !contained) h.setp(out, key, val);
+            if (!contained and aparams == .array) {
+                for (aparams.array.data.items) |pd| {
+                    const name = h.getp(pd, "name");
+                    if (name == .string and std.mem.eql(u8, name.string, key)) {
+                        contained = true;
+                        break;
+                    }
+                }
+            }
+            var wire: []const u8 = key;
+            if (aquery == .array) {
+                for (aquery.array.data.items) |qd| {
+                    const name = h.getp(qd, "name");
+                    const orig = h.getp(qd, "orig");
+                    if (name == .string and orig == .string and orig.string.len != 0 and
+                        std.mem.eql(u8, name.string, key))
+                    {
+                        wire = orig.string;
+                        break;
+                    }
+                }
+            }
+            if (!h.is_noval(val) and !std.mem.eql(u8, key, "$action") and !contained) h.setp(out, wire, val);
         }
     }
     return out;

package/project/sdkgen-package.json

@@ -3,7 +3,7 @@
     "package": 1
   },
   "name": "@voxgig/sdkgen",
-  "version": "4.30.2",
+  "version": "4.31.0",
   "provides": {
     "target": [
       "c",

package/src/cmp/ReadmeTop.ts

@@ -8,6 +8,7 @@ import {
 
 import { requirePath } from '../utility'
 import { featureDocs } from './FeatureDocs'
+import type { FeatureDoc } from './FeatureDocs'
 
 import {
   entityPrimaryOp, entityIdField, opRequestShape, entityPath, entityActions,
@@ -23,7 +24,6 @@ import {
   vendorCommand,
   apiName,
   nonAffiliation,
-  repoInfo,
   docsSiteUrl,
   SECURITY_EMAIL,
 } from '../helpers/packageMeta'
@@ -192,7 +192,7 @@ Learn more about Voxgig SDKs at [voxgig.com/sdk](${VOXGIG_SDK}).
     // Named here, in one line, with the detail left to each target's README.
     const features = featureDocs(model)
     if (0 < features.length) {
-      Content(`> **Features:** ${features.map((f: any) => '`' + f.n + '`').join(', ')} — opt-in,
+      Content(`> **Features:** ${features.map((f: FeatureDoc) => '`' + f.name + '`').join(', ')} — opt-in,
 > inactive until switched on, and configured per client. See the Features
 > section of any SDK README below for what each one does.
 
@@ -308,10 +308,9 @@ network, and no credentials:
     // 3. Packages — real published package name + install command per
     // ecosystem. A package that is NOT yet live on its registry (the fleet
     // default: 'pending') must NOT advertise a `npm install ...` that 404s —
-    // its Install cell links to the git-tag releases page instead. The go
-    // family resolves from the tag directly (`go get <mod>@latest`).
+    // its Install cell links to the target README's install section instead.
+    // The go family resolves from the default branch (`go get <mod>@latest`).
     if (pkgTargets.length > 0) {
-      const { tagsUrl } = repoInfo(model)
       Content(`## Packages
 
 | Language | Package | Install |
@@ -327,7 +326,9 @@ network, and no credentials:
         } else if ('tag' === state) {
           cell = '`' + vendorCommand(model, tgt.name) + '`'
         } else {
-          cell = `publish pending — [install from git tag](${tagsUrl})`
+          // The target README always gives a route that works without a
+          // tag, which a repository may not have.
+          cell = `publish pending — [install from source](${tgt.name}/README.md#install)`
         }
         Content(`| ${tgt.title} | \`${packageName(model, tgt.name)}\` | ${cell} |
 `)