@voxgig/sdkgen 0.43.0 → 0.45.0

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

@@ -0,0 +1,58 @@
+
+import { cmp, each, Content } 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)
+  if (0 === publishedOptions.length) {
+    return
+  }
+
+  Content(`
+
+## Options
+
+Pass options when creating a client instance:
+
+`)
+
+  Content(`\`\`\`ts
+const client = new ${model.Name}SDK({
+`)
+
+  publishedOptions.map((option: any) => {
+    if ('apikey' === option.name) {
+      Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
+`)
+    }
+    else {
+      Content(`  // ${option.name}: ${option.kind === 'string' ? "'...'" : '...'},
+`)
+    }
+  })
+
+  Content(`})
+\`\`\`
+
+`)
+
+  Content(`| Option | Type | Description |
+| --- | --- | --- |
+`)
+
+  publishedOptions.map((option: any) => {
+    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
+`)
+  })
+
+  Content(`
+`)
+})
+
+
+export {
+  ReadmeOptions
+}

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -21,14 +21,16 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
     e.active !== false && e.ancestors && e.ancestors.length > 0
   ) as any
 
+  const apikeyArg = isAuthActive(model)
+    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
+    : ''
+
   Content(`### 1. Create a client
 
 \`\`\`ts
 import { ${model.const.Name}SDK } from '${target.module.name}'
 
-const client = new ${model.const.Name}SDK({
-  apikey: process.env.${model.NAME}_APIKEY,
-})
+const client = new ${model.const.Name}SDK({${apikeyArg}})
 \`\`\`
 
 `)

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

@@ -0,0 +1,384 @@
+
+import { cmp, each, Content, File, isAuthActive } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
+  load: {
+    sig: 'load(match: object, ctrl?: object)',
+    returns: 'Promise<object>',
+    desc: 'Load a single entity matching the given criteria.',
+  },
+  list: {
+    sig: 'list(match: object, ctrl?: object)',
+    returns: 'Promise<object[]>',
+    desc: 'List entities matching the given criteria. Returns an array.',
+  },
+  create: {
+    sig: 'create(data: object, ctrl?: object)',
+    returns: 'Promise<object>',
+    desc: 'Create a new entity with the given data.',
+  },
+  update: {
+    sig: 'update(data: object, ctrl?: object)',
+    returns: 'Promise<object>',
+    desc: 'Update an existing entity. The data must include the entity `id`.',
+  },
+  remove: {
+    sig: 'remove(match: object, ctrl?: object)',
+    returns: 'Promise<void>',
+    desc: 'Remove the entity matching the given criteria.',
+  },
+}
+
+
+const ReadmeRef = cmp(function ReadmeRef(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  const publishedEntities = each(entity).filter((e: any) => e.active !== false)
+
+
+  File({ name: 'REFERENCE.md' }, () => {
+
+    Content(`# ${model.Name} ${target.title} SDK Reference
+
+Complete API reference for the ${model.Name} ${target.title} SDK.
+
+
+## ${model.Name}SDK
+
+### Constructor
+
+`)
+
+    Content(`\`\`\`ts
+new ${model.Name}SDK(options?: object)
+\`\`\`
+
+Create a new SDK client instance.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`options\` | \`object\` | SDK configuration options. |
+| \`options.apikey\` | \`string\` | API key for authentication. |
+| \`options.base\` | \`string\` | Base URL for API requests. |
+| \`options.prefix\` | \`string\` | URL prefix appended after base. |
+| \`options.suffix\` | \`string\` | URL suffix appended after path. |
+| \`options.headers\` | \`object\` | Custom headers for all requests. |
+| \`options.feature\` | \`object\` | Feature configuration. |
+| \`options.system\` | \`object\` | System overrides (e.g. custom fetch). |
+
+`)
+
+
+    Content(`
+### Static Methods
+
+`)
+
+    Content(`#### \`${model.Name}SDK.test(testopts?, sdkopts?)\`
+
+Create a test client with mock features active.
+
+\`\`\`ts
+const client = ${model.Name}SDK.test()
+\`\`\`
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`testopts\` | \`object\` | Test feature options. |
+| \`sdkopts\` | \`object\` | Additional SDK options merged with test defaults. |
+
+**Returns:** \`${model.Name}SDK\` instance in test mode.
+
+`)
+
+
+    Content(`
+### Instance Methods
+
+`)
+
+
+    // Entity factory methods
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`${ent.Name}(data?: object)\`
+
+Create a new \`${ent.Name}\` entity instance.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`data\` | \`object\` | Initial entity data. |
+
+**Returns:** \`${ent.Name}Entity\` instance.
+
+`)
+    })
+
+
+    Content(`#### \`options()\`
+
+Return a deep copy of the current SDK options.
+
+**Returns:** \`object\`
+
+#### \`utility()\`
+
+Return a copy of the SDK utility object.
+
+**Returns:** \`object\`
+
+#### \`direct(fetchargs?: object)\`
+
+Make a direct HTTP request to any API endpoint.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`fetchargs.path\` | \`string\` | URL path with optional \`{param}\` placeholders. |
+| \`fetchargs.method\` | \`string\` | HTTP method (default: \`GET\`). |
+| \`fetchargs.params\` | \`object\` | Path parameter values for \`{param}\` substitution. |
+| \`fetchargs.query\` | \`object\` | Query string parameters. |
+| \`fetchargs.headers\` | \`object\` | Request headers (merged with defaults). |
+| \`fetchargs.body\` | \`any\` | Request body (objects are JSON-serialized). |
+| \`fetchargs.ctrl\` | \`object\` | Control options (e.g. \`{ explain: true }\`). |
+
+**Returns:** \`Promise<{ ok, status, headers, data } | Error>\`
+
+#### \`prepare(fetchargs?: object)\`
+
+Prepare a fetch definition without sending the request. Accepts the
+same parameters as \`direct()\`.
+
+**Returns:** \`Promise<{ url, method, headers, body } | Error>\`
+
+#### \`tester(testopts?, sdkopts?)\`
+
+Alias for \`${model.Name}SDK.test()\`.
+
+**Returns:** \`${model.Name}SDK\` instance in test mode.
+
+`)
+
+
+    // Entity reference sections
+    publishedEntities.map((ent: any) => {
+      const opnames = Object.keys(ent.op || {})
+      const fields = ent.fields || []
+
+      Content(`
+---
+
+## ${ent.Name}Entity
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`ts
+const ${ent.name} = client.${ent.Name}()
+\`\`\`
+
+`)
+
+
+      // Field schema
+      if (fields.length > 0) {
+        Content(`### Fields
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+`)
+        each(fields, (field: any) => {
+          const req = field.req ? 'Yes' : 'No'
+          const desc = field.short || ''
+          Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${req} | ${desc} |
+`)
+        })
+
+        Content(`
+`)
+
+        // Field operations breakdown
+        const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
+        if (hasFieldOps) {
+          Content(`### Field Usage by Operation
+
+| Field | load | list | create | update | remove |
+| --- | --- | --- | --- | --- | --- |
+`)
+          each(fields, (field: any) => {
+            const fops = field.op || {}
+            const cols = ['load', 'list', 'create', 'update', 'remove'].map((op: string) => {
+              if (!opnames.includes(op)) return '-'
+              const fop = fops[op]
+              if (null == fop) return '-'
+              if (fop.active === false) return '-'
+              return 'Yes'
+            })
+            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+`)
+          })
+
+          Content(`
+`)
+        }
+      }
+
+
+      // Operation details
+      if (opnames.length > 0) {
+        Content(`### Operations
+
+`)
+
+        opnames.map((opname: string) => {
+          const info = OP_SIGNATURES[opname]
+          if (!info) return
+
+          Content(`#### \`${info.sig}\`
+
+${info.desc}
+
+`)
+
+          // Show example
+          if ('load' === opname || 'remove' === opname) {
+            Content(`\`\`\`ts
+const result = await client.${ent.Name}().${opname}({ id: '${ent.name}_id' })
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`ts
+const results = await client.${ent.Name}().${opname}()
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            Content(`\`\`\`ts
+const result = await client.${ent.Name}().create({
+`)
+            each(fields, (field: any) => {
+              if ('id' !== field.name && field.req) {
+                Content(`  ${field.name}: /* ${field.type || 'value'} */,
+`)
+              }
+            })
+            Content(`})
+\`\`\`
+
+`)
+          }
+          else if ('update' === opname) {
+            Content(`\`\`\`ts
+const result = await client.${ent.Name}().update({
+  id: '${ent.name}_id',
+  // Fields to update
+})
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common methods
+      Content(`### Common Methods
+
+#### \`data(data?: object)\`
+
+Get or set the entity data. When called with data, sets the entity's
+internal data and returns the current data. When called without
+arguments, returns a copy of the current data.
+
+#### \`match(match?: object)\`
+
+Get or set the entity match criteria. Works the same as \`data()\`.
+
+#### \`make()\`
+
+Create a new \`${ent.Name}Entity\` instance with the same client and
+options.
+
+#### \`client()\`
+
+Return the parent \`${model.Name}SDK\` instance.
+
+#### \`entopts()\`
+
+Return a copy of the entity options.
+
+`)
+    })
+
+
+    // Features section
+    const activeFeatures = each(feature).filter((f: any) => f.active)
+    if (activeFeatures.length > 0) {
+      Content(`
+---
+
+## Features
+
+| Feature | Version | Description |
+| --- | --- | --- |
+`)
+
+      activeFeatures.map((f: any) => {
+        Content(`| \`${f.name}\` | ${f.version || '0.0.1'} | ${f.title || ''} |
+`)
+      })
+
+      Content(`
+
+Features are activated via the \`feature\` option:
+
+`)
+
+      Content(`\`\`\`ts
+const client = new ${model.Name}SDK({
+  feature: {
+`)
+      activeFeatures.map((f: any) => {
+        Content(`    ${f.name}: { active: true },
+`)
+      })
+      Content(`  }
+})
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+
+
+export {
+  ReadmeRef
+}

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

@@ -1,5 +1,5 @@
 
-import { cmp, Content } from '@voxgig/sdkgen'
+import { cmp, Content, isAuthActive } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,12 +14,14 @@ const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
   const entity = getModelPath(model, `main.${KIT}.entity`)
   const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
+  const apikeyArg = isAuthActive(model)
+    ? `\n  apikey: process.env.${model.NAME}_APIKEY,\n`
+    : ''
+
   Content(`\`\`\`ts
 import { ${model.const.Name}SDK } from '${target.module.name}'
 
-const client = new ${model.const.Name}SDK({
-  apikey: process.env.${model.NAME}_APIKEY,
-})
+const client = new ${model.const.Name}SDK({${apikeyArg}})
 
 `)
 

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

@@ -1,5 +1,8 @@
 
 import {
+  Model,
+  ModelEntity,
+  ModelPoint,
   nom,
   depluralize,
 } from '@voxgig/apidef'
@@ -13,6 +16,7 @@ import {
   Slot,
   cmp,
   snakify,
+  isAuthActive,
 } from '@voxgig/sdkgen'
 
 
@@ -23,16 +27,25 @@ import {
 
 const TestDirect = cmp(function TestDirect(props: any) {
   const ctx$ = props.ctx$
-  const model = ctx$.model
+  const model: Model = ctx$.model
   const stdrep = ctx$.stdrep
 
   const target = props.target
-  const entity = props.entity
+  const entity: ModelEntity = props.entity
 
   const ff = projectPath('src/cmp/ts/fragment/')
 
-  const PROJECTNAME = model.Name.toUpperCase().replace(/[^A-Z_]/g, '_')
-  const entidEnvVar = `${PROJECTNAME}_TEST_${entity.Name.toUpperCase().replace(/[^A-Z_]/g, '_')}_ENTID`
+  const PROJECTNAME = nom(model, 'Name').toUpperCase().replace(/[^A-Z_]/g, '_')
+  const entidEnvVar = `${PROJECTNAME}_TEST_${nom(entity, 'NAME').replace(/[^A-Z_]/g, '_')}_ENTID`
+
+  const authActive = isAuthActive(model)
+  const apikeyEnvEntry = authActive
+    ? `\n    '${PROJECTNAME}_APIKEY': 'NONE',`
+    : ''
+  const apikeyLiveField = authActive
+    ? `
+      apikey: env.${PROJECTNAME}_APIKEY,`
+    : ''
 
   const opnames = Object.keys(entity.op)
   const hasLoad = opnames.includes('load')
@@ -64,15 +77,13 @@ function directSetup(mockres?: any) {
 
   const env = envOverride({
     '${entidEnvVar}': {},
-    '${PROJECTNAME}_TEST_LIVE': 'FALSE',
-    '${PROJECTNAME}_APIKEY': 'NONE',
+    '${PROJECTNAME}_TEST_LIVE': 'FALSE',${apikeyEnvEntry}
   })
 
   const live = 'TRUE' === env.${PROJECTNAME}_TEST_LIVE
 
   if (live) {
-    const client = new ${nom(model.const, 'Name')}SDK({
-      apikey: env.${PROJECTNAME}_APIKEY,
+    const client = new ${nom(model.const, 'Name')}SDK({${apikeyLiveField}
     })
 
     let idmap: any = env['${entidEnvVar}']
@@ -121,9 +132,9 @@ function directSetup(mockres?: any) {
 })
 
 
-function generateDirectLoad(model: any, entity: any) {
+function generateDirectLoad(model: Model, entity: ModelEntity) {
   const loadOp = entity.op.load
-  const loadPoint = loadOp?.points?.[0]
+  const loadPoint: ModelPoint | undefined = loadOp?.points?.[0]
 
   if (null == loadPoint) {
     return
@@ -132,6 +143,19 @@ function generateDirectLoad(model: any, entity: any) {
   const loadParams = loadPoint.args?.params || []
   const loadPath = normalizePathParams(loadPoint.parts || [], loadParams, loadPoint.rename?.param)
 
+  // Required query params that the spec advertises an example value for.
+  // Live mode needs these on the request or the API returns 4xx; mock mode
+  // ignores them. Optional query params (e.g. `app`, `version`) are skipped
+  // even when they have examples — only the strictly required ones are
+  // necessary to satisfy the contract.
+  const loadQuery = loadPoint.args?.query || []
+  const liveQueryEntries = loadQuery
+    .filter((q: any) => q.reqd && undefined !== q.example && null !== q.example)
+  const hasLiveQuery = liveQueryEntries.length > 0
+  const liveQueryLines = liveQueryEntries
+    .map((q: any) => `      query.${q.name} = ${JSON.stringify(q.example)}`)
+    .join('\n')
+
   // Get list info for live mode bootstrapping
   const listOp = entity.op.list
   const listPoint = listOp?.points?.[0]
@@ -159,6 +183,10 @@ function generateDirectLoad(model: any, entity: any) {
     return { name: p.name, key }
   })
 
+  // Prefix the live block with required-query setup so it applies to both
+  // the list-bootstrapped and the no-list cases.
+  const liveQueryPrefix = liveQueryLines ? liveQueryLines + '\n' : ''
+
   let liveParamsBlock = ''
   if (hasList) {
     const listParamLines = liveListParams.map((lp: any) =>
@@ -167,7 +195,7 @@ function generateDirectLoad(model: any, entity: any) {
       `      params.${lp.name} = setup.idmap['${lp.key}']`).join('\n')
 
     liveParamsBlock = `    if (setup.live) {
-      const listResult: any = await client.direct({
+${liveQueryPrefix}      const listResult: any = await client.direct({
         path: '${listPath}',
         method: 'GET',
         params: {
@@ -184,10 +212,14 @@ ${ancestorParamLines}
     } else {
 ${loadParams.map((p: any, i: number) => `      params.${p.name} = 'direct0${i + 1}'`).join('\n')}
     }`
-  } else {
-    liveParamsBlock = `    if (!setup.live) {
+  } else if (hasLiveQuery || loadParams.length > 0) {
+    liveParamsBlock = `    if (setup.live) {
+${liveQueryPrefix.replace(/\n$/, '')}
+    } else {
 ${loadParams.map((p: any, i: number) => `      params.${p.name} = 'direct0${i + 1}'`).join('\n')}
     }`
+  } else {
+    liveParamsBlock = ''
   }
 
   Content(`
@@ -196,12 +228,14 @@ ${loadParams.map((p: any, i: number) => `      params.${p.name} = 'direct0${i +
     const { client, calls } = setup
 
     const params: any = {}
+    const query: any = {}
 ${liveParamsBlock}
 
     const result: any = await client.direct({
       path: '${loadPath}',
       method: 'GET',
       params,
+      query,
     })
 
     assert(result.ok === true)
@@ -218,9 +252,9 @@ ${paramAsserts}    }
 }
 
 
-function generateDirectList(model: any, entity: any) {
+function generateDirectList(model: Model, entity: ModelEntity) {
   const listOp = entity.op.list
-  const listPoint = listOp?.points?.[0]
+  const listPoint: ModelPoint | undefined = listOp?.points?.[0]
 
   if (null == listPoint) {
     return
@@ -229,6 +263,14 @@ function generateDirectList(model: any, entity: any) {
   const listParams = listPoint.args?.params || []
   const listPath = normalizePathParams(listPoint.parts || [], listParams, listPoint.rename?.param)
 
+  // Required query params with spec-provided examples — needed to satisfy
+  // the API contract in live mode (see generateDirectLoad for rationale).
+  const listQuery = listPoint.args?.query || []
+  const liveQueryLines = listQuery
+    .filter((q: any) => q.reqd && undefined !== q.example && null !== q.example)
+    .map((q: any) => `      query.${q.name} = ${JSON.stringify(q.example)}`)
+    .join('\n')
+
   // Build live params
   const liveParams = listParams.map((p: any) => {
     const key = p.name === 'id'
@@ -241,21 +283,26 @@ function generateDirectList(model: any, entity: any) {
     '      assert(calls[0].url.includes(\'direct0' + (i + 1) + '\'))\n').join('')
 
   let paramsBlock = ''
-  if (listParams.length > 0) {
-    const liveLines = liveParams.map((lp: any) =>
-      `      params.${lp.name} = setup.idmap['${lp.key}']`).join('\n')
+  if (listParams.length > 0 || liveQueryLines) {
+    const liveLines = [
+      liveQueryLines,
+      liveParams.map((lp: any) =>
+        `      params.${lp.name} = setup.idmap['${lp.key}']`).join('\n'),
+    ].filter(Boolean).join('\n')
     const mockLines = listParams.map((p: any, i: number) =>
       `      params.${p.name} = 'direct0${i + 1}'`).join('\n')
 
     paramsBlock = `    const params: any = {}
+    const query: any = {}
     if (setup.live) {
 ${liveLines}
-    } else {
+    }${mockLines ? ` else {
 ${mockLines}
-    }
+    }` : ''}
 `
   } else {
     paramsBlock = `    const params: any = {}
+    const query: any = {}
 `
   }
 
@@ -269,6 +316,7 @@ ${paramsBlock}
       path: '${listPath}',
       method: 'GET',
       params,
+      query,
     })
 
     assert(result.ok === true)