@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/elixir/ReadmeRef_elixir.ts

@@ -0,0 +1,333 @@
+
+import { cmp, each, Content, canonToType, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+// Type names come from the shared canonToType 'elixir' column (single source of truth).
+import { elixirLit } from './utility_elixir'
+
+
+const OP_SIGNATURES: Record<string, { sig: string, desc: string }> = {
+  load: {
+    sig: 'load(entity, reqmatch, ctrl \\\\ nil) :: map()',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+  },
+  list: {
+    sig: 'list(entity, reqmatch \\\\ nil, ctrl \\\\ nil) :: list()',
+    desc: 'List entities matching the given criteria. The match is optional — call `list(entity)` to list all records. Returns a list and raises on error.',
+  },
+  create: {
+    sig: 'create(entity, reqdata, ctrl \\\\ nil) :: map()',
+    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+  },
+  update: {
+    sig: 'update(entity, reqdata, ctrl \\\\ nil) :: map()',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+  },
+  remove: {
+    sig: 'remove(entity, reqmatch, ctrl \\\\ nil) :: map()',
+    desc: 'Remove the entity matching the given criteria. Raises on error.',
+  },
+}
+
+
+const ReadmeRef = cmp(function ReadmeRef(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const Name = model.const.Name
+  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.
+
+
+## ${Name}
+
+### Constructor
+
+\`\`\`elixir
+sdk = ${Name}.new(options)
+\`\`\`
+
+Create a new SDK client. \`options\` is a struct value node — build one from a
+native map with \`${Name}.Helpers.deep/1\`.
+
+**Options:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+${isAuthActive(model) ? '| `apikey` | `String.t()` | API key for authentication. |\n' : ''}| \`base\` | \`String.t()\` | Base URL for API requests. |
+| \`prefix\` | \`String.t()\` | URL prefix appended after base. |
+| \`suffix\` | \`String.t()\` | URL suffix appended after path. |
+| \`headers\` | \`map()\` | Custom headers for all requests. |
+| \`feature\` | \`map()\` | Feature configuration. |
+| \`system\` | \`map()\` | System overrides (e.g. custom fetch). |
+
+
+### Constructors
+
+#### \`${Name}.test(testopts \\\\ nil, sdkopts \\\\ nil)\`
+
+Create a test client with mock features active. Both arguments may be \`nil\`.
+
+\`\`\`elixir
+sdk = ${Name}.test()
+\`\`\`
+
+
+### Functions
+
+`)
+
+
+    // Entity factory functions
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`${Name}.${ent.name}(client, entopts \\\\ nil)\`
+
+Create a \`${Name}.Entity.${ent.Name}\` handle.
+
+`)
+    })
+
+
+    Content(`#### \`options_map(client) :: map()\`
+
+Return a deep copy of the current SDK options.
+
+#### \`get_utility(client) :: map()\`
+
+Return the SDK utility node.
+
+#### \`direct(client, fetchargs) :: map()\`
+
+Make a direct HTTP request to any API endpoint. Returns a result node with
+\`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This escape
+hatch never raises — branch on \`Voxgig.Struct.getprop(result, "ok")\`.
+
+**fetchargs keys:**
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`path\` | \`String.t()\` | URL path with optional \`{param}\` placeholders. |
+| \`method\` | \`String.t()\` | HTTP method (default: \`"GET"\`). |
+| \`params\` | \`map()\` | Path parameter values. |
+| \`query\` | \`map()\` | Query string parameters. |
+| \`headers\` | \`map()\` | Request headers (merged with defaults). |
+| \`body\` | \`any()\` | Request body (maps are JSON-serialized). |
+
+#### \`prepare(client, fetchargs) :: map()\`
+
+Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises
+on error.
+
+`)
+
+
+    // Entity reference sections
+    publishedEntities.map((ent: any) => {
+      const EName = ent.Name
+      const eVar = ent.name
+      const opnames = Object.keys(ent.op || {})
+      const fields = ent.fields || []
+      const idF = entityIdField(ent)
+
+      Content(`
+---
+
+## ${Name}.Entity.${EName}
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`elixir
+${eVar} = ${Name}.${eVar}(sdk)
+\`\`\`
+
+`)
+
+
+      // 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}\` | \`${canonToType(field.type, target.name)}\` | ${req} | ${desc} |
+`)
+        })
+
+        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}
+
+`)
+
+          if ('load' === opname || 'remove' === opname) {
+            const matchItems = opRequestShape(ent, opname).items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const arg = 0 < matchItems.length
+              ? `${Name}.Helpers.deep(%{${matchItems.map((it: any) =>
+                `"${it.name}" => ${elixirLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')}})`
+              : `${Name}.Helpers.deep(%{})`
+            Content(`\`\`\`elixir
+record = ${Name}.Entity.${EName}.${opname}(${eVar}, ${arg})
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`elixir
+records = ${Name}.Entity.${EName}.list(${eVar})
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`elixir
+record = ${Name}.Entity.${EName}.create(${eVar}, ${Name}.Helpers.deep(%{
+`)
+            createItems.map((it: any) => {
+              Content(`  "${it.name}" => ${elixirLit(it.type, 'example_' + it.name)},  # ${canonToType(it.type, target.name)}
+`)
+            })
+            Content(`}))
+\`\`\`
+
+`)
+          }
+          else if ('update' === opname) {
+            const updateItems = opRequestShape(ent, 'update').items
+              .filter((it: any) => !it.optional || it.name === idF)
+              .sort((a: any, b: any) =>
+                (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+            const updateLines = updateItems.map((it: any) =>
+              `  "${it.name}" => ${elixirLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
+            Content(`\`\`\`elixir
+record = ${Name}.Entity.${EName}.update(${eVar}, ${Name}.Helpers.deep(%{
+${updateLines}  # Fields to update
+}))
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common functions
+      Content(`### Common Functions
+
+#### \`data_get(entity) :: map()\`
+
+Get the entity data.
+
+#### \`data_set(entity, data)\`
+
+Set the entity data.
+
+#### \`match_get(entity) :: map()\`
+
+Get the entity match criteria.
+
+#### \`match_set(entity, match)\`
+
+Set the entity match criteria.
+
+#### \`make(entity) :: entity\`
+
+Create a new \`${Name}.Entity.${EName}\` handle with the same options.
+
+#### \`get_name(entity) :: String.t()\`
+
+Return the entity name.
+
+`)
+    })
+
+
+    // 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(`\`\`\`elixir
+sdk = ${Name}.new(${Name}.Helpers.deep(%{
+  "feature" => %{
+`)
+      activeFeatures.map((f: any) => {
+        Content(`    "${f.name}" => %{"active" => true},
+`)
+      })
+      Content(`  }
+}))
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+export {
+  ReadmeRef
+}

package/project/.sdk/src/cmp/elixir/ReadmeTopHowto_elixir.ts

@@ -0,0 +1,26 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { ctx$: { model } } = props
+
+  const Name = model.const.Name
+
+  Content(`**Elixir:**
+\`\`\`elixir
+result = ${Name}.direct(sdk, ${Name}.Helpers.deep(%{
+  "path" => "/api/resource/{id}",
+  "method" => "GET",
+  "params" => %{"id" => "example"}
+}))
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

package/project/.sdk/src/cmp/elixir/ReadmeTopQuick_elixir.ts

@@ -0,0 +1,79 @@
+
+import { cmp, Content, isAuthActive, envName, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { elixirLit } from './utility_elixir'
+
+
+const ReadmeTopQuick = cmp(function ReadmeTopQuick(props: any) {
+  const { ctx$: { model } } = props
+
+  const Name = model.const.Name
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `${Name}.new(H.deep(%{"apikey" => System.get_env("${envName(model)}_APIKEY")}))`
+    : `${Name}.new()`
+
+  Content(`\`\`\`elixir
+alias ${Name}.Helpers, as: H
+
+sdk = ${ctor}
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const eVar = exampleEntity.name
+    const opnames = Object.keys(exampleEntity.op || {})
+    const idF = entityIdField(exampleEntity)
+
+    Content(`${eVar} = ${Name}.${eVar}(sdk)
+`)
+
+    if (opnames.includes('list')) {
+      Content(`
+# List all ${eName.toLowerCase()} records (raises on error)
+records = ${Name}.Entity.${eName}.list(${eVar})
+IO.inspect(records)
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(exampleEntity, 'load').items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      const loadArg = 0 < loadItems.length
+        ? `H.deep(%{${loadItems.map((it: any) =>
+          `"${it.name}" => ${elixirLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}})`
+        : ''
+      Content(`
+# Load a specific ${eName.toLowerCase()} (returns the record, raises on error)
+record = ${Name}.Entity.${eName}.load(${eVar}, ${loadArg})
+IO.inspect(record)
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/elixir/ReadmeTopTest_elixir.ts

@@ -0,0 +1,68 @@
+
+import { cmp, Content, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { elixirLit } from './utility_elixir'
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { ctx$: { model } } = props
+
+  const Name = model.const.Name
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Pick an entity with a real op (prefer a read op) — never fabricate a
+  // `load` on an op-less entity.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`elixir
+alias ${Name}.Helpers, as: H
+
+sdk = ${Name}.test()
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eName = nom(exampleEntity, 'Name')
+    const eVar = exampleEntity.name
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = ''
+    if (isMatchOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => !it.optional || it.name === idF)
+        .sort((a: any, b: any) =>
+          (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+      arg = 0 < items.length
+        ? `H.deep(%{${items.map((it: any) =>
+          `"${it.name}" => ${it.name === idF ? '"test01"' : elixirLit(it.type)}`).join(', ')}})`
+        : 'H.deep(%{})'
+    } else if ('create' === primaryOp || 'update' === primaryOp) {
+      const items = opRequestShape(exampleEntity, primaryOp).items
+        .filter((it: any) => it.name !== idF && it.name !== 'id')
+      const required = items.filter((it: any) => !it.optional)
+      const chosen = required.length ? required : items.slice(0, 3)
+      arg = `H.deep(%{${chosen.map((it: any) => `"${it.name}" => ${elixirLit(it.type)}`).join(', ')}})`
+    } else {
+      arg = 'H.deep(%{})'
+    }
+    const resVar = 'list' === primaryOp ? 'records' : 'record'
+    Content(`${eVar} = ${Name}.${eVar}(sdk)
+${resVar} = ${Name}.Entity.${eName}.${primaryOp}(${eVar}, ${arg})
+IO.inspect(${resVar})
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/elixir/Test_elixir.ts

@@ -12,6 +12,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_elixir'
 import { TestDirect } from './TestDirect_elixir'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_elixir'
 
 
 const Test = cmp(function Test(props: any) {
@@ -38,6 +39,9 @@ end
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // Validate the documented elixir examples in the README/REFERENCE docs.
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/elixir/fragment/EntityCreateOp.fragment.ex

@@ -1,5 +1,9 @@
 # EJECT-START
 
+  # Returns the created entityname entity map (ProjectName.Types.entityname/0)
+  # on success; pipeline errors surface as the error value built by
+  # Utility.make_error (shape is utility-configurable), hence term().
+  @spec create(map(), ProjectName.Types.entityname_create_data() | nil, map() | nil) :: term()
   def create(ent, reqdata, ctrl \\ nil) do
     ctx =
       Context.new(

package/project/.sdk/src/cmp/elixir/fragment/EntityListOp.fragment.ex

@@ -1,5 +1,9 @@
 # EJECT-START
 
+  # Returns a list of entityname entity maps (ProjectName.Types.entityname/0)
+  # on success; pipeline errors surface as the error value built by
+  # Utility.make_error (shape is utility-configurable), hence term().
+  @spec list(map(), ProjectName.Types.entityname_list_match() | nil, map() | nil) :: term()
   def list(ent, reqmatch \\ nil, ctrl \\ nil) do
     reqmatch = if reqmatch == nil, do: S.jm([]), else: reqmatch
 

package/project/.sdk/src/cmp/elixir/fragment/EntityLoadOp.fragment.ex

@@ -1,5 +1,9 @@
 # EJECT-START
 
+  # Returns the entityname entity map (ProjectName.Types.entityname/0) on
+  # success; pipeline errors surface as the error value built by
+  # Utility.make_error (shape is utility-configurable), hence term().
+  @spec load(map(), ProjectName.Types.entityname_load_match() | nil, map() | nil) :: term()
   def load(ent, reqmatch \\ nil, ctrl \\ nil) do
     reqmatch = if reqmatch == nil, do: S.jm([]), else: reqmatch
 

package/project/.sdk/src/cmp/elixir/fragment/EntityRemoveOp.fragment.ex

@@ -1,5 +1,9 @@
 # EJECT-START
 
+  # Returns the removed entityname entity map (ProjectName.Types.entityname/0)
+  # on success; pipeline errors surface as the error value built by
+  # Utility.make_error (shape is utility-configurable), hence term().
+  @spec remove(map(), ProjectName.Types.entityname_remove_match() | nil, map() | nil) :: term()
   def remove(ent, reqmatch \\ nil, ctrl \\ nil) do
     reqmatch = if reqmatch == nil, do: S.jm([]), else: reqmatch
 

package/project/.sdk/src/cmp/elixir/fragment/EntityUpdateOp.fragment.ex

@@ -1,5 +1,9 @@
 # EJECT-START
 
+  # Returns the updated entityname entity map (ProjectName.Types.entityname/0)
+  # on success; pipeline errors surface as the error value built by
+  # Utility.make_error (shape is utility-configurable), hence term().
+  @spec update(map(), ProjectName.Types.entityname_update_data() | nil, map() | nil) :: term()
   def update(ent, reqdata, ctrl \\ nil) do
     ctx =
       Context.new(

package/project/.sdk/src/cmp/elixir/utility_elixir.ts

@@ -6,6 +6,36 @@ import {
   walk,
 } from '@voxgig/struct'
 
+import {
+  canonKey,
+  canonToType,
+} from '@voxgig/sdkgen'
+
+
+// Map a canonical type sentinel ($STRING, $INTEGER, ...) to an idiomatic
+// Elixir typespec. Unknown/missing sentinels fall back to `any()` (never
+// throws). Thin delegate to the SHARED canonToType 'elixir' column (the
+// single source of truth per language — do not keep a local table here);
+// kept as an exported function so existing importers keep working.
+function elixirType(sentinel: unknown): string {
+  return canonToType(sentinel, 'elixir')
+}
+
+
+// A type-correct, executable Elixir literal for a field/param of the given
+// canonical type. Strings render the quoted placeholder; numeric/boolean/
+// collection types render a real literal so example blocks parse and run.
+function elixirLit(sentinel: unknown, placeholder: string = 'example'): string {
+  switch (canonKey(sentinel)) {
+    case 'INTEGER':
+    case 'NUMBER': return '1'
+    case 'BOOLEAN': return 'true'
+    case 'ARRAY': return '[]'
+    case 'OBJECT': return '%{}'
+    default: return `"${placeholder}"`
+  }
+}
+
 
 function projectPath(suffix?: string): string {
   return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
@@ -81,5 +111,7 @@ export {
   clean,
   formatElixir,
   elixirString,
+  elixirType,
+  elixirLit,
   projectPath,
 }

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

@@ -31,7 +31,7 @@ import {
   File, Content, Folder,
 } from '@voxgig/sdkgen'
 
-import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -74,9 +74,13 @@ function fieldLine(name: string, sentinel: any, optional: boolean): string {
 
 const EntityTypes = cmp(function EntityTypes(props: any) {
   const { target } = props
-  const { model } = props.ctx$
+  const { model, log } = props.ctx$
 
-  const entity = getModelPath(model, `main.${KIT}.entity`)
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
   // Emit for every entity that gets an entity file. Main_go.ts / Entity_go.ts
   // iterate entities WITHOUT an `active` filter and reference the typed data
   // type `<Name>` in every *_entity.go, so a struct is required for each or the
@@ -89,6 +93,11 @@ const EntityTypes = cmp(function EntityTypes(props: any) {
   const entityList = each(entity).filter((e: any) => e && null != e.name)
   entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
 
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
   Folder({ name: 'entity' }, () => {
 
     File({ name: 'types.' + target.ext }, () => {

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

@@ -45,7 +45,12 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
   const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
   let testArg = 'nil'
   if (exampleEntity && isMatchOp) {
-    testArg = idF ? `map[string]any{"${idF}": "test01"}` : 'nil'
+    const items = opRequestShape(exampleEntity, primaryOp).items
+      .filter((it: any) => !it.optional || it.name === idF)
+      .sort((a: any, b: any) => (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+    testArg = 0 < items.length
+      ? `map[string]any{${items.map((it: any) => `"${it.name}": ${it.name === idF ? '"test01"' : goLit(it.type)}`).join(', ')}}`
+      : 'nil'
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')