@voxgig/sdkgen 0.32.2 → 0.33.0

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

@@ -1,68 +1,105 @@
 
-const { Config } = require('./Config')
+const { inspect } = require('node:util')
+
+const { config } = require('./Config')
 const { Utility } = require('./utility/Utility')
 
 
-class NameSDK {
-  #options
-  #features
-  #utility = Utility
-  
+const { BaseFeature } = require('./feature/base/BaseFeature')
+
+
+const stdutil = new Utility()
+
+
+class ProjectNameSDK {
+  _mode = 'live'
+  _options
+  _utility = new Utility()
+  _features
+  _rootctx
+
   constructor(options) {
 
-    this.#options = this.#utility.makeOptions({
+    this._rootctx = this._utility.makeContext({
       client: this,
-      utility: this.#utility,
-      config: Config,
+      utility: this._utility,
+      config,
       options,
+      shared: new WeakMap()
     })
 
-    // #FeatureOptions
+    this._options = this._utility.makeOptions(this._rootctx)
 
-    this.#features = {
-      // #BuildFeature
+    const struct = this._utility.struct
+    const getpath = struct.getpath
+    const items = struct.items
+
+    if (true === getpath(this._options.feature, 'test.active')) {
+      this._mode = 'test'
     }
 
-    // #PostConstruct-Hook
-  }
+    this._rootctx.options = this._options
 
+    this._features = []
 
-  options() {
-    return { ...this.#options }
-  }
+    const featureAdd = this._utility.featureAdd
+    const featureInit = this._utility.featureInit
 
-  features() {
-    return { ...this.#features }
-  }
+    items(this._options.feature, (fitem) => {
+      const fname = fitem[0]
+      const fopts = fitem[1]
+      if (fopts.active) {
+        featureAdd(this._rootctx, this._rootctx.config.makeFeature(fname))
+      }
+    })
 
-  utility() {
-    return { ...this.#utility }
+    if (null != this._options.extend) {
+      for (let f of this._options.extend) {
+        featureAdd(this._rootctx, f)
+      }
+    }
+
+    for (let f of this._features) {
+      featureInit(this._rootctx, f)
+    }
+
+    const featureHook = this._utility.featureHook
+    featureHook(this._rootctx, 'PostConstruct')
   }
 
 
-  static test(opts) {
-    return new NameSDK({
-      // #TestOptions
-      ...(opts || {})
-    })
+  options() {
+    return this._utility.struct.clone(this._options)
   }
 
-  test(opts) {
-    return new NameSDK({
-      // #TestOptions
-      ...(opts || this.#options || {})
-    })
+
+  utility() {
+    return this._utility.struct.clone(this._utility)
   }
 
-  
+
   async prepare(fetchargs) {
-    const utility = this.#utility
-    const { headers, auth, fullurl } = utility
+    const utility = this._utility
+    const struct = utility.struct
+    const clone = struct.clone
+
+    const {
+      makeContext,
+      makeFetchDef,
+      prepareHeaders,
+      prepareAuth,
+    } = utility
 
     fetchargs = fetchargs || {}
 
-    const options = this.options()
+    let ctx = makeContext({
+      opname: 'prepare',
+      ctrl: fetchargs.ctrl || {},
+    }, this._rootctx)
+
+    const options = this._options
 
+    // Build spec directly from SDK options + user-provided fetch args.
     const spec = {
       base: options.base,
       prefix: options.prefix,
@@ -71,12 +108,13 @@ class NameSDK {
       method: fetchargs.method || 'GET',
       params: fetchargs.params || {},
       query: fetchargs.query || {},
-      headers: headers({ client: this, utility }),
+      headers: prepareHeaders(ctx),
       body: fetchargs.body,
       step: 'start',
-      alias: {},
     }
 
+    ctx.spec = spec
+
     // Merge user-provided headers over SDK defaults.
     if (fetchargs.headers) {
       const uheaders = fetchargs.headers
@@ -85,51 +123,48 @@ class NameSDK {
       }
     }
 
-    // Apply SDK auth.
-    const ctx = { client: this, op: { params: [] }, spec, utility }
-    auth(ctx)
-
-    // Build URL.
-    const url = fullurl(ctx)
-
-    const fetchdef = {
-      url,
-      method: spec.method,
-      headers: { ...spec.headers },
+    // Apply SDK auth (apikey, auth prefix, etc.)
+    const authResult = prepareAuth(ctx)
+    if (authResult instanceof Error) {
+      return authResult
     }
 
-    if (null != spec.body) {
-      fetchdef.body =
-        'object' === typeof spec.body ? JSON.stringify(spec.body) : spec.body
-    }
-
-    return fetchdef
+    return makeFetchDef(ctx)
   }
 
 
   async direct(fetchargs) {
+    const utility = this._utility
+    const fetcher = utility.fetcher
+    const makeContext = utility.makeContext
+
     const fetchdef = await this.prepare(fetchargs)
     if (fetchdef instanceof Error) {
       return fetchdef
     }
 
-    const options = this.options()
-    const fetch = options.system.fetch
+    let ctx = makeContext({
+      opname: 'direct',
+      ctrl: (fetchargs || {}).ctrl || {},
+    }, this._rootctx)
 
     try {
-      const response = await fetch(fetchdef.url, fetchdef)
+      const fetched = await fetcher(ctx, fetchdef.url, fetchdef)
 
-      if (null == response) {
-        return { ok: false, err: new Error('response: undefined') }
+      if (null == fetched) {
+        return { ok: false, err: ctx.error('direct_no_response', 'response: undefined') }
+      }
+      else if (fetched instanceof Error) {
+        return { ok: false, err: fetched }
       }
 
-      const status = response.status
-      const json = 'function' === typeof response.json ? await response.json() : response.json
+      const status = fetched.status
+      const json = 'function' === typeof fetched.json ? await fetched.json() : fetched.json
 
       return {
         ok: status >= 200 && status < 300,
         status,
-        headers: response.headers,
+        headers: fetched.headers,
         data: json,
       }
     }
@@ -140,12 +175,62 @@ class NameSDK {
 
 
   // <[SLOT]>
+
+
+  static test(testoptsarg, sdkoptsarg) {
+    const struct = stdutil.struct
+    const setpath = struct.setpath
+    const getdef = struct.getdef
+    const clone = struct.clone
+    const setprop = struct.setprop
+
+    const sdkopts = getdef(clone(sdkoptsarg), {})
+    const testopts = getdef(clone(testoptsarg), {})
+    setprop(testopts, 'active', true)
+    setpath(sdkopts, 'feature.test', testopts)
+
+    const testsdk = new ProjectNameSDK(sdkopts)
+    testsdk._mode = 'test'
+
+    return testsdk
+  }
+
+
+  tester(testopts, sdkopts) {
+    return ProjectNameSDK.test(testopts, sdkopts)
+  }
+
+
+  toJSON() {
+    return { name: 'ProjectName' }
+  }
+
+  toString() {
+    return 'ProjectName ' + this._utility.struct.jsonify(this.toJSON())
+  }
+
+  [inspect.custom]() {
+    return this.toString()
+  }
+
+}
+
+
+class ProjectNameEntity {
+
 }
 
 
-const SDK = NameSDK
+const SDK = ProjectNameSDK
+
 
 module.exports = {
-  NameSDK,
+  stdutil,
+
+  BaseFeature,
+  ProjectNameEntity,
+
+  ProjectNameSDK,
   SDK,
 }
+

package/project/.sdk/src/cmp/js/fragment/SdkError.fragment.js

@@ -0,0 +1,22 @@
+
+const { Context } = require('./Context')
+
+
+class ProjectNameError extends Error {
+
+  isProjectNameError = true
+
+  sdk = 'ProjectName'
+
+  constructor(code, msg, ctx) {
+    super(msg)
+    this.code = code
+    this.ctx = ctx
+  }
+
+}
+
+module.exports = {
+  ProjectNameError
+}
+

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

@@ -0,0 +1,64 @@
+
+import * as Path from 'node:path'
+
+
+import {
+  clone,
+  walk,
+} from '@voxgig/struct'
+
+
+function projectPath(suffix?: string): string {
+  return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
+}
+
+
+function formatJSONSrc(jsonsrc: string) {
+  return jsonsrc
+    .replace(/([{:\[,])/g, '$1 ')
+    .replace(/([}\]])/g, ' $1')
+}
+
+
+function formatJson(obj: any, flags?: { line?: boolean, margin?: number }): string {
+  const marginSize = flags?.margin ?? 0
+  const marginStr = ' '.repeat(marginSize)
+
+  let json: string
+
+  if (flags?.line) {
+    // One line with spaces for clarity
+    json = JSON.stringify(obj)
+      .replace(/([{:\[,])/g, '$1 ')
+      .replace(/([}\]])/g, ' $1')
+  }
+  else {
+    // Pretty printed with 2-space indentation
+    json = JSON.stringify(obj, null, 2)
+  }
+
+  // Add margin to the left of every line
+  if (marginSize > 0) {
+    json = json.split('\n').map(line => marginStr + line).join('\n')
+  }
+
+  return json
+}
+
+
+function clean(o: any) {
+  return walk(clone(o), (k: any, v: any, p: any) => {
+    if (null != k && k.endsWith('$')) {
+      delete p[k]
+    }
+    return v
+  })
+}
+
+
+export {
+  clean,
+  formatJSONSrc,
+  formatJson,
+  projectPath,
+}

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

@@ -1,20 +1,117 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
 
 
 const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$: { model } } = props
 
-  Content('```ts')
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Find the first published entity for examples
+  const exampleEntity = Object.values(entity).find((e: any) => e.publish) as any
+
   Content(`
-const { ${model.const.Name}SDK } = require('${target.module.name}')
+### Create a Client
+
+\`\`\`ts
+import { ${model.const.Name}SDK } from '${target.module.name}'
 
-const client = ${model.const.Name}SDK.make({
+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('load')) {
+      Content(`
+### Load a ${eName}
+
+\`\`\`ts
+const ${exampleEntity.name} = await client.${eName}().load({ id: '${exampleEntity.name}_id' })
+console.log(${exampleEntity.name})
+\`\`\`
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`
+### List ${eName} Records
+
+\`\`\`ts
+const ${exampleEntity.name}s = await client.${eName}().list()
+console.log(${exampleEntity.name}s)
+\`\`\`
+`)
+    }
+
+    if (opnames.includes('create')) {
+      Content(`
+### Create a ${eName}
+
+\`\`\`ts
+const created = await client.${eName}().create({
+  // Provide ${exampleEntity.name} fields
+})
+console.log(created)
+\`\`\`
+`)
+    }
+
+    if (opnames.includes('update')) {
+      Content(`
+### Update a ${eName}
+
+\`\`\`ts
+const updated = await client.${eName}().update({
+  id: '${exampleEntity.name}_id',
+  // Fields to update
+})
+console.log(updated)
+\`\`\`
+`)
+    }
+
+    if (opnames.includes('remove')) {
+      Content(`
+### Remove a ${eName}
+
+\`\`\`ts
+await client.${eName}().remove({ id: '${exampleEntity.name}_id' })
+\`\`\`
+`)
+    }
+  }
+
+
+  Content(`
+### Direct API Access
+
+Use \`client.direct()\` to call any API endpoint directly:
+
+\`\`\`ts
+const result = await client.direct({
+  path: '/custom/endpoint/{id}',
+  method: 'GET',
+  params: { id: 'abc123' },
+})
+
+if (result.ok) {
+  console.log(result.data)
+}
+\`\`\`
 
 `)
-  Content('```')
 
 })
 

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

@@ -29,8 +29,8 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   const ff = projectPath('src/cmp/ts/fragment/')
 
-  const PROJECTNAME = model.Name.toUpperCase()
-  const entidEnvVar = `${PROJECTNAME}_TEST_${entity.Name.toUpperCase()}_ENTID`
+  const PROJECTNAME = model.Name.toUpperCase().replace(/[^A-Z_]/g, '_')
+  const entidEnvVar = `${PROJECTNAME}_TEST_${entity.Name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID`
 
   const opnames = Object.keys(entity.op)
   const hasLoad = opnames.includes('load')

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

@@ -48,6 +48,9 @@ const TestEntity = cmp(function TestEntity(props: any) {
   const target = props.target
   const entity = props.entity
 
+  const PROJENVNAME = nom(model.const, 'NAME').replace(/[^A-Z_]/g, '_')
+  const ENTENVNAME = nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')
+
   // TODO: should be a utility function
   const ff = projectPath('src/cmp/ts/fragment/')
 
@@ -118,18 +121,18 @@ function basicSetup(extra?: any) {
     })
 
   const env = envOverride({
-    '${nom(model.const, 'NAME')}_TEST_${nom(entity, 'NAME')}_ENTID': idmap,
-    '${nom(model.const, 'NAME')}_TEST_LIVE': 'FALSE',
-    '${nom(model.const, 'NAME')}_TEST_EXPLAIN': 'FALSE',
-    '${nom(model.const, 'NAME')}_APIKEY': 'NONE',
+    '${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID': idmap,
+    '${PROJENVNAME}_TEST_LIVE': 'FALSE',
+    '${PROJENVNAME}_TEST_EXPLAIN': 'FALSE',
+    '${PROJENVNAME}_APIKEY': 'NONE',
   })
 
-  idmap = env['${nom(model.const, 'NAME')}_TEST_${nom(entity, 'NAME')}_ENTID']
+  idmap = env['${PROJENVNAME}_TEST_${ENTENVNAME}_ENTID']
 
-  if ('TRUE' === env.${model.NAME}_TEST_LIVE) {
+  if ('TRUE' === env.${PROJENVNAME}_TEST_LIVE) {
     client = new ${model.Name}SDK(merge([
       {
-        apikey: env.${nom(model.const, 'NAME')}_APIKEY,
+        apikey: env.${PROJENVNAME}_APIKEY,
       },
       extra
     ]))
@@ -142,7 +145,7 @@ function basicSetup(extra?: any) {
     client,
     struct,
     data: entityData,
-    explain: 'TRUE' === env.${nom(model.const, 'NAME')}_TEST_EXPLAIN,
+    explain: 'TRUE' === env.${PROJENVNAME}_TEST_EXPLAIN,
     now: Date.now(),
   }
 

package/src/cmp/Readme.ts

@@ -8,6 +8,7 @@ import { ReadmeQuick } from './ReadmeQuick'
 import { ReadmeModel } from './ReadmeModel'
 import { ReadmeOptions } from './ReadmeOptions'
 import { ReadmeEntity } from './ReadmeEntity'
+import { ReadmeRef } from './ReadmeRef'
 
 
 const Readme = cmp(function Readme(props: any) {
@@ -26,7 +27,18 @@ const Readme = cmp(function Readme(props: any) {
     ReadmeModel({ target })
     ReadmeOptions({ target })
     ReadmeEntity({ target })
+
+    Content(`
+## Reference
+
+See [REFERENCE.md](REFERENCE.md) for complete API reference
+documentation including all method signatures, entity field schemas,
+and detailed usage examples.
+`)
   })
+
+  // Generate separate reference documentation
+  ReadmeRef({ target })
 })