@voxgig/sdkgen 0.35.1 → 0.36.0

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

@@ -0,0 +1,130 @@
+
+import * as Path from 'node:path'
+
+import {
+  cmp, each, names, cmap,
+  List, File, Content, Copy, Folder, Fragment, Line, FeatureHook,
+} from '@voxgig/sdkgen'
+
+
+import type {
+  ModelEntity
+} from '@voxgig/apidef'
+
+
+import {
+  KIT,
+  getModelPath
+} from '@voxgig/apidef'
+
+
+import { Package } from './Package_rb'
+import { Config } from './Config_rb'
+import { MainEntity } from './MainEntity_rb'
+
+
+const Main = cmp(async function Main(props: any) {
+
+  const { target } = props
+  const { model } = props.ctx$
+
+  const entity: ModelEntity = getModelPath(model, `main.${KIT}.entity`)
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  Package({ target })
+
+  // Copy tm/rb files with replacements
+  Copy({
+    from: 'tm/' + target.name,
+    exclude: [/src\//],
+    replace: {
+      ...props.ctx$.stdrep,
+    }
+  })
+
+  // Generate main SDK file
+  File({ name: model.name + '_sdk.' + target.ext }, () => {
+
+    Fragment(
+      {
+        from: Path.normalize(__dirname + '/../../../src/cmp/rb/fragment/Main.fragment.rb'),
+        replace: {
+          ...props.ctx$.stdrep,
+
+          '#BuildFeatures': ({ indent }: any) => {
+            each(feature, (feat: any) => {
+              const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+              Content({ indent }, `  # feature: ${feat.name}
+`)
+            })
+          },
+
+          '#Feature-Hook': ({ name, indent }: any) => Content({ indent }, `
+utility.feature_hook.call(@_rootctx, "${name}")
+`),
+
+        }
+      },
+
+      // Entities - injected at SLOT
+      () => {
+        each(entity, (entity: ModelEntity) => {
+          const entitySDK = getModelPath(model, `main.${KIT}.entity.${entity.name}`)
+          const entprops = { target, entity, entitySDK }
+          MainEntity(entprops)
+        })
+      })
+  })
+
+  // Generate config module
+  Folder({ name: '.' }, () => {
+    Config({ target })
+  })
+
+  // Generate feature factory module
+  File({ name: 'features.' + target.ext }, () => {
+    Content(`# ${model.const.Name} SDK feature factory
+
+require_relative 'feature/base_feature'
+`)
+
+    each(feature, (feat: any) => {
+      if (feat.name !== 'base') {
+        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        Content(`require_relative 'feature/${feat.name}_feature'
+`)
+      }
+    })
+
+    Content(`
+
+module ${model.const.Name}Features
+  def self.make_feature(name)
+    case name
+    when "base"
+      ${model.const.Name}BaseFeature.new
+`)
+
+    each(feature, (feat: any) => {
+      if (feat.name !== 'base') {
+        const fname = feat.name.charAt(0).toUpperCase() + feat.name.slice(1)
+        Content(`    when "${feat.name}"
+      ${model.const.Name}${fname}Feature.new
+`)
+      }
+    })
+
+    Content(`    else
+      ${model.const.Name}BaseFeature.new
+    end
+  end
+end
+`)
+  })
+
+})
+
+
+export {
+  Main
+}

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

@@ -0,0 +1,111 @@
+
+import {
+  Content,
+  File,
+  cmp,
+  each,
+} from '@voxgig/sdkgen'
+
+
+import {
+  KIT,
+  Model,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+const Package = cmp(async function Package(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const feature = getModelPath(model, `main.${KIT}.feature`)
+
+  // Generate Gemfile
+  File({ name: 'Gemfile' }, () => {
+    Content(`source "https://rubygems.org"
+
+gemspec
+
+`)
+
+    // Collect dependencies from features
+    each(feature, (f: any) => {
+      const rbDeps = f.deps?.rb
+      if (rbDeps) {
+        each(rbDeps, (dep: any) => {
+          if (dep.active) {
+            Content(`gem "${dep.key$}", "~> ${dep.version}"
+`)
+          }
+        })
+      }
+    })
+
+    // Add target-level deps
+    const targetDeps = target.deps
+    if (targetDeps) {
+      each(targetDeps, (dep: any) => {
+        if (dep.active !== false) {
+          Content(`gem "${dep.key$}", "~> ${dep.version || '0.0'}"
+`)
+        }
+      })
+    }
+  })
+
+  // Generate gemspec
+  File({ name: model.name + '_sdk.gemspec' }, () => {
+    Content(`Gem::Specification.new do |spec|
+  spec.name          = "${model.name}-sdk"
+  spec.version       = "0.0.1"
+  spec.authors       = ["Voxgig"]
+  spec.summary       = "${model.const.Name} SDK for Ruby"
+  spec.license       = "MIT"
+  spec.homepage      = "https://github.com/voxgig/${model.name}-sdk"
+
+  spec.files         = Dir["lib/**/*.rb", "*.rb"]
+  spec.require_paths = ["."]
+
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.add_dependency "json"
+`)
+
+    // Collect dependencies from features
+    each(feature, (f: any) => {
+      const rbDeps = f.deps?.rb
+      if (rbDeps) {
+        each(rbDeps, (dep: any) => {
+          if (dep.active) {
+            Content(`  spec.add_dependency "${dep.key$}", "~> ${dep.version}"
+`)
+          }
+        })
+      }
+    })
+
+    // Add target-level deps
+    const targetDeps = target.deps
+    if (targetDeps) {
+      each(targetDeps, (dep: any) => {
+        if (dep.active !== false) {
+          Content(`  spec.add_dependency "${dep.key$}", "~> ${dep.version || '0.0'}"
+`)
+        }
+      })
+    }
+
+    Content(`
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+end
+`)
+  })
+})
+
+
+export {
+  Package
+}

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

@@ -0,0 +1,42 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Data as hashes
+
+The Ruby SDK uses plain Ruby hashes throughout rather than typed
+objects. This mirrors the dynamic nature of the API and keeps the
+SDK flexible — no code generation is needed when the API schema
+changes.
+
+Use \`Helpers.to_map()\` to safely validate that a value is a hash.
+
+### Module structure
+
+\`\`\`
+rb/
+├── ${model.name}_sdk.rb       -- Main SDK module
+├── config.rb                  -- Configuration
+├── features.rb                -- Feature factory
+├── core/                      -- Core types and context
+├── entity/                    -- Entity implementations
+├── feature/                   -- Built-in features (Base, Test, Log)
+├── utility/                   -- Utility functions and struct library
+└── test/                      -- Test suites
+\`\`\`
+
+The main module (\`${model.name}_sdk\`) exports the SDK class
+and test helper. Import entity or utility modules directly only
+when needed.
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,98 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeHowto = cmp(function ReadmeHowto(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Make a direct HTTP request
+
+For endpoints not covered by entity methods:
+
+\`\`\`ruby
+result, err = client.direct({
+  "path" => "/api/resource/{id}",
+  "method" => "GET",
+  "params" => { "id" => "example" },
+})
+raise err if err
+
+if result["ok"]
+  puts result["status"]  # 200
+  puts result["data"]    # response body
+end
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`ruby
+fetchdef, err = client.prepare({
+  "path" => "/api/resource/{id}",
+  "method" => "DELETE",
+  "params" => { "id" => "example" },
+})
+raise err if err
+
+puts fetchdef["url"]
+puts fetchdef["method"]
+puts fetchdef["headers"]
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing — no server required:
+
+\`\`\`ruby
+client = ${model.const.Name}SDK.test(nil, nil)
+
+result, err = client.${model.const.Name}(nil).load(
+  { "id" => "test01" }, nil
+)
+# result contains mock response data
+\`\`\`
+
+### Use a custom fetch function
+
+Replace the HTTP transport with your own function:
+
+\`\`\`ruby
+mock_fetch = ->(url, init) {
+  return {
+    "status" => 200,
+    "statusText" => "OK",
+    "headers" => {},
+    "json" => ->() { { "id" => "mock01" } },
+  }, nil
+}
+
+client = ${model.const.Name}SDK.new({
+  "base" => "http://localhost:8080",
+  "system" => {
+    "fetch" => mock_fetch,
+  },
+})
+\`\`\`
+
+### Run live tests
+
+Create a \`.env.local\` file at the project root:
+
+\`\`\`
+${model.NAME}_TEST_LIVE=TRUE
+${model.NAME}_APIKEY=<your-key>
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+cd rb && ruby -Itest -e "Dir['test/*_test.rb'].each { |f| require_relative f }"
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

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

@@ -0,0 +1,31 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
+  const { target, ctx$ } = props
+  const { model } = ctx$
+
+  Content(`\`\`\`bash
+gem install ${model.name}-sdk
+\`\`\`
+
+Or add to your \`Gemfile\`:
+
+\`\`\`ruby
+gem "${model.name}-sdk"
+\`\`\`
+
+Then run:
+
+\`\`\`bash
+bundle install
+\`\`\`
+
+`)
+})
+
+
+export {
+  ReadmeInstall
+}

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

@@ -0,0 +1,129 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+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)
+
+  Content(`### ${model.const.Name}SDK
+
+\`\`\`ruby
+require_relative "${model.name}_sdk"
+client = ${model.const.Name}SDK.new(options)
+\`\`\`
+
+Creates a new SDK client.
+
+| Option | Type | Description |
+| --- | --- | --- |
+| \`apikey\` | \`String\` | API key for authentication. |
+| \`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\` | \`Hash\` | Feature activation flags. |
+| \`extend\` | \`Hash\` | Additional Feature instances to load. |
+| \`system\` | \`Hash\` | System overrides (e.g. custom \`fetch\` lambda). |
+
+### test
+
+\`\`\`ruby
+client = ${model.const.Name}SDK.test(testopts, sdkopts)
+\`\`\`
+
+Creates a test-mode client with mock transport. Both arguments may be \`nil\`.
+
+### ${model.const.Name}SDK methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`options_map\` | \`() -> Hash\` | Deep copy of current SDK options. |
+| \`get_utility\` | \`() -> Utility\` | Copy of the SDK utility object. |
+| \`prepare\` | \`(fetchargs) -> [Hash, err]\` | Build an HTTP request definition without sending. |
+| \`direct\` | \`(fetchargs) -> [Hash, err]\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}\` | \`(data) -> ${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`
+### Entity interface
+
+All entities share the same interface.
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`load\` | \`(reqmatch, ctrl) -> [any, err]\` | Load a single entity by match criteria. |
+| \`list\` | \`(reqmatch, ctrl) -> [any, err]\` | List entities matching the criteria. |
+| \`create\` | \`(reqdata, ctrl) -> [any, err]\` | Create a new entity. |
+| \`update\` | \`(reqdata, ctrl) -> [any, err]\` | Update an existing entity. |
+| \`remove\` | \`(reqmatch, ctrl) -> [any, err]\` | Remove an entity. |
+| \`data_get\` | \`() -> Hash\` | Get entity data. |
+| \`data_set\` | \`(data)\` | Set entity data. |
+| \`match_get\` | \`() -> Hash\` | Get entity match criteria. |
+| \`match_set\` | \`(match)\` | Set entity match criteria. |
+| \`make\` | \`() -> Entity\` | Create a new instance with the same options. |
+| \`get_name\` | \`() -> String\` | Return the entity name. |
+
+### Result shape
+
+Entity operations return \`[any, err]\`. The first value is a
+\`Hash\` with these keys:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| \`ok\` | \`Boolean\` | \`true\` if the HTTP status is 2xx. |
+| \`status\` | \`Integer\` | HTTP status code. |
+| \`headers\` | \`Hash\` | Response headers. |
+| \`data\` | \`any\` | 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/rb/ReadmeQuick_rb.ts

@@ -0,0 +1,99 @@
+
+import { cmp, each, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+  nom,
+} from '@voxgig/apidef'
+
+
+const ReadmeQuick = cmp(function ReadmeQuick(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 nestedEntity = Object.values(entity).find((e: any) =>
+    e.active !== false && e.ancestors && e.ancestors.length > 0
+  ) as any
+
+  Content(`### 1. Create a client
+
+\`\`\`ruby
+require_relative "${model.name}_sdk"
+
+client = ${model.const.Name}SDK.new({
+  "apikey" => ENV["${model.NAME}_APIKEY"],
+})
+\`\`\`
+
+`)
+
+  if (exampleEntity) {
+    const eName = nom(exampleEntity, 'Name')
+    const opnames = Object.keys(exampleEntity.op || {})
+
+    if (opnames.includes('list')) {
+      Content(`### 2. List ${eName.toLowerCase()}s
+
+\`\`\`ruby
+result, err = client.${eName}(nil).list(nil, nil)
+raise err if err
+
+if result.is_a?(Array)
+  result.each do |item|
+    d = item.data_get
+    puts "#{d["id"]} #{d["name"]}"
+  end
+end
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('load')) {
+      Content(`### 3. Load a ${eName.toLowerCase()}
+
+\`\`\`ruby
+result, err = client.${eName}(nil).load({ "id" => "example_id" }, nil)
+raise err if err
+puts result
+\`\`\`
+
+`)
+    }
+
+    if (opnames.includes('create') || opnames.includes('update') || opnames.includes('remove')) {
+      Content(`### 4. Create, update, and remove
+
+\`\`\`ruby
+`)
+      if (opnames.includes('create')) {
+        Content(`# Create
+created, _ = client.${eName}(nil).create({ "name" => "Example" }, nil)
+
+`)
+      }
+      if (opnames.includes('update')) {
+        Content(`# Update
+client.${eName}(nil).update({ "id" => created["id"], "name" => "Example-Renamed" }, nil)
+
+`)
+      }
+      if (opnames.includes('remove')) {
+        Content(`# Remove
+client.${eName}(nil).remove({ "id" => created["id"] }, nil)
+`)
+      }
+      Content(`\`\`\`
+
+`)
+    }
+  }
+})
+
+
+export {
+  ReadmeQuick
+}

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

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