feat: add timeout resume helpers (#1795)

Author: radu-mocanu

packages/uipath-core/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-core"
-version = "0.5.28"
+version = "0.5.29"
 description = "UiPath Core abstractions"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-core/src/uipath/core/triggers/__init__.py

@@ -5,6 +5,7 @@
     "UiPathResumeTriggerType",
     "UiPathApiTrigger",
     "UiPathIntegrationTrigger",
+    "UiPathResumeMetadata",
     "UiPathResumeTriggerName",
     "UIPATH_METADATA_KEY",
 ]
@@ -13,6 +14,7 @@
     UIPATH_METADATA_KEY,
     UiPathApiTrigger,
     UiPathIntegrationTrigger,
+    UiPathResumeMetadata,
     UiPathResumeTrigger,
     UiPathResumeTriggerName,
     UiPathResumeTriggerType,

packages/uipath-core/src/uipath/core/triggers/trigger.py

@@ -48,6 +48,20 @@ class UiPathResumeTriggerName(str, Enum):
     DEEP_RAG_RAW = "DeepRagRaw"
 
 
+class UiPathResumeMetadata(BaseModel):
+    """UiPath metadata attached to resume values from multi-trigger interrupts."""
+
+    kind: str | None = None
+    trigger_type: UiPathResumeTriggerType | None = Field(
+        default=None, alias="triggerType"
+    )
+    trigger_name: UiPathResumeTriggerName | None = Field(
+        default=None, alias="triggerName"
+    )
+
+    model_config = ConfigDict(validate_by_name=True)
+
+
 class UiPathApiTrigger(BaseModel):
     """API resume trigger request."""
 

packages/uipath-core/tests/triggers/test_resume_metadata.py

@@ -0,0 +1,29 @@
+from uipath.core.triggers import (
+    UiPathResumeMetadata,
+    UiPathResumeTriggerName,
+    UiPathResumeTriggerType,
+)
+
+
+def test_resume_metadata_accepts_trigger_aliases() -> None:
+    metadata = UiPathResumeMetadata.model_validate(
+        {
+            "kind": "timeout",
+            "triggerType": "Timer",
+            "triggerName": "Timer",
+        }
+    )
+
+    assert metadata.kind == "timeout"
+    assert metadata.trigger_type == UiPathResumeTriggerType.TIMER
+    assert metadata.trigger_name == UiPathResumeTriggerName.TIMER
+
+
+def test_resume_metadata_accepts_field_names() -> None:
+    metadata = UiPathResumeMetadata(
+        trigger_type=UiPathResumeTriggerType.API,
+        trigger_name=UiPathResumeTriggerName.API,
+    )
+
+    assert metadata.trigger_type == UiPathResumeTriggerType.API
+    assert metadata.trigger_name == UiPathResumeTriggerName.API

packages/uipath-core/uv.lock

@@ -1,14 +1,14 @@
 [project]
 name = "uipath-platform"
-version = "0.2.1"
+version = "0.2.2"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
 dependencies = [
   "httpx>=0.28.1",
   "tenacity>=9.0.0",
   "truststore>=0.10.1",
-  "uipath-core>=0.5.28, <0.6.0",
+  "uipath-core>=0.5.29, <0.6.0",
   "pydantic-function-models>=0.1.11",
   "sqlparse>=0.5.5",
 ]

packages/uipath-platform/pyproject.toml

@@ -3,6 +3,8 @@
 This module contains common models used across multiple services.
 """
 
+from uipath.core.triggers import UiPathResumeMetadata
+
 from ._api_client import ApiClient
 from ._base_service import BaseService, resolve_trace_id
 from ._bindings import (
@@ -62,6 +64,12 @@
     WaitUntil,
 )
 from .paging import PagedResult
+from .timeout import (
+    UiPathTimeoutError,
+    assert_no_timeout,
+    get_resume_metadata,
+    is_timeout,
+)
 
 __all__ = [
     "ApiClient",
@@ -125,6 +133,11 @@
     "resolve_service_url",
     "inject_routing_headers",
     "resolve_trace_id",
+    "UiPathTimeoutError",
+    "UiPathResumeMetadata",
+    "assert_no_timeout",
+    "get_resume_metadata",
+    "is_timeout",
 ]
 
 from .validation import validate_pagination_params

packages/uipath-platform/src/uipath/platform/common/__init__.py

@@ -0,0 +1,56 @@
+"""Helpers for resume values produced by timeout triggers."""
+
+from collections.abc import Mapping
+from typing import Any, TypeVar
+
+from pydantic import ValidationError
+from uipath.core.triggers import (
+    UIPATH_METADATA_KEY,
+    UiPathResumeMetadata,
+)
+
+T = TypeVar("T")
+
+_TIMEOUT_KIND = "timeout"
+
+
+class UiPathTimeoutError(TimeoutError):
+    """Raised when a resume value came from a UiPath timeout trigger."""
+
+    def __init__(self, value: Any):
+        """Create a timeout error that keeps the original resume value."""
+        super().__init__("UiPath interrupt timed out.")
+        self.value = value
+
+
+def is_timeout(value: Any) -> bool:
+    """Return True when a resume value came from a UiPath timeout trigger."""
+    metadata = get_resume_metadata(value)
+    return metadata is not None and metadata.kind == _TIMEOUT_KIND
+
+
+def assert_no_timeout(value: T) -> T:
+    """Raise UiPathTimeoutError if a resume value came from a timeout trigger."""
+    if is_timeout(value):
+        raise UiPathTimeoutError(value)
+    return value
+
+
+def get_resume_metadata(value: Any) -> UiPathResumeMetadata | None:
+    """Return UiPath resume metadata when present on a resume value."""
+    metadata = _metadata(value)
+    if metadata is None:
+        return None
+
+    try:
+        return UiPathResumeMetadata.model_validate(metadata)
+    except ValidationError:
+        return None
+
+
+def _metadata(value: Any) -> Mapping[str, Any] | None:
+    if not isinstance(value, Mapping):
+        return None
+
+    metadata = value.get(UIPATH_METADATA_KEY)
+    return metadata if isinstance(metadata, Mapping) else None

packages/uipath-platform/src/uipath/platform/common/timeout.py

@@ -0,0 +1,96 @@
+import pytest
+from uipath.core.triggers import (
+    UIPATH_METADATA_KEY,
+    UiPathResumeTriggerName,
+    UiPathResumeTriggerType,
+)
+
+from uipath.platform.common import (
+    UiPathResumeMetadata,
+    UiPathTimeoutError,
+    assert_no_timeout,
+    get_resume_metadata,
+    is_timeout,
+)
+
+
+def test_is_timeout_detects_timeout_metadata() -> None:
+    value = {
+        UIPATH_METADATA_KEY: {
+            "kind": "timeout",
+            "triggerType": "Timer",
+            "triggerName": "Timer",
+        },
+        "value": None,
+    }
+
+    assert is_timeout(value) is True
+
+
+def test_get_resume_metadata_returns_typed_metadata() -> None:
+    value = {
+        UIPATH_METADATA_KEY: {
+            "kind": "timeout",
+            "triggerType": "Timer",
+            "triggerName": "Timer",
+        },
+        "resumeTime": "2026-07-07T12:00:00Z",
+    }
+
+    metadata = get_resume_metadata(value)
+
+    assert isinstance(metadata, UiPathResumeMetadata)
+    assert metadata.kind == "timeout"
+    assert metadata.trigger_type == UiPathResumeTriggerType.TIMER
+    assert metadata.trigger_name == UiPathResumeTriggerName.TIMER
+
+
+def test_get_resume_metadata_returns_none_without_metadata() -> None:
+    assert get_resume_metadata({"result": "done"}) is None
+    assert get_resume_metadata("done") is None
+
+
+def test_get_resume_metadata_returns_none_for_invalid_metadata() -> None:
+    value = {
+        UIPATH_METADATA_KEY: {
+            "triggerType": "NotARealTrigger",
+            "triggerName": "Timer",
+        },
+    }
+
+    assert get_resume_metadata(value) is None
+
+
+def test_is_timeout_ignores_plain_timer_metadata() -> None:
+    value = {
+        UIPATH_METADATA_KEY: {
+            "triggerType": "Timer",
+            "triggerName": "Timer",
+        },
+        "resumeTime": "2026-07-07T12:00:00Z",
+    }
+
+    assert is_timeout(value) is False
+
+
+def test_is_timeout_ignores_user_timed_out_fields() -> None:
+    assert is_timeout({"timedOut": True}) is False
+    assert is_timeout("timeout") is False
+
+
+def test_assert_no_timeout_returns_original_value() -> None:
+    value = {"result": "done"}
+
+    assert assert_no_timeout(value) is value
+
+
+def test_assert_no_timeout_raises_with_resume_value() -> None:
+    value = {
+        UIPATH_METADATA_KEY: {"kind": "timeout"},
+        "value": {"jobKey": "job-1"},
+    }
+
+    with pytest.raises(UiPathTimeoutError) as exc_info:
+        assert_no_timeout(value)
+
+    assert exc_info.value.value is value