@voxgig/sdkgen 4.5.3 → 4.7.0

package/project/.sdk/src/cmp/rust/Config_rust.ts

@@ -9,6 +9,7 @@ import {
   isAuthActive,
   isConfigData,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -35,7 +36,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/rust/Main_rust.ts

@@ -5,6 +5,8 @@ import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
   entityClassName,
+  targetFeatures,
+  TEST_CONTROL_EXCLUDE
 } from '@voxgig/sdkgen'
 
 
@@ -35,7 +37,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The rust crate identifier (RUSTCRATE placeholder), e.g. solar_sdk —
   // used in every `use <crate>::...` path in the test templates.
@@ -50,7 +55,7 @@ const Main = cmp(async function Main(props: any) {
   // here exactly like the go target.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//],
+    exclude: [/src\//, TEST_CONTROL_EXCLUDE],
     replace: {
       ...props.ctx$.stdrep,
       RUSTCRATE: rustcrate,

package/project/.sdk/src/cmp/rust/TestDirect_rust.ts

@@ -11,7 +11,9 @@ import {
   File,
   cmp,
   snakify,
-  isAuthActive, envName, envToken
+  isAuthActive, envName, envToken,
+  serverVarEnv,
+  serverVariables
 } from '@voxgig/sdkgen'
 
 
@@ -67,12 +69,28 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
-    ? `\n        ("${PROJECTNAME}_APIKEY", Value::str("NONE")),`
+    ? `\n        ("${PROJECTNAME}_APIKEY", Value::str("")),`
     : ''
   const apikeyLiveField = authActive
     ? `("apikey", getp(&env, "${PROJECTNAME}_APIKEY"))`
     : ''
 
+  // A templated server URL (OpenAPI server variables) makes a LIVE client
+  // impossible to construct without values: makeOptions raises rather than
+  // request a URL with a literal `{account_id}` in it. So the live suite
+  // takes them from the environment the same way it takes the apikey.
+  //
+  // Emitted as a jo() tuple entry, so it carries its own leading comma only
+  // when an apikey entry precedes it - otherwise `jo(vec![, ...])`.
+  const svars = serverVariables(model)
+  const serverEnvEntry = svars
+    .map((v: any) => `\n        ("${serverVarEnv(PROJECTNAME, v.name)}", Value::str(${JSON.stringify(v.dflt)})),`).join('')
+  const serverLiveEntry = 0 === svars.length ? '' :
+    `("server", jo(vec![${svars
+      .map((v: any) => `("${v.name}", getp(&env, "${serverVarEnv(PROJECTNAME, v.name)}"))`).join(', ')}]))`
+  const serverLiveField = '' === serverLiveEntry ? '' :
+    ('' === apikeyLiveField ? serverLiveEntry : ', ' + serverLiveEntry)
+
   const opnames = Object.keys(entity.op || {})
   const hasLoad = opnames.includes('load')
   const hasList = opnames.includes('list')
@@ -148,13 +166,22 @@ fn ${evar}_direct_setup(mockres: Value) -> ${entity.Name}DirectSetup {
 
     let env = env_override(jo(vec![
         ("${entidEnvVar}", Value::empty_map()),
-        ("${PROJECTNAME}_TEST_LIVE", Value::str("FALSE")),${apikeyEnvEntry}
+        ("${PROJECTNAME}_TEST_LIVE", Value::str("FALSE")),${apikeyEnvEntry}${serverEnvEntry}
     ]));
 
     let live = getp(&env, "${PROJECTNAME}_TEST_LIVE") == Value::str("TRUE");
 
     if live {
-        let client = ${model.const.Name}SDK::new(jo(vec![${apikeyLiveField}]));
+        // live_client_options() FIRST, so the generated entries below win:
+        // sdk-test-control.json's test.client.options adds to the live
+        // client, it does not redirect it.
+        let client = ${model.const.Name}SDK::new(to_map(&vs::merge(
+            &ja(vec![
+                live_client_options(),
+                jo(vec![${apikeyLiveField}${serverLiveField}]),
+            ]),
+            None,
+        )));
         let idmap = match to_map(&getp(&env, "${entidEnvVar}")) {
             Value::Map(m) => Value::Map(m),
             _ => Value::empty_map(),

package/project/.sdk/src/cmp/rust/TestEntity_rust.ts

@@ -17,7 +17,9 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
-  isAuthActive, envName, envToken
+  isAuthActive, envName, envToken,
+  serverVarEnv,
+  serverVariables
 } from '@voxgig/sdkgen'
 
 
@@ -56,12 +58,28 @@ const TestEntity = cmp(function TestEntity(props: any) {
 
   const authActive = isAuthActive(model)
   const apikeyEnvEntry = authActive
-    ? `\n        ("${PROJUPPER}_APIKEY", Value::str("NONE")),`
+    ? `\n        ("${PROJUPPER}_APIKEY", Value::str("")),`
     : ''
   const apikeyLiveField = authActive
     ? `("apikey", getp(&env, "${PROJUPPER}_APIKEY"))`
     : ''
 
+  // A templated server URL (OpenAPI server variables) makes a LIVE client
+  // impossible to construct without values: makeOptions raises rather than
+  // request a URL with a literal `{account_id}` in it. So the live suite
+  // takes them from the environment the same way it takes the apikey.
+  //
+  // Emitted as a jo() tuple entry, so it carries its own leading comma only
+  // when an apikey entry precedes it - otherwise `jo(vec![, ...])`.
+  const svars = serverVariables(model)
+  const serverEnvEntry = svars
+    .map((v: any) => `\n        ("${serverVarEnv(PROJUPPER, v.name)}", Value::str(${JSON.stringify(v.dflt)})),`).join('')
+  const serverLiveEntry = 0 === svars.length ? '' :
+    `("server", jo(vec![${svars
+      .map((v: any) => `("${v.name}", getp(&env, "${serverVarEnv(PROJUPPER, v.name)}"))`).join(', ')}]))`
+  const serverLiveField = '' === serverLiveEntry ? '' :
+    ('' === apikeyLiveField ? serverLiveEntry : ', ' + serverLiveEntry)
+
   const idnames = buildIdNames(entity, basicflow)
   const idnamesStr = idnames.map(n => `Value::str("${n}")`).join(', ')
 
@@ -268,7 +286,7 @@ ${allSteps.length > 0 ? '    let client = setup.client.clone();\n' : ''}`)
     let env = env_override(jo(vec![
         ("${PROJUPPER}_TEST_${ENTUPPER}_ENTID", idmap.clone()),
         ("${PROJUPPER}_TEST_LIVE", Value::str("FALSE")),
-        ("${PROJUPPER}_TEST_EXPLAIN", Value::str("FALSE")),${apikeyEnvEntry}
+        ("${PROJUPPER}_TEST_EXPLAIN", Value::str("FALSE")),${apikeyEnvEntry}${serverEnvEntry}
     ]));
 
     let idmap_resolved = match to_map(&getp(&env, "${PROJUPPER}_TEST_${ENTUPPER}_ENTID")) {
@@ -293,7 +311,22 @@ ${allSteps.length > 0 ? '    let client = setup.client.clone();\n' : ''}`)
 
     let client = if live {
         let merged = vs::merge(
-            &ja(vec![jo(vec![${apikeyLiveField}]), extra]),
+            // live_client_options() FIRST, so the generated entries below win:
+            // sdk-test-control.json's test.client.options adds to the live
+            // client, it does not redirect it.
+            &ja(vec![
+                live_client_options(),
+                jo(vec![${apikeyLiveField}${serverLiveField}]),
+                // A NON-NODE later entry REPLACES the accumulated map in
+                // vs::merge, and the normal call passes Value::Noval - so a
+                // a bare extra discarded live_client_options() and the
+                // apikey/server map above it, and the live client was
+                // constructed with nothing.
+                match extra {
+                    Value::Map(m) => Value::Map(m),
+                    _ => Value::empty_map(),
+                },
+            ]),
             None,
         );
         ${model.const.Name}SDK::new(to_map(&merged))

package/project/.sdk/src/cmp/rust/Test_rust.ts

@@ -3,7 +3,8 @@ import type {
   ModelEntity
 } from '@voxgig/apidef'
 
-import { cmp, each, Folder, File, Content, entityCollection } from '@voxgig/sdkgen'
+import { cmp, each, Folder, File, Content, entityCollection,
+  TestControl } from '@voxgig/sdkgen'
 
 
 import { TestEntity } from './TestEntity_rust'
@@ -20,6 +21,9 @@ const Test = cmp(function Test(props: any) {
 
   Folder({ name: 'tests' }, () => {
 
+    // Write-once: a project's edited control file survives regeneration.
+    TestControl({ target, dir: 'tests' })
+
     // exists test — the SDK constructs in test mode.
     File({ name: 'exists_test.' + target.ext }, () => {
       Content(`// Generated existence test: the SDK constructs in test mode.

package/project/.sdk/src/cmp/scala/Config_scala.ts

@@ -6,6 +6,7 @@ import {
   each,
   isAuthActive,
   resolveAuthPrefix,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -35,7 +36,10 @@ const Config = cmp(async function Config(props: any) {
   const scalapackage = scalaPackage(model)
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 

package/project/.sdk/src/cmp/scala/Main_scala.ts

@@ -4,6 +4,8 @@ import * as Path from 'node:path'
 import {
   cmp, each,
   File, Content, Copy, Folder, Fragment,
+  targetFeatures,
+  TEST_CONTROL_EXCLUDE
 } from '@voxgig/sdkgen'
 
 
@@ -33,7 +35,10 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The Scala package root for every runtime piece (like GOMODULE for go).
   const scalapackage = scalaPackage(model)
@@ -47,7 +52,7 @@ const Main = cmp(async function Main(props: any) {
   // ProjectName carries the SDK name into vendored template strings.
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\//],
+    exclude: [/src\//, TEST_CONTROL_EXCLUDE],
     replace: {
       ...props.ctx$.stdrep,
       ProjectName: model.const.Name,

package/project/.sdk/src/cmp/scala/Test_scala.ts

@@ -9,7 +9,8 @@ import type {
   ModelEntity
 } from '@voxgig/apidef'
 
-import { cmp, each, Folder, File, Content, entityCollection } from '@voxgig/sdkgen'
+import { cmp, each, Folder, File, Content, entityCollection,
+  TestControl } from '@voxgig/sdkgen'
 
 
 import { TestEntity } from './TestEntity_scala'
@@ -31,6 +32,9 @@ const Test = cmp(function Test(props: any) {
   // template, and are driven by the generated SdkEntityTestMain aggregator.
   Folder({ name: 'sdktest' }, () => {
 
+    // Write-once: a project's edited control file survives regeneration.
+    TestControl({ target, dir: 'sdktest' })
+
     const entities: { Name: string; entity: boolean; direct: boolean }[] = []
 
     const entity = each(entityCollection(model))

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

@@ -5,6 +5,7 @@ import {
   cmp,
   configDefinition,
   each,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -26,7 +27,10 @@ const Config = cmp(async function Config(props: any) {
 
   const model: Model = ctx$.model
 
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   // The config as data, built by the shared helper so every target embeds
   // the same model by construction. Passing target.name opts this target

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

@@ -18,6 +18,7 @@ import {
   isHttpBasicAuth,
   resolveAuthPrefix,
   serverVariables,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -41,7 +42,10 @@ const Config = cmp(async function Config(props: any) {
   const model: Model = ctx$.model
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
 
   const ff = Path.normalize(__dirname + '/../../../src/cmp/ts/fragment/')
 
@@ -95,10 +99,13 @@ const Config = cmp(async function Config(props: any) {
 
         replace: {
 
-          '// #ImportFeatures': () => each(feature, (f: any) => {
-            Line(`import { ${nom(f, 'Name')}Feature } from ` +
-              `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
-          }),
+          '// #ImportFeatures': () => {
+            each(feature, (f: any) => {
+              Line(`import { ${nom(f, 'Name')}Feature } from ` +
+                `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
+            })
+            pluginImports(feature)
+          },
 
           '// #FeatureClasses': () => each(feature, (f: any) => {
             Line(` ${f.name}: ${nom(f, 'Name')}Feature,`)
@@ -126,10 +133,13 @@ const Config = cmp(async function Config(props: any) {
 
         "'HEADERS'": indent(JSON.stringify(headers, null, 2), 4).trim(),
 
-        '// #ImportFeatures': () => each(feature, (f: any) => {
-          Line(`import { ${nom(f, 'Name')}Feature } from ` +
-            `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
-        }),
+        '// #ImportFeatures': () => {
+          each(feature, (f: any) => {
+            Line(`import { ${nom(f, 'Name')}Feature } from ` +
+              `'./feature/${f.name}/${nom(f, 'Name')}Feature'`)
+          })
+          pluginImports(feature)
+        },
 
         // Values from configDefinition's def, not re-derived here, so the
         // literal rep and the data rep cannot disagree on identity.
@@ -173,6 +183,42 @@ const Config = cmp(async function Config(props: any) {
 })
 
 
+
+// PLUGIN REGISTRATION IMPORTS.
+//
+// A sekreto provider module registers itself when it is imported, and
+// nothing else imports it: the core surface deliberately does not reach a
+// platform-dependent provider, and the full-set barrel — the file whose
+// job was to reach all of them — is not vendored into an SDK at all.
+//
+// So without these lines an SDK generates `provider/dotenv.ts`, never
+// imports it, and throws `unknown provider kind: dotenv` the first time a
+// chain names it. Emitted here because Config already imports every active
+// feature from the model, and this is the same list one level down.
+//
+// Import for SIDE EFFECT only — `import '...'`, no bindings. The module's
+// top-level `register()` call is the whole point.
+function pluginImports(feature: any) {
+  each(feature, (f: any) => {
+    each(f.plugin, (plugin: any) => {
+      // Filter on `active` HERE rather than trusting the feature object to
+      // arrive filtered. Whether a model path was read with `only_active`
+      // varies by call site, and getting it wrong in this direction emits
+      // an import for a module the trim just deleted — an SDK that does
+      // not compile, rather than one that merely carries too much.
+      if (false === plugin.active || null == plugin.active) return
+
+      for (const one of (plugin.path || [])) {
+        const path = String(one)
+        // Only a provider MODULE registers a kind; a plugin may own other
+        // files (Sigv4.ts is signing support, not a provider).
+        if (!/\/provider\/[^/]+\.ts$/.test(path)) continue
+        Line(`import '${'./' + path.replace(/^src\//, '').replace(/\.ts$/, '')}'`)
+      }
+    })
+  })
+}
+
 export {
   Config
 }

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

@@ -4,7 +4,10 @@ import * as Path from 'node:path'
 import {
   cmp, each, names, cmap,
   List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
-  entityClassName, entityCollection, srcFeatureExcludes, stationLibrary,
+  entityClassName, entityCollection, srcFeatureExcludes, pluginExcludes,
+  stationLibrary,
+  targetFeatures,
+  TEST_CONTROL_EXCLUDE
 } from '@voxgig/sdkgen'
 
 
@@ -35,7 +38,14 @@ const Main = cmp(async function Main(props: any) {
   const { model } = props.ctx$
 
   const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by the applicability tags, so this target never imports or
+  // registers a feature it has no source for. One rule, one place:
+  // helpers/applicability.
+  const feature = targetFeatures(model, target)
+
+  // Does the secrets feature apply here and is it switched on? Both, since
+  // targetFeatures already dropped it for a target with no sekreto port.
+  const secrets = null != feature.secrets
 
   Package({ target })
 
@@ -45,7 +55,13 @@ const Main = cmp(async function Main(props: any) {
     from: 'tm/' + target.name,
     // Root copies src/feature/<name>/ per ACTIVE feature; keep this blanket
     // copy from restoring one that was switched off after `target add`.
-    exclude: srcFeatureExcludes(model),
+    // A feature's inactive plugins go too - same rule, one level
+    // deeper. See helpers/featureSource.pluginExcludes.
+    exclude: [
+      ...srcFeatureExcludes(model),
+      ...pluginExcludes(model),
+      TEST_CONTROL_EXCLUDE,
+    ],
     replace: {
       ...props.ctx$.stdrep,
     }
@@ -74,6 +90,54 @@ const Main = cmp(async function Main(props: any) {
           replace: {
             ...props.ctx$.stdrep,
 
+            // SECRETS. All five slots are emitted only when the secrets
+            // feature applies to this target AND the model activates it.
+            // An unconditional edit here would land in every generated SDK
+            // and break the inactive-output gate: a model without the
+            // feature must generate byte-identically to pre-migration.
+            //
+            // `feature` is already gated by targetFeatures, so a target
+            // that does not provide 'sekreto' never reaches these.
+            '// #SecretsImport': () => secrets ?
+              Line(`import * as sekreto from './feature/secrets/sekreto'`) : undefined,
+
+            '// #SecretsField': ({ indent }: any) => secrets ?
+              Line({ indent }, '_secrets?: any') : undefined,
+
+            // The LIVE instance, not a clone: sekreto holds provider and
+            // cache state, so a clone would resolve into a copy that
+            // prepareAuth never sees.
+            '// #SecretsAccessor': ({ indent }: any) => secrets ?
+              Content({ indent }, `
+secrets() {
+  return this._secrets && this._secrets.sekreto()
+}
+`) : undefined,
+
+            // prepare() bypasses the feature hook pipeline, so the PreSpec
+            // hook that resolves the secret for entity ops never runs on
+            // this path and the resolve has to be explicit.
+            //
+            // It RETURNS the Error rather than rejecting: _rawRequest
+            // awaits prepare() outside its try, and direct()/graphql() are
+            // documented to return a value or an Error, never reject. The
+            // prototype rejected here, which would have turned a broken
+            // vault into an unhandled rejection on the direct path.
+            '// #SecretsResolve': ({ indent }: any) => secrets ?
+              Content({ indent }, `
+if (null != this._secrets) {
+  try {
+    await this._secrets.resolve()
+  }
+  catch (err: any) {
+    return err instanceof Error ? err : new Error(String(err))
+  }
+}
+`) : undefined,
+
+            '// #SecretsExport': ({ indent }: any) => secrets ?
+              Line({ indent }, 'sekreto,') : undefined,
+
             '#BuildFeatures': ({ indent }: any) => {
               List({ item: feature, line: false }, ({ item }: any) =>
                 Line({ indent },

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

@@ -13,6 +13,7 @@ import {
   PUBLISHER_URL,
   packageVersion,
   authorInfo,
+  targetFeatures,
 } from '@voxgig/sdkgen'
 
 
@@ -36,7 +37,9 @@ const Package = cmp(async function Package(props: any) {
   // constant here did.
   const author = authorInfo(model, target.name)
 
-  const feature = getModelPath(model, `main.${KIT}.feature`)
+  // Gated by applicability: a feature that does not apply to this
+  // target must not inject its deps into the generated manifest.
+  const feature = targetFeatures(model, target)
 
   const only = (kind: string, deps: any) =>
     omap(deps, ([k, v]: any) => [v.active && kind === v.kind ? k : undefined, v.version])

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, isHttpBasicAuth } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, isHttpBasicAuth, serverVariables } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -61,12 +61,24 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
     ? '| `secret` | `string` | API secret for authentication. |\n'
     : ''
 
+  // Server variables are not one option among many: without them the
+  // constructor THROWS, because the base URL is a template. Documented
+  // first for that reason, and named individually so a reader knows what
+  // to supply without going back to the spec.
+  const svars = serverVariables(model)
+  const serverOptionType = 0 === svars.length ? '' :
+    `\n  server?: { ${svars.map((v: any) => `${v.name}: string`).join(', ')} }`
+  const serverOptionRow = 0 === svars.length ? '' :
+    '| `server` | `object` | **Required.** Values for the server-URL variables: ' +
+    svars.map((v: any) => '`' + v.name + '`').join(', ') +
+    '. The API base URL is a template over them. |\n'
+
   Content(`### ${model.const.Name}SDK
 
 #### Constructor
 
 \`\`\`ts
-new ${model.const.Name}SDK(options?: {${apikeyOptionType}${secretOptionType}
+new ${model.const.Name}SDK(options?: {${apikeyOptionType}${secretOptionType}${serverOptionType}
   base?: string
   prefix?: string
   suffix?: string
@@ -77,7 +89,7 @@ new ${model.const.Name}SDK(options?: {${apikeyOptionType}${secretOptionType}
 
 | Option | Type | Description |
 | --- | --- | --- |
-${apikeyOptionRow}${secretOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
+${serverOptionRow}${apikeyOptionRow}${secretOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
 | \`prefix\` | \`string\` | URL path prefix prepended to all requests. |
 | \`suffix\` | \`string\` | URL path suffix appended to all requests. |
 | \`feature\` | \`object\` | Feature activation flags (e.g. \`{ test: { active: true } }\`). |

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content, isAuthActive, isHttpBasicAuth, packageName, envName, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive, isHttpBasicAuth, packageName, envName, serverVariables, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -40,10 +40,23 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
       !it.optional && it.name !== entityIdField(e))
   ) as any
 
-  const ctor = isAuthActive(model)
-    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,${
-      isHttpBasicAuth(model) ? `\n  secret: process.env.${envName(model)}_SECRET,` : ''}\n})`
-    : `new ${model.const.Name}SDK()`
+  // Server variables (a templated server URL) are REQUIRED at construction
+  // — makeOptions refuses rather than request a URL with a literal
+  // `{account_id}` in it — so a quickstart that omits them is a quickstart
+  // that throws on its first line.
+  const svarLines = serverVariables(model)
+    .map((v: any) => `\n    ${v.name}: '<${v.name}>',`).join('')
+  const serverField = '' === svarLines ? '' :
+    `\n  // Required: this API's server URL is templated on these.\n  server: {${svarLines}\n  },`
+
+  const ctorFields = (isAuthActive(model)
+    ? `\n  apikey: process.env.${envName(model)}_APIKEY,${
+      isHttpBasicAuth(model) ? `\n  secret: process.env.${envName(model)}_SECRET,` : ''}`
+    : '') + serverField
+
+  const ctor = '' === ctorFields
+    ? `new ${model.const.Name}SDK()`
+    : `new ${model.const.Name}SDK({${ctorFields}\n})`
 
   Content(`### 1. Create a client
 

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content, isAuthActive, isHttpBasicAuth, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, isHttpBasicAuth, packageName, envName, entityIdField, entityOps, opRequestShape, safeVarName, exampleVarName, jsKey, matchArg, idLiteral , serverVariables} from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -28,10 +28,24 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
   const authActive = isAuthActive(model)
-  const ctor = authActive
-    ? `new ${model.const.Name}SDK({\n  apikey: process.env.${envName(model)}_APIKEY,${
-      isHttpBasicAuth(model) ? `\n  secret: process.env.${envName(model)}_SECRET,` : ''}\n})`
-    : `new ${model.const.Name}SDK()`
+
+  // Server variables (a templated server URL) are REQUIRED at construction
+  // - makeOptions refuses rather than request a URL with a literal
+  // {account_id} in it - so a quickstart that omits them is a quickstart
+  // that throws on its first line.
+  const svarLines = serverVariables(model)
+    .map((v: any) => `\n    ${v.name}: '<${v.name}>',`).join('')
+  const serverField = '' === svarLines ? '' :
+    `\n  // Required: this API's server URL is templated on these.\n  server: {${svarLines}\n  },`
+
+  const ctorFields = (authActive
+    ? `\n  apikey: process.env.${envName(model)}_APIKEY,${
+      isHttpBasicAuth(model) ? `\n  secret: process.env.${envName(model)}_SECRET,` : ''}`
+    : '') + serverField
+
+  const ctor = '' === ctorFields
+    ? `new ${model.const.Name}SDK()`
+    : `new ${model.const.Name}SDK({${ctorFields}\n})`
 
   Content(`\`\`\`ts
 import { ${model.const.Name}SDK } from '${packageName(model, target.name)}'