@voxgig/sdkgen 1.2.1 → 1.3.2

package/project/.sdk/src/cmp/rb/TestDirect_rb.ts

@@ -185,7 +185,7 @@ ${listSkipBlock}    client = setup[:client]
 `)
         }
         Content(`
-    result, err = client.direct({
+    result = client.direct({
       "path" => "${listPath}",
       "method" => "GET",
       "params" => params,
@@ -193,7 +193,7 @@ ${listSkipBlock}    client = setup[:client]
 `)
       } else {
         Content(`
-    result, err = client.direct({
+    result = client.direct({
       "path" => "${listPath}",
       "method" => "GET",
       "params" => {},
@@ -205,8 +205,8 @@ ${listSkipBlock}    client = setup[:client]
       # Live mode is lenient: synthetic IDs frequently 4xx and the list-
       # response shape varies wildly across public APIs. Skip rather than
       # fail when the call doesn't return a usable list.
-      if !err.nil?
-        skip("list call failed (likely synthetic IDs against live API): #{err}")
+      if !result["err"].nil?
+        skip("list call failed (likely synthetic IDs against live API): #{result["err"]}")
         return
       end
       unless result["ok"]
@@ -219,7 +219,7 @@ ${listSkipBlock}    client = setup[:client]
         return
       end
     else
-      assert_nil err
+      assert_nil result["err"]
       assert result["ok"]
       assert_equal 200, Helpers.to_int(result["status"])
       assert result["data"].is_a?(Array)
@@ -294,7 +294,7 @@ ${loadLiveQueryLines}
       }
 
       Content(`
-    result, err = client.direct({
+    result = client.direct({
       "path" => "${loadPath}",
       "method" => "GET",
 `)
@@ -311,8 +311,8 @@ ${loadLiveQueryLines}
       # Live mode is lenient: synthetic IDs frequently 4xx. Skip rather
       # than fail when the load endpoint isn't reachable with the IDs
       # we can construct from setup.idmap.
-      if !err.nil?
-        skip("load call failed (likely synthetic IDs against live API): #{err}")
+      if !result["err"].nil?
+        skip("load call failed (likely synthetic IDs against live API): #{result["err"]}")
         return
       end
       unless result["ok"]
@@ -325,7 +325,7 @@ ${loadLiveQueryLines}
         return
       end
     else
-      assert_nil err
+      assert_nil result["err"]
       assert result["ok"]
       assert_equal 200, Helpers.to_int(result["status"])
       assert !result["data"].nil?

package/project/.sdk/src/cmp/rb/TestEntity_rb.ts

@@ -264,8 +264,7 @@ const generateCreate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-    ${datavar}_result, err = ${entvar}.create(${datavar}, nil)
-    assert_nil err
+    ${datavar}_result = ${entvar}.create(${datavar}, nil)
     ${datavar} = Helpers.to_map(${datavar}_result)
     assert !${datavar}.nil?
 `)
@@ -310,8 +309,7 @@ const generateList: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-    ${listvar}_result, err = ${entvar}.list(${matchvar}, nil)
-    assert_nil err
+    ${listvar}_result = ${entvar}.list(${matchvar}, nil)
     assert ${listvar}_result.is_a?(Array)
 `)
 
@@ -399,8 +397,7 @@ const generateUpdate: OpGen = (ctx, step, index) => {
   }
 
   Content(`
-    ${resdatavar}_result, err = ${entvar}.update(${datavar}_up, nil)
-    assert_nil err
+    ${resdatavar}_result = ${entvar}.update(${datavar}_up, nil)
     ${resdatavar} = Helpers.to_map(${resdatavar}_result)
     assert !${resdatavar}.nil?
 `)
@@ -465,8 +462,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
     Content(`    ${matchvar} = {
       "id" => ${srcdatavar}["id"],
     }
-    ${datavar}_loaded, err = ${entvar}.load(${matchvar}, nil)
-    assert_nil err
+    ${datavar}_loaded = ${entvar}.load(${matchvar}, nil)
     ${datavar}_load_result = Helpers.to_map(${datavar}_loaded)
     assert !${datavar}_load_result.nil?
     assert_equal ${datavar}_load_result["id"], ${srcdatavar}["id"]
@@ -474,8 +470,7 @@ const generateLoad: OpGen = (ctx, step, index) => {
   }
   else {
     Content(`    ${matchvar} = {}
-    ${datavar}_loaded, err = ${entvar}.load(${matchvar}, nil)
-    assert_nil err
+    ${datavar}_loaded = ${entvar}.load(${matchvar}, nil)
     assert !${datavar}_loaded.nil?
 `)
   }
@@ -503,8 +498,7 @@ const generateRemove: OpGen = (ctx, step, index) => {
   Content(`    ${matchvar} = {
       "id" => ${srcdatavar}["id"],
     }
-    _, err = ${entvar}.remove(${matchvar}, nil)
-    assert_nil err
+    ${entvar}.remove(${matchvar}, nil)
 `)
 }
 

package/project/.sdk/src/cmp/rb/Test_rb.ts

@@ -13,6 +13,7 @@ import { cmp, each, Folder, File, Content } from '@voxgig/sdkgen'
 
 import { TestEntity } from './TestEntity_rb'
 import { TestDirect } from './TestDirect_rb'
+import { ReadmeExamplesTest } from './ReadmeExamplesTest_rb'
 
 
 const Test = cmp(function Test(props: any) {
@@ -41,6 +42,9 @@ end
       TestEntity({ target, entity })
       TestDirect({ target, entity })
     })
+
+    // README example snippet test (syntax + offline test-mode run).
+    ReadmeExamplesTest({ target })
   })
 })
 

package/project/.sdk/src/cmp/rb/fragment/Entity.fragment.rb

@@ -45,6 +45,7 @@ class EntityNameEntity
     end
   end
 
+  # @return [EntityName, Hash] the current EntityName data
   def data_get
     @_utility.feature_hook.call(@_entctx, "GetData")
     VoxgigStruct.clone(@_data)
@@ -57,6 +58,7 @@ class EntityNameEntity
     end
   end
 
+  # @return [Hash] the current match filter (any subset of EntityName fields)
   def match_get
     @_utility.feature_hook.call(@_entctx, "GetMatch")
     VoxgigStruct.clone(@_match)

package/project/.sdk/src/cmp/rb/fragment/EntityCreateOp.fragment.rb

@@ -3,6 +3,11 @@ require_relative '../core/helpers'
 
 # EJECT-START
 
+  # Create a new EntityName.
+  #
+  # @param reqdata [EntityNameCreateData, Hash, nil] body data
+  # @param ctrl [Object, nil] optional per-call control
+  # @return [EntityName, Hash] the created EntityName; raises ProjectNameError on failure
   def create(reqdata, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

package/project/.sdk/src/cmp/rb/fragment/EntityListOp.fragment.rb

@@ -1,6 +1,12 @@
 # EJECT-START
 
-  def list(reqmatch, ctrl = nil)
+  # List EntityName items matching the given filter.
+  #
+  # @param reqmatch [EntityNameListMatch, Hash, nil] match filter (any subset of
+  #   EntityName fields); defaults to nil, treated as an empty match that lists all.
+  # @param ctrl [Object, nil] optional per-call control
+  # @return [Array<EntityName>, Array] the matching EntityName items; raises ProjectNameError on failure
+  def list(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({
       "opname" => "list",
@@ -10,11 +16,23 @@
       "reqmatch" => reqmatch,
     }, @_entctx)
 
-    _run_op(ctx) do
+    records = _run_op(ctx) do
       if ctx.result
         @_match = ctx.result.resmatch if ctx.result.resmatch
       end
     end
+
+    # list yields the BARE Array of records — each an accessible Hash — so
+    # callers can index item["id"] directly, matching py/lua/go. make_result
+    # wraps each entry as an Entity instance for internal use; unwrap those
+    # back to their bare record Hashes here (load/create/etc. are unaffected).
+    if records.is_a?(Array)
+      records = records.map do |item|
+        item.respond_to?(:data_get) ? item.data_get : item
+      end
+    end
+
+    records
   end
 
 # EJECT-END

package/project/.sdk/src/cmp/rb/fragment/EntityLoadOp.fragment.rb

@@ -3,7 +3,14 @@ require_relative '../core/helpers'
 
 # EJECT-START
 
-  def load(reqmatch, ctrl = nil)
+  # Load a single EntityName.
+  #
+  # @param reqmatch [EntityNameLoadMatch, Hash, nil] match criteria (id/query fields);
+  #   optional — an entity with no id-like key loads with no match (nil is treated
+  #   as an empty match, so client.EntityName.load works with no args).
+  # @param ctrl [Object, nil] optional per-call control
+  # @return [EntityName, Hash] the loaded EntityName; raises ProjectNameError on failure
+  def load(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({
       "opname" => "load",

package/project/.sdk/src/cmp/rb/fragment/EntityRemoveOp.fragment.rb

@@ -3,7 +3,12 @@ require_relative '../core/helpers'
 
 # EJECT-START
 
-  def remove(reqmatch, ctrl = nil)
+  # Remove an EntityName matching the given criteria.
+  #
+  # @param reqmatch [EntityNameRemoveMatch, Hash, nil] match criteria (id/query fields)
+  # @param ctrl [Object, nil] optional per-call control
+  # @return [EntityName, Hash] the removed EntityName; raises ProjectNameError on failure
+  def remove(reqmatch = nil, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({
       "opname" => "remove",

package/project/.sdk/src/cmp/rb/fragment/EntityUpdateOp.fragment.rb

@@ -3,6 +3,11 @@ require_relative '../core/helpers'
 
 # EJECT-START
 
+  # Update an existing EntityName.
+  #
+  # @param reqdata [EntityNameUpdateData, Hash, nil] body data
+  # @param ctrl [Object, nil] optional per-call control
+  # @return [EntityName, Hash] the updated EntityName; raises ProjectNameError on failure
   def update(reqdata, ctrl = nil)
     utility = @_utility
     ctx = utility.make_context.call({

package/project/.sdk/src/cmp/rb/fragment/Main.fragment.rb

@@ -13,6 +13,9 @@ require_relative 'config'
 require_relative 'feature/base_feature'
 require_relative 'features'
 
+# Load typed models (Struct value objects).
+require_relative 'ProjectName_types'
+
 
 class ProjectNameSDK
   attr_accessor :mode, :features, :options
@@ -131,16 +134,29 @@ class ProjectNameSDK
     end
 
     _, err = utility.prepare_auth.call(ctx)
-    return nil, err if err
+    raise err if err
+
+    # make_fetch_def returns a (fetchdef, err) tuple; destructure it and
+    # return just the fetchdef Hash (raising on error) so callers — including
+    # direct(), which indexes fetchdef["url"] — receive a Hash, mirroring the
+    # ts/py prepare().
+    fetchdef, fd_err = utility.make_fetch_def.call(ctx)
+    raise fd_err if fd_err
 
-    utility.make_fetch_def.call(ctx)
+    fetchdef
   end
 
   def direct(fetchargs = {})
     utility = @_utility
 
-    fetchdef, err = prepare(fetchargs)
-    return { "ok" => false, "err" => err }, nil if err
+    # direct() is the raw-HTTP escape hatch: it always returns a result hash
+    # ({ "ok" => ..., ... }) and never raises. prepare() raises on error, so
+    # trap that and surface it in the hash.
+    begin
+      fetchdef = prepare(fetchargs)
+    rescue ProjectNameError => err
+      return { "ok" => false, "err" => err }
+    end
 
     fetchargs ||= {}
     ctrl = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "ctrl")) || {}
@@ -153,13 +169,13 @@ class ProjectNameSDK
     url = fetchdef["url"] || ""
     fetched, fetch_err = utility.fetcher.call(ctx, url, fetchdef)
 
-    return { "ok" => false, "err" => fetch_err }, nil if fetch_err
+    return { "ok" => false, "err" => fetch_err } if fetch_err
 
     if fetched.nil?
       return {
         "ok" => false,
         "err" => ctx.make_error("direct_no_response", "response: undefined"),
-      }, nil
+      }
     end
 
     if fetched.is_a?(Hash)
@@ -189,13 +205,13 @@ class ProjectNameSDK
         "status" => status,
         "headers" => headers,
         "data" => json_data,
-      }, nil
+      }
     end
 
     return {
       "ok" => false,
       "err" => ctx.make_error("direct_invalid", "invalid response type"),
-    }, nil
+    }
   end
 
   # <[SLOT]>

package/project/.sdk/src/cmp/ts/Config_ts.ts

@@ -11,6 +11,7 @@ import {
   each,
   indent,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -42,12 +43,8 @@ const Config = cmp(async function Config(props: any) {
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  let authPrefix = 'Bearer'
-  try {
-    const v = getModelPath(model, `main.${KIT}.config.auth.prefix`,
-      { only_active: false, required: false })
-    if (null != v) authPrefix = v
-  } catch (_e) { /* ignore */ }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
   const authBlock = authActive
     ? `auth: {
       prefix: '${authPrefix}',

package/project/.sdk/src/cmp/ts/EntityTypes_ts.ts

@@ -0,0 +1,105 @@
+
+
+// Typed-model generator (TypeScript reference target).
+//
+// Reads main.<KIT>.entity.<e>.fields[] and per-op params
+// (op.<name>.points[].args.params[]) and emits one file, src/<Sdk>Types.ts,
+// with a TS `interface <Name>` per active entity plus a request/match type per
+// active op. Field/param sentinels ($STRING, $INTEGER, ...) are turned into
+// real TS types by the shared sdkgen helper `canonToType` (source of truth:
+// @voxgig/apidef VALID_CANON).
+//
+// PORT RECIPE (language X): copy this file to EntityTypes_<X>.ts, keep the SAME
+// type-name scheme (<Name>, <Name>LoadMatch, <Name>ListMatch, <Name>CreateData,
+// <Name>UpdateData, <Name>RemoveMatch), swap the interface syntax for X's
+// struct/class/dataclass syntax, pass 'X' to canonToType, wire it into
+// Main_<X>.ts next to EntityBase, and reference the same type names from the
+// <X> op fragments + entity accessor.
+
+import {
+  cmp, each,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'ts'
+
+
+// A valid TS property key, or a quoted string literal for anything else.
+function propKey(name: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name)
+}
+
+
+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)
+
+  File({ name: model.const.Name + 'Types.' + LANG }, () => {
+
+    Content(`// Typed models for the ${model.const.Name} SDK.
+//
+// GENERATED from the API model: main.${KIT}.entity.<e>.fields[] and per-op
+// params (op.<name>.points[].args.params[]). Field/param types come from the
+// canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+// @voxgig/apidef VALID_CANON). Do not edit by hand.
+
+`)
+
+    entityList.forEach((ent: any) => {
+      const Name = ent.Name
+      const fields = (ent.fields ? each(ent.fields) : [])
+        .filter((f: any) => f.active !== false)
+
+      // Entity data model: one property per field, `req:false` -> optional.
+      Content(`export interface ${Name} {
+`)
+      fields.forEach((f: any) => {
+        const opt = false === f.req ? '?' : ''
+        Content(`  ${propKey(f.name)}${opt}: ${canonToType(f.type, LANG)}
+`)
+      })
+      Content(`}
+
+`)
+
+      // Per active op: a request/match type. The members and each member's
+      // required/optional decision come from the shared partiality policy
+      // (opRequestShape); this file only renders them as a TS interface.
+      const ops = ent.op || {}
+      ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+        if (null == ops[opname]) {
+          return
+        }
+
+        const typeName = opTypeName(Name, opname)
+        const { items } = opRequestShape(ent, opname)
+
+        Content(`export interface ${typeName} {
+`)
+        items.forEach((it: any) => {
+          const opt = it.optional ? '?' : ''
+          Content(`  ${propKey(it.name)}${opt}: ${canonToType(it.type, LANG)}
+`)
+        })
+        Content(`}
+
+`)
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

package/project/.sdk/src/cmp/ts/Entity_ts.ts

@@ -3,7 +3,8 @@ import * as Path from 'node:path'
 
 import {
   cmp, each, camelify, names,
-  File, Content, Folder, Fragment, Line, FeatureHook, Slot
+  File, Content, Folder, Fragment, Line, FeatureHook, Slot,
+  opTypeName,
 } from '@voxgig/sdkgen'
 
 import { EntityOperation } from './EntityOperation_ts'
@@ -20,6 +21,19 @@ const Entity = cmp(function Entity(props: any) {
 
   names(entrep, entity.Name, 'EntityName')
 
+  // Import exactly the typed models this entity references: its data type plus
+  // one request type per ACTIVE op (matches what EntityTypes_ts.ts emits).
+  const typeNames = [entity.Name]
+  const opnamesAll = Object.keys(entity.op || {})
+  ;['load', 'list', 'create', 'update', 'remove'].forEach((opname: string) => {
+    if (opnamesAll.includes(opname)) {
+      typeNames.push(opTypeName(entity.Name, opname))
+    }
+  })
+  const typeImport =
+    'import type {\n  ' + typeNames.join(',\n  ') +
+    `,\n} from '../${model.const.Name}Types'`
+
   const ff = Path.normalize(__dirname + '/../../../src/cmp/ts/fragment/')
 
   Folder({ name: 'src/entity' }, () => {
@@ -44,6 +58,8 @@ const Entity = cmp(function Entity(props: any) {
           SdkName: model.const.Name,
           EntityName: entity.Name,
 
+          '#TypeImports': ({ indent }: any) => Content({ indent }, typeImport),
+
           '#Feature-Hook': ({ name, indent }: any) =>
             Content({ indent }, `
 fres = featureHook(ctx, '${name}')

package/project/.sdk/src/cmp/ts/MainEntity_ts.ts

@@ -7,6 +7,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { entity } = props
 
   Content(`
+  // Entity access: \`client.${entity.Name}().list()\` / \`client.${entity.Name}().load({ id })\`.
   ${entity.Name}(data?: any) {
     const self = this
     return new ${entity.Name}Entity(self,data)

package/project/.sdk/src/cmp/ts/Main_ts.ts

@@ -23,6 +23,7 @@ import { Config } from './Config_ts'
 import { Gitignore } from './Gitignore_ts'
 import { MainEntity } from './MainEntity_ts'
 import { EntityBase } from './EntityBase_ts'
+import { EntityTypes } from './EntityTypes_ts'
 import { SdkError } from './SdkError_ts'
 
 
@@ -57,6 +58,10 @@ const Main = cmp(async function Main(props: any) {
       List({ item: entity }, ({ item }: any) =>
         Line(`import { ${item.Name}Entity } from './entity/${item.Name}Entity'`))
 
+      // Re-export the generated typed models so consumers can
+      // `import { Advice, AdviceLoadMatch } from '<pkg>'`.
+      Line(`export type * from './${model.const.Name}Types'\n`)
+
       Fragment(
         {
           from: Path.normalize(__dirname + '/../../../src/cmp/ts/fragment/Main.fragment.ts'),
@@ -99,6 +104,7 @@ if (fres instanceof Promise) { await fres }
 
     Config({ target })
     EntityBase({ target })
+    EntityTypes({ target })
 
   })
 })

package/project/.sdk/src/cmp/ts/Package_ts.ts

@@ -5,6 +5,12 @@ import {
   cmp,
   each,
   omap,
+  packageName,
+  pkgDescription,
+  keywords,
+  repoInfo,
+  PUBLISHER,
+  PUBLISHER_URL,
 } from '@voxgig/sdkgen'
 
 
@@ -43,16 +49,17 @@ const Package = cmp(async function Package(props: any) {
           dev: only('dev', target.deps),
         })
 
-  const sdkname = model.name
   const SdkName = nom(model, 'Name')
-  const origin = null == model.origin ? '' : `@${model.origin}/`
-  const sdknamesuffix = model.origin?.endsWith('-sdk') ? '' : '-sdk'
+  const { repoUrl, issuesUrl } = repoInfo(model)
 
-  // TODO: complete SDK meta data in model and use here
   const pkg = {
-    name: `${origin}${sdkname}${sdknamesuffix}`,
+    name: packageName(model, 'npm'),
     version: `0.0.1`,
-    description: 'DESCRIPTION',
+    description: pkgDescription(model, target.name),
+    keywords: keywords(model),
+    homepage: `${repoUrl}#readme`,
+    repository: { type: 'git', url: `git+${repoUrl}.git` },
+    bugs: { url: issuesUrl },
     main: `dist/${SdkName}SDK.js`,
     type: 'commonjs',
     types: `dist/${SdkName}SDK.d.ts`,
@@ -67,7 +74,7 @@ const Package = cmp(async function Package(props: any) {
       "clean": "rm -rf node_modules yarn.lock package-lock.json",
       "reset": "npm run clean && npm i && npm run build && npm test",
     },
-    author: `${SdkName}`,
+    author: { name: PUBLISHER, url: PUBLISHER_URL },
 
     // TODO: needs to be config
     license: 'MIT',