update

src/nats_bridge.py

@@ -14,8 +14,24 @@ API Standard:
     # Input format for smartsend (always a list of tuples with type info)
     [(dataname1, data1, type1), (dataname2, data2, type2), ...]
     
-    # Output format for smartreceive (always returns a list of tuples)
+    # Output format for smartreceive (returns a dictionary with payloads field containing list of tuples)
-    [(dataname1, data1, type1), (dataname2, data2, type2), ...]
+    # Returns: Dict with envelope metadata and payloads field containing list of tuples
+    # {
+    #   "correlation_id": "...",
+    #   "msg_id": "...",
+    #   "timestamp": "...",
+    #   "send_to": "...",
+    #   "msg_purpose": "...",
+    #   "sender_name": "...",
+    #   "sender_id": "...",
+    #   "receiver_name": "...",
+    #   "receiver_id": "...",
+    #   "reply_to": "...",
+    #   "reply_to_msg_id": "...",
+    #   "broker_url": "...",
+    #   "metadata": {...},
+    #   "payloads": [(dataname1, data1, type1), (dataname2, data2, type2), ...]
+    # }
 """
 
 import json
@@ -121,7 +137,7 @@ class MessageEnvelope:
     
     def __init__(self, send_to, payloads, correlation_id="", msg_id="", timestamp="",
                  msg_purpose="", sender_name="", sender_id="", receiver_name="",
-                 receiver_id="", reply_to="", reply_to_msg_id="", broker_url=DEFAULT_NATS_URL,
+                 receiver_id="", reply_to="", reply_to_msg_id="", broker_url=DEFAULT_BROKER_URL,
                  metadata=None):
         """
         Initialize a MessageEnvelope.
@@ -572,12 +588,18 @@ def smartsend(subject, data, broker_url=DEFAULT_BROKER_URL, fileserver_url=DEFAU
     publishes directly over NATS. Otherwise, it uploads the data to a fileserver and publishes 
     only the download URL over NATS.
     
+    API Standard:
+        - Input format: List of (dataname, data, payload_type) tuples
+        - Even single payloads must be wrapped in a list
+        - Each payload can have a different type, enabling mixed-content messages
+    
     Args:
         subject: NATS subject to publish the message to
         data: List of (dataname, data, payload_type) tuples to send
             - dataname: Name of the payload
             - data: The actual data to send
             - payload_type: Payload type ("text", "dictionary", "table", "image", "audio", "video", "binary")
+            - Example: [("message", "Hello World!", "text"), ("config", {"key": "value"}, "dictionary")]
         broker_url: URL of the NATS server
         fileserver_url: URL of the HTTP file server
         fileserver_upload_handler: Function to handle fileserver uploads (must return dict with "status", "uploadid", "fileid", "url" keys)
@@ -711,6 +733,11 @@ def smartreceive(msg, fileserver_download_handler=_fetch_with_backoff, max_retri
     This function processes incoming NATS messages, handling both direct transport
     (base64 decoded payloads) and link transport (URL-based payloads).
     
+    API Standard:
+        - Returns a dictionary with envelope metadata and 'payloads' field
+        - payloads field contains list of (dataname, data, payload_type) tuples
+        - Supports mixed-content messages with different payload types
+    
     Args:
         msg: NATS message to process (dict or JSON string with envelope data)
         fileserver_download_handler: Function to handle downloading data from file server URLs
@@ -723,6 +750,10 @@ def smartreceive(msg, fileserver_download_handler=_fetch_with_backoff, max_retri
     Returns:
         dict: Envelope dictionary with metadata and 'payloads' field containing list of 
               (dataname, data, payload_type) tuples
+        - Envelope fields: correlation_id, msg_id, timestamp, send_to, msg_purpose,
+          sender_name, sender_id, receiver_name, receiver_id, reply_to, reply_to_msg_id,
+          broker_url, metadata
+        - payloads: List of (dataname, data, payload_type) tuples
     
     Example:
         >>> env = smartreceive(msg)
@@ -821,10 +852,20 @@ if __name__ == "__main__":
     print("  from nats_bridge import smartsend, smartreceive")
     print()
     print("  # Send data (list of (dataname, data, payload_type) tuples)")
+    print("  # Even single payloads must be wrapped in a list")
     print("  data = [(\"message\", \"Hello World!\", \"text\")]")
     print("  env, env_json_str = smartsend(\"my.subject\", data)")
     print()
     print("  # On receiver:")
     print("  env = smartreceive(msg)")
+    print("  # env contains envelope metadata and payloads field")
     print("  for dataname, data, payload_type in env[\"payloads\"]:")
-    print("      print(\"Received {} of type {}: {}\".format(dataname, payload_type, data))")
+    print("      print(\"Received {} of type {}: {}\".format(dataname, payload_type, data))")
+    print()
+    print("  # Mixed-content message example:")
+    print("  mixed_data = [")
+    print("      (\"text\", \"Hello!\", \"text\"),")
+    print("      (\"config\", {\"key\": \"value\"}, \"dictionary\"),")
+    print("      (\"table\", [{\"id\": 1}], \"table\")")
+    print("  ]")
+    print("  smartsend(\"/chat\", mixed_data)")