@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/cpp/ReadmeTopQuick_cpp.ts

@@ -0,0 +1,95 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cppVarName } from './utility_cpp'
+
+
+// A type-correct C++ literal for a param.
+function cppLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
+  if ('BOOLEAN' === k) return 'Value(true)'
+  if ('ARRAY' === k) return 'vlist()'
+  if ('OBJECT' === k) return 'vmap()'
+  return `Value("${placeholder}")`
+}
+
+
+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
+
+  const Name = model.const.Name
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `const char* apikey = std::getenv("${envName(model)}_APIKEY");
+auto client = std::make_shared<${Name}SDK>(vmap({
+    {"apikey", Value(apikey ? apikey : "")},
+}));`
+    : `auto client = ${Name}SDK::create();`
+  const ctorIncludes = authActive
+    ? `#include <cstdlib>
+#include "core/sdk.hpp"`
+    : `#include "core/sdk.hpp"`
+
+  Content(`\`\`\`cpp
+${ctorIncludes}
+
+using namespace sdk;
+
+${ctor}
+
+`)
+
+  if (exampleEntity) {
+    const acc = cppVarName(exampleEntity.name)
+    const eVar = acc
+    const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`// List all ${acc}s (returns a Value list, throws on error)
+Value ${eVar}s = client->${acc}()->list(Value::undef(), Value::undef());
+for (const auto& ${eVar} : *${eVar}s.as_list()) {
+  std::cout << Struct::jsonify(${eVar}) << std::endl;
+}
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params).
+      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
+        ? `vmap({${loadItems.map((it: any) =>
+          `{"${it.name}", ${cppLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}}`).join(', ')}})`
+        : 'Value::undef()'
+      Content(`
+// Load a specific ${acc} (returns the record, throws on error)
+Value ${eVar} = client->${acc}()->load(${loadArg}, Value::undef());
+std::cout << Struct::jsonify(${eVar}) << std::endl;
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/cpp/ReadmeTopTest_cpp.ts

@@ -0,0 +1,70 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { cppVarName } from './utility_cpp'
+
+
+// A type-correct C++ literal for a field's canonical type.
+function cppLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'Value(1)'
+  if ('BOOLEAN' === k) return 'Value(true)'
+  if ('ARRAY' === k) return 'vlist()'
+  if ('OBJECT' === k) return 'vmap()'
+  return 'Value("example")'
+}
+
+
+const ReadmeTopTest = cmp(function ReadmeTopTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  // Pick an entity with a real op (prefer a read op).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`cpp
+auto client = ${model.const.Name}SDK::testSDK();
+`)
+
+  if (exampleEntity && primaryOp) {
+    const acc = cppVarName(exampleEntity.name)
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'Value::undef()'
+    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
+        ? `vmap({${items.map((it: any) =>
+          `{"${it.name}", ${it.name === idF ? 'Value("test01")' : cppLit(it.type)}}`).join(', ')}})`
+        : 'Value::undef()'
+    } 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 = `vmap({${chosen.map((it: any) => `{"${it.name}", ${cppLit(it.type)}}`).join(', ')}})`
+    }
+    const eVar = acc + ('list' === primaryOp ? 's' : '')
+    Content(`Value ${eVar} = client->${acc}()->${primaryOp}(${arg}, Value::undef());
+std::cout << Struct::jsonify(${eVar}) << std::endl;
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/cpp/TestEntity_cpp.ts

@@ -173,7 +173,7 @@ static void ${evar}_entity_stream() {
 static void ${evar}_entity_basic() {
   auto setup = ${evar}_basic_setup(Value::undef());
   std::string mode = setup.live ? "live" : "unit";
-  for (const std::string& op : {${opsList}}) {
+  for (const std::string& op : std::vector<std::string>{${opsList}}) {
     auto sk = is_control_skipped("entityOp", std::string("${entity.name}.") + op, mode);
     if (sk.first) { std::cerr << "skip: " << (sk.second.empty()? "sdk-test-control.json" : sk.second) << "\\n"; return; }
   }
@@ -186,7 +186,11 @@ static void ${evar}_entity_basic() {
       const preambleVar = cppVarName(entity.name + '_ref01')
       Content(`
   // Bootstrap entity data from existing test data (no create step in flow).
+  // Declare _data at FUNCTION scope (later load/update steps reference it);
+  // only _data_raw was declared, so the block-local assignment left _data
+  // undeclared ("was not declared in this scope").
   Value ${preambleVar}_data_raw = Helpers::toMapAny(Struct::getpath(setup.data, {"existing", "${entity.name}"}));
+  Value ${preambleVar}_data = vmap();
   {
     std::vector<Value> its = Struct::items(${preambleVar}_data_raw);
     ${preambleVar}_data = its.empty() ? vmap() : Helpers::toMapAny(pair_val(its[0]));

package/project/.sdk/src/cmp/csharp/EntityTypes_csharp.ts

@@ -0,0 +1,196 @@
+
+
+// Typed-model generator (C# target). Port of EntityTypes_py.ts / EntityTypes_js.ts.
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file, core/<Name>Types.cs,
+// with a `public record <Name>` per active entity plus a request/match record
+// per active op.
+//
+// TYPE CHOICE: reference `record` types with nullable `init` properties, NOT
+// the wired runtime type. The generated ops take/return the loose object model
+// (`Dictionary<string, object?>` / `object?`), so these records are NOT wired
+// into the op signatures — they are documentation/DX reference shapes a caller
+// may use to describe a payload before converting it to a dictionary. This
+// mirrors the JS target's JSDoc typedefs (annotation only, no runtime effect):
+// C# has no annotation-only type, so a `record` is the closest zero-behaviour
+// analogue. Emitting unused records is harmless — they compile and have no
+// runtime effect.
+//
+// OPTIONAL FIELDS: a `req:false` field/param becomes a nullable property
+// (`T?`), a required one the plain type (`T`). Nullability warnings for
+// uninitialised required reference properties (CS8618) are already suppressed
+// by the generated csproj, so no initialisation is forced.
+//
+// Sentinels map to C# types via the SHARED canonToType 'csharp' column (the
+// single source of truth per language — do not keep a local table here).
+//
+// Keep the SAME type-name scheme as every other language: <Name>,
+// <Name>LoadMatch, <Name>ListMatch, <Name>CreateData, <Name>UpdateData,
+// <Name>RemoveMatch (via the shared opTypeName helper).
+
+import {
+  cmp, each, names,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'csharp'
+
+
+// C# keywords that need the `@` verbatim prefix to be legal identifiers.
+const CS_KEYWORDS = new Set<string>([
+  'abstract', 'as', 'base', 'bool', 'break', 'byte', 'case', 'catch',
+  'char', 'checked', 'class', 'const', 'continue', 'decimal', 'default',
+  'delegate', 'do', 'double', 'else', 'enum', 'event', 'explicit',
+  'extern', 'false', 'finally', 'fixed', 'float', 'for', 'foreach',
+  'goto', 'if', 'implicit', 'in', 'int', 'interface', 'internal', 'is',
+  'lock', 'long', 'namespace', 'new', 'null', 'object', 'operator',
+  'out', 'override', 'params', 'private', 'protected', 'public',
+  'readonly', 'ref', 'return', 'sbyte', 'sealed', 'short', 'sizeof',
+  'stackalloc', 'static', 'string', 'struct', 'switch', 'this', 'throw',
+  'true', 'try', 'typeof', 'uint', 'ulong', 'unchecked', 'unsafe',
+  'ushort', 'using', 'virtual', 'void', 'volatile', 'while',
+])
+
+
+// A field/param name that has a safe C# property rendering (valid identifier).
+// Names that are not valid identifiers (hyphens, leading digits) have no clean
+// property form and are skipped — they remain reachable via the runtime dict.
+function csIdent(name: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)
+}
+
+
+// A legal C# property identifier: keyword names get the `@` verbatim prefix.
+function csProp(name: string): string {
+  return CS_KEYWORDS.has(name) ? '@' + name : name
+}
+
+
+// Emit `public record <typeName>` from {name, type, optional} items. Optional
+// items become nullable properties (`T?`); required items the plain type. An
+// item whose name is not a legal identifier is skipped (WITH a warning — the
+// key stays reachable via the runtime dict, but its absence from the typed
+// model should be visible, not silent). An empty record is a valid,
+// zero-member shape.
+function emitRecord(typeName: string, items: any[], log?: any): void {
+  const usable = items.filter((it: any) => it && null != it.name && csIdent(it.name))
+
+  items.forEach((it: any) => {
+    if (it && null != it.name && !csIdent(it.name) && log && log.warn) {
+      log.warn({
+        point: 'entity-types-skip-field', typeName, field: it.name,
+        note: `csharp: field "${it.name}" of ${typeName} has no legal C# ` +
+          `identifier form; omitted from the typed model (still reachable ` +
+          `via the runtime dictionary)`,
+      })
+    }
+  })
+
+  if (0 === usable.length) {
+    Content(`public record ${typeName}();
+
+`)
+    return
+  }
+
+  Content(`public record ${typeName}
+{
+`)
+  usable.forEach((it: any) => {
+    const base = canonToType(it.type, LANG)
+    // `object?` is already nullable; other types get a trailing `?` when optional.
+    const t = it.optional && !base.endsWith('?') ? base + '?' : base
+    Content(`    public ${t} ${csProp(it.name)} { get; init; }
+`)
+  })
+  Content(`}
+
+`)
+}
+
+
+const EntityTypes = cmp(function EntityTypes(props: any) {
+  const { model, log } = props.ctx$
+  const target = props.target || {}
+  const ext = target.ext || 'cs'
+
+  // 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 generated entity code: the consumer
+  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
+  // filter, so inactive entities still get class files referencing these
+  // typed names. Filter on `name` (always present), NOT `active` — parity
+  // with the go emitter's fix.
+  const entityList = each(entity).filter((e: any) => e && null != e.name)
+  // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
+  // entity not yet named (e.g. a fieldless placeholder) would otherwise read
+  // `Name = undefined` below. Parity with the go/py emitter's fix.
+  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)
+
+  File({ name: model.const.Name + 'Types.' + ext }, () => {
+
+    Content(`// Typed reference models for the ${model.const.Name} SDK.
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels (source of truth: @voxgig/apidef VALID_CANON). Do
+// not edit by hand.
+//
+// These records are documentation/DX reference shapes ONLY. The SDK ops take
+// and return the loose object model (Dictionary<string, object?> / object?) at
+// runtime, so these types are not wired into the op signatures — use them to
+// describe a payload before converting it to a dictionary. Optional (req:false)
+// keys are modelled as nullable properties.
+
+namespace ${model.const.Name}Sdk.Types;
+
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one property per field, `req:false` -> nullable.
+      emitRecord(Name, fields.map((f: any) => ({
+        name: f.name, type: f.type, optional: false === f.req,
+      })), log)
+
+      // Per active op: a request/match record. Members and their optionality
+      // come from the shared partiality policy (opRequestShape).
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        emitRecord(typeName, items, log)
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/csharp/Main_csharp.ts

@@ -24,6 +24,7 @@ import { Gitignore } from './Gitignore_csharp'
 import { MainEntity } from './MainEntity_csharp'
 import { SdkError } from './SdkError_csharp'
 import { EntityBase } from './EntityBase_csharp'
+import { EntityTypes } from './EntityTypes_csharp'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -82,6 +83,11 @@ const Main = cmp(async function Main(props: any) {
     SdkError({ target })
 
     EntityBase({ target })
+
+    // Generate the typed reference-model file (<Name>Types.cs) beside the
+    // other generated core files. Documentation/DX shapes only — not wired
+    // into the loose-object-model op signatures.
+    EntityTypes({ target })
   })
 })
 

package/project/.sdk/src/cmp/csharp/ReadmeEntity_csharp.ts

@@ -0,0 +1,174 @@
+
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { csVarName } from './utility_csharp'
+
+
+// Type names come from the shared canonToType 'csharp' column (single source of truth).
+
+// A type-correct, JSON-serialisable C# literal for a field's canonical type.
+function csLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return '1L'
+  if ('NUMBER' === k) return '1.0'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return 'new List<object?>()'
+  if ('OBJECT' === k) return 'new Dictionary<string, object?>()'
+  return `"${placeholder}"`
+}
+
+
+// Operation method spelling for C#: PascalCase methods over the loose object
+// model. The op descriptions are language-agnostic.
+const OP_DESC: Record<string, { method: string, desc: string }> = {
+  load:   { method: 'Load(match)',   desc: 'Load a single entity by match criteria.' },
+  list:   { method: 'List(null)',    desc: 'List entities, optionally matching the given 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 { target } = props
+  const { model } = props.ctx$
+
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+
+  const publishedEntities = each(entity)
+    .filter((entity: any) => entity.active !== false)
+
+  if (0 === publishedEntities.length) {
+    return
+  }
+
+  Content(`
+
+## Entities
+
+`)
+
+  publishedEntities.map((entity: any) => {
+    const opnames = Object.keys(entity.op || {})
+    const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
+    // Sanitise the local variable name — a camelCased C# keyword gets a
+    // trailing underscore (csVarName) so the snippet compiles.
+    const eVar = csVarName(entity.name)
+
+    Content(`
+### ${entity.Name}
+
+`)
+
+    if (entity.short) {
+      Content(`${entity.short}
+
+`)
+    }
+
+    Content(`Create an instance: \`var ${eVar} = client.${entity.Name}();\`
+
+`)
+
+    if (opnames.length > 0) {
+      Content(`#### Operations
+
+| Method | Description |
+| --- | --- |
+`)
+      opnames.map((opname: string) => {
+        const info = OP_DESC[opname]
+        if (info) {
+          Content(`| \`${info.method}\` | ${info.desc} |
+`)
+        }
+      })
+
+      Content(`
+`)
+    }
+
+    if (fields.length > 0) {
+      Content(`#### Fields
+
+| Field | Type | Description |
+| --- | --- | --- |
+`)
+
+      each(fields, (field: any) => {
+        const desc = field.short || ''
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
+`)
+      })
+
+      Content(`
+`)
+    }
+
+    if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, '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
+        ? `new Dictionary<string, object?> {${loadItems.map((it: any) =>
+          ` ["${it.name}"] = ${csLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(',')} }`
+        : 'null'
+      Content(`#### Example: Load
+
+\`\`\`csharp
+var ${eVar} = client.${entity.Name}().Load(${loadArg});
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('list')) {
+      Content(`#### Example: List
+
+\`\`\`csharp
+var ${eVar}List = client.${entity.Name}().List(null);
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real literal.
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
+      Content(`#### Example: Create
+
+\`\`\`csharp
+var ${eVar} = client.${entity.Name}().Create(new Dictionary<string, object?>
+{
+`)
+      createItems.map((it: any) => {
+        Content(`    ["${it.name}"] = ${csLit(it.type, 'example_' + it.name)},  // ${canonToType(it.type, target.name)}
+`)
+      })
+      Content(`});
+\`\`\`
+
+`)
+    }
+  })
+})
+
+
+export {
+  ReadmeEntity
+}