refactor: addressing pr comments

Author: aorumbayev

.github/actions/setup-api-tools/action.yml

@@ -1,6 +1,12 @@
 name: 'Setup API Tools'
 description: 'Setup Rust, Bun, and Python dependencies for API tools'
 
+inputs:
+  setup_algokit:
+    description: 'Whether to install and start algokit localnet'
+    required: false
+    default: 'false'
+
 runs:
   using: 'composite'
   steps:
@@ -24,4 +30,14 @@ runs:
     - name: Install uv dependencies
       working-directory: api/oas_generator
       shell: bash
-      run: uv sync --extra dev
+      run: uv sync --extra dev
+
+    - name: Optionally install algokit
+      if: ${{ inputs.setup_algokit == 'true' }}
+      shell: bash
+      run: uv tool install algokit
+
+    - name: Optionally start localnet
+      if: ${{ inputs.setup_algokit == 'true' }}
+      shell: bash
+      run: algokit localnet start

.github/workflows/api_ci.yml

@@ -81,6 +81,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup-api-tools
+        with:
+          setup_algokit: 'true'
       - uses: actions/setup-node@v4
         with:
           node-version: "20"
@@ -108,3 +110,7 @@ jobs:
       - name: Build (tsc) ${{ matrix.pkg }}
         working-directory: packages/typescript/${{ matrix.pkg }}
         run: bun run build
+
+      - name: Test (${{ matrix.pkg }})
+        working-directory: packages/typescript/${{ matrix.pkg }}
+        run: bun test

api/oas_generator/ts_oas_generator/cli.py

@@ -30,24 +30,17 @@ def parse_command_line_args(args: list[str] | None = None) -> argparse.Namespace
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  %(prog)s --runtime-only --output ./packages/algod_client --package-name algod_client
   %(prog)s ../specs/algod.oas3.json --output ./packages/algod_client --package-name algod_client
   %(prog)s ../specs/indexer.oas3.json -o ./packages/indexer_client -p indexer_client
         """,
     )
 
     parser.add_argument(
         "spec_file",
-        nargs="?",
         type=Path,
         help="Path to OpenAPI specification file (JSON or YAML)",
         metavar="SPEC_FILE",
     )
-    parser.add_argument(
-        "--runtime-only",
-        action="store_true",
-        help="Generate only the base runtime files (no models/APIs); does not require a spec file",
-    )
     parser.add_argument(
         "--output",
         "-o",
@@ -86,10 +79,7 @@ def parse_command_line_args(args: list[str] | None = None) -> argparse.Namespace
     parsed_args = parser.parse_args(args)
 
     # Validate inputs
-    if not parsed_args.runtime_only and parsed_args.spec_file is None:
-        parser.error("SPEC_FILE is required unless --runtime-only is provided")
-
-    if parsed_args.spec_file is not None and not parsed_args.spec_file.exists():
+    if not parsed_args.spec_file.exists():
         parser.error(f"Specification file not found: {parsed_args.spec_file}")
 
     return parsed_args
@@ -141,19 +131,12 @@ def main(args: list[str] | None = None) -> int:
         with backup_and_prepare_output_dir(parsed_args.output_dir):
             generator = TsCodeGenerator(template_dir=parsed_args.template_dir)
 
-            if parsed_args.runtime_only:
-                generated_files = generator.generate_runtime(
-                    parsed_args.output_dir,
-                    parsed_args.package_name,
-                    custom_description=parsed_args.custom_description,
-                )
-            else:
-                generated_files = generator.generate_full(
-                    parsed_args.spec_file,
-                    parsed_args.output_dir,
-                    parsed_args.package_name,
-                    custom_description=parsed_args.custom_description,
-                )
+            generated_files = generator.generate_full(
+                parsed_args.spec_file,
+                parsed_args.output_dir,
+                parsed_args.package_name,
+                custom_description=parsed_args.custom_description,
+            )
 
             # Write files to disk (overwrite safely)
             write_files_to_disk(generated_files)

api/oas_generator/ts_oas_generator/generator/filters.py

@@ -105,7 +105,8 @@ def _inline_object(schema: dict[str, Any], schemas: dict[str, Any] | None) -> st
     parts: list[str] = []
 
     for prop_name, prop_schema in properties.items():
-        ts_name = ts_property_name(prop_name)
+        # Generate camelCase TS property names for better DX
+        ts_name = ts_camel_case(prop_name)
         ts_t = ts_type(prop_schema, schemas)
         opt = "" if prop_name in required else "?"
         parts.append(f"{ts_name}{opt}: {ts_t};")
@@ -121,12 +122,12 @@ def _inline_object(schema: dict[str, Any], schemas: dict[str, Any] | None) -> st
     return "{" + (" ".join(parts)) + "}"
 
 
-def _map_primitive(schema_type: str, _schema_format: str | None, schema: dict[str, Any]) -> str:
-    if schema.get("x-algokit-bigint") is True and schema_type == "integer":
-        return "bigint"
-
+def _map_primitive(schema_type: str, _schema_format: str | None, _schema: dict[str, Any]) -> str:
     if schema_type == "integer":
-        return "number"
+        # Default to bigint for blockchain-sized integers; keep int32 as number
+        if _schema_format == "int32":
+            return "number"
+        return "bigint"
 
     if schema_type in ("number",):
         return "number"

api/oas_generator/ts_oas_generator/generator/template_engine.py

@@ -71,14 +71,23 @@ def generate_runtime(
         """Generate runtime files under the provided output directory."""
         output_dir = Path(output_dir)
         src_core = output_dir / "src" / "core"
+        base_name = ts_pascal_case(package_name)
+        base_core = base_name[:-6] if base_name.lower().endswith("client") else base_name
+        client_class_name = f"{base_core}Client"
+        service_class_name = f"{base_core}Api"
+
         context = {
             "package_name": package_name,
             "custom_description": custom_description,
+            "client_class_name": client_class_name,
+            "service_class_name": service_class_name,
         }
 
         files: dict[Path, str] = {}
         # Core runtime files
-        files[src_core / "OpenAPI.ts"] = self.template_engine.render_template("base/src/core/OpenAPI.ts.j2", context)
+        files[src_core / "ClientConfig.ts"] = self.template_engine.render_template(
+            "base/src/core/ClientConfig.ts.j2", context
+        )
         files[src_core / "BaseHttpRequest.ts"] = self.template_engine.render_template(
             "base/src/core/BaseHttpRequest.ts.j2", context
         )
@@ -92,6 +101,7 @@ def generate_runtime(
         )
         files[src_core / "json.ts"] = self.template_engine.render_template("base/src/core/json.ts.j2", context)
         files[src_core / "msgpack.ts"] = self.template_engine.render_template("base/src/core/msgpack.ts.j2", context)
+        files[src_core / "casing.ts"] = self.template_engine.render_template("base/src/core/casing.ts.j2", context)
 
         # Index barrel (runtime-only)
         files[output_dir / "src" / "index.ts"] = self.template_engine.render_template("base/src/index.ts.j2", context)
@@ -222,8 +232,8 @@ def collect_model_types(type_str: str) -> set[str]:
                         param = node
                     schema = param.get("schema", {}) or {}
                     t = ts_type(schema, schemas)
-                    # BigInt params accept number | bigint
-                    if schema.get("x-algokit-bigint") is True and t == "bigint":
+                    # When a parameter resolves to bigint, accept number | bigint for ergonomics
+                    if t == "bigint":
                         t_sig = "number | bigint"
                         stringify_bigint = True
                     else:
@@ -256,23 +266,44 @@ def collect_model_types(type_str: str) -> set[str]:
                         }
                     )
 
-                # Request body (pick json if present, else msgpack/text)
+                # Request body handling
                 request_body_ctx: dict[str, Any] | None = None
+                request_body_supports_msgpack = False
+                request_body_supports_json = False
                 rb = op.get("requestBody")
                 if isinstance(rb, dict):
                     content = rb.get("content", {})
+
+                    # Check what content types are supported
+                    if "application/msgpack" in content:
+                        request_body_supports_msgpack = True
+                    if "application/json" in content:
+                        request_body_supports_json = True
+
+                    # Determine the type to use for TypeScript typing
+                    # Prefer JSON schema for typing even when msgpack is used at runtime
                     if "application/json" in content:
                         sch = (content["application/json"] or {}).get("schema", {})
                         request_body_ctx = {
-                            "mediaType": "application/json",
+                            "mediaType": (
+                                "application/msgpack"
+                                if request_body_supports_msgpack and not request_body_supports_json
+                                else "application/json"
+                            ),
                             "tsType": ts_type(sch, schemas),
                             "required": rb.get("required", False),
+                            "supportsMsgpack": request_body_supports_msgpack,
+                            "supportsJson": request_body_supports_json,
                         }
                     elif "application/msgpack" in content:
+                        # msgpack-only endpoint - infer type from msgpack schema if available
+                        sch = (content["application/msgpack"] or {}).get("schema", {})
                         request_body_ctx = {
                             "mediaType": "application/msgpack",
-                            "tsType": "Uint8Array",
+                            "tsType": ts_type(sch, schemas) if sch else "any",
                             "required": rb.get("required", False),
+                            "supportsMsgpack": True,
+                            "supportsJson": False,
                         }
                     elif "application/x-binary" in content or "application/octet-stream" in content:
                         # Raw binary transaction submission etc.
@@ -281,13 +312,17 @@ def collect_model_types(type_str: str) -> set[str]:
                             "mediaType": mt,
                             "tsType": "Uint8Array",
                             "required": rb.get("required", False),
+                            "supportsMsgpack": False,
+                            "supportsJson": False,
                         }
                     elif "text/plain" in content:
                         sch = (content["text/plain"] or {}).get("schema", {})
                         request_body_ctx = {
                             "mediaType": "text/plain",
                             "tsType": ts_type(sch, schemas),
                             "required": rb.get("required", False),
+                            "supportsMsgpack": False,
+                            "supportsJson": False,
                         }
 
                 # Responses
@@ -387,6 +422,8 @@ def collect_model_types(type_str: str) -> set[str]:
                     "acceptsMsgpack": returns_msgpack,
                     "returnsMsgpack": returns_msgpack,
                     "supportsJson": supports_json,
+                    "requestBodySupportsMsgpack": request_body_supports_msgpack,
+                    "requestBodySupportsJson": request_body_supports_json,
                     "hasFormatParam": has_format_param,
                     "formatVarName": format_var_name,
                     "signature": ", ".join(sig_parts),
@@ -465,21 +502,32 @@ def generate_full(
             for t in op.get("importTypes", []):
                 import_types.add(t)
 
+        # Determine class names from package name (e.g., algod_client -> AlgodClient, AlgodApi)
+        base_name = ts_pascal_case(package_name)
+        base_core = base_name[:-6] if base_name.lower().endswith("client") else base_name
+        client_class_name = f"{base_core}Client"
+        service_class_name = f"{base_core}Api"
+
         svc_content = self.template_engine.render_template(
             "apis/service.ts.j2",
-            {"tag_name": "api", "operations": all_ops, "import_types": sorted(import_types)},
+            {
+                "tag_name": "api",
+                "operations": all_ops,
+                "import_types": sorted(import_types),
+                "service_class_name": service_class_name,
+            },
         )
         files[apis_dir / "api.service.ts"] = svc_content
 
         files[apis_dir / "index.ts"] = self.template_engine.render_template(
             "apis/index.ts.j2",
-            {},
+            {"service_class_name": service_class_name},
         )
 
         # Client (single service)
         files[Path(output_dir) / "src" / "client.ts"] = self.template_engine.render_template(
             "client.ts.j2",
-            {},
+            {"service_class_name": service_class_name, "client_class_name": client_class_name},
         )
 
         # Replace index with full barrel
@@ -488,12 +536,6 @@ def generate_full(
             {},
         )
 
-        # Smoke tests (generated)
-        files[Path(output_dir) / "tests" / "generated" / "smoke.generated.spec.ts"] = (
-            self.template_engine.render_template(
-                "full/tests/smoke.spec.ts.j2",
-                {},
-            )
-        )
+        # Note: Generated smoke tests removed; prefer manual integration tests maintained by developers
 
         return files

api/oas_generator/ts_oas_generator/templates/apis/index.ts.j2

@@ -1,2 +1,2 @@
 // Barrel file for services
-export { ApiService } from './api.service';
+export { {{ service_class_name }} } from './api.service';

api/oas_generator/ts_oas_generator/templates/apis/service.ts.j2

@@ -3,7 +3,7 @@ import type { BaseHttpRequest, ApiRequestOptions } from '../core/BaseHttpRequest
 import type { {{ import_types | sort | join(', ') }} } from '../models/index';
 {% endif %}
 
-export class ApiService {
+export class {{ service_class_name }} {
   constructor(public readonly httpRequest: BaseHttpRequest) {}
 
 {% for op in operations %}
@@ -25,16 +25,15 @@ export class ApiService {
   ): Promise<{{ op.responseTsType }}> {
     const headers: Record<string, string> = {};
 {%   if op.acceptsMsgpack %}
-    // Content negotiation:
-    // - If explicit format=json, prefer JSON
-    // - Else if server supports JSON, prefer JSON by default
-    // - Else fall back to msgpack
+    // Content negotiation (aligned with Rust behavior):
+    // - Default to msgpack when available (better performance, smaller payload)
+    // - Only use JSON if explicitly requested via format=json
 {%     if op.hasFormatParam and op.formatVarName %}
-    const hasExplicitJson = params?.{{ op.formatVarName }} === 'json';
-    const prefersJson = hasExplicitJson || {{ 'true' if op.supportsJson else 'false' }};
-    headers['Accept'] = prefersJson ? 'application/json' : 'application/msgpack';
+    const useJson = params?.{{ op.formatVarName }} === 'json';
+    headers['Accept'] = useJson ? 'application/json' : 'application/msgpack';
 {%     else %}
-    headers['Accept'] = {{ "'application/json'" if op.supportsJson else "'application/msgpack'" }};
+    // Prefer msgpack when available, fallback to JSON
+    headers['Accept'] = 'application/msgpack';
 {%     endif %}
 {%   else %}
     headers['Accept'] = 'application/json';
@@ -65,12 +64,27 @@ export class ApiService {
       },
       headers,
       body: {% if op.requestBody %}params?.body{% else %}undefined{% endif %},
-      mediaType: {% if op.requestBody %}'{{ op.requestBody['mediaType'] }}'{% else %}undefined{% endif %},
+{%   if op.requestBody %}
+{%     if op.requestBodySupportsMsgpack and op.requestBodySupportsJson and op.hasFormatParam and op.formatVarName %}
+      // Dynamic mediaType based on format parameter (prefer msgpack by default)
+      mediaType: params?.{{ op.formatVarName }} === 'json' ? 'application/json' : 'application/msgpack',
+{%     elif op.requestBodySupportsMsgpack and not op.requestBodySupportsJson %}
+      // Only msgpack supported for request body
+      mediaType: 'application/msgpack',
+{%     elif op.requestBodySupportsMsgpack and op.requestBodySupportsJson %}
+      // Both supported, prefer msgpack for better performance
+      mediaType: 'application/msgpack',
+{%     else %}
+      mediaType: '{{ op.requestBody['mediaType'] }}',
+{%     endif %}
+{%   else %}
+      mediaType: undefined,
+{%   endif %}
 {%   if op.returnsMsgpack %}
 {%     if op.hasFormatParam and op.formatVarName %}
-      expectBinary: params?.{{ op.formatVarName }} === 'json' ? false : {{ 'false' if op.supportsJson else 'true' }},
+      expectBinary: params?.{{ op.formatVarName }} === 'json' ? false : true,
 {%     else %}
-      expectBinary: {{ 'false' if op.supportsJson else 'true' }},
+      expectBinary: true,
 {%     endif %}
 {%   else %}
       expectBinary: false,