unique_sdk 0.10.19__py3-none-any.whl → 0.10.71__py3-none-any.whl

unique_sdk/api_resources/_folder.py

@@ -1,4 +1,3 @@
-from enum import Enum
 from typing import (
     ClassVar,
     List,
@@ -23,26 +22,10 @@ class Folder(APIResource["Folder"]):
         Represents the access level of a scope.
         """
 
-        class ScopeAccessType(Enum):
-            """
-            Enum for scope access levels.
-            """
-
-            READ = "READ"
-            WRITE = "WRITE"
-
-        class ScopeAccessEntityType(Enum):
-            """
-            Enum for scope access entity types.
-            """
-
-            USER = "USER"
-            GROUP = "GROUP"
-
         entityId: str
-        type: ScopeAccessType
-        entityType: ScopeAccessEntityType
-        createdAt: str | None = None
+        type: Literal["READ", "WRITE"]
+        entityType: Literal["USER", "GROUP"]
+        createdAt: NotRequired[str]
 
     class Children(TypedDict):
         """
@@ -61,19 +44,19 @@ class Folder(APIResource["Folder"]):
         languageModel: str | None
 
     class IngestionConfig(TypedDict):
-        chunkMaxTokens: int | None
-        chunkMaxTokensOnePager: int | None
-        chunkMinTokens: int | None
-        chunkStrategy: str | None
-        customApiOptions: List["Folder.CustomApiOptions"] | None
-        documentMinTokens: int | None
-        excelReadMode: str | None
-        jpgReadMode: str | None
-        pdfReadMode: str | None
-        pptReadMode: str | None
+        chunkMaxTokens: NotRequired[int | None]
+        chunkMaxTokensOnePager: NotRequired[int | None]
+        chunkMinTokens: NotRequired[int | None]
+        chunkStrategy: NotRequired[str | None]
+        customApiOptions: NotRequired[List["Folder.CustomApiOptions"] | None]
+        documentMinTokens: NotRequired[int | None]
+        excelReadMode: NotRequired[str | None]
+        jpgReadMode: NotRequired[str | None]
+        pdfReadMode: NotRequired[str | None]
+        pptReadMode: NotRequired[str | None]
         uniqueIngestionMode: str
-        vttConfig: Optional["Folder.VttConfig"]
-        wordReadMode: str | None
+        vttConfig: NotRequired["Folder.VttConfig | None"]
+        wordReadMode: NotRequired[str | None]
 
     class CreatedFolder(TypedDict):
         id: str
@@ -86,6 +69,7 @@ class Folder(APIResource["Folder"]):
 
     class CreateParams(RequestOptions):
         paths: List[str]
+        inheritAccess: NotRequired[bool]
 
     class FolderInfo(TypedDict):
         """
@@ -100,6 +84,10 @@ class Folder(APIResource["Folder"]):
         parentId: str | None
         externalId: str | None
 
+    class FolderInfos(TypedDict):
+        folderInfos: List["Folder.FolderInfo"]
+        totalCount: int
+
     id: str
     name: str
     scopeAccess: List[ScopeAccess]
@@ -110,8 +98,8 @@ class Folder(APIResource["Folder"]):
         Parameters for updating folder ingestion config.
         """
 
-        scopeId: str | None
-        folderPath: str | None
+        scopeId: NotRequired[str | None]
+        folderPath: NotRequired[str | None]
         ingestionConfig: "Folder.IngestionConfig"
         applyToSubScopes: bool
 
@@ -120,8 +108,8 @@ class Folder(APIResource["Folder"]):
         Parameters for adding access to a folder.
         """
 
-        scopeId: str | None
-        folderPath: str | None
+        scopeId: NotRequired[str | None]
+        folderPath: NotRequired[str | None]
         scopeAccesses: List["Folder.ScopeAccess"]
         applyToSubScopes: bool
 
@@ -130,8 +118,8 @@ class Folder(APIResource["Folder"]):
         Parameters for removing access from a folder.
         """
 
-        scopeId: str | None
-        folderPath: str | None
+        scopeId: NotRequired[str | None]
+        folderPath: NotRequired[str | None]
         scopeAccesses: List["Folder.ScopeAccess"]
         applyToSubScopes: bool
 
@@ -149,8 +137,19 @@ class Folder(APIResource["Folder"]):
         Parameters for getting a folder by its Id or path.
         """
 
-        scopeId: str | None = None
-        folderPath: str | None = None
+        scopeId: NotRequired[str]
+        folderPath: NotRequired[str]
+
+    class UpdateParams(RequestOptions):
+        """
+        Parameters for updating a folder.
+        """
+
+        scopeId: NotRequired[str]
+        folderPath: NotRequired[str]
+        parentFolderPath: NotRequired[str]
+        parentId: NotRequired[str]
+        name: NotRequired[str]
 
     class GetInfosParams(RequestOptions):
         """
@@ -158,6 +157,7 @@ class Folder(APIResource["Folder"]):
         """
 
         parentId: NotRequired[str]
+        parentFolderPath: NotRequired[str]
         take: NotRequired[int]
         skip: NotRequired[int]
 
@@ -179,6 +179,53 @@ class Folder(APIResource["Folder"]):
         successFolders: List["Folder.DeleteFolderResponse"]
         failedFolders: List["Folder.DeleteFolderResponse"]
 
+    class FolderPathResponse(TypedDict):
+        """
+        Response for getting folder path.
+        """
+
+        folderPath: str
+
+    @classmethod
+    def get_folder_path(
+        cls,
+        user_id: str,
+        company_id: str,
+        scope_id: str,
+    ) -> "Folder.FolderPathResponse":
+        """
+        Get the complete folder path for a given folder ID.
+        """
+        return cast(
+            "Folder.FolderPathResponse",
+            cls._static_request(
+                "get",
+                f"/folder/{scope_id}/path",
+                user_id,
+                company_id,
+            ),
+        )
+
+    @classmethod
+    async def get_folder_path_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        scope_id: str,
+    ) -> "Folder.FolderPathResponse":
+        """
+        Async get the complete folder path for a given folder ID.
+        """
+        return cast(
+            "Folder.FolderPathResponse",
+            await cls._static_request_async(
+                "get",
+                f"/folder/{scope_id}/path",
+                user_id,
+                company_id,
+            ),
+        )
+
     @classmethod
     def get_info(
         cls, user_id: str, company_id: str, **params: Unpack["Folder.GetParams"]
@@ -218,12 +265,22 @@ class Folder(APIResource["Folder"]):
     @classmethod
     def get_infos(
         cls, user_id: str, company_id: str, **params: Unpack["Folder.GetInfosParams"]
-    ) -> "List[Folder.FolderInfo]":
+    ) -> "Folder.FolderInfos":
         """
         Get paginated folders based on parentId. If the parentId is not defined, the root folders will be returned.
         """
+        parent_id = cls.resolve_scope_id_from_folder_path(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=params.get("parentId"),
+            folder_path=params.get("parentFolderPath"),
+        )
+        params.pop("parentFolderPath", None)
+        if parent_id:
+            params["parentId"] = parent_id
+
         return cast(
-            "List[Folder.FolderInfo]",
+            "Folder.FolderInfos",
             cls._static_request(
                 "get",
                 "/folder/infos",
@@ -236,12 +293,22 @@ class Folder(APIResource["Folder"]):
     @classmethod
     async def get_infos_async(
         cls, user_id: str, company_id: str, **params: Unpack["Folder.GetInfosParams"]
-    ) -> "List[Folder.FolderInfo]":
+    ) -> "Folder.FolderInfos":
         """
         Async get paginated folders based on parentId. If the parentId is not defined, the root folders will be returned.
         """
+        parent_id = await cls.resolve_scope_id_from_folder_path_async(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=params.get("parentId"),
+            folder_path=params.get("parentFolderPath"),
+        )
+        params.pop("parentFolderPath", None)
+        if parent_id:
+            params["parentId"] = parent_id
+
         return cast(
-            "List[Folder.FolderInfo]",
+            "Folder.FolderInfos",
             await cls._static_request_async(
                 "get",
                 "/folder/infos",
@@ -256,7 +323,7 @@ class Folder(APIResource["Folder"]):
         cls, user_id: str, company_id: str, **params: Unpack["Folder.CreateParams"]
     ) -> "Folder.CreateFolderStructureResponse":
         return cast(
-            "Folder",
+            "Folder.CreateFolderStructureResponse",
             cls._static_request(
                 "post",
                 cls.RESOURCE_URL,
@@ -271,7 +338,7 @@ class Folder(APIResource["Folder"]):
         cls, user_id: str, company_id: str, **params: Unpack["Folder.CreateParams"]
     ) -> "Folder.CreateFolderStructureResponse":
         return cast(
-            "Folder",
+            "Folder.CreateFolderStructureResponse",
             await cls._static_request_async(
                 "post",
                 cls.RESOURCE_URL,
@@ -407,6 +474,84 @@ class Folder(APIResource["Folder"]):
             ),
         )
 
+    @classmethod
+    def update(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Folder.UpdateParams"],
+    ) -> "Folder.FolderInfo":
+        """
+        Update a folder given its id or path. Can update the name or the parent folder by specifying its id or path.
+        """
+
+        scopeId = cls.resolve_scope_id_from_folder_path(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=params.get("scopeId"),
+            folder_path=params.get("folderPath"),
+        )
+        parentId = cls.resolve_scope_id_from_folder_path(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=params.get("parentId"),
+            folder_path=params.get("parentFolderPath"),
+        )
+        params.pop("folderPath", None)
+        params.pop("parentFolderPath", None)
+        if parentId:
+            params["parentId"] = parentId
+
+        return cast(
+            "Folder.FolderInfo",
+            cls._static_request(
+                "patch",
+                f"{cls.RESOURCE_URL}/{scopeId}",
+                user_id,
+                company_id=company_id,
+                params=params,
+            ),
+        )
+
+    @classmethod
+    async def update_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        **params: Unpack["Folder.UpdateParams"],
+    ) -> "Folder.FolderInfo":
+        """
+        Async update a folder given its id or path. Can update the name or the parent folder by specifying its id or path.
+        """
+
+        scopeId = cls.resolve_scope_id_from_folder_path(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=params.get("scopeId"),
+            folder_path=params.get("folderPath"),
+        )
+        parentId = cls.resolve_scope_id_from_folder_path(
+            user_id=user_id,
+            company_id=company_id,
+            scope_id=params.get("parentId"),
+            folder_path=params.get("parentFolderPath"),
+        )
+        params.pop("folderPath", None)
+        params.pop("parentFolderPath", None)
+        if parentId:
+            params["parentId"] = parentId
+
+        return cast(
+            "Folder.FolderInfo",
+            await cls._static_request_async(
+                "patch",
+                f"{cls.RESOURCE_URL}/{scopeId}",
+                user_id,
+                company_id=company_id,
+                params=params,
+            ),
+        )
+
     @classmethod
     def delete(
         cls,
@@ -473,6 +618,10 @@ class Folder(APIResource["Folder"]):
         """
         Returns the scopeId to use: if scope_id is provided, returns it;
         if not, but folder_path is provided, resolves and returns the id for that folder path.
+
+        Returns:
+            str: The resolved folder ID.
+            None: Failed to resolve a folder ID (e.g., folder_path not found or not provided).
         """
         if scope_id:
             return scope_id
@@ -489,3 +638,116 @@ class Folder(APIResource["Folder"]):
                 )
             return resolved_id
         return None
+
+    @classmethod
+    def resolve_scope_id_from_folder_path_with_create(
+        cls,
+        user_id: str,
+        company_id: str,
+        scope_id: str | None = None,
+        folder_path: str | None = None,
+        create_if_not_exists: bool = True,
+    ) -> str | None:
+        if scope_id:
+            return scope_id
+        if folder_path:
+            try:
+                folder_info = cls.get_info(
+                    user_id=user_id,
+                    company_id=company_id,
+                    folderPath=folder_path,
+                )
+                resolved_id = folder_info.get("id")
+                if resolved_id:
+                    return resolved_id
+            except Exception:
+                pass
+
+            if create_if_not_exists:
+                result = cls.create_paths(
+                    user_id=user_id,
+                    company_id=company_id,
+                    paths=[folder_path],
+                )
+                created_folders = result.get("createdFolders", [])
+                if created_folders:
+                    return created_folders[-1]["id"]
+                raise ValueError(
+                    f"Failed to create folder with folderPath: {folder_path}"
+                )
+
+            raise ValueError(f"Could not find a folder with folderPath: {folder_path}")
+        return None
+
+    @classmethod
+    async def resolve_scope_id_from_folder_path_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        scope_id: str | None = None,
+        folder_path: str | None = None,
+    ) -> str | None:
+        """
+        Async version of resolve_scope_id_from_folder_path.
+        Returns the scopeId to use: if scope_id is provided, returns it;
+        if not, but folder_path is provided, resolves and returns the id for that folder path.
+
+        Returns:
+            str: The resolved folder ID.
+            None: Failed to resolve a folder ID (e.g., folder_path not found or not provided).
+        """
+        if scope_id:
+            return scope_id
+        if folder_path:
+            folder_info = await cls.get_info_async(
+                user_id=user_id,
+                company_id=company_id,
+                folderPath=folder_path,
+            )
+            resolved_id = folder_info.get("id")
+            if not resolved_id:
+                raise ValueError(
+                    f"Could not find a folder with folderPath: {folder_path}"
+                )
+            return resolved_id
+        return None
+
+    @classmethod
+    async def resolve_scope_id_from_folder_path_with_create_async(
+        cls,
+        user_id: str,
+        company_id: str,
+        scope_id: str | None = None,
+        folder_path: str | None = None,
+        create_if_not_exists: bool = True,
+    ) -> str | None:
+        if scope_id:
+            return scope_id
+        if folder_path:
+            try:
+                folder_info = await cls.get_info_async(
+                    user_id=user_id,
+                    company_id=company_id,
+                    folderPath=folder_path,
+                )
+                resolved_id = folder_info.get("id")
+                if resolved_id:
+                    return resolved_id
+            except Exception:
+                pass
+
+            if create_if_not_exists:
+                result = await cls.create_paths_async(
+                    user_id=user_id,
+                    company_id=company_id,
+                    paths=[folder_path],
+                )
+                created_folders = result.get("createdFolders", [])
+                if created_folders:
+                    return created_folders[-1]["id"]
+                raise ValueError(
+                    f"Failed to create folder with folderPath: {folder_path}"
+                )
+
+            raise ValueError(f"Could not find a folder with folderPath: {folder_path}")
+        return None