Document _request and add a Dataverse success-path test

src/fwl_io/mirror.py

@@ -143,6 +143,32 @@ def _headers(self) -> dict:
         return {'X-Dataverse-key': self.token}
 
     def _request(self, method: str, path: str, **kwargs) -> dict:
+        """Call one Dataverse native-API endpoint and return its decoded body.
+
+        Parameters
+        ----------
+        method : str
+            HTTP method, e.g. ``'POST'`` or ``'DELETE'``.
+        path : str
+            API path relative to ``self.base_url``, e.g.
+            ``'/api/datasets/:persistentId'``.
+        **kwargs
+            Passed through to :func:`requests.request` (``params``, ``json``,
+            ``files``, and so on).
+
+        Returns
+        -------
+        dict
+            The decoded JSON body, or ``{}`` for a 2xx response with an empty
+            body (routine for a DELETE call).
+
+        Raises
+        ------
+        DataverseError
+            If the HTTP transport fails, the response status is 400 or
+            higher, or a non-empty successful body fails to parse as JSON or
+            parses to something other than a JSON object.
+        """
         try:
             response = requests.request(
                 method,

tests/test_mirror.py

@@ -418,6 +418,22 @@ def test_create_with_a_non_object_json_body_raises_with_the_status_and_body():
         requests.request = orig
 
 
+@pytest.mark.unit
+def test_request_returns_the_decoded_body_on_a_valid_success_response():
+    """A 2xx response with a non-empty JSON-object body decodes and returns as-is."""
+    import requests
+
+    client = DataverseClient('http://unused', 'tok')
+    orig = requests.request
+    body_bytes = b'{"status": "OK", "data": {"id": 7}}'
+    requests.request = lambda *args, **kwargs: _fake_response(200, body_bytes)
+    try:
+        body = client._request('POST', '/api/datasets/:persistentId/add')
+        assert body == {'status': 'OK', 'data': {'id': 7}}
+    finally:
+        requests.request = orig
+
+
 @pytest.mark.unit
 def test_add_file_accepts_an_empty_success_body(tmp_path):
     """add_file does not raise when Dataverse returns 2xx with an empty body."""