@voxgig/sdkgen 1.3.2 → 1.3.5

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

@@ -38,6 +38,9 @@ def prepare_auth_util(ctx):
         apikey_val = ""
         if isinstance(apikey, str):
             apikey_val = apikey
-        headers[HEADER_AUTH] = auth_prefix + " " + apikey_val
+        # Empty prefix (raw apiKey credential) must not add a leading space.
+        headers[HEADER_AUTH] = (
+            auth_prefix + " " + apikey_val if auth_prefix else apikey_val
+        )
 
     return spec, None

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

@@ -25,7 +25,9 @@ module ProjectNameUtilities
     else
       auth_prefix = VoxgigStruct.getpath(options, "auth.prefix") || ""
       apikey_val = apikey.is_a?(String) ? apikey : ""
-      headers[HEADER_AUTH] = "#{auth_prefix} #{apikey_val}"
+      # Empty prefix (raw apiKey credential) must not add a leading space.
+      headers[HEADER_AUTH] =
+        auth_prefix.empty? ? apikey_val : "#{auth_prefix} #{apikey_val}"
     end
 
     return spec, nil

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

@@ -36,13 +36,17 @@ function prepareAuth(ctx: Context): Spec | Error {
     return spec
   }
 
+  const prefix = options.auth.prefix
+
   const apikey = getprop(options, OPTION_apikey, NOTFOUND)
 
   if (NOTFOUND === apikey || null == apikey || '' === apikey) {
     delprop(headers, HEADER_auth)
   }
   else {
-    setprop(headers, HEADER_auth, options.auth.prefix + ' ' + apikey)
+    // A raw credential (empty prefix, e.g. an apiKey scheme) must go in
+    // as-is; only a non-empty prefix (Bearer/Basic/OAuth) is space-joined.
+    setprop(headers, HEADER_auth, prefix ? prefix + ' ' + apikey : apikey)
   }
 
   return spec

package/src/cmp/ReadmeErrors.ts

@@ -6,7 +6,7 @@ import {
   getModelPath
 } from '../types'
 
-import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { entityIdField, pickExampleEntity } from '../helpers/opShape'
 import { primaryOpCall } from '../helpers/opExample'
 import type { ExampleLang, PrimaryCall } from '../helpers/opExample'
 import { safeVarName } from '../helpers/naming'
@@ -224,29 +224,28 @@ const ReadmeErrors = cmp(function ReadmeErrors(props: any) {
 
   const lang = LANGS[target.name] || DEFAULT_LANG
 
-  // Derive a real example entity from the model (the same way the sibling
-  // Readme components do) so the snippet never references a phantom entity.
+  // Pick a real example entity WITH a real op (prefer a read op) so the
+  // error-handling snippet never references a phantom entity or fabricates a
+  // `.load()` on an op-less one (e.g. Cloudsmith's `Abort`). primaryOp is null
+  // only when NO entity exposes any op — then the entity example is skipped
+  // and only the direct() error handling (which every SDK has) is shown.
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
-  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
-  // Sanitise the variable name against the target's reserved words (a `Delete`
-  // entity must not bind `const delete = ...`).
-  const eLower = safeVarName(eName.toLowerCase(), target.name)
-
-  // The entity's id-like key field name, or null when it has none.
-  const idF = entityIdField(ex)
-  // The entity's PRIMARY op — an op it actually exposes (prefer list/load, else
-  // create/update/remove). A create-only entity therefore never shows a
-  // phantom `.load()`.
-  const primaryOp = entityPrimaryOp(ex) || 'load'
-  const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+  const { entity: ex, primaryOp } = pickExampleEntity(entity || {})
 
   Content(`
 ## Error handling
 
 `)
 
-  Content(lang.entity(call, primaryOp))
+  if (ex && primaryOp) {
+    const eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
+    // Sanitise the variable name against the target's reserved words (a
+    // `Delete` entity must not bind `const delete = ...`).
+    const eLower = safeVarName(eName.toLowerCase(), target.name)
+    const idF = entityIdField(ex)
+    const call = primaryOpCall(target.name as ExampleLang, eName, eLower, primaryOp, idF, ex)
+    Content(lang.entity(call, primaryOp))
+  }
 
   Content(lang.direct)
 })

package/src/cmp/ReadmeExplanation.ts

@@ -8,7 +8,7 @@ import {
 
 import { requirePath } from '../utility'
 
-import { entityIdField, entityPrimaryOp } from '../helpers/opShape'
+import { entityIdField, pickExampleEntity } from '../helpers/opShape'
 import { idLiteral, matchArg, dataArg } from '../helpers/opExample'
 import type { ExampleLang } from '../helpers/opExample'
 import { safeVarName } from '../helpers/naming'
@@ -225,39 +225,40 @@ const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
   const feature = getModelPath(model, `main.${KIT}.feature`)
   const lang = LANGS[target.name] || DEFAULT_LANG
 
-  // Derive a real example entity from the model (the same way the sibling
-  // Readme components do) so the entity-state example never references a
-  // phantom entity.
+  // Pick a real example entity WITH a real op (prefer a read op) so the
+  // entity-state example never references a phantom entity or fabricates a
+  // `.load()` on an op-less one (e.g. Cloudsmith's `Abort`). primaryOp is null
+  // only when NO entity exposes any op — then the entity-state section is
+  // skipped (a direct()-only SDK has no entity op to illustrate).
   const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
-  const ex = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
-  const eName = ex ? (ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))) : 'Entity'
-  // Sanitise against the target's reserved words (a `Delete` entity must not
-  // bind `const delete = ...`).
-  const eLower = safeVarName(eName.toLowerCase(), target.name)
+  const { entity: ex, primaryOp } = pickExampleEntity(entity || {})
   const lname = target.name as ExampleLang
-  // The entity's id-like key field name, or null when it has none (a
-  // response-wrapped spec can model an entity with no id). Drives whether the
-  // state example keys on an id at all.
-  const idF = entityIdField(ex)
-  // The entity's PRIMARY op — an op it actually exposes (never a hardcoded
-  // `load` a create-only entity lacks).
-  const primaryOp = entityPrimaryOp(ex) || 'load'
-  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
-  // Type-correct example id literal (numeric when the id param is integer-typed),
-  // derived from the OP's param type so an id carried only in the match compiles.
-  const idLit = idLiteral(ex, primaryOp, idF)
-  // Language-correct call argument for the primary op: a match for load/remove,
-  // a required-field body for create/update, nothing for list.
-  let stateArg: string
-  if ('list' === primaryOp) {
-    stateArg = 'go' === target.name ? 'nil' : ''
-  } else if (isMatchOp) {
-    stateArg = matchArg(lname, idF, idLit)
-  } else {
-    stateArg = dataArg(lname, ex, primaryOp, idF)
+  const hasEntityExample = !!(ex && primaryOp)
+
+  let eName = 'Entity', eLower = 'entity', stateArg = '', matchIdF: string | null = null, idLit = ''
+  if (hasEntityExample) {
+    eName = ex.Name || (ex.name[0].toUpperCase() + ex.name.slice(1))
+    // Sanitise against the target's reserved words (a `Delete` entity must
+    // not bind `const delete = ...`).
+    eLower = safeVarName(eName.toLowerCase(), target.name)
+    const idF = entityIdField(ex)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    // Type-correct example id literal (numeric when the id param is integer-
+    // typed), derived from the OP's param type so an id carried only in the
+    // match compiles.
+    idLit = idLiteral(ex, primaryOp as string, idF)
+    // Language-correct call argument for the primary op: a match for
+    // load/remove, a required-field body for create/update, nothing for list.
+    if ('list' === primaryOp) {
+      stateArg = 'go' === target.name ? 'nil' : ''
+    } else if (isMatchOp) {
+      stateArg = matchArg(lname, idF, idLit)
+    } else {
+      stateArg = dataArg(lname, ex, primaryOp as string, idF)
+    }
+    // Only a match op keys the `.match()` comment on `{ id: ... }`.
+    matchIdF = isMatchOp ? idF : null
   }
-  // Only a match op keys the `.match()` comment on `{ id: ... }`.
-  const matchIdF = isMatchOp ? idF : null
 
   Content(`
 ## Advanced
@@ -327,12 +328,13 @@ were added, so later features can override earlier ones.
   }
 
 
-  // Entity state
-  Content(`### Entity state
+  // Entity state — only when the SDK actually has an entity op to show.
+  if (hasEntityExample) {
+    Content(`### Entity state
 
 `)
-
-  Content(lang.entityState(eName, eLower, primaryOp, stateArg, matchIdF, idLit))
+    Content(lang.entityState(eName, eLower, primaryOp as string, stateArg, matchIdF, idLit))
+  }
 
 
   // Direct vs entity access

package/src/cmp/ReadmeTop.ts

@@ -86,6 +86,17 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
   const docsUrl = info.docs_url || ''
   const entityDesc = info.entity_desc || {}
 
+  // Spec-derived (apidef): a short "what this API is" blurb and a link back
+  // to the API's own website. Both surface right under the title, before
+  // the unofficial-SDK disclosure, so a reader immediately sees what the
+  // underlying API is and where it comes from.
+  const apiSummary = (info.summary || '').trim()
+  const apiWebsite = (info.website || '').trim()
+  const websiteLine = apiWebsite
+    ? `Learn more about ${productName} at ` +
+    `[${apiWebsite.replace(/^https?:\/\//, '').replace(/\/$/, '')}](${apiWebsite}).`
+    : ''
+
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const target = getModelPath(model, `main.${KIT}.target`)
   const feature = getModelPath(model, `main.${KIT}.feature`)
@@ -123,12 +134,24 @@ const ReadmeTop = cmp(function ReadmeTop(props: any) {
 
   File({ name: 'README.md' }, () => {
 
-    // 1. H1 + one-line value prop + unofficial / non-affiliation disclosure
+    // 1. H1 + one-line value prop, then the API's own purpose + website
+    // (spec-derived), then the unofficial / non-affiliation disclosure.
     Content(`# ${model.Name} SDK
 
 ${tagline}
 
-${nonAffiliation(model)}
+`)
+    if (apiSummary) {
+      Content(`${apiSummary}
+
+`)
+    }
+    if (websiteLine) {
+      Content(`${websiteLine}
+
+`)
+    }
+    Content(`${nonAffiliation(model)}
 
 `)
 

package/src/helpers/naming.ts

@@ -11,8 +11,11 @@
 // words a `const` binding trips on). Go lists its 25 keywords — a var named
 // `type`/`func`/`range` fails `go build`; Go builtins like `delete`/`len` are
 // NOT keywords and are legal identifiers, so they are intentionally omitted.
-// py/php/rb/lua rarely collide on a lowercased entity name and are not treated
-// here (add a set if a real collision surfaces).
+// rb/py/lua list the keywords that are illegal as a local-variable binding
+// (e.g. a `Self` entity -> `self = client.Self` is a Ruby SyntaxError, an
+// `End` entity -> `end = ...` a Lua one). PHP variables are `$`-prefixed so a
+// lowercased entity name never collides (only `$this` is special, and no
+// entity is named `this`), so PHP is not treated.
 
 const JS_RESERVED = new Set<string>([
   'break', 'case', 'catch', 'class', 'const', 'continue', 'debugger',
@@ -32,10 +35,37 @@ const GO_RESERVED = new Set<string>([
   'var',
 ])
 
+// Ruby keywords — illegal as a local-variable name (e.g. `self`, `end`).
+const RB_RESERVED = new Set<string>([
+  'alias', 'and', 'begin', 'break', 'case', 'class', 'def', 'defined?',
+  'do', 'else', 'elsif', 'end', 'ensure', 'false', 'for', 'if', 'in',
+  'module', 'next', 'nil', 'not', 'or', 'redo', 'rescue', 'retry', 'return',
+  'self', 'super', 'then', 'true', 'undef', 'unless', 'until', 'when',
+  'while', 'yield', '__FILE__', '__LINE__', '__ENCODING__', 'BEGIN', 'END',
+])
+
+// Python keywords — illegal as a variable name.
+const PY_RESERVED = new Set<string>([
+  'False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await', 'break',
+  'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally',
+  'for', 'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal',
+  'not', 'or', 'pass', 'raise', 'return', 'try', 'while', 'with', 'yield',
+])
+
+// Lua keywords — illegal as a variable name. (`self` is NOT reserved in Lua.)
+const LUA_RESERVED = new Set<string>([
+  'and', 'break', 'do', 'else', 'elseif', 'end', 'false', 'for', 'function',
+  'goto', 'if', 'in', 'local', 'nil', 'not', 'or', 'repeat', 'return',
+  'then', 'true', 'until', 'while',
+])
+
 const RESERVED: Record<string, Set<string>> = {
   ts: JS_RESERVED,
   js: JS_RESERVED,
   go: GO_RESERVED,
+  rb: RB_RESERVED,
+  py: PY_RESERVED,
+  lua: LUA_RESERVED,
 }
 
 

package/src/helpers/opShape.ts

@@ -238,6 +238,93 @@ function entityPrimaryOp(ent: any): string | null {
 }
 
 
+// Collision-free target-language CLASS name for an entity. The natural
+// class name is `<Name>Entity`, but that can equal another entity's
+// canonical DATA-type name `<Name'>` when Name' === Name + 'Entity' (e.g.
+// GitLab's `project` -> class `ProjectEntity` collides with `project_entity`
+// -> data type `ProjectEntity`), which redeclares a type in Go and merges/
+// shadows it in ts/py/rb. This assigns each entity a class name that is
+// unique across ALL emitted top-level type names (every entity's data type
+// and per-op Match/Data types, plus already-assigned class names): the
+// natural `<Name>Entity` when free, else `<Name>EntityClient`, `...Client2`,
+// … The DATA type keeps its canonical `<Name>` — only the suffixed class
+// yields. Deterministic (sorted-key iteration) and stable across runs.
+//
+// Memoised per entity-collection object so the O(n) assignment runs once.
+const _classNameCache = new WeakMap<object, Record<string, string>>()
+
+function entityClassNames(entityColl: any): Record<string, string> {
+  const cached = _classNameCache.get(entityColl)
+  if (null != cached) {
+    return cached
+  }
+
+  const ents = each(entityColl).filter((e: any) => e && e.active !== false)
+
+  // 1. Every top-level DATA-type name the target emits.
+  const taken: Record<string, boolean> = {}
+  ents.forEach((e: any) => {
+    taken[e.Name] = true
+    for (const op of ['load', 'list', 'create', 'update', 'remove']) {
+      if (e.op && e.op[op]) {
+        taken[opTypeName(e.Name, op)] = true
+      }
+    }
+  })
+
+  // 2. Assign each class name, avoiding all data types and prior classes.
+  const out: Record<string, string> = {}
+  ents.forEach((e: any) => {
+    let name = e.Name + 'Entity'
+    if (taken[name]) {
+      const base = name + 'Client'
+      name = base
+      let n = 1
+      while (taken[name]) {
+        n++
+        name = base + n
+      }
+    }
+    taken[name] = true
+    out[e.name] = name
+  })
+
+  _classNameCache.set(entityColl, out)
+  return out
+}
+
+
+// The collision-free class name for one entity (see entityClassNames).
+// `entityColl` is main.<KIT>.entity (the collection the entity belongs to).
+function entityClassName(ent: any, entityColl: any): string {
+  if (null == ent) {
+    return ''
+  }
+  const map = entityClassNames(entityColl)
+  return map[ent.name] || (ent.Name + 'Entity')
+}
+
+
+// Pick a representative entity for a single illustrative snippet (e.g. the
+// README's test-mode example): the first ACTIVE entity that exposes a read
+// op (list/load) so the snippet is meaningful, else the first with ANY
+// active op, else the first active entity. Returns { entity, primaryOp }
+// where primaryOp is null only when NO entity has an op — so callers never
+// fabricate an op the entity lacks (the cause of `.load()` on an op-less
+// entity like Cloudsmith's `Abort`). Entities iterate in sorted-key order
+// for deterministic output.
+function pickExampleEntity(entity: any): { entity: any, primaryOp: string | null } {
+  const actives = each(entity).filter((e: any) => e && e.active !== false)
+  const readable = actives.find((e: any) => {
+    const op = entityPrimaryOp(e)
+    return 'list' === op || 'load' === op
+  })
+  const withOp = actives.find((e: any) => null != entityPrimaryOp(e))
+  const chosen = readable || withOp || actives[0] || null
+  return { entity: chosen, primaryOp: null == chosen ? null : entityPrimaryOp(chosen) }
+}
+
+
 // The id field on the entity's DATA type (its fields[]), or null. DISTINCT from
 // entityIdField (the load-MATCH key): an API can model a load match that carries
 // an `id` param while the response entity itself has no `id` field, so `.id`
@@ -267,6 +354,8 @@ export {
   entityDataIdField,
   entityOps,
   entityPrimaryOp,
+  pickExampleEntity,
+  entityClassName,
 }
 
 export type {

package/src/sdkgen.ts

@@ -48,7 +48,7 @@ import { getMatchEntries } from './helpers/getMatchEntries'
 import { collectDeps } from './helpers/collectDeps'
 import type { DepEntry } from './helpers/collectDeps'
 import { canonToType, canonKey } from './helpers/canonType'
-import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp } from './helpers/opShape'
+import { OP_SUFFIX, opTypeName, opParams, opRequestShape, entityIdField, entityDataIdField, entityOps, entityPrimaryOp, pickExampleEntity, entityClassName } from './helpers/opShape'
 import { isReservedName, safeVarName } from './helpers/naming'
 import {
   packageName,
@@ -448,6 +448,8 @@ export {
   entityDataIdField,
   entityOps,
   entityPrimaryOp,
+  pickExampleEntity,
+  entityClassName,
   isReservedName,
   safeVarName,