feat: expose S3 presigned download URL on FsNode

nc_py_api/files/__init__.py

@@ -107,6 +107,8 @@ def __init__(self, **kwargs):
             self.creation_date = kwargs.get("creation_date", datetime.datetime(1970, 1, 1))
         except (ValueError, TypeError):
             self.creation_date = datetime.datetime(1970, 1, 1)
+        self._download_url: str = kwargs.get("download_url", "")
+        self._download_url_expiration: int = kwargs.get("download_url_expiration", 0)
         self._trashbin: dict[str, str | int] = {}
         for i in ("trashbin_filename", "trashbin_original_location", "trashbin_deletion_time"):
             if i in kwargs:
@@ -132,6 +134,20 @@ def permissions(self) -> str:
         """Permissions for the object."""
         return self._raw_data["permissions"]
 
+    @property
+    def download_url(self) -> str:
+        """S3 presigned URL for direct download, bypassing Nextcloud.
+
+        Only available when the storage backend is S3 with ``use_presigned_url`` enabled.
+        Empty string when not available.
+        """
+        return self._download_url
+
+    @property
+    def download_url_expiration(self) -> int:
+        """Expiration timestamp for :py:attr:`download_url`. Zero when not available."""
+        return self._download_url_expiration
+
     @property
     def last_modified(self) -> datetime.datetime:
         """Time when the object was last modified.

nc_py_api/files/_files.py

@@ -26,6 +26,7 @@
     "oc:id",
     "oc:fileid",
     "oc:downloadURL",
+    "nc:download-url-expiration",
     "oc:dDC",
     "oc:permissions",
     "oc:checksums",
@@ -306,6 +307,10 @@ def _parse_record(full_path: str, prop_stats: list[dict]) -> FsNode:  # noqa pyl
             fs_node_args["mimetype"] = prop["d:getcontenttype"]
         if "oc:permissions" in prop_keys:
             fs_node_args["permissions"] = prop["oc:permissions"]
+        if "oc:downloadURL" in prop_keys and prop["oc:downloadURL"]:
+            fs_node_args["download_url"] = prop["oc:downloadURL"]
+        if "nc:download-url-expiration" in prop_keys and prop["nc:download-url-expiration"]:
+            fs_node_args["download_url_expiration"] = int(prop["nc:download-url-expiration"])
         if "oc:favorite" in prop_keys:
             fs_node_args["favorite"] = bool(int(prop["oc:favorite"]))
         if "nc:trashbin-filename" in prop_keys:
@@ -367,7 +372,7 @@ def _webdav_response_to_records(webdav_res: Response, info: str) -> list[dict]:
     if "d:error" in response_data:
         err = response_data["d:error"]
         raise NextcloudException(
-            reason=f'{err["s:exception"]}: {err["s:message"]}'.replace("\n", ""), info=info, response=webdav_res
+            reason=f"{err['s:exception']}: {err['s:message']}".replace("\n", ""), info=info, response=webdav_res
         )
     response = response_data["d:multistatus"].get("d:response", [])
     return [response] if isinstance(response, dict) else response