@voxgig/sdkgen 0.35.2 → 0.36.0

package/src/cmp/ReadmeModel.ts

@@ -6,123 +6,92 @@ import {
   getModelPath
 } from '../types'
 
+import { requirePath } from '../utility'
+
 
 const ReadmeModel = cmp(function ReadmeModel(props: any) {
-  const { ctx$: { model } } = props
+  const { target, ctx$ } = props
+  const { model } = ctx$
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
-  const entityList = Object.values(entity).filter((e: any) => e.publish)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
 
   Content(`
-## SDK Structure
+## Reference
 
-This SDK uses an entity-oriented interface rather than exposing API
-endpoint paths directly. Business logic maps directly to business
-entities in your code.
+`)
 
+  // Delegate to target-specific reference summary
+  const ReadmeModel_sdk =
+    requirePath(ctx$, `./cmp/${target.name}/ReadmeModel_${target.name}`, { ignore: true })
+
+  if (ReadmeModel_sdk) {
+    ReadmeModel_sdk['ReadmeModel']({ target })
+  }
+  else {
+    // Fallback: generic reference summary
+    ReadmeModelGeneric({ target, model, entityList })
+  }
+})
 
-### Client
 
-Create a client instance using the constructor or the static \`test\` method:
+const ReadmeModelGeneric = cmp(function ReadmeModelGeneric(props: any) {
+  const { target, model, entityList } = props
 
-\`\`\`ts
-// Production client
-const client = new ${model.Name}SDK({ apikey: '...' })
+  Content(`### ${model.Name}SDK
 
-// Test client with mock features
-const testClient = ${model.Name}SDK.test()
-\`\`\`
+#### Constructor
 
+| 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. |
+| \`extend\` | \`array\` | Additional Feature instances to load. |
 
-### Client Methods
+#### Methods
 
-| Method | Description |
-| --- | --- |
+| Method | Returns | Description |
+| --- | --- | --- |
 `)
 
-  each(entityList, (entity: any) => {
-    Content(`| \`${entity.Name}(data?)\` | Create a new \`${entity.Name}\` entity instance. |
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
 `)
   })
 
-  Content(`| \`options()\` | Return a copy of the current SDK options. |
-| \`utility()\` | Return a copy of the SDK utility object. |
-| \`direct(fetchargs)\` | Make a direct HTTP request to any API endpoint. |
-| \`prepare(fetchargs)\` | Prepare a fetch definition without sending the request. |
-| \`tester(testopts?, sdkopts?)\` | Create a test client instance. |
+  Content(`| \`options()\` | \`object\` | Deep copy of current SDK options. |
+| \`utility()\` | \`Utility\` | Copy of the SDK utility object. |
+| \`prepare(fetchargs?)\` | \`FetchDef\` | Build an HTTP request definition without sending it. |
+| \`direct(fetchargs?)\` | \`DirectResult\` | Build and send an HTTP request. |
+| \`tester(testopts?, sdkopts?)\` | \`${model.Name}SDK\` | Create a test-mode client instance. |
+
+#### Static methods
 
+| Method | Returns | Description |
+| --- | --- | --- |
+| \`${model.Name}SDK.test(testopts?, sdkopts?)\` | \`${model.Name}SDK\` | Create a test-mode client. |
 
-### Entity Methods
+### Entity interface
 
-Each entity instance provides the following methods, where available:
+All entities share the same interface.
 
 | Method | Description |
 | --- | --- |
-| \`data(data?)\` | Get or set the entity data. Returns the current data. |
-| \`match(match?)\` | Get or set the entity match criteria. Returns the current match. |
-| \`load(match)\` | Load a single entity by match criteria. |
-| \`list(match)\` | List entities matching the criteria. Returns an array. |
-| \`create(data)\` | Create a new entity with the given data. |
-| \`update(data)\` | Update an existing entity with the given data. |
-| \`remove(match)\` | Remove the entity matching the criteria. |
-| \`make()\` | Create a new entity instance with the same options. |
-| \`client()\` | Return the parent client instance. |
+| \`load(reqmatch?, ctrl?)\` | Load a single entity by match criteria. |
+| \`list(reqmatch?, ctrl?)\` | List entities matching the criteria. |
+| \`create(reqdata?, ctrl?)\` | Create a new entity. |
+| \`update(reqdata?, ctrl?)\` | Update an existing entity. |
+| \`remove(reqmatch?, ctrl?)\` | Remove an entity. |
+| \`data(data?)\` | Get or set entity data. |
+| \`match(match?)\` | Get or set entity match criteria. |
+| \`make()\` | Create a new instance with the same options. |
+| \`client()\` | Return the parent SDK client. |
 | \`entopts()\` | Return a copy of the entity options. |
 
-
-### Direct API Access
-
-The \`direct\` method allows you to call any API endpoint without
-using the entity interface:
-
-\`\`\`ts
-const result = await client.direct({
-  path: '/api/v1/resource/{id}',
-  method: 'GET',
-  params: { id: 'abc123' },
-  query: { fields: 'name,status' },
-  headers: { 'X-Custom': 'value' },
-  body: { key: 'value' },
-})
-\`\`\`
-
-The result object has the following shape:
-
-\`\`\`ts
-{
-  ok: boolean,     // true if status is 2xx
-  status: number,  // HTTP status code
-  headers: object, // Response headers
-  data: any,       // Parsed JSON response body
-}
-\`\`\`
-
-Use the \`prepare\` method to build the fetch definition without
-sending the request:
-
-\`\`\`ts
-const fetchdef = await client.prepare({
-  path: '/api/v1/resource',
-  method: 'POST',
-  body: { name: 'example' },
-})
-
-// fetchdef contains: { url, method, headers, body }
-\`\`\`
-
-
-### Testing
-
-Create a test client using the static \`test\` method. The test
-client activates the test feature, which provides mock responses:
-
-\`\`\`ts
-const client = ${model.Name}SDK.test()
-\`\`\`
-
 `)
-
-
 })
 
 

package/src/cmp/ReadmeOptions.ts

@@ -6,6 +6,8 @@ const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
   const { target } = props
   const { model } = props.ctx$
 
+  const isGo = target.name === 'go'
+
   const publishedOptions = each(target.options)
     .filter((option: any) => option.publish)
 
@@ -19,25 +21,52 @@ const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
 
 Pass options when creating a client instance:
 
-\`\`\`ts
+`)
+
+  if (isGo) {
+    Content(`\`\`\`go
+client := sdk.New${model.const.Name}SDK(map[string]any{
+`)
+
+    publishedOptions.map((option: any) => {
+      if ('apikey' === option.name) {
+        Content(`    "${option.name}": os.Getenv("${model.NAME}_APIKEY"),
+`)
+      }
+      else {
+        Content(`    // "${option.name}": ${option.kind === 'string' ? '"..."' : '...'},
+`)
+      }
+    })
+
+    Content(`})
+\`\`\`
+
+`)
+  }
+  else {
+    Content(`\`\`\`ts
 const client = new ${model.Name}SDK({
 `)
 
-  publishedOptions.map((option: any) => {
-    if ('apikey' === option.name) {
-      Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
+    publishedOptions.map((option: any) => {
+      if ('apikey' === option.name) {
+        Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
 `)
-    }
-    else {
-      Content(`  // ${option.name}: ${option.kind === 'string' ? "'...'" : '...'},
+      }
+      else {
+        Content(`  // ${option.name}: ${option.kind === 'string' ? "'...'" : '...'},
 `)
-    }
-  })
+      }
+    })
 
-  Content(`})
+    Content(`})
 \`\`\`
 
-| Option | Type | Description |
+`)
+  }
+
+  Content(`| Option | Type | Description |
 | --- | --- | --- |
 `)
 

package/src/cmp/ReadmeQuick.ts

@@ -8,7 +8,10 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   const { target, ctx$ } = props
 
   Content(`
-## Quick Start
+## Tutorial: your first API call
+
+This tutorial walks through creating a client, listing entities, and
+loading a specific record.
 
 `)