@voxgig/sdkgen 0.35.2 → 0.37.0

package/src/cmp/ReadmeTop.ts

@@ -0,0 +1,213 @@
+
+import { cmp, each, names, Content, File } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
+import { requirePath } from '../utility'
+
+
+const ReadmeTop = cmp(function ReadmeTop(props: any) {
+  const { ctx$ } = props
+  const { model } = ctx$
+
+  const desc = model.main.def.desc || ''
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const target = getModelPath(model, `main.${KIT}.target`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  // Ensure names are computed on entities and features
+  each(entity, (ent: any) => { if (!ent.Name) names(ent, ent.name) })
+  each(feature, (feat: any) => { if (!feat.Name) names(feat, feat.name) })
+
+  const activeEntities = each(entity).filter((e: any) => e.active !== false)
+  const activeTargets = each(target)
+
+  File({ name: 'README.md' }, () => {
+
+    Content(`# ${model.Name} SDK
+
+${desc}
+
+`)
+
+    // Target links
+    if (activeTargets.length > 0) {
+      Content(`Available for `)
+      const links = activeTargets.map((t: any) =>
+        `[${t.title}](${t.name}/)`
+      )
+      Content(`${links.join(' and ')}.
+
+`)
+    }
+
+
+    // Entities section
+    if (activeEntities.length > 0) {
+      Content(`
+## Entities
+
+The API exposes ${activeEntities.length === 1 ? 'one entity' : activeEntities.length + ' entities'}:
+
+| Entity | Description | API path |
+| --- | --- | --- |
+`)
+
+      activeEntities.map((ent: any) => {
+        const entdesc = ent.short || ''
+        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}** | ${entdesc} | \`${path}\` |
+`)
+      })
+
+      Content(`
+Each entity supports the following operations where available: **load**, **list**, **create**,
+**update**, and **remove**.
+
+`)
+    }
+
+
+    // Architecture section
+    Content(`
+## Architecture
+
+### Entity-operation model
+
+Every SDK call follows the same pipeline:
+
+1. **Point** — resolve the API endpoint from the operation definition.
+2. **Spec** — build the HTTP specification (URL, method, headers, body).
+3. **Request** — send the HTTP request.
+4. **Response** — receive and parse the response.
+5. **Result** — extract the result data for the caller.
+
+At each stage a feature hook fires (e.g. \`PrePoint\`, \`PreSpec\`,
+\`PreRequest\`), allowing features to inspect or modify the pipeline.
+
+### Features
+
+Features are hook-based middleware that extend SDK behaviour.
+
+| Feature | Purpose |
+| --- | --- |
+`)
+
+    each(feature, (feat: any) => {
+      if (!feat.active) return
+      const purpose = feat.title || feat.Name || feat.name
+      Content(`| **${feat.Name || feat.name}Feature** | ${purpose} |
+`)
+    })
+
+    Content(`
+You can add custom features by passing them in the \`extend\` option at
+construction time.
+
+### Direct and Prepare
+
+For endpoints not covered by the entity model, use the low-level methods:
+
+- **\`direct(fetchargs)\`** — build and send an HTTP request in one step.
+- **\`prepare(fetchargs)\`** — build the request without sending it.
+
+Both accept a map with \`path\`, \`method\`, \`params\`, \`query\`, \`headers\`,
+and \`body\`.
+
+`)
+
+
+    // Quick start section with examples from each target
+    Content(`
+## Quick start
+
+`)
+
+    activeTargets.map((tgt: any) => {
+      const ReadmeTopQuick_sdk =
+        requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopQuick_${tgt.name}`, { ignore: true })
+
+      if (ReadmeTopQuick_sdk) {
+        Content(`### ${tgt.title}
+
+`)
+        ReadmeTopQuick_sdk['ReadmeTopQuick']({ target: tgt })
+        Content(`
+`)
+      }
+    })
+
+
+    // Testing section
+    Content(`
+## Testing
+
+Both SDKs provide a test mode that replaces the HTTP transport with an
+in-memory mock, so tests run without a network connection.
+
+`)
+
+    activeTargets.map((tgt: any) => {
+      const ReadmeTopTest_sdk =
+        requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopTest_${tgt.name}`, { ignore: true })
+
+      if (ReadmeTopTest_sdk) {
+        Content(`### ${tgt.title}
+
+`)
+        ReadmeTopTest_sdk['ReadmeTopTest']({ target: tgt })
+        Content(`
+`)
+      }
+    })
+
+
+    // How-to guides
+    Content(`
+## How-to guides
+
+### Make a direct API call
+
+When the entity interface does not cover an endpoint, use \`direct\`:
+
+`)
+
+    activeTargets.map((tgt: any) => {
+      const ReadmeTopHowto_sdk =
+        requirePath(ctx$, `./cmp/${tgt.name}/ReadmeTopHowto_${tgt.name}`, { ignore: true })
+
+      if (ReadmeTopHowto_sdk) {
+        ReadmeTopHowto_sdk['ReadmeTopHowto']({ target: tgt })
+      }
+    })
+
+
+    // Language-specific links
+    Content(`
+## Language-specific documentation
+
+`)
+
+    activeTargets.map((tgt: any) => {
+      Content(`- [${tgt.title} SDK](${tgt.name}/README.md)
+`)
+    })
+
+    Content(`
+`)
+  })
+})
+
+
+export {
+  ReadmeTop
+}

package/src/sdkgen.ts

@@ -25,10 +25,16 @@ import { Main } from './cmp/Main'
 import { Entity } from './cmp/Entity'
 import { Feature } from './cmp/Feature'
 import { Readme } from './cmp/Readme'
+import { ReadmeTop } from './cmp/ReadmeTop'
 import { Test } from './cmp/Test'
 import { ReadmeInstall } from './cmp/ReadmeInstall'
+import { ReadmeQuick } from './cmp/ReadmeQuick'
+import { ReadmeIntro } from './cmp/ReadmeIntro'
+import { ReadmeModel } from './cmp/ReadmeModel'
 import { ReadmeOptions } from './cmp/ReadmeOptions'
 import { ReadmeEntity } from './cmp/ReadmeEntity'
+import { ReadmeHowto } from './cmp/ReadmeHowto'
+import { ReadmeExplanation } from './cmp/ReadmeExplanation'
 import { ReadmeRef } from './cmp/ReadmeRef'
 import { FeatureHook } from './cmp/FeatureHook'
 
@@ -356,9 +362,15 @@ export {
   Feature,
   Test,
   Readme,
+  ReadmeTop,
   ReadmeInstall,
+  ReadmeQuick,
+  ReadmeIntro,
+  ReadmeModel,
   ReadmeOptions,
   ReadmeEntity,
+  ReadmeHowto,
+  ReadmeExplanation,
   ReadmeRef,
   FeatureHook,
 

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

@@ -1,78 +0,0 @@
-
-import { names, getx, each, cmp, File, Content } from '@voxgig/sdkgen'
-
-
-const Quick = cmp(function Quick(props: any) {
-  const { target } = props
-  const { model, meta: { spec } } = props.ctx$
-
-  // get quick entity from target config
-
-  let ent: any
-  let entmap = getx(spec.config.guideModel, 'guide entity?test:quick:active=true')
-
-  if (entmap) {
-    ent = Object.values(entmap)[0]
-    ent.name = Object.keys(entmap)[0]
-  }
-
-  ent = ent || { name: 'Entity' }
-  names(ent, ent.name)
-
-  // TODO: selected features should be active by default!
-
-  const featureOptions = each(model.main.kit.feature)
-    .filter((f: any) => f.active)
-    .reduce((a: any, f: any) => a + `\n    ${f.name}: { active: true },`, '')
-
-
-  File({ name: 'quick.' + target.name }, () => {
-
-    Content(`
-require('dotenv').config({ path: ['../../.env.local']})
-
-const { ${model.const.Name}SDK } = require('../')
-
-run()
-
-async function run() {
-  const client = new ${model.const.Name}SDK({
-    apikey: process.env.${model.NAME}_APIKEY,
-    ${featureOptions}
-  })
-
-`)
-
-    if (ent.test?.quick.create) {
-      Content(`
-  out = await client.${ent.Name}().create(${JSON.stringify(ent.test?.quick.create)})
-  console.log('${ent.Name}.load', out)
-`)
-    }
-
-    if (ent.test?.quick.load) {
-      Content(`
-  out = await client.${ent.Name}().load(${JSON.stringify(ent.test?.quick.load)})
-  console.log('${ent.Name}.load', out)
-`)
-    }
-
-    if (ent.test?.quick.list) {
-      Content(`
-  out = await client.${ent.Name}().list(${JSON.stringify(ent.test?.quick.list)})
-  console.log('${ent.Name}.list', out)
-`)
-    }
-
-    Content(`
-}
-`)
-
-  })
-})
-
-
-export {
-  Quick
-}
-

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

@@ -1,13 +0,0 @@
-
-import { cmp, camelify, Content } from '@voxgig/sdkgen'
-
-
-const TestAcceptEntity = cmp(function TestEntity(props: any) {
-  const { entity } = props
-
-})
-
-
-export {
-  TestAcceptEntity
-}

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

@@ -1,18 +0,0 @@
-
-import { cmp, each, File, Content } from '@voxgig/sdkgen'
-
-
-import { TestAcceptEntity } from './TestAcceptEntity_js'
-
-
-const TestAccept = cmp(function TestMain(props: any) {
-  const { target } = props
-  const { model } = props.ctx$
-
-})
-
-
-export {
-  TestAccept
-}
-

package/project/.sdk/tm/go/test/exists_test.go

@@ -1,16 +0,0 @@
-package sdktest
-
-import (
-	"testing"
-
-	sdk "GOMODULE"
-)
-
-func TestExists(t *testing.T) {
-	t.Run("test-mode", func(t *testing.T) {
-		testsdk := sdk.TestSDK(nil, nil)
-		if testsdk == nil {
-			t.Fatal("expected non-nil SDK")
-		}
-	})
-}

package/project/.sdk/tm/js/src/utility/AuthUtility.js

@@ -1,21 +0,0 @@
-
-function auth(ctx) {
-  const { client, spec } = ctx
-  const { headers } = spec
-  
-  let options = client.options()
-
-  if(null != options.apikey && '' !== options.apikey) {
-    headers['authorization'] = 'Bearer '+options.apikey
-  }
-  else {
-    delete headers['authorization']
-  }
-  
-  return spec
-}
-
-
-module.exports = {
-  auth
-}

package/project/.sdk/tm/js/src/utility/BodyUtility.js

@@ -1,29 +0,0 @@
-
-
-function body(ctx) {
-  const { op, result, utility } = ctx
-  const { struct, error } = utility
-  const { isfunc, transform } = struct
-  
-  let body = undefined
-
-  if('req' === op.kind) {
-    try {
-      const reqform = op.reqform
-      body = isfunc(reqform) ? reqform(ctx) : transform(op, op.reqform)
-
-      if(op.check.nobody && null == body) {
-        return error(ctx, new Error('Request body is empty.'))
-      }
-    }
-    catch (err) {
-      return error(ctx, err)
-    }
-  }
-
-  return body
-}
-
-module.exports = {
-  body
-}

package/project/.sdk/tm/js/src/utility/ErrorUtility.js

@@ -1,33 +0,0 @@
-
-function error(ctx, err) {
-
-  ctx = ctx || {}
-  const op = ctx.op || {}
-  op.name = op.name || 'unknown operation'
-
-  const result = ctx.result = ctx.result || {}
-  result.ok = false
-  
-  const reserr = result.err
-  
-  err = undefined === err ? reserr : err
-  err = err || new Error('unknown error')
-  
-  const errmsg = err.message || 'unknown error'
-  const msg = 'StatuspageSDK: '+op.name+': '+errmsg
-  err.message = msg
-  // result.err = {...err}
-  
-  const spec = ctx.spec || {}
-
-  err.result = ctx.result
-  err.spec = spec
-
-  // TODO: model option to return instead
-  throw err
-}
-
-
-module.exports = {
-  error
-}

package/project/.sdk/tm/js/src/utility/FindparamUtility.js

@@ -1,31 +0,0 @@
-
-/* Find value of a match parameter, possibly using an alias.
- *
- * The match parameter may have an alias key. For example, the parameter `foo_id` may be
- * aliased to `id` in the entity data.
- *
- * This function returns `undefined` rather than failing.
- */
-function findparam(ctx, key) {
-  let { op, spec } = ctx
-  let { match, data, alias } = op
-
-  let source = ('res' === op.kind ? match : data) || {}
-  let val = source[key]
-
-  if(null == val) {
-    alias = alias || {}
-    let akey = alias[key]
-    val = source[akey]
-
-    spec = spec || {}
-    spec.alias = spec.alias || {}
-    spec.alias[akey] = key
-  }
-
-  return val
-}
-
-module.exports = {
-  findparam
-}

package/project/.sdk/tm/js/src/utility/FullurlUtility.js

@@ -1,39 +0,0 @@
-
-
-function fullurl(ctx) {
-  const { op, spec, utility: { struct, findparam } } = ctx
-  const { escurl, escre, joinurl } = struct
-  
-  let url = joinurl([spec.base, spec.prefix, spec.path, spec.suffix])
-
-  const params = spec.params
-  for(let key of op.params) {
-    if(null == params[key]) {
-      params[key] = findparam(ctx, key)
-    }
-  }
-  
-  for(let key in params) {
-    const val = params[key]
-    if(null != val) { 
-      url = url.replace(RegExp('{'+escre(key)+'}'), escurl(val))
-    }
-  }
-
-  let qsep = '?'
-  for(let key in spec.query) {
-    if(null == spec.alias[key]) {
-      const val = spec.query[key]
-      if(null != val) { 
-        url += qsep + escurl(key) + '=' + escurl(val)
-        qsep = '&'
-      }
-    }
-  }
-
-  return url
-}
-
-module.exports = {
-  fullurl
-}

package/project/.sdk/tm/js/src/utility/HeadersUtility.js

@@ -1,13 +0,0 @@
-
-function headers(ctx) {
-  const out = {}
-
-  // TODO: should come from options via config
-  out['content-type'] = 'application/json'
-  
-  return out
-}
-
-module.exports = {
-  headers
-}

package/project/.sdk/tm/js/src/utility/JoinurlUtility.js

@@ -1,14 +0,0 @@
-
-// TODO: MOVE TO STRUCT
-function joinurl(...s) {
-  return s
-    .filter(s=>null!=s&&''!==s)
-    .map((s,i)=> 0===i ? s.replace(/([^\/])\/+/,'$1/').replace(/\/+$/,'') :
-        s.replace(/([^\/])\/+/,'$1/').replace(/^\/+/,'').replace(/\/+$/,''))
-    .filter(s=>''!==s)
-    .join('/')
-}
-
-module.exports = {
-  joinurl
-}

package/project/.sdk/tm/js/src/utility/OperatorUtility.js

@@ -1,44 +0,0 @@
-
-
-const OPKIND = {
-  create: 'req',
-  update: 'req',
-  remove: 'req',
-  load: 'res',
-  list: 'res',
-}
-
-
-// Ensure standard operation definition.
-function operator(ctx) {
-  const { op, utility } = ctx
-  const { validate } = utility.struct
-
-  const opspec = {
-
-    // Required.
-    name: '`$STRING`',
-    kind: ['`$ONE`','req','res'],
-    path: '`$STRING`',
-    entity: '`$STRING`',
-    reqform: ['`$ONE`','`$STRING`','`$OBJECT`','`$FUNCTION`'],
-    resform: ['`$ONE`','`$STRING`','`$OBJECT`','`$FUNCTION`'],
-
-    // Optional.
-    params: ['`$CHILD`', '`$STRING`'],
-    alias: {'`$CHILD`': '`$STRING`' },
-    match: {},
-    data: ['`$ONE`',{}, []],
-    state: {},
-    check: {},
-  }
-
-  ctx.op.kind = OPKIND[op.name]
-  
-  ctx.op = validate(ctx.op, opspec)
-}
-
-
-module.exports = {
-  operator
-}

package/project/.sdk/tm/js/src/utility/OptionsUtility.js

@@ -1,54 +0,0 @@
-
-function options(ctx) {
-  const { options, utility } = ctx
-  
-  let opts = { ...(options||{}) }
-  
-  const customUtils = opts.utility || {}
-  for(let key of Object.keys(customUtils)) {
-    utility[key] = customUtils[key]
-  }
-  
-  const { isempty, merge, validate } = utility.struct
-
-  let config = ctx.config || {}
-  let cfgopts = config.options || {}
-  
-  // Standard SDK option values.
-  const optspec = {
-    apikey: '',
-    base: 'http://localhost:8000',
-    prefix: '',
-    suffix: '',
-    entity: {
-      '`$CHILD`': {
-        '`$OPEN`': true, 
-        active: false,
-        alias: {}
-      }
-    },
-    feature: {
-      '`$CHILD`': {
-        '`$OPEN`': true,
-        active: false, 
-      }
-    },
-    utility: {},
-    system: {},
-  }
-
-  // JavaScript specific option values.
-  optspec.system.fetch = optspec.system.fetch || global.fetch
-
-  opts = merge([{},cfgopts,opts])
-
-  opts = validate(opts, optspec)
-
-  return opts
-}
-
-
-
-module.exports = {
-  options
-}

package/project/.sdk/tm/js/src/utility/ParamsUtility.js

@@ -1,21 +0,0 @@
-
-function params(ctx) {
-  const { op } = ctx
-  let { params, match } = op
-  params = params || []
-  match = match || {}
-  
-  const out = {}
-  for(let key of params) {
-    let val = match[key]
-    if(null!=val) {
-      out[key] = val
-    }
-  }
-
-  return out
-}
-
-module.exports = {
-  params
-}

package/project/.sdk/tm/js/src/utility/QueryUtility.js

@@ -1,21 +0,0 @@
-
-function query(ctx) {
-  const { op } = ctx
-  let { params, match } = op
-  params = params || []
-  match = match || {}
-  
-  const out = {}
-  for(let key of Object.keys(match)) {
-    let val = match[key]
-    if(null!=val && !params.includes(key)) {
-      out[key] = val
-    }
-  }
-
-  return out
-}
-
-module.exports = {
-  query
-}