Add cached diff-scan polling support to DiffScans.get (#99)

* Add cached/query param support and 202 handling to diffscans.get

DiffScans.get now accepts optional query params (cached, omit_unchanged,
omit_license_details) and returns a {"status": "processing", "id": ...}
dict on HTTP 202 instead of logging an error, so clients can poll
GET /orgs/{org}/diff-scans/{id}?cached=true until the computed diff is
ready rather than holding a single idle connection open while the
backend computes (which idle-timeout middleboxes like Azure NAT
gateways kill after ~4 minutes).

Also encode list-valued query params (e.g. committers) as repeated
params in create_from_repo/create_from_ids via urlencode(doseq=True).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Harden diff-scan processing sentinel

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: lelia

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "socketdev"
-version = "3.4.0"
+version = "3.4.1"
 requires-python = ">= 3.9"
 dependencies = [
     'requests',

socketdev/diffscans/__init__.py

@@ -21,12 +21,45 @@ def list(self, org_slug: str, params: Optional[Dict[str, Any]] = None) -> dict:
         log.error(f"Error listing diff scans: {response.status_code}, message: {response.text}")
         return {}
 
-    def get(self, org_slug: str, diff_scan_id: str) -> dict:
-        """Fetch a diff scan by ID."""
+    def get(self, org_slug: str, diff_scan_id: str, params: Optional[Dict[str, Any]] = None) -> dict:
+        """Fetch a diff scan by ID.
+
+        Args:
+            org_slug: Organization slug
+            diff_scan_id: The ID of the diff scan to fetch
+            params: Optional query parameters. Supports:
+                cached: When "true", return pre-computed results immediately
+                        (200) or a processing status (202) instead of holding
+                        the connection open while the diff is computed.
+                omit_unchanged: When "true", omit unchanged artifacts.
+                omit_license_details: When "true", omit license details.
+
+        Returns:
+            dict: On 200, the API response containing the diff_scan object.
+                On 202 (results still processing when cached=true), a dict of
+                {"status": "processing", "id": diff_scan_id} so callers can
+                poll until the diff scan is ready. Empty dict on error.
+        """
+        import urllib.parse
         path = f"orgs/{org_slug}/diff-scans/{diff_scan_id}"
+        if params:
+            path += "?" + urllib.parse.urlencode(params, doseq=True)
         response = self.api.do_request(path=path, method="GET")
         if response.status_code == 200:
             return response.json()
+        if response.status_code == 202:
+            result = {}
+            try:
+                body = response.json()
+                if isinstance(body, dict):
+                    result.update(body)
+            except ValueError:
+                pass
+            # HTTP 202 always means the requested diff is still processing.
+            # Keep any additional response fields, but make the polling
+            # sentinel and requested resource ID authoritative for callers.
+            result.update({"status": "processing", "id": diff_scan_id})
+            return result
         log.error(f"Error fetching diff scan: {response.status_code}, message: {response.text}")
         return {}
 
@@ -61,7 +94,8 @@ def create_from_repo(self, org_slug: str, repo_slug: str, files: list, params: O
         import urllib.parse
         path = f"orgs/{org_slug}/diff-scans/from-repo/{repo_slug}"
         if params:
-            path += "?" + urllib.parse.urlencode(params)
+            # doseq=True so list values (e.g. committers) become repeated params
+            path += "?" + urllib.parse.urlencode(params, doseq=True)
 
         # Use lazy loading if requested
         if use_lazy_loading:
@@ -80,7 +114,7 @@ def create_from_ids(self, org_slug: str, params: Dict[str, Any]) -> dict:
         import urllib.parse
         path = f"orgs/{org_slug}/diff-scans/from-ids"
         if params:
-            path += "?" + urllib.parse.urlencode(params)
+            path += "?" + urllib.parse.urlencode(params, doseq=True)
         response = self.api.do_request(path=path, method="POST")
         if response.status_code in (200, 201):
             return response.json()

socketdev/version.py

@@ -1 +1 @@
-__version__ = "3.4.0"
+__version__ = "3.4.1"

tests/unit/test_all_endpoints_unit.py

@@ -113,6 +113,59 @@ def test_diffscans_get_unit(self):
         self.assertEqual(call_args[0][0], "GET")
         self.assertIn("/orgs/test-org/diff-scans/diff-123", call_args[0][1])
 
+    def test_diffscans_get_cached_unit(self):
+        """Test diffscans get passes cached/omit params through as a query string."""
+        expected_data = {
+            "diff_scan": {
+                "id": "diff-123",
+                "artifacts": {"added": [], "removed": [], "unchanged": [], "replaced": [], "updated": []},
+            }
+        }
+        self._mock_response(expected_data)
+
+        result = self.sdk.diffscans.get("test-org", "diff-123", params={"cached": "true"})
+
+        self.assertEqual(result, expected_data)
+        call_args = self.mock_requests.request.call_args
+        self.assertEqual(call_args[0][0], "GET")
+        self.assertIn("/orgs/test-org/diff-scans/diff-123?cached=true", call_args[0][1])
+
+    def test_diffscans_get_processing_unit(self):
+        """Test diffscans get surfaces 202 processing status instead of an error."""
+        self._mock_response({"status": "processing", "id": "diff-123"}, 202)
+
+        result = self.sdk.diffscans.get("test-org", "diff-123", params={"cached": "true"})
+
+        self.assertEqual(result.get("status"), "processing")
+        self.assertEqual(result.get("id"), "diff-123")
+
+    def test_diffscans_get_processing_empty_body_unit(self):
+        """Test diffscans get synthesizes the processing status when the 202 body is empty."""
+        mock_response = Mock()
+        mock_response.status_code = 202
+        mock_response.headers = {}
+        mock_response.json.side_effect = ValueError("no body")
+        mock_response.text = ""
+        self.mock_requests.request.return_value = mock_response
+
+        result = self.sdk.diffscans.get("test-org", "diff-123", params={"cached": "true"})
+
+        self.assertEqual(result, {"status": "processing", "id": "diff-123"})
+
+    def test_diffscans_get_processing_sentinel_wins_unit(self):
+        """Test a 202 body cannot override the SDK's polling sentinel or requested ID."""
+        self._mock_response(
+            {"status": "pending", "id": "wrong-id", "retry_after": 5},
+            202,
+        )
+
+        result = self.sdk.diffscans.get("test-org", "diff-123", params={"cached": "true"})
+
+        self.assertEqual(
+            result,
+            {"status": "processing", "id": "diff-123", "retry_after": 5},
+        )
+
     def test_diffscans_create_from_ids_unit(self):
         """Test diffscans creation from scan IDs."""
         expected_data = {"id": "new-diff-scan", "status": "queued"}
@@ -153,6 +206,29 @@ def test_diffscans_create_from_repo_unit(self):
             finally:
                 os.unlink(f.name)
 
+    def test_diffscans_create_from_repo_committers_list_unit(self):
+        """Test list-valued params (committers) encode as repeated query params."""
+        self._mock_response({"id": "repo-diff-scan"}, 201)
+
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f:
+            json.dump({"name": "test", "version": "1.0.0"}, f)
+            f.flush()
+
+            try:
+                with open(f.name, "rb") as file_obj:
+                    files = [("file", ("package.json", file_obj))]
+                    params = {"committers": ["alice", "bob"], "branch": "main"}
+                    self.sdk.diffscans.create_from_repo("test-org", "test-repo", files, params)
+
+                call_args = self.mock_requests.request.call_args
+                url = call_args[0][1]
+                self.assertIn("committers=alice", url)
+                self.assertIn("committers=bob", url)
+                self.assertIn("branch=main", url)
+
+            finally:
+                os.unlink(f.name)
+
     def test_diffscans_gfm_unit(self):
         """Test diffscans GitHub Flavored Markdown export."""
         expected_data = {"markdown": "# Diff Report\n\n## Summary\n- Added: 0\n- Removed: 0"}