@voxgig/sdkgen 1.3.14 → 1.3.17

package/project/.sdk/src/cmp/perl/ReadmeRef_perl.ts

@@ -0,0 +1,399 @@
+
+import { cmp, each, Content, canonKey, File, isAuthActive, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+// A type-correct, executable Perl literal for a field's canonical type.
+function perlLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return '1'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  return `'${placeholder}'`
+}
+
+
+// Perl has no static types; describe field shapes with idiomatic Perl terms.
+function perlType(type: any): string {
+  const k = canonKey(type)
+  const m: Record<string, string> = {
+    STRING: 'string', INTEGER: 'integer', NUMBER: 'number',
+    BOOLEAN: 'boolean', ARRAY: 'arrayref', OBJECT: 'hashref', NULL: 'undef',
+  }
+  return m[k] || 'scalar'
+}
+
+
+const OP_SIGNATURES: Record<string, { sig: string, returns: string, desc: string }> = {
+  load: {
+    sig: 'load($reqmatch, $ctrl) -> hashref',
+    returns: 'the entity data',
+    desc: 'Load a single entity matching the given criteria. Returns the entity data and dies on error.',
+  },
+  list: {
+    sig: 'list($reqmatch, $ctrl) -> arrayref',
+    returns: 'an arrayref of entities',
+    desc: 'List entities matching the given criteria. The match is optional — call `list` with no argument to list all records. Returns an arrayref and dies on error.',
+  },
+  create: {
+    sig: 'create($reqdata, $ctrl) -> hashref',
+    returns: 'the created entity data',
+    desc: 'Create a new entity with the given data. Returns the created entity data and dies on error.',
+  },
+  update: {
+    sig: 'update($reqdata, $ctrl) -> hashref',
+    returns: 'the updated entity data',
+    desc: 'Update an existing entity. The data must include the entity `id`. Returns the updated entity data and dies on error.',
+  },
+  remove: {
+    sig: 'remove($reqmatch, $ctrl) -> hashref',
+    returns: 'the removed entity data',
+    desc: 'Remove the entity matching the given criteria. Dies 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.
+
+
+## ${model.Name}SDK
+
+### Constructor
+
+`)
+
+    Content(`\`\`\`perl
+use lib 'lib';
+use ${model.const.Name}SDK;
+
+my $client = ${model.const.Name}SDK->new($options);
+\`\`\`
+
+Create a new SDK client instance.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`$options\` | \`hashref\` | SDK configuration options. |
+${isAuthActive(model) ? '| \`$options->{apikey}\` | \`string\` | API key for authentication. |\n' : ''}| \`$options->{base}\` | \`string\` | Base URL for API requests. |
+| \`$options->{prefix}\` | \`string\` | URL prefix appended after base. |
+| \`$options->{suffix}\` | \`string\` | URL suffix appended after path. |
+| \`$options->{headers}\` | \`hashref\` | Custom headers for all requests. |
+| \`$options->{feature}\` | \`hashref\` | Feature configuration. |
+| \`$options->{system}\` | \`hashref\` | System overrides (e.g. custom fetch). |
+
+`)
+
+
+    Content(`
+### Static Methods
+
+`)
+
+    Content(`#### \`${model.const.Name}SDK->test($testopts, $sdkopts)\`
+
+Create a test client with mock features active. Both arguments may be \`undef\`.
+
+\`\`\`perl
+my $client = ${model.const.Name}SDK->test();
+\`\`\`
+
+`)
+
+
+    Content(`
+### Instance Methods
+
+`)
+
+
+    // Entity factory methods
+    publishedEntities.map((ent: any) => {
+      Content(`#### \`${ent.Name}($data)\`
+
+Create a new \`${ent.Name}\` entity instance. Pass \`undef\` for no initial data.
+
+`)
+    })
+
+
+    Content(`#### \`options_map() -> hashref\`
+
+Return a deep copy of the current SDK options.
+
+#### \`get_utility() -> utility\`
+
+Return a copy of the SDK utility object.
+
+#### \`direct($fetchargs) -> hashref\`
+
+Make a direct HTTP request to any API endpoint. Returns a result \`hashref\` with \`ok\`, \`status\`, \`headers\`, and \`data\` (or \`err\` on failure). This escape hatch never dies — branch on \`$result->{ok}\`.
+
+**Parameters:**
+
+| Name | Type | Description |
+| --- | --- | --- |
+| \`$fetchargs->{path}\` | \`string\` | URL path with optional \`{param}\` placeholders. |
+| \`$fetchargs->{method}\` | \`string\` | HTTP method (default: \`'GET'\`). |
+| \`$fetchargs->{params}\` | \`hashref\` | Path parameter values. |
+| \`$fetchargs->{query}\` | \`hashref\` | Query string parameters. |
+| \`$fetchargs->{headers}\` | \`hashref\` | Request headers (merged with defaults). |
+| \`$fetchargs->{body}\` | \`any\` | Request body (hashrefs are JSON-serialized). |
+
+**Returns:** \`hashref\`
+
+#### \`prepare($fetchargs) -> hashref\`
+
+Prepare a fetch definition without sending. Returns the \`fetchdef\` and dies 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 eVar = ent.name
+
+      Content(`
+---
+
+## ${ent.Name} entity
+
+`)
+
+      if (ent.short) {
+        Content(`${ent.short}
+
+`)
+      }
+
+      Content(`\`\`\`perl
+my $${eVar} = $client->${ent.Name};
+\`\`\`
+
+`)
+
+
+      // 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}\` | \`${perlType(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
+              ? `{ ${matchItems.map((it: any) =>
+                `'${it.name}' => ${perlLit(it.type,
+                  it.name === idF ? ent.name + '_id' : it.name)}`).join(', ')} }`
+              : ''
+            Content(`\`\`\`perl
+my $result = $client->${ent.Name}->${opname}(${arg});
+\`\`\`
+
+`)
+          }
+          else if ('list' === opname) {
+            Content(`\`\`\`perl
+my $results = $client->${ent.Name}->list;
+for my $${eVar} (@$results) {
+    print "$${eVar}->{id}\\n";
+}
+\`\`\`
+
+`)
+          }
+          else if ('create' === opname) {
+            const createItems = opRequestShape(ent, 'create').items
+              .filter((it: any) => !it.optional)
+            Content(`\`\`\`perl
+my $result = $client->${ent.Name}->create({
+`)
+            createItems.map((it: any) => {
+              Content(`    '${it.name}' => ${perlLit(it.type, 'example_' + it.name)},  # ${perlType(it.type)}
+`)
+            })
+            Content(`});
+\`\`\`
+
+`)
+          }
+          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}' => ${perlLit(it.type,
+                it.name === idF ? ent.name + '_id' : it.name)},\n`).join('')
+            Content(`\`\`\`perl
+my $result = $client->${ent.Name}->update({
+${updateLines}    # Fields to update
+});
+\`\`\`
+
+`)
+          }
+        })
+      }
+
+
+      // Common methods
+      Content(`### Common Methods
+
+#### \`data_get() -> hashref\`
+
+Get the entity data.
+
+#### \`data_set($data)\`
+
+Set the entity data.
+
+#### \`match_get() -> hashref\`
+
+Get the entity match criteria.
+
+#### \`match_set($match)\`
+
+Set the entity match criteria.
+
+#### \`make() -> entity\`
+
+Create a new \`${ent.Name}\` entity instance with the same options.
+
+#### \`get_name() -> 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(`\`\`\`perl
+my $client = ${model.const.Name}SDK->new({
+    'feature' => {
+`)
+      activeFeatures.map((f: any) => {
+        Content(`        '${f.name}' => { 'active' => 1 },
+`)
+      })
+      Content(`    },
+});
+\`\`\`
+
+`)
+    }
+
+  })
+})
+
+
+
+
+export {
+  ReadmeRef
+}

package/project/.sdk/src/cmp/perl/ReadmeTopHowto_perl.ts

@@ -0,0 +1,24 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeTopHowto = cmp(function ReadmeTopHowto(props: any) {
+  const { target } = props
+
+  Content(`**Perl:**
+\`\`\`perl
+my $result = $client->direct({
+    'path' => '/api/resource/{id}',
+    'method' => 'GET',
+    'params' => { 'id' => 'example' },
+});
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeTopHowto
+}

package/project/.sdk/src/cmp/perl/ReadmeTopQuick_perl.ts

@@ -0,0 +1,91 @@
+
+import { cmp, Content, isAuthActive, envName, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+// A type-correct, executable Perl literal for a param: numeric/boolean/
+// array/hash params render a typed literal; strings render the quoted
+// placeholder (the doc test EXECUTES this block, so a comment placeholder
+// would break it).
+function perlLit(type: any, placeholder: string = 'example'): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return '1'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  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
+    ? `${model.const.Name}SDK->new({\n    'apikey' => $ENV{'${envName(model)}_APIKEY'},\n})`
+    : `${model.const.Name}SDK->new`
+
+  Content(`\`\`\`perl
+use lib '${target.name}/lib';
+use ${model.const.Name}SDK;
+
+my $client = ${ctor};
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const eVar = eName.toLowerCase()
+    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 ${eName.toLowerCase()}s (returns an arrayref; dies on error)
+my $${eVar}s = $client->${eName}->list;
+for my $${eVar} (@$${eVar}s) {
+    print "$${eVar}->{id}\\n";
+}
+`)
+    }
+
+    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
+        ? `{ ${loadItems.map((it: any) =>
+          `'${it.name}' => ${perlLit(it.type,
+            it.name === idF ? 'example_id' : 'example_' + it.name)}`).join(', ')} }`
+        : ''
+      Content(`
+# Load a specific ${eName.toLowerCase()} (returns the bare record; dies on error)
+my $${eVar} = $client->${eName}->load(${loadArg});
+print "$${eVar}->{id}\\n";
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopQuick
+}

package/project/.sdk/src/cmp/perl/ReadmeTopTest_perl.ts

@@ -0,0 +1,83 @@
+
+import { cmp, Content, canonKey, entityIdField, pickExampleEntity, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+// A type-correct Perl literal for a field's canonical type.
+function perlLit(type: any): string {
+  const k = canonKey(type)
+  if ('INTEGER' === k || 'NUMBER' === k) return '1'
+  if ('BOOLEAN' === k) return '1'
+  if ('ARRAY' === k) return '[]'
+  if ('OBJECT' === k) return '{}'
+  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(`\`\`\`perl
+use lib '${target.name}/lib';
+use ${model.const.Name}SDK;
+
+my $client = ${model.const.Name}SDK->test(undef, undef);
+`)
+
+  if (exampleEntity && primaryOp) {
+    const eName = nom(exampleEntity, 'Name')
+    const idF = entityIdField(exampleEntity)
+    const isMatchOp = 'load' === primaryOp || 'remove' === primaryOp
+    let arg = ''
+    if (isMatchOp) {
+      // Every REQUIRED match key (id first) — the same shape that generates
+      // the op's match resolution, so the block runs offline against a seeded
+      // fixture.
+      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
+        ? `{ ${items.map((it: any) =>
+          `'${it.name}' => ${it.name === idF ? "'test01'" : perlLit(it.type)}`).join(', ')} }`
+        : ''
+    } 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 = `{ ${chosen.map((it: any) => `'${it.name}' => ${perlLit(it.type)}`).join(', ')} }`
+    }
+    // A list() result is an arrayref — name the variable accordingly.
+    const eVar = eName.toLowerCase() + ('list' === primaryOp ? 's' : '')
+    Content(`my $${eVar} = $client->${eName}->${primaryOp}(${arg});
+`)
+    if ('list' === primaryOp) {
+      Content(`print scalar(@$${eVar}), " records\\n";
+`)
+    } else {
+      Content(`print "$${eVar}->{id}\\n";
+`)
+    }
+  }
+
+  Content(`\`\`\`
+`)
+
+})
+
+
+export {
+  ReadmeTopTest
+}

package/project/.sdk/src/cmp/perl/Test_perl.ts

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_perl'
 import { TestDirect } from './TestDirect_perl'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_perl'
 
 
 const Test = cmp(function Test(props: any) {
@@ -45,6 +46,9 @@ done_testing();
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // README example snippet gate (syntax + offline test-mode run).
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/php/EntityTypes_php.ts

@@ -29,7 +29,7 @@ import {
   File, Content, Folder,
 } from '@voxgig/sdkgen'
 
-import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+import { canonToType, opTypeName, opRequestShape, warnEntityTypeCollisions } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -50,9 +50,12 @@ function validName(name: string): boolean {
 // Emit one typed PHP property line. `mixed` is already nullable in PHP and
 // rejects the `?` prefix, so it is special-cased; every other optional field
 // becomes `?type` with a `= null` default so the property is safely optional.
+// A `$NULL`-typed field maps to the 'null' type name, which is not usable as
+// a property type here (`?null` is a fatal, and standalone `null` needs
+// PHP >= 8.2), so it degrades to `mixed` too.
 function propLine(name: string, sentinel: unknown, optional: boolean): string {
   const type = canonToType(sentinel, LANG)
-  if ('mixed' === type) {
+  if ('mixed' === type || 'null' === type) {
     return optional
       ? `    public mixed $${name} = null;\n`
       : `    public mixed $${name};\n`
@@ -64,15 +67,29 @@ function propLine(name: string, sentinel: unknown, optional: boolean): string {
 
 
 const EntityTypes = cmp(function EntityTypes(props: any) {
-  const { model } = props.ctx$
-
-  const entity = getModelPath(model, `main.${KIT}.entity`)
-  const entityList = each(entity).filter((e: any) => e.active !== false)
+  const { model, log } = props.ctx$
+
+  // only_active:false — getModelPath DROPS active:false entries by default,
+  // but the consumer scaffold (create-sdkgen Root.ts) iterates the RAW entity
+  // collection, so inactive entities still get generated entity code that
+  // references these typed names. The typed model must cover them too.
+  const entity = getModelPath(model, `main.${KIT}.entity`, { only_active: false, required: false })
+  // Emit for EVERY entity that gets generated entity code: the consumer
+  // scaffold (create-sdkgen Root.ts) iterates entities WITHOUT an active
+  // filter, so inactive entities still get class files referencing these
+  // typed names. Filter on `name` (always present), NOT `active` — parity
+  // with the go emitter's fix.
+  const entityList = each(entity).filter((e: any) => e && null != e.name)
   // Derive the PascalCase Name up-front — it is set LAZILY by names(), so an
   // entity not yet named (e.g. a fieldless placeholder) would otherwise read
   // `Name = undefined` below. Parity with the go emitter's fix.
   entityList.forEach((e: any) => { if (null == e.Name) names(e, e.name) })
 
+  // Surface duplicate generated type names (two entities with the same
+  // PascalCase Name) — they would redeclare a type in statically-typed
+  // targets. Detection only; renaming is a model-level decision.
+  warnEntityTypeCollisions(entity, log, LANG)
+
   Folder({ name: 'types' }, () => {
 
     File({ name: model.const.Name + 'Types.' + LANG }, () => {

package/project/.sdk/src/cmp/php/ReadmeHowto_php.ts

@@ -34,7 +34,12 @@ const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
     : `${model.const.Name}SDK::test()`
   let testCallArg = ''
   if (exampleEntity && isMatchOp) {
-    testCallArg = idF ? `["${idF}" => "test01"]` : ''
+    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))
+    testCallArg = 0 < items.length
+      ? `[${items.map((it: any) => `"${it.name}" => ${it.name === idF ? '"test01"' : phpLit(it.type)}`).join(', ')}]`
+      : ''
   } else if (exampleEntity && ('create' === primaryOp || 'update' === primaryOp)) {
     const items = opRequestShape(exampleEntity, primaryOp).items
       .filter((it: any) => it.name !== idF && it.name !== 'id')