...

packages/clients/myceliumclient/README.md

@@ -0,0 +1,119 @@
+# SAL Mycelium (`sal-mycelium`)
+
+A Rust client library for interacting with Mycelium node's HTTP API, with Rhai scripting support.
+
+## Installation
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+sal-mycelium = "0.1.0"
+```
+
+## Overview
+
+SAL Mycelium provides async HTTP client functionality for managing Mycelium nodes, including:
+
+- Node information retrieval
+- Peer management (list, add, remove)
+- Route inspection (selected and fallback routes)
+- Message operations (send and receive)
+
+## Usage
+
+### Rust API
+
+```rust
+use sal_mycelium::*;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let api_url = "http://localhost:8989";
+    
+    // Get node information
+    let node_info = get_node_info(api_url).await?;
+    println!("Node info: {:?}", node_info);
+    
+    // List peers
+    let peers = list_peers(api_url).await?;
+    println!("Peers: {:?}", peers);
+    
+    // Send a message
+    use std::time::Duration;
+    let result = send_message(
+        api_url,
+        "destination_ip",
+        "topic",
+        "Hello, Mycelium!",
+        Some(Duration::from_secs(30))
+    ).await?;
+    
+    Ok(())
+}
+```
+
+### Rhai Scripting
+
+```rhai
+// Get node information
+let api_url = "http://localhost:8989";
+let node_info = mycelium_get_node_info(api_url);
+print(`Node subnet: ${node_info.nodeSubnet}`);
+
+// List peers
+let peers = mycelium_list_peers(api_url);
+print(`Found ${peers.len()} peers`);
+
+// Send message (timeout in seconds, -1 for no timeout)
+let result = mycelium_send_message(api_url, "dest_ip", "topic", "message", 30);
+```
+
+## API Functions
+
+### Core Functions
+
+- `get_node_info(api_url)` - Get node information
+- `list_peers(api_url)` - List connected peers
+- `add_peer(api_url, peer_address)` - Add a new peer
+- `remove_peer(api_url, peer_id)` - Remove a peer
+- `list_selected_routes(api_url)` - List selected routes
+- `list_fallback_routes(api_url)` - List fallback routes
+- `send_message(api_url, destination, topic, message, timeout)` - Send message
+- `receive_messages(api_url, topic, timeout)` - Receive messages
+
+### Rhai Functions
+
+All functions are available in Rhai with `mycelium_` prefix:
+- `mycelium_get_node_info(api_url)`
+- `mycelium_list_peers(api_url)`
+- `mycelium_add_peer(api_url, peer_address)`
+- `mycelium_remove_peer(api_url, peer_id)`
+- `mycelium_list_selected_routes(api_url)`
+- `mycelium_list_fallback_routes(api_url)`
+- `mycelium_send_message(api_url, destination, topic, message, timeout_secs)`
+- `mycelium_receive_messages(api_url, topic, timeout_secs)`
+
+## Requirements
+
+- A running Mycelium node with HTTP API enabled
+- Default API endpoint: `http://localhost:8989`
+
+## Testing
+
+```bash
+# Run all tests
+cargo test
+
+# Run with a live Mycelium node for integration tests
+# (tests will skip if no node is available)
+cargo test -- --nocapture
+```
+
+## Dependencies
+
+- `reqwest` - HTTP client
+- `serde_json` - JSON handling
+- `base64` - Message encoding
+- `tokio` - Async runtime
+- `rhai` - Scripting support