@voxgig/sdkgen 1.2.1 → 1.3.2

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

@@ -144,16 +144,23 @@ class ProjectNameSDK:
 
         _, err = utility.prepare_auth(ctx)
         if err is not None:
-            return None, err
+            raise err
 
-        return utility.make_fetch_def(ctx)
+        fetchdef, err = utility.make_fetch_def(ctx)
+        if err is not None:
+            raise err
+
+        return fetchdef
 
     def direct(self, fetchargs=None):
         utility = self._utility
 
-        fetchdef, err = self.prepare(fetchargs)
-        if err is not None:
-            return {"ok": False, "err": err}, None
+        try:
+            fetchdef = self.prepare(fetchargs)
+        except Exception as err:
+            # direct() is the raw-HTTP escape hatch: it never raises, it
+            # returns a result object callers branch on via result["ok"].
+            return {"ok": False, "err": err}
 
         if fetchargs is None:
             fetchargs = {}
@@ -170,13 +177,13 @@ class ProjectNameSDK:
         fetched, fetch_err = utility.fetcher(ctx, url, fetchdef)
 
         if fetch_err is not None:
-            return {"ok": False, "err": fetch_err}, None
+            return {"ok": False, "err": fetch_err}
 
         if fetched is None:
             return {
                 "ok": False,
                 "err": ctx.make_error("direct_no_response", "response: undefined"),
-            }, None
+            }
 
         if isinstance(fetched, dict):
             status = helpers.to_int(vs.getprop(fetched, "status"))
@@ -205,17 +212,17 @@ class ProjectNameSDK:
                 "status": status,
                 "headers": headers,
                 "data": json_data,
-            }, None
+            }
 
         return {
             "ok": False,
             "err": ctx.make_error("direct_invalid", "invalid response type"),
-        }, None
+        }
 
     # <[SLOT]>
 
     @classmethod
-    def test(cls, testopts=None, sdkopts=None):
+    def test(cls, testopts=None, sdkopts=None) -> "ProjectNameSDK":
         if sdkopts is None:
             sdkopts = {}
         sdkopts = vs.clone(sdkopts)

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

@@ -10,6 +10,7 @@ import {
   cmp,
   each,
   isAuthActive,
+  resolveAuthPrefix,
 } from '@voxgig/sdkgen'
 
 
@@ -39,8 +40,8 @@ const Config = cmp(async function Config(props: any) {
   const headers = getModelPath(model, `main.${KIT}.config.headers`) || {}
 
   const authActive = isAuthActive(model)
-  let authPrefix = ''
-  try { authPrefix = getModelPath(model, `main.${KIT}.config.auth.prefix`) } catch (_e) { }
+  // config.auth.prefix override -> spec-derived info.security.prefix -> 'Bearer'
+  const authPrefix = resolveAuthPrefix(model)
 
   let baseUrl = ''
   try { baseUrl = getModelPath(model, `main.${KIT}.info.servers.0.url`) } catch (_e) { }

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

@@ -0,0 +1,136 @@
+
+
+// Typed-model generator (Ruby target).
+//
+// Ported from the TypeScript reference EntityTypes_ts.ts. Reads
+// main.<KIT>.entity.<e>.fields[] and per-op params (op.<name>.points[].args.params[])
+// and emits one file, <Sdk>_types.rb, containing a keyword-init Struct per active
+// entity plus a request/match Struct per active op. Ruby has no enforced static
+// types, so each member carries a YARD `@!attribute`/`@return` annotation whose
+// element type comes from the canonical sentinels via the shared sdkgen helper
+// `canonToType` (source of truth: @voxgig/apidef VALID_CANON):
+//   $STRING -> String, $INTEGER -> Integer, $NUMBER -> Float, $BOOLEAN -> Boolean,
+//   $OBJECT -> Hash, $ARRAY -> Array, unknown -> Object.
+//
+// Type-name scheme (IDENTICAL to TS): data type = <Name>; per-op request
+// <Name>LoadMatch / <Name>ListMatch / <Name>RemoveMatch (query/id ops),
+// <Name>CreateData / <Name>UpdateData (body ops). An op WITH params -> a Struct of
+// those params (reqd:false -> annotated `[Type, nil]`). An op WITHOUT params -> a
+// Struct over the entity fields (Struct members are always optional/nil, so this is
+// the Ruby stand-in for TS `Partial<Name>`; callers may equally pass a plain Hash).
+//
+// Struct.new(keyword_init: true) gives value objects usable as `Advice.new(id: ...)`.
+// The file is required by the main SDK module so these constants are always loaded.
+
+import {
+  cmp, each,
+  File, Content,
+} from '@voxgig/sdkgen'
+
+import { canonToType, opTypeName, opRequestShape } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const LANG = 'rb'
+
+
+// A Ruby symbol literal for a member name: bare for identifiers, quoted otherwise.
+function symName(name: string): string {
+  return /^[A-Za-z_][A-Za-z0-9_]*[?!=]?$/.test(name) ? ':' + name : ':"' + name + '"'
+}
+
+
+// Emit one typed value class: a YARD @!attribute block plus a keyword-init
+// Struct. Ruby's `Struct.new` rejects zero members, so an empty shape falls
+// back to a plain empty class (keeps the type name available).
+function emitStruct(
+  typeName: string,
+  doc: string,
+  members: Array<{ name: string, type: unknown, optional: boolean }>,
+) {
+  let block = `# ${doc}\n`
+
+  members.forEach((m) => {
+    const t = canonToType(m.type, LANG)
+    const ret = m.optional ? `[${t}, nil]` : `[${t}]`
+    block += `#\n# @!attribute [rw] ${m.name}\n#   @return ${ret}\n`
+  })
+
+  if (0 === members.length) {
+    block += `class ${typeName}\nend\n\n`
+    Content(block)
+    return
+  }
+
+  block += `${typeName} = Struct.new(\n`
+  members.forEach((m) => {
+    block += `  ${symName(m.name)},\n`
+  })
+  block += `  keyword_init: true\n)\n\n`
+
+  Content(block)
+}
+
+
+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(`# frozen_string_literal: true
+
+# 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[]). Member types come from the
+# canonical type sentinels via @voxgig/sdkgen canonToType (source of truth:
+# @voxgig/apidef VALID_CANON). Ruby types are unenforced; these YARD
+# annotations document the shapes. 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 member per field (`req:false` -> nilable).
+      emitStruct(
+        Name,
+        `${Name} entity data model.`,
+        fields.map((f: any) => ({ name: f.name, type: f.type, optional: false === f.req })),
+      )
+
+      // Per active op: a request/match Struct. Members and their optionality
+      // come from the shared partiality policy (opRequestShape); this file only
+      // renders them as a keyword-init Struct.
+      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)
+
+        emitStruct(
+          typeName,
+          `Request payload for ${Name}#${opname}.`,
+          items,
+        )
+      })
+    })
+  })
+})
+
+
+export {
+  EntityTypes,
+}

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

@@ -8,6 +8,7 @@ const MainEntity = cmp(async function MainEntity(props: any) {
   const { model } = props.ctx$
 
   Content(`
+  # Canonical facade: client.${entity.Name}.list / client.${entity.Name}.load({ "id" => ... })
   def ${entity.Name}(data = nil)
     require_relative 'entity/${entity.name}_entity'
     ${entity.Name}Entity.new(self, data)

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

@@ -22,6 +22,7 @@ import { Package } from './Package_rb'
 import { Config } from './Config_rb'
 import { Gitignore } from './Gitignore_rb'
 import { MainEntity } from './MainEntity_rb'
+import { EntityTypes } from './EntityTypes_rb'
 
 
 const Main = cmp(async function Main(props: any) {
@@ -84,6 +85,9 @@ utility.feature_hook.call(@_rootctx, "${name}")
     Config({ target })
   })
 
+  // Generate typed models (<Sdk>_types.rb) — required by the main SDK file.
+  EntityTypes({ target })
+
   // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`# ${model.const.Name} SDK feature factory

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

@@ -4,6 +4,8 @@ import {
   File,
   cmp,
   collectDeps,
+  pkgDescription,
+  repoInfo,
 } from '@voxgig/sdkgen'
 
 
@@ -24,6 +26,7 @@ const Package = cmp(async function Package(props: any) {
   const ns = model.origin || 'voxgig-sdk'
   const pkgBase = ns.endsWith('-sdk') ? model.name : `${model.name}-sdk`
   const gemName = `${ns}-${pkgBase}`
+  const { repoUrl, issuesUrl, changelogUrl } = repoInfo(model)
 
   const versionOf = (d: { version: string; source: 'feature' | 'target' }) =>
     d.source === 'target' ? (d.version || '0.0') : d.version
@@ -44,23 +47,47 @@ gemspec
 
   // Generate gemspec
   File({ name: model.const.Name + '_sdk.gemspec' }, () => {
+    // RubyGems rejects a gemspec that declares the same runtime dependency
+    // twice (Gem::InvalidSpecificationException at `gem build`), so the
+    // unconstrained json fallback is only emitted when the model's own
+    // dependency list doesn't already declare json.
+    const deps = collectDeps(model, target.name, target.deps)
+    const hasJson = deps.some((d: any) => 'json' === d.name)
+
     Content(`Gem::Specification.new do |spec|
   spec.name          = "${gemName}"
   spec.version       = "0.0.1"
   spec.authors       = ["Voxgig"]
-  spec.summary       = "${model.const.Name} SDK for Ruby"
+  spec.summary       = "${pkgDescription(model, 'rb')}"
+  spec.description   = "${pkgDescription(model, 'rb')}"
   spec.license       = "MIT"
-  spec.homepage      = "https://github.com/${ns}/${model.name}-sdk"
-
-  spec.files         = Dir["lib/**/*.rb", "*.rb"]
+  spec.homepage      = "${repoUrl}"
+  spec.metadata      = {
+    "homepage_uri"          => "${repoUrl}",
+    "source_code_uri"       => "${repoUrl}",
+    "bug_tracker_uri"       => "${issuesUrl}",
+    "changelog_uri"         => "${changelogUrl}",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files         = Dir[
+    "*.rb",
+    "core/**/*.rb",
+    "entity/**/*.rb",
+    "feature/**/*.rb",
+    "utility/**/*.rb",
+    "LICENSE",
+    "README.md",
+    "REFERENCE.md"
+  ]
   spec.require_paths = ["."]
 
   spec.required_ruby_version = ">= 3.0"
-
+${hasJson ? '' : `
   spec.add_dependency "json"
-`)
+`}`)
 
-    for (const d of collectDeps(model, target.name, target.deps)) {
+    for (const d of deps) {
       Content(`  spec.add_dependency "${d.name}", "~> ${versionOf(d)}"
 `)
     }

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

@@ -1,5 +1,5 @@
 
-import { cmp, each, Content } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonToType, canonKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
 
 import {
   KIT,
@@ -7,6 +7,19 @@ import {
 } from '@voxgig/apidef'
 
 
+// A type-correct Ruby literal for a field's canonical type — the create body
+// is EXECUTED by the doc test, so it must carry a real value per field.
+// Strings render the quoted placeholder.
+function rbLit(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 '[]'
+  if ('OBJECT' === k) return '{}'
+  return `"${placeholder}"`
+}
+
+
 // Operation method spelling differs between Go and other languages — Go
 // uses PascalCase methods with explicit ctrl arg, others use lowercase
 // methods with optional ctrl. The op descriptions are language-agnostic.
@@ -41,6 +54,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
     const fields = entity.fields || []
+    // Model-driven id key: null when this entity has no id-like field.
+    const idF = entityIdField(entity)
 
     Content(`
 ### ${entity.Name}
@@ -53,7 +68,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    Content(`Create an instance: \`const ${entity.name} = client.${entity.Name}()\`
+    Content(`Create an instance: \`${entity.name} = client.${entity.Name}\`
 
 `)
 
@@ -84,7 +99,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
       each(fields, (field: any) => {
         const desc = field.short || ''
-        Content(`| \`${field.name}\` | \`${field.type || 'any'}\` | ${desc} |
+        Content(`| \`${field.name}\` | \`${canonToType(field.type, target.name)}\` | ${desc} |
 `)
       })
 
@@ -93,10 +108,23 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
     }
 
     if (opnames.includes('load')) {
+      // The id key plus every REQUIRED match key (parent path params like
+      // page_id) — the same shape the runtime resolves path params from, so
+      // the example always works.
+      const loadItems = opRequestShape(entity, '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}" => ${rbLit(it.type,
+            it.name === idF ? entity.name + '_id' : it.name)}`).join(', ')} }`
+        : ''
       Content(`#### Example: Load
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_id' })
+\`\`\`ruby
+# load returns the bare ${entity.Name} record (raises on error).
+${entity.name} = client.${entity.Name}.load(${loadArg})
 \`\`\`
 
 `)
@@ -105,24 +133,30 @@ const ${entity.name} = await client.${entity.Name}().load({ id: '${entity.name}_
     if (opnames.includes('list')) {
       Content(`#### Example: List
 
-\`\`\`ts
-const ${entity.name}s = await client.${entity.Name}().list()
+\`\`\`ruby
+# list returns an Array of ${entity.Name} records (raises on error).
+${entity.name}s = client.${entity.Name}.list
 \`\`\`
 
 `)
     }
 
     if (opnames.includes('create')) {
+      // Members come from the SAME shape the runtime validates
+      // (opRequestShape): every required member must appear — including a
+      // required id and parent keys like page_id — with a real, executable
+      // literal (the doc test RUNS this block, so a comment placeholder
+      // would break it).
+      const createItems = opRequestShape(entity, 'create').items
+        .filter((it: any) => !it.optional)
       Content(`#### Example: Create
 
-\`\`\`ts
-const ${entity.name} = await client.${entity.Name}().create({
+\`\`\`ruby
+${entity.name} = client.${entity.Name}.create({
 `)
-      each(fields, (field: any) => {
-        if ('id' !== field.name && field.req) {
-          Content(`  ${field.name}: /* ${field.type || 'value'} */,
+      createItems.map((it: any) => {
+        Content(`  "${it.name}" => ${rbLit(it.type, 'example_' + it.name)}, # ${canonToType(it.type, target.name)}
 `)
-        }
       })
       Content(`})
 \`\`\`