Port Python SDK route generation from nextlove to Metalsmith

[razor-x]

Summary

This PR replaces the direct dependency on @seamapi/nextlove-sdk-generator with a Metalsmith-based code generation pipeline for Python SDK route files. The generation logic has been ported and restructured to align with the existing javascript-http codegen plugin architecture.

Key Changes

• Replaced generation script: Removed generate-routes.js which called @seamapi/nextlove-sdk-generator directly. Replaced with codegen/smith.ts that uses Metalsmith as the build orchestrator.

• Ported core generation logic: Migrated route generation from @seamapi/nextlove-sdk-generator to codegen/lib/routes.ts, which:

  • Iterates through blueprint routes and endpoints
  • Builds class models with methods and parameters
  • Generates route namespace hierarchy
  • Filters endpoints based on OpenAPI extensions and endpoint rules

• Extracted OpenAPI utilities: Created modular OpenAPI processing functions:

  • get-filtered-routes.ts: Filters documented routes
  • get-parameter-and-response-schema.ts: Extracts request/response schemas
  • deep-flatten-one-of-and-all-of-schema.ts: Flattens complex schema compositions
  • flatten-obj-schema.ts: Normalizes object schemas
  • map-parent-to-children-resource.ts: Maps resource hierarchies
  • types.ts: Minimal OpenAPI type definitions

• Introduced data models: Created class-model.ts to represent route classes, methods, and parameters independently of serialization.

• Built layout context builders: Created context builders for Handlebars templates:

  • layouts/route.ts: Builds context for individual route class files
  • layouts/models.ts: Builds context for the models file
  • layouts/routes-index.ts: Builds context for the routes index file

• Added Handlebars templates: Created template files for code generation:

  • route.hbs: Route class template
  • models.hbs: Models file template
  • routes-index.hbs: Routes index template
  • partials/route-method.hbs: Route method template
  • partials/abstract-route-class.hbs: Abstract class template
  • partials/model-dataclass.hbs: Dataclass template
  • partials/abstract-routes.hbs: Abstract routes template

• Added utility modules:

  • map-python-type.ts: Maps OpenAPI types to Python types
  • custom-resource-name-conversions.ts: Handles special resource name mappings
  • endpoint-rules.ts: Defines endpoint filtering rules
  • handlebars-helpers.ts: Custom Handlebars helpers

• Updated build configuration: Modified package.json to use tsx codegen/smith.ts instead of node generate-routes.js, and added dependencies on @metalsmith/layouts, @seamapi/blueprint, and @seamapi/smith.

• Added configuration files: Created .prettierignore to exclude Handlebars templates from formatting.

Notable Implementation Details

• The generation logic preserves exact output compatibility with the previous nextlove generator through careful porting, including quirks like the operator precedence bug in parameter sorting.
• Multiple TODO comments mark locations where the code could migrate to use @seamapi/blueprint data once generated output changes are allowed.
• The raw OpenAPI spec is consulted alongside the blueprint where they normalize data differently (e.g., integer vs. number types, union flattening).
• The Metalsmith pipeline follows the same plugin architecture as the existing javascript-http codegen, making it maintainable and extensible.

https://claude.ai/code/session_019iX1vWXfXKzUyRJTVm8D7s

[razor-x]

Suggested change

# Negations must follow the pattern they negate, so this cannot move to the top