@voxgig/sdkgen 0.44.0 → 1.0.1

package/project/.sdk/src/cmp/rb/TestEntity_rb.ts

@@ -7,7 +7,12 @@ import {
 
 import {
   KIT,
+  Model,
+  ModelEntity,
+  ModelEntityFlow,
+  ModelEntityFlowStep,
   getModelPath,
+  nom,
 } from '@voxgig/apidef'
 
 
@@ -18,34 +23,43 @@ import {
   each,
   buildIdNames,
   getMatchEntries,
+  isAuthActive,
 } from '@voxgig/sdkgen'
 
 
-type OpGen = (ctx: GenCtx, step: any, index: any) => void
-
+// See TestEntity_ts.ts for the GenCtx/OpGen contract.
 type GenCtx = {
-  model: any
-  entity: any
-  flow: any
+  model: Model
+  entity: ModelEntity
+  flow: ModelEntityFlow
   PROJUPPER: string
 }
 
+type OpGen = (ctx: GenCtx, step: ModelEntityFlowStep, index: number) => void
+
 
 const TestEntity = cmp(function TestEntity(props: any) {
   const ctx$ = props.ctx$
-  const model = ctx$.model
+  const model: Model = ctx$.model
 
   const target = props.target
-  const entity = props.entity
+  const entity: ModelEntity = props.entity
 
-  const basicflow = getModelPath(model, `main.${KIT}.flow.Basic${entity.Name}Flow`)
-  const dobasic = basicflow && true === basicflow.active
-
-  if (!dobasic) {
+  const basicflow: ModelEntityFlow | undefined =
+    getModelPath(model, `main.${KIT}.flow.Basic${nom(entity, 'Name')}Flow`)
+  if (null == basicflow || true !== basicflow.active) {
     return
   }
 
-  const PROJUPPER = model.const.Name.toUpperCase().replace(/[^A-Z_]/g, '_')
+  const PROJUPPER = nom(model.const, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+
+  const authActive = isAuthActive(model)
+  const apikeyEnvEntry = authActive
+    ? `\n    "${PROJUPPER}_APIKEY" => "NONE",`
+    : ''
+  const apikeyLiveField = authActive
+    ? `\n        "apikey" => env["${PROJUPPER}_APIKEY"],`
+    : ''
 
   const idnames = buildIdNames(entity, basicflow)
   const idnamesStr = idnames.map(n => `"${n}"`).join(', ')
@@ -77,6 +91,21 @@ class ${entity.Name}EntityTest < Minitest::Test
 
   def test_basic_flow
     setup = ${entity.name}_basic_setup(nil)
+    # Per-op sdk-test-control.json skip.
+    _live = setup[:live] || false
+    [${(Array.from(new Set((allSteps as any[]).map((s: any) => s.op).filter(Boolean)))).map(o => `"${o}"`).join(', ')}].each do |_op|
+      _should_skip, _reason = Runner.is_control_skipped("entityOp", "${entity.name}." + _op, _live ? "live" : "unit")
+      if _should_skip
+        skip(_reason || "skipped via sdk-test-control.json")
+        return
+      end
+    end
+    # The basic flow consumes synthetic IDs from the fixture. In live mode
+    # without an *_ENTID env override, those IDs hit the live API and 4xx.
+    if setup[:synthetic_only]
+      skip "live entity test uses synthetic IDs from fixture — set ${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID JSON to run live"
+      return
+    end
     client = setup[:client]
 
 `)
@@ -138,11 +167,16 @@ end
 
 `)
 
-    Content(`  env = Runner.env_override({
+    Content(`  # Detect ENTID env override before envOverride consumes it. When live
+  # mode is on without a real override, the basic test runs against synthetic
+  # IDs from the fixture and 4xx's. Surface this so the test can skip.
+  entid_env_raw = ENV["${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID"]
+  idmap_overridden = !entid_env_raw.nil? && entid_env_raw.strip.start_with?("{")
+
+  env = Runner.env_override({
     "${PROJUPPER}_TEST_${entity.name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID" => idmap,
     "${PROJUPPER}_TEST_LIVE" => "FALSE",
-    "${PROJUPPER}_TEST_EXPLAIN" => "FALSE",
-    "${PROJUPPER}_APIKEY" => "NONE",
+    "${PROJUPPER}_TEST_EXPLAIN" => "FALSE",${apikeyEnvEntry}
   })
 
   idmap_resolved = Helpers.to_map(
@@ -163,20 +197,22 @@ end
     Content(`
   if env["${PROJUPPER}_TEST_LIVE"] == "TRUE"
     merged_opts = Vs.merge([
-      {
-        "apikey" => env["${PROJUPPER}_APIKEY"],
+      {${apikeyLiveField}
       },
       extra || {},
     ])
     client = ${model.const.Name}SDK.new(Helpers.to_map(merged_opts))
   end
 
+  live = env["${PROJUPPER}_TEST_LIVE"] == "TRUE"
   {
     client: client,
     data: entity_data,
     idmap: idmap_resolved,
     env: env,
     explain: env["${PROJUPPER}_TEST_EXPLAIN"] == "TRUE",
+    live: live,
+    synthetic_only: live && !idmap_overridden,
     now: (Time.now.to_f * 1000).to_i,
   }
 end
@@ -187,9 +223,9 @@ end
 
 const generateCreate: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
-  const ref = step.input?.ref ?? entity.name + '_ref01'
-  const entvar = step.input?.entvar ?? ref + '_ent'
-  const datavar = step.input?.datavar ?? (ref + '_data' + (step.input?.suffix ?? ''))
+  const ref = step.input.ref ?? entity.name + '_ref01'
+  const entvar = step.input.entvar ?? ref + '_ent'
+  const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
 
   const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
@@ -197,8 +233,8 @@ const generateCreate: OpGen = (ctx, step, index) => {
 
   const hasDatvar = priorSteps.some((s: any) => {
     if ('create' === s.op) {
-      const priorRef = s.input?.ref ?? entity.name + '_ref01'
-      const priorDatvar = s.input?.datavar ?? (priorRef + '_data' + (s.input?.suffix ?? ''))
+      const priorRef = s.input.ref ?? entity.name + '_ref01'
+      const priorDatvar = s.input.datavar ?? (priorRef + '_data' + (s.input.suffix ?? ''))
       return priorDatvar === datavar
     }
     return false
@@ -232,17 +268,20 @@ const generateCreate: OpGen = (ctx, step, index) => {
     assert_nil err
     ${datavar} = Helpers.to_map(${datavar}_result)
     assert !${datavar}.nil?
-    assert !${datavar}["id"].nil?
 `)
+  if (null != ctx.entity.id) {
+    Content(`    assert !${datavar}["id"].nil?
+`)
+  }
 }
 
 
 const generateList: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
-  const ref = step.input?.ref ?? entity.name + '_ref01'
-  const entvar = step.input?.entvar ?? ref + '_ent'
-  const matchvar = step.input?.matchvar ?? (ref + '_match' + (step.input?.suffix ?? ''))
-  const listvar = step.input?.listvar ?? (ref + '_list' + (step.input?.suffix ?? ''))
+  const ref = step.input.ref ?? entity.name + '_ref01'
+  const entvar = step.input.entvar ?? ref + '_ent'
+  const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
+  const listvar = step.input.listvar ?? (ref + '_list' + (step.input.suffix ?? ''))
 
   const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
@@ -282,7 +321,7 @@ const generateList: OpGen = (ctx, step, index) => {
     for (const validator of step.valid) {
       const validRef = validator.def?.ref
       const hasRefData = validRef && allSteps.some((s: any) => 'create' === s.op &&
-        ((s.input?.ref ?? entity.name + '_ref01') === validRef))
+        ((s.input.ref ?? entity.name + '_ref01') === validRef))
 
       if ('ItemExists' === validator.apply && hasRefData) {
         const refDataVar = validRef + '_data'
@@ -308,17 +347,19 @@ const generateList: OpGen = (ctx, step, index) => {
 
 const generateUpdate: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
-  const ref = step.input?.ref ?? entity.name + '_ref01'
-  const entvar = step.input?.entvar ?? ref + '_ent'
-  const datavar = step.input?.datavar ?? (ref + '_data' + (step.input?.suffix ?? ''))
-  const resdatavar = step.input?.resdatavar ?? (ref + '_resdata' + (step.input?.suffix ?? ''))
-  const markdefvar = step.input?.markdefvar ?? (ref + '_markdef' + (step.input?.suffix ?? ''))
-  const srcdatavar = step.input?.srcdatavar ?? (ref + '_data' + (step.input?.suffix ?? ''))
+  const ref = step.input.ref ?? entity.name + '_ref01'
+  const entvar = step.input.entvar ?? ref + '_ent'
+  const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
+  const resdatavar = step.input.resdatavar ?? (ref + '_resdata' + (step.input.suffix ?? ''))
+  const markdefvar = step.input.markdefvar ?? (ref + '_markdef' + (step.input.suffix ?? ''))
+  const srcdatavar = step.input.srcdatavar ?? (ref + '_data' + (step.input.suffix ?? ''))
 
   const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
+  const hasEntIdU = null != entity.id
+
   Content(`    # UPDATE
 `)
   if (needsEnt) {
@@ -326,8 +367,11 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 `)
   }
   Content(`    ${datavar}_up = {
-      "id" => ${srcdatavar}["id"],
 `)
+  if (hasEntIdU) {
+    Content(`      "id" => ${srcdatavar}["id"],
+`)
+  }
 
   if (step.data) {
     const dataEntries = Object.entries(step.data).filter(([k]: any) => k !== 'id' && !k.endsWith('$'))
@@ -342,7 +386,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
   if (step.spec) {
     for (const spec of step.spec) {
-      if ('TextFieldMark' === spec.apply && null != step.input?.textfield) {
+      if ('TextFieldMark' === spec.apply && null != step.input.textfield) {
         const fieldname = step.input.textfield
         const fieldvalue = spec.def?.mark ?? `Mark01-${ref}`
         Content(`
@@ -359,12 +403,15 @@ const generateUpdate: OpGen = (ctx, step, index) => {
     assert_nil err
     ${resdatavar} = Helpers.to_map(${resdatavar}_result)
     assert !${resdatavar}.nil?
-    assert_equal ${resdatavar}["id"], ${datavar}_up["id"]
 `)
+  if (hasEntIdU) {
+    Content(`    assert_equal ${resdatavar}["id"], ${datavar}_up["id"]
+`)
+  }
 
   if (step.spec) {
     for (const spec of step.spec) {
-      if ('TextFieldMark' === spec.apply && null != step.input?.textfield) {
+      if ('TextFieldMark' === spec.apply && null != step.input.textfield) {
         Content(`    assert_equal ${resdatavar}[${markdefvar}_name], ${markdefvar}_value
 `)
       }
@@ -375,11 +422,11 @@ const generateUpdate: OpGen = (ctx, step, index) => {
 
 const generateLoad: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
-  const ref = step.input?.ref ?? entity.name + '_ref01'
-  const entvar = step.input?.entvar ?? ref + '_ent'
-  const matchvar = step.input?.matchvar ?? (ref + '_match' + (step.input?.suffix ?? ''))
-  const datavar = step.input?.datavar ?? (ref + '_data' + (step.input?.suffix ?? ''))
-  const srcdatavar = step.input?.srcdatavar ?? (ref + '_data' + (step.input?.suffix ?? ''))
+  const ref = step.input.ref ?? entity.name + '_ref01'
+  const entvar = step.input.entvar ?? ref + '_ent'
+  const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
+  const datavar = step.input.datavar ?? (ref + '_data' + (step.input.suffix ?? ''))
+  const srcdatavar = step.input.srcdatavar ?? (ref + '_data' + (step.input.suffix ?? ''))
 
   const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
   const hasEntVar = priorSteps.some((s: any) =>
@@ -390,20 +437,22 @@ const generateLoad: OpGen = (ctx, step, index) => {
   const hasSrcData = (!flowHasCreate && srcdatavar === (preambleRef + '_data')) ||
     priorSteps.some((s: any) => {
       if ('create' === s.op) {
-        const priorRef = s.input?.ref ?? entity.name + '_ref01'
-        const priorDatvar = s.input?.datavar ?? (priorRef + '_data' + (s.input?.suffix ?? ''))
+        const priorRef = s.input.ref ?? entity.name + '_ref01'
+        const priorDatvar = s.input.datavar ?? (priorRef + '_data' + (s.input.suffix ?? ''))
         return priorDatvar === srcdatavar
       }
       return false
     })
 
+  const hasEntId = null != entity.id
+
   Content(`    # LOAD
 `)
   if (!hasEntVar) {
     Content(`    ${entvar} = client.${entity.Name}(nil)
 `)
   }
-  if (!hasSrcData) {
+  if (!hasSrcData && hasEntId) {
     Content(`    ${srcdatavar}_raw = Vs.items(Helpers.to_map(
       Vs.getpath(setup[:data], "existing.${entity.name}")))
     ${srcdatavar} = nil
@@ -412,7 +461,8 @@ const generateLoad: OpGen = (ctx, step, index) => {
     end
 `)
   }
-  Content(`    ${matchvar} = {
+  if (hasEntId) {
+    Content(`    ${matchvar} = {
       "id" => ${srcdatavar}["id"],
     }
     ${datavar}_loaded, err = ${entvar}.load(${matchvar}, nil)
@@ -421,32 +471,50 @@ const generateLoad: OpGen = (ctx, step, index) => {
     assert !${datavar}_load_result.nil?
     assert_equal ${datavar}_load_result["id"], ${srcdatavar}["id"]
 `)
+  }
+  else {
+    Content(`    ${matchvar} = {}
+    ${datavar}_loaded, err = ${entvar}.load(${matchvar}, nil)
+    assert_nil err
+    assert !${datavar}_loaded.nil?
+`)
+  }
 }
 
 
 const generateRemove: OpGen = (ctx, step, index) => {
   const { entity, flow } = ctx
-  const ref = step.input?.ref ?? entity.name + '_ref01'
-  const entvar = step.input?.entvar ?? ref + '_ent'
-  const matchvar = step.input?.matchvar ?? (ref + '_match' + (step.input?.suffix ?? ''))
-  const srcdatavar = step.input?.srcdatavar ?? (ref + '_data')
+  const ref = step.input.ref ?? entity.name + '_ref01'
+  const entvar = step.input.entvar ?? ref + '_ent'
+  const matchvar = step.input.matchvar ?? (ref + '_match' + (step.input.suffix ?? ''))
+  const srcdatavar = step.input.srcdatavar ?? (ref + '_data')
 
   const priorSteps = Object.values(flow.step).slice(0, Number(index)) as any[]
   const needsEnt = !priorSteps.some((s: any) =>
     ['create', 'list', 'load', 'update', 'remove'].includes(s.op))
 
+  const hasEntIdR = null != entity.id
+
   Content(`    # REMOVE
 `)
   if (needsEnt) {
     Content(`    ${entvar} = client.${entity.Name}(nil)
 `)
   }
-  Content(`    ${matchvar} = {
+  if (hasEntIdR) {
+    Content(`    ${matchvar} = {
       "id" => ${srcdatavar}["id"],
     }
     _, err = ${entvar}.remove(${matchvar}, nil)
     assert_nil err
 `)
+  }
+  else {
+    Content(`    ${matchvar} = {}
+    _, err = ${entvar}.remove(${matchvar}, nil)
+    assert_nil err
+`)
+  }
 }
 
 

package/project/.sdk/src/cmp/rb/fragment/Main.fragment.rb

@@ -164,14 +164,30 @@ class ProjectNameSDK
 
     if fetched.is_a?(Hash)
       status = ProjectNameHelpers.to_int(VoxgigStruct.getprop(fetched, "status"))
+      headers = VoxgigStruct.getprop(fetched, "headers") || {}
+
+      # No-body responses (204, 304) and explicit zero content-length must
+      # skip JSON parsing — calling json() on an empty body errors.
+      content_length = headers.is_a?(Hash) ? headers["content-length"] : nil
+      no_body = status == 204 || status == 304 || content_length.to_s == "0"
+
       json_data = nil
-      jf = VoxgigStruct.getprop(fetched, "json")
-      json_data = jf.call if jf.is_a?(Proc)
+      unless no_body
+        jf = VoxgigStruct.getprop(fetched, "json")
+        if jf.is_a?(Proc)
+          begin
+            json_data = jf.call
+          rescue StandardError
+            # Non-JSON body — leave data nil, keep status/headers.
+            json_data = nil
+          end
+        end
+      end
 
       return {
         "ok" => status >= 200 && status < 300,
         "status" => status,
-        "headers" => VoxgigStruct.getprop(fetched, "headers"),
+        "headers" => headers,
         "data" => json_data,
       }, nil
     end

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

@@ -10,6 +10,7 @@ import {
   cmp,
   each,
   indent,
+  isAuthActive,
 } from '@voxgig/sdkgen'
 
 
@@ -40,6 +41,21 @@ const Config = cmp(async function Config(props: any) {
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
+  const authActive = isAuthActive(model)
+  let authPrefix = 'Bearer'
+  try {
+    const v = getModelPath(model, `main.${KIT}.config.auth.prefix`,
+      { only_active: false, required: false })
+    if (null != v) authPrefix = v
+  } catch (_e) { /* ignore */ }
+  const authBlock = authActive
+    ? `auth: {
+      prefix: '${authPrefix}',
+    },
+
+    `
+    : ''
+
   File({ name: 'Config.' + target.ext }, () => {
 
     Fragment({
@@ -47,6 +63,8 @@ const Config = cmp(async function Config(props: any) {
 
       replace: {
 
+        "'AUTHBLOCK'": authBlock,
+
         "'HEADERS'": indent(JSON.stringify(headers, null, 2), 4).trim(),
 
         '// #ImportFeatures': () => each(feature, (f: any) => {

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

@@ -57,7 +57,7 @@ const Package = cmp(async function Package(props: any) {
     type: 'commonjs',
     types: `dist/${SdkName}SDK.d.ts`,
     scripts: {
-      'test': 'node --enable-source-maps --test \'dist-test/**/*.test.js\'',
+      'test': 'node --enable-source-maps --test-concurrency=1 --test \'dist-test/**/*.test.js\'',
       'test-some': 'node --enable-source-maps --experimental-test-isolation=none ' +
         '--test-name-pattern=\"$TEST_PATTERN\" --test \'dist-test/**/*.test.js\'',
       'test-utility': 'node --enable-source-maps --test test/utility/*.test.ts',

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

@@ -0,0 +1,138 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// Operation method spelling differs between Go and other languages — Go
+// uses PascalCase methods with explicit ctrl arg, others use lowercase
+// methods with optional ctrl. The op descriptions are language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'load(match)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'list(match)',   desc: 'List entities matching the criteria.' },
+  create: { method: 'create(data)',  desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data)',  desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
+}
+
+
+const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      Content(`#### Example: Load
+
+\`\`\`ts
+const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`ts
+const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      Content(`#### Example: Create
+
+\`\`\`ts
+const ${entity.name} = await client.${entity.Name}().create({
+`)
+      each(fields, (field: any) => {
+        if ('id' !== field.name && field.req) {
+          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+`)
+        }
+      })
+      Content(`})
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -10,6 +10,13 @@ import {
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
+  const authActive = isAuthActive(model)
+  const apikeyTesterCtor = authActive
+    ? `new ${model.const.Name}SDK({ apikey: '...' })`
+    : `new ${model.const.Name}SDK()`
+  const apikeyExtendField = authActive ? `\n  apikey: '...',` : ''
+  const apikeyEnvLine = authActive ? `\n${model.NAME}_APIKEY=<your-key>` : ''
+
   Content(`### Make a direct HTTP request
 
 For endpoints not covered by entity methods:
@@ -57,7 +64,7 @@ const result = await client.Planet().load({ id: 'test01' })
 You can also use the instance method:
 
 \`\`\`ts
-const client = new ${model.const.Name}SDK({ apikey: '...' })
+const client = ${apikeyTesterCtor}
 const testClient = client.tester()
 \`\`\`
 
@@ -92,8 +99,7 @@ const logger = {
   },
 }
 
-const client = new ${model.const.Name}SDK({
-  apikey: '...',
+const client = new ${model.const.Name}SDK({${apikeyExtendField}
   extend: [logger],
 })
 \`\`\`
@@ -103,8 +109,7 @@ const client = new ${model.const.Name}SDK({
 Create a \`.env.local\` file at the project root:
 
 \`\`\`
-${model.NAME}_TEST_LIVE=TRUE
-${model.NAME}_APIKEY=<your-key>
+${model.NAME}_TEST_LIVE=TRUE${apikeyEnvLine}
 \`\`\`
 
 Then run:

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

@@ -0,0 +1,18 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+The ${target.title} SDK for the ${model.Name} API. Provides a type-safe, entity-oriented interface with full async/await support.
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}