From 0cf300a3017e51ba75358db6a6910f5fc1cef9be Mon Sep 17 00:00:00 2001
From: radu-mocanu <radu.mocanu@uipath.com>
Date: Fri, 26 Jun 2026 16:58:58 +0300
Subject: [PATCH] fix(core): match AttachmentsProtocol.upload_async to the
 concrete overloads

---
 packages/uipath-core/pyproject.toml           |  2 +-
 .../src/uipath/core/workspace/protocols.py    | 24 ++++++++++++++++++-
 packages/uipath-core/uv.lock                  |  2 +-
 .../services/test_attachments_service.py      | 14 +++++++++++
 packages/uipath-platform/uv.lock              |  2 +-
 packages/uipath/uv.lock                       |  2 +-
 6 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/packages/uipath-core/pyproject.toml b/packages/uipath-core/pyproject.toml
index 473d485a3..93be7ebc0 100644
--- a/packages/uipath-core/pyproject.toml
+++ b/packages/uipath-core/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "uipath-core"
-version = "0.5.22"
+version = "0.5.23"
 description = "UiPath Core abstractions"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"
diff --git a/packages/uipath-core/src/uipath/core/workspace/protocols.py b/packages/uipath-core/src/uipath/core/workspace/protocols.py
index c3f39c170..c49c7bc59 100644
--- a/packages/uipath-core/src/uipath/core/workspace/protocols.py
+++ b/packages/uipath-core/src/uipath/core/workspace/protocols.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Protocol, runtime_checkable
+from typing import Protocol, overload, runtime_checkable
 from uuid import UUID
 
 
@@ -20,6 +20,28 @@ async def download_async(
     ) -> str:
         """Download an attachment to a local path."""
 
+    # Overloads mirror the concrete AttachmentsService: content XOR source_path,
+    # so the real service is a structural subtype of this protocol.
+    @overload
+    async def upload_async(
+        self,
+        *,
+        name: str,
+        content: str | bytes,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> UUID: ...
+
+    @overload
+    async def upload_async(
+        self,
+        *,
+        name: str,
+        source_path: str,
+        folder_key: str | None = None,
+        folder_path: str | None = None,
+    ) -> UUID: ...
+
     async def upload_async(
         self,
         *,
diff --git a/packages/uipath-core/uv.lock b/packages/uipath-core/uv.lock
index cfb903454..67d937f3a 100644
--- a/packages/uipath-core/uv.lock
+++ b/packages/uipath-core/uv.lock
@@ -1011,7 +1011,7 @@ wheels = [
 
 [[package]]
 name = "uipath-core"
-version = "0.5.22"
+version = "0.5.23"
 source = { editable = "." }
 dependencies = [
     { name = "opentelemetry-instrumentation" },
diff --git a/packages/uipath-platform/tests/services/test_attachments_service.py b/packages/uipath-platform/tests/services/test_attachments_service.py
index dfde1a304..0623858e2 100644
--- a/packages/uipath-platform/tests/services/test_attachments_service.py
+++ b/packages/uipath-platform/tests/services/test_attachments_service.py
@@ -1193,3 +1193,17 @@ async def test_open_async_write_mode(
         assert upload_request is not None
         assert upload_request.method == "PUT"
         assert upload_request.url == blob_uri_response["BlobFileAccess"]["Uri"]
+
+
+def test_attachments_service_conforms_to_attachments_protocol(
+    service: AttachmentsService,
+) -> None:
+    """AttachmentsService must satisfy AttachmentsProtocol (workspace hydration).
+
+    The static annotation makes mypy verify the upload_async overloads line up;
+    the isinstance check covers the runtime_checkable contract.
+    """
+    from uipath.core.workspace import AttachmentsProtocol
+
+    conforming: AttachmentsProtocol = service
+    assert isinstance(conforming, AttachmentsProtocol)
diff --git a/packages/uipath-platform/uv.lock b/packages/uipath-platform/uv.lock
index 0f0f36b5a..c0552fa41 100644
--- a/packages/uipath-platform/uv.lock
+++ b/packages/uipath-platform/uv.lock
@@ -1063,7 +1063,7 @@ wheels = [
 
 [[package]]
 name = "uipath-core"
-version = "0.5.22"
+version = "0.5.23"
 source = { editable = "../uipath-core" }
 dependencies = [
     { name = "opentelemetry-instrumentation" },
diff --git a/packages/uipath/uv.lock b/packages/uipath/uv.lock
index 59e93a39d..f99dd06a0 100644
--- a/packages/uipath/uv.lock
+++ b/packages/uipath/uv.lock
@@ -2659,7 +2659,7 @@ dev = [
 
 [[package]]
 name = "uipath-core"
-version = "0.5.22"
+version = "0.5.23"
 source = { editable = "../uipath-core" }
 dependencies = [
     { name = "opentelemetry-instrumentation" },