@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/tm/perl/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) $$const.year$$ Voxgig
+Copyright (c) $$const.year$$ PROJECTPUBLISHER
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/project/.sdk/tm/perl/core/context.pm

@@ -113,7 +113,7 @@ sub resolve_op {
 
   my $opcfg = ProjectNameHelpers::gpath($self->{config}, "entity.$entname.op.$opname");
 
-  my $input = ($opname eq 'update' || $opname eq 'create') ? 'data' : 'match';
+  my $input = ($opname eq 'update' || $opname eq 'create' || $opname eq 'patch') ? 'data' : 'match';
 
   my $points = [];
   if (Voxgig::Struct::ismap($opcfg)) {

package/project/.sdk/tm/perl/core/response.pm

@@ -34,6 +34,8 @@ sub new {
     json_func   => $json_func,
     body        => ProjectNameHelpers::gp($resmap, 'body'),
     err         => ProjectNameHelpers::gp($resmap, 'err'),
+    # Set by a transport that could not read a non-blank body as JSON.
+    unreadable  => (ProjectNameHelpers::gp($resmap, 'unreadable') ? 1 : 0),
   }, $class;
 }
 

package/project/.sdk/tm/perl/core/spec.pm

@@ -27,6 +27,9 @@ sub new {
     body    => $specmap->{body},
     url     => $g->('url', ''),
     path    => $g->('path', ''),
+    # The query parameters prepare_auth placed: the credential, which the
+    # request sends and the entity's match leaves out.
+    authquery => $g->('authquery', []),
   }, $class;
 }
 

package/project/.sdk/tm/perl/feature/test_feature.pm

@@ -15,6 +15,17 @@ require(Cwd::abs_path("$__dir/base_feature.pm"));
 
 package ProjectNameTestFeature;
 
+# The key a list's response transform
+# ["`$EACH`", "body", { "`$MERGE`" => "`.<key>`" }] reads each item's record under.
+sub item_envelope_key {
+  my ($spec) = @_;
+  return undef unless ref($spec) eq 'ARRAY' && 3 == @$spec &&
+    '`$EACH`' eq ($spec->[0] // '') && 'body' eq ($spec->[1] // '') && ref($spec->[2]) eq 'HASH';
+  my $merge = $spec->[2]{'`$MERGE`'};
+  return undef unless defined $merge && !ref($merge) && $merge =~ /^`\.([^.`\$]+)`$/;
+  return $1;
+}
+
 our @ISA = ('ProjectNameBaseFeature');
 
 sub new {
@@ -65,6 +76,8 @@ sub init {
     return $data unless defined $fctx && defined $fctx->{point};
     my $tm = ProjectNameHelpers::gp($fctx->{point}, 'transform');
     my $spec = ProjectNameHelpers::gp($tm, 'res');
+    my $key = item_envelope_key($spec);
+    return [ map { +{ $key => $_ } } @$data ] if defined $key && ref($data) eq 'ARRAY';
     return $data unless defined $spec && !ref($spec);
     # Rebuild whatever nesting the transform unwraps. Multi-segment on purpose:
     # GraphQL ops unwrap `body.data.<field>`, not just one envelope property.
@@ -133,7 +146,7 @@ sub init {
       my $out = Voxgig::Struct::clone($found);
       return $respond->($fctx, 200, $out, undef);
     }
-    elsif ('update' eq $op->{name}) {
+    elsif ('update' eq $op->{name} || 'patch' eq $op->{name}) {
       # 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. When reqdata has no id,
@@ -158,7 +171,7 @@ sub init {
       return $respond->($fctx, 404, undef, { 'statusText' => 'Not found' })
         unless ProjectNameHelpers::rb_truthy($ent);
       if (Voxgig::Struct::ismap($ent) && Voxgig::Struct::ismap($fctx->{reqdata})) {
-        Voxgig::Struct::merge([$ent, $fctx->{reqdata}]);
+        Voxgig::Struct::merge([$ent, _record($fctx->{reqdata})]);
       }
       Voxgig::Struct::delprop($ent, '$KEY');
       my $out = Voxgig::Struct::clone($ent);
@@ -183,7 +196,7 @@ sub init {
         int(rand(0x10000)), int(rand(0x10000)),
         int(rand(0x10000)), int(rand(0x10000))) unless defined $id;
 
-      my $ent = Voxgig::Struct::clone($fctx->{reqdata});
+      my $ent = Voxgig::Struct::clone(_record($fctx->{reqdata}));
       if (Voxgig::Struct::ismap($ent)) {
         $ent->{id} = $id;
         $entmap->{"$id"} = $ent if defined $id && !ref $id;
@@ -214,6 +227,16 @@ sub init {
 # {min,max}), a budget of first-N failures ("failTimes" -> "failStatus"),
 # first-N connection errors ("errorTimes"), or a hard "offline" outage.
 # Counter-driven, so simulations are deterministic across a test.
+# The record the mock keeps: the request data without `$body`, which only the
+# wire carries.
+sub _record {
+  my ($reqdata) = @_;
+  return $reqdata unless ref $reqdata eq 'HASH';
+  my %out = %$reqdata;
+  delete $out{'$body'};
+  return \%out;
+}
+
 sub make_netsim {
   my ($self, $net, $inner) = @_;
   $self->{netcalls} = 0;

package/project/.sdk/tm/perl/feature/validate_feature.pm

@@ -206,6 +206,8 @@ sub _payload {
   # fields will never name it - and under `strict` every custom-action call
   # would be rejected for the one key that made it reachable.
   delete $out{'$action'};
+  # Nor is `$body`, the raw request body.
+  delete $out{'$body'};
 
   return \%out;
 }

package/project/.sdk/tm/perl/t/feature.t

@@ -30,7 +30,7 @@ sub has_feature {
 sub default_method {
   my ($opname) = @_;
   return 'POST' if 'create' eq $opname;
-  return 'PATCH' if 'update' eq $opname;
+  return 'PATCH' if 'update' eq $opname || 'patch' eq $opname;
   return 'DELETE' if 'remove' eq $opname;
   return 'GET';
 }

package/project/.sdk/tm/perl/t/feature_corpus.t

@@ -35,7 +35,7 @@ unless (defined $TEST_JSON && -e $TEST_JSON) {
 # without a listed feature still skips, not fails.
 
 # The standard operation names, in the order the runner prefers them.
-my @FEATURE_CORPUS_OPS = qw(load list create update remove);
+my @FEATURE_CORPUS_OPS = qw(load list create update patch remove);
 
 my $CORPUS = do {
   open my $fh, '<', $TEST_JSON or die "cannot read $TEST_JSON: $!";
@@ -101,10 +101,14 @@ sub scripted_fetcher {
 #
 # The plain constructor, not the test-mode one: the `test` feature is
 # transport: 'base' and REPLACES the transport, so a client in test mode
-# would shadow the script.
+# would shadow the script. The `test` OPTION installs no transport: it says
+# the client is not live, so a required server variable becomes test-<name>.
 sub build_client {
   my ($kase) = @_;
-  my $opts = { 'utility' => { 'fetcher' => scripted_fetcher($kase->{res}) } };
+  my $opts = {
+    'test' => { 'active' => 1 },
+    'utility' => { 'fetcher' => scripted_fetcher($kase->{res}) },
+  };
   $opts->{feature} = $kase->{feature} if defined $kase->{feature};
   return ProjectNameSDK->new($opts);
 }
@@ -281,6 +285,23 @@ sub record {
   return $client->{"_$name"};
 }
 
+# The first feature a case composes that this SDK does not generate, probed
+# as a section's own feature is. Such a case is skipped rather than failed.
+sub missing_feature {
+  my ($kase, $have) = @_;
+  my $spec = $kase->{feature};
+  my @names = ref $spec eq 'ARRAY' ? map { ref $_ eq 'HASH' ? $_->{name} : undef } @$spec
+    : ref $spec eq 'HASH' ? sort keys %$spec
+    : ();
+  for my $name (@names) {
+    next unless defined $name && !ref $name;
+    $have->{$name} //=
+      present(build_client({ feature => [ { name => $name, active => 1 } ] }), $name) ? 1 : 0;
+    return $name unless $have->{$name};
+  }
+  return undef;
+}
+
 
 my @ops = usable_ops(2);
 
@@ -292,6 +313,8 @@ ok(scalar(@ops) > 0,
   exit 0;
 };
 
+my %have;
+
 for my $name (sort keys %{ $CORPUS->{feature} || {} }) {
   my $section = ($CORPUS->{feature} || {})->{$name};
   next unless defined $section;
@@ -315,53 +338,69 @@ for my $name (sort keys %{ $CORPUS->{feature} || {} }) {
   my $ran = 0;
   for my $raw (@$cases) {
     my $need = tokens_used($raw);
-    next if $need > scalar(@ops);
+    if ($need > scalar(@ops)) {
+      diag(sprintf('skip "%s": needs %d operations, this SDK offers %d',
+        $raw->{name} // '', $need, scalar(@ops)));
+      next;
+    }
+
+    my $missing = missing_feature($raw, \%have);
+    if (defined $missing) {
+      diag(sprintf('skip "%s": needs the %s feature, which this SDK does not generate',
+        $raw->{name} // '', $missing));
+      next;
+    }
 
     my %tokens;
     for my $i (0 .. $need - 1) {
       $tokens{ '#OP' . ($i + 1) } = $ops[$i]{key};
     }
     my $kase = resolve($raw, \%tokens);
-
-    my $client = build_client($kase);
     my $label = $kase->{name} || '';
+    $ran++;
 
-    for my $step (@{ $kase->{op} || [] }) {
-      my $op = $by_key{ $step->{op} };
-      ok(defined $op, "$label: operation $step->{op} is known") or next;
-      my $ctrl = $step->{ctrl} || {};
-      my $wanterr = $step->{err};
-
-      my $ok = eval { invoke($client, $op, $ctrl); 1 };
-      my $err = $@;
-
-      if (!defined $wanterr) {
-        ok($ok, "$label: $step->{op} succeeded")
-          or diag("failed unexpectedly: $err");
-        next;
+    # Every failing case is reported, not only the first.
+    my $done = eval {
+      my $client = build_client($kase);
+
+      for my $step (@{ $kase->{op} || [] }) {
+        my $op = $by_key{ $step->{op} };
+        ok(defined $op, "$label: operation $step->{op} is known") or next;
+        my $ctrl = $step->{ctrl} || {};
+        my $wanterr = $step->{err};
+
+        my $ok = eval { invoke($client, $op, $ctrl); 1 };
+        my $err = $@;
+
+        if (!defined $wanterr) {
+          ok($ok, "$label: $step->{op} succeeded")
+            or diag("failed unexpectedly: $err");
+          next;
+        }
+
+        ok(!$ok, "$label: $step->{op} failed as expected") or next;
+
+        if (!ref $wanterr) {
+          # The CODE, not the message: make_error prefixes and humanises the
+          # text, so matching it would pass on any error mentioning the word.
+          my $code = (Scalar::Util::blessed($err) && $err->can('code'))
+            ? $err->code : undef;
+          is($code, $wanterr, "$label: error code");
+        }
       }
 
-      ok(!$ok, "$label: $step->{op} failed as expected") or next;
-
-      if (!ref $wanterr) {
-        # The CODE, not the message: make_error prefixes and humanises the
-        # text, so matching it would pass on any error mentioning the word.
-        my $code = (Scalar::Util::blessed($err) && $err->can('code'))
-          ? $err->code : undef;
-        is($code, $wanterr, "$label: error code");
-      }
-    }
-
-    subset(record($client, $name), $kase->{out}, "$label: _$name");
-    $ran++;
+      subset(record($client, $name), $kase->{out}, "$label: _$name");
+      1;
+    };
+    fail("$label: $@") unless $done;
   }
 
-  ok($ran > 0, "at least one feature.$name case ran");
   # Say how many ran. A partial run is legitimate (an SDK with one operation
   # skips the cases needing two) but it should be visible rather than
   # inferred from a green tick.
   diag(sprintf('feature.%s: ran %d of %d case(s) against %d operation(s)',
     $name, $ran, scalar(@$cases), scalar(@ops)));
+  ok($ran > 0, "at least one feature.$name case ran");
 }
 
 done_testing();

package/project/.sdk/tm/perl/t/runner.pm

@@ -167,4 +167,90 @@ sub live_delay_ms {
   return 500;
 }
 
+# A live check that did not pass, as main.kit.test.live.strict decides:
+# strict fails the test, lenient skips it with the same reason. The caller
+# leaves its block after either.
+sub live_miss {
+  my ($strict, $name, $reason) = @_;
+  if ($strict) {
+    Test::More::fail("$name: $reason");
+  }
+  else {
+    Test::More->builder->skip("$name: $reason");
+  }
+  return;
+}
+
+# An account holding no record for the test to read skips either way.
+sub live_empty {
+  my ($name, $reason) = @_;
+  Test::More->builder->skip("$name: $reason");
+  return;
+}
+
+# A live list response's records: the body, or the first list an envelope
+# holds.
+sub live_list {
+  my ($data) = @_;
+  return $data if ref $data eq 'ARRAY';
+  if (ref $data eq 'HASH') {
+    for my $k (sort keys %$data) {
+      return $data->{$k} if ref $data->{$k} eq 'ARRAY';
+    }
+  }
+  return undef;
+}
+
+# A live response for a message: the SDK's error, or else its status and
+# content type, never its body.
+sub live_describe {
+  my ($result) = @_;
+  return 'no response' unless ref $result eq 'HASH';
+  return '' . $result->{err} if defined $result->{err};
+  my $ctype;
+  for my $k (keys %{ $result->{headers} || {} }) {
+    $ctype = $result->{headers}{$k} if lc($k) eq 'content-type';
+  }
+  my $out = 'HTTP ' . ($result->{status} // 'none');
+  if (defined $ctype) {
+    my ($media) = split /;/, $ctype;
+    $media =~ s/^\s+|\s+$//g;
+    $out .= " $media";
+  }
+  return $out;
+}
+
+# The record a create-less flow reads live: the first its list returns, put
+# where the flow reads the fixture's existing records. False once the test
+# is settled and its block ends.
+sub live_existing {
+  my ($setup, $strict, $label, $name, $list) = @_;
+  my $found = eval { $list->() };
+  if (my $err = $@) {
+    live_miss($strict, $label, "Live list discovery failed: $err");
+    return 0;
+  }
+  if (ref $found ne 'ARRAY') {
+    live_miss($strict, $label, 'Live list discovery returned no list');
+    return 0;
+  }
+  if (!@$found) {
+    live_empty($label, "The account has no $name record to load");
+    return 0;
+  }
+  my $first = $found->[0];
+  my $record = (Scalar::Util::blessed($first) && $first->can('data_get'))
+    ? $first->data_get : $first;
+  $setup->{data}{existing}{$name} = { 'live01' => $record };
+  return 1;
+}
+
+# In a lenient live run a step that dies skips, observing the live API.
+sub live_observe {
+  my ($err, $setup, $strict, $label) = @_;
+  die $err if $strict || !$setup->{live};
+  Test::More->builder->skip("$label: live run, main.kit.test.live.strict is false: $err");
+  return;
+}
+
 1;

package/project/.sdk/tm/perl/t/server_variables.t

@@ -0,0 +1,39 @@
+#!perl
+# ProjectName SDK server variables
+#
+# A templated base URL takes each {name} from the `server` option. A missing
+# or empty value fails construction; test mode fills in test-<name>.
+
+use strict;
+use warnings;
+use Test::More;
+use FindBin;
+use lib "$FindBin::Bin/../lib";
+
+use ProjectNameSDK;
+
+# A variable no API declares, so the API's own server defaults cannot fill it.
+my $base = 'https://api.example.test/bot{zzvar}';
+
+for my $server ({}, { 'zzvar' => '' }) {
+  my $client = eval { ProjectNameSDK->new({ 'base' => $base, 'server' => $server }) };
+  my $err = $@;
+  ok(!defined $client, 'construction fails without a value for zzvar');
+  is(ref $err ? $err->{code} : '', 'server_var_required', 'the error carries its code');
+  like("$err", qr/the server variable 'zzvar' is required/, 'the error names the variable');
+  like("$err", qr/\Q$base\E/, 'the error quotes the base URL');
+}
+
+my $filled = ProjectNameSDK->new({ 'base' => $base, 'server' => { 'zzvar' => 'T1' } });
+is($filled->options_map()->{base}, 'https://api.example.test/botT1',
+  'a server value fills the base');
+
+my $testmode = ProjectNameSDK->new({ 'base' => $base, 'test' => { 'active' => 1 } });
+is($testmode->options_map()->{base}, 'https://api.example.test/bottest-zzvar',
+  'the test option fills test-<name>');
+
+my $mock = ProjectNameSDK->test(undef, { 'base' => $base });
+is($mock->options_map()->{base}, 'https://api.example.test/bottest-zzvar',
+  'the test feature fills test-<name>');
+
+done_testing();

package/project/.sdk/tm/perl/utility/clean.pm

@@ -314,25 +314,30 @@ sub add_sensitive {
 
 # A feature's name is not a field name: only the sensitive names inside its
 # settings count, so `secrets` does not make every setting a secret. Entity
-# blocks (per-entity settings, seeded records) hold no credential.
+# blocks (per-entity settings, seeded records) hold no credential, and nor do
+# rbac's rules, keyed by entity and operation names.
 sub add_options {
   my ($ctx, $opts) = @_;
   my %scan = %$opts;
   my $feature = delete $scan{feature};
   delete $scan{entity};
-  $scan{test} = no_entity($scan{test}) if exists $scan{test};
+  $scan{test} = plain_settings($scan{test}) if exists $scan{test};
   add_sensitive($ctx, \%scan);
-  my @blocks = Voxgig::Struct::ismap($feature) ? values %$feature
-    : Voxgig::Struct::islist($feature) ? @$feature : ($feature);
-  add_sensitive($ctx, no_entity($_)) for @blocks;
+  my @blocks = Voxgig::Struct::ismap($feature)
+    ? map { [$_, $feature->{$_}] } sort keys %$feature
+    : Voxgig::Struct::islist($feature)
+    ? map { [Voxgig::Struct::ismap($_) ? $_->{name} : undef, $_] } @$feature
+    : ([undef, $feature]);
+  add_sensitive($ctx, plain_settings($_->[1], $_->[0])) for @blocks;
   return;
 }
 
-sub no_entity {
-  my ($block) = @_;
+sub plain_settings {
+  my ($block, $name) = @_;
   return $block unless Voxgig::Struct::ismap($block);
   my %copy = %$block;
   delete $copy{entity};
+  delete $copy{rules} if defined $name && 'rbac' eq $name;
   return \%copy;
 }
 

package/project/.sdk/tm/perl/utility/fetcher.pm

@@ -6,6 +6,7 @@ use warnings;
 use File::Basename ();
 use Cwd ();
 use HTTP::Tiny ();
+use Scalar::Util ();
 
 my $__dir;
 BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
@@ -43,11 +44,26 @@ our $DefaultHttpFetch = sub {
     $hdrs{$k} = "$v";
   }
   # Default User-Agent - some CDNs block library defaults. Use a
-  # Mozilla-shaped UA unless the caller already set one.
-  $hdrs{'User-Agent'} = 'Mozilla/5.0 (compatible; ProjectNameSDK/1.0)' unless $has_ua;
+  # Mozilla-shaped UA unless the caller already set one, and record it with
+  # the headers the request sent.
+  unless ($has_ua) {
+    $hdrs{'User-Agent'} = 'Mozilla/5.0 (compatible; ProjectNameSDK/1.0)';
+    $headers->{'user-agent'} = $hdrs{'User-Agent'};
+  }
 
+  # HTTP::Tiny sends bytes: a character string goes out as UTF-8, and a
+  # filehandle is read.
+  if (ref $body eq 'GLOB' || (Scalar::Util::blessed($body) && $body->can('read'))) {
+    local $/;
+    my $fh = $body;
+    $body = <$fh>;
+  }
   my $opts = { headers => \%hdrs };
-  $opts->{content} = "$body" if defined $body && !ref $body;
+  if (defined $body && !ref $body) {
+    my $content = "$body";
+    utf8::encode($content) if utf8::is_utf8($content);
+    $opts->{content} = $content;
+  }
 
   # fetchdef.redirect 'manual' (the ts fetch vocabulary): return a 3xx
   # as-is instead of following it. HTTP::Tiny follows redirects by
@@ -62,27 +78,21 @@ our $DefaultHttpFetch = sub {
     if defined $fetchdef->{proxy} && !ref $fetchdef->{proxy}
       && length $fetchdef->{proxy};
 
+  # A request that got no answer fails the operation.
   my $res = eval { _http_client(%new_args)->request($method, $fullurl, $opts) };
   if (!$res) {
-    my $e = defined $@ ? "$@" : 'request failed';
+    my $e = (defined $@ && length $@) ? "$@" : 'request failed';
     $e =~ s/\s+\z//;
-    return ({
-      'status' => 0, 'statusText' => $e, 'headers' => {},
-      'json' => sub { undef }, 'body' => undef,
-    }, undef);
+    return (undef, $e);
   }
 
-  # Network-level failures (DNS, TCP, TLS, timeouts) - HTTP::Tiny signals
-  # these with a synthesized 599 + the error text as content. Return a
-  # status-0 response so callers can branch on result.ok like any other
-  # failed request, instead of seeing an unhandled exception.
+  # HTTP::Tiny reports a network failure (DNS, TCP, TLS, a timeout) as a
+  # synthesized 599 carrying the error text.
   if (599 == ($res->{status} || 0) && !$res->{success}) {
-    my $reason = defined $res->{content} ? "$res->{content}" : 'network error';
+    my $reason = (defined $res->{content} && length $res->{content})
+      ? "$res->{content}" : 'network error';
     $reason =~ s/\s+\z//;
-    return ({
-      'status' => 0, 'statusText' => $reason, 'headers' => {},
-      'json' => sub { undef }, 'body' => undef,
-    }, undef);
+    return (undef, $reason);
   }
 
   my $resp_headers = {};
@@ -94,8 +104,10 @@ our $DefaultHttpFetch = sub {
   }
 
   my $json_body;
-  if (defined $res->{content} && length $res->{content}) {
-    $json_body = eval { Voxgig::Struct::parse_json($res->{content}) };
+  my $unreadable = 0;
+  if (defined $res->{content} && $res->{content} =~ /\S/) {
+    my $parsed = eval { $json_body = Voxgig::Struct::parse_json($res->{content}); 1 };
+    $unreadable = 1 unless $parsed;
   }
   my $captured = $json_body;
 
@@ -105,6 +117,7 @@ our $DefaultHttpFetch = sub {
     'headers' => $resp_headers,
     'json' => sub { $captured },
     'body' => $res->{content},
+    'unreadable' => $unreadable,
   }, undef);
 };
 

package/project/.sdk/tm/perl/utility/make_fetch_def.pm

@@ -10,6 +10,7 @@ my $__dir;
 BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
 require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
 require(Cwd::abs_path("$__dir/../core/result.pm"));
+require(Cwd::abs_path("$__dir/media.pm"));
 
 package ProjectNameUtilities;
 
@@ -34,10 +35,9 @@ $REGISTRY{make_fetch_def} = sub {
     'method' => $spec->{method},
     'headers' => $spec->{headers},
   };
-  if (ProjectNameHelpers::rb_truthy($spec->{body})) {
-    $fetchdef->{body} = Voxgig::Struct::ismap($spec->{body})
-      ? Voxgig::Struct::jsonify($spec->{body})
-      : $spec->{body};
+  my $body = $spec->{body};
+  if (defined $body && !Voxgig::Struct::is_none($body) && !Voxgig::Struct::is_jnull($body)) {
+    $fetchdef->{body} = request_body($ctx->{point}, $body);
   }
 
   return ($fetchdef, undef);

package/project/.sdk/tm/perl/utility/make_options.pm

@@ -10,6 +10,7 @@ my $__dir;
 BEGIN { $__dir = File::Basename::dirname(Cwd::abs_path(__FILE__)) }
 require(Cwd::abs_path("$__dir/../lib/Voxgig/Struct.pm"));
 require(Cwd::abs_path("$__dir/../core/helpers.pm"));
+require(Cwd::abs_path("$__dir/../core/error.pm"));
 require(Cwd::abs_path("$__dir/../schema.pm"));
 require(Cwd::abs_path("$__dir/clean.pm"));
 
@@ -184,6 +185,29 @@ $REGISTRY{make_options} = sub {
     $opts->{extend} = $extend_raw;
   }
 
+  # A templated base URL takes each {name} from options.server. An empty value
+  # cannot make a working URL, so it fails construction, except in test mode,
+  # where it becomes test-<name>.
+  my $base = $opts->{base};
+  if (defined $base && !ref $base && 0 <= index($base, '{')) {
+    my $testmode = ProjectNameHelpers::is_true(ProjectNameHelpers::gpath($opts, 'test.active'))
+      || ProjectNameHelpers::is_true(ProjectNameHelpers::gpath($opts, 'feature.test.active'));
+    my $server = ProjectNameHelpers::to_map($opts->{server}) || {};
+    my $sdkname = ProjectNameHelpers::gpath($config, 'main.name');
+    $sdkname = 'SDK' unless defined $sdkname && !ref $sdkname && '' ne $sdkname;
+    my $fill = sub {
+      my ($name) = @_;
+      my $val = $server->{$name};
+      return $val if defined $val && !ref $val && '' ne $val;
+      return 'test-' . $name if $testmode;
+      die ProjectNameError->new('server_var_required',
+        "$sdkname: the server variable '$name' is required: the API base URL is '$base'"
+        . " - pass { 'server' => { '$name' => '...' } } in the SDK options", $ctx);
+    };
+    (my $resolved = $base) =~ s/\{([A-Za-z0-9_]+)\}/$fill->($1)/ge;
+    $opts->{base} = $resolved;
+  }
+
   # Resolve the feature add-order: an explicit array order (above) wins;
   # otherwise order the map test-first, then the remaining names sorted, so
   # the outcome is deterministic and `test` is always the base transport.