@voxgig/sdkgen 0.44.0 → 1.0.1

package/project/.sdk/tm/py/test/runner.py

@@ -62,6 +62,54 @@ class ProjectNameTestRunner:
 
         return m
 
+    _test_control = None
+
+    @staticmethod
+    def load_test_control():
+        """Load sdk-test-control.json from this test dir; cache after first read.
+        Returns a dict with the empty-skip default if the file is missing or invalid
+        so tests never crash on a bad config.
+        """
+        if ProjectNameTestRunner._test_control is not None:
+            return ProjectNameTestRunner._test_control
+        ctrl_path = os.path.join(os.path.dirname(__file__), "sdk-test-control.json")
+        try:
+            with open(ctrl_path, "r") as f:
+                ProjectNameTestRunner._test_control = json.load(f)
+        except (FileNotFoundError, IOError, ValueError):
+            ProjectNameTestRunner._test_control = {
+                "version": 1,
+                "test": {"skip": {
+                    "live": {"direct": [], "entityOp": []},
+                    "unit": {"direct": [], "entityOp": []},
+                }},
+            }
+        return ProjectNameTestRunner._test_control
+
+    @staticmethod
+    def is_control_skipped(kind, name, mode):
+        """Check sdk-test-control.json for a skip entry. Returns (skip, reason)."""
+        ctrl = ProjectNameTestRunner.load_test_control()
+        skip = ctrl.get("test", {}).get("skip", {}).get(mode, {}) or {}
+        items = skip.get(kind, []) or []
+        for item in items:
+            if kind == "direct" and item.get("test") == name:
+                return True, item.get("reason")
+            if kind == "entityOp":
+                key = (item.get("entity") or "") + "." + (item.get("op") or "")
+                if key == name:
+                    return True, item.get("reason")
+        return False, None
+
+    @staticmethod
+    def live_delay_ms():
+        """Per-test live pacing delay (ms); default 500."""
+        ctrl = ProjectNameTestRunner.load_test_control()
+        v = ctrl.get("test", {}).get("live", {}).get("delayMs")
+        if isinstance(v, int) and v >= 0:
+            return v
+        return 500
+
     @staticmethod
     def entity_list_to_data(lst):
         out = []
@@ -88,3 +136,15 @@ def env_override(m):
 
 def entity_list_to_data(lst):
     return ProjectNameTestRunner.entity_list_to_data(lst)
+
+
+def is_control_skipped(kind, name, mode):
+    return ProjectNameTestRunner.is_control_skipped(kind, name, mode)
+
+
+def load_test_control():
+    return ProjectNameTestRunner.load_test_control()
+
+
+def live_delay_ms():
+    return ProjectNameTestRunner.live_delay_ms()

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

@@ -0,0 +1,19 @@
+{
+  "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 py test runner.",
+  "test": {
+    "skip": {
+      "live": {
+        "direct": [],
+        "entityOp": []
+      },
+      "unit": {
+        "direct": [],
+        "entityOp": []
+      }
+    },
+    "live": {
+      "delayMs": 500
+    }
+  }
+}

package/project/.sdk/tm/py/utility/fetcher.py

@@ -5,6 +5,14 @@ import json
 from utility.voxgig_struct import voxgig_struct as vs
 
 
+# Default User-Agent — many CDNs (notably Cloudflare) reject requests with
+# Python's default urllib UA ("Python-urllib/3.x"), returning 403 before
+# the request even reaches the origin. Set a Mozilla-shaped UA so the SDK
+# behaves like every other HTTP client by default. Users can still override
+# by passing a User-Agent header in fetchdef.
+_DEFAULT_USER_AGENT = "Mozilla/5.0 (compatible; ProjectNameSDK/1.0)"
+
+
 def _default_http_fetch(fullurl, fetchdef):
     import urllib.request
     import urllib.error
@@ -19,8 +27,13 @@ def _default_http_fetch(fullurl, fetchdef):
     data = body_str.encode("utf-8") if body_str is not None else None
 
     req = urllib.request.Request(fullurl, data=data, method=method)
+    has_ua = False
     for k, v in headers.items():
+        if k.lower() == "user-agent":
+            has_ua = True
         req.add_header(k, v)
+    if not has_ua:
+        req.add_header("User-Agent", _DEFAULT_USER_AGENT)
 
     try:
         resp = urllib.request.urlopen(req)

package/project/.sdk/tm/py/utility/make_url.py

@@ -29,6 +29,19 @@ def make_url_util(ctx):
                 url = url.replace("{" + key + "}", encoded)
                 resmatch[key] = val
 
+    # Append query string from spec.query.
+    qsep = "?"
+    query_items = vs.items(getattr(spec, "query", None))
+    if query_items is not None:
+        for item in query_items:
+            key = item[0]
+            val = item[1]
+            if val is not None and isinstance(key, str):
+                val_str = val if isinstance(val, str) else str(val)
+                url += qsep + vs.escurl(key) + "=" + vs.escurl(val_str)
+                qsep = "&"
+                resmatch[key] = val
+
     result.resmatch = resmatch
 
     return url, None

package/project/.sdk/tm/py/utility/prepare_auth.py

@@ -17,9 +17,18 @@ def prepare_auth_util(ctx):
     headers = spec.headers
     options = ctx.client.options_map()
 
+    # Public APIs that need no auth omit the options.auth block entirely.
+    if options.get("auth") is None:
+        headers.pop(HEADER_AUTH, None)
+        return spec, None
+
     apikey = vs.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
-    if isinstance(apikey, str) and apikey == NOT_FOUND:
+    if (
+        (isinstance(apikey, str) and apikey == NOT_FOUND)
+        or apikey is None
+        or apikey == ""
+    ):
         headers.pop(HEADER_AUTH, None)
     else:
         auth_prefix = ""

package/project/.sdk/tm/rb/feature/test_feature.rb

@@ -48,8 +48,22 @@ class ProjectNameTestFeature < ProjectNameBaseFeature
       entmap = VoxgigStruct.getprop(entity, op.entity)
       entmap = {} unless entmap.is_a?(Hash)
 
+      # For single-entity ops (load, remove) with an empty explicit match, fall
+      # back to the id the entity client already knows from a prior create/load
+      # (in fctx.match / fctx.data). Mirrors the TS mock where param() resolves
+      # the id from that accumulated state.
+      resolve_match = lambda do |explicit|
+        return explicit if explicit.is_a?(Hash) && !explicit.empty?
+        [fctx.match, fctx.data].each do |src|
+          next if src.nil?
+          v = VoxgigStruct.getprop(src, "id")
+          return { "id" => v } if !v.nil? && v != "__UNDEFINED__"
+        end
+        {}
+      end
+
       if op.name == "load"
-        args = test_self.build_args(fctx, op, fctx.reqmatch)
+        args = test_self.build_args(fctx, op, resolve_match.call(fctx.reqmatch))
         found = VoxgigStruct.select(entmap, args)
         ent = VoxgigStruct.getelem(found, 0)
         return respond.call(404, nil, { "statusText" => "Not found" }) unless ent
@@ -68,9 +82,28 @@ class ProjectNameTestFeature < ProjectNameBaseFeature
         respond.call(200, out, nil)
 
       elsif op.name == "update"
-        args = test_self.build_args(fctx, op, fctx.reqdata)
+        # Match the existing entity by id only (or its alias). reqdata also
+        # contains the new field values, which would otherwise cause select
+        # to filter out the entity we want to update. Falls back to first
+        # entity when no id present and no match found, mirroring the TS
+        # mock's empirical behavior where param(undef) collapses to "no
+        # constraint" and select returns all.
+        update_match = {}
+        if fctx.reqdata.is_a?(Hash)
+          update_match["id"] = fctx.reqdata["id"] if fctx.reqdata.key?("id")
+          if op.alias_map
+            alias_id = VoxgigStruct.getprop(op.alias_map, "id")
+            if alias_id && fctx.reqdata.key?(alias_id)
+              update_match[alias_id] = fctx.reqdata[alias_id]
+            end
+          end
+        end
+        args = test_self.build_args(fctx, op, update_match)
         found = VoxgigStruct.select(entmap, args)
         ent = VoxgigStruct.getelem(found, 0)
+        if ent.nil? && entmap.is_a?(Hash) && !entmap.empty?
+          ent = entmap.values.find { |e| e.is_a?(Hash) }
+        end
         return respond.call(404, nil, { "statusText" => "Not found" }) unless ent
         if ent.is_a?(Hash) && fctx.reqdata
           fctx.reqdata.each { |k, v| ent[k] = v }
@@ -80,7 +113,7 @@ class ProjectNameTestFeature < ProjectNameBaseFeature
         respond.call(200, out, nil)
 
       elsif op.name == "remove"
-        args = test_self.build_args(fctx, op, fctx.reqmatch)
+        args = test_self.build_args(fctx, op, resolve_match.call(fctx.reqmatch))
         found = VoxgigStruct.select(entmap, args)
         ent = VoxgigStruct.getelem(found, 0)
         return respond.call(404, nil, { "statusText" => "Not found" }) unless ent

package/project/.sdk/tm/rb/test/runner.rb

@@ -62,6 +62,52 @@ module ProjectNameTestRunner
     end
     out
   end
+
+  @test_control = nil
+
+  # Load sdk-test-control.json from this test dir; cache. Returns the
+  # empty-skip default if the file is missing or invalid.
+  def self.load_test_control
+    return @test_control unless @test_control.nil?
+    ctrl_path = File.join(File.dirname(__FILE__), 'sdk-test-control.json')
+    @test_control = begin
+      JSON.parse(File.read(ctrl_path))
+    rescue StandardError
+      {
+        'version' => 1,
+        'test' => { 'skip' => {
+          'live' => { 'direct' => [], 'entityOp' => [] },
+          'unit' => { 'direct' => [], 'entityOp' => [] },
+        }},
+      }
+    end
+    @test_control
+  end
+
+  # Check sdk-test-control.json for a skip entry. Returns [skip, reason].
+  def self.is_control_skipped(kind, name, mode)
+    ctrl = load_test_control
+    skip = (ctrl.dig('test', 'skip', mode) || {})
+    items = skip[kind] || []
+    items.each do |item|
+      if kind == 'direct' && item['test'] == name
+        return [true, item['reason']]
+      end
+      if kind == 'entityOp'
+        key = "#{item['entity']}.#{item['op']}"
+        return [true, item['reason']] if key == name
+      end
+    end
+    [false, nil]
+  end
+
+  # Per-test live pacing delay (ms); default 500.
+  def self.live_delay_ms
+    ctrl = load_test_control
+    v = ctrl.dig('test', 'live', 'delayMs')
+    return v if v.is_a?(Integer) && v >= 0
+    500
+  end
 end
 
 # Module-level aliases for test convenience.

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

@@ -0,0 +1,19 @@
+{
+  "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 rb test runner.",
+  "test": {
+    "skip": {
+      "live": {
+        "direct": [],
+        "entityOp": []
+      },
+      "unit": {
+        "direct": [],
+        "entityOp": []
+      }
+    },
+    "live": {
+      "delayMs": 500
+    }
+  }
+}

package/project/.sdk/tm/rb/utility/fetcher.rb

@@ -10,39 +10,60 @@ module ProjectNameUtilities
     body_str = fetchdef["body"]
     headers = fetchdef["headers"] || {}
 
-    uri = URI.parse(fullurl)
-    http = Net::HTTP.new(uri.host, uri.port)
-    http.use_ssl = (uri.scheme == "https")
+    begin
+      uri = URI.parse(fullurl)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
 
-    klass = case method_str.upcase
-            when "POST" then Net::HTTP::Post
-            when "PUT" then Net::HTTP::Put
-            when "DELETE" then Net::HTTP::Delete
-            when "PATCH" then Net::HTTP::Patch
-            else Net::HTTP::Get
-            end
+      klass = case method_str.upcase
+              when "POST" then Net::HTTP::Post
+              when "PUT" then Net::HTTP::Put
+              when "DELETE" then Net::HTTP::Delete
+              when "PATCH" then Net::HTTP::Patch
+              else Net::HTTP::Get
+              end
 
-    request = klass.new(uri)
-    headers.each { |k, v| request[k] = v.to_s if v.is_a?(String) }
-    request.body = body_str if body_str.is_a?(String)
+      request = klass.new(uri)
+      has_ua = false
+      headers.each do |k, v|
+        next unless v.is_a?(String)
+        has_ua = true if k.to_s.downcase == 'user-agent'
+        request[k] = v.to_s
+      end
+      # Default User-Agent — Net::HTTP sets "Ruby" which some CDNs block.
+      # Use a Mozilla-shaped UA unless the caller already set one.
+      request['User-Agent'] = 'Mozilla/5.0 (compatible; ProjectNameSDK/1.0)' unless has_ua
+      request.body = body_str if body_str.is_a?(String)
 
-    resp = http.request(request)
-    resp_headers = {}
-    resp.each_header { |k, v| resp_headers[k.downcase] = v }
+      resp = http.request(request)
+      resp_headers = {}
+      resp.each_header { |k, v| resp_headers[k.downcase] = v }
 
-    json_body = nil
-    begin
-      json_body = JSON.parse(resp.body) if resp.body && !resp.body.empty?
-    rescue JSON::ParserError
-    end
+      json_body = nil
+      begin
+        json_body = JSON.parse(resp.body) if resp.body && !resp.body.empty?
+      rescue JSON::ParserError
+      end
 
-    return {
-      "status" => resp.code.to_i,
-      "statusText" => resp.message,
-      "headers" => resp_headers,
-      "json" => -> { json_body },
-      "body" => resp.body,
-    }, nil
+      return {
+        "status" => resp.code.to_i,
+        "statusText" => resp.message,
+        "headers" => resp_headers,
+        "json" => -> { json_body },
+        "body" => resp.body,
+      }, nil
+    rescue StandardError => e
+      # Network-level failures (DNS, TCP, TLS, timeouts) — return a synthesized
+      # response with status 0 so callers can branch on result.ok like any
+      # other failed request, instead of seeing an unhandled exception.
+      return {
+        "status" => 0,
+        "statusText" => "#{e.class}: #{e.message}",
+        "headers" => {},
+        "json" => -> { nil },
+        "body" => nil,
+      }, nil
+    end
   }
 
   Fetcher = ->(ctx, fullurl, fetchdef) {

package/project/.sdk/tm/rb/utility/make_url.rb

@@ -26,6 +26,22 @@ module ProjectNameUtilities
       end
     end
 
+    # Append query string from spec.query.
+    qsep = "?"
+    query_items = VoxgigStruct.items(spec.respond_to?(:query) ? spec.query : nil)
+    if query_items
+      query_items.each do |item|
+        key = item[0]
+        val = item[1]
+        if val && key.is_a?(String)
+          val_str = val.is_a?(String) ? val : val.to_s
+          url += qsep + VoxgigStruct.escurl(key) + "=" + VoxgigStruct.escurl(val_str)
+          qsep = "&"
+          resmatch[key] = val
+        end
+      end
+    end
+
     result.resmatch = resmatch
     return url, nil
   }

package/project/.sdk/tm/rb/utility/prepare_auth.rb

@@ -11,9 +11,16 @@ module ProjectNameUtilities
 
     headers = spec.headers
     options = ctx.client.options_map
+
+    # Public APIs that need no auth omit the options.auth block entirely.
+    if options["auth"].nil?
+      headers.delete(HEADER_AUTH)
+      return spec, nil
+    end
+
     apikey = VoxgigStruct.getprop(options, OPTION_APIKEY, NOT_FOUND)
 
-    if apikey.is_a?(String) && apikey == NOT_FOUND
+    if apikey.nil? || (apikey.is_a?(String) && (apikey == NOT_FOUND || apikey == ""))
       headers.delete(HEADER_AUTH)
     else
       auth_prefix = VoxgigStruct.getpath(options, "auth.prefix") || ""

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

@@ -37,18 +37,17 @@ function makeUrl(ctx: Context): Error | string {
   }
 
 
-  /* TODO: fix
+  // Append query string from spec.query. Entity ops populate this via
+  // PrepareQueryUtility from the operation's reqmatch; direct() callers
+  // pass it as fetchargs.query.
   let qsep = '?'
   for (let [key, val] of items(spec.query)) {
-    if (null == spec.alias[key]) {
-      if (null != val) {
-        url += qsep + escurl(key) + '=' + escurl(val)
-        qsep = '&'
-        resmatch[key] = val
-      }
+    if (null != val) {
+      url += qsep + escurl(key) + '=' + escurl(val)
+      qsep = '&'
+      resmatch[key] = val
     }
   }
-  */
 
   result.resmatch = resmatch
 

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

@@ -30,9 +30,15 @@ function prepareAuth(ctx: Context): Spec | Error {
 
   const options = client.options()
 
+  // Public APIs that need no auth omit the options.auth block entirely.
+  if (null == options.auth) {
+    delprop(headers, HEADER_auth)
+    return spec
+  }
+
   const apikey = getprop(options, OPTION_apikey, NOTFOUND)
 
-  if (NOTFOUND === apikey) {
+  if (NOTFOUND === apikey || null == apikey || '' === apikey) {
     delprop(headers, HEADER_auth)
   }
   else {

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

@@ -0,0 +1,19 @@
+{
+  "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.",
+  "test": {
+    "skip": {
+      "live": {
+        "direct": [],
+        "entityOp": []
+      },
+      "unit": {
+        "direct": [],
+        "entityOp": []
+      }
+    },
+    "live": {
+      "delayMs": 500
+    }
+  }
+}

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

@@ -1,10 +1,14 @@
 /**
  * Shared utility functions for unit tests
- * 
+ *
  * This module provides common helper functions used across unit tests
  * for creating test data, transformations, validations, and environment overrides.
  */
 
+import * as Fs from 'node:fs'
+import * as Path from 'node:path'
+
+
 // Creates a new step data structure within the data model
 function makeStepData(dm: Record<string, any>, stepname: string): Record<string, any> {
   dm.s[stepname] = {
@@ -76,11 +80,125 @@ function envOverride(m: Record<string, any>) {
 }
 
 
+// Loads sdk-test-control.json (cached). Returns an empty-skip object if
+// the file is missing or unparsable so tests never crash on a bad config.
+type TestControl = {
+  version?: number
+  test?: {
+    skip?: {
+      live?: { direct?: any[], entityOp?: any[] }
+      unit?: { direct?: any[], entityOp?: any[] }
+    }
+    live?: { delayMs?: number }
+    [k: string]: any
+  }
+  [k: string]: any
+}
+
+let _testControlCache: TestControl | null = null
+
+function loadTestControl(): TestControl {
+  if (_testControlCache) return _testControlCache
+  const ctrlPath = Path.resolve(__dirname, '../test/sdk-test-control.json')
+  try {
+    _testControlCache = JSON.parse(Fs.readFileSync(ctrlPath, 'utf8')) as TestControl
+  }
+  catch {
+    _testControlCache = {
+      version: 1,
+      test: { skip: { live: { direct: [], entityOp: [] }, unit: { direct: [], entityOp: [] } } }
+    }
+  }
+  return _testControlCache!
+}
+
+
+// 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'.
+function isControlSkipped(
+  kind: 'direct' | 'entityOp',
+  name: string,
+  mode: 'live' | 'unit'
+): { skip: boolean, reason?: string } {
+  const ctrl = loadTestControl()
+  const list = ctrl?.test?.skip?.[mode]?.[kind] ?? []
+  for (const e of list) {
+    if (kind === 'direct' && e?.test === name) {
+      return { skip: true, reason: e.reason }
+    }
+    if (kind === 'entityOp') {
+      const key = (e?.entity ?? '') + '.' + (e?.op ?? '')
+      if (key === name) return { skip: true, reason: e.reason }
+    }
+  }
+  return { skip: false }
+}
+
+
+// Skips the current test if sdk-test-control.json lists it. Returns true
+// when skipped (caller should `return` immediately).
+function maybeSkipControl(
+  t: any,
+  kind: 'direct' | 'entityOp',
+  name: string,
+  live: boolean
+): boolean {
+  const decision = isControlSkipped(kind, name, live ? 'live' : 'unit')
+  if (decision.skip) {
+    t.skip(decision.reason || 'skipped via sdk-test-control.json')
+    return true
+  }
+  return false
+}
+
+
+// Skips the current live test when required idmap keys aren't supplied.
+// Generated tests call this when they would otherwise pass `undefined`
+// values into a path/query param and 4xx the request.
+function skipIfMissingIds(t: any, setup: any, requiredKeys: string[]): boolean {
+  if (!setup.live) return false
+  const missing = requiredKeys.filter(k => null == setup.idmap?.[k])
+  if (missing.length > 0) {
+    t.skip(`live test needs ${missing.join(', ')} via *_ENTID env var (synthetic IDs only)`)
+    return true
+  }
+  return false
+}
+
+
+// Per-test live pacing delay (ms). Read from sdk-test-control.json
+// `test.live.delayMs`; defaults to 500ms if absent or invalid.
+function liveDelayMs(): number {
+  const ctrl = loadTestControl()
+  const v = ctrl?.test?.live?.delayMs
+  return ('number' === typeof v && v >= 0) ? v : 500
+}
+
+
+// afterEach hook helper for live pacing. Generated tests register this
+// via `afterEach(liveDelay(<envVar>))`; it sleeps `liveDelayMs()` only
+// when the SDK's *_TEST_LIVE env var is set.
+function liveDelay(liveEnvVar: string): () => Promise<void> {
+  return async () => {
+    if ('TRUE' === process.env[liveEnvVar]) {
+      await new Promise(r => setTimeout(r, liveDelayMs()))
+    }
+  }
+}
+
+
 export {
   makeStepData,
   makeMatch,
   makeReqdata,
   makeValid,
   makeCtrl,
-  envOverride
+  envOverride,
+  loadTestControl,
+  isControlSkipped,
+  maybeSkipControl,
+  skipIfMissingIds,
+  liveDelayMs,
+  liveDelay,
 }