@voxgig/sdkgen 4.30.3 → 4.31.0

package/project/.sdk/src/cmp/swift/PrepareAuth_swift.ts

@@ -148,9 +148,11 @@ function basicBlock(spec: AuthSpec): string {
   if (!spec.basic) return ''
 
   return `
-  // True HTTP Basic Auth needs TWO credentials, base64-joined - a single
+  // True HTTP Basic Auth joins the two credentials, base64-encoded - a single
   // token in the header (the branch below) can never authenticate against
   // an API that actually checks \`Authorization: Basic base64(user:pass)\`.
+  // The password may be empty (RFC 7617): Lob, for one, documents the key as
+  // the user with a blank password (\`curl -u key:\`).
   if true == gpath(options, "auth", "basic").asBool {
     let secret = getprop(.map(options), .string(optionSecret), .string(notFound))
 
@@ -159,12 +161,12 @@ function basicBlock(spec: AuthSpec): string {
       noSecret = true
     }
 
-    if skip || noSecret {
+    if skip {
       headers.entries.removeValue(forKey: headerAuth)
     } else {
       var authPrefix = ""
       if let ap = gpath(options, "auth", "prefix").asString { authPrefix = ap }
-      let joined = (apikey.asString ?? "") + ":" + (secret.asString ?? "")
+      let joined = (apikey.asString ?? "") + ":" + (noSecret ? "" : (secret.asString ?? ""))
       let b64 = Data(joined.utf8).base64EncodedString()
       // Empty prefix (raw credential) must not add a leading space.
       headers.entries[headerAuth] = .string(authPrefix == "" ? b64 : authPrefix + " " + b64)

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

@@ -108,19 +108,21 @@ ${cookieHelper(spec.where)}
   // query parameter or a cookie, so the branch is emitted only where it
   // can mean something.
   const basicBlock = (spec.basic && 'header' === spec.where) ? `
-  // True HTTP Basic Auth needs TWO credentials, base64-joined - a single
+  // True HTTP Basic Auth joins the two credentials, base64-encoded - a single
   // token in the header (the branch below) can never authenticate against
   // an API that actually checks \`Authorization: Basic base64(user:pass)\`.
+  // The password may be empty (RFC 7617): Lob, for one, documents the key as
+  // the user with a blank password (\`curl -u key:\`).
   if (true === options.auth.basic) {
     const secret = getprop(options, OPTION_secret, NOTFOUND)
     const noApikey = NOTFOUND === apikey || null == apikey || '' === apikey
-    const noSecret = NOTFOUND === secret || null == secret || '' === secret
+    const pass = NOTFOUND === secret || null == secret ? '' : secret
 
-    if (noApikey || noSecret) {
+    if (noApikey) {
       delprop(headers, CRED_name)
     }
     else {
-      const b64 = Buffer.from(apikey + ':' + secret).toString('base64')
+      const b64 = Buffer.from(apikey + ':' + pass).toString('base64')
       setprop(headers, CRED_name, prefix ? prefix + ' ' + b64 : b64)
     }
 

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

@@ -16,12 +16,18 @@ ${installCommand(model, target.name)}
   }
 
   // Publish pending: the package is not yet on npm, so install from the
-  // git release tag instead of a `npm install` that would 404.
-  const { releasesUrl } = repoInfo(model)
+  // git release tag instead of a `npm install` that would 404. A repository
+  // may have no tag at all, and npm cannot install a subdirectory of a git
+  // URL, so a clone is always offered too. It carries the compiled dist/.
+  const { releasesUrl, repoUrl, repo } = repoInfo(model)
   Content(`This package is not yet published to npm. Install it from the GitHub
-release tag (\`${target.name}/vX.Y.Z\`):
+release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})), or from a
+clone, which carries the compiled \`dist/\`:
 
-- Releases: [${releasesUrl}](${releasesUrl})
+\`\`\`bash
+git clone ${repoUrl}
+npm install ./${repo}/${target.name}
+\`\`\`
 
 `)
 })

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

@@ -0,0 +1,40 @@
+import { cmp, File, Content, definitionPlan } from '@voxgig/sdkgen'
+
+
+// Every operation checked against the API definition, offline, in the SDK's
+// own suite: see test/definition-runner.
+const TestDefinition = cmp(function TestDefinition(props: any) {
+  const plan = definitionPlan(props.ctx$)
+  if (0 === plan.length) return
+
+  File({ name: 'definition.test.ts' }, () => Content(`import { describe, test } from 'node:test'
+import { SDK } from '..'
+import { runDefinitionPoint } from './definition-runner'
+import { isControlSkipped } from './utility'
+
+
+// Generated from the API definition, not from the model this SDK was built
+// from: the route, the declared query parameters, the credential the security
+// scheme names, and the definition's own response example.
+const PLAN: any[] = ${JSON.stringify(plan, null, 2)}
+
+
+describe('definition', () => {
+  for (const point of PLAN) {
+    test(point.entity + '.' + point.op + ' ' + point.method + ' ' + point.path, async (t) => {
+      const control = isControlSkipped('entityOp', point.entity + '.' + point.op, 'definition')
+      if (control.skip) {
+        t.skip(control.reason || 'skipped via sdk-test-control.json')
+        return
+      }
+      await runDefinitionPoint(SDK, point)
+    })
+  }
+})
+`))
+})
+
+
+export {
+  TestDefinition
+}

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

@@ -8,6 +8,7 @@ import { cmp, each, Folder, entityCollection,
 
 
 import { TestLive } from './TestLive_ts'
+import { TestDefinition } from './TestDefinition_ts'
 import { TestDirect } from './TestDirect_ts'
 import { TestEntity } from './TestEntity_ts'
 import { ReadmeExampleTest } from './ReadmeExampleTest_ts'
@@ -23,6 +24,7 @@ const Test = cmp(function Test(props: any) {
     // Write-once: a project's edited control file survives regeneration.
     TestControl({ target, dir: 'test' })
     TestLive({ target })
+    TestDefinition({ target })
 
     ReadmeExampleTest({ target })
     ReadmeExamplesTest({ target })

package/project/.sdk/src/cmp/zig/PrepareAuth_zig.ts

@@ -330,9 +330,11 @@ fn base64_std(text: []const u8) []const u8 {
 // something — and only when the model says the scheme IS basic.
 function basicBlock(): string {
   return `
-    // True HTTP Basic Auth needs TWO credentials, base64-joined - a single
+    // True HTTP Basic Auth joins the two credentials, base64-encoded - a single
     // token in the header (the branch below) can never authenticate against
     // an API that actually checks \`Authorization: Basic base64(user:pass)\`.
+    // The password may be empty (RFC 7617): Lob, for one, documents the key as
+    // the user with a blank password (\`curl -u key:\`).
     if (is_true(h.getpath(&.{ "auth", "basic" }, options))) {
         const secret = vs.getprop(h.A(), options, h.vstr(OPTION_SECRET), h.vstr(NOT_FOUND)) catch h.vstr(NOT_FOUND);
 
@@ -342,7 +344,7 @@ function basicBlock(): string {
             else => false,
         };
 
-        if (skip or no_secret) {
+        if (skip) {
             h.del_prop(headers, h.vstr(CRED_NAME));
         } else {
             const basic_prefix: []const u8 = switch (h.getpath(&.{ "auth", "prefix" }, options)) {
@@ -353,7 +355,7 @@ function basicBlock(): string {
                 .string => |s| s,
                 else => "",
             };
-            const secret_val: []const u8 = switch (secret) {
+            const secret_val: []const u8 = if (no_secret) "" else switch (secret) {
                 .string => |s| s,
                 else => "",
             };

package/project/.sdk/tm/c/utility/prepare_query.c

@@ -15,12 +15,44 @@ static bool params_contains(voxgig_value* params, const char* key) {
   return false;
 }
 
+// A path parameter travels in the path. The generated config lists them as
+// args.params, which prepare_params reads; params is the older list of names.
+static bool args_params_contains(voxgig_value* aparams, const char* key) {
+  if (voxgig_is_list(aparams)) {
+    voxgig_list* pl = voxgig_as_list(aparams);
+    for (size_t i = 0; i < pl->len; i++) {
+      voxgig_value* name = getp(pl->items[i], "name");
+      if (voxgig_is_string(name) && strcmp(voxgig_as_string(name), key) == 0) return true;
+    }
+  }
+  return false;
+}
+
+// A query parameter travels under the name the definition gives it, its orig,
+// which the model may have renamed for the caller.
+static const char* query_wire_name(voxgig_value* aquery, const char* key) {
+  if (voxgig_is_list(aquery)) {
+    voxgig_list* ql = voxgig_as_list(aquery);
+    for (size_t i = 0; i < ql->len; i++) {
+      voxgig_value* name = getp(ql->items[i], "name");
+      voxgig_value* orig = getp(ql->items[i], "orig");
+      if (voxgig_is_string(name) && voxgig_is_string(orig) &&
+          strcmp(voxgig_as_string(name), key) == 0 && voxgig_as_string(orig)[0] != '\0') {
+        return voxgig_as_string(orig);
+      }
+    }
+  }
+  return key;
+}
+
 voxgig_value* prepare_query_util(Context* ctx) {
   voxgig_value* point = ctx->point;
   voxgig_value* reqmatch = voxgig_is_map(ctx->reqmatch) ? ctx->reqmatch : voxgig_new_map();
 
   voxgig_value* params = getp(point, "params");
   if (!voxgig_is_list(params)) params = voxgig_new_list();
+  voxgig_value* aparams = getpath2(point, "args", "params");
+  voxgig_value* aquery = getpath2(point, "args", "query");
 
   voxgig_value* out = voxgig_new_map();
   if (voxgig_is_map(reqmatch)) {
@@ -29,8 +61,8 @@ voxgig_value* prepare_query_util(Context* ctx) {
       const char* key = rm->entries[i].key;
       voxgig_value* val = rm->entries[i].value;
       if (!v_is_noval(val) && !v_is_null(val) && strcmp(key, "$action") != 0 &&
-          !params_contains(params, key)) {
-        setp(out, key, v_share(val));
+          !params_contains(params, key) && !args_params_contains(aparams, key)) {
+        setp(out, query_wire_name(aquery, key), v_share(val));
       }
     }
   }

package/project/.sdk/tm/clojure/src/sdk/core.clj

@@ -500,12 +500,30 @@
   (let [point (oget ctx :point)
         reqmatch (or (oget ctx :reqmatch) (vs/jm))
         params (let [p (when point (vs/getprop point "params"))] (if (vs/islist p) p (vs/jt)))
-        pset (into #{} (vec params))
+        ;; A path parameter travels in the path. The generated config lists
+        ;; them as args.params, which u-prepare-params reads; params is the
+        ;; older list of names.
+        aparams (let [args (when point (vs/getprop point "args"))
+                      p (when (vs/ismap args) (vs/getprop args "params"))]
+                  (if (vs/islist p) p (vs/jt)))
+        pset (into (into #{} (vec params))
+                   (keep (fn [pd] (when (vs/ismap pd) (vs/getprop pd "name"))) (vec aparams)))
+        ;; A query parameter travels under the name the definition gives it,
+        ;; its orig, which the model may have renamed for the caller.
+        aquery (let [args (when point (vs/getprop point "args"))
+                     q (when (vs/ismap args) (vs/getprop args "query"))]
+                 (if (vs/islist q) q (vs/jt)))
+        wire (into {}
+                   (keep (fn [qd]
+                           (when (vs/ismap qd)
+                             (let [n (vs/getprop qd "name") o (vs/getprop qd "orig")]
+                               (when (and (string? n) (string? o) (not= "" o)) [n o]))))
+                         (vec aquery)))
         out (vs/jm)]
     (doseq [item (or (vs/items reqmatch) [])]
       (let [k (vs/getprop item 0) v (vs/getprop item 1)]
         (when (and (some? v) (string? k) (not= "$action" k) (not (contains? pset k)))
-          (.put ^java.util.Map out k v))))
+          (.put ^java.util.Map out (get wire k k) v))))
     out))
 
 ;; `$action` selects the point (see u-make-point); it is never an API field,

package/project/.sdk/tm/cpp/utility/pipeline.hpp

@@ -1022,12 +1022,41 @@ inline Value prepareQuery(CtxPtr ctx) {
     return false;
   };
 
+  // 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.
+  Value aparams = point.is_map() ? getp(getp(point, "args"), "params") : Value::undef();
+  auto in_args = [&](const std::string& s) {
+    if (!aparams.is_list()) return false;
+    for (const auto& pd : *aparams.as_list()) {
+      Value name = getp(pd, "name");
+      if (name.is_string() && name.as_string() == s) return true;
+    }
+    return false;
+  };
+
+  // A query parameter travels under the name the definition gives it, its
+  // orig, which the model may have renamed for the caller.
+  Value aquery = point.is_map() ? getp(getp(point, "args"), "query") : Value::undef();
+  auto wire_name = [&](const std::string& s) {
+    if (aquery.is_list()) {
+      for (const auto& qd : *aquery.as_list()) {
+        Value name = getp(qd, "name");
+        Value orig = getp(qd, "orig");
+        if (name.is_string() && orig.is_string() && name.as_string() == s &&
+            !orig.as_string().empty()) {
+          return orig.as_string();
+        }
+      }
+    }
+    return s;
+  };
+
   Value out = vmap();
   for (const auto& item : Struct::items(reqmatch)) {
     std::string key = as_str(pair_key(item));
     Value val = pair_val(item);
-    if (!is_nullish(val) && "$action" != key && !contains_str(params, key)) {
-      map_put(out, key, val);
+    if (!is_nullish(val) && "$action" != key && !contains_str(params, key) && !in_args(key)) {
+      map_put(out, wire_name(key), val);
     }
   }
   return out;

package/project/.sdk/tm/csharp/utility/PrepareQuery.cs

@@ -12,12 +12,40 @@ public static partial class SdkUtility
         var point = ctx.Point;
         var reqmatch = ctx.Reqmatch ?? new Dictionary<string, object?>();
 
-        List<object?>? paramnames = null;
+        var paramnames = new List<object?>();
         if (point != null && StructUtils.GetProp(point, "params") is List<object?> pl)
         {
-            paramnames = pl;
+            paramnames.AddRange(pl);
+        }
+        // A path parameter travels in the path. The generated config lists them
+        // as args.params, which PrepareParams reads; params is the older list.
+        if (point != null &&
+            StructUtils.GetPath(point, StructUtils.Jt("args", "params")) is List<object?> apl)
+        {
+            foreach (var pd in apl)
+            {
+                if (StructUtils.GetProp(pd, "name") is string name)
+                {
+                    paramnames.Add(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 = new Dictionary<string, string>();
+        if (point != null &&
+            StructUtils.GetPath(point, StructUtils.Jt("args", "query")) is List<object?> aql)
+        {
+            foreach (var qd in aql)
+            {
+                if (StructUtils.GetProp(qd, "name") is string qname &&
+                    StructUtils.GetProp(qd, "orig") is string qorig && qorig != "")
+                {
+                    wire[qname] = qorig;
+                }
+            }
         }
-        paramnames ??= new List<object?>();
 
         var query = new Dictionary<string, object?>();
         foreach (var item in StructUtils.Items(reqmatch))
@@ -26,7 +54,7 @@ public static partial class SdkUtility
             var val = item[1];
             if (val != null && "$action" != key && !ContainsStr(paramnames, key))
             {
-                query[key] = val;
+                query[wire.TryGetValue(key, out var wkey) ? wkey : key] = val;
             }
         }
 

package/project/.sdk/tm/elixir/lib/projectname/utility.ex

@@ -1206,12 +1206,46 @@ defmodule ProjectName.Utility do
         Enum.map(0..(S.size(params) - 1), fn i -> S.getelem(params, i) end)
       end
 
+    # A path parameter travels in the path. The generated config lists them
+    # as args.params, which prepare_params reads; params is the older list.
+    aparams = if point != nil, do: S.getpath(point, "args.params"), else: nil
+
+    arg_strs =
+      if S.islist(aparams) and S.size(aparams) > 0 do
+        Enum.map(0..(S.size(aparams) - 1), fn i ->
+          S.getprop(S.getelem(aparams, i), "name")
+        end)
+      else
+        []
+      end
+
+    param_strs = param_strs ++ arg_strs
+
+    # A query parameter travels under the name the definition gives it, its
+    # orig, which the model may have renamed for the caller.
+    aquery = if point != nil, do: S.getpath(point, "args.query"), else: nil
+
+    wire =
+      if S.islist(aquery) and S.size(aquery) > 0 do
+        Enum.reduce(0..(S.size(aquery) - 1), %{}, fn i, acc ->
+          qd = S.getelem(aquery, i)
+          name = S.getprop(qd, "name")
+          orig = S.getprop(qd, "orig")
+
+          if is_binary(name) and is_binary(orig) and orig != "",
+            do: Map.put(acc, name, orig),
+            else: acc
+        end)
+      else
+        %{}
+      end
+
     out = S.jm([])
 
     Enum.each(H.entries(reqmatch), fn {key, val} ->
       if val != nil and is_binary(key) and key != "$action" and
            not Enum.member?(param_strs, key) do
-        S.setprop(out, key, val)
+        S.setprop(out, Map.get(wire, key, key), val)
       end
     end)
 

package/project/.sdk/tm/go/utility/prepare_query.go

@@ -17,7 +17,7 @@ func prepareQueryUtil(ctx *core.Context) map[string]any {
 	if point != nil {
 		if p := vs.GetProp(point, "params"); p != nil {
 			if pl, ok := p.([]any); ok {
-				params = pl
+				params = append([]any{}, pl...)
 			}
 		}
 	}
@@ -25,11 +25,41 @@ func prepareQueryUtil(ctx *core.Context) map[string]any {
 		params = []any{}
 	}
 
+	// 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 point != nil {
+		if pl, ok := vs.GetPath(point, []any{"args", "params"}).([]any); ok {
+			for _, pd := range pl {
+				if name, ok := vs.GetProp(pd, "name").(string); ok {
+					params = append(params, name)
+				}
+			}
+		}
+	}
+
+	// A query parameter travels under the name the definition gives it, its
+	// orig, which the model may have renamed for the caller.
+	wire := map[string]string{}
+	if point != nil {
+		if ql, ok := vs.GetPath(point, []any{"args", "query"}).([]any); ok {
+			for _, qd := range ql {
+				name, _ := vs.GetProp(qd, "name").(string)
+				orig, _ := vs.GetProp(qd, "orig").(string)
+				if "" != name && "" != orig {
+					wire[name] = orig
+				}
+			}
+		}
+	}
+
 	out := map[string]any{}
 	for _, item := range vs.Items(reqmatch) {
 		key, _ := item[0].(string)
 		val := item[1]
 		if val != nil && key != "$action" && !containsStr(params, key) {
+			if orig, ok := wire[key]; ok {
+				key = orig
+			}
 			out[key] = val
 		}
 	}

package/project/.sdk/tm/java/utility/PrepareQuery.java

@@ -20,15 +20,39 @@ final class PrepareQuery {
       reqmatch = new LinkedHashMap<>();
     }
 
-    List<Object> params = null;
+    List<Object> params = new ArrayList<>();
     if (point != null) {
       Object p = Struct.getprop(point, "params");
       if (p instanceof List) {
-        params = (List<Object>) p;
+        params.addAll((List<Object>) p);
+      }
+      // A path parameter travels in the path. The generated config lists them
+      // as args.params, which prepareParams reads; params is the older list.
+      Object pl = Struct.getpath(point, List.of("args", "params"));
+      if (pl instanceof List) {
+        for (Object pd : (List<Object>) pl) {
+          Object name = Struct.getprop(pd, "name");
+          if (name instanceof String) {
+            params.add(name);
+          }
+        }
       }
     }
-    if (params == null) {
-      params = new ArrayList<>();
+
+    // A query parameter travels under the name the definition gives it, its
+    // orig, which the model may have renamed for the caller.
+    Map<String, String> wire = new LinkedHashMap<>();
+    if (point != null) {
+      Object ql = Struct.getpath(point, List.of("args", "query"));
+      if (ql instanceof List) {
+        for (Object qd : (List<Object>) ql) {
+          Object name = Struct.getprop(qd, "name");
+          Object orig = Struct.getprop(qd, "orig");
+          if (name instanceof String && orig instanceof String && !((String) orig).isEmpty()) {
+            wire.put((String) name, (String) orig);
+          }
+        }
+      }
     }
 
     Map<String, Object> out = new LinkedHashMap<>();
@@ -36,7 +60,7 @@ final class PrepareQuery {
       String key = item.get(0) instanceof String ? (String) item.get(0) : "";
       Object val = item.get(1);
       if (val != null && !"$action".equals(key) && !containsStr(params, key)) {
-        out.put(key, val);
+        out.put(wire.getOrDefault(key, key), val);
       }
     }
 

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

@@ -11,10 +11,24 @@ function prepareQuery(ctx) {
   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 = params.concat(
+    ((point.args && point.args.params) || []).map((p) => p && 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 = Object.create(null)
+  for (const q of ((point.args && point.args.query) || [])) {
+    if (q && 'string' === typeof q.name && 'string' === typeof q.orig && '' !== q.orig) {
+      wire[q.name] = q.orig
+    }
+  }
+
   const out = {}
   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[null == wire[key] ? key : wire[key]] = val
     }
   }