@voxgig/sdkgen 1.2.1 → 1.3.1

package/project/.sdk/src/cmp/js/EntityTypes_js.ts

@@ -0,0 +1,111 @@
+
+
+// Typed-model generator (JavaScript target).
+//
+// JavaScript is dynamically typed, so the "types" are JSDoc typedefs
+// (@typedef / @property) for editor/tooling DX only — no runtime effect.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file, src/<Sdk>Types.js,
+// with a `@typedef {Object} <Name>` per active entity plus a request/match
+// typedef per active op. Field/param sentinels ($STRING, $INTEGER, ...) are
+// turned into JSDoc types by the shared sdkgen helper `canonToType`
+// ('js' column: Object / Array / * for open shapes).
+//
+// The typedefs are emitted at file (script) scope so they are GLOBAL across
+// the SDK's JS program — the op fragments reference them by bare name
+// (@param {AdviceLoadMatch} / @returns {Promise<Advice>}). Keeps the SAME
+// type-name scheme as the TS reference (<Name>, <Name>LoadMatch,
+// <Name>ListMatch, <Name>CreateData, <Name>UpdateData, <Name>RemoveMatch).
+
+import {
+  cmp, each,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'js'
+
+
+// A bare JSDoc property key, or a quoted string literal for anything that is
+// not a plain identifier.
+function propKey(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  File({ name: model.const.Name + 'Types.' + LANG }, () => {
+
+    Content(`// Typed models for the ${model.const.Name} SDK (JSDoc typedefs).
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+// @voxgig/apidef VALID_CANON). Annotations only — no runtime effect. Do not
+// edit by hand.
+
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one @property per field, `req:false` -> optional [].
+      Content(`/**
+ * @typedef {Object} ${Name}
+`)
+      fields.forEach((f: any) => {
+        const key = false === f.req ? '[' + propKey(f.name) + ']' : propKey(f.name)
+        Content(` * @property {${canonToType(f.type, LANG)}} ${key}
+`)
+      })
+      Content(` */
+
+`)
+
+      // Per active op: a request/match typedef. Members and their optionality
+      // come from the shared partiality policy (opRequestShape); this file only
+      // renders them as JSDoc @property lines (optional -> [bracketed] key).
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        Content(`/**
+ * @typedef {Object} ${typeName}
+`)
+        items.forEach((it: any) => {
+          const key = it.optional ? '[' + propKey(it.name) + ']' : propKey(it.name)
+          Content(` * @property {${canonToType(it.type, LANG)}} ${key}
+`)
+        })
+        Content(` */
+
+`)
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/js/MainEntity_js.ts

@@ -7,6 +7,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
 
   Content(`
+  // Entity access: \`client.${entity.Name}().list()\` / \`client.${entity.Name}().load({ id })\`.
   ${entity.Name}(data) {
     const self = this
     return new ${entity.Name}Entity(self,data)

package/project/.sdk/src/cmp/js/Main_js.ts

@@ -24,6 +24,7 @@ import { Gitignore } from './Gitignore_js'
 import { MainEntity } from './MainEntity_js'
 import { SdkError } from './SdkError_js'
 import { EntityBase } from './EntityBase_js'
+import { EntityTypes } from './EntityTypes_js'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -101,6 +102,8 @@ if (fres instanceof Promise) { await fres }
 
     EntityBase({ target })
 
+    EntityTypes({ target })
+
   })
 })
 

package/project/.sdk/src/cmp/js/Package_js.ts

@@ -5,6 +5,12 @@ import {
   cmp,
   each,
   omap,
+  packageName,
+  pkgDescription,
+  keywords,
+  repoInfo,
+  PUBLISHER,
+  PUBLISHER_URL,
 } from '@voxgig/sdkgen'
 
 
@@ -43,16 +49,19 @@ const Package = cmp(async function Package(props: any) {
           dev: only('dev', target.deps),
         })
 
-  const sdkname = model.name
   const SdkName = nom(model, 'Name')
-  const origin = null == model.origin ? '' : `@${model.origin}/`
-  const sdknamesuffix = model.origin?.endsWith('-sdk') ? '' : '-sdk'
+  const { repoUrl, issuesUrl } = repoInfo(model)
 
-  // TODO: complete SDK meta data in model and use here
   const pkg = {
-    name: `${origin}${sdkname}${sdknamesuffix}`,
+    // The ts target publishes the canonical scoped npm name; the js target
+    // appends `-js` so the two never collide on npm.
+    name: packageName(model, 'js'),
     version: `0.0.1`,
-    description: 'DESCRIPTION',
+    description: pkgDescription(model, target.name),
+    keywords: keywords(model),
+    homepage: `${repoUrl}#readme`,
+    repository: { type: 'git', url: `git+${repoUrl}.git` },
+    bugs: { url: issuesUrl },
     main: `src/${SdkName}SDK.js`,
     type: 'commonjs',
     scripts: {
@@ -64,7 +73,7 @@ const Package = cmp(async function Package(props: any) {
       "clean": "rm -rf node_modules yarn.lock package-lock.json",
       "reset": "npm run clean && npm i && npm test",
     },
-    author: `${SdkName}`,
+    author: { name: PUBLISHER, url: PUBLISHER_URL },
 
     // TODO: needs to be config
     license: 'MIT',

package/project/.sdk/src/cmp/js/ReadmeEntity_js.ts

@@ -1,11 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, entityIdField, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
@@ -41,6 +43,10 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // Variable-safe lowercase name (a `Delete` entity must not bind `delete`).
+    const eVar = safeVarName(entity.name, 'js')
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +59,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`const ${eVar} = client.${entity.Name}()\`
 
 `)
 
@@ -84,7 +90,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -96,7 +102,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
       Content(`#### Example: Load
 
 \`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+const ${eVar} = await client.${entity.Name}().load(${idF ? `{ ${idF}: ${exampleValue(entity, entity.op && entity.op.load, idF, entity.name + '_id')} }` : ''})
 \`\`\`
 
 `)
@@ -106,7 +112,7 @@ const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_
       Content(`#### Example: List
 
 \`\`\`ts
-const ${entity.name}s = await client.${entity.Name}().list()
+const ${eVar}s = await client.${entity.Name}().list()
 \`\`\`
 
 `)
@@ -116,11 +122,11 @@ const ${entity.name}s = await client.${entity.Name}().list()
       Content(`#### Example: Create
 
 \`\`\`ts
-const ${entity.name} = await client.${entity.Name}().create({
+const ${eVar} = await client.${entity.Name}().create({
 `)
       each(fields, (field: any) => {
         if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+          Content(`  ${field.name}: /* ${canonToType(field.type, target.name)} */,
 `)
         }
       })

package/project/.sdk/src/cmp/js/ReadmeExplanation_js.ts

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, packageName } from '@voxgig/sdkgen'
 
 
 const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
@@ -20,7 +20,7 @@ ${model.name}/
 Import the SDK from the package root:
 
 \`\`\`js
-const { ${model.Name}SDK } = require('${model.name}')
+const { ${model.Name}SDK } = require('${packageName(model, target.name)}')
 \`\`\`
 
 `)

package/project/.sdk/src/cmp/js/ReadmeHowto_js.ts

@@ -1,21 +1,59 @@
 
-import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive, envName, entityIdField, entityDataIdField, entityPrimaryOp, opRequestShape, safeVarName } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
+  nom,
 } from '@voxgig/apidef'
 
+import { exampleValue } from './utility_js'
+
 
 const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const { target, ctx$: { model } } = props
 
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {}).find((e: any) => e && e.active !== false) as any
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  const eVar = safeVarName(eName.toLowerCase(), 'js')
+
+  // Drive the test-mode / stateful examples off the entity's PRIMARY op — an op
+  // it actually exposes — never a hardcoded `load` a create-only entity lacks.
+  const primaryOp = exampleEntity ? (entityPrimaryOp(exampleEntity) || 'load') : 'load'
+  const primaryOpDef = exampleEntity && exampleEntity.op && exampleEntity.op[primaryOp]
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  // idF is the MATCH key; dataIdF is the id on the RETURNED record's data type
+  // (guard `.id` reads off a returned record on this, not the match key).
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const dataIdF = exampleEntity ? entityDataIdField(exampleEntity) : null
+
+  const primaryArg = (idPlaceholder: string): string => {
+    if (!exampleEntity) return ''
+    if ('list' === primaryOp) return ''
+    if (isMatchOp) {
+      return idF ? `{ ${idF}: ${exampleValue(exampleEntity, primaryOpDef, idF, idPlaceholder)} }` : ''
+    }
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => it.name !== idF && it.name !== 'id')
+    const required = items.filter((it: any) => !it.optional)
+    const chosen = required.length ? required : items.slice(0, 3)
+    const pairs = chosen.map((it: any) =>
+      `${it.name}: ${exampleValue(exampleEntity, primaryOpDef, it.name, 'example_' + it.name)}`)
+    return `{ ${pairs.join(', ')} }`
+  }
+  const testCallArg = primaryArg('test01')
+  const stateCallArg = primaryArg('example')
+  const stateDataLine = dataIdF
+    ? `console.log(data.${dataIdF})`
+    : `console.log(data)`
+
   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>` : ''
+  const apikeyEnvLine = authActive ? `\n${envName(model)}_APIKEY=<your-key>` : ''
 
   Content(`### Make a direct HTTP request
 
@@ -28,6 +66,9 @@ const result = await client.direct({
   params: { id: 'example' },
 })
 
+if (result instanceof Error) {
+  throw result
+}
 if (result.ok) {
   console.log(result.status)  // 200
   console.log(result.data)    // response body
@@ -56,9 +97,9 @@ Create a mock client for unit testing — no server required:
 \`\`\`js
 const client = ${model.const.Name}SDK.test()
 
-const result = await client.Planet().load({ id: 'test01' })
-// result.ok === true
-// result.data contains mock response data
+const ${eVar} = await client.${eName}().${primaryOp}(${testCallArg})
+// ${eVar} is a bare entity populated with mock response data
+console.log(${eVar})
 \`\`\`
 
 You can also use the instance method:
@@ -73,14 +114,14 @@ const testClient = client.tester()
 Entity instances remember their last match and data:
 
 \`\`\`js
-const entity = client.Planet()
+const entity = client.${eName}()
 
-// First call sets internal match
-await entity.load({ id: 'example' })
+// First call runs the operation and stores its result
+await entity.${primaryOp}(${stateCallArg})
 
-// Subsequent calls reuse the stored match
+// Subsequent calls reuse the stored state
 const data = entity.data()
-console.log(data.id) // 'example'
+${stateDataLine}
 \`\`\`
 
 ### Add custom middleware
@@ -109,7 +150,7 @@ const client = new ${model.const.Name}SDK({${apikeyExtendField}
 Create a \`.env.local\` file at the project root:
 
 \`\`\`
-${model.NAME}_TEST_LIVE=TRUE${apikeyEnvLine}
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
 \`\`\`
 
 Then run:

package/project/.sdk/src/cmp/js/ReadmeIntro_js.ts

@@ -1,13 +1,51 @@
 
 import { cmp, Content } from '@voxgig/sdkgen'
 
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
   const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
 
   Content(`# ${model.Name} ${target.title} SDK
 
-The ${target.title} SDK for the ${model.Name} API. Provides an entity-oriented interface with full async/await support.
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client with full async/await support.
+
+The API is exposed as capitalised, semantic **Entities** — e.g.
+\`client.${eName}()\` — each with a small set of operations (${opList})
+instead of raw URL paths and query parameters. This keeps the surface
+predictable and low-friction for both humans and AI agents.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
 
 `)
 })

package/project/.sdk/src/cmp/js/ReadmeModel_js.ts

@@ -13,6 +13,43 @@ const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const entityList = each(entity).filter((e: any) => e.active !== false)
 
+  // Model-driven op rows for the shared entity interface: emit a
+  // load/list/create/update/remove row only for operations at least one active
+  // entity actually exposes (a read-only entity has just list+load) — never
+  // document an operation no entity has.
+  const opUnion = new Set<string>()
+  entityList.forEach((e: any) => Object.keys(e.op || {})
+    .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
+  const opRowDefs: Record<string, string> = {
+    load: '| `load` | `load(reqmatch?, ctrl?): Promise<Entity>` | Load a single entity by match criteria. |',
+    list: '| `list` | `list(reqmatch?, ctrl?): Promise<Entity[]>` | List entities matching the criteria. |',
+    create: '| `create` | `create(reqdata?, ctrl?): Promise<Entity>` | Create a new entity. |',
+    update: '| `update` | `update(reqdata?, ctrl?): Promise<Entity>` | Update an existing entity. |',
+    remove: '| `remove` | `remove(reqmatch?, ctrl?): Promise<void>` | Remove an entity. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  // Model-driven return-value bullets: describe only the operations that
+  // actually exist (single-object ops among load/create/update, plus
+  // list/remove) — never document return semantics for a missing op.
+  const singleOps = ['load', 'create', 'update'].filter((o) => opUnion.has(o))
+    .map((o) => '`' + o + '`')
+  const retBullets: string[] = []
+  if (singleOps.length) {
+    const joined = singleOps.length > 1
+      ? singleOps.slice(0, -1).join(', ') + ' and ' + singleOps[singleOps.length - 1]
+      : singleOps[0]
+    retBullets.push(`- ${joined} ${singleOps.length > 1 ? 'resolve' : 'resolves'} to a single entity object.`)
+  }
+  if (opUnion.has('list')) {
+    retBullets.push('- `list` resolves to an **array** of entity objects (iterate it directly;\n  there is no `.data` and no `.ok`).')
+  }
+  if (opUnion.has('remove')) {
+    retBullets.push('- `remove` resolves to `undefined`.')
+  }
+  const returnBullets = retBullets.join('\n')
+
   const apikeyOptionRow = isAuthActive(model)
     ? '| `apikey` | `string` | API key for authentication. |\n'
     : ''
@@ -44,7 +81,8 @@ ${apikeyOptionRow}| \`base\` | \`string\` | Base URL of the API server. |
 `)
 
   each(entityList, (ent: any) => {
-    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
 `)
   })
 
@@ -64,29 +102,23 @@ All entities share the same interface.
 
 | Method | Signature | Description |
 | --- | --- | --- |
-| \`load\` | \`load(reqmatch?, ctrl?): Promise<Result>\` | Load a single entity by match criteria. |
-| \`list\` | \`list(reqmatch?, ctrl?): Promise<Result>\` | List entities matching the criteria. |
-| \`create\` | \`create(reqdata?, ctrl?): Promise<Result>\` | Create a new entity. |
-| \`update\` | \`update(reqdata?, ctrl?): Promise<Result>\` | Update an existing entity. |
-| \`remove\` | \`remove(reqmatch?, ctrl?): Promise<Result>\` | Remove an entity. |
-| \`data\` | \`data(data?): any\` | Get or set entity data. |
-| \`match\` | \`match(match?): any\` | Get or set entity match criteria. |
+${opRows}
+| \`data\` | \`data(data?: Partial<Entity>): Entity\` | Get or set entity data. |
+| \`match\` | \`match(match?: Partial<Entity>): Partial<Entity>\` | Get or set entity match criteria. |
 | \`make\` | \`make(): Entity\` | Create a new instance with the same options. |
 | \`client\` | \`client(): ${model.const.Name}SDK\` | Return the parent SDK client. |
 | \`entopts\` | \`entopts(): object\` | Return a copy of the entity options. |
 
-#### Result shape
+#### Return values
 
-All entity operations return a Result object:
+Entity operations resolve to the entity data directly — there is no
+result envelope:
 
-\`\`\`js
-{
-  ok: true,       // true if the HTTP status is 2xx
-  status: 200,    // HTTP status code
-  headers: {},    // response headers
-  data: {}        // parsed JSON response body
-}
-\`\`\`
+${returnBullets}
+
+On a failed request these methods **throw**, so wrap calls in
+\`try\`/\`catch\` to handle errors. Only \`direct()\` returns the result
+envelope described below.
 
 ### DirectResult shape
 

package/project/.sdk/src/cmp/js/ReadmeOptions_js.ts

@@ -1,12 +1,13 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
 
 
 const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
-  const publishedOptions = each(target.options).filter((option: any) => option.publish)
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
   if (0 === publishedOptions.length) {
     return
   }
@@ -25,7 +26,7 @@ const client = new ${model.Name}SDK({
 
   publishedOptions.map((option: any) => {
     if ('apikey' === option.name) {
-      Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
+      Content(`  ${option.name}: process.env.${envName(model)}_APIKEY,
 `)
     }
     else {