@voxgig/sdkgen 1.3.14 → 1.3.17

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

@@ -0,0 +1,111 @@
+
+import { cmp, Content, File } from '@voxgig/sdkgen'
+
+
+// Emits test/readme_examples_test.ml — a structural gate over every ```ocaml
+// fenced block in the three docs that ship ocaml examples:
+//   - the root README.md (top-level, multi-language quick start)
+//   - the per-language ocaml/README.md
+//   - the per-language ocaml/REFERENCE.md
+//
+// DESIGN NOTE (mirrors ReadmeExamplesTest_rust): the py gate shells out to a
+// python subprocess to COMPILE + EXECUTE every block. A faithful ocaml port
+// would shell out to `ocamlc` against each extracted snippet — a large,
+// environment-sensitive harness that cannot be authored safely without a build
+// to validate it (and the generated SDK ships a dependency-free stock-ocamlc
+// build, no doc-test tooling). This gate instead validates that every
+// documented ocaml block is PRESENT and STRUCTURALLY well-formed (balanced
+// delimiters, non-empty). It is a real, always-passing test that keeps the docs
+// honest about block structure; upgrading it to a true compile gate (a temp
+// project that `ocamlc`s each block against the generated SDK) is a follow-up.
+// Missing docs are tolerated (a run may generate a subset of phases).
+const ReadmeExamplesTest = cmp(function ReadmeExamplesTest(props: any) {
+  const { target, ctx$: { model } } = props
+
+  File({ name: 'readme_examples_test.' + target.ext }, () => {
+    Content(`(* Structural gate over every \`\`\`ocaml block in the ${model.const.Name} SDK
+ * docs (root README.md, ocaml/README.md, ocaml/REFERENCE.md). Generated by
+ * @voxgig/sdkgen — do not edit by hand.
+ *
+ * Validates that each documented ocaml block is present, non-empty, and has
+ * balanced delimiters. Missing docs are tolerated. See ReadmeExamplesTest_ocaml
+ * for why this is a structural gate rather than a full compile harness. *)
+
+open Testutil
+
+let fence = "\`\`\`ocaml"
+let close_fence = "\`\`\`"
+
+let trim = String.trim
+
+(* Read a whole file, or None when it is absent (a doc not generated). *)
+let read_file (path : string) : string option =
+  try Some (In_channel.with_open_text path In_channel.input_all)
+  with Sys_error _ -> None
+
+let split_lines (s : string) : string list = String.split_on_char '\\n' s
+
+(* Extract the body of every \`\`\`ocaml ... \`\`\` fenced block from markdown. *)
+let extract_ocaml_blocks (md : string) : string list =
+  let blocks = ref [] in
+  let cur = ref [] in
+  let in_block = ref false in
+  List.iter (fun line ->
+      let t = trim line in
+      if not !in_block then begin
+        if t = fence then begin in_block := true; cur := [] end
+      end
+      else if t = close_fence then begin
+        blocks := String.concat "\\n" (List.rev !cur) :: !blocks;
+        in_block := false
+      end
+      else cur := line :: !cur)
+    (split_lines md);
+  List.rev !blocks
+
+(* Balanced (), [], {} outside of string literals. Naive quote toggle: the
+ * generated snippets never embed an escaped quote inside a string. *)
+let is_balanced (block : string) : bool =
+  let in_str = ref false in
+  let depth = ref 0 in
+  let ok = ref true in
+  String.iter (fun c ->
+      if c = '"' then in_str := not !in_str
+      else if not !in_str then
+        match c with
+        | '(' | '[' | '{' -> incr depth
+        | ')' | ']' | '}' -> decr depth; if !depth < 0 then ok := false
+        | _ -> ())
+    block;
+  !ok && !depth = 0 && not !in_str
+
+let docs = [
+  ("root README", "../README.md");
+  ("ocaml/README", "README.md");
+  ("ocaml/REFERENCE", "REFERENCE.md");
+]
+
+let () =
+  test "readme.ocaml_snippets_wellformed" (fun () ->
+      let total = ref 0 in
+      List.iter (fun (label, path) ->
+          match read_file path with
+          | None -> ()   (* doc not generated in this run — tolerate *)
+          | Some src ->
+            List.iteri (fun i block ->
+                check (label ^ " block " ^ string_of_int (i + 1) ^ " non-empty")
+                  (trim block <> "");
+                check (label ^ " block " ^ string_of_int (i + 1) ^ " balanced delimiters")
+                  (is_balanced block);
+                incr total)
+              (extract_ocaml_blocks src))
+        docs;
+      check "at least one ocaml code block across the docs" (!total > 0))
+`)
+  })
+})
+
+
+export {
+  ReadmeExamplesTest
+}

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

@@ -0,0 +1,46 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as \`value\`
+
+The OCaml SDK uses a single dynamic \`value\` type throughout rather than a
+typed record per entity. \`value\` is the vendored voxgig struct port (a
+JSON-shaped variant: \`Str\`, \`Num\`, \`Bool\`, \`List\`, \`Map\`, \`Null\`,
+\`Noval\`). This mirrors the dynamic nature of the API and keeps the SDK
+flexible — no code generation is needed when the API schema changes.
+
+Build request maps with the \`jo\` / \`ja\` helpers and read fields back with
+\`getp\`; use \`to_map\` to safely coerce a value to a map.
+
+### Module structure
+
+\`\`\`
+${target.name}/
+├── sdk_client.ml               -- Main SDK client (constructors + accessors)
+├── sdk_config.ml               -- Embedded API config + feature factory
+├── sdk_error.ml                -- Branded error re-exports
+├── sdk_entity_*.ml             -- Per-entity implementations (one each)
+├── sdk_types.ml                -- Core pipeline types
+├── sdk_helpers.ml              -- jo / ja / getp and friends
+├── sdk_runtime.ml              -- Operation pipeline runner
+├── sdk_features.ml             -- Built-in features (base, test, log)
+├── utility/                    -- Vendored voxgig struct port
+└── test/                       -- Test suites
+\`\`\`
+
+The public surface lives in \`Sdk_client\` (the constructors and per-entity
+accessors); \`Sdk_helpers\` carries the \`jo\` / \`ja\` / \`getp\` value
+helpers. Open the runtime modules directly only when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,147 @@
+
+import { cmp, Content, isAuthActive, envName, 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 ReadmeHowto = cmp(function ReadmeHowto(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. primaryOp is null only when NO entity exposes
+  // any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const fn = exampleEntity ? ocamlVarName(exampleEntity.name) : 'entity'
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const field = primaryOp
+    ? ('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 testArg = 'Noval'
+  if (exampleEntity && 'list' === primaryOp) {
+    testArg = '(empty_map ())'
+  } else if (exampleEntity && isMatchOp) {
+    testArg = idF ? `(jo [("${idF}", Str "test01")])` : '(empty_map ())'
+  } else if (exampleEntity && ('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)
+    testArg = `(jo [${chosen.map((it: any) => `("${it.name}", ${ocamlLit(it.type)})`).join('; ')}])`
+  }
+
+  // The op-driven test-mode line, shown only when the SDK has an entity op.
+  // A direct()-only SDK (no ops anywhere) shows a direct() call instead.
+  const testModeExample = primaryOp
+    ? `(* Entity ops return the bare record and raise on error. *)
+  let ${fn} = (Sdk_client.${fn} client Noval).${field} ${testArg} Noval in
+  print_endline (stringify ${fn})  (* the mock response record *)`
+    : `let result = Sdk_client.direct client (jo [("path", Str "/api/resource"); ("method", Str "GET")]) in
+  print_endline (stringify result)`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`ocaml
+let result = Sdk_client.direct client (jo [
+    ("path", Str "/api/resource/{id}");
+    ("method", Str "GET");
+    ("params", jo [("id", Str "example")]);
+]) in
+(match getp result "ok" with
+ | Bool true ->
+   print_endline (stringify (getp result "status"));  (* 200 *)
+   print_endline (stringify (getp result "data"))      (* response body *)
+ | _ ->
+   (* A non-2xx response carries status + data (the error body); a transport
+      failure carries err instead. Read whichever is present. *)
+   print_endline (stringify (getp result "status"));
+   print_endline (stringify (getp result "err")))
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`ocaml
+(* prepare returns the fetch definition and raises on error. *)
+let fetchdef = Sdk_client.prepare client (jo [
+    ("path", Str "/api/resource/{id}");
+    ("method", Str "DELETE");
+    ("params", jo [("id", Str "example")]);
+]) in
+print_endline (stringify (getp fetchdef "url"));
+print_endline (stringify (getp fetchdef "method"));
+print_endline (stringify (getp fetchdef "headers"))
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`ocaml
+let () =
+  let client = Sdk_client.test () in
+  ${testModeExample}
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function:
+
+\`\`\`ocaml
+let mock_fetch = Func (fun _ _args _ _ ->
+    jo [("status", Num 200.); ("statusText", Str "OK"); ("headers", empty_map ());
+        ("json", json_thunk (jo [("id", Str "mock01")]))]) in
+let client = Sdk_client.make (jo [
+    ("base", Str "http://localhost:8080");
+    ("system", jo [("fetch", mock_fetch)]);
+]) in
+ignore client
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd ${target.name} && make test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

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

@@ -0,0 +1,44 @@
+
+import { cmp, Content, installCommand, isPublished, repoInfo } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  if (isPublished(model, target.name)) {
+    Content(`\`\`\`bash
+${installCommand(model, target.name)}
+\`\`\`
+
+Or build from a source checkout — the SDK is dependency-free and compiles
+with the stock \`ocamlc\` (no opam packages, no dune):
+
+\`\`\`bash
+cd ${target.name} && make build
+\`\`\`
+
+`)
+    return
+  }
+
+  // Publish pending: not yet on the opam registry. Build from the git release
+  // tag or from a local source checkout. The generated library is
+  // dependency-free — a plain `make build` (stock `ocamlc`) is all it needs.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to the opam registry. Install it from the
+GitHub release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl}))
+or from a source checkout. The SDK is dependency-free and compiles with the
+stock \`ocamlc\` — no opam packages, no dune:
+
+\`\`\`bash
+cd ${target.name} && make build
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

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

@@ -0,0 +1,68 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { ocamlVarName } from './utility_ocaml'
+
+
+const ReadmeIntro = cmp(function ReadmeIntro(props: any) {
+  const { target, ctx$: { model } } = props
+  const info = (model.main && model.main.kit && model.main.kit.info) || {}
+  const tagline = info.tagline || ''
+
+  Content(`# ${model.Name} ${target.title} SDK
+
+${tagline}
+
+The ${target.title} SDK for the ${model.Name} API — an entity-oriented client
+following idiomatic OCaml conventions (a dependency-free library that compiles
+with the stock \`ocamlc\`).
+
+`)
+
+  // Emphasise the entity-oriented design: the SDK surfaces the API as
+  // capitalised, semantic Entities with a small, uniform verb set rather
+  // than raw URL paths and query strings. The example entity name is
+  // derived from the model, never hardcoded.
+  const entity = getModelPath(model, `main.${KIT}.entity`)
+  const exampleEntity = Object.values(entity || {})
+    .find((e: any) => e.active !== false) as any
+  const example = exampleEntity
+    ? `for example \`Sdk_client.${ocamlVarName(exampleEntity.name)} client Noval\` — each`
+    : 'each'
+
+  // Model-driven op list — only the operations the active entities actually
+  // expose (a read-only entity has just list+load); never claim
+  // create/update/remove exist when no entity has them.
+  const CANON_OPS = ['list', 'load', 'create', 'update', 'remove']
+  const opSet = new Set<string>()
+  Object.values(entity || {}).forEach((e: any) => {
+    if (!e || e.active === false) return
+    Object.keys(e.op || {}).forEach((o: string) => {
+      if (e.op[o] && e.op[o].active !== false) opSet.add(o)
+    })
+  })
+  const opNames = CANON_OPS.filter((o) => opSet.has(o))
+    .concat([...opSet].filter((o) => !CANON_OPS.includes(o)))
+  const opList = (opNames.length ? opNames : ['list', 'load'])
+    .map((o) => '`' + o + '`').join(', ')
+
+  Content(`The SDK exposes the API as capitalised, semantic **Entities** — ${example}
+carrying a small, uniform set of operations (${opList}) instead of raw URL
+paths and query strings. You work with named resources and verbs, which
+keeps the cognitive load low.
+
+> Other languages, the CLI, and MCP server live alongside this one — see
+> the [top-level README](../README.md).
+
+`)
+})
+
+
+export {
+  ReadmeIntro
+}

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
+}