Add file saving and URL posting methods to vCon

- Implement `save_to_file()` method for easy JSON file serialization
- Add `post_to_url()` method to send vCons to API endpoints
- Update documentation and examples in GUIDE.md and README.md
- Include comprehensive error handling and logging
- Add corresponding test cases for new methods

Author: howethomas

GUIDE.md

@@ -99,8 +99,33 @@ json_str = vcon.dumps()
 
 # To dictionary
 dict_data = vcon.to_dict()
+
+# Save to file
+vcon.save_to_file("conversation.json")
+
+# Post to URL with custom headers
+response = vcon.post_to_url(
+    'https://api.example.com/vcons',
+    headers={
+        'x-conserver-api-token': 'your-token-here',
+        'x-custom-header': 'custom-value'
+    }
+)
+if response.status_code == 200:
+    print("Successfully posted vCon")
 ```
 
+The `save_to_file` method allows you to save a vCon directly to a JSON file:
+- Takes a file path as argument
+- Automatically handles JSON serialization
+- Raises IOError if there are file permission issues
+
+The `post_to_url` method enables sending a vCon to a URL endpoint:
+- Automatically sets Content-Type to application/json
+- Supports custom headers for authentication and other purposes
+- Returns a requests.Response object for handling the server response
+- Raises requests.RequestException for network/server errors
+
 ### Tags
 ```python
 # Add a tag

README.md

@@ -95,6 +95,15 @@ else:
 
 # Serialize to JSON
 json_data = vcon.to_json()
+
+# Save to file
+vcon.save_to_file("conversation.json")
+
+# Post to URL with authentication
+response = vcon.post_to_url(
+    'https://api.example.com/vcons',
+    headers={'x-conserver-api-token': 'your-token-here'}
+)
 ```
 
 ## File Validation
@@ -134,6 +143,17 @@ except requests.RequestException:
     print("Error fetching from URL")
 except json.JSONDecodeError:
     print("Invalid JSON format")
+
+# Save a vCon to file
+vcon.save_to_file("conversation.json")
+
+# Post a vCon to a URL with custom headers
+response = vcon.post_to_url(
+    'https://api.example.com/vcons',
+    headers={'x-conserver-api-token': 'your-token-here'}
+)
+if response.status_code == 200:
+    print("Successfully posted vCon")
 ```
 
 The validation checks include:

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "vcon"
-version = "0.4.1"
+version = "0.5.0"
 description = "The vCon library"
 authors = ["Thomas McCarthy-Howe <ghostofbasho@gmail.com>"]
 license = "MIT"

samples/example.py

@@ -11,6 +11,7 @@
 from vcon import Vcon
 from vcon.party import Party
 from vcon.dialog import Dialog
+import requests
 
 
 def main():
@@ -123,8 +124,37 @@ def main():
 
     # Save the vCon to a file
     output_filename = "example.vcon.json"
-    with open(output_filename, "w") as file:
-        file.write(vcon.to_json())
+    try:
+        vcon.save_to_file(output_filename)
+        print(f"Successfully saved vCon to {output_filename}")
+    except IOError as e:
+        print(f"Error saving vCon to file: {str(e)}")
+
+    # Post the vCon to a server (example using httpbin.org as a test endpoint)
+    try:
+        # Example with authentication and custom headers
+        headers = {
+            'x-conserver-api-token': 'your-token-here',
+            'x-custom-header': 'test-value'
+        }
+        response = vcon.post_to_url(
+            'https://httpbin.org/post',  # Test endpoint that echoes back the request
+            headers=headers
+        )
+        
+        if response.status_code == 200:
+            print("Successfully posted vCon to server")
+            # The response from httpbin.org includes the sent data and headers
+            response_data = response.json()
+            print("Server received our custom headers:")
+            for header, value in response_data['headers'].items():
+                if header.lower().startswith('x-'):
+                    print(f"  {header}: {value}")
+        else:
+            print(f"Server returned status code: {response.status_code}")
+            
+    except requests.RequestException as e:
+        print(f"Error posting vCon to server: {str(e)}")
 
 
 if __name__ == "__main__":

src/vcon/vcon.py

@@ -1078,3 +1078,62 @@ def load_from_url(cls, url: str) -> Vcon:
         response = requests.get(url)
         response.raise_for_status()  # Raise an exception for bad status codes
         return cls.build_from_json(response.text)
+
+    def save_to_file(self, file_path: str) -> None:
+        """
+        Save the vCon to a JSON file.
+
+        :param file_path: Path where the vCon JSON should be saved
+        :type file_path: str
+        :raises IOError: If there is an error writing to the file
+        """
+        logger.debug(f"Saving vCon to file: {file_path}")
+        try:
+            with open(file_path, 'w') as f:
+                f.write(self.to_json())
+            logger.info(f"Successfully saved vCon to {file_path}")
+        except IOError as e:
+            logger.error(f"Failed to save vCon to file: {str(e)}")
+            raise
+
+    def post_to_url(self, url: str, headers: Optional[Dict[str, str]] = None) -> requests.Response:
+        """
+        Post the vCon as JSON to a URL with optional headers.
+
+        :param url: The URL to post the vCon to
+        :type url: str
+        :param headers: Optional dictionary of HTTP headers (e.g., {'x-conserver-api-token': 'token123'})
+        :type headers: Optional[Dict[str, str]]
+        :return: The HTTP response from the server
+        :rtype: requests.Response
+        :raises requests.RequestException: If there is an error making the HTTP request
+        
+        Example:
+            >>> vcon = Vcon.build_new()
+            >>> response = vcon.post_to_url(
+            ...     'https://api.example.com/vcons',
+            ...     headers={'x-conserver-api-token': 'your-token-here'}
+            ... )
+            >>> print(response.status_code)  # Prints HTTP status code (e.g., 200 for success)
+        """
+        logger.debug(f"Posting vCon to URL: {url}")
+        
+        # Prepare headers
+        request_headers = {
+            'Content-Type': 'application/json'
+        }
+        if headers:
+            request_headers.update(headers)
+        
+        try:
+            response = requests.post(
+                url,
+                data=self.to_json(),
+                headers=request_headers
+            )
+            response.raise_for_status()
+            logger.info(f"Successfully posted vCon to {url}")
+            return response
+        except requests.RequestException as e:
+            logger.error(f"Failed to post vCon to URL: {str(e)}")
+            raise

tests/test_vcon.py

@@ -770,3 +770,84 @@ def test_load_detects_file_vs_url() -> None:
         # Restore original methods
         Vcon.load_from_file = original_load_from_file
         Vcon.load_from_url = original_load_from_url
+
+
+def test_save_to_file(tmp_path):
+    """Test saving a vCon to a file"""
+    # Create a vCon with known content
+    vcon = Vcon.build_from_json(test_vcon_string)
+    
+    # Save to a temporary file
+    file_path = tmp_path / "saved_vcon.json"
+    vcon.save_to_file(str(file_path))
+    
+    # Verify the file exists and contains correct content
+    assert file_path.exists()
+    with open(file_path, 'r') as f:
+        saved_content = f.read()
+    assert json.loads(saved_content) == json.loads(vcon.to_json())
+
+
+def test_save_to_file_permission_error(tmp_path):
+    """Test saving to a file with no write permissions raises IOError"""
+    vcon = Vcon.build_new()
+    file_path = tmp_path / "readonly.json"
+    
+    # Create a read-only directory
+    file_path.parent.chmod(0o444)
+    
+    with pytest.raises(IOError):
+        vcon.save_to_file(str(file_path))
+
+
+@pytest.mark.vcr()
+def test_post_to_url():
+    """Test posting a vCon to a URL"""
+    vcon = Vcon.build_new()
+    url = "https://httpbin.org/post"  # Test endpoint that echoes back the request
+    
+    # Test with custom headers
+    headers = {
+        'x-conserver-api-token': 'test-token',
+        'x-custom-header': 'test-value'
+    }
+    
+    response = vcon.post_to_url(url, headers=headers)
+    
+    # Verify the response
+    assert response.status_code == 200
+    response_data = response.json()
+    
+    # Verify the sent data matches our vCon
+    assert json.loads(response_data['data']) == json.loads(vcon.to_json())
+    
+    # Verify headers were sent correctly
+    assert response_data['headers']['Content-Type'] == 'application/json'
+    assert response_data['headers']['X-Conserver-Api-Token'] == 'test-token'
+    assert response_data['headers']['X-Custom-Header'] == 'test-value'
+
+
+@pytest.mark.vcr()
+def test_post_to_url_no_headers():
+    """Test posting a vCon to a URL without custom headers"""
+    vcon = Vcon.build_new()
+    url = "https://httpbin.org/post"
+    
+    response = vcon.post_to_url(url)
+    
+    assert response.status_code == 200
+    response_data = response.json()
+    
+    # Verify only default headers were sent
+    assert response_data['headers']['Content-Type'] == 'application/json'
+    assert 'X-Conserver-Api-Token' not in response_data['headers']
+
+
+@pytest.mark.vcr()
+def test_post_to_url_error():
+    """Test posting to an invalid URL raises RequestException"""
+    vcon = Vcon.build_new()
+    url = "https://nonexistent.example.com"
+    
+    with pytest.raises(requests.RequestException):
+        vcon.post_to_url(url)