@voxgig/sdkgen 0.35.2 → 0.37.0

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

@@ -0,0 +1,159 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeModel = cmp(function ReadmeModel(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const entityList = each(entity).filter((e: any) => e.active !== false)
+
+  Content(`### ${model.const.Name}SDK
+
+#### Constructor
+
+\`\`\`ts
+new ${model.const.Name}SDK(options?: {
+  apikey?: string
+  base?: string
+  prefix?: string
+  suffix?: string
+  feature?: Record<string, { active: boolean }>
+  extend?: Feature[]
+})
+\`\`\`
+
+| 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 (e.g. \`{ test: { active: true } }\`). |
+| \`extend\` | \`Feature[]\` | Additional feature instances to load. |
+
+#### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| \`options()\` | \`object\` | Deep copy of current SDK options. |
+| \`utility()\` | \`Utility\` | Deep copy of the SDK utility object. |
+| \`prepare(fetchargs?)\` | \`Promise<FetchDef>\` | Build an HTTP request definition without sending it. |
+| \`direct(fetchargs?)\` | \`Promise<DirectResult>\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`| \`tester(testopts?, sdkopts?)\` | \`${model.const.Name}SDK\` | Create a test-mode client instance. |
+
+#### Static methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| \`${model.const.Name}SDK.test(testopts?, sdkopts?)\` | \`${model.const.Name}SDK\` | Create a test-mode client. |
+
+### Entity interface
+
+All entities share the same interface.
+
+#### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`load\` | \`load(reqmatch?, ctrl?): Promise<Result>\` | Load a single entity by match criteria. |
+| \`list\` | \`list(reqmatch?, ctrl?): Promise<Result>\` | List entities matching the criteria. |
+| \`create\` | \`create(reqdata?, ctrl?): Promise<Result>\` | Create a new entity. |
+| \`update\` | \`update(reqdata?, ctrl?): Promise<Result>\` | Update an existing entity. |
+| \`remove\` | \`remove(reqmatch?, ctrl?): Promise<Result>\` | Remove an entity. |
+| \`data\` | \`data(data?): any\` | Get or set entity data. |
+| \`match\` | \`match(match?): any\` | Get or set entity match criteria. |
+| \`make\` | \`make(): Entity\` | Create a new instance with the same options. |
+| \`client\` | \`client(): ${model.const.Name}SDK\` | Return the parent SDK client. |
+| \`entopts\` | \`entopts(): object\` | Return a copy of the entity options. |
+
+#### Result shape
+
+All entity operations return a Result object:
+
+\`\`\`ts
+{
+  ok: boolean      // true if the HTTP status is 2xx
+  status: number   // HTTP status code
+  headers: object  // response headers
+  data: any        // parsed JSON response body
+}
+\`\`\`
+
+### DirectResult shape
+
+The \`direct()\` method returns:
+
+\`\`\`ts
+{
+  ok: boolean
+  status: number
+  headers: object
+  data: any
+}
+\`\`\`
+
+On error, \`ok\` is \`false\` and an \`err\` property contains the error.
+
+### FetchDef shape
+
+The \`prepare()\` method returns:
+
+\`\`\`ts
+{
+  url: string
+  method: string
+  headers: Record<string, string>
+  body?: any
+}
+\`\`\`
+
+### Entities
+
+`)
+
+  each(entityList, (ent: any) => {
+    const fields = ent.fields || []
+    const opnames = Object.keys(ent.op || {})
+    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}
+
+| Field | Description |
+| --- | --- |
+`)
+    each(fields, (field: any) => {
+      Content(`| \`${field.name}\` | ${field.short || ''} |
+`)
+    })
+
+    Content(`
+Operations: ${opnames.join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

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

@@ -14,10 +14,14 @@ const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
   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
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
 
-  Content(`
-### Create a Client
+  // Find a nested entity if available
+  const nestedEntity = Object.values(entity).find((e: any) =>
+    e.active !== false && e.ancestors && e.ancestors.length > 0
+  ) as any
+
+  Content(`### 1. Create a client
 
 \`\`\`ts
 import { ${model.const.Name}SDK } from '${target.module.name}'
@@ -26,6 +30,7 @@ const client = new ${model.const.Name}SDK({
   apikey: process.env.${model.NAME}_APIKEY,
 })
 \`\`\`
+
 `)
 
 
@@ -33,85 +38,95 @@ const client = new ${model.const.Name}SDK({
     const eName = nom(exampleEntity, 'Name')
     const opnames = Object.keys(exampleEntity.op || {})
 
-    if (opnames.includes('load')) {
-      Content(`
-### Load a ${eName}
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()}s
 
 \`\`\`ts
-const ${exampleEntity.name} = await client.${eName}().load({ id: '${exampleEntity.name}_id' })
-console.log(${exampleEntity.name})
+const result = await client.${eName}().list()
+
+if (result.ok) {
+  for (const item of result.data) {
+    console.log(item.id, item.name)
+  }
+}
 \`\`\`
+
 `)
     }
 
-    if (opnames.includes('list')) {
-      Content(`
-### List ${eName} Records
+    if (nestedEntity) {
+      const neName = nom(nestedEntity, 'Name')
+      const parentFields = (nestedEntity.fields || [])
+        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
+      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
 
-\`\`\`ts
-const ${exampleEntity.name}s = await client.${eName}().list()
-console.log(${exampleEntity.name}s)
-\`\`\`
-`)
-    }
+      Content(`### 3. Load a ${neName.toLowerCase()}
 
-    if (opnames.includes('create')) {
-      Content(`
-### Create a ${eName}
+${neName} is nested under ${eName}, so provide the \`${parentParam}\`:
 
 \`\`\`ts
-const created = await client.${eName}().create({
-  // Provide ${exampleEntity.name} fields
+const ${neName.toLowerCase()} = client.${neName}()
+const result = await ${neName.toLowerCase()}.load({
+  ${parentParam}: 'example',
+  id: 'example_id',
 })
-console.log(created)
+
+if (result.ok) {
+  console.log(result.data)
+}
 \`\`\`
+
 `)
     }
-
-    if (opnames.includes('update')) {
-      Content(`
-### Update a ${eName}
+    else if (opnames.includes('load')) {
+      Content(`### 3. Load a ${eName.toLowerCase()}
 
 \`\`\`ts
-const updated = await client.${eName}().update({
-  id: '${exampleEntity.name}_id',
-  // Fields to update
-})
-console.log(updated)
+const result = await client.${eName}().load({ id: 'example_id' })
+
+if (result.ok) {
+  console.log(result.data)
+}
 \`\`\`
+
 `)
     }
 
-    if (opnames.includes('remove')) {
-      Content(`
-### Remove a ${eName}
+    // CRUD operations
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
 
 \`\`\`ts
-await client.${eName}().remove({ id: '${exampleEntity.name}_id' })
-\`\`\`
 `)
-    }
-  }
-
-
-  Content(`
-### Direct API Access
-
-Use \`client.direct()\` to call any API endpoint directly:
+      if (opnames.includes('create')) {
+        Content(`// Create
+const created = await client.${eName}().create({
+  name: 'Example',
+})
 
-\`\`\`ts
-const result = await client.direct({
-  path: '/custom/endpoint/{id}',
-  method: 'GET',
-  params: { id: 'abc123' },
+`)
+      }
+      if (opnames.includes('update')) {
+        Content(`// Update
+const updated = await client.${eName}().update({
+  id: created.data.id,
+  name: 'Example-Renamed',
 })
 
-if (result.ok) {
-  console.log(result.data)
-}
-\`\`\`
+`)
+      }
+      if (opnames.includes('remove')) {
+        Content(`// Remove
+const removed = await client.${eName}().remove({
+  id: created.data.id,
+})
+`)
+      }
+      Content(`\`\`\`
 
 `)
+    }
+  }
 
 })
 

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

@@ -0,0 +1,25 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**TypeScript:**
+\`\`\`ts
+const result = await client.direct({
+  path: '/api/resource/{id}',
+  method: 'GET',
+  params: { id: 'example' },
+})
+console.log(result.data)
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

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

@@ -0,0 +1,65 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  Content(`\`\`\`ts
+import { ${model.const.Name}SDK } from '${target.module.name}'
+
+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('list')) {
+      Content(`// List all ${eName.toLowerCase()}s
+const ${eName.toLowerCase()}s = await client.${eName}().list()
+`)
+    }
+
+    // Find a nested entity for a more interesting example
+    const nestedEntity = Object.values(entity).find((e: any) =>
+      e.active !== false && e.ancestors && e.ancestors.length > 0
+    ) as any
+
+    if (nestedEntity && opnames.includes('load')) {
+      const neName = nom(nestedEntity, 'Name')
+      const parentFields = (nestedEntity.fields || [])
+        .filter((f: any) => f.name !== 'id' && f.name.endsWith('_id'))
+      const parentParam = parentFields.length > 0 ? parentFields[0].name : 'parent_id'
+
+      Content(`
+// Load a specific ${neName.toLowerCase()}
+const ${neName.toLowerCase()} = await client.${neName}().load({
+  ${parentParam}: 'example',
+  id: 'example_id',
+})
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

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

@@ -0,0 +1,36 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  Content(`\`\`\`ts
+const client = ${model.const.Name}SDK.test()
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    Content(`const result = await client.${eName}().load({ id: 'test01' })
+// result.ok === true, result.data contains mock data
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/tm/go/feature/log_feature.go

@@ -0,0 +1,133 @@
+package feature
+
+import (
+	"log/slog"
+	"os"
+
+	"GOMODULE/core"
+)
+
+type LogFeature struct {
+	BaseFeature
+	client  *core.ProjectNameSDK
+	options map[string]any
+	logger  *slog.Logger
+}
+
+func NewLogFeature() *LogFeature {
+	return &LogFeature{
+		BaseFeature: BaseFeature{
+			Version: "0.0.1",
+			Name:    "log",
+			Active:  true,
+		},
+	}
+}
+
+func (f *LogFeature) Init(ctx *core.Context, options map[string]any) {
+	f.client = ctx.Client
+	f.options = options
+
+	if active, ok := options["active"].(bool); ok {
+		f.Active = active
+	}
+
+	if f.Active {
+		if logger, ok := options["logger"].(*slog.Logger); ok && logger != nil {
+			f.logger = logger
+		} else {
+			level := slog.LevelInfo
+			if lvl, ok := options["level"].(string); ok {
+				switch lvl {
+				case "debug":
+					level = slog.LevelDebug
+				case "warn":
+					level = slog.LevelWarn
+				case "error":
+					level = slog.LevelError
+				}
+			}
+
+			f.logger = slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{
+				Level: level,
+			})).With("name", "log")
+		}
+	}
+}
+
+func (f *LogFeature) PostConstruct(ctx *core.Context) {
+	f.loghook("PostConstruct", ctx, "")
+}
+
+func (f *LogFeature) PostConstructEntity(ctx *core.Context) {
+	f.loghook("PostConstructEntity", ctx, "")
+}
+
+func (f *LogFeature) SetData(ctx *core.Context) {
+	f.loghook("SetData", ctx, "")
+}
+
+func (f *LogFeature) GetData(ctx *core.Context) {
+	f.loghook("GetData", ctx, "")
+}
+
+func (f *LogFeature) SetMatch(ctx *core.Context) {
+	f.loghook("SetMatch", ctx, "")
+}
+
+func (f *LogFeature) GetMatch(ctx *core.Context) {
+	f.loghook("GetMatch", ctx, "")
+}
+
+func (f *LogFeature) PrePoint(ctx *core.Context) {
+	f.loghook("PrePoint", ctx, "")
+}
+
+func (f *LogFeature) PreSpec(ctx *core.Context) {
+	f.loghook("PreSpec", ctx, "")
+}
+
+func (f *LogFeature) PreRequest(ctx *core.Context) {
+	f.loghook("PreRequest", ctx, "")
+}
+
+func (f *LogFeature) PreResponse(ctx *core.Context) {
+	f.loghook("PreResponse", ctx, "")
+}
+
+func (f *LogFeature) PreResult(ctx *core.Context) {
+	f.loghook("PreResult", ctx, "")
+}
+
+func (f *LogFeature) loghook(hook string, ctx *core.Context, level string) {
+	if f.logger == nil {
+		return
+	}
+
+	if level == "" {
+		level = "info"
+	}
+
+	attrs := []any{
+		"hook", hook,
+	}
+
+	if ctx.Op != nil {
+		attrs = append(attrs, "op", ctx.Op.Name)
+	}
+
+	if ctx.Spec != nil {
+		attrs = append(attrs, "spec", ctx.Spec.Method+" "+ctx.Spec.Path)
+	}
+
+	switch level {
+	case "debug":
+		f.logger.Debug("hook", attrs...)
+	case "warn":
+		f.logger.Warn("hook", attrs...)
+	case "error":
+		f.logger.Error("hook", attrs...)
+	default:
+		f.logger.Info("hook", attrs...)
+	}
+}

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

@@ -6,6 +6,7 @@ import (
 	"os"
 	"path/filepath"
 	"reflect"
+	"regexp"
 	"runtime"
 	"strings"
 	"sync"
@@ -140,7 +141,7 @@ func runset(t *testing.T, testspec map[string]any, subject RunSubject) {
 			if expectedErr != nil {
 				errMsg := err.Error()
 				if expStr, ok := expectedErr.(string); ok {
-					if !strings.Contains(errMsg, expStr) {
+					if !matchString(expStr, errMsg) {
 						t.Errorf("entry %d%s: error mismatch: got %q, want contains %q",
 							i, mark, errMsg, expStr)
 					}
@@ -272,7 +273,7 @@ func matchDeep(t *testing.T, entryIdx int, mark string, check any, base any, pat
 		if !reflect.DeepEqual(normCheck, normBase) {
 			if isStr && checkStr != "" {
 				baseStr := vs.Stringify(base)
-				if strings.Contains(strings.ToLower(baseStr), strings.ToLower(checkStr)) {
+				if matchString(checkStr, baseStr) {
 					return
 				}
 			}
@@ -282,6 +283,19 @@ func matchDeep(t *testing.T, entryIdx int, mark string, check any, base any, pat
 	}
 }
 
+// matchString checks if val matches pattern. If pattern is /regex/, use regexp;
+// otherwise do case-insensitive contains.
+func matchString(pattern string, val string) bool {
+	if len(pattern) >= 2 && pattern[0] == '/' && pattern[len(pattern)-1] == '/' {
+		re, err := regexp.Compile(pattern[1 : len(pattern)-1])
+		if err != nil {
+			return false
+		}
+		return re.MatchString(val)
+	}
+	return strings.Contains(strings.ToLower(val), strings.ToLower(pattern))
+}
+
 // makeCtxFromMap creates a Context from a JSON test entry's ctx or args map.
 func makeCtxFromMap(ctxmap map[string]any, client *sdk.ProjectNameSDK, utility *sdk.Utility) *sdk.Context {
 	if ctxmap == nil {