@voxgig/sdkgen 1.3.14 → 1.3.17

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

@@ -0,0 +1,60 @@
+
+import { cmp, each, Content, envName, isAuthActive } from '@voxgig/sdkgen'
+
+
+const ReadmeOptions = cmp(function ReadmeOptions(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  const publishedOptions = each(target.options).filter((option: any) =>
+    option.publish && ('apikey' !== option.name || isAuthActive(model)))
+  if (0 === publishedOptions.length) {
+    return
+  }
+
+  Content(`
+
+## Options
+
+Pass options when creating a client instance:
+
+`)
+
+  Content(`\`\`\`csharp
+var client = new ${model.Name}SDK(new Dictionary<string, object?>
+{
+`)
+
+  publishedOptions.map((option: any) => {
+    if ('apikey' === option.name) {
+      Content(`    ["${option.name}"] = Environment.GetEnvironmentVariable("${envName(model)}_APIKEY"),
+`)
+    }
+    else {
+      Content(`    // ["${option.name}"] = ${option.kind === 'string' ? "\"...\"" : '...'},
+`)
+    }
+  })
+
+  Content(`});
+\`\`\`
+
+`)
+
+  Content(`| Option | Type | Description |
+| --- | --- | --- |
+`)
+
+  publishedOptions.map((option: any) => {
+    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
+`)
+  })
+
+  Content(`
+`)
+})
+
+
+export {
+  ReadmeOptions
+}

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

@@ -0,0 +1,219 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityOps } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { csVarName } from './utility_csharp'
+
+
+const ReadmeQuick = cmp(function ReadmeQuick(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
+
+  // Find a nested entity if available: one with a parent chain
+  // (relations.ancestors), an active load op, and a required non-id load
+  // param to demonstrate (the parent key, e.g. page_id).
+  const nestedEntity = Object.values(entity).find((e: any) =>
+    e.active !== false &&
+    e.relations && e.relations.ancestors && 0 < e.relations.ancestors.length &&
+    entityOps(e).includes('load') &&
+    opRequestShape(e, 'load').items.some((it: any) =>
+      !it.optional && it.name !== entityIdField(e))
+  ) as any
+
+  const authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `new ${model.const.Name}SDK(new Dictionary<string, object?>\n{\n    ["apikey"] = Environment.GetEnvironmentVariable("${envName(model)}_APIKEY"),\n})`
+    : `new ${model.const.Name}SDK()`
+
+  Content(`### 1. Create a client
+
+\`\`\`csharp
+using ${model.const.Name}Sdk;
+
+var client = ${ctor};
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
+    // Sanitise the local variable name — a camelCased C# keyword gets a
+    // trailing underscore (csVarName) so the snippet compiles.
+    const eVar = csVarName(exampleEntity.name)
+    const opnames = entityOps(exampleEntity)
+    // Model-driven id key: `idF` is the entity's id-like MATCH field name, or
+    // null when it has none.
+    const idF = entityIdField(exampleEntity)
+
+    // A type-correct C# literal for a param.
+    const 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}"`
+    }
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()} records
+
+\`List(null)\` returns an aggregate list of records (as \`object?\`) and raises
+on error.
+
+\`\`\`csharp
+try
+{
+    var ${eVar}List = client.${eName}().List(null);
+    Console.WriteLine(${eVar}List);
+}
+catch (Exception err)
+{
+    Console.WriteLine($"list failed: {err.Message}");
+}
+\`\`\`
+
+`)
+    }
+
+    if (nestedEntity) {
+      const neName = nom(nestedEntity, 'Name')
+      const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
+      const neVar = csVarName(nestedEntity.name)
+
+      // Model-driven match: every REQUIRED load-match key. Parent keys (e.g.
+      // page_id) first, the entity's own id last.
+      const neIdF = entityIdField(nestedEntity)
+      const neRequired = opRequestShape(nestedEntity, 'load').items
+        .filter((it: any) => !it.optional)
+        .sort((a: any, b: any) =>
+          (a.name === neIdF ? 1 : 0) - (b.name === neIdF ? 1 : 0))
+      const parentItem = neRequired.find((it: any) => it.name !== neIdF) as any
+      const parentParam = parentItem && parentItem.name
+      const parentName = parentParam ? parentParam.replace(/_id$/, '') : 'its parent'
+      const neMatch = neRequired.map((it: any) =>
+        `["${it.name}"] = ${csLit(it.type,
+          it.name === neIdF ? 'example_id' : 'example_' + it.name)}`)
+
+      Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
+
+${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
+\`Load()\` returns the bare record (as \`object?\`) and raises on error.
+
+\`\`\`csharp
+try
+{
+    var ${neVar} = client.${neName}().Load(new Dictionary<string, object?> { ${neMatch.join(', ')} });
+    Console.WriteLine(${neVar});
+}
+catch (Exception err)
+{
+    Console.WriteLine($"load failed: {err.Message}");
+}
+\`\`\`
+
+`)
+    }
+    else if (opnames.includes('load')) {
+      // Every REQUIRED load-match key (id first, then parent path params).
+      const loadRequired = 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 < loadRequired.length
+        ? `new Dictionary<string, object?> {${loadRequired.map((it: any) =>
+          ` ["${it.name}"] = ${csLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(',')} }`
+        : 'null'
+
+      Content(`### 3. Load ${article} ${eName.toLowerCase()}
+
+\`Load()\` returns the bare record (as \`object?\`) and raises on error.
+
+\`\`\`csharp
+try
+{
+    var ${eVar} = client.${eName}().Load(${loadArg});
+    Console.WriteLine(${eVar});
+}
+catch (Exception err)
+{
+    Console.WriteLine($"load failed: {err.Message}");
+}
+\`\`\`
+
+`)
+    }
+
+    // Model-driven example fields: derive the create/update body from the op
+    // shape (opRequestShape) so the docs reference REAL writable fields.
+    const examplePairs = (opname: string): string[] => {
+      const items = opRequestShape(exampleEntity, opname).items
+        .filter((it: any) => (it.name !== idF && it.name !== 'id') ||
+          ('create' === opname && !it.optional))
+      const required = items.filter((it: any) => !it.optional)
+      const optional = items.filter((it: any) => it.optional)
+      const chosen = 'create' === opname
+        ? (required.length ? required : items.slice(0, 2))
+        : required.concat(optional).slice(0, Math.max(2, required.length))
+      return chosen.map((it: any) => `["${it.name}"] = ${csLit(it.type, 'example_' + it.name)}`)
+    }
+
+    const idParamType = (opname: string): any => {
+      const it = opRequestShape(exampleEntity, opname).items.find((x: any) => x.name === idF)
+      return it && it.type
+    }
+
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
+
+\`\`\`csharp
+`)
+      if (opnames.includes('create')) {
+        Content(`// Create — returns the bare created record (as object?)
+var created = client.${eName}().Create(new Dictionary<string, object?> { ${examplePairs('create').join(', ')} });
+
+`)
+      }
+      if (opnames.includes('update')) {
+        const updatePairs = (idF ? [`["${idF}"] = ${csLit(idParamType('update'), 'example_id')}`] : [])
+          .concat(examplePairs('update'))
+        Content(`// Update — supply the id in the match/data
+client.${eName}().Update(new Dictionary<string, object?> { ${updatePairs.join(', ')} });
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        // Every REQUIRED remove-match key: the id plus parent keys like page_id.
+        const removePairs = opRequestShape(exampleEntity, 'remove').items
+          .filter((it: any) => !it.optional || it.name === idF)
+          .sort((a: any, b: any) =>
+            (a.name === idF ? 0 : 1) - (b.name === idF ? 0 : 1))
+          .map((it: any) => it.name === idF
+            ? `["${it.name}"] = ${csLit(idParamType('remove'), 'example_id')}`
+            : `["${it.name}"] = ${csLit(it.type, 'example_' + it.name)}`)
+        Content(`// Remove
+client.${eName}().Remove(${removePairs.length ? `new Dictionary<string, object?> { ${removePairs.join(', ')} }` : 'null'});
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeQuick
+}

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

@@ -0,0 +1,390 @@
+
+import { cmp, each, Content, canonToType, canonKey, File, isAuthActive, 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 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}"`
+}
+
+
+const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
+  load: {
+    sig: 'Load(reqmatch, ctrl = null) -> object?',
+    returns: 'the entity data',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+  },
+  list: {
+    sig: 'List(reqmatch, ctrl = null) -> object?',
+    returns: 'an aggregate list of entities',
+    desc: 'List entities matching the given criteria. The match is optional — call `List(null)` to list all records. Returns an aggregate list and raises on error.',
+  },
+  create: {
+    sig: 'Create(reqdata, ctrl = null) -> object?',
+    returns: 'the created entity data',
+    desc: 'Create a new entity with the given data. Returns the created entity data and raises on error.',
+  },
+  update: {
+    sig: 'Update(reqdata, ctrl = null) -> object?',
+    returns: 'the updated entity data',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and raises on error.',
+  },
+  remove: {
+    sig: 'Remove(reqmatch, ctrl = null) -> object?',
+    returns: 'the removed entity data',
+    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 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.
+
+
+## ${model.const.Name}SDK
+
+### Constructor
+
+`)
+
+    Content(`\`\`\`csharp
+using ${model.const.Name}Sdk;
+
+var client = new ${model.const.Name}SDK(options);
+\`\`\`
+
+Create a new SDK client instance. \`options\` is a
+\`Dictionary<string, object?>\`.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`options\` | \`Dictionary\` | SDK configuration options. |
+${isAuthActive(model) ? '| \`options["apikey"]\` | \`string\` | API key for authentication. |\n' : ''}| \`options["base"]\` | \`string\` | Base URL for API requests. |
+| \`options["prefix"]\` | \`string\` | URL prefix appended after base. |
+| \`options["suffix"]\` | \`string\` | URL suffix appended after path. |
+| \`options["headers"]\` | \`Dictionary\` | Custom headers for all requests. |
+| \`options["feature"]\` | \`Dictionary\` | Feature configuration. |
+| \`options["system"]\` | \`Dictionary\` | System overrides (e.g. custom fetch). |
+
+`)
+
+
+    Content(`
+### Static Methods
+
+`)
+
+    Content(`#### \`${model.const.Name}SDK.TestSDK(testopts = null, sdkopts = null)\`
+
+Create a test client with mock features active. Both arguments may be \`null\`.
+
+\`\`\`csharp
+var client = ${model.const.Name}SDK.TestSDK(null, null);
+\`\`\`
+
+`)
+
+
+    Content(`
+### Instance Methods
+
+`)
+
+
+    // Entity factory methods
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`${ent.Name}(entopts = null)\`
+
+Create a new \`${ent.Name}\` entity instance (returns
+\`${model.const.Name}EntityBase\`). Pass \`null\` for no initial options.
+
+`)
+    })
+
+
+    Content(`#### \`OptionsMap() -> Dictionary\`
+
+Return a deep copy of the current SDK options.
+
+#### \`GetUtility() -> Utility\`
+
+Return a copy of the SDK utility object.
+
+#### \`Direct(fetchargs = null) -> Dictionary\`
+
+Make a direct HTTP request to any API endpoint. Returns a result
+\`Dictionary<string, object?>\` with \`ok\`, \`status\`, \`headers\`, and \`data\`
+(or \`err\` on failure). This escape hatch never raises — branch on
+\`result["ok"]\`.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`fetchargs["path"]\` | \`string\` | URL path with optional \`{param}\` placeholders. |
+| \`fetchargs["method"]\` | \`string\` | HTTP method (default: \`"GET"\`). |
+| \`fetchargs["params"]\` | \`Dictionary\` | Path parameter values. |
+| \`fetchargs["query"]\` | \`Dictionary\` | Query string parameters. |
+| \`fetchargs["headers"]\` | \`Dictionary\` | Request headers (merged with defaults). |
+| \`fetchargs["body"]\` | \`object?\` | Request body (dictionaries are JSON-serialized). |
+
+**Returns:** \`Dictionary<string, object?>\`
+
+#### \`Prepare(fetchargs = null) -> Dictionary\`
+
+Prepare a fetch definition without sending. Returns the \`fetchdef\` and raises on error.
+
+`)
+
+
+    // Entity reference sections
+    publishedEntities.map((ent: any) => {
+      const opnames = Object.keys(ent.op || {})
+      const fields = ent.fields || []
+      // Model-driven id key: null when this entity has no id-like field.
+      const idF = entityIdField(ent)
+      // Sanitise the local variable name — csVarName guards C# keywords.
+      const eVar = csVarName(ent.name)
+
+      Content(`
+---
+
+## ${ent.Name}
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`csharp
+var ${eVar} = client.${ent.Name}();
+\`\`\`
+
+`)
+
+
+      // 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(`
+`)
+
+        // Field operations breakdown
+        const hasFieldOps = fields.some((f: any) => f.op && Object.keys(f.op).length > 0)
+        if (hasFieldOps) {
+          const opcols = ['load', 'list', 'create', 'update', 'remove']
+            .filter((op: string) => opnames.includes(op) && ent.op[op]?.active !== false)
+          Content(`### Field Usage by Operation
+
+| Field | ${opcols.join(' | ')} |
+| --- | ${opcols.map(() => '---').join(' | ')} |
+`)
+          each(fields, (field: any) => {
+            const fops = field.op || {}
+            const cols = opcols.map((op: string) => {
+              const fop = fops[op]
+              if (null == fop) return '-'
+              if (fop.active === false) return '-'
+              return 'Yes'
+            })
+            Content(`| \`${field.name}\` | ${cols.join(' | ')} |
+`)
+          })
+
+          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
+              ? `new Dictionary<string, object?> {${matchItems.map((it: any) =>
+                ` ["${it.name}"] = ${csLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(',')} }`
+              : 'null'
+            Content(`\`\`\`csharp
+var result = client.${ent.Name}().${opname.charAt(0).toUpperCase() + opname.slice(1)}(${arg});
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`csharp
+var results = client.${ent.Name}().List(null);
+Console.WriteLine(results);
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`csharp
+var result = client.${ent.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(`});
+\`\`\`
+
+`)
+          }
+          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}"] = ${csLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
+            Content(`\`\`\`csharp
+var result = client.${ent.Name}().Update(new Dictionary<string, object?>
+{
+${updateLines}    // Fields to update
+});
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common methods
+      Content(`### Common Methods
+
+#### \`Data(newdata = null) -> object?\`
+
+Get or set the entity data.
+
+#### \`Match(newmatch = null) -> object?\`
+
+Get or set the entity match criteria.
+
+#### \`Make() -> IEntity\`
+
+Create a new \`${ent.Name}\` entity instance with the same options.
+
+#### \`GetName() -> string\`
+
+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(`\`\`\`csharp
+var client = new ${model.const.Name}SDK(new Dictionary<string, object?>
+{
+    ["feature"] = new Dictionary<string, object?>
+    {
+`)
+      activeFeatures.map((f: any) => {
+        Content(`        ["${f.name}"] = new Dictionary<string, object?> { ["active"] = true },
+`)
+      })
+      Content(`    },
+});
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+export {
+  ReadmeRef
+}

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

@@ -0,0 +1,25 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**C#:**
+\`\`\`csharp
+var result = client.Direct(new Dictionary<string, object?>
+{
+    ["path"] = "/api/resource/{id}",
+    ["method"] = "GET",
+    ["params"] = new Dictionary<string, object?> { ["id"] = "example" },
+});
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}