Expose token in Share objects (#427)

Some use cases require passing the token to external applications that
access NextCloud shares via WebDAV.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* File shares now include a read-only token property so users can access
share token information directly when working with shared files.

* **Tests**
* Test coverage expanded to assert that newly created shares provide a
non-empty token and that token values returned by share lookups match
the original creation token.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: meck-gd

nc_py_api/files/__init__.py

@@ -442,6 +442,12 @@ def path(self) -> str:
         """Share path relative to the user's root directory."""
         return self._raw_data.get("path", "").lstrip("/")
 
+    @property
+    def token(self) -> str:
+        """Token for the Shared object."""
+        # Nextcloud pre-initializes token to null and overwrites it for types that have it.
+        return self._raw_data.get("token") or ""
+
     @property
     def label(self) -> str:
         """Label for the Shared object."""

tests/actual_tests/files_sharing_test.py

@@ -46,6 +46,8 @@ def _test_share_fields(new_share: Share, get_by_id: Share, shared_file: FsNode):
     assert new_share.permissions & FilePermissions.PERMISSION_READ
     assert new_share.url
     assert new_share.path == shared_file.user_path
+    assert new_share.token
+    assert get_by_id.token == new_share.token
     assert get_by_id.share_id == new_share.share_id
     assert get_by_id.path == new_share.path
     assert get_by_id.mimetype == new_share.mimetype