@voxgig/sdkgen 1.2.1 → 1.3.2

package/project/.sdk/src/cmp/go-mcp/fragment/tools.fragment.go

@@ -0,0 +1,114 @@
+// Generated by sdkgen go-mcp target.
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+	sdk "GOMODULE"
+)
+
+// Args is the common argument shape for both tools. `entity` selects
+// the SDK entity to operate on; `query` is the optional reqmatch /
+// reqdata map passed through to the SDK. For load, `query` should be
+// `{"id": <value>}`. For list, omit `query` or pass an empty map.
+type Args struct {
+	Entity string         `json:"entity" jsonschema:"// <[SLOT:entityHelp]>"`
+	Query  map[string]any `json:"query,omitempty" jsonschema:"optional match map e.g. {\"id\":1} for load, omit for list"`
+}
+
+func registerTools(server *mcp.Server, client *sdk.ProjectNameSDK) {
+	mcp.AddTool(server, &mcp.Tool{
+		Name: "// <[SLOT:toolPrefixList]>",
+		Description: "List records from ProjectName. " +
+			"Args: entity (one of the supported SDK entities), query (optional filter map). " +
+			"Returns the first page of records as JSON.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args Args) (*mcp.CallToolResult, any, error) {
+		return runOp(client, "list", args)
+	})
+
+	mcp.AddTool(server, &mcp.Tool{
+		Name: "// <[SLOT:toolPrefixLoad]>",
+		Description: "Load a single record from ProjectName. " +
+			"Args: entity, query ({\"id\":N} required). Returns the record as JSON.",
+	}, func(ctx context.Context, req *mcp.CallToolRequest, args Args) (*mcp.CallToolResult, any, error) {
+		return runOp(client, "load", args)
+	})
+}
+
+func runOp(client *sdk.ProjectNameSDK, op string, args Args) (*mcp.CallToolResult, any, error) {
+	ent, err := entityFor(client, args.Entity)
+	if err != nil {
+		return toolError(err.Error())
+	}
+
+	var result any
+	switch op {
+	case "list":
+		result, err = ent.List(args.Query, nil)
+	case "load":
+		result, err = ent.Load(args.Query, nil)
+	default:
+		return toolError(fmt.Sprintf("unknown op %q", op))
+	}
+	if err != nil {
+		return toolError(err.Error())
+	}
+
+	// SDK returns *Entity wrappers; unwrap each via .Data() to get a
+	// plain map[string]any (or []any of maps for list) suitable for
+	// JSON marshalling.
+	data := extractData(result)
+	body, err := json.MarshalIndent(data, "", "  ")
+	if err != nil {
+		return toolError(fmt.Sprintf("marshal: %v", err))
+	}
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: string(body)},
+		},
+	}, data, nil
+}
+
+// entityFor dispatches on the lowercase entity name. The generator
+// emits one `case "<name>":` per entity defined in the SDK model.
+func entityFor(client *sdk.ProjectNameSDK, name string) (sdk.ProjectNameEntity, error) {
+	switch strings.ToLower(name) {
+	// <[SLOT:entityCases]>
+	}
+	return nil, fmt.Errorf("unknown entity %q", name)
+}
+
+// extractData walks an SDK result and replaces any sdk.Entity wrapper
+// with its underlying record (via .Data()).
+func extractData(x any) any {
+	switch v := x.(type) {
+	case sdk.Entity:
+		return extractData(v.Data())
+	case []any:
+		out := make([]any, len(v))
+		for i, e := range v {
+			out[i] = extractData(e)
+		}
+		return out
+	case map[string]any:
+		out := make(map[string]any, len(v))
+		for k, vv := range v {
+			out[k] = extractData(vv)
+		}
+		return out
+	}
+	return x
+}
+
+func toolError(msg string) (*mcp.CallToolResult, any, error) {
+	return &mcp.CallToolResult{
+		IsError: true,
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: msg},
+		},
+	}, nil, nil
+}

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

@@ -11,6 +11,7 @@ import {
   each,
   indent,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -42,12 +43,8 @@ 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 */ }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
   const authBlock = authActive
     ? `auth: {
       prefix: '${authPrefix}',

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, opRequestShape, 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} |
 `)
       })
 
@@ -93,10 +99,22 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `{ ${loadItems.map((it: any) =>
+          `${it.name}: ${exampleValue(entity, entity.op && entity.op.load, it.name,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
       Content(`#### Example: Load
 
 \`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+const ${eVar} = await client.${entity.Name}().load(${loadArg})
 \`\`\`
 
 `)
@@ -106,23 +124,28 @@ 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()
 \`\`\`
 
 `)
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id (the /* type */
+      // placeholders mark the block as an illustration); an all-optional
+      // create renders an empty — still valid — literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       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'} */,
+      createItems.map((it: any) => {
+        Content(`  ${it.name}: /* ${canonToType(it.type, target.name)} */,
 `)
-        }
       })
       Content(`})
 \`\`\`

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).
 
 `)
 })