feat: implement session management methods

Implement WebSocket-specific session management methods:
- set_heartbeat(interval): Enable heartbeats with specified interval (10-3600 seconds)
- disable_heartbeat(): Disable heartbeat messages
- hello(client_name, client_version): Send client identification to server

Changes:
- Add PUBLIC_SET_HEARTBEAT, PUBLIC_DISABLE_HEARTBEAT constants
- Add request builder methods for session management
- Implement client methods with proper error handling
- Add 8 unit tests for request builders

Closes #14

Author: joaquinbejar

src/client.rs

@@ -307,6 +307,108 @@ impl DeribitWebSocketClient {
         self.send_request(request).await
     }
 
+    /// Enable heartbeat with specified interval
+    ///
+    /// The server will send a heartbeat message every `interval` seconds.
+    /// If heartbeat is enabled, the server will also send `test_request` notifications
+    /// which the client should respond to with `public/test` to keep the connection alive.
+    ///
+    /// # Arguments
+    ///
+    /// * `interval` - Heartbeat interval in seconds (10-3600)
+    ///
+    /// # Returns
+    ///
+    /// Returns `"ok"` on success
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the request fails or the interval is invalid
+    pub async fn set_heartbeat(&self, interval: u64) -> Result<String, WebSocketError> {
+        let request = {
+            let mut builder = self.request_builder.lock().await;
+            builder.build_set_heartbeat_request(interval)
+        };
+
+        let response = self.send_request(request).await?;
+
+        match response.result {
+            JsonRpcResult::Success { result } => {
+                result.as_str().map(String::from).ok_or_else(|| {
+                    WebSocketError::InvalidMessage(
+                        "Expected string result from set_heartbeat".to_string(),
+                    )
+                })
+            }
+            JsonRpcResult::Error { error } => {
+                Err(WebSocketError::ApiError(error.code, error.message))
+            }
+        }
+    }
+
+    /// Disable heartbeat
+    ///
+    /// Stops the server from sending heartbeat messages and `test_request` notifications.
+    ///
+    /// # Returns
+    ///
+    /// Returns `"ok"` on success
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the request fails
+    pub async fn disable_heartbeat(&self) -> Result<String, WebSocketError> {
+        let request = {
+            let mut builder = self.request_builder.lock().await;
+            builder.build_disable_heartbeat_request()
+        };
+
+        let response = self.send_request(request).await?;
+
+        match response.result {
+            JsonRpcResult::Success { result } => {
+                result.as_str().map(String::from).ok_or_else(|| {
+                    WebSocketError::InvalidMessage(
+                        "Expected string result from disable_heartbeat".to_string(),
+                    )
+                })
+            }
+            JsonRpcResult::Error { error } => {
+                Err(WebSocketError::ApiError(error.code, error.message))
+            }
+        }
+    }
+
+    /// Send client identification to the server
+    ///
+    /// This method identifies the client to the server with its name and version.
+    /// It's recommended to call this after connecting to provide debugging information.
+    ///
+    /// # Arguments
+    ///
+    /// * `client_name` - Name of the client application
+    /// * `client_version` - Version of the client application
+    ///
+    /// # Returns
+    ///
+    /// Returns a JSON response containing the API version information
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the request fails
+    pub async fn hello(
+        &self,
+        client_name: &str,
+        client_version: &str,
+    ) -> Result<JsonRpcResponse, WebSocketError> {
+        let request = {
+            let mut builder = self.request_builder.lock().await;
+            builder.build_hello_request(client_name, client_version)
+        };
+
+        self.send_request(request).await
+    }
+
     /// Place mass quotes
     pub async fn mass_quote(
         &self,

src/constants.rs

@@ -33,6 +33,12 @@ pub mod methods {
     /// Private unsubscribe from all channels
     pub const PRIVATE_UNSUBSCRIBE_ALL: &str = "private/unsubscribe_all";
 
+    // Session management
+    /// Set heartbeat interval
+    pub const PUBLIC_SET_HEARTBEAT: &str = "public/set_heartbeat";
+    /// Disable heartbeat
+    pub const PUBLIC_DISABLE_HEARTBEAT: &str = "public/disable_heartbeat";
+
     // Market data
     /// Get ticker information
     pub const PUBLIC_GET_TICKER: &str = "public/ticker";

src/message/request.rs

@@ -97,7 +97,69 @@ impl RequestBuilder {
 
     /// Build test request
     pub fn build_test_request(&mut self) -> JsonRpcRequest {
-        self.build_request("public/test", None)
+        self.build_request(crate::constants::methods::PUBLIC_TEST, None)
+    }
+
+    /// Build set_heartbeat request
+    ///
+    /// Enables heartbeat with specified interval. The server will send a heartbeat
+    /// message every `interval` seconds, and expects a response within the same interval.
+    ///
+    /// # Arguments
+    ///
+    /// * `interval` - Heartbeat interval in seconds (10-3600)
+    ///
+    /// # Returns
+    ///
+    /// A JSON-RPC request for setting the heartbeat interval
+    pub fn build_set_heartbeat_request(&mut self, interval: u64) -> JsonRpcRequest {
+        let params = serde_json::json!({
+            "interval": interval
+        });
+        self.build_request(
+            crate::constants::methods::PUBLIC_SET_HEARTBEAT,
+            Some(params),
+        )
+    }
+
+    /// Build disable_heartbeat request
+    ///
+    /// Disables heartbeat messages. The server will stop sending heartbeat messages
+    /// and test_request notifications.
+    ///
+    /// # Returns
+    ///
+    /// A JSON-RPC request for disabling heartbeats
+    pub fn build_disable_heartbeat_request(&mut self) -> JsonRpcRequest {
+        self.build_request(
+            crate::constants::methods::PUBLIC_DISABLE_HEARTBEAT,
+            Some(serde_json::json!({})),
+        )
+    }
+
+    /// Build hello request
+    ///
+    /// Sends client identification to the server. This is used for client tracking
+    /// and debugging purposes.
+    ///
+    /// # Arguments
+    ///
+    /// * `client_name` - Name of the client application
+    /// * `client_version` - Version of the client application
+    ///
+    /// # Returns
+    ///
+    /// A JSON-RPC request for client identification
+    pub fn build_hello_request(
+        &mut self,
+        client_name: &str,
+        client_version: &str,
+    ) -> JsonRpcRequest {
+        let params = serde_json::json!({
+            "client_name": client_name,
+            "client_version": client_version
+        });
+        self.build_request(crate::constants::methods::PUBLIC_HELLO, Some(params))
     }
 
     /// Build get time request

tests/unit/message.rs

@@ -147,3 +147,125 @@ fn test_request_with_empty_channels() {
         assert_eq!(channels_array.len(), 0);
     }
 }
+
+// =============================================================================
+// Session management request tests (Issue #14)
+// =============================================================================
+
+#[test]
+fn test_request_builder_set_heartbeat() {
+    let mut builder = RequestBuilder::new();
+    let request = builder.build_set_heartbeat_request(30);
+
+    assert_eq!(request.method, "public/set_heartbeat");
+    assert_eq!(request.jsonrpc, "2.0");
+    assert!(request.id.is_number());
+
+    if let Some(params) = request.params {
+        let params_obj = params.as_object().unwrap();
+        assert_eq!(params_obj["interval"], 30);
+    } else {
+        panic!("set_heartbeat request should have params");
+    }
+}
+
+#[test]
+fn test_request_builder_set_heartbeat_custom_interval() {
+    let mut builder = RequestBuilder::new();
+    let request = builder.build_set_heartbeat_request(60);
+
+    if let Some(params) = request.params {
+        let params_obj = params.as_object().unwrap();
+        assert_eq!(params_obj["interval"], 60);
+    } else {
+        panic!("set_heartbeat request should have params");
+    }
+}
+
+#[test]
+fn test_request_builder_disable_heartbeat() {
+    let mut builder = RequestBuilder::new();
+    let request = builder.build_disable_heartbeat_request();
+
+    assert_eq!(request.method, "public/disable_heartbeat");
+    assert_eq!(request.jsonrpc, "2.0");
+    assert!(request.id.is_number());
+    assert!(request.params.is_some());
+}
+
+#[test]
+fn test_request_builder_hello() {
+    let mut builder = RequestBuilder::new();
+    let request = builder.build_hello_request("test-client", "1.0.0");
+
+    assert_eq!(request.method, "public/hello");
+    assert_eq!(request.jsonrpc, "2.0");
+    assert!(request.id.is_number());
+
+    if let Some(params) = request.params {
+        let params_obj = params.as_object().unwrap();
+        assert_eq!(params_obj["client_name"], "test-client");
+        assert_eq!(params_obj["client_version"], "1.0.0");
+    } else {
+        panic!("hello request should have params");
+    }
+}
+
+#[test]
+fn test_request_builder_hello_custom_values() {
+    let mut builder = RequestBuilder::new();
+    let request = builder.build_hello_request("deribit-websocket", "0.2.0");
+
+    if let Some(params) = request.params {
+        let params_obj = params.as_object().unwrap();
+        assert_eq!(params_obj["client_name"], "deribit-websocket");
+        assert_eq!(params_obj["client_version"], "0.2.0");
+    } else {
+        panic!("hello request should have params");
+    }
+}
+
+#[test]
+fn test_request_builder_set_heartbeat_serialization() {
+    let mut builder = RequestBuilder::new();
+    let request = builder.build_set_heartbeat_request(30);
+
+    let serialized = serde_json::to_string(&request).unwrap();
+    let parsed: serde_json::Value = serde_json::from_str(&serialized).unwrap();
+
+    assert_eq!(parsed["jsonrpc"], "2.0");
+    assert_eq!(parsed["method"], "public/set_heartbeat");
+    assert!(parsed["id"].is_number());
+    assert_eq!(parsed["params"]["interval"], 30);
+}
+
+#[test]
+fn test_request_builder_hello_serialization() {
+    let mut builder = RequestBuilder::new();
+    let request = builder.build_hello_request("my-app", "2.0.0");
+
+    let serialized = serde_json::to_string(&request).unwrap();
+    let parsed: serde_json::Value = serde_json::from_str(&serialized).unwrap();
+
+    assert_eq!(parsed["jsonrpc"], "2.0");
+    assert_eq!(parsed["method"], "public/hello");
+    assert!(parsed["id"].is_number());
+    assert_eq!(parsed["params"]["client_name"], "my-app");
+    assert_eq!(parsed["params"]["client_version"], "2.0.0");
+}
+
+#[test]
+fn test_request_builder_incremental_ids_session_methods() {
+    let mut builder = RequestBuilder::new();
+
+    let req1 = builder.build_set_heartbeat_request(30);
+    let req2 = builder.build_disable_heartbeat_request();
+    let req3 = builder.build_hello_request("test", "1.0");
+
+    let id1 = req1.id.as_u64().unwrap();
+    let id2 = req2.id.as_u64().unwrap();
+    let id3 = req3.id.as_u64().unwrap();
+
+    assert_eq!(id2, id1 + 1);
+    assert_eq!(id3, id2 + 1);
+}