@voxgig/sdkgen 0.35.2 → 0.36.0

package/project/.sdk/src/cmp/go/ReadmeHowto_go.ts

@@ -0,0 +1,112 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const orgPrefix = (model.origin || '').replace(/-sdk$/, '').replace(/[^a-z0-9]/gi, '')
+  const gomodule = orgPrefix + model.name + 'sdk'
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`go
+result, err := client.Direct(map[string]any{
+    "path":   "/api/resource/{id}",
+    "method": "GET",
+    "params": map[string]any{"id": "example"},
+})
+if err != nil {
+    panic(err)
+}
+
+if result["ok"] == true {
+    fmt.Println(result["status"]) // 200
+    fmt.Println(result["data"])   // response body
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`go
+fetchdef, err := client.Prepare(map[string]any{
+    "path":   "/api/resource/{id}",
+    "method": "DELETE",
+    "params": map[string]any{"id": "example"},
+})
+if err != nil {
+    panic(err)
+}
+
+fmt.Println(fetchdef["url"])
+fmt.Println(fetchdef["method"])
+fmt.Println(fetchdef["headers"])
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing \u2014 no server required:
+
+\`\`\`go
+client := sdk.TestSDK(nil, nil)
+
+result, err := client.Planet(nil).Load(
+    map[string]any{"id": "test01"}, nil,
+)
+// result contains mock response data
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function:
+
+\`\`\`go
+mockFetch := func(url string, init map[string]any) (map[string]any, error) {
+    return map[string]any{
+        "status":     200,
+        "statusText": "OK",
+        "headers":    map[string]any{},
+        "json": (func() any)(func() any {
+            return map[string]any{"id": "mock01"}
+        }),
+    }, nil
+}
+
+client := sdk.New${model.const.Name}SDK(map[string]any{
+    "base": "http://localhost:8080",
+    "system": map[string]any{
+        "fetch": (func(string, map[string]any) (map[string]any, error))(mockFetch),
+    },
+})
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${model.NAME}_TEST_LIVE=TRUE
+${model.NAME}_APIKEY=<your-key>
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd go && go test ./test/...
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

package/project/.sdk/src/cmp/go/ReadmeInstall_go.ts

@@ -0,0 +1,29 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  const orgPrefix = (model.origin || '').replace(/-sdk$/, '').replace(/[^a-z0-9]/gi, '')
+  const gomodule = orgPrefix + model.name + 'sdk'
+
+  Content(`\`\`\`bash
+go get ${gomodule}
+\`\`\`
+
+If the module is not yet published to a registry, use a \`replace\` directive
+in your \`go.mod\` to point to a local checkout:
+
+\`\`\`bash
+go mod edit -replace ${gomodule}=../path/to/${gomodule}
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

package/project/.sdk/src/cmp/go/ReadmeModel_go.ts

@@ -0,0 +1,129 @@
+
+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)
+
+  const orgPrefix = (model.origin || '').replace(/-sdk$/, '').replace(/[^a-z0-9]/gi, '')
+  const gomodule = orgPrefix + model.name + 'sdk'
+
+  Content(`### New${model.const.Name}SDK
+
+\`\`\`go
+func New${model.const.Name}SDK(options map[string]any) *${model.const.Name}SDK
+\`\`\`
+
+Creates a new SDK client.
+
+| 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"\` | \`map[string]any\` | Feature activation flags. |
+| \`"extend"\` | \`[]any\` | Additional Feature instances to load. |
+| \`"system"\` | \`map[string]any\` | System overrides (e.g. custom \`"fetch"\` function). |
+
+### TestSDK
+
+\`\`\`go
+func TestSDK(testopts map[string]any, sdkopts map[string]any) *${model.const.Name}SDK
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
+
+### ${model.const.Name}SDK methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`OptionsMap\` | \`() map[string]any\` | Deep copy of current SDK options. |
+| \`GetUtility\` | \`() *Utility\` | Copy of the SDK utility object. |
+| \`Prepare\` | \`(fetchargs map[string]any) (map[string]any, error)\` | Build an HTTP request definition without sending. |
+| \`Direct\` | \`(fetchargs map[string]any) (map[string]any, error)\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}\` | \`(data map[string]any) ${model.const.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface (${model.const.Name}Entity)
+
+All entities implement the \`${model.const.Name}Entity\` interface.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`Load\` | \`(reqmatch, ctrl map[string]any) (any, error)\` | Load a single entity by match criteria. |
+| \`List\` | \`(reqmatch, ctrl map[string]any) (any, error)\` | List entities matching the criteria. |
+| \`Create\` | \`(reqdata, ctrl map[string]any) (any, error)\` | Create a new entity. |
+| \`Update\` | \`(reqdata, ctrl map[string]any) (any, error)\` | Update an existing entity. |
+| \`Remove\` | \`(reqmatch, ctrl map[string]any) (any, error)\` | Remove an entity. |
+| \`Data\` | \`(args ...any) any\` | Get or set entity data. |
+| \`Match\` | \`(args ...any) any\` | Get or set entity match criteria. |
+| \`Make\` | \`() Entity\` | Create a new instance with the same options. |
+| \`GetName\` | \`() string\` | Return the entity name. |
+
+### Result shape
+
+Entity operations return \`(any, error)\`. The \`any\` value is a
+\`map[string]any\` with these keys:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`"ok"\` | \`bool\` | \`true\` if the HTTP status is 2xx. |
+| \`"status"\` | \`int\` | HTTP status code. |
+| \`"headers"\` | \`map[string]any\` | Response headers. |
+| \`"data"\` | \`any\` | Parsed JSON response body. |
+
+On error, \`"ok"\` is \`false\` and \`"err"\` contains the error value.
+
+`)
+
+  // Entities summary
+  Content(`### 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.map((n: string) => n.charAt(0).toUpperCase() + n.slice(1)).join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}

package/project/.sdk/src/cmp/go/ReadmeQuick_go.ts

@@ -0,0 +1,163 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const orgPrefix = (model.origin || '').replace(/-sdk$/, '').replace(/[^a-z0-9]/gi, '')
+  const gomodule = orgPrefix + model.name + 'sdk'
+
+  // Find the first published entity for examples
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  // 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
+
+\`\`\`go
+package main
+
+import (
+    "fmt"
+    "os"
+
+    sdk "${gomodule}"
+    "${gomodule}/core"
+)
+
+func main() {
+    client := sdk.New${model.const.Name}SDK(map[string]any{
+        "apikey": os.Getenv("${model.NAME}_APIKEY"),
+    })
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()}s
+
+\`\`\`go
+    result, err := client.${eName}(nil).List(nil, nil)
+    if err != nil {
+        panic(err)
+    }
+
+    rm := core.ToMapAny(result)
+    if rm["ok"] == true {
+        for _, item := range rm["data"].([]any) {
+            p := core.ToMapAny(item)
+            fmt.Println(p["id"], p["name"])
+        }
+    }
+\`\`\`
+
+`)
+    }
+
+    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(`### 3. Load a ${neName.toLowerCase()}
+
+${neName} is nested under ${eName}, so provide the \`${parentParam}\`:
+
+\`\`\`go
+    ${neName.toLowerCase()} := client.${neName}(nil)
+    result, err = ${neName.toLowerCase()}.Load(
+        map[string]any{"${parentParam}": "example", "id": "example_id"}, nil,
+    )
+    if err != nil {
+        panic(err)
+    }
+
+    rm = core.ToMapAny(result)
+    if rm["ok"] == true {
+        fmt.Println(rm["data"])
+    }
+}
+\`\`\`
+
+`)
+    }
+    else if (opnames.includes('load')) {
+      Content(`### 3. Load a ${eName.toLowerCase()}
+
+\`\`\`go
+    result, err = client.${eName}(nil).Load(
+        map[string]any{"id": "example_id"}, nil,
+    )
+    if err != nil {
+        panic(err)
+    }
+
+    rm = core.ToMapAny(result)
+    if rm["ok"] == true {
+        fmt.Println(rm["data"])
+    }
+}
+\`\`\`
+
+`)
+    }
+
+    // CRUD operations
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
+
+\`\`\`go
+`)
+      if (opnames.includes('create')) {
+        Content(`// Create
+created, _ := client.${eName}(nil).Create(
+    map[string]any{"name": "Example"}, nil,
+)
+cm := core.ToMapAny(created)
+newID := core.ToMapAny(cm["data"])["id"]
+
+`)
+      }
+      if (opnames.includes('update')) {
+        Content(`// Update
+client.${eName}(nil).Update(
+    map[string]any{"id": newID, "name": "Example-Renamed"}, nil,
+)
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        Content(`// Remove
+client.${eName}(nil).Remove(
+    map[string]any{"id": newID}, nil,
+)
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+
+})
+
+
+export {
+  ReadmeQuick
+}

package/project/.sdk/src/cmp/go/ReadmeTopHowto_go.ts

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**Go:**
+\`\`\`go
+result, err := client.Direct(map[string]any{
+    "path":   "/api/resource/{id}",
+    "method": "GET",
+    "params": map[string]any{"id": "example"},
+})
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

package/project/.sdk/src/cmp/go/ReadmeTopQuick_go.ts

@@ -0,0 +1,67 @@
+
+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 orgPrefix = (model.origin || '').replace(/-sdk$/, '').replace(/[^a-z0-9]/gi, '')
+  const gomodule = orgPrefix + model.name + 'sdk'
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  Content(`\`\`\`go
+import sdk "${gomodule}"
+
+client := sdk.New${model.const.Name}SDK(map[string]any{
+    "apikey": os.Getenv("${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
+${eName.toLowerCase()}s, err := client.${eName}(nil).List(nil, nil)
+`)
+    }
+
+    // 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()}
+${neName.toLowerCase()}, err := client.${neName}(nil).Load(
+    map[string]any{"${parentParam}": "example", "id": "example_id"}, nil,
+)
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/go/ReadmeTopTest_go.ts

@@ -0,0 +1,40 @@
+
+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 orgPrefix = (model.origin || '').replace(/-sdk$/, '').replace(/[^a-z0-9]/gi, '')
+  const gomodule = orgPrefix + model.name + 'sdk'
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  Content(`\`\`\`go
+client := sdk.TestSDK(nil, nil)
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    Content(`result, err := client.${eName}(nil).Load(
+    map[string]any{"id": "test01"}, nil,
+)
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/go/TestDirect_go.ts

@@ -1,11 +1,55 @@
 
+import {
+  depluralize,
+} from '@voxgig/apidef'
+
 import {
   Content,
   File,
   cmp,
+  snakify,
 } from '@voxgig/sdkgen'
 
 
+// Replace raw OpenAPI parameter names in path parts with model parameter names.
+// Path parts may have e.g. {subBreed} while model params use sub_breed.
+// When a rename mapping exists (e.g. closureId -> id), path parts contain the
+// renamed form {id} but params still use the original name closure_id.
+function normalizePathParams(
+  parts: string[],
+  params: any[],
+  rename?: Record<string, string>
+): string {
+  return parts.map((part: string) => {
+    return part.replace(/\{([^}]+)\}/g, (match: string, rawName: string) => {
+      const snaked = snakify(rawName)
+      const depluralized = depluralize(snaked)
+      const param = params.find((p: any) =>
+        p.orig === snaked || p.name === snaked ||
+        p.orig === depluralized || p.name === depluralized
+      )
+      if (param) return '{' + param.name + '}'
+
+      if (rename) {
+        for (const [origCamel, renamedTo] of Object.entries(rename)) {
+          if (renamedTo === rawName) {
+            const origSnaked = snakify(origCamel)
+            const origDepluralized = depluralize(origSnaked)
+            const renamedParam = params.find(
+              (p: any) => p.orig === origSnaked || p.name === origSnaked ||
+                p.orig === origDepluralized || p.name === origDepluralized
+            )
+            if (renamedParam) return '{' + renamedParam.name + '}'
+          }
+        }
+      }
+
+      return match
+    })
+  }).join('/')
+}
+
+
 const TestDirect = cmp(function TestDirect(props: any) {
   const ctx$ = props.ctx$
   const model = ctx$.model
@@ -29,12 +73,12 @@ const TestDirect = cmp(function TestDirect(props: any) {
 
   // Get load point info
   const loadPoint = loadOp?.points?.[0]
-  const loadPath = loadPoint ? (loadPoint.parts || []).join('/') : ''
+  const loadPath = loadPoint ? normalizePathParams(loadPoint.parts || [], loadPoint?.args?.params || [], loadPoint?.rename?.param) : ''
   const loadParams = loadPoint?.args?.params || []
 
   // Get list point info
   const listPoint = listOp?.points?.[0]
-  const listPath = listPoint ? (listPoint.parts || []).join('/') : ''
+  const listPath = listPoint ? normalizePathParams(listPoint.parts || [], listPoint?.args?.params || [], listPoint?.rename?.param) : ''
   const listParams = listPoint?.args?.params || []
 
   // Build the ENTID env var name for this entity