@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/src/cmp/dart/ReadmeIntro_dart.ts

@@ -1,65 +0,0 @@
-
-import { cmp, Content } from '@voxgig/sdkgen'
-
-import {
-  KIT,
-  getModelPath,
-  nom,
-} from '@voxgig/apidef'
-
-
-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 Dart conventions.
-
-`)
-
-  // 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 \`client.${nom(exampleEntity, 'Name')}()\` — 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/dart/ReadmeModel_dart.ts

@@ -1,151 +0,0 @@
-
-import { cmp, each, Content, isAuthActive } from '@voxgig/sdkgen'
-
-import {
-  KIT,
-  getModelPath,
-} from '@voxgig/apidef'
-
-import { dartPackageName } from './Package_dart'
-
-
-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)
-  const pkg = dartPackageName(model)
-
-  // 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: '| `load` | `(reqmatch, [ctrl]) -> Future<dynamic>` | Load a single entity by match criteria. Throws on error. |',
-    list: '| `list` | `(reqmatch, [ctrl]) -> Future<List>` | List entities matching the criteria (a list of entity instances). Throws on error. |',
-    create: '| `create` | `(reqdata, [ctrl]) -> Future<dynamic>` | Create a new entity. Throws on error. |',
-    update: '| `update` | `(reqdata, [ctrl]) -> Future<dynamic>` | Update an existing entity. Throws on error. |',
-    remove: '| `remove` | `(reqmatch, [ctrl]) -> Future<dynamic>` | Remove an entity. Throws 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(`### ${model.const.Name}SDK
-
-\`\`\`dart
-import 'package:${pkg}/${model.const.Name}SDK.dart';
-
-final client = ${model.const.Name}SDK(options);
-\`\`\`
-
-Creates a new SDK client.
-
-| 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). |
-
-### test
-
-\`\`\`dart
-final client = ${model.const.Name}SDK.test(testopts, sdkopts);
-\`\`\`
-
-Creates a test-mode client with mock transport. Both arguments may be \`null\`.
-
-### ${model.const.Name}SDK methods
-
-| Method | Signature | Description |
-| --- | --- | --- |
-| \`options\` | \`() -> Map\` | Deep copy of current SDK options. |
-| \`utility\` | \`() -> Utility\` | The SDK utility object. |
-| \`prepare\` | \`([fetchargs]) -> Future\` | Build an HTTP request definition without sending. Returns an error value on failure. |
-| \`direct\` | \`([fetchargs]) -> Future<Map>\` | Build and send an HTTP request. Returns a result map (branch on \`ok\`); never throws. |
-`)
-
-  each(entityList, (ent: any) => {
-    const article = /^[aeiou]/i.test(ent.Name) ? 'an' : 'a'
-    Content(`| \`${ent.Name}\` | \`([entopts]) -> ${ent.Name}Entity\` | Create ${article} ${ent.Name} entity instance. |
-`)
-  })
-
-  Content(`
-### Entity interface
-
-All entities share the same interface.
-
-| Method | Signature | Description |
-| --- | --- | --- |
-${opRows}
-| \`data\` | \`([d]) -> Map\` | Get (or, with an argument, set) entity data. |
-| \`match\` | \`([m]) -> Map\` | Get (or, with an argument, set) entity match criteria. |
-| \`make\` | \`() -> Entity\` | Create a new instance with the same options. |
-| \`entopts\` | \`() -> Map\` | Return the entity options. |
-| \`Name\` | \`String\` | The entity name (a public field). |
-
-### Result shape
-
-Entity operations return the ENTITY (call data() for the record) (a \`Map\` for single-entity
-ops, a \`List\` of entity instances for \`list\`) and throw on error. Wrap calls
-in \`try\`/\`catch\` to handle failures.
-
-The \`direct()\` escape hatch never throws — it returns a result \`Map\` you
-branch on via \`result['ok']\`:
-
-| Key | Type | Description |
-| --- | --- | --- |
-| \`ok\` | \`bool\` | \`true\` if the HTTP status is 2xx. |
-| \`status\` | \`int\` | HTTP status code. |
-| \`headers\` | \`Map\` | Response headers. |
-| \`data\` | \`dynamic\` | Parsed JSON response body. |
-
-On error, \`ok\` is \`false\` and \`err\` contains 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/dart/ReadmeOptions_dart.ts

@@ -1,63 +0,0 @@
-
-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)
-  const importIO = authActive ? `import 'dart:io';\n` : ''
-
-  Content(`
-
-## Options
-
-Pass options when creating a client instance:
-
-`)
-
-  Content(`\`\`\`dart
-${importIO}
-final client = ${model.Name}SDK({
-`)
-
-  publishedOptions.map((option: any) => {
-    if ('apikey' === option.name) {
-      Content(`  'apikey': Platform.environment['${envName(model)}_APIKEY'],
-`)
-    }
-    else {
-      Content(`  // '${option.name}': ${option.kind === 'string' ? "'...'" : '...'},
-`)
-    }
-  })
-
-  Content(`});
-\`\`\`
-
-`)
-
-  Content(`| Option | Type | Description |
-| --- | --- | --- |
-`)
-
-  publishedOptions.map((option: any) => {
-    Content(`| \`${option.name}\` | \`${option.kind}\` | ${option.short} |
-`)
-  })
-
-  Content(`
-`)
-})
-
-
-export {
-  ReadmeOptions
-}

package/project/.sdk/src/cmp/dart/ReadmeQuick_dart.ts

@@ -1,225 +0,0 @@
-
-import { cmp, each, Content, isAuthActive, envName, canonKey, canonScalarKey, opRequestShape, entityIdField, entityDataIdField, entityOps, safeVarName, exampleVarName, matchArg, idLiteral } from '@voxgig/sdkgen'
-
-import {
-  KIT,
-  getModelPath,
-  nom,
-} from '@voxgig/apidef'
-
-import { dartPackageName } from './Package_dart'
-
-
-// A `list()` on a NESTED entity needs its parent path params. The
-// quickstart used to emit `client.Moon().list()` for an entity at
-// `/planet/{planet_id}/moon`, which 404s against a live server from a
-// half-built URL — indistinguishable from "no such record". The model
-// already marks those params `reqd: true`; matchArg renders exactly them.
-function listMatchArg(ent: any): string {
-  const idF = entityIdField(ent)
-  return matchArg('ts', ent, 'list', idF, idLiteral(ent, 'list', idF))
-}
-
-
-const ReadmeQuick = cmp(function ReadmeQuick(props: any) {
-  const { target, ctx$: { model } } = props
-
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const pkg = dartPackageName(model)
-
-  const exampleEntity = Object.values(entity).find((e: any) => e.active !== false) as any
-
-  // Find a nested entity if available: one with a parent chain
-  // (relations.ancestors), an active load op, and a required non-id load
-  // param to demonstrate (the parent key, e.g. page_id).
-  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 importIO = authActive ? `import 'dart:io';\n` : ''
-  const ctor = authActive
-    ? `${model.const.Name}SDK({\n  'apikey': Platform.environment['${envName(model)}_APIKEY'],\n})`
-    : `${model.const.Name}SDK()`
-
-  Content(`### 1. Create a client
-
-\`\`\`dart
-${importIO}import 'package:${pkg}/${model.const.Name}SDK.dart';
-
-final client = ${ctor};
-\`\`\`
-
-`)
-
-  if (exampleEntity) {
-    const eName = nom(exampleEntity, 'Name')
-    const article = /^[aeiou]/i.test(eName) ? 'an' : 'a'
-    const eVar = exampleVarName(eName.toLowerCase(), 'dart')
-    const opnames = entityOps(exampleEntity)
-    // Model-driven id keys: `idF` is the entity's id-like MATCH field name, or
-    // null when it has none. `dataIdF` is the id on the RETURNED record's data
-    // type — an entity can key its match on an id it does not carry as data.
-    const idF = entityIdField(exampleEntity)
-    const dataIdF = entityDataIdField(exampleEntity)
-
-    // A type-correct, executable Dart literal for a param.
-    const dartLit = (type: any, placeholder: string = 'example'): string => {
-      const k = canonScalarKey(type)
-      if ('INTEGER' === k || 'NUMBER' === k) return '1'
-      if ('BOOLEAN' === k) return 'true'
-      if ('ARRAY' === k) return '<dynamic>[]'
-      if ('OBJECT' === k) return '<String, dynamic>{}'
-      return `'${placeholder}'`
-    }
-
-    if (opnames.includes('list')) {
-      Content(`### 2. List ${eName.toLowerCase()} records
-
-\`list()\` returns a \`List\` of entity instances and throws on error — iterate
-it and read each record's data via \`.data()\`.
-
-\`\`\`dart
-try {
-  final ${eVar}s = await client.${eName}().list(${listMatchArg(exampleEntity)});
-  for (final item in ${eVar}s) {
-    print(item.data());
-  }
-} catch (err) {
-  print('list failed: $err');
-}
-\`\`\`
-
-`)
-    }
-
-    if (nestedEntity) {
-      const neName = nom(nestedEntity, 'Name')
-      const neArticle = /^[aeiou]/i.test(neName) ? 'an' : 'a'
-      const neVar = exampleVarName(neName.toLowerCase(), 'dart')
-
-      // Model-driven match: every REQUIRED load-match key. Parent keys (e.g.
-      // page_id) 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}': ${dartLit(it.type,
-          it.name === neIdF ? 'example_id' : 'example_' + it.name)}`)
-
-      Content(`### 3. Load ${neArticle} ${neName.toLowerCase()}
-
-${neName} is nested under ${parentName}, so provide the \`${parentParam}\`.
-\`load()\` returns the ENTITY — call data() for the record — and throws on error.
-
-\`\`\`dart
-try {
-  final ${neVar} = await client.${neName}().load({${neMatch.join(', ')}});
-  print(${neVar});
-} catch (err) {
-  print('load failed: $err');
-}
-\`\`\`
-
-`)
-    }
-    else if (opnames.includes('load')) {
-      // Every REQUIRED load-match key (id first, then parent path params).
-      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
-        ? `{${loadRequired.map((it: any) =>
-          `'${it.name}': ${dartLit(it.type,
-            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')}}`
-        : ''
-
-      Content(`### 3. Load ${article} ${eName.toLowerCase()}
-
-\`load()\` returns the ENTITY — call data() for the record — and throws on error.
-
-\`\`\`dart
-try {
-  final ${eVar} = await client.${eName}().load(${loadArg});
-  print(${eVar});
-} catch (err) {
-  print('load failed: $err');
-}
-\`\`\`
-
-`)
-    }
-
-    // Model-driven example fields for create/update bodies.
-    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}': ${dartLit(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'))
-      ? `created.data()['${dataIdF}']`
-      : dartLit(idParamType(opname), 'example_id')
-
-    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
-      Content(`### 4. Create, update, and remove
-
-\`\`\`dart
-`)
-      if (opnames.includes('create')) {
-        Content(`// Create — returns the ENTITY (call data() for the record)
-final created = await client.${eName}().create({${examplePairs('create').join(', ')}});
-
-`)
-      }
-      if (opnames.includes('update')) {
-        const updatePairs = (idF ? [`'${idF}': ${idValueFor('update')}`] : []).concat(examplePairs('update'))
-        const fromCreated = null != dataIdF && opnames.includes('create')
-        Content(`// Update${fromCreated ? " — the created record's id is a plain map key" : ''}
-await client.${eName}().update({${updatePairs.join(', ')}});
-
-`)
-      }
-      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}': ${dartLit(it.type, 'example_' + it.name)}`)
-        Content(`// Remove
-await client.${eName}().remove(${removePairs.length ? `{${removePairs.join(', ')}}` : ''});
-`)
-      }
-      Content(`\`\`\`
-
-`)
-    }
-  }
-})
-
-
-export {
-  ReadmeQuick
-}