@voxgig/sdkgen 0.36.0 → 0.37.0

package/bin/voxgig-sdkgen

@@ -8,7 +8,7 @@ const { Gubu, Fault, One } = require('gubu')
 
 const { SdkGen } = require('../dist/sdkgen.js')
 
-const VERSION = '0.36.0'
+const VERSION = '0.37.0'
 const KONSOLE = console
 
 

package/dist/cmp/Main.js

@@ -6,18 +6,6 @@ const utility_1 = require("../utility");
 const Main = (0, jostraca_1.cmp)(function Main(props) {
     const { target, ctx$ } = props;
     const { model, stdrep, log } = ctx$;
-    const copyOpts = {
-        // This folder is relative to the .sdk folder in the project, as that is where
-        // the sdk is generated from.
-        from: 'tm/' + target.name,
-        replace: {
-            ...stdrep,
-        }
-    };
-    if (false === target.srcfeature) {
-        copyOpts.exclude = [/src\//];
-    }
-    (0, jostraca_1.Copy)(copyOpts);
     const Main_sdk = (0, utility_1.requirePath)(ctx$, `cmp/${target.name}/Main_${target.name}`);
     Main_sdk['Main']({ model, target, stdrep });
     log.info({ point: 'generate-main', target, note: 'target:' + target.name });

package/dist/cmp/Main.js.map

@@ -1 +1 @@
-{"version":3,"file":"Main.js","sourceRoot":"","sources":["../../src/cmp/Main.ts"],"names":[],"mappings":";;;AACA,uCAA2C;AAE3C,wCAAwC;AAOxC,MAAM,IAAI,GAAG,IAAA,cAAG,EAAC,SAAS,IAAI,CAAC,KAAU;IACvC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IAC9B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;IAEnC,MAAM,QAAQ,GAAQ;QACpB,8EAA8E;QAC9E,6BAA6B;QAC7B,IAAI,EAAE,KAAK,GAAG,MAAM,CAAC,IAAI;QACzB,OAAO,EAAE;YACP,GAAG,MAAM;SACV;KACF,CAAA;IAED,IAAI,KAAK,KAAK,MAAM,CAAC,UAAU,EAAE,CAAC;QAChC,QAAQ,CAAC,OAAO,GAAG,CAAC,OAAO,CAAC,CAAA;IAC9B,CAAC;IAED,IAAA,eAAI,EAAC,QAAQ,CAAC,CAAA;IAEd,MAAM,QAAQ,GAAG,IAAA,qBAAW,EAAC,IAAI,EAAE,OAAO,MAAM,CAAC,IAAI,SAAS,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IAE5E,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAE3C,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;AAC7E,CAAC,CAAC,CAAA;AAIA,oBAAI"}
+{"version":3,"file":"Main.js","sourceRoot":"","sources":["../../src/cmp/Main.ts"],"names":[],"mappings":";;;AACA,uCAAqC;AAErC,wCAAwC;AAOxC,MAAM,IAAI,GAAG,IAAA,cAAG,EAAC,SAAS,IAAI,CAAC,KAAU;IACvC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAA;IAC9B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;IAEnC,MAAM,QAAQ,GAAG,IAAA,qBAAW,EAAC,IAAI,EAAE,OAAO,MAAM,CAAC,IAAI,SAAS,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;IAE5E,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAA;IAE3C,GAAG,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,CAAA;AAC7E,CAAC,CAAC,CAAA;AAIA,oBAAI"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxgig/sdkgen",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "main": "dist/sdkgen.js",
   "type": "commonjs",
   "types": "dist/sdkgen.d.ts",

package/project/.sdk/src/cmp/go/Config_go.ts

@@ -36,8 +36,12 @@ const Config = cmp(async function Config(props: any) {
   const feature = getModelPath(model, `main.${KIT}.feature`)
 
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
-  const authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`)
-  const baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`)
+
+  let authPrefix = ''
+  try { authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`) } catch (_e) { }
+
+  let baseUrl = ''
+  try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }
 
   // Config is now in core/ package
   File({ name: 'config.' + target.ext }, () => {

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

@@ -0,0 +1,34 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp,
+  File, Folder, Fragment,
+} from '@voxgig/sdkgen'
+
+
+
+const EntityBase = cmp(async function EntityBase(props: any) {
+
+  // Needs type: target object
+  const { target } = props
+  const { model } = props.ctx$
+
+  File({ name: model.const.Name + 'EntityBase.' + target.name }, () => {
+
+    Fragment(
+      {
+        from:
+          Path.normalize(__dirname + '/../../../src/cmp/js/fragment/EntityBase.fragment.js'),
+
+        replace: {
+          ...props.ctx$.stdrep,
+        }
+      })
+  })
+})
+
+
+export {
+  EntityBase
+}

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

@@ -22,6 +22,7 @@ import { Package } from './Package_js'
 import { Config } from './Config_js'
 import { MainEntity } from './MainEntity_js'
 import { SdkError } from './SdkError_js'
+import { EntityBase } from './EntityBase_js'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -35,6 +36,13 @@ const Main = cmp(async function Main(props: any) {
 
   Package({ target })
 
+  Copy({
+    from: 'tm/' + target.name,
+    replace: {
+      ...props.ctx$.stdrep,
+    }
+  })
+
   Folder({ name: 'src' }, () => {
 
     SdkError({ target })
@@ -88,6 +96,8 @@ if (fres instanceof Promise) { await fres }
 
     Config({ target })
 
+    EntityBase({ target })
+
   })
 })
 

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

@@ -0,0 +1,33 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Module structure
+
+\`\`\`
+${model.name}/
+├── src/
+│   ├── ${model.Name}SDK.js        # Main SDK class
+│   ├── entity/             # Entity implementations
+│   ├── feature/            # Built-in features (Base, Test, Log)
+│   └── utility/            # Utility functions
+└── test/                   # Test suites
+\`\`\`
+
+Import the SDK from the package root:
+
+\`\`\`js
+const { ${model.Name}SDK } = require('${model.name}')
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,123 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`js
+const result = await client.direct({
+  path: '/api/resource/{id}',
+  method: 'GET',
+  params: { id: 'example' },
+})
+
+if (result.ok) {
+  console.log(result.status)  // 200
+  console.log(result.data)    // response body
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`js
+const fetchdef = await client.prepare({
+  path: '/api/resource/{id}',
+  method: 'DELETE',
+  params: { id: 'example' },
+})
+
+// Inspect before sending
+console.log(fetchdef.url)
+console.log(fetchdef.method)
+console.log(fetchdef.headers)
+\`\`\`
+
+### Use test mode
+
+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
+\`\`\`
+
+You can also use the instance method:
+
+\`\`\`js
+const client = new ${model.const.Name}SDK({ apikey: '...' })
+const testClient = client.tester()
+\`\`\`
+
+### Retain entity state across calls
+
+Entity instances remember their last match and data:
+
+\`\`\`js
+const entity = client.Planet()
+
+// First call sets internal match
+await entity.load({ id: 'example' })
+
+// Subsequent calls reuse the stored match
+const data = entity.data()
+console.log(data.id) // 'example'
+\`\`\`
+
+### Add custom middleware
+
+Pass features via the \`extend\` option:
+
+\`\`\`js
+const logger = {
+  hooks: {
+    PreRequest: (ctx) => {
+      console.log('Requesting:', ctx.spec.method, ctx.spec.path)
+    },
+    PreResponse: (ctx) => {
+      console.log('Status:', ctx.out.request?.status)
+    },
+  },
+}
+
+const client = new ${model.const.Name}SDK({
+  apikey: '...',
+  extend: [logger],
+})
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${model.NAME}_TEST_LIVE=TRUE
+${model.NAME}_APIKEY=<your-key>
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd js && npm test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

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

@@ -0,0 +1,152 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeModel = cmp(function ReadmeModel(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  Content(`### ${model.const.Name}SDK
+
+#### Constructor
+
+\`\`\`js
+new ${model.const.Name}SDK(options?)
+\`\`\`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| \`apikey\` | \`string\` | API key for authentication. |
+| \`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 } }\`). |
+| \`extend\` | \`Feature[]\` | Additional feature instances to load. |
+
+#### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| \`options()\` | \`object\` | Deep copy of current SDK options. |
+| \`utility()\` | \`Utility\` | Deep copy of the SDK utility object. |
+| \`prepare(fetchargs?)\` | \`Promise<FetchDef>\` | Build an HTTP request definition without sending it. |
+| \`direct(fetchargs?)\` | \`Promise<DirectResult>\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`| \`tester(testopts?, sdkopts?)\` | \`${model.const.Name}SDK\` | Create a test-mode client instance. |
+
+#### Static methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| \`${model.const.Name}SDK.test(testopts?, sdkopts?)\` | \`${model.const.Name}SDK\` | Create a test-mode client. |
+
+### Entity interface
+
+All entities share the same interface.
+
+#### Methods
+
+| 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. |
+| \`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
+
+All entity operations return a Result object:
+
+\`\`\`js
+{
+  ok: true,       // true if the HTTP status is 2xx
+  status: 200,    // HTTP status code
+  headers: {},    // response headers
+  data: {}        // parsed JSON response body
+}
+\`\`\`
+
+### DirectResult shape
+
+The \`direct()\` method returns:
+
+\`\`\`js
+{
+  ok: true,
+  status: 200,
+  headers: {},
+  data: {}
+}
+\`\`\`
+
+On error, \`ok\` is \`false\` and an \`err\` property contains the error.
+
+### FetchDef shape
+
+The \`prepare()\` method returns:
+
+\`\`\`js
+{
+  url: 'string',
+  method: 'string',
+  headers: {},
+  body: undefined
+}
+\`\`\`
+
+### Entities
+
+`)
+
+  each(entityList, (ent: any) => {
+    const fields = ent.fields || []
+    const opnames = Object.keys(ent.op || {})
+    const ops = ent.op || {}
+    const points = each(ops).map((op: any) =>
+      op.points ? each(op.points) : []
+    ).flat()
+    const path = points.length > 0 ? (points[0] as any).orig || '' : ''
+
+    Content(`#### ${ent.Name}
+
+| Field | Description |
+| --- | --- |
+`)
+    each(fields, (field: any) => {
+      Content(`| \`${field.name}\` | ${field.short || ''} |
+`)
+    })
+
+    Content(`
+Operations: ${opnames.join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

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

@@ -0,0 +1,25 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**JavaScript:**
+\`\`\`js
+const result = await client.direct({
+  path: '/api/resource/{id}',
+  method: 'GET',
+  params: { id: 'example' },
+})
+console.log(result.data)
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

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

@@ -0,0 +1,65 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  Content(`\`\`\`js
+const { ${model.const.Name}SDK } = require('${target.module.name}')
+
+const client = new ${model.const.Name}SDK({
+  apikey: process.env.${model.NAME}_APIKEY,
+})
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`// List all ${eName.toLowerCase()}s
+const ${eName.toLowerCase()}s = await client.${eName}().list()
+`)
+    }
+
+    // Find a nested entity for a more interesting example
+    const nestedEntity = Object.values(entity).find((e: any) =>
+      e.active !== false && e.ancestors && e.ancestors.length > 0
+    ) as any
+
+    if (nestedEntity && opnames.includes('load')) {
+      const neName = nom(nestedEntity, 'Name')
+      const parentFields = (nestedEntity.fields || [])
+        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
+      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
+
+      Content(`
+// Load a specific ${neName.toLowerCase()}
+const ${neName.toLowerCase()} = await client.${neName}().load({
+  ${parentParam}: 'example',
+  id: 'example_id',
+})
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

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

@@ -0,0 +1,36 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  Content(`\`\`\`js
+const client = ${model.const.Name}SDK.test()
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    Content(`const result = await client.${eName}().load({ id: 'test01' })
+// result.ok === true, result.data contains mock data
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

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

@@ -1,6 +1,7 @@
 
 import {
   nom,
+  depluralize,
 } from '@voxgig/apidef'
 
 
@@ -11,6 +12,7 @@ import {
   Fragment,
   Slot,
   cmp,
+  snakify,
 } from '@voxgig/sdkgen'
 
 
@@ -121,20 +123,20 @@ function directSetup(mockres) {
 
 function generateDirectLoad(model: any, entity: any) {
   const loadOp = entity.op.load
-  const loadPoint = loadOp.points[0]
+  const loadPoint = loadOp?.points?.[0]
 
   if (null == loadPoint) {
     return
   }
 
-  const loadPath = (loadPoint.parts || []).join('/')
   const loadParams = loadPoint.args?.params || []
+  const loadPath = normalizePathParams(loadPoint.parts || [], loadParams, loadPoint.rename?.param)
 
   // Get list info for live mode bootstrapping
   const listOp = entity.op.list
   const listPoint = listOp?.points?.[0]
-  const listPath = listPoint ? (listPoint.parts || []).join('/') : ''
   const listParams = listPoint?.args?.params || []
+  const listPath = listPoint ? normalizePathParams(listPoint.parts || [], listParams, listPoint.rename?.param) : ''
   const hasList = null != listPoint
 
   // Ancestor params (not 'id') for live mode
@@ -218,14 +220,14 @@ ${paramAsserts}    }
 
 function generateDirectList(model: any, entity: any) {
   const listOp = entity.op.list
-  const listPoint = listOp.points[0]
+  const listPoint = listOp?.points?.[0]
 
   if (null == listPoint) {
     return
   }
 
-  const listPath = (listPoint.parts || []).join('/')
   const listParams = listPoint.args?.params || []
+  const listPath = normalizePathParams(listPoint.parts || [], listParams, listPoint.rename?.param)
 
   // Build live params
   const liveParams = listParams.map((p: any) => {
@@ -283,6 +285,52 @@ ${paramAsserts}    }
 }
 
 
+// Replace raw OpenAPI parameter names in path parts with model parameter names.
+// Path parts may have e.g. {subBreed} while model params use sub_breed.
+// When a rename mapping exists (e.g. closureId -> id), path parts contain the
+// renamed form {id} but params still use the original name closure_id.
+// The rename mapping is used to reverse-lookup the original param name.
+function normalizePathParams(
+  parts: string[],
+  params: any[],
+  rename?: Record<string, string>
+): string {
+  return parts.map((part: string) => {
+    // Replace each {paramName} occurrence within the part.
+    // Handles both simple parts like "{id}" and compound parts like
+    // "{outputFields}.{format}" that contain multiple parameters.
+    return part.replace(/\{([^}]+)\}/g, (match: string, rawName: string) => {
+      const snaked = snakify(rawName)
+      const depluralized = depluralize(snaked)
+      const param = params.find((p: any) =>
+        p.orig === snaked || p.name === snaked ||
+        p.orig === depluralized || p.name === depluralized
+      )
+      if (param) return '{' + param.name + '}'
+
+      // Reverse-lookup through rename mapping: if rawName is a renamed value
+      // (e.g. "id"), find the original camelCase key (e.g. "closureId"),
+      // snakify+depluralize it (e.g. "closure_id"), and match against params.
+      if (rename) {
+        for (const [origCamel, renamedTo] of Object.entries(rename)) {
+          if (renamedTo === rawName) {
+            const origSnaked = snakify(origCamel)
+            const origDepluralized = depluralize(origSnaked)
+            const renamedParam = params.find(
+              (p: any) => p.orig === origSnaked || p.name === origSnaked ||
+                p.orig === origDepluralized || p.name === origDepluralized
+            )
+            if (renamedParam) return '{' + renamedParam.name + '}'
+          }
+        }
+      }
+
+      return match
+    })
+  }).join('/')
+}
+
+
 export {
   TestDirect
 }