Why
The Node.js client is handwritten, while the v1 API now has an OpenAPI spec. Maintaining endpoints and types in both places can let the client drift from the server.
Approach
- Fix inaccurate server contracts so the spec describes real responses.
- Keep a copy of the spec in this repo and generate typed Axios operations from it. Commit the generated files and check regeneration in CI; do not edit them by hand.
- Expose those operations at
@hackmd/api/raw alongside the existing API class.
- Add a small handwritten layer for conveniences such as response unwrapping, retries, and ETag handling. Migrate incrementally without breaking existing users.
Why
The Node.js client is handwritten, while the v1 API now has an OpenAPI spec. Maintaining endpoints and types in both places can let the client drift from the server.
Approach
@hackmd/api/rawalongside the existingAPIclass.