@voxgig/sdkgen 1.3.14 → 1.3.18

package/project/.sdk/src/cmp/ocaml/ReadmeRef_ocaml.ts

@@ -0,0 +1,402 @@
+
+import { cmp, each, Content, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+// A type-correct OCaml `value` literal. Strings render the quoted placeholder.
+function ocamlLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
+  if ('BOOLEAN' === k) return '(Bool true)'
+  if ('ARRAY' === k) return '(empty_list ())'
+  if ('OBJECT' === k) return '(empty_map ())'
+  return `(Str "${placeholder}")`
+}
+
+
+// The logical OCaml type of a field's canonical type (every field is carried
+// inside the dynamic `value` variant).
+function ocamlType(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k) return 'int'
+  if ('NUMBER' === k) return 'float'
+  if ('BOOLEAN' === k) return 'bool'
+  if ('STRING' === k) return 'string'
+  if ('ARRAY' === k) return 'value list'
+  if ('OBJECT' === k) return 'value map'
+  return 'value'
+}
+
+
+const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
+  load: {
+    sig: 'e_load reqmatch ctrl : value',
+    returns: 'the entity data',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+  },
+  list: {
+    sig: 'e_list reqmatch ctrl : value',
+    returns: 'a List of entities',
+    desc: 'List entities matching the given criteria. The match is optional — pass `(empty_map ())` to list all records. Returns a List and raises on error.',
+  },
+  create: {
+    sig: 'e_create reqdata ctrl : value',
+    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: 'e_update reqdata ctrl : value',
+    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: 'e_remove reqmatch ctrl : value',
+    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.
+
+
+## Sdk_client
+
+### Constructor
+
+`)
+
+    Content(`\`\`\`ocaml
+open Voxgig_struct
+open Sdk_helpers
+
+let client = Sdk_client.make options
+\`\`\`
+
+Create a new SDK client instance from a \`value\` options map. Use
+\`Sdk_client.make0 ()\` for defaults.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`options\` | \`value\` | SDK configuration options (a Map). |
+${isAuthActive(model) ? '| `apikey` | `string` | API key for authentication. |\n' : ''}| \`base\` | \`string\` | Base URL for API requests. |
+| \`prefix\` | \`string\` | URL prefix appended after base. |
+| \`suffix\` | \`string\` | URL suffix appended after path. |
+| \`headers\` | \`map\` | Custom headers for all requests. |
+| \`feature\` | \`map\` | Feature configuration. |
+| \`system\` | \`map\` | System overrides (e.g. custom fetch). |
+
+`)
+
+
+    Content(`
+### Static constructors
+
+`)
+
+    Content(`#### \`Sdk_client.test testopts sdkopts\`
+
+Create a test client with mock features active. Both arguments may be \`Noval\`
+(\`Sdk_client.test ()\` uses defaults, \`Sdk_client.test_with\` takes explicit
+options).
+
+\`\`\`ocaml
+let client = Sdk_client.test ()
+\`\`\`
+
+`)
+
+
+    Content(`
+### Instance functions
+
+`)
+
+
+    // Entity accessor functions
+    publishedEntities.map((ent: any) => {
+      const fn = ocamlVarName(ent.name)
+      Content(`#### \`Sdk_client.${fn} client entopts : entity_obj\`
+
+Create a \`${ent.Name}\` entity accessor. Pass \`Noval\` for no initial options.
+
+`)
+    })
+
+
+    Content(`#### \`Sdk_client.direct client fetchargs : value\`
+
+Make a direct HTTP request to any API endpoint. Returns a result \`value\` map
+with \`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This
+escape hatch never raises — branch on \`getp result "ok"\`.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`path\` | \`string\` | URL path with optional \`{param}\` placeholders. |
+| \`method\` | \`string\` | HTTP method (default: \`"GET"\`). |
+| \`params\` | \`map\` | Path parameter values. |
+| \`query\` | \`map\` | Query string parameters. |
+| \`headers\` | \`map\` | Request headers (merged with defaults). |
+| \`body\` | \`value\` | Request body (Maps are JSON-serialized). |
+
+**Returns:** a result \`value\` map.
+
+#### \`Sdk_client.prepare client fetchargs : value\`
+
+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 || []
+      const idF = entityIdField(ent)
+      const fn = ocamlVarName(ent.name)
+
+      Content(`
+---
+
+## ${ent.Name}
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`ocaml
+let ${fn} = Sdk_client.${fn} client Noval
+\`\`\`
+
+`)
+
+
+      // 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}\` | \`${ocamlType(field.type)}\` | ${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
+              ? `jo [${matchItems.map((it: any) =>
+                `("${it.name}", ${ocamlLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)})`).join('; ')}]`
+              : 'Noval'
+            Content(`\`\`\`ocaml
+let result = (Sdk_client.${fn} client Noval).${'load' === opname ? 'e_load' : 'e_remove'} (${arg}) Noval
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`ocaml
+let results = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+(match results with
+ | List items -> List.iter (fun r -> print_endline (stringify r)) !items
+ | _ -> ())
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`ocaml
+let result = (Sdk_client.${fn} client Noval).e_create (jo [
+`)
+            createItems.map((it: any) => {
+              Content(`    ("${it.name}", ${ocamlLit(it.type, 'example_' + it.name)});  (* ${ocamlType(it.type)} *)
+`)
+            })
+            Content(`]) Noval
+\`\`\`
+
+`)
+          }
+          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}", ${ocamlLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)});\n`).join('')
+            Content(`\`\`\`ocaml
+let result = (Sdk_client.${fn} client Noval).e_update (jo [
+${updateLines}    (* Fields to update *)
+]) Noval
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common fields
+      Content(`### Common Fields
+
+#### \`e_data_get : unit -> value\`
+
+Get the entity data.
+
+#### \`e_data_set : value -> unit\`
+
+Set the entity data.
+
+#### \`e_match_get : unit -> value\`
+
+Get the entity match criteria.
+
+#### \`e_match_set : value -> unit\`
+
+Set the entity match criteria.
+
+#### \`e_make : unit -> entity_obj\`
+
+Create a new \`${ent.Name}\` entity accessor with the same options.
+
+#### \`e_name : string\`
+
+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(`\`\`\`ocaml
+let client = Sdk_client.make (jo [
+    ("feature", jo [
+`)
+      activeFeatures.map((f: any) => {
+        Content(`        ("${f.name}", jo [("active", Bool true)]);
+`)
+      })
+      Content(`    ]);
+])
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+
+
+export {
+  ReadmeRef
+}

package/project/.sdk/src/cmp/ocaml/ReadmeTopHowto_ocaml.ts

@@ -0,0 +1,25 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**OCaml:**
+\`\`\`ocaml
+let result = Sdk_client.direct client (jo [
+    ("path", Str "/api/resource/{id}");
+    ("method", Str "GET");
+    ("params", jo [("id", Str "example")]);
+]) in
+ignore result
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

package/project/.sdk/src/cmp/ocaml/ReadmeTopQuick_ocaml.ts

@@ -0,0 +1,86 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+// A type-correct OCaml `value` literal for a param: numeric/boolean/array/
+// object params render a typed literal; strings render the quoted placeholder.
+function ocamlLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
+  if ('BOOLEAN' === k) return '(Bool true)'
+  if ('ARRAY' === k) return '(empty_list ())'
+  if ('OBJECT' === k) return '(empty_map ())'
+  return `(Str "${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 authActive = isAuthActive(model)
+  const ctor = authActive
+    ? `Sdk_client.make (jo [("apikey", Str (Sys.getenv "${envName(model)}_APIKEY"))])`
+    : `Sdk_client.make0 ()`
+
+  Content(`\`\`\`ocaml
+open Voxgig_struct
+open Sdk_helpers
+
+let () =
+  let client = ${ctor} in
+`)
+
+  if (exampleEntity) {
+    const fn = ocamlVarName(exampleEntity.name)
+    const opnames = Object.keys(exampleEntity.op || {})
+    // Model-driven id key: null when the entity has no id-like field, in which
+    // case the load example takes no match argument.
+    const idF = entityIdField(exampleEntity)
+
+    if (opnames.includes('list')) {
+      Content(`  (* List all ${fn} records (returns a List value; raises on error) *)
+  let ${fn}s = (Sdk_client.${fn} client Noval).e_list (empty_map ()) Noval in
+  (match ${fn}s with List items -> List.iter (fun r -> print_endline (stringify r)) !items | _ -> ());
+`)
+    }
+
+    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
+        ? `jo [${loadItems.map((it: any) =>
+          `("${it.name}", ${ocamlLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)})`).join('; ')}]`
+        : 'Noval'
+      Content(`  (* Load a specific ${fn} (returns the record; raises on error) *)
+  let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval in
+  print_endline (stringify ${fn})
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/ocaml/ReadmeTopTest_ocaml.ts

@@ -0,0 +1,79 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+// A type-correct OCaml `value` literal for a field's canonical type.
+function ocamlLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '(Num 1.)'
+  if ('BOOLEAN' === k) return '(Bool true)'
+  if ('ARRAY' === k) return '(empty_list ())'
+  if ('OBJECT' === k) return '(empty_map ())'
+  return '(Str "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) — never fabricate a
+  // `load` on an op-less entity.
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+
+  Content(`\`\`\`ocaml
+let () =
+  let client = Sdk_client.test () in
+`)
+
+  if (exampleEntity && primaryOp) {
+    const fn = ocamlVarName(exampleEntity.name)
+    const idF = entityIdField(exampleEntity)
+    const field =
+      'load' === primaryOp ? 'e_load' :
+        'list' === primaryOp ? 'e_list' :
+          'create' === primaryOp ? 'e_create' :
+            'update' === primaryOp ? 'e_update' : 'e_remove'
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'Noval'
+    if ('list' === primaryOp) {
+      arg = '(empty_map ())'
+    } else if (isMatchOp) {
+      // Every REQUIRED match key (id first).
+      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
+        ? `(jo [${items.map((it: any) =>
+          `("${it.name}", ${it.name === idF ? '(Str "test01")' : ocamlLit(it.type)})`).join('; ')}])`
+        : '(empty_map ())'
+    } 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 = `(jo [${chosen.map((it: any) => `("${it.name}", ${ocamlLit(it.type)})`).join('; ')}])`
+    }
+    Content(`  let result = (Sdk_client.${fn} client Noval).${field} ${arg} Noval in
+  print_endline (stringify result)
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/ocaml/Test_ocaml.ts

@@ -13,6 +13,7 @@ import { cmp, each, Folder } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_ocaml'
 import { TestDirect } from './TestDirect_ocaml'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_ocaml'
 
 
 const Test = cmp(function Test(props: any) {
@@ -26,6 +27,9 @@ const Test = cmp(function Test(props: any) {
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // Structural gate over the ```ocaml blocks in the generated docs.
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/perl/Entity_perl.ts

@@ -4,7 +4,7 @@ import * as Path from 'node:path'
 import {
   cmp, camelify, names,
   File, Folder, Fragment,
-  entityClassName,
+  entityClassName, entityCollection,
 } from '@voxgig/sdkgen'
 
 import {
@@ -22,7 +22,7 @@ const Entity = cmp(function Entity(props: any) {
   // Collision-free entity CLASS name (see entityClassName): normally
   // `<Name>Entity`, disambiguated when it would clash with another entity's
   // data-type name. The snake-cased source-file name is unaffected.
-  const entityColl = getModelPath(model, `main.${KIT}.entity`)
+  const entityColl = entityCollection(model)
   const cls = entityClassName(entity, entityColl)
 
   const entrep = {
@@ -38,7 +38,7 @@ const Entity = cmp(function Entity(props: any) {
 
     File({ name: entity.name + '_entity.pm' }, () => {
 
-      const opnames = Object.keys(entity.op)
+      const opnames = Object.keys(entity.op || {})
 
       const opfrags =
         (['load', 'list', 'create', 'update', 'remove']

package/project/.sdk/src/cmp/perl/MainEntity_perl.ts

@@ -1,6 +1,6 @@
 
 
-import { cmp, Content, entityClassName } from '@voxgig/sdkgen'
+import { cmp, Content, entityClassName, entityCollection } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -14,7 +14,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
 
   // Return the collision-free class (entityClassName); the accessor METHOD
   // name (entity.Name) is unchanged so callers still write $client->{Name}.
-  const cls = entityClassName(entity, getModelPath(model, `main.${KIT}.entity`))
+  const cls = entityClassName(entity, entityCollection(model))
 
   Content(`
 # Canonical facade: $client->${entity.Name}->list / ->load({ 'id' => ... })

package/project/.sdk/src/cmp/perl/Package_perl.ts

@@ -27,7 +27,7 @@ const Package = cmp(async function Package(props: any) {
   // (e.g. "Voxgig::SDK::Solar" -> dist voxgig-sdk-solar).
   const Name = model.const.Name
 
-  const deps = collectDeps(model, target.name, target.deps)
+  const deps = collectDeps(model, target.name, target.deps, ctx$.log)
   const prereq = deps
     .map((d: any) => `        '${d.name}' => '${d.version || '0'}',`)
     .join('\n')