update

examples/tutorial.md

@@ -107,10 +107,15 @@ python3 -m http.server 8080 --directory /tmp/fileserver
 ```python
 from nats_bridge import smartsend
 
-# Send a text message
+# Send a text message (is_publish=True by default)
 data = [("message", "Hello World", "text")]
-env = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
+env, msg_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
 print("Message sent!")
+
+# Or use is_publish=False to get envelope and JSON without publishing
+env, msg_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222", is_publish=False)
+# env: MessageEnvelope object
+# msg_json_str: JSON string for publishing to NATS
 ```
 
 #### JavaScript
@@ -118,12 +123,19 @@ print("Message sent!")
 ```javascript
 const { smartsend } = require('./src/NATSBridge');
 
-// Send a text message
+// Send a text message (isPublish=true by default)
 await smartsend("/chat/room1", [
     { dataname: "message", data: "Hello World", type: "text" }
 ], { natsUrl: "nats://localhost:4222" });
 
 console.log("Message sent!");
+
+// Or use isPublish=false to get envelope and JSON without publishing
+const { env, msg_json_str } = await smartsend("/chat/room1", [
+    { dataname: "message", data: "Hello World", type: "text" }
+], { natsUrl: "nats://localhost:4222", isPublish: false });
+// env: MessageEnvelope object
+// msg_json_str: JSON string for publishing to NATS
 ```
 
 #### Julia
@@ -133,7 +145,9 @@ using NATSBridge
 
 # Send a text message
 data = [("message", "Hello World", "text")]
-env = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
+env, msg_json_str = smartsend("/chat/room1", data, nats_url="nats://localhost:4222")
+# env: msgEnvelope_v1 object with all metadata and payloads
+# msg_json_str: JSON string representation of the envelope for publishing
 println("Message sent!")
 ```
 
@@ -279,13 +293,15 @@ from nats_bridge import smartsend
 
 # Send command with reply-to
 data = [("command", {"action": "read_sensor"}, "dictionary")]
-env = smartsend(
+env, msg_json_str = smartsend(
     "/device/command",
     data,
     nats_url="nats://localhost:4222",
     reply_to="/device/response",
     reply_to_msg_id="cmd-001"
 )
+# env: msgEnvelope_v1 object
+# msg_json_str: JSON string for publishing to NATS
 ```
 
 #### JavaScript (Responder)

examples/walkthrough.md

@@ -514,6 +514,7 @@ class SensorSender:
         
         data = [("reading", reading.to_dict(), "dictionary")]
         
+        # Default: is_publish=True (automatically publishes to NATS)
         smartsend(
             f"/sensors/{sensor_id}",
             data,
@@ -521,6 +522,31 @@ class SensorSender:
             fileserver_url=self.fileserver_url
         )
         
+    def prepare_message_only(self, sensor_id: str, value: float, unit: str):
+        """Prepare a message without publishing (is_publish=False)."""
+        reading = SensorReading(
+            sensor_id=sensor_id,
+            timestamp=datetime.now().isoformat(),
+            value=value,
+            unit=unit
+        )
+        
+        data = [("reading", reading.to_dict(), "dictionary")]
+        
+        # With is_publish=False, returns (envelope, json_str) without publishing
+        env, msg_json_str = smartsend(
+            f"/sensors/{sensor_id}/prepare",
+            data,
+            nats_url=self.nats_url,
+            fileserver_url=self.fileserver_url,
+            is_publish=False
+        )
+        
+        # Now you can publish manually using NATS request-reply pattern
+        # nc.request(subject, msg_json_str, reply_to=reply_to_topic)
+        
+        return env, msg_json_str
+        
     def send_batch(self, readings: List[SensorReading]):
         batch = SensorBatch()
         for reading in readings: