Add org slug param with org-scoped routing, deprecation warning

Signed-off-by: lelia <2418071+lelia@users.noreply.github.com>

Author: lelia

.gitignore

@@ -16,4 +16,7 @@ dist
 *.egg-info
 *.cpython-312.pyc
 example-socket-export.py
-__pycache__/
+__pycache__/
+.coverage
+.coverage.*
+htmlcov/

README.rst

@@ -28,31 +28,35 @@ Supported Functions
 -------------------
 
 
-purl.post(license, components)
-""""""""""""""""""""""""""""""
-Retrieve the package information for a purl post
+purl.post(license, components, org_slug=None)
+"""""""""""""""""""""""""""""""""""""""""""
+Retrieve package information for one or more PURLs. Pass ``org_slug`` to use the
+current org-scoped endpoint. Omitting ``org_slug`` keeps the legacy deprecated
+endpoint for backwards compatibility.
 
 **Usage:**
 
 .. code-block:: python
 
-    from socketdev import socketdev
-    socket = socketdev(token="REPLACE_ME")
-    license = "true"
-    components = [
-        {
+    from socketdev import socketdev
+    socket = socketdev(token="REPLACE_ME")
+    org_slug = "your-org-slug"
+    license = "true"
+    components = [
+        {
         "purl": "pkg:pypi/pyonepassword@5.0.0"
         },
         {
-        "purl": "pkg:pypi/socketsecurity"
-        }
-    ]
-    print(socket.purl.post(license, components))
+        "purl": "pkg:pypi/socketsecurity"
+        }
+    ]
+    print(socket.purl.post(license, components, org_slug=org_slug))
 
 **PARAMETERS:**
 
-- **license (str)** - The license parameter if enabled will show alerts and license information. If disabled will only show the basic package metadata and scores. Default is true
-- **components (array{dict})** - The components list of packages urls
+- **license (str)** - The license parameter if enabled will show alerts and license information. If disabled will only show the basic package metadata and scores. Default is true
+- **components (array{dict})** - The components list of packages urls
+- **org_slug (str, optional)** - Organization slug for the supported org-scoped PURL endpoint. If omitted, the SDK uses the deprecated legacy endpoint for backwards compatibility.
 
 export.cdx_bom(org_slug, id, query_params)
 """"""""""""""""""""""""""""""""""""""""""

socketdev/purl/__init__.py

@@ -1,5 +1,6 @@
 import json
 import urllib.parse
+import warnings
 from socketdev.log import log
 from ..core.dedupe import Dedupe
 
@@ -8,8 +9,21 @@ class Purl:
     def __init__(self, api):
         self.api = api
 
-    def post(self, license: str = "false", components: list = None, **kwargs) -> list:
-        path = "purl?"
+    def post(
+        self,
+        license: str = "false",
+        components: list = None,
+        org_slug: str = None,
+        **kwargs,
+    ) -> list:
+        if org_slug is None:
+            warnings.warn(
+                "Calling purl.post() without org_slug uses the deprecated POST /v0/purl endpoint. "
+                "Pass org_slug to migrate to POST /v0/orgs/{org_slug}/purl.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        path = f"orgs/{org_slug}/purl?" if org_slug else "purl?"
         if components is None:
             components = []
         purls = {"components": components}