@voxgig/sdkgen 4.31.0 → 4.32.0

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/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/zig/core/utility.zig

@@ -764,6 +764,15 @@ pub fn make_url_util(ctx: *Context) E![]const u8 {
         h.vstr(spec.suffix),
     }), "/", true) catch "";
 
+    // 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 = h.getp(ctx.point, "orig");
+    if (orig == .string and std.mem.endsWith(u8, orig.string, "/") and spec.suffix.len == 0 and
+        !std.mem.endsWith(u8, url, "/"))
+    {
+        url = std.mem.concat(h.A(), u8, &.{ url, "/" }) catch url;
+    }
+
     const resmatch = h.omap();
 
     if (spec.params == .object) {
@@ -1043,12 +1052,37 @@ pub fn prepare_headers_util(ctx: *Context) Value {
     const options: Value = if (ctx.client) |client| client.options_map() else ctx.options;
 
     const headers = h.getp(options, "headers");
-    if (h.is_noval(headers)) return h.omap();
-
-    return switch (h.clone(headers)) {
+    const out: Value = if (h.is_noval(headers)) h.omap() else switch (h.clone(headers)) {
         .object => h.clone(headers),
         else => h.omap(),
     };
+
+    // 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.
+    const aheader: Value = h.getpath(&.{ "args", "header" }, ctx.point);
+    if (aheader == .array) {
+        for (aheader.array.data.items) |hd| {
+            const name = h.getp(hd, "name");
+            if (name != .string or name.string.len == 0) continue;
+            const orig = h.getp(hd, "orig");
+            const wire: []const u8 = if (orig == .string and orig.string.len != 0) orig.string else name.string;
+            var val = h.getp(ctx.reqmatch, name.string);
+            if (h.is_noval(val)) val = h.getp(ctx.reqdata, name.string);
+            if (h.is_noval(val)) continue;
+            const key = std.ascii.allocLowerString(h.A(), wire) catch wire;
+            while (true) {
+                var kit = out.object.iterator();
+                const same: ?[]const u8 = while (kit.next()) |kv| {
+                    if (std.ascii.eqlIgnoreCase(kv.key_ptr.*, key)) break kv.key_ptr.*;
+                } else null;
+                _ = out.object.fetchOrderedRemove(same orelse break);
+            }
+            h.setp(out, key, h.vstr(h.stringify(val)));
+        }
+    }
+
+    return out;
 }
 
 pub fn prepare_body_util(ctx: *Context) Value {
@@ -1094,6 +1128,16 @@ pub fn prepare_path_util(ctx: *Context) []const u8 {
     return vs.join(h.A(), parts, "/", true) catch "";
 }
 
+// Whether a list of argument definitions names this key.
+fn names_key(defs: Value, key: []const u8) bool {
+    if (defs != .array) return false;
+    for (defs.array.data.items) |d| {
+        const name = h.getp(d, "name");
+        if (name == .string and std.mem.eql(u8, name.string, key)) return true;
+    }
+    return false;
+}
+
 pub fn prepare_query_util(ctx: *Context) Value {
     const point = ctx.point;
     const reqmatch: Value = switch (ctx.reqmatch) {
@@ -1107,6 +1151,8 @@ pub fn prepare_query_util(ctx: *Context) Value {
     // 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 header parameter travels in the headers, which prepare_headers fills.
+    const aheader: Value = h.getpath(&.{ "args", "header" }, 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);
@@ -1126,15 +1172,7 @@ pub fn prepare_query_util(ctx: *Context) Value {
                     }
                 }
             }
-            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;
-                    }
-                }
-            }
+            if (!contained) contained = names_key(aparams, key) or names_key(aheader, key);
             var wire: []const u8 = key;
             if (aquery == .array) {
                 for (aquery.array.data.items) |qd| {
@@ -1406,13 +1444,33 @@ pub fn result_body_util(ctx: *Context) ?*SdkResult {
 // `$action` selects the point (see make_point_util); it is never an API
 // field, so the body is a copy without it. The caller's map is left untouched.
 fn strip_action(reqdata: Value) Value {
+    return omit_keys(reqdata, h.vnull(), true);
+}
+
+// A header argument travels as a header, which prepare_headers_util sends, so
+// the body is built from the request data without it.
+fn dropped(key: []const u8, point: Value, action: bool) bool {
+    if (action) return std.mem.eql(u8, key, "$action");
+    const aheader: Value = h.getpath(&.{ "args", "header" }, point);
+    if (aheader != .array) return false;
+    for (aheader.array.data.items) |hd| {
+        const name = h.getp(hd, "name");
+        if (name == .string and std.mem.eql(u8, name.string, key)) return true;
+    }
+    return false;
+}
+
+fn omit_keys(reqdata: Value, point: Value, action: bool) Value {
     if (reqdata != .object) return reqdata;
-    if (reqdata.object.get("$action") == null) return reqdata;
-    const body = h.omap();
+    var found = false;
     var it = reqdata.object.iterator();
-    while (it.next()) |kv| {
+    while (it.next()) |kv| found = found or dropped(kv.key_ptr.*, point, action);
+    if (!found) return reqdata;
+    const body = h.omap();
+    var bit = reqdata.object.iterator();
+    while (bit.next()) |kv| {
         const key = kv.key_ptr.*;
-        if (!std.mem.eql(u8, key, "$action")) h.setp(body, key, kv.value_ptr.*);
+        if (!dropped(key, point, action)) h.setp(body, key, kv.value_ptr.*);
     }
     return body;
 }
@@ -1423,16 +1481,18 @@ pub fn transform_request_util(ctx: *Context) Value {
 
     if (spec) |sp| sp.step = "reqform";
 
+    const reqdata = omit_keys(ctx.reqdata, point, false);
+
     const transform = h.to_map(h.getp(point, "transform"));
-    if (h.is_noval(transform)) return strip_action(ctx.reqdata);
+    if (h.is_noval(transform)) return strip_action(reqdata);
 
     const reqform = h.getp(transform, "req");
-    if (h.is_noval(reqform)) return strip_action(ctx.reqdata);
+    if (h.is_noval(reqform)) return strip_action(reqdata);
 
-    const store = h.jo(&.{.{ "reqdata", ctx.reqdata }});
+    const store = h.jo(&.{.{ "reqdata", reqdata }});
     // transform now reports collected injection errors beside the value; .out
     // is what it used to return on its own, errors or not.
-    const tres = vs.transform(h.A(), store, reqform) catch return strip_action(ctx.reqdata);
+    const tres = vs.transform(h.A(), store, reqform) catch return strip_action(reqdata);
     return strip_action(tres.out);
 }
 

package/project/sdkgen-package.json

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

package/src/action/package.ts

@@ -737,7 +737,7 @@ async function npmFetch(pkgname: string, actx: ActionContext) {
   try {
     const out = await run(
       'win32' === process.platform ? 'npm.cmd' : 'npm',
-      ['install', '--save-dev', pkgname + '@latest'],
+      npmFetchArgs(pkgname),
       { cwd, maxBuffer: 64 * 1024 * 1024 })
 
     actx.log.debug({
@@ -755,6 +755,14 @@ async function npmFetch(pkgname: string, actx: ActionContext) {
 }
 
 
+// The saved range is a tilde, as the scaffold writes it: a caret would let
+// the next minor float in, and a scaffold contract can change in a minor.
+// An .npmrc `save-exact` outranks the prefix, so it is switched off here.
+function npmFetchArgs(pkgname: string): string[] {
+  return ['install', '--save-dev', '--save-exact=false', '--save-prefix=~', pkgname + '@latest']
+}
+
+
 function validateFetched(
   pkgname: string, installed: Installed[], actx: ActionContext,
 ) {
@@ -938,6 +946,7 @@ export {
   package_add,
   package_update,
   installedFrom,
+  npmFetchArgs,
   resolvePackage,
   selectItems,
   parseAliases,