fix: improve JSON parsing robustness and handle optional Order fields

- Add field existence checks to parsing macros (TIMESTAMP_FROM_JSON, etc.)
- Fix Order deserialization for optional fields (edit_history, attached_order_configuration)
- Support both creation_time and created_time field names
- Enhance error logging with contextual exception details
- Bump version to 0.2.1

Author: kzhdev

CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.1] - 2026-02-19
+
+### Changed
+- **BREAKING:** Renamed WebSocket channel `HEARTBEAT` to `HEARTBEATS` to match Coinbase API specification
+- Improved JSON parsing macros to check for field existence before parsing (`TIMESTAMP_FROM_JSON`, `NANOSECONDS_FROM_JSON`, `DOUBLE_FROM_JSON`, `INT_FROM_JSON`)
+- Enhanced error logging to combine context and error messages for better debugging
+
+### Fixed
+- Fixed Order JSON parsing to handle optional fields (`edit_history`, `creation_time`, `current_pending_replace`, `attached_order_configuration`)
+- Fixed Order parsing to support both `creation_time` and `created_time` field names
+- Fixed WebSocket error handling to properly process and dispatch error messages instead of throwing exceptions
+- Fixed user event processing to use correct JSON path for order updates (`event.at("orders")` instead of `j.at("orders")`)
+- Fixed sequence number checks to handle messages without `sequence_num` field
+- Improved null-safety in JSON parsing throughout order and websocket modules
+
 ## [0.2.0] - 2026-02-19
 
 ### Added

CMakeLists.txt

@@ -3,7 +3,7 @@ cmake_minimum_required(VERSION 3.20)
 set(CMAKE_CXX_STANDARD 20)
 
 project(coinbase-advanced-cpp
-    VERSION 0.2.0
+    VERSION 0.2.1
     LANGUAGES CXX)
 
 if (CMAKE_BUILD_TYPE MATCHES Debug)

include/coinbase/order.hpp

@@ -522,10 +522,13 @@ inline void from_json(const json &j, Order &o) {
         VARIABLE_FROM_JSON(j, o, retail_portfolio_id);
         VARIABLE_FROM_JSON(j, o, originating_order_id);
         VARIABLE_FROM_JSON(j, o, attached_order_id);
-        if (!j["current_pending_replace"].is_null()) {
-            o.current_pending_replace = j["current_pending_replace"];
+        STRUCT_FROM_JSON(j, o, current_pending_replace);
+        if (j.contains("creation_time")) {
+            o.created_time = milliseconds_from_json(j, "creation_time");
+        }
+        else {
+            TIMESTAMP_FROM_JSON(j, o, created_time);
         }
-        TIMESTAMP_FROM_JSON(j, o, created_time);
         TIMESTAMP_FROM_JSON(j, o, last_fill_time);
         DOUBLE_FROM_JSON(j, o, completion_percentage);
         DOUBLE_FROM_JSON(j, o, fee);
@@ -537,7 +540,9 @@ inline void from_json(const json &j, Order &o) {
         DOUBLE_FROM_JSON(j, o, workable_size);
         DOUBLE_FROM_JSON(j, o, workable_size_completion_pct);
         INT_FROM_JSON(j, o, number_of_fills);
-        o.edit_history = j["edit_history"];
+        if (j.contains("edit_history")) {
+            o.edit_history = j["edit_history"];
+        }
         ENUM_FROM_JSON(j, o, side);
         o.status = to_order_status(j.at("status").get<std::string_view>());
         ENUM_FROM_JSON(j, o, contract_expiry_type);
@@ -549,10 +554,8 @@ inline void from_json(const json &j, Order &o) {
         VARIABLE_FROM_JSON(j, o, size_inclusive_of_fees);
         VARIABLE_FROM_JSON(j, o, settled);
         VARIABLE_FROM_JSON(j, o, is_liquidation);
-        o.order_configuration = j["order_configuration"];
-        if (j.contains("attached_order_configuration")) {
-            o.attached_order_configuration = j["attached_order_configuration"];
-        }
+        STRUCT_FROM_JSON(j, o, order_configuration);
+        STRUCT_FROM_JSON(j, o, attached_order_configuration);
     }
     catch (const std::exception &e) {
         LOG_INFO(j.dump().c_str());

include/coinbase/utils.hpp

@@ -50,8 +50,7 @@ inline double double_from_json(const json &j, std::string_view field) {
     }
     catch(const std::exception& e)
     {
-        LOG_INFO("{} {}", field, j.dump());
-        LOG_ERROR(e.what());
+        LOG_ERROR("double_from_json exception: {}. field: {} {}", e.what(), field, j.dump());
     }
     return 0.;
 }
@@ -67,8 +66,7 @@ inline int32_t int_from_json(const json &j, std::string_view field) {
     }
     catch(const std::exception& e)
     {
-        LOG_INFO("{} {}", field, j.dump());
-        LOG_ERROR(e.what());
+        LOG_ERROR("int_from_json exception: {}. field: {} {}", e.what(), field, j.dump());
     }
     return 0;
 }
@@ -110,10 +108,10 @@ inline std::string to_string(double value, Side side, double min_increment) {
     return oss.str();
 }
 
-#define TIMESTAMP_FROM_JSON(j, o, field) o.field = milliseconds_from_json(j, #field)
-#define NANOSECONDS_FROM_JSON(j, o, field) o.field = nanoseconds_from_json(j, #field)
-#define DOUBLE_FROM_JSON(j, o, field) o.field = double_from_json(j, #field)
-#define INT_FROM_JSON(j, o, field) o.field = int_from_json(j, #field)
+#define TIMESTAMP_FROM_JSON(j, o, field) if (j.contains(#field)) o.field = milliseconds_from_json(j, #field)
+#define NANOSECONDS_FROM_JSON(j, o, field) if (j.contains(#field)) o.field = nanoseconds_from_json(j, #field)
+#define DOUBLE_FROM_JSON(j, o, field) if (j.contains(#field)) o.field = double_from_json(j, #field)
+#define INT_FROM_JSON(j, o, field) if (j.contains(#field)) o.field = int_from_json(j, #field)
 #define VARIABLE_FROM_JSON(j, o, field) if (j.contains(#field) && !j[#field].is_null()) try { j.at(#field).get_to(o.field); } catch(const std::exception &e) { LOG_INFO(#field " {}", j.dump()); LOG_ERROR(e.what()); }
 #define BOOL_FROM_JSON(j, o, field) if (j.contains(#field) && !j[#field].is_null() && j[#field].is_string()) { if (j[#field] == "true") o.field = true; else if (j[#field] == "false") o.field = false; } else try { j.at(#field).get_to(o.field); } catch(const std::exception &e) { LOG_INFO(#field " {}", j.dump()); LOG_ERROR(e.what()); }
 #define BOOL_FROM_JSON_VALUE(j, o, field, j_name) if (j.contains(j_name) && !j[j_name].is_null() && j[j_name].is_string()) { if (j[j_name] == "true") o.field = true; else if (j[j_name] == "false") o.field = false; } else try { j.at(j_name).get_to(o.field); } catch(const std::exception &e) { LOG_INFO(j_name " {}", j.dump()); LOG_ERROR(e.what()); }

include/coinbase/websocket.hpp

@@ -29,7 +29,7 @@ using Websocket = slick::net::Websocket;
 using json = nlohmann::json;
 
 enum WebSocketChannel : uint8_t {
-    HEARTBEAT,
+    HEARTBEATS,
     LEVEL2,
     MARKET_TRADES,
     TICKER,

src/websocket.cpp

@@ -8,8 +8,8 @@ namespace coinbase {
 
 std::string to_string(WebSocketChannel channel) {
     switch(channel) {
-    case WebSocketChannel::HEARTBEAT:
-        return "heartbeat";
+    case WebSocketChannel::HEARTBEATS:
+        return "heartbeats";
     case WebSocketChannel::LEVEL2:
         return "level2";
     case WebSocketChannel::MARKET_TRADES:
@@ -279,7 +279,7 @@ void WebSocketClient::unsubscribe(const std::vector<std::string> &product_ids, c
         if (websocket->status() <= Websocket::Status::CONNECTED) {
             websocket->send(unsubscribe_str.c_str(), unsubscribe_str.size());
         }
-        if (channel == WebSocketChannel::HEARTBEAT) {
+        if (channel == WebSocketChannel::HEARTBEATS) {
             if (user_data_websocket_ && user_data_websocket_->status() <= Websocket::Status::CONNECTED) {
                 user_data_websocket_->send(unsubscribe_str.c_str(), unsubscribe_str.size());
             }
@@ -445,7 +445,13 @@ void WebSocketClient::onUserDataError(std::string &&err) {
 void DataHandler::processMarketData(WebSocketClient *ws_client, const char* data, std::size_t size) {
     try {
         auto j = json::parse(data, data + size);
-        checkMarketDataSequenceNumber(ws_client, j["sequence_num"]);
+        if (j.contains("sequence_num")) {
+            checkMarketDataSequenceNumber(ws_client, j["sequence_num"]);
+        }
+        if (j["type"] == "error") {
+            callbacks_->onMarketDataError(ws_client, j["message"]);
+            return;
+        }
         auto channel = j["channel"];
         if (channel == "l2_data") {
             processLevel2Update(ws_client, j);
@@ -479,7 +485,13 @@ void DataHandler::processMarketData(WebSocketClient *ws_client, const char* data
 void DataHandler::processUserData(WebSocketClient *ws_client, const char* data, std::size_t size) {
     try {
         auto j = json::parse(data, data + size);
-        checkUserDataSequenceNumber(ws_client, j["sequence_num"]);
+        if (j.contains("sequence_num")) {
+            checkUserDataSequenceNumber(ws_client, j["sequence_num"]);
+        }
+        if (j["type"] == "error") {
+            callbacks_->onUserDataError(ws_client, j["message"]);
+            return;
+        }
         auto channel = j["channel"];
         if (channel == "user") {
             processUserEvent(ws_client, j);
@@ -585,7 +597,7 @@ void DataHandler::processUserEvent(WebSocketClient *ws_client, const json &j) {
             callbacks_->onUserDataSnapshot(ws_client, j.at("sequence_num").get<uint64_t>(), orders, positions.at("perpetual_futures_positions"), positions.at("expiring_futures_positions"));
         }
         else if (event["type"] == "update") {
-            callbacks_->onOrderUpdates(ws_client, j.at("sequence_num").get<uint64_t>(), j.at("orders"));
+            callbacks_->onOrderUpdates(ws_client, j.at("sequence_num").get<uint64_t>(), event.at("orders"));
         }
         else {
             LOG_WARN("unknown user event type: {}", j["type"].get<std::string_view>());