@voxgig/sdkgen 1.3.13 → 1.3.17

package/project/.sdk/src/cmp/haskell/ReadmeHowto_haskell.ts

@@ -0,0 +1,168 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { hsVarName } from './utility_haskell'
+
+
+// A type-correct Haskell `Value` literal for a field's canonical type.
+function hsLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return 'VNum 1'
+  if ('BOOLEAN' === k) return 'VBool True'
+  if ('ARRAY' === k || 'OBJECT' === k) return 'VNoval'
+  return 'VStr "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). primaryOp is null only
+  // when NO entity exposes any op (a direct()-only SDK).
+  const { entity: exampleEntity, primaryOp } = pickExampleEntity(entity)
+  const eName = exampleEntity ? nom(exampleEntity, 'Name') : 'Entity'
+  const eFn = exampleEntity ? hsVarName(exampleEntity.name) : 'entity'
+  const idF = exampleEntity ? entityIdField(exampleEntity) : null
+  const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+  let testArgExpr = 'emptyMap'
+  if (exampleEntity && isMatchOp) {
+    testArgExpr = idF ? `jo [("${idF}", VStr "test01")]` : 'emptyMap'
+  } 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)
+    testArgExpr = `jo [${chosen.map((it: any) => `("${it.name}", ${hsLit(it.type)})`).join(', ')}]`
+  }
+
+  // The op-driven test-mode line, shown only when the SDK has an entity op.
+  const testModeExample = primaryOp
+    ? `  ent <- Sdk.${eFn} sdk VNoval
+  arg <- ${testArgExpr}
+  ctrl <- emptyMap
+  -- Entity ops return the bare record and raise on error.
+  ${eFn} <- Sdk.e${primaryOp.charAt(0).toUpperCase() + primaryOp.slice(1)} ent arg ctrl
+  print ${eFn}`
+    : `  args <- jo [("path", VStr "/api/resource"), ("method", VStr "GET")]
+  result <- F.direct sdk args
+  print result`
+
+  const apikeyEnvLine = isAuthActive(model)
+    ? `\n${envName(model)}_APIKEY=<your-key>`
+    : ''
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity accessors, use \`direct\` — it never
+raises and returns a result \`Value\` you branch on via its \`ok\` field:
+
+\`\`\`haskell
+import qualified SdkClient as Sdk
+import qualified SdkFeatures as F
+import VoxgigStruct (Value (..))
+import SdkHelpers (jo, getp)
+
+main :: IO ()
+main = do
+  sdk <- Sdk.newSdk0
+  params <- jo [("id", VStr "example")]
+  args <- jo [("path", VStr "/api/resource/{id}"), ("method", VStr "GET"), ("params", params)]
+  result <- F.direct sdk args
+  ok <- getp result "ok"
+  case ok of
+    VBool True -> do
+      status <- getp result "status"   -- e.g. VNum 200
+      body <- getp result "data"       -- the response body
+      print (status, body)
+    _ -> do
+      -- A non-2xx response carries status + data (the error body); a
+      -- transport-level failure carries err instead.
+      status <- getp result "status"
+      err <- getp result "err"
+      print (status, err)
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`haskell
+import qualified SdkClient as Sdk
+import qualified SdkFeatures as F
+import VoxgigStruct (Value (..))
+import SdkHelpers (jo, getp)
+
+main :: IO ()
+main = do
+  sdk <- Sdk.newSdk0
+  params <- jo [("id", VStr "example")]
+  args <- jo [("path", VStr "/api/resource/{id}"), ("method", VStr "DELETE"), ("params", params)]
+  -- prepare returns the fetch definition and raises on error.
+  fetchdef <- F.prepare sdk args
+  url <- getp fetchdef "url"
+  method <- getp fetchdef "method"
+  print (url, method)
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`haskell
+import qualified SdkClient as Sdk
+import qualified SdkFeatures as F
+import VoxgigStruct (Value (..), emptyMap)
+import SdkHelpers (jo)
+
+main :: IO ()
+main = do
+  sdk <- Sdk.testSdk0
+${testModeExample}
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own \`VFunc\` under \`system.fetch\`:
+
+\`\`\`haskell
+import qualified SdkClient as Sdk
+import VoxgigStruct (Value (..))
+import SdkHelpers (jo, jsonThunk)
+
+customClient :: IO Sdk.Client
+customClient = do
+  let mockFetch = VFunc (\\_ _ _ _ -> do
+        body <- jo [("id", VStr "mock01")]
+        jo [("status", VNum 200), ("statusText", VStr "OK"), ("json", jsonThunk body)])
+  sys <- jo [("fetch", mockFetch)]
+  opts <- jo [("base", VStr "http://localhost:8080"), ("system", sys)]
+  Sdk.newSdk opts
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${envName(model)}_TEST_LIVE=TRUE${apikeyEnvLine}
+\`\`\`
+
+Then run the suite (stock GHC, no third-party dependencies):
+
+\`\`\`bash
+cd ${target.name} && make test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

package/project/.sdk/src/cmp/haskell/ReadmeInstall_haskell.ts

@@ -0,0 +1,51 @@
+
+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 with the bundled Makefile (stock GHC, no
+third-party dependencies — only the GHC boot libraries):
+
+\`\`\`bash
+cd ${target.name} && make test
+\`\`\`
+
+`)
+    return
+  }
+
+  // Publish pending: not yet on Hackage. Build from the git release tag or
+  // from a local source checkout. The runtime is dependency-free, so no cabal
+  // solve is needed — the Makefile drives stock GHC directly.
+  const { releasesUrl } = repoInfo(model)
+  Content(`This package is not yet published to Hackage. Install it from the GitHub
+release tag (\`${target.name}/vX.Y.Z\`, see [Releases](${releasesUrl})) or
+from a source checkout. The runtime has no third-party dependencies (only the
+GHC boot libraries: \`base\`, \`containers\`, \`array\`, \`time\`), so the
+bundled Makefile drives stock GHC with no cabal solve:
+
+\`\`\`bash
+cd ${target.name} && make test
+\`\`\`
+
+A \`.cabal\` file is also generated for use with \`cabal\`/\`stack\`:
+
+\`\`\`bash
+cd ${target.name} && cabal build
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

package/project/.sdk/src/cmp/haskell/ReadmeIntro_haskell.ts

@@ -0,0 +1,67 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+import { hsVarName } from './utility_haskell'
+
+
+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 Haskell conventions (pure functions, explicit \`IO\`, and the dependency-free vendored \`Value\` struct model).
+
+`)
+
+  // 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 accessor 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 \`${hsVarName(exampleEntity.name)} sdk VNoval\` — 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) => '`e' + o.charAt(0).toUpperCase() + o.slice(1) + '`').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/haskell/ReadmeModel_haskell.ts

@@ -0,0 +1,160 @@
+
+import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+import { hsVarName } from './utility_haskell'
+
+
+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 record 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: '| `eLoad` | `Value -> Value -> IO Value` | Load a single entity by match criteria. Raises on error. |',
+    list: '| `eList` | `Value -> Value -> IO Value` | List entities matching the criteria. Raises on error. |',
+    create: '| `eCreate` | `Value -> Value -> IO Value` | Create a new entity. Raises on error. |',
+    update: '| `eUpdate` | `Value -> Value -> IO Value` | Update an existing entity. Raises on error. |',
+    remove: '| `eRemove` | `Value -> Value -> IO 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(`### Client constructors
+
+\`\`\`haskell
+import qualified SdkClient as Sdk
+import VoxgigStruct (Value (..))
+import SdkHelpers (jo)
+
+makeClient :: IO Sdk.Client
+makeClient = do
+  opts <- jo [("base", VStr "https://api.example.com")]
+  Sdk.newSdk opts
+\`\`\`
+
+\`newSdk :: Value -> IO Client\` constructs a client from an options map;
+\`newSdk0 :: IO Client\` is the no-argument convenience form.
+
+| Option (map key) | 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. |
+| \`headers\` | \`Value\` | Custom headers for all requests. |
+| \`feature\` | \`Value\` | Feature activation flags. |
+| \`system\` | \`Value\` | System overrides (e.g. custom \`fetch\` function). |
+
+### Test client
+
+\`\`\`haskell
+client <- Sdk.testSdk testopts sdkopts
+\`\`\`
+
+\`testSdk :: Value -> Value -> IO Client\` constructs a test-mode client with
+mock transport (\`testSdk0 :: IO Client\` for the no-argument form). Pass
+\`VNoval\` for defaults.
+
+### Client functions
+
+| Function | Signature | Description |
+| --- | --- | --- |
+| \`newSdk\` | \`Value -> IO Client\` | Construct a live client from options. |
+| \`newSdk0\` | \`IO Client\` | Construct a live client with defaults. |
+| \`testSdk\` | \`Value -> Value -> IO Client\` | Construct a test-mode client. |
+| \`prepare\` | \`Client -> Value -> IO Value\` | Build an HTTP request definition without sending. Raises on error. |
+| \`direct\` | \`Client -> Value -> IO Value\` | Build and send an HTTP request. Returns a result \`Value\` (branch on \`ok\`). |
+`)
+
+  each(entityList, (ent: any) => {
+    const eFn = hsVarName(ent.name)
+    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
+    Content(`| \`${eFn}\` | \`Client -> Value -> IO Entity\` | Create ${article} ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface
+
+All entities share the same record interface (fields of the \`Entity\` type).
+
+| Field | Signature | Description |
+| --- | --- | --- |
+${opRows}
+| \`eDataGet\` | \`IO Value\` | Get entity data. |
+| \`eDataSet\` | \`Value -> IO ()\` | Set entity data. |
+| \`eStream\` | \`String -> Value -> Value -> IO [Value]\` | Run an op as a lazy stream of items. |
+| \`eMake\` | \`IO Entity\` | Create a new instance with the same options. |
+| \`eName\` | \`String\` | The entity name. |
+
+### Result shape
+
+Entity operations return the bare result \`Value\` (a map for single-entity
+ops, a list for \`eList\`) and raise on error. Wrap calls in
+\`Control.Exception.try\` to handle failures.
+
+The \`direct\` escape hatch never raises — it returns a result \`Value\`
+you branch on via its \`ok\` field (read with \`getp result "ok"\`):
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`Bool\` | \`True\` if the HTTP status is 2xx. |
+| \`status\` | \`Int\` | HTTP status code. |
+| \`headers\` | \`Value\` | Response headers. |
+| \`data\` | \`Value\` | Parsed JSON response body. |
+
+On error, \`ok\` is \`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/haskell/ReadmeOptions_haskell.ts

@@ -0,0 +1,74 @@
+
+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
+  }
+
+  const authActive = isAuthActive(model)
+
+  Content(`
+
+## Options
+
+Pass an options \`Value\` (built with \`jo\`) when constructing a client. Any
+option may be omitted; the entries below are illustrative.
+
+`)
+
+  if (authActive) {
+    Content(`\`\`\`haskell
+import qualified SdkClient as Sdk
+import VoxgigStruct (Value (..))
+import SdkHelpers (jo)
+
+makeClient :: IO Sdk.Client
+makeClient = do
+  -- Read the API key from the ${envName(model)}_APIKEY environment variable.
+  opts <- jo [("apikey", VStr "your-api-key")]
+  Sdk.newSdk opts
+\`\`\`
+
+`)
+  }
+  else {
+    Content(`\`\`\`haskell
+import qualified SdkClient as Sdk
+import VoxgigStruct (Value (..))
+import SdkHelpers (jo)
+
+makeClient :: IO Sdk.Client
+makeClient = do
+  opts <- jo [("base", VStr "https://api.example.com")]
+  Sdk.newSdk opts
+\`\`\`
+
+`)
+  }
+
+  Content(`Every published option:
+
+| Option | Type | Description |
+| --- | --- | --- |
+`)
+
+  publishedOptions.map((option: any) => {
+    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
+`)
+  })
+
+  Content(`
+`)
+})
+
+
+export {
+  ReadmeOptions
+}