Skip to content

CLAUDE.md

Latest commit

 

History

History
118 lines (87 loc) · 4.49 KB

CLAUDE.md

File metadata and controls

118 lines (87 loc) · 4.49 KB
Raw

Agent Guidelines

SDK layers — update ALL of them when adding/changing an API or type

This repo ships the SDK in six language layers. The Rust core is the source of truth; every other layer is a hand-written binding that mirrors it. When you add a new API endpoint, type, enum, or field, you must propagate the change to every layer below — it is easy to forget the C++ and Java layers, so treat this list as a checklist:

  1. Rust core (rust/src/) — the source of truth.
  2. C (c/src/) — FFI structs (*Owned + ToFFI), enums, extern "C" fns. Header c/csrc/include/longbridge.h is auto-generated by cbindgen.
  3. C++ (cpp/) — wraps the C layer. Update cpp/include/*.hpp (public types/methods), cpp/src/convert.hpp (C↔C++ conversions), and cpp/src/*_context.cpp.
  4. Java (java/) — JNI. Update the Rust JNI layer (java/src/*.rs) and the Java classes (java/javasrc/src/main/java/com/longbridge/).
  5. Node.js (nodejs/src/) — napi. index.d.ts / index.js are auto-generated by npm run build:debug.
  6. Python (python/src/) — PyO3. Keep the hand-maintained stub python/pysrc/longbridge/openapi.pyi in sync.

After modifying Rust code

Run the following commands from the workspace root:

cargo clippy --all --all-features
cargo +nightly fmt --all

Note: cargo +nightly fmt may reflow doc comments (e.g. /// @param … lines). Do not revert those changes — they are intentional formatting output and should be committed as-is.

After modifying the Node.js SDK (nodejs/)

Build the native .node binary from the nodejs/ directory:

npm run build:debug

nodejs/index.d.ts and nodejs/index.js are auto-generated by npm run build:debug — never edit them by hand.

After updating the proto submodule (rust/crates/proto/openapi-protobufs/)

Run the following command from the workspace root to regenerate the Rust proto source files (e.g. rust/crates/proto/src/longbridge.control.v1.rs, rust/crates/proto/src/longbridge.quote.v1.rs, rust/crates/proto/src/longbridge.trade.v1.rs):

cargo make protoc

The generated *.rs files under rust/crates/proto/src/ are auto-generated — never edit them by hand.

After modifying the Python SDK API (python/)

python/pysrc/longbridge/openapi.pyi is a manually maintained type-stub file that provides type hints and docstrings for the native Rust/PyO3 extension module. IDEs and type checkers (mypy/pyright) rely on it for autocompletion and static analysis.

When you add, remove, or change any #[pyclass]/#[pymethods] definitions in python/src/, you must update openapi.pyi accordingly — keeping signatures, type annotations, and docstrings in sync with the Rust implementation.

To build and install the Python SDK locally (from the python/ directory):

maturin develop

python/pyproject.toml uses dynamic = ["version"] — maturin reads the version from python/Cargo.toml automatically. Do not add a hardcoded version field to pyproject.toml.

After modifying the C SDK (c/)

c/csrc/include/longbridge.h is auto-generated by cbindgen during the build — never edit it by hand. Rebuild the C crate to update it:

cargo build -p longbridge-c

After modifying the C++ SDK (cpp/)

The C++ SDK wraps the C layer, so update the C SDK first. Public types and methods live in cpp/include/*.hpp, the C↔C++ conversion helpers in cpp/src/convert.hpp, and method implementations in cpp/src/*_context.cpp. It is built via CMake (see the cmake-* tasks in the root Makefile.toml, which build out of cmake.build/).

After modifying the Java SDK (java/)

The Java SDK is a JNI binding with two halves that must stay in sync:

  • Rust JNI layer in java/src/*.rs (e.g. java/src/trade_context.rs) — build with cargo build -p longbridge-java.
  • Java classes in java/javasrc/src/main/java/com/longbridge/ — one file per type/enum. Data crosses the boundary as JSON (gson), so field names must match what the Rust JNI layer serializes.

After any change

Update CHANGELOG.md in the workspace root to document notable changes. The format follows Keep a Changelog. Add an entry under the [Unreleased] section in the appropriate subsection (Added, Changed, Fixed, Breaking changes, etc.). If the [Unreleased] section does not yet exist, create it at the top of the changelog (above the latest versioned block).