@voxgig/sdkgen 0.32.2 → 0.32.3

package/src/cmp/ReadmeEntity.ts

@@ -7,33 +7,129 @@ import {
 } from '../types'
 
 
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load: { method: 'load(match)', desc: 'Load a single entity by match criteria.' },
+  list: { method: 'list(match)', desc: 'List entities matching the criteria.' },
+  create: { method: 'create(data)', desc: 'Create a new entity with the given data.' },
+  update: { method: 'update(data)', desc: 'Update an existing entity.' },
+  remove: { method: 'remove(match)', desc: 'Remove the matching entity.' },
+}
+
+
 const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   const { ctx$: { model } } = props
 
   const entity = getModelPath(model, `main.${KIT}.entity`)
 
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.publish)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
   Content(`
 
 ## Entities
+
 `)
 
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.field || []
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+
+`)
+
+    // Operations table
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
 
-  each(entity)
-    .filter((entity: any) => entity.publish)
-    .map((entity: any) => {
       Content(`
-### Entity: __${entity.Name}__
+`)
+    }
+
+    // Fields table
+    if (fields.length > 0) {
+      Content(`#### Fields
 
+| Field | Type | Description |
+| --- | --- | --- |
 `)
 
-      each(entity.field, (field: any) => {
-        Content(`
-* __${field.name}__ (${field.type}): ${field.short}
-  
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
 `)
       })
-    })
 
+      Content(`
+`)
+    }
+
+    // Example usage
+    if (opnames.includes('load')) {
+      Content(`#### Example: Load
+
+\`\`\`ts
+const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`ts
+const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      Content(`#### Example: Create
+
+\`\`\`ts
+const ${entity.name} = await client.${entity.Name}().create({
+`)
+      each(fields, (field: any) => {
+        if ('id' !== field.name && field.req) {
+          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+`)
+        }
+      })
+      Content(`})
+\`\`\`
+
+`)
+    }
+
+  })
 
 })
 

package/src/cmp/ReadmeIntro.ts

@@ -1,18 +1,46 @@
 
 import { cmp, Content } from 'jostraca'
 
+import {
+  KIT,
+  getModelPath
+} from '../types'
+
 
 const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
-  const { ctx$: { model } } = props
+  const { target } = props
+  const { model } = props.ctx$
+
+  const desc = model.main.def.desc || ''
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const entityNames = Object.values(entity)
+    .filter((e: any) => e.publish)
+    .map((e: any) => `\`${e.Name}\``)
 
   Content(`
 ## Introduction
 
-${model.main.def.desc}
+${desc}
+`)
+
+  if (entityNames.length > 0) {
+    Content(`
+This SDK provides an entity-oriented interface for the ${model.Name} API.
+The following entities are available: ${entityNames.join(', ')}.
 
 `)
+  }
+
+  Content(`
+### Features
 
+- Entity-based API: work with business objects directly.
+- Type safe: full TypeScript definitions included.
+- Direct HTTP access: call any API endpoint using \`client.direct()\`.
+- Testable: built-in test mode with mock support.
 
+`)
 
 })
 

package/src/cmp/ReadmeModel.ts

@@ -1,44 +1,127 @@
 
-import { cmp, Content } from 'jostraca'
+import { cmp, each, Content } from 'jostraca'
+
+import {
+  KIT,
+  getModelPath
+} from '../types'
 
 
 const ReadmeModel = cmp(function ReadmeModel(props: any) {
   const { ctx$: { model } } = props
 
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = Object.values(entity).filter((e: any) => e.publish)
+
   Content(`
-## Entity Model
+## SDK Structure
+
+This SDK uses an entity-oriented interface rather than exposing API
+endpoint paths directly. Business logic maps directly to business
+entities in your code.
 
-This SDK uses an entity-oriented interface, rather than exposing
-endpoint paths directly.  Business logic can be mapped directly to
-business entities in your code.
 
-The SDK itself allows you to create one or more client instances,
-which can be used concurrently in the same thread. Each client
-instance provides a set of entity methods to create entity
-instances. Each entity instance can likewise operate independently.
+### Client
 
+Create a client instance using the constructor or the static \`test\` method:
 
-### SDK Methods
+\`\`\`ts
+// Production client
+const client = new ${model.Name}SDK({ apikey: '...' })
 
-* \`make(options)\`: Create a new client instance. 
+// Test client with mock features
+const testClient = ${model.Name}SDK.test()
+\`\`\`
 
 
 ### Client Methods
 
-* \`[Entity]()\`: Create a new business entity instance. 
+| Method | Description |
+| --- | --- |
+`)
+
+  each(entityList, (entity: any) => {
+    Content(`| \`${entity.Name}(data?)\` | Create a new \`${entity.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. |
 
 
 ### Entity Methods
 
-* \`data(data?)\`: Set the data properties of the entity, returning the current data.
-* \`load(query)\`: Load matching single entity data into the entity instance.
-* \`save(data?)\`: Save the current entity, optionally setting data.
-* \`list(query)\`: List matching entities, return an array of new entities.
-* \`remove(query)\`: Delete the matching single entity.
+Each entity instance provides the following methods, where available:
+
+| 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. |
+| \`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

@@ -4,21 +4,50 @@ import { cmp, each, Content } from 'jostraca'
 
 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:
+
+\`\`\`ts
+const client = new ${model.Name}SDK({
 `)
 
-  each(target.options)
-    .filter((option: any) => option.publish)
-    .map((option: any) => {
-      Content(`
-* __${option.name} (${option.kind})__: ${option.short}
+  publishedOptions.map((option: any) => {
+    if ('apikey' === option.name) {
+      Content(`  ${option.name}: process.env.${model.NAME}_APIKEY,
+`)
+    }
+    else {
+      Content(`  // ${option.name}: ${option.kind === 'string' ? "'...'" : '...'},
 `)
-    })
+    }
+  })
+
+  Content(`})
+\`\`\`
 
+| Option | Type | Description |
+| --- | --- | --- |
+`)
+
+  publishedOptions.map((option: any) => {
+    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
+`)
+  })
+
+  Content(`
+`)
 
 })