@voxgig/sdkgen 1.3.14 → 1.3.18

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

@@ -0,0 +1,155 @@
+
+import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+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)
+
+  // Model-driven op rows for the shared entity interface: emit a row only for
+  // operations at least one active entity actually exposes.
+  const opUnion = new Set<string>()
+  entityList.forEach((e: any) => Object.keys(e.op || {})
+    .forEach((o: string) => { if (e.op[o] && e.op[o].active !== false) opUnion.add(o) }))
+  const opRowDefs: Record<string, string> = {
+    load: '| `e_load` | `value -> value -> value` | Load a single entity by match criteria. Raises on error. |',
+    list: '| `e_list` | `value -> value -> value` | List entities matching the criteria (returns a List). Raises on error. |',
+    create: '| `e_create` | `value -> value -> value` | Create a new entity. Raises on error. |',
+    update: '| `e_update` | `value -> value -> value` | Update an existing entity. Raises on error. |',
+    remove: '| `e_remove` | `value -> value -> value` | Remove an entity. Raises on error. |',
+  }
+  const opRows = ['load', 'list', 'create', 'update', 'remove']
+    .filter((o) => opUnion.has(o)).map((o) => opRowDefs[o]).join('\n')
+
+  const apikeyOptionRow = isAuthActive(model)
+    ? '| `apikey` | `string` | API key for authentication. |\n'
+    : ''
+
+  Content(`### Sdk_client
+
+\`\`\`ocaml
+open Voxgig_struct
+open Sdk_helpers
+
+let client = Sdk_client.make options
+\`\`\`
+
+Creates a new SDK client from a \`value\` options map. Use \`Sdk_client.make0 ()\`
+for defaults.
+
+| Option | Type | Description |
+| --- | --- | --- |
+${apikeyOptionRow}| \`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\` | Feature activation flags. |
+| \`extend\` | \`list\` | Additional feature instances to load. |
+| \`system\` | \`map\` | System overrides (e.g. custom \`fetch\` function). |
+
+### Sdk_client.test
+
+\`\`\`ocaml
+let client = Sdk_client.test_with testopts sdkopts
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be \`Noval\`
+(\`Sdk_client.test ()\` uses defaults).
+
+### Sdk_client functions
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| \`make\` | \`value -> sdk_client\` | Construct a client from options. |
+| \`make0\` | \`unit -> sdk_client\` | Construct a client with defaults. |
+| \`prepare\` | \`sdk_client -> value -> value\` | Build an HTTP request definition without sending. Raises on error. |
+| \`direct\` | \`sdk_client -> value -> value\` | Build and send an HTTP request. Returns a result map (branch on \`ok\`). |
+`)
+
+  each(entityList, (ent: any) => {
+    const fn = ocamlVarName(ent.name)
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${fn}\` | \`sdk_client -> value -> entity_obj\` | ${article.charAt(0).toUpperCase() + article.slice(1)} ${ent.Name} entity accessor. |
+`)
+  })
+
+  Content(`
+### Entity interface
+
+All entities are \`entity_obj\` records sharing the same fields.
+
+| Field | Signature | Description |
+| --- | --- | --- |
+${opRows}
+| \`e_data_get\` | \`unit -> value\` | Get entity data. |
+| \`e_data_set\` | \`value -> unit\` | Set entity data. |
+| \`e_match_get\` | \`unit -> value\` | Get entity match criteria. |
+| \`e_match_set\` | \`value -> unit\` | Set entity match criteria. |
+| \`e_make\` | \`unit -> entity_obj\` | Create a new instance with the same options. |
+| \`e_name\` | \`string\` | The entity name. |
+
+### Result shape
+
+Entity operations return the bare result value (a \`Map\` for single-entity
+ops, a \`List\` for \`e_list\`) and raise \`Sdk_error.E\` on error. Wrap calls
+in \`try\`/\`with\` to handle failures.
+
+The \`direct\` escape hatch never raises — it returns a result \`value\` map
+you branch on via \`getp result "ok"\`:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`Bool\` | \`Bool true\` if the HTTP status is 2xx. |
+| \`status\` | \`Num\` | HTTP status code. |
+| \`headers\` | \`Map\` | Response headers. |
+| \`data\` | \`value\` | Parsed JSON response body. |
+
+On error, \`ok\` is \`Bool false\` and \`err\` carries 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/ocaml/ReadmeOptions_ocaml.ts

@@ -0,0 +1,59 @@
+
+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 as a \`value\` map when creating a client:
+
+`)
+
+  Content(`\`\`\`ocaml
+let client = Sdk_client.make (jo [
+`)
+
+  publishedOptions.map((option: any) => {
+    if ('apikey' === option.name) {
+      Content(`  ("${option.name}", Str (Sys.getenv "${envName(model)}_APIKEY"));
+`)
+    }
+    else {
+      Content(`  (* ("${option.name}", ${option.kind === 'string' ? 'Str "..."' : '(* ... *)'}); *)
+`)
+    }
+  })
+
+  Content(`])
+\`\`\`
+
+`)
+
+  Content(`| Option | Type | Description |
+| --- | --- | --- |
+`)
+
+  publishedOptions.map((option: any) => {
+    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
+`)
+  })
+
+  Content(`
+`)
+})
+
+
+export {
+  ReadmeOptions
+}

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

@@ -0,0 +1,205 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, opRequestShape, entityIdField, entityDataIdField, entityOps } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+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, an active load
+  // op, and a required non-id load param to demonstrate (the parent key).
+  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
+    ? `Sdk_client.make (jo [("apikey", Str (Sys.getenv "${envName(model)}_APIKEY"))])`
+    : `Sdk_client.make0 ()`
+
+  Content(`### 1. Create a client
+
+\`\`\`ocaml
+open Voxgig_struct
+open Sdk_helpers
+
+let client = ${ctor}
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
+    const fn = ocamlVarName(exampleEntity.name)
+    const opnames = entityOps(exampleEntity)
+    // Model-driven id key: `idF` is the entity's id-like MATCH field, or null.
+    // `dataIdF` is the id on the RETURNED record's data type.
+    const idF = entityIdField(exampleEntity)
+    const dataIdF = entityDataIdField(exampleEntity)
+
+    // A type-correct OCaml `value` literal for a param.
+    const 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}")`
+    }
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${fn} records
+
+\`e_list\` returns a \`List\` value of records (each a \`Map\`) and raises on
+error — iterate it directly.
+
+\`\`\`ocaml
+(try
+   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
+    | _ -> ())
+ with Sdk_error.E err -> Printf.eprintf "list failed: %s\\n" (Sdk_error.message err))
+\`\`\`
+
+`)
+    }
+
+    if (nestedEntity) {
+      const neName = nom(nestedEntity, 'Name')
+      const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
+      const neFn = ocamlVarName(nestedEntity.name)
+
+      // Model-driven match: every REQUIRED load-match key. Parent keys 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}", ${ocamlLit(it.type,
+          it.name === neIdF ? 'example_id' : 'example_' + it.name)})`)
+
+      Content(`### 3. Load ${neArticle} ${neFn}
+
+${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
+\`e_load\` returns the bare record (a \`Map\`) and raises on error.
+
+\`\`\`ocaml
+(try
+   let ${neFn} = (Sdk_client.${neFn} client Noval).e_load (jo [${neMatch.join('; ')}]) Noval in
+   print_endline (stringify ${neFn})
+ with Sdk_error.E err -> Printf.eprintf "load failed: %s\\n" (Sdk_error.message err))
+\`\`\`
+
+`)
+    }
+    else if (opnames.includes('load')) {
+      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
+        ? `jo [${loadRequired.map((it: any) =>
+          `("${it.name}", ${ocamlLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)})`).join('; ')}]`
+        : 'Noval'
+
+      Content(`### 3. Load ${article} ${fn}
+
+\`e_load\` returns the bare record (a \`Map\`) and raises on error.
+
+\`\`\`ocaml
+(try
+   let ${fn} = (Sdk_client.${fn} client Noval).e_load (${loadArg}) Noval in
+   print_endline (stringify ${fn})
+ with Sdk_error.E err -> Printf.eprintf "load failed: %s\\n" (Sdk_error.message err))
+\`\`\`
+
+`)
+    }
+
+    // Model-driven example fields: derive the create/update body from the op
+    // shape 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}", ${ocamlLit(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
+    }
+    const idValueFor = (opname: string): string => (null != dataIdF && opnames.includes('create'))
+      ? `(getp created "${dataIdF}")`
+      : ocamlLit(idParamType(opname), 'example_id')
+
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
+
+\`\`\`ocaml
+`)
+      if (opnames.includes('create')) {
+        Content(`(* Create — returns the bare created record (a Map) *)
+let created = (Sdk_client.${fn} client Noval).e_create (jo [${examplePairs('create').join('; ')}]) Noval in
+ignore created;
+
+`)
+      }
+      if (opnames.includes('update')) {
+        const updatePairs = (idF ? [`("${idF}", ${idValueFor('update')})`] : []).concat(examplePairs('update'))
+        Content(`(* Update *)
+ignore ((Sdk_client.${fn} client Noval).e_update (jo [${updatePairs.join('; ')}]) Noval);
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        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}", ${idValueFor('remove')})`
+            : `("${it.name}", ${ocamlLit(it.type, 'example_' + it.name)})`)
+        Content(`(* Remove *)
+ignore ((Sdk_client.${fn} client Noval).e_remove (${removePairs.length ? `jo [${removePairs.join('; ')}]` : 'Noval'}) Noval)
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeQuick
+}