@voxgig/sdkgen 4.31.1 → 4.32.1

package/project/.sdk/tm/scala/utility/Prepare.scala

@@ -80,6 +80,15 @@ object PrepareQuery {
           }
         case _ =>
       }
+      // A header parameter travels in the headers, which prepareHeaders fills.
+      Struct.getpath(point, java.util.List.of("args", "header")) match {
+        case l: JList[_] =>
+          val hit = l.iterator()
+          while (hit.hasNext) {
+            Struct.getprop(hit.next(), "name") match { case s: String => params.add(s); case _ => }
+          }
+        case _ =>
+      }
     }
 
     // A query parameter travels under the name the definition gives it, its
@@ -124,9 +133,39 @@ object PrepareHeaders {
   def prepareHeaders(ctx: Context): JMap[String, Object] = {
     val options = ctx.client.optionsMap()
     val headers = Struct.getprop(options, "headers")
-    if (headers == null) return new LinkedHashMap[String, Object]()
-    val out = Helpers.toMapAny(Struct.clone(headers))
-    if (out != null) out else new LinkedHashMap[String, Object]()
+    val cloned = if (headers == null) null else Helpers.toMapAny(Struct.clone(headers))
+    val out: JMap[String, Object] = if (cloned != null) cloned else new LinkedHashMap[String, Object]()
+
+    // A header parameter travels as a header, under the name the definition
+    // gives it, and only from this call's own arguments. It replaces a default
+    // of the same name, whatever its case.
+    if (ctx.point != null) {
+      Struct.getpath(ctx.point, java.util.List.of("args", "header")) match {
+        case l: JList[_] =>
+          val hit = l.iterator()
+          while (hit.hasNext) {
+            val hd = hit.next()
+            Struct.getprop(hd, "name") match {
+              case name: String if name.nonEmpty =>
+                val wire = Struct.getprop(hd, "orig") match {
+                  case o: String if o.nonEmpty => o
+                  case _ => name
+                }
+                var v: Object = if (ctx.reqmatch == null) null else Struct.getprop(ctx.reqmatch, name, null)
+                if (v == null && ctx.reqdata != null) v = Struct.getprop(ctx.reqdata, name, null)
+                if (v != null) {
+                  val key = wire.toLowerCase(java.util.Locale.ROOT)
+                  out.keySet().removeIf(k => k != null && k.toLowerCase(java.util.Locale.ROOT) == key)
+                  out.put(key, Struct.stringify(v))
+                }
+              case _ =>
+            }
+          }
+        case _ =>
+      }
+    }
+
+    out
   }
 }
 

package/project/.sdk/tm/scala/utility/Transform.scala

@@ -8,28 +8,52 @@ object TransformRequest {
   def transformRequest(ctx: Context): Object = {
     if (ctx.spec != null) ctx.spec.step = "reqform"
 
+    val reqdata = omit(ctx.reqdata, headerArgNames(ctx))
+
     val transform = Helpers.toMapAny(Struct.getprop(ctx.point, "transform"))
-    if (transform == null) return stripAction(ctx.reqdata)
+    if (transform == null) return stripAction(reqdata)
 
     val reqform = Struct.getprop(transform, "req", null)
-    if (reqform == null) return stripAction(ctx.reqdata)
+    if (reqform == null) return stripAction(reqdata)
 
     val data = new LinkedHashMap[String, Object]()
-    data.put("reqdata", ctx.reqdata)
+    data.put("reqdata", reqdata)
 
     stripAction(Struct.transform(data, reqform))
   }
 
   // `$action` selects the point (see MakePoint); it is never an API field, so
   // the body is a copy without it. The caller's map is left untouched.
-  private def stripAction(reqdata: Object): Object = {
+  private def stripAction(reqdata: Object): Object = omit(reqdata, Seq("$action"))
+
+  // A header argument travels as a header, which PrepareHeaders sends, so the
+  // body is built from the request data without it.
+  private def headerArgNames(ctx: Context): Seq[String] = {
+    if (ctx.point == null) return Seq.empty
+    Struct.getpath(ctx.point, java.util.List.of("args", "header")) match {
+      case l: java.util.List[_] =>
+        val names = scala.collection.mutable.ArrayBuffer[String]()
+        val hit = l.iterator()
+        while (hit.hasNext) {
+          val hd = hit.next()
+          Struct.getprop(hd, "name") match {
+            case name: String if name.nonEmpty => names += name
+            case _ =>
+          }
+        }
+        names.toSeq
+      case _ => Seq.empty
+    }
+  }
+
+  private def omit(reqdata: Object, names: Seq[String]): Object = {
     reqdata match {
-      case src: JMap[_, _] if src.containsKey("$action") =>
+      case src: JMap[_, _] if names.exists(n => src.containsKey(n)) =>
         val body = new LinkedHashMap[String, Object]()
         val it = src.asInstanceOf[JMap[String, Object]].entrySet().iterator()
         while (it.hasNext) {
           val e = it.next()
-          if ("$action" != e.getKey) body.put(e.getKey, e.getValue)
+          if (!names.contains(e.getKey)) body.put(e.getKey, e.getValue)
         }
         body
       case _ => reqdata

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

@@ -208,6 +208,13 @@ func makeUrlUtil(_ ctx: Context) throws -> String {
   var url = join(jtp(spec.base, spec.prefix, spec.path, spec.suffix), "/", true)
   let resmatch = VMap()
 
+  // A route the definition ends with a slash keeps it: a server such as a
+  // Django REST one redirects or refuses the route without it.
+  if let orig = gp(ctx.point, "orig").asString, orig.hasSuffix("/"), spec.suffix.isEmpty,
+     !url.hasSuffix("/") {
+    url += "/"
+  }
+
   for item in items(.map(spec.params)) {
     let key = item[0].asString ?? ""
     let val = item[1]

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

@@ -39,8 +39,28 @@ func preparePathUtil(_ ctx: Context) -> String {
 func prepareHeadersUtil(_ ctx: Context) -> VMap {
   let options = ctx.client!.optionsMap()
   let headers = gp(options, "headers")
-  if isNil(headers) { return VMap() }
-  return clone(headers).asMap ?? VMap()
+  let out = isNil(headers) ? VMap() : (clone(headers).asMap ?? VMap())
+
+  // A header parameter travels as a header, under the name the definition
+  // gives it, and only from this call's own arguments. It replaces a default
+  // of the same name, whatever its case.
+  if let ahl = gpath(ctx.point, "args", "header").asList {
+    for hd in ahl.items {
+      guard let name = gp(hd, "name").asString, !name.isEmpty else { continue }
+      let orig = gp(hd, "orig").asString ?? ""
+      let wire = orig.isEmpty ? name : orig
+      var val = gp(ctx.reqmatch, name)
+      if isNil(val) { val = gp(ctx.reqdata, name) }
+      if !isNil(val) {
+        let key = wire.lowercased()
+        for k in out.entries.keys where k.lowercased() == key {
+          _ = out.entries.removeValue(forKey: k)
+        }
+        out.entries[key] = .string(stringify(val))
+      }
+    }
+  }
+  return out
 }
 
 func prepareParamsUtil(_ ctx: Context) -> VMap {
@@ -73,6 +93,12 @@ func prepareQueryUtil(_ ctx: Context) -> VMap {
       paramnames.append(gp(pd, "name"))
     }
   }
+  // A header parameter travels in the headers, which prepareHeaders fills.
+  if let ahl = gpath(ctx.point, "args", "header").asList {
+    for hd in ahl.items {
+      paramnames.append(gp(hd, "name"))
+    }
+  }
 
   // A query parameter travels under the name the definition gives it, its
   // orig, which the model may have renamed for the caller.

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

@@ -57,9 +57,25 @@ func resultHeadersUtil(_ ctx: Context) -> Result {
 // `$action` selects the point (see makePointUtil); it is never an API field,
 // so the body is a copy without it. The caller's map is left untouched.
 private func stripAction(_ reqdata: Value) -> Value {
-  guard let src = reqdata.asMap, src.entries["$action"] != nil else { return reqdata }
+  return omitKeys(reqdata, ["$action"])
+}
+
+// A header argument travels as a header, which prepareHeadersUtil sends, so
+// the body is built from the request data without it.
+private func headerArgNames(_ ctx: Context) -> [String] {
+  guard let ahl = gpath(ctx.point, "args", "header").asList else { return [] }
+  return ahl.items.compactMap { hd in
+    guard let name = gp(hd, "name").asString, !name.isEmpty else { return nil }
+    return name
+  }
+}
+
+private func omitKeys(_ reqdata: Value, _ names: [String]) -> Value {
+  guard let src = reqdata.asMap, names.contains(where: { src.entries[$0] != nil }) else {
+    return reqdata
+  }
   let body = VMap()
-  for (key, val) in src.entries where "$action" != key {
+  for (key, val) in src.entries where !names.contains(key) {
     body.entries[key] = val
   }
   return .map(body)
@@ -68,11 +84,13 @@ private func stripAction(_ reqdata: Value) -> Value {
 func transformRequestUtil(_ ctx: Context) -> Value {
   if let sp = ctx.spec { sp.step = "reqform" }
 
-  guard let tfm = gp(ctx.point, "transform").asMap else { return stripAction(.map(ctx.reqdata)) }
+  let reqdata = omitKeys(.map(ctx.reqdata), headerArgNames(ctx))
+
+  guard let tfm = gp(ctx.point, "transform").asMap else { return stripAction(reqdata) }
   let reqform = gp(tfm, "req")
-  if isNil(reqform) { return stripAction(.map(ctx.reqdata)) }
+  if isNil(reqform) { return stripAction(reqdata) }
 
-  return stripAction(transform(.map(vm(("reqdata", .map(ctx.reqdata)))), reqform))
+  return stripAction(transform(.map(vm(("reqdata", reqdata))), reqform))
 }
 
 func transformResponseUtil(_ ctx: Context) -> Value {

package/project/.sdk/tm/ts/src/Response.ts

@@ -14,13 +14,26 @@ class Response {
     this.status = getprop(resmap, 'status', -1)
     this.statusText = getprop(resmap, 'statusText', '')
     this.headers = getprop(resmap, 'headers')
-    this.json = resmap.json ? resmap.json.bind(resmap) : async () => undefined
+    this.json = readJson(resmap)
     this.body = getprop(resmap, 'body')
     this.err = getprop(resmap, 'err')
   }
 }
 
 
+// An empty body, such as the one an accepted delete answers with, is no
+// body: parsing it as JSON would throw after the call has succeeded.
+function readJson(resmap: Record<string, any>): Function {
+  if ('function' === typeof resmap.text) {
+    return async () => {
+      const text = await resmap.text()
+      return '' === text.trim() ? undefined : JSON.parse(text)
+    }
+  }
+  return resmap.json ? resmap.json.bind(resmap) : async () => undefined
+}
+
+
 export {
   Response,
 }

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

@@ -26,6 +26,13 @@ function makeUrl(ctx: Context): Error | string {
   let url = join([spec.base, spec.prefix, spec.path, spec.suffix], '/', true)
   let resmatch: Record<string, any> = {}
 
+  // A route the definition ends with a slash keeps it: a server such as a
+  // Django REST one redirects or refuses the route without it.
+  const orig = ctx.point?.orig
+  if ('string' === typeof orig && orig.endsWith('/') && !spec.suffix && !url.endsWith('/')) {
+    url += '/'
+  }
+
   const params = spec.params
 
   for (let [key, val] of items(params)) {

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

@@ -6,6 +6,7 @@ function prepareHeaders(ctx: Context) {
   const struct = ctx.utility.struct
   const clone = struct.clone
   const getprop = struct.getprop
+  const stringify = struct.stringify
 
   const client = ctx.client
 
@@ -13,6 +14,21 @@ function prepareHeaders(ctx: Context) {
 
   let out = clone(getprop(options, 'headers', {}))
 
+  // A header parameter travels as a header, under the name the definition
+  // gives it, and only from this call's own arguments. It replaces a default
+  // of the same name, whatever its case.
+  for (const h of (ctx.point?.args?.header || [])) {
+    if ('string' !== typeof h?.name || '' === h.name) continue
+    const val = getprop(ctx.reqmatch, h.name) ?? getprop(ctx.reqdata, h.name)
+    if (null != val) {
+      const wire = String(h.orig || h.name).toLowerCase()
+      for (const key of Object.keys(out)) {
+        if (wire === key.toLowerCase()) delete out[key]
+      }
+      out[wire] = stringify(val)
+    }
+  }
+
   return out
 }
 

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

@@ -16,8 +16,10 @@ function prepareQuery(ctx: Context) {
 
   // 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.
+  // A header parameter travels in the headers, which prepareHeaders fills.
   const inpath: string[] = params.concat(
-    (point.args?.params || []).map((p: any) => p?.name))
+    (point.args?.params || []).map((p: any) => p?.name),
+    (point.args?.header || []).map((h: any) => h?.name))
 
   // A query parameter travels under the name the definition gives it, its
   // orig, which the model may have renamed for the caller.

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

@@ -15,7 +15,7 @@ function transformRequest(ctx: Context) {
   try {
     const reqform = point.transform.req
     const reqdata = isfunc(reqform) ? reqform(ctx) : transform({
-      reqdata: ctx.reqdata
+      reqdata: omit(ctx.reqdata, headerArgNames(ctx))
     }, reqform)
 
     return stripAction(reqdata)
@@ -29,17 +29,30 @@ function transformRequest(ctx: Context) {
 
 
 function stripAction(reqdata: any) {
+  return omit(reqdata, ['$action'])
+}
+
+
+// A header argument travels as a header, which prepareHeaders sends, so the
+// body is built from the request data without it.
+function headerArgNames(ctx: Context): string[] {
+  return (ctx.point?.args?.header || []).map((h: any) => h?.name)
+    .filter((name: any) => 'string' === typeof name && '' !== name)
+}
+
+
+function omit(reqdata: any, names: string[]) {
   if (null == reqdata || 'object' !== typeof reqdata || Array.isArray(reqdata)) {
     return reqdata
   }
 
-  if (!Object.prototype.hasOwnProperty.call(reqdata, '$action')) {
+  if (!names.some((name) => Object.prototype.hasOwnProperty.call(reqdata, name))) {
     return reqdata
   }
 
   const body: Record<string, any> = {}
   for (const key of Object.keys(reqdata)) {
-    if ('$action' === key) {
+    if (names.includes(key)) {
       continue
     }
     if ('__proto__' === key) {

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

@@ -16,6 +16,7 @@ type DefinitionPoint = {
   action?: string
   args: { name: string, wire: string, value: any }[]
   select: Record<string, any>
+  headers?: { name: string, wire: string, value: any }[]
   query: string[]
   auth: Credential[][] | null
   status: number
@@ -49,6 +50,7 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
 
   const input: any = { ...point.select }
   for (const arg of point.args) input[arg.name] = arg.value
+  for (const h of point.headers || []) input[h.name] = h.value
   if (null != point.action) input.$action = point.action
 
   let result: any
@@ -70,7 +72,9 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
     const arg = point.args.find((a) => a.wire === name)
     return null == arg ? '{' + name + '}' : encodeURIComponent(String(arg.value))
   })
-  assert.equal(url.pathname, route, 'route')
+  // Read as the request was, so a backslash in the definition's path, as in
+  // GitLab's `Packages\(\)`, is the slash the URL parser makes it.
+  assert.equal(url.pathname, new URL(BASE + route).pathname, 'route')
 
   // Only what the definition declares, so never a path parameter again.
   const credentialQuery = (point.auth || []).flat()
@@ -87,6 +91,18 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
       'credential not sent as the definition declares it: ' + JSON.stringify(point.auth))
   }
 
+  // A header parameter goes out as a header. The credential check above owns
+  // any header the security scheme names, and the SDK sets the content type
+  // from the body it sends.
+  const credentialHeaders = (point.auth || []).flat()
+    .filter((c) => 'header' === c.in).map((c) => c.name.toLowerCase())
+  for (const h of point.headers || []) {
+    const wire = h.wire.toLowerCase()
+    if (credentialHeaders.includes(wire) || 'content-type' === wire) continue
+    assert.equal(new Headers(init.headers).get(wire), String(h.value),
+      'header parameter not sent as a header: ' + h.wire)
+  }
+
   if (null != error) {
     throw error
   }
@@ -105,7 +121,7 @@ async function runDefinitionPoint(SDK: any, point: DefinitionPoint): Promise<voi
     }
   }
   else if ('load' === point.op || 'create' === point.op || 'update' === point.op) {
-    const record = recordOf(point.sample, point.idField)
+    const record = recordOf(point.sample, point.idField, point.entity)
     if (null != record) {
       assert.equal(result?.data?.()?.[point.idField], record[point.idField],
         'the entity does not hold the record the definition example returns')
@@ -145,33 +161,79 @@ function placed(cred: Credential, headers: Headers, url: URL): boolean {
 }
 
 
-// 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.
+// What an envelope may hold beside what it carries, compared without case,
+// `_` or `-`: status, paging and the page's own metadata, each by its whole
+// name, so a record's homepage or preview is data of its own.
+const ENVELOPE_KEYS = new Set([
+  'success', 'status', 'ok', 'message', 'code', 'error', 'errorcode', 'errormessage',
+  'requestid', 'timestamp', 'took', 'version', 'apiversion', 'object', 'url',
+  'count', 'total', 'totalcount', 'totalhits', 'totalitems', 'totalpages', 'totalresults',
+  'totalrecords', 'totalrowcount', 'totalentries', 'itemcount', 'resultcount', 'rowcount',
+  'page', 'pages', 'pagecount', 'pagenumber', 'pageindex', 'pagesize', 'perpage',
+  'currentpage', 'lastpage', 'limit', 'offset', 'cursor', 'nextcursor', 'prevcursor',
+  'previouscursor', 'next', 'nextpage', 'nexturl', 'nextlink', 'nextpagetoken', 'nexttoken',
+  'pagetoken', 'continuationtoken', 'prev', 'previous', 'prevpage', 'previouspage',
+  'prevurl', 'previousurl', 'prevlink', 'hasmore', 'hasnext', 'hasnextpage', 'hasprevious',
+  'haspreviouspage', 'more', 'meta', 'metadata', 'pagination', 'paging', 'pageinfo', 'links',
+])
+
+
+function envelopeKey(key: string): boolean {
+  return ENVELOPE_KEYS.has(squash(key))
+}
+
+
+function ownData(sample: any): boolean {
+  return Object.entries(sample).some(([key, value]) =>
+    null != value && 'object' !== typeof value && !envelopeKey(key))
+}
+
+
+function isRecord(value: any): boolean {
+  return null != value && 'object' === typeof value && !Array.isArray(value)
+}
+
+
+// The records a list response holds: the body itself, or the one non-empty
+// list of objects in a page. Anything else, such as a record that happens to
+// hold a list, proves nothing.
 function recordsOf(sample: any): any[] | null {
   if (Array.isArray(sample)) {
     return sample
   }
-  if (null == sample || 'object' !== typeof sample) {
+  if (!isRecord(sample) || ownData(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)))
+    v.every(isRecord))
   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)) {
+// The record a single-item response returns: the body, or the one object
+// with the identity field that an envelope carries, under the entity's name
+// or beside envelope keys alone. Otherwise the body is the record itself,
+// such as GitHub's check suite preferences beside their repository.
+function recordOf(sample: any, idField: string, entity?: string): any {
+  if (!isRecord(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
+  const keys = Object.keys(sample)
+  const inner = keys.filter((key) => isRecord(sample[key]) && null != sample[key][idField])
+  if (1 !== inner.length) {
+    return null
+  }
+  const named = null != entity && squash(inner[0]) === squash(entity) && !ownData(sample)
+  const alone = keys.every((key) => key === inner[0] || envelopeKey(key))
+  return named || alone ? sample[inner[0]] : null
+}
+
+
+function squash(name: string): string {
+  return name.toLowerCase().replace(/[_-]/g, '')
 }
 
 

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

@@ -259,6 +259,31 @@ describe('PrimaryUtility', async () => {
   })
 
 
+  // An accepted delete answers 202 with an empty body, which is no body.
+  test('resbody-empty', async () => {
+    const read = async (res: any) => {
+      const reqClient = new (SDK as any)({
+        base: 'http://localhost:8080',
+        system: { fetch: async () => res },
+      })
+      const reqUtility = reqClient.utility()
+      const ctx = reqUtility.makeContext({
+        opname: 'remove',
+        spec: {
+          alias: {}, base: 'http://localhost/', headers: {}, method: 'DELETE',
+          params: {}, path: '/p0', prefix: '', query: {}, suffix: '',
+        },
+      }, reqClient._rootctx)
+      ctx.client = reqClient
+      await reqUtility.makeRequest(ctx)
+      return reqUtility.resultBody(ctx)
+    }
+
+    equal((await read(new Response('', { status: 202 }))).body, undefined)
+    deepStrictEqual((await read(new Response('{"a":1}', { status: 200 }))).body, { a: 1 })
+  })
+
+
   test('request-basic', async () => {
     const mockFetch = async (url: string, init: any) => ({
       status: 200,