@voxgig/sdkgen 0.35.2 → 0.36.0

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

@@ -0,0 +1,26 @@
+require_relative '../utility/struct/voxgig_struct'
+require_relative '../core/helpers'
+
+# EJECT-START
+
+  def remove(reqmatch, ctrl = nil)
+    utility = @_utility
+    ctx = utility.make_context.call({
+      "opname" => "remove",
+      "ctrl" => ctrl,
+      "match" => @_match,
+      "data" => @_data,
+      "reqmatch" => reqmatch,
+    }, @_entctx)
+
+    _run_op(ctx) do
+      if ctx.result
+        @_match = ctx.result.resmatch if ctx.result.resmatch
+        if ctx.result.resdata
+          @_data = ProjectNameHelpers.to_map(VoxgigStruct.clone(ctx.result.resdata)) || {}
+        end
+      end
+    end
+  end
+
+# EJECT-END

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

@@ -0,0 +1,26 @@
+require_relative '../utility/struct/voxgig_struct'
+require_relative '../core/helpers'
+
+# EJECT-START
+
+  def update(reqdata, ctrl = nil)
+    utility = @_utility
+    ctx = utility.make_context.call({
+      "opname" => "update",
+      "ctrl" => ctrl,
+      "match" => @_match,
+      "data" => @_data,
+      "reqdata" => reqdata,
+    }, @_entctx)
+
+    _run_op(ctx) do
+      if ctx.result
+        @_match = ctx.result.resmatch if ctx.result.resmatch
+        if ctx.result.resdata
+          @_data = ProjectNameHelpers.to_map(VoxgigStruct.clone(ctx.result.resdata)) || {}
+        end
+      end
+    end
+  end
+
+# EJECT-END

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

@@ -0,0 +1,203 @@
+# ProjectName SDK
+
+require_relative 'utility/struct/voxgig_struct'
+require_relative 'core/utility_type'
+require_relative 'core/spec'
+require_relative 'core/helpers'
+
+# Load utility registration
+require_relative 'utility/register'
+
+# Load config and features
+require_relative 'config'
+require_relative 'feature/base_feature'
+require_relative 'features'
+
+
+class ProjectNameSDK
+  attr_accessor :mode, :features, :options
+
+  def initialize(options = {})
+    @mode = "live"
+    @features = []
+    @options = nil
+
+    utility = ProjectNameUtility.new
+    @_utility = utility
+
+    config = ProjectNameConfig.make_config
+
+    @_rootctx = utility.make_context.call({
+      "client" => self,
+      "utility" => utility,
+      "config" => config,
+      "options" => options || {},
+      "shared" => {},
+    }, nil)
+
+    @options = utility.make_options.call(@_rootctx)
+
+    if VoxgigStruct.getpath(@options, "feature.test.active") == true
+      @mode = "test"
+    end
+
+    @_rootctx.options = @options
+
+    # Add features from config.
+    feature_opts = ProjectNameHelpers.to_map(VoxgigStruct.getprop(@options, "feature"))
+    if feature_opts
+      items = VoxgigStruct.items(feature_opts)
+      if items
+        items.each do |item|
+          fname = item[0]
+          fopts = ProjectNameHelpers.to_map(item[1])
+          if fopts && fopts["active"] == true
+            utility.feature_add.call(@_rootctx, ProjectNameFeatures.make_feature(fname))
+          end
+        end
+      end
+    end
+
+    # Add extension features.
+    extend_val = VoxgigStruct.getprop(@options, "extend")
+    if extend_val.is_a?(Array)
+      extend_val.each do |f|
+        if f.respond_to?(:get_name)
+          utility.feature_add.call(@_rootctx, f)
+        end
+      end
+    end
+
+    # Initialize features.
+    @features.each do |f|
+      utility.feature_init.call(@_rootctx, f)
+    end
+
+    utility.feature_hook.call(@_rootctx, "PostConstruct")
+  end
+
+  def options_map
+    out = VoxgigStruct.clone(@options)
+    out.is_a?(Hash) ? out : {}
+  end
+
+  def get_utility
+    ProjectNameUtility.copy(@_utility)
+  end
+
+  def get_root_ctx
+    @_rootctx
+  end
+
+  def prepare(fetchargs = {})
+    utility = @_utility
+    fetchargs ||= {}
+
+    ctrl = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "ctrl")) || {}
+
+    ctx = utility.make_context.call({
+      "opname" => "prepare",
+      "ctrl" => ctrl,
+    }, @_rootctx)
+
+    opts = @options
+    path = VoxgigStruct.getprop(fetchargs, "path") || ""
+    path = "" unless path.is_a?(String)
+    method_val = VoxgigStruct.getprop(fetchargs, "method") || "GET"
+    method_val = "GET" unless method_val.is_a?(String)
+    params = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "params")) || {}
+    query = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "query")) || {}
+    headers = utility.prepare_headers.call(ctx)
+
+    base = VoxgigStruct.getprop(opts, "base") || ""
+    base = "" unless base.is_a?(String)
+    prefix = VoxgigStruct.getprop(opts, "prefix") || ""
+    prefix = "" unless prefix.is_a?(String)
+    suffix = VoxgigStruct.getprop(opts, "suffix") || ""
+    suffix = "" unless suffix.is_a?(String)
+
+    ctx.spec = ProjectNameSpec.new({
+      "base" => base, "prefix" => prefix, "suffix" => suffix,
+      "path" => path, "method" => method_val,
+      "params" => params, "query" => query, "headers" => headers,
+      "body" => VoxgigStruct.getprop(fetchargs, "body"),
+      "step" => "start",
+    })
+
+    # Merge user-provided headers.
+    uh = VoxgigStruct.getprop(fetchargs, "headers")
+    if uh.is_a?(Hash)
+      uh.each { |k, v| ctx.spec.headers[k] = v }
+    end
+
+    _, err = utility.prepare_auth.call(ctx)
+    return nil, err if err
+
+    utility.make_fetch_def.call(ctx)
+  end
+
+  def direct(fetchargs = {})
+    utility = @_utility
+
+    fetchdef, err = prepare(fetchargs)
+    return { "ok" => false, "err" => err }, nil if err
+
+    fetchargs ||= {}
+    ctrl = ProjectNameHelpers.to_map(VoxgigStruct.getprop(fetchargs, "ctrl")) || {}
+
+    ctx = utility.make_context.call({
+      "opname" => "direct",
+      "ctrl" => ctrl,
+    }, @_rootctx)
+
+    url = fetchdef["url"] || ""
+    fetched, fetch_err = utility.fetcher.call(ctx, url, fetchdef)
+
+    return { "ok" => false, "err" => fetch_err }, nil 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)
+      status = ProjectNameHelpers.to_int(VoxgigStruct.getprop(fetched, "status"))
+      json_data = nil
+      jf = VoxgigStruct.getprop(fetched, "json")
+      json_data = jf.call if jf.is_a?(Proc)
+
+      return {
+        "ok" => status >= 200 && status < 300,
+        "status" => status,
+        "headers" => VoxgigStruct.getprop(fetched, "headers"),
+        "data" => json_data,
+      }, nil
+    end
+
+    return {
+      "ok" => false,
+      "err" => ctx.make_error("direct_invalid", "invalid response type"),
+    }, nil
+  end
+
+  # <[SLOT]>
+
+  def self.test(testopts = nil, sdkopts = nil)
+    sdkopts = sdkopts || {}
+    sdkopts = VoxgigStruct.clone(sdkopts)
+    sdkopts = {} unless sdkopts.is_a?(Hash)
+
+    testopts = testopts || {}
+    testopts = VoxgigStruct.clone(testopts)
+    testopts = {} unless testopts.is_a?(Hash)
+    testopts["active"] = true
+
+    VoxgigStruct.setpath(sdkopts, "feature.test", testopts)
+
+    sdk = ProjectNameSDK.new(sdkopts)
+    sdk.mode = "test"
+    sdk
+  end
+end

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

@@ -0,0 +1,16 @@
+# ProjectName SDK error
+
+class ProjectNameError < StandardError
+  attr_accessor :code, :msg, :sdk
+
+  def initialize(code = "", msg = "")
+    super(msg)
+    @code = code
+    @msg = msg
+    @sdk = "ProjectName"
+  end
+
+  def error
+    "#{@sdk}: #{@code}: #{@msg}"
+  end
+end

package/project/.sdk/src/cmp/rb/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "esModuleInterop": true,
+    "module": "nodenext",
+    "noEmitOnError": true,
+    "outDir":"../dist",
+    "rootDir":".",
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "strict": true,
+    "target": "es2022",
+    "declaration": true,
+    "declarationDir": "../dist"
+  }
+}

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

@@ -0,0 +1,84 @@
+
+import * as Path from 'node:path'
+
+import {
+  clone,
+  walk,
+} from '@voxgig/struct'
+
+
+function projectPath(suffix?: string): string {
+  return Path.normalize(Path.join(__dirname, '../../..', suffix ?? ''))
+}
+
+
+function formatRubyHash(obj: any, indent: number = 0): string {
+  if (obj == null) {
+    return 'nil'
+  }
+
+  const pad = '  '.repeat(indent)
+  const padInner = '  '.repeat(indent + 1)
+
+  if (Array.isArray(obj)) {
+    if (obj.length === 0) {
+      return '[]'
+    }
+    const items = obj.map(v => padInner + formatRubyValue(v, indent + 1)).join(',\n')
+    return `[\n${items},\n${pad}]`
+  }
+
+  if (typeof obj === 'object') {
+    const entries = Object.entries(obj)
+    if (entries.length === 0) {
+      return '{}'
+    }
+    const items = entries
+      .map(([k, v]) => `${padInner}"${k}" => ${formatRubyValue(v, indent + 1)}`)
+      .join(',\n')
+    return `{\n${items},\n${pad}}`
+  }
+
+  return formatRubyValue(obj, indent)
+}
+
+
+function formatRubyValue(val: any, indent: number = 0): string {
+  if (val === null || val === undefined) {
+    return 'nil'
+  }
+  if (typeof val === 'string') {
+    return `"${val.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`
+  }
+  if (typeof val === 'number') {
+    return String(val)
+  }
+  if (typeof val === 'boolean') {
+    return val ? 'true' : 'false'
+  }
+  if (Array.isArray(val)) {
+    return formatRubyHash(val, indent)
+  }
+  if (typeof val === 'object') {
+    return formatRubyHash(val, indent)
+  }
+  return String(val)
+}
+
+
+function clean(o: any) {
+  return walk(clone(o), (k: any, v: any, p: any) => {
+    if (null != k && k.endsWith('$')) {
+      delete p[k]
+    }
+    return v
+  })
+}
+
+
+export {
+  clean,
+  formatRubyHash,
+  formatRubyValue,
+  projectPath,
+}

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

@@ -0,0 +1,34 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+
+const ReadmeExplanation = cmp(function ReadmeExplanation(props: any) {
+  const { target, ctx$: { model } } = props
+
+  Content(`### Module structure
+
+\`\`\`
+${model.name}/
+├── src/
+│   ├── ${model.Name}SDK.ts        # Main SDK class
+│   ├── entity/             # Entity implementations
+│   ├── feature/            # Built-in features (Base, Test, Log)
+│   └── utility/            # Utility functions
+├── test/                   # Test suites
+└── dist/                   # Compiled output
+\`\`\`
+
+Import the SDK from the package root:
+
+\`\`\`ts
+import { ${model.Name}SDK } from '${model.name}'
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeExplanation
+}

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

@@ -0,0 +1,123 @@
+
+import { cmp, Content } from '@voxgig/sdkgen'
+
+import {
+  KIT,
+  getModelPath,
+} from '@voxgig/apidef'
+
+
+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:
+
+\`\`\`ts
+const result = await client.direct({
+  path: '/api/resource/{id}',
+  method: 'GET',
+  params: { id: 'example' },
+})
+
+if (result.ok) {
+  console.log(result.status)  // 200
+  console.log(result.data)    // response body
+}
+\`\`\`
+
+### Prepare a request without sending it
+
+\`\`\`ts
+const fetchdef = await client.prepare({
+  path: '/api/resource/{id}',
+  method: 'DELETE',
+  params: { id: 'example' },
+})
+
+// Inspect before sending
+console.log(fetchdef.url)
+console.log(fetchdef.method)
+console.log(fetchdef.headers)
+\`\`\`
+
+### Use test mode
+
+Create a mock client for unit testing \u2014 no server required:
+
+\`\`\`ts
+const client = ${model.const.Name}SDK.test()
+
+const result = await client.Planet().load({ id: 'test01' })
+// result.ok === true
+// result.data contains mock response data
+\`\`\`
+
+You can also use the instance method:
+
+\`\`\`ts
+const client = new ${model.const.Name}SDK({ apikey: '...' })
+const testClient = client.tester()
+\`\`\`
+
+### Retain entity state across calls
+
+Entity instances remember their last match and data:
+
+\`\`\`ts
+const entity = client.Planet()
+
+// First call sets internal match
+await entity.load({ id: 'example' })
+
+// Subsequent calls reuse the stored match
+const data = entity.data()
+console.log(data.id) // 'example'
+\`\`\`
+
+### Add custom middleware
+
+Pass features via the \`extend\` option:
+
+\`\`\`ts
+const logger = {
+  hooks: {
+    PreRequest: (ctx: any) => {
+      console.log('Requesting:', ctx.spec.method, ctx.spec.path)
+    },
+    PreResponse: (ctx: any) => {
+      console.log('Status:', ctx.out.request?.status)
+    },
+  },
+}
+
+const client = new ${model.const.Name}SDK({
+  apikey: '...',
+  extend: [logger],
+})
+\`\`\`
+
+### 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 ts && npm test
+\`\`\`
+
+`)
+
+})
+
+
+export {
+  ReadmeHowto
+}

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

@@ -5,7 +5,7 @@ import { cmp, Content } from '@voxgig/sdkgen'
 const ReadmeInstall = cmp(function ReadmeInstall(props: any) {
   const { target } = props
 
-  Content('```ts')
+  Content('```bash')
   Content(`
 npm install ${target.module.name}
 `)

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

@@ -0,0 +1,159 @@
+
+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
+
+#### Constructor
+
+\`\`\`ts
+new ${model.const.Name}SDK(options?: {
+  apikey?: string
+  base?: string
+  prefix?: string
+  suffix?: string
+  feature?: Record<string, { active: boolean }>
+  extend?: Feature[]
+})
+\`\`\`
+
+| 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\` | \`object\` | Feature activation flags (e.g. \`{ test: { active: true } }\`). |
+| \`extend\` | \`Feature[]\` | Additional feature instances to load. |
+
+#### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| \`options()\` | \`object\` | Deep copy of current SDK options. |
+| \`utility()\` | \`Utility\` | Deep copy of the SDK utility object. |
+| \`prepare(fetchargs?)\` | \`Promise<FetchDef>\` | Build an HTTP request definition without sending it. |
+| \`direct(fetchargs?)\` | \`Promise<DirectResult>\` | Build and send an HTTP request. |
+`)
+
+  each(entityList, (ent: any) => {
+    Content(`| \`${ent.Name}(data?)\` | \`${ent.Name}Entity\` | Create a ${ent.Name} entity instance. |
+`)
+  })
+
+  Content(`| \`tester(testopts?, sdkopts?)\` | \`${model.const.Name}SDK\` | Create a test-mode client instance. |
+
+#### Static methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| \`${model.const.Name}SDK.test(testopts?, sdkopts?)\` | \`${model.const.Name}SDK\` | Create a test-mode client. |
+
+### Entity interface
+
+All entities share the same interface.
+
+#### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| \`load\` | \`load(reqmatch?, ctrl?): Promise<Result>\` | Load a single entity by match criteria. |
+| \`list\` | \`list(reqmatch?, ctrl?): Promise<Result>\` | List entities matching the criteria. |
+| \`create\` | \`create(reqdata?, ctrl?): Promise<Result>\` | Create a new entity. |
+| \`update\` | \`update(reqdata?, ctrl?): Promise<Result>\` | Update an existing entity. |
+| \`remove\` | \`remove(reqmatch?, ctrl?): Promise<Result>\` | Remove an entity. |
+| \`data\` | \`data(data?): any\` | Get or set entity data. |
+| \`match\` | \`match(match?): any\` | Get or set entity match criteria. |
+| \`make\` | \`make(): Entity\` | Create a new instance with the same options. |
+| \`client\` | \`client(): ${model.const.Name}SDK\` | Return the parent SDK client. |
+| \`entopts\` | \`entopts(): object\` | Return a copy of the entity options. |
+
+#### Result shape
+
+All entity operations return a Result object:
+
+\`\`\`ts
+{
+  ok: boolean      // true if the HTTP status is 2xx
+  status: number   // HTTP status code
+  headers: object  // response headers
+  data: any        // parsed JSON response body
+}
+\`\`\`
+
+### DirectResult shape
+
+The \`direct()\` method returns:
+
+\`\`\`ts
+{
+  ok: boolean
+  status: number
+  headers: object
+  data: any
+}
+\`\`\`
+
+On error, \`ok\` is \`false\` and an \`err\` property contains the error.
+
+### FetchDef shape
+
+The \`prepare()\` method returns:
+
+\`\`\`ts
+{
+  url: string
+  method: string
+  headers: Record<string, string>
+  body?: any
+}
+\`\`\`
+
+### 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.join(', ')}.
+
+API path: \`${path}\`
+
+`)
+  })
+
+})
+
+
+export {
+  ReadmeModel
+}