@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/clojure/ReadmeRef_clojure.ts

@@ -0,0 +1,409 @@
+
+import { cmp, each, Content, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// A type-correct Clojure literal for a field's canonical type.
+function cljLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '(vs/jt)'
+  if ('OBJECT' === k) return '(vs/jm)'
+  return `"${placeholder}"`
+}
+
+
+// A descriptive Clojure-ish type name (documentation hint, not a static type).
+function cljType(type: any): string {
+  const k = canonKey(type)
+  if ('STRING' === k) return 'string'
+  if ('INTEGER' === k) return 'long'
+  if ('NUMBER' === k) return 'double'
+  if ('BOOLEAN' === k) return 'boolean'
+  if ('ARRAY' === k) return 'vector'
+  if ('OBJECT' === k) return 'map'
+  return 'any'
+}
+
+
+const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
+  load: {
+    sig: '(load ent reqmatch ctrl) -> map',
+    returns: 'the entity data',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and raises on error.',
+  },
+  list: {
+    sig: '(list ent reqmatch ctrl) -> vector',
+    returns: 'a vector of entities',
+    desc: 'List entities matching the given criteria. The match is optional — call with `nil` to list all records. Returns a vector and raises on error.',
+  },
+  create: {
+    sig: '(create ent reqdata ctrl) -> map',
+    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 ent reqdata ctrl) -> map',
+    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 ent reqmatch ctrl) -> map',
+    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.
+
+
+## Client
+
+### make-sdk
+
+`)
+
+    Content(`\`\`\`clojure
+(require '[sdk.api :as api]
+         '[voxgig.struct :as vs])
+
+(def client (api/make-sdk options))
+\`\`\`
+
+Create a new SDK client instance. \`options\` is a \`voxgig.struct\` map.
+
+**Options:**
+
+| Key | Type | Description |
+| --- | --- | --- |
+${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(`
+### Test client
+
+`)
+
+    Content(`#### \`(api/test-sdk testopts sdkopts)\`
+
+Create a test client with mock features active. Both arguments may be \`nil\`.
+
+\`\`\`clojure
+(def client (api/test-sdk nil nil))
+\`\`\`
+
+`)
+
+
+    Content(`
+### Client functions
+
+`)
+
+
+    // Entity factory functions
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`(api/${ent.name} client data)\`
+
+Create a new \`${ent.Name}\` entity instance. Pass \`nil\` for no initial data.
+
+`)
+    })
+
+
+    Content(`#### \`(api/options-map client) -> map\`
+
+Return a deep copy of the current SDK options.
+
+#### \`(api/get-utility client) -> utility\`
+
+Return a copy of the SDK utility object.
+
+#### \`(api/direct client fetchargs) -> map\`
+
+Make a direct HTTP request to any API endpoint. Returns a result \`map\` with \`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This escape hatch never raises — branch on \`(vs/getprop result "ok")\`.
+
+**Fetch args:**
+
+| Key | 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\` | \`any\` | Request body (maps are JSON-serialized). |
+
+**Returns:** a result \`map\`.
+
+#### \`(api/prepare client fetchargs) -> map\`
+
+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)
+      const eLow = ent.name
+
+      Content(`
+---
+
+## ${ent.Name}
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`clojure
+(require '[sdk.entity.${eLow} :as e-${eLow}])
+
+(def ${eLow} (api/${eLow} client nil))
+\`\`\`
+
+`)
+
+
+      // 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}\` | \`${cljType(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
+              ? `(vs/jm ${matchItems.map((it: any) =>
+                `"${it.name}" ${cljLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(' ')})`
+              : 'nil'
+            Content(`\`\`\`clojure
+(def result (e-${eLow}/${opname} (api/${eLow} client nil) ${arg} nil))
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`clojure
+(doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) nil nil)]
+  (println ${eLow}))
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`clojure
+(def result
+  (e-${eLow}/create (api/${eLow} client nil)
+    (vs/jm
+`)
+            createItems.map((it: any) => {
+              Content(`      "${it.name}" ${cljLit(it.type, 'example_' + it.name)}  ;; ${cljType(it.type)}
+`)
+            })
+            Content(`      )
+    nil))
+\`\`\`
+
+`)
+          }
+          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}" ${cljLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)}\n`).join('')
+            Content(`\`\`\`clojure
+(def result
+  (e-${eLow}/update (api/${eLow} client nil)
+    (vs/jm
+${updateLines}      ;; Fields to update
+      )
+    nil))
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common methods
+      Content(`### Common Members
+
+State accessors are stored on the entity map and called via keyword lookup.
+
+#### \`((:data-get ent)) -> map\`
+
+Get the entity data.
+
+#### \`((:data-set ent) data)\`
+
+Set the entity data.
+
+#### \`((:match-get ent)) -> map\`
+
+Get the entity match criteria.
+
+#### \`((:match-set ent) match)\`
+
+Set the entity match criteria.
+
+#### \`((:make ent)) -> entity\`
+
+Create a new \`${ent.Name}\` entity instance with the same options.
+
+#### \`((:get-name ent)) -> 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(`\`\`\`clojure
+(def client
+  (api/make-sdk
+    (vs/jm "feature"
+      (vs/jm
+`)
+      activeFeatures.map((f: any) => {
+        Content(`        "${f.name}" (vs/jm "active" true)
+`)
+      })
+      Content(`        ))))
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+
+
+export {
+  ReadmeRef
+}

package/project/.sdk/src/cmp/clojure/ReadmeTopHowto_clojure.ts

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**Clojure:**
+\`\`\`clojure
+(def result
+  (api/direct client
+    (vs/jm "path" "/api/resource/{id}"
+           "method" "GET"
+           "params" (vs/jm "id" "example"))))
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

package/project/.sdk/src/cmp/clojure/ReadmeTopQuick_clojure.ts

@@ -0,0 +1,98 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+// A type-correct Clojure literal for a param: numeric/boolean/array/object
+// params render a typed literal; strings render the quoted placeholder.
+function cljLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '(vs/jt)'
+  if ('OBJECT' === k) return '(vs/jm)'
+  return `"${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
+    ? `(api/make-sdk (vs/jm "apikey" (System/getenv "${envName(model)}_APIKEY")))`
+    : `(api/make-sdk nil)`
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const eLow = exampleEntity.name
+
+    Content(`\`\`\`clojure
+(require '[sdk.api :as api]
+         '[sdk.entity.${eLow} :as e-${eLow}]
+         '[voxgig.struct :as vs])
+
+(def client ${ctor})
+
+`)
+
+    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 ${eLow}s (returns a vector, raises on error)
+(doseq [${eLow} (e-${eLow}/list (api/${eLow} client nil) nil nil)]
+  (println ${eLow}))
+`)
+    }
+
+    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
+        ? `(vs/jm ${loadItems.map((it: any) =>
+          `"${it.name}" ${cljLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(' ')})`
+        : 'nil'
+      Content(`
+;; Load a specific ${eLow} (returns the record, raises on error)
+(def ${eLow} (e-${eLow}/load (api/${eLow} client nil) ${loadArg} nil))
+(println ${eLow})
+`)
+    }
+
+    Content(`\`\`\`
+`)
+  }
+  else {
+    Content(`\`\`\`clojure
+(require '[sdk.api :as api]
+         '[voxgig.struct :as vs])
+
+(def client ${ctor})
+\`\`\`
+`)
+  }
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/clojure/ReadmeTopTest_clojure.ts

@@ -0,0 +1,78 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// A type-correct Clojure literal for a field's canonical type.
+function cljLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return 'true'
+  if ('ARRAY' === k) return '(vs/jt)'
+  if ('OBJECT' === k) return '(vs/jm)'
+  return '"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(`\`\`\`clojure
+(require '[sdk.api :as api]
+`)
+  if (exampleEntity && primaryOp) {
+    Content(`         '[sdk.entity.${exampleEntity.name} :as e-${exampleEntity.name}]
+`)
+  }
+  Content(`         '[voxgig.struct :as vs])
+
+(def client (api/test-sdk nil nil))
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eLow = exampleEntity.name
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = 'nil'
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's match handling.
+      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
+        ? `(vs/jm ${items.map((it: any) =>
+          `"${it.name}" ${it.name === idF ? '"test01"' : cljLit(it.type)}`).join(' ')})`
+        : 'nil'
+    } 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 = `(vs/jm ${chosen.map((it: any) => `"${it.name}" ${cljLit(it.type)}`).join(' ')})`
+    }
+    const eVar = eLow + ('list' === primaryOp ? 's' : '')
+    Content(`(def ${eVar} (e-${eLow}/${primaryOp} (api/${eLow} client nil) ${arg} nil))
+(println ${eVar})
+`)
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/clojure/TestDirect_clojure.ts

@@ -0,0 +1,58 @@
+
+import {
+  Content,
+  cmp,
+  isAuthActive,
+} from '@voxgig/sdkgen'
+
+
+// Emit per-entity direct()/prepare() checks INTO the shared gentest run body
+// (the clojure test runner drives a single sdk.gentest/run). Only entities
+// with a read op get a check — matching the py/elixir TestDirect gate — so an
+// op-less entity does not fabricate a request path. The checks exercise the
+// raw-HTTP escape hatch: prepare() builds a fetchdef without sending, and
+// direct() runs a live-mode client against an in-test mock system.fetch.
+const TestDirect = cmp(function TestDirect(props: any) {
+  const { model } = props.ctx$
+  const entity = props.entity
+
+  const opnames = Object.keys(entity.op || {})
+  const hasLoad = opnames.includes('load')
+  const hasList = opnames.includes('list')
+  if (!hasLoad && !hasList) {
+    return
+  }
+
+  const ename = entity.name
+  // A live-mode client must satisfy prepare-auth when auth is active, so pass a
+  // dummy apikey; otherwise prepare() (and thus direct()) would throw.
+  const apikeyOpt = isAuthActive(model) ? ` "apikey" "test-key"` : ''
+
+  // prepare(): pure request-definition build, no transport.
+  Content(`  (t/run-check rec "gen-prepare-${ename}"
+    (fn [] (let [client (api/make-sdk (vs/jm "base" "http://example.test"${apikeyOpt}))
+                 fetchdef (api/prepare client (vs/jm "path" "/api/${ename}" "method" "GET"))]
+             (t/is-true (vs/ismap fetchdef) "prepare returns a fetchdef map")
+             (t/is-some (vs/getprop fetchdef "url") "fetchdef carries a url")
+             (t/is-eq (vs/getprop fetchdef "method") "GET" "fetchdef preserves the method"))))
+`)
+
+  // direct(): live-mode client wired to a recording mock system.fetch. The
+  // mock returns a 200 JSON response, so direct() reports ok=true.
+  Content(`  (t/run-check rec "gen-direct-${ename}"
+    (fn [] (let [fetch (fn [_url _fetchdef]
+                         [(vs/jm "status" 200 "statusText" "OK" "headers" (vs/jm)
+                                 "json" (fn [] (vs/jm "id" "d1"))) nil])
+                 client (api/make-sdk (vs/jm "base" "http://example.test"${apikeyOpt}
+                                             "system" (vs/jm "fetch" fetch)))
+                 result (api/direct client (vs/jm "path" "/api/${ename}" "method" "GET"))]
+             (t/is-true (vs/ismap result) "direct returns a result map")
+             (t/is-true (vs/getprop result "ok") "direct 200 => ok true")
+             (t/is-eq (vs/getprop result "status") 200 "direct surfaces the status"))))
+`)
+})
+
+
+export {
+  TestDirect
+}