feat(sdk): add JobsService list, exists, restart, stop

src/uipath/_utils/__init__.py

@@ -5,6 +5,7 @@
 from ._request_spec import RequestSpec
 from ._url import UiPathUrl
 from ._user_agent import header_user_agent, user_agent_value
+from .validation import validate_pagination_params
 
 __all__ = [
     "Endpoint",
@@ -16,4 +17,5 @@
     "header_user_agent",
     "user_agent_value",
     "UiPathUrl",
+    "validate_pagination_params",
 ]

src/uipath/_utils/validation.py

@@ -0,0 +1,43 @@
+"""Validation utilities for SDK services."""
+
+
+def validate_pagination_params(
+    skip: int,
+    top: int,
+    max_skip: int = 10000,
+    max_top: int = 1000,
+) -> None:
+    """Validate pagination parameters for OData queries.
+
+    This validator is used across multiple services (BucketsService, JobsService, etc.)
+    to ensure consistent pagination behavior.
+
+    Args:
+        skip: Number of items to skip (must be >= 0 and <= max_skip)
+        top: Maximum items per page (must be >= 1 and <= max_top)
+        max_skip: Maximum allowed skip value (default: 10000)
+        max_top: Maximum allowed top value (default: 1000)
+
+    Raises:
+        ValueError: If parameters are invalid
+
+    Examples:
+        >>> validate_pagination_params(skip=0, top=100)
+        >>> validate_pagination_params(skip=5000, top=500)
+        >>> validate_pagination_params(skip=-1, top=100)  # Raises ValueError
+        >>> validate_pagination_params(skip=0, top=2000)  # Raises ValueError
+    """
+    if skip < 0:
+        raise ValueError("skip must be >= 0")
+    if skip > max_skip:
+        raise ValueError(
+            f"skip must be <= {max_skip} (requested: {skip}). "
+            f"Use filters to narrow results or manual pagination."
+        )
+    if top < 1:
+        raise ValueError("top must be >= 1")
+    if top > max_top:
+        raise ValueError(
+            f"top must be <= {max_top} (requested: {top}). "
+            f"Use pagination with skip and top parameters."
+        )

src/uipath/platform/orchestrator/_buckets_service.py

@@ -8,6 +8,7 @@
 
 from ..._utils import Endpoint, RequestSpec, header_folder, resource_override
 from ..._utils._ssl_context import get_httpx_client_kwargs
+from ..._utils.validation import validate_pagination_params
 from ...tracing import traced
 from ..common import BaseService, FolderContext, UiPathApiConfig, UiPathExecutionContext
 from ..common.paging import PagedResult
@@ -94,21 +95,13 @@ def list(
             >>> for bucket in iter_all_buckets(sdk, name="invoice"):
             ...     process_bucket(bucket)
         """
-        # Validate parameters
-        if skip < 0:
-            raise ValueError("skip must be >= 0")
-        if skip > MAX_SKIP_OFFSET:
-            raise ValueError(
-                f"skip must be <= {MAX_SKIP_OFFSET} (requested: {skip}). "
-                f"For large datasets, use list_files() with continuation tokens instead of offset-based pagination."
-            )
-        if top < 1:
-            raise ValueError("top must be >= 1")
-        if top > MAX_PAGE_SIZE:
-            raise ValueError(
-                f"top must be <= {MAX_PAGE_SIZE} (requested: {top}). "
-                f"Use pagination with skip and top parameters to retrieve larger datasets."
-            )
+        # Validate parameters using shared utility
+        validate_pagination_params(
+            skip=skip,
+            top=top,
+            max_skip=MAX_SKIP_OFFSET,
+            max_top=MAX_PAGE_SIZE,
+        )
 
         spec = self._list_spec(
             folder_path=folder_path,
@@ -178,21 +171,13 @@ async def list_async(
             ...         break
             ...     skip += top
         """
-        # Validate parameters
-        if skip < 0:
-            raise ValueError("skip must be >= 0")
-        if skip > MAX_SKIP_OFFSET:
-            raise ValueError(
-                f"skip must be <= {MAX_SKIP_OFFSET} (requested: {skip}). "
-                f"For large datasets, use list_files() with continuation tokens instead of offset-based pagination."
-            )
-        if top < 1:
-            raise ValueError("top must be >= 1")
-        if top > MAX_PAGE_SIZE:
-            raise ValueError(
-                f"top must be <= {MAX_PAGE_SIZE} (requested: {top}). "
-                f"Use pagination with skip and top parameters to retrieve larger datasets."
-            )
+        # Validate parameters using shared utility
+        validate_pagination_params(
+            skip=skip,
+            top=top,
+            max_skip=MAX_SKIP_OFFSET,
+            max_top=MAX_PAGE_SIZE,
+        )
 
         spec = self._list_spec(
             folder_path=folder_path,