sharing_folders.stone

namespace sharing

import async
import common
import files
import team_common
import users_common

alias DropboxId = String(min_length=1)

union AccessLevel
    "Defines the access levels for collaborators."

    owner
        "The collaborator is the owner of the shared folder. Owners can
        view and edit the shared folder as well as set the folder's
        policies using :route:`update_folder_policy`."
    editor
        "The collaborator can both view and edit the shared folder."
    viewer
        "The collaborator can only view the shared folder."
    viewer_no_comment
        "The collaborator can only view the shared folder and does
        not have any access to comments."
    traverse
        "The collaborator can only view the shared folder that they have
        access to."
    no_access
        "If there is a Righteous Link on the folder which grants access
        and the user has visited such link, they are allowed to perform
        certain action (i.e. add themselves to the folder) via the link
        access even though the user themselves are not a member on the
        shared folder yet."

struct FolderPolicy
    "A set of policies governing membership and privileges for a shared
    folder."

    member_policy MemberPolicy?
        "Who can be a member of this shared folder, as set on the folder itself.
        The effective policy may differ from this value if the team-wide policy
        is more restrictive. Present only if the folder is owned by a team."
    resolved_member_policy MemberPolicy?
        "Who can be a member of this shared folder, taking into account both the
        folder and the team-wide policy. This value may differ from that of
        member_policy if the team-wide policy is more restrictive than the folder
        policy. Present only if the folder is owned by a team."
    acl_update_policy AclUpdatePolicy
        "Who can add and remove members from this shared folder."
    shared_link_policy SharedLinkPolicy
        "Who links can be shared with."
    viewer_info_policy ViewerInfoPolicy?
        "Who can enable/disable viewer info for this shared folder."

    example default
        member_policy = anyone
        resolved_member_policy = team
        acl_update_policy = owner
        shared_link_policy = anyone

union FolderAction
    "Actions that may be taken on shared folders."

    change_options
        "Change folder options, such as who can be invited to join the folder."

    disable_viewer_info
        "Disable viewer information for this folder."

    edit_contents
        "Change or edit contents of the folder."

    enable_viewer_info
        "Enable viewer information on the folder."

    invite_editor
        "Invite a user or group to join the folder with read and write permission."

    invite_viewer
        "Invite a user or group to join the folder with read permission."

    invite_viewer_no_comment
        "Invite a user or group to join the folder with read permission but no comment permissions."

    relinquish_membership
        "Relinquish one's own membership in the folder."

    unmount
        "Unmount the folder."

    unshare
        "Stop sharing this folder."

    leave_a_copy
        "Keep a copy of the contents upon leaving or being kicked from the folder."

    share_link
        "Use create_link instead."

    create_link
        "Create a shared link for folder."

    set_access_inheritance
        "Set whether the folder inherits permissions from its parent."

struct FolderPermission
    "Whether the user is allowed to take the action on the shared folder."

    action FolderAction
        "The action that the user may wish to take on the folder."
    allow Boolean
        "True if the user is allowed to take the action."
    reason PermissionDeniedReason?
        "The reason why the user is denied the permission. Not present if the action
        is allowed, or if no reason is available."

    example default
        action = edit_contents
        allow = false
        reason = user_not_same_team_as_owner

union MemberPolicy
    "Policy governing who can be a member of a shared folder. Only applicable
    to folders owned by a user on a team."

    team
        "Only a teammate can become a member."
    anyone
        "Anyone can become a member."

union MemberAction
    "Actions that may be taken on members of a shared folder."

    leave_a_copy
        "Allow the member to keep a copy of the folder when removing."
    make_editor
        "Make the member an editor of the folder."
    make_owner
        "Make the member an owner of the folder."
    make_viewer
        "Make the member a viewer of the folder."
    make_viewer_no_comment
        "Make the member a viewer of the folder without commenting permissions."
    remove
        "Remove the member from the folder."

struct MemberPermission
    "Whether the user is allowed to take the action on the associated member."

    action MemberAction
        "The action that the user may wish to take on the member."
    allow Boolean
        "True if the user is allowed to take the action."
    reason PermissionDeniedReason?
        "The reason why the user is denied the permission. Not present if the action is allowed."

    example default
        action = make_owner
        allow = false
        reason = target_is_indirect_member

union PermissionDeniedReason
    "Possible reasons the user is denied a permission."

    user_not_same_team_as_owner
        "User is not on the same team as the folder owner."
    user_not_allowed_by_owner
        "User is prohibited by the owner from taking the action."
    target_is_indirect_member
        "Target is indirectly a member of the folder, for example by being part of a group."
    target_is_owner
        "Target is the owner of the folder."
    target_is_self
        "Target is the user itself."
    target_not_active
        "Target is not an active member of the team."
    folder_is_limited_team_folder
        "Folder is team folder for a limited team."
    owner_not_on_team
        "The content owner needs to be on a Dropbox team to perform this action."
    permission_denied
        "The user does not have permission to perform this action on the link."
    restricted_by_team
        "The user's team policy prevents performing this action on the link."
    user_account_type
        "The user's account type does not support this action."
    user_not_on_team
        "The user needs to be on a Dropbox team to perform this action."
    folder_is_inside_shared_folder
        "Folder is inside of another shared folder."
    restricted_by_parent_folder
        "Policy cannot be changed due to restrictions from parent folder."
    insufficient_plan InsufficientPlan

struct InsufficientPlan
    message String
        "A message to tell the user to upgrade in order to support expected action."
    upsell_url String?
        "A URL to send the user to in order to obtain the account type they need, e.g. upgrading.
        Absent if there is no action the user can take to upgrade."

union AclUpdatePolicy
    "Who can change a shared folder's access control list (ACL). In other words, who can add,
    remove, or change the privileges of members."

    owner
        "Only the owner can update the ACL."
    editors
        "Any editor can update the ACL. This may be further restricted to
        editors on the same team."

union SharedLinkPolicy
    "Who can view shared links in this folder."

    anyone
        "Links can be shared with anyone."
    team
        "Links can be shared with anyone on the same team as the owner."
    members
        "Links can only be shared among members of the shared folder."

struct MembershipInfo
    "The information about a member of the shared content."

    access_type AccessLevel
        "The access type for this member. It contains inherited access type from parent folder,
        and acquired access type from this folder."
    permissions List(MemberPermission)?
        "The permissions that requesting user has on this member. The set of
        permissions corresponds to the MemberActions in the request."
    initials String?
        "Never set."
    is_inherited Boolean = false
        "True if the member has access from a parent folder."

    example default
        access_type = owner
        permissions = []
        initials = "JD"
        is_inherited = false

struct UserInfo
    "Basic information about a user. Use :route:`users.get_account` and
    :route:`users.get_account_batch` to obtain more detailed information."

    account_id users_common.AccountId
        "The account ID of the user."
    email String
        "Email address of user."
    display_name String
        "The display name of the user."
    same_team Boolean
        "If the user is in the same team as current user."
    team_member_id String?
        "The team member ID of the shared folder member. Only present if
        :field:`same_team` is true."

    example default
        account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        same_team = true
        team_member_id = "dbmid:abcd1234"
        email = "bob@example.com"
        display_name = "Robert Smith"

struct UserMembershipInfo extends MembershipInfo
    "The information about a user member of the shared content."

    user UserInfo
        "The account information for the membership user."

    example default
        user = default
        access_type = owner
        permissions = []

union InviteeInfo
    "Information about the recipient of a shared content invitation."

    email common.EmailAddress
        "Email address of invited user."

    example default
        email = "jessica@example.com"

struct InviteeMembershipInfo extends MembershipInfo
    "Information about an invited member of a shared content."

    invitee InviteeInfo
        "Recipient of the invitation."
    user UserInfo?
        "The user this invitation is tied to, if available."

    example default
        invitee = default
        access_type = viewer
        permissions = []

struct GroupInfo extends team_common.GroupSummary
    "The information about a group. Groups is a way to manage a list of users
     who need same access permission to the shared folder."

    group_type team_common.GroupType
        "The type of group."
    is_member Boolean
        "If the current user is a member of the group."
    is_owner Boolean
        "If the current user is an owner of the group."
    same_team Boolean
        "If the group is owned by the current user's team."

    example default
        group_name = "Test group"
        group_id = "g:e2db7665347abcd600000000001a2b3c"
        member_count = 10
        group_management_type = user_managed
        group_type = user_managed
        is_member = false
        is_owner = false
        same_team = true

struct GroupMembershipInfo extends MembershipInfo
    "The information about a group member of the shared content."

    group GroupInfo
        "The information about the membership group."

    example default
        group = default
        access_type = editor
        permissions = []

struct SharedFolderMetadataBase
    "Properties of the shared folder."

    access_type AccessLevel
        "The current user's access level for this shared folder."

    is_inside_team_folder Boolean
        "Whether this folder is inside of a team folder."

    is_team_folder Boolean
        "Whether this folder is a
        :link:`team folder https://www.dropbox.com/en/help/986`."

    owner_display_names List(String)?
        "The display names of the users that own the folder. If the folder is
        part of a team folder, the display names of the team admins are also
        included. Absent if the owner display names cannot be fetched."

    owner_team users.Team?
        "The team that owns the folder. This field is not present if the folder
        is not owned by a team."

    parent_shared_folder_id common.SharedFolderId?
        "The ID of the parent shared folder. This field is present only if the
        folder is contained within another shared folder."

    path_display String?
        "The full path of this shared folder. Absent for unmounted folders."

    path_lower String?
        "The lower-cased full path of this shared folder. Absent for unmounted folders."

    parent_folder_name String?
        "Display name for the parent folder."

    example default
        access_type = owner
        is_inside_team_folder = false
        is_team_folder = false
        owner_display_names = ["Jane Doe"]
        owner_team = default
        parent_folder_name = "Parent Shared Folder"

union AccessInheritance
    "Information about the inheritance policy of a shared folder."

    inherit
        "The shared folder inherits its members from the parent folder."

    no_inherit
        "The shared folder does not inherit its members from the parent folder."

# NOTE: If you modify this struct, also modify InternalSharedFolderMetadata,
# which is used by mobile
struct SharedFolderMetadata extends SharedFolderMetadataBase
    "The metadata which includes basic information about the shared folder."

    link_metadata SharedContentLinkMetadata?
        "The metadata of the shared content link to this shared folder. Absent if there is no
        link on the folder. This is for an unreleased feature so it may not be returned yet."

    name String
        "The name of the this shared folder."

    permissions List(FolderPermission)?
        "Actions the current user may perform on the folder and its contents.
        The set of permissions corresponds to the FolderActions in the request."

    policy FolderPolicy
        "Policies governing this shared folder."

    preview_url String
        "URL for displaying a web preview of the shared folder."

    shared_folder_id common.SharedFolderId
        "The ID of the shared folder."

    time_invited common.DropboxTimestamp
        "Timestamp indicating when the current user was invited to this shared folder."

    access_inheritance AccessInheritance = inherit
        "Whether the folder inherits its members from its parent."

    example default
        path_lower = "/dir"
        link_metadata = default
        name = "dir"
        shared_folder_id = "84528192421"
        permissions = []
        access_type = owner
        is_inside_team_folder = false
        is_team_folder = false
        policy = default
        time_invited = "2016-01-20T00:00:00Z"
        preview_url = "https://www.dropbox.com/scl/fo/fir9vjelf"
        access_inheritance = inherit

union SharedFolderAccessError
    "There is an error accessing the shared folder."

    invalid_id
        "This shared folder ID is invalid."
    not_a_member
        "The user is not a member of the shared folder
        thus cannot access it."
    invalid_member
        "The user does not exist or their account is disabled."
    email_unverified
        "Never set."
    unmounted
        "The shared folder is unmounted."

struct MemberAccessLevelResult
    "Contains information about a member's access level to content after an operation."
    access_level AccessLevel?
        "The member still has this level of access to the content through a parent folder."
    warning String?
        "A localized string with additional information about why the user
        has this access level to the content."
    access_details List(ParentFolderAccessInfo)?
        "The parent folders that a member has access to. The field is present if the user
        has access to the first parent folder where the member gains access."

    example default

struct ParentFolderAccessInfo
    "Contains information about a parent folder that a member has access to."

    folder_name String
        "Display name for the folder."

    shared_folder_id common.SharedFolderId
        "The identifier of the parent shared folder."

    permissions List(MemberPermission)
        "The user's permissions for the parent shared folder."

    path String
        "The full path to the parent shared folder relative to the acting user's root."

    example default
        folder_name = "Shared Folder"
        shared_folder_id = "84528192421"
        permissions = []
        path = "/Shared Folder"

# --

route list_folders(ListFoldersArgs, ListFoldersResult, Void)
    "Return the list of all shared folders the current user has access to."

    attrs
        scope = "sharing.read"

struct ListFoldersArgs
    limit UInt32(min_value=1, max_value=1000) = 1000
        "The maximum number of results to return per request."
    actions List(FolderAction)?
        "A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
         response's :field:`SharedFolderMetadata.permissions` field describing the actions the
         authenticated user can perform on the folder."

    example default
        limit = 100
        actions = []

struct ListFoldersResult
    "Result for :route:`list_folders` or :route:`list_mountable_folders`, depending on which
    endpoint was requested.

    Unmounted shared folders can be identified by the absence of
    :field:`SharedFolderMetadata.path_lower`."

    entries List(SharedFolderMetadata)
        "List of all shared folders the authenticated user has access to."
    cursor String?
        "Present if there are additional shared folders that have not been returned yet. Pass the
        cursor into the corresponding continue endpoint (either :route:`list_folders/continue`
        or :route:`list_mountable_folders/continue`) to list additional folders."

    example default
        entries = [default]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

# --

route list_folders/continue(ListFoldersContinueArg, ListFoldersResult, ListFoldersContinueError)
    "Once a cursor has been retrieved from :route:`list_folders`, use this to paginate through all
    shared folders. The cursor must come from a previous call to :route:`list_folders` or
    :route:`list_folders/continue`."

    attrs
        scope = "sharing.read"

struct ListFoldersContinueArg
    cursor String
        "The cursor returned by the previous API call specified in the endpoint description."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

union ListFoldersContinueError
    invalid_cursor
        ":field:`ListFoldersContinueArg.cursor` is invalid."

# --

route list_mountable_folders(ListFoldersArgs, ListFoldersResult, Void)
    "Return the list of all shared folders the current user can mount or unmount."

    attrs
        scope = "sharing.read"

# --

route list_mountable_folders/continue(ListFoldersContinueArg, ListFoldersResult, ListFoldersContinueError)
    "Once a cursor has been retrieved from :route:`list_mountable_folders`, use this to paginate through all
    mountable shared folders. The cursor must come from a previous call to :route:`list_mountable_folders` or
    :route:`list_mountable_folders/continue`."

    attrs
        scope = "sharing.read"

# --

route get_folder_metadata(GetMetadataArgs, SharedFolderMetadata, SharedFolderAccessError)
    "Returns shared folder metadata by its folder ID."

    attrs
        select_admin_mode = "whole_team"
        scope = "sharing.read"

struct GetMetadataArgs
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."
    actions List(FolderAction)?
        "A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
         response's :field:`SharedFolderMetadata.permissions` field describing the actions the
         authenticated user can perform on the folder."

    example default
        shared_folder_id = "84528192421"
        actions = []

# --

route list_folder_members(ListFolderMembersArgs, SharedFolderMembers, SharedFolderAccessError)
    "Returns shared folder membership by its folder ID."

    attrs
        select_admin_mode = "whole_team"
        scope = "sharing.read"

struct ListFolderMembersCursorArg
    actions List(MemberAction)?
        "This is a list indicating whether each returned member will include a boolean value
        :field:`MemberPermission.allow` that describes whether the current user can perform
        the MemberAction on the member."

    limit UInt32(min_value=1, max_value=1000) = 1000
        "The maximum number of results that include members, groups and invitees to return per request."

    example default
        actions = []
        limit = 10

struct ListFolderMembersArgs extends ListFolderMembersCursorArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."

    example default
        shared_folder_id = "84528192421"
        actions = []
        limit = 10

struct SharedFolderMembers
    "Shared folder user and group membership."

    users List(UserMembershipInfo)
        "The list of user members of the shared folder."
    groups List(GroupMembershipInfo)
        "The list of group members of the shared folder."
    invitees List(InviteeMembershipInfo)
        "The list of invitees to the shared folder."
    cursor String?
        "Present if there are additional shared folder members that have not been returned yet. Pass
        the cursor into :route:`list_folder_members/continue` to list additional members."

    example default
        users = [default]
        groups = [default]
        invitees = [default]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

# --

route list_folder_members/continue(ListFolderMembersContinueArg, SharedFolderMembers, ListFolderMembersContinueError)
    "Once a cursor has been retrieved from :route:`list_folder_members`, use this to paginate
    through all shared folder members."

    attrs
        select_admin_mode = "whole_team"
        scope = "sharing.read"

struct ListFolderMembersContinueArg
    cursor String
        "The cursor returned by your last call to :route:`list_folder_members` or
        :route:`list_folder_members/continue`."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

union ListFolderMembersContinueError
    access_error SharedFolderAccessError
    invalid_cursor
        ":field:`ListFolderMembersContinueArg.cursor` is invalid."

# --

route share_folder(ShareFolderArg, ShareFolderLaunch, ShareFolderError )
    "Share a folder with collaborators.

    Most sharing will be completed synchronously. Large folders will be
    completed asynchronously. To make testing the async case repeatable, set
    `ShareFolderArg.force_async`.

    If a :field:`ShareFolderLaunch.async_job_id` is returned, you'll need to
    call :route:`check_share_job_status` until the action completes to get the
    metadata for the folder."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

# As of 2017-05, there are three kinds of arg:
# ShareFolderArg: The public stable version. We cannot make backwards-incompatible changes at all.
# ShareFolderInternalArg: The private stable version. We cannot make backwards-incompatible changes
#   unless we are sure no clients in the wild are using the endpoint.
# AlphaShareFolderArg: The private experimental version. We can do what we want as long as it
#   doesn't break web.
struct ShareFolderArgBase
    acl_update_policy AclUpdatePolicy?
        "Who can add and remove members of this shared folder."
    force_async Boolean = false
        "Whether to force the share to happen asynchronously."
    member_policy MemberPolicy?
        "Who can be a member of this shared folder. Only applicable if the
        current user is on a team."
    path files.WritePathOrId
        "The path or the file id to the folder to share. If it does not exist,
        then a new one is created."
    shared_link_policy SharedLinkPolicy?
        "The policy to apply to shared links created for content inside this
        shared folder.  The current user must be on a team to set this policy to
        :field:`SharedLinkPolicy.members`."
    viewer_info_policy ViewerInfoPolicy?
        "Who can enable/disable viewer info for this shared folder."
    access_inheritance AccessInheritance = inherit
        "The access inheritance settings for the folder."

    example default
        path = "/example/workspace"

struct ShareFolderArg extends ShareFolderArgBase
    actions List(FolderAction)?
        "A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
         response's :field:`SharedFolderMetadata.permissions` field describing the actions the
         authenticated user can perform on the folder."
    link_settings LinkSettings?
        "Settings on the link for this folder."

    example default
        path = "/example/workspace"
        member_policy = team
        acl_update_policy = editors
        shared_link_policy = members

union ShareFolderErrorBase
    email_unverified
        "This user's email address is not verified. This functionality is only
        available on accounts with a verified email address. Users can verify
        their email address :link:`here https://www.dropbox.com/help/317`."
    bad_path SharePathError
        ":field:`ShareFolderArg.path` is invalid."
    team_policy_disallows_member_policy
        "Team policy is more restrictive than :field:`ShareFolderArg.member_policy`."
    disallowed_shared_link_policy
        "The current user's account is not allowed to select the specified
        :field:`ShareFolderArg.shared_link_policy`."

union ShareFolderError extends ShareFolderErrorBase
    no_permission
        "The current user does not have permission to perform this action."

union SharePathError
    is_file
        "A file is at the specified path."
    inside_shared_folder
        "We do not support sharing a folder inside a shared folder."
    contains_shared_folder
        "We do not support shared folders that contain shared folders."
    contains_app_folder
        "We do not support shared folders that contain app folders."
    contains_team_folder
        "We do not support shared folders that contain team folders."
    is_app_folder
        "We do not support sharing an app folder."
    inside_app_folder
        "We do not support sharing a folder inside an app folder."
    is_public_folder
        "A public folder can't be shared this way. Use a public link instead."
    inside_public_folder
        "A folder inside a public folder can't be shared this way. Use a public
        link instead."
    already_shared SharedFolderMetadata
        "Folder is already shared. Contains metadata about the existing shared folder."
    invalid_path
        "Path is not valid."
    is_osx_package
        "We do not support sharing a Mac OS X package."
    inside_osx_package
        "We do not support sharing a folder inside a Mac OS X package."
    is_vault
        "We do not support sharing the Vault folder."
    is_vault_locked
        "We do not support sharing a folder inside a locked Vault."
    is_family
        "We do not support sharing the Family folder."

# --

union_closed ShareFolderJobStatus extends async.PollResultBase
    complete SharedFolderMetadata
        "The share job has finished. The value is the metadata for the folder."
    failed ShareFolderError

    example default
        complete = default

union_closed ShareFolderLaunch extends async.LaunchResultBase
    complete SharedFolderMetadata

    example default
        complete = default

route check_share_job_status(async.PollArg, ShareFolderJobStatus, async.PollError)
    "Returns the status of an asynchronous job for sharing a folder."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

union_closed JobStatus extends async.PollResultBase
    complete
        "The asynchronous job has finished."
    failed JobError
        "The asynchronous job returned an error."

# --

union SharedFolderMemberError
    invalid_dropbox_id
        "The target dropbox_id is invalid."
    not_a_member
        "The target dropbox_id is not a member of the shared folder."
    no_explicit_access MemberAccessLevelResult
        "The target member only has inherited access to the shared folder."

union JobError
    "Error occurred while performing an asynchronous job from :route:`unshare_folder`
    or :route:`remove_folder_member`."

    unshare_folder_error UnshareFolderError
        "Error occurred while performing :route:`unshare_folder` action."
    remove_folder_member_error RemoveFolderMemberError
        "Error occurred while performing :route:`remove_folder_member` action."
    relinquish_folder_membership_error RelinquishFolderMembershipError
        "Error occurred while performing :route:`relinquish_folder_membership` action."

route check_job_status(async.PollArg, JobStatus, async.PollError)
    "Returns the status of an asynchronous job."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

# --

route unshare_folder(UnshareFolderArg, async.LaunchEmptyResult, UnshareFolderError)
    "Allows a shared folder owner to unshare the folder.

    You'll need to call :route:`check_job_status` to determine if the action has
    completed successfully."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct UnshareFolderArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."
    leave_a_copy Boolean = false
        "If true, members of this shared folder will get a copy of this folder
        after it's unshared. Otherwise, it will be removed from their Dropbox.
        The current user, who is an owner, will always retain their copy."

    example default
        shared_folder_id = "84528192421"
        leave_a_copy = false

union UnshareFolderError
    access_error SharedFolderAccessError
    team_folder
        "This action cannot be performed on a team shared folder."
    no_permission
        "The current user does not have permission to perform this action."
    too_many_files
        "This shared folder has too many files to be unshared."

# --

route transfer_folder(TransferFolderArg, Void, TransferFolderError)
    "Transfer ownership of a shared folder to a member of the shared folder.

    User must have :field:`AccessLevel.owner` access to the shared folder to perform a transfer."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct TransferFolderArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."
    to_dropbox_id DropboxId
        "A account or team member ID to transfer ownership to."

    example default
        shared_folder_id = "84528192421"
        to_dropbox_id = "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"

union TransferFolderError
    access_error SharedFolderAccessError
    invalid_dropbox_id
        ":field:`TransferFolderArg.to_dropbox_id` is invalid."
    new_owner_not_a_member
        "The new designated owner is not currently a member of the shared folder."
    new_owner_unmounted
        "The new designated owner has not added the folder to their Dropbox."
    new_owner_email_unverified
        "The new designated owner's email address is not verified. This functionality
        is only available on accounts with a verified email address. Users can verify
        their email address :link:`here https://www.dropbox.com/help/317`."
    team_folder
        "This action cannot be performed on a team shared folder."
    no_permission
        "The current user does not have permission to perform this action."

# --

route update_folder_policy(UpdateFolderPolicyArg, SharedFolderMetadata, UpdateFolderPolicyError)
    "Update the sharing policies for a shared folder.

    User must have :field:`AccessLevel.owner` access to the shared folder to update its policies."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct UpdateFolderPolicyArg
    "If any of the policies are unset, then they retain their current setting."

    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."
    member_policy MemberPolicy?
        "Who can be a member of this shared folder. Only applicable if the
        current user is on a team."
    acl_update_policy AclUpdatePolicy?
        "Who can add and remove members of this shared folder."
    viewer_info_policy ViewerInfoPolicy?
        "Who can enable/disable viewer info for this shared folder."
    shared_link_policy SharedLinkPolicy?
        "The policy to apply to shared links created for content inside this
        shared folder. The current user must be on a team to set this policy to
        :field:`SharedLinkPolicy.members`."
    link_settings LinkSettings?
        "Settings on the link for this folder."
    actions List(FolderAction)?
        "A list of `FolderAction`s corresponding to `FolderPermission`s that should appear in the
         response's :field:`SharedFolderMetadata.permissions` field describing the actions the
         authenticated user can perform on the folder."
    example default
        shared_folder_id = "84528192421"
        member_policy = team
        acl_update_policy = owner
        shared_link_policy = members

union UpdateFolderPolicyError
    access_error SharedFolderAccessError
    not_on_team
        ":field:`UpdateFolderPolicyArg.member_policy` was set even though user
        is not on a team."
    team_policy_disallows_member_policy
        "Team policy is more restrictive than :field:`ShareFolderArg.member_policy`."
    disallowed_shared_link_policy
        "The current account is not allowed to select the specified
        :field:`ShareFolderArg.shared_link_policy`."
    no_permission
        "The current user does not have permission to perform this action."
    team_folder
        "This action cannot be performed on a team shared folder."

# --

route add_folder_member(AddFolderMemberArg, Void, AddFolderMemberError)
    "Allows an owner or editor (if the ACL update policy allows) of a shared
    folder to add another member.

    For the new member to get access to all the functionality for this folder,
    you will need to call :route:`mount_folder` on their behalf."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct AddFolderMemberArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."

    members List(AddMember)
        "The intended list of members to add.  Added members will receive
        invites to join the shared folder."

    quiet Boolean = false
        "Whether added members should be notified via email and device
        notifications of their invite."

    custom_message String(min_length=1)?
        "Optional message to display to added members in their invitation."

    example default
        members = [default, account]
        shared_folder_id = "84528192421"
        custom_message = "Documentation for launch day"

struct AddMember
    "The member and type of access the member should have when added to a shared folder."

    member MemberSelector
        "The member to add to the shared folder."
    access_level AccessLevel = viewer
        "The access level to grant :field:`member` to the shared folder.  :field:`AccessLevel.owner`
        is disallowed."

    example default
        member = default
        access_level = editor

    example account
        member = account
        access_level = viewer

union MemberSelector
    "Includes different ways to identify a member of a shared folder."

    dropbox_id DropboxId
        "Dropbox account, team member, or group ID of member."
    email common.EmailAddress
        "Email address of member."

    example default
        email = "justin@example.com"

    example account
        dropbox_id = "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"

    example group
        dropbox_id = "g:98d36ed08e6290c2e9d536a392f974ee"

union AddFolderMemberError
    access_error SharedFolderAccessError
        "Unable to access shared folder."
    email_unverified
        "This user's email address is not verified. This functionality is only
        available on accounts with a verified email address. Users can verify
        their email address :link:`here https://www.dropbox.com/help/317`."
    banned_member
        "The current user has been banned."
    bad_member AddMemberSelectorError
        ":field:`AddFolderMemberArg.members` contains a bad invitation recipient."
    cant_share_outside_team
        "Your team policy does not allow sharing outside of the team."
    too_many_members UInt64
        "The value is the member limit that was reached."
    too_many_pending_invites UInt64
        "The value is the pending invite limit that was reached."
    rate_limit
        "The current user has hit the limit of invites they can send per day. Try again in 24 hours."
    too_many_invitees
        "The current user is trying to share with too many people at once."
    insufficient_plan
        "The current user's account doesn't support this action. An example of
        this is when adding a read-only member. This action can only be
        performed by users that have upgraded to a Pro or Business plan."
    team_folder
        "This action cannot be performed on a team shared folder."
    no_permission
        "The current user does not have permission to perform this action."
    invalid_shared_folder
        "Invalid shared folder error will be returned as an access_error."

    example default
        no_permission = null

    example member
        bad_member = default

union AddMemberSelectorError
    automatic_group
        "Automatically created groups can only be added to team folders."
    invalid_dropbox_id DropboxId
        "The value is the ID that could not be identified."
    invalid_email common.EmailAddress
        "The value is the e-email address that is malformed."
    unverified_dropbox_id DropboxId
        "The value is the ID of the Dropbox user with an unverified email
        address. Invite unverified users by email address instead of by their
        Dropbox ID."
    group_deleted
        "At least one of the specified groups in :field:`AddFolderMemberArg.members`
        is deleted."
    group_not_on_team
        "Sharing to a group that is not on the current user's team."

    example default
        invalid_dropbox_id = "dbid:AAEufNrMPSPe0dMQijRP0N_aZtBJRm26W4Q"

# --

route remove_folder_member(RemoveFolderMemberArg, async.LaunchResultBase, RemoveFolderMemberError)
    "Allows an owner or editor (if the ACL update policy allows) of a shared
    folder to remove another member."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct RemoveFolderMemberArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."
    member MemberSelector
        "The member to remove from the folder."
    leave_a_copy Boolean
        "If true, the removed user will keep their copy of the folder after
        it's unshared, assuming it was mounted. Otherwise, it will be removed
        from their Dropbox. This must be set to false when removing a group,
        or when the folder is within a team folder or another shared folder."

    example default
        shared_folder_id = "84528192421"
        member = default
        leave_a_copy = false

union RemoveFolderMemberError
    access_error SharedFolderAccessError
    member_error SharedFolderMemberError
    folder_owner
        "The target user is the owner of the shared folder. You can't remove
        this user until ownership has been transferred to another member."
    group_access
        "The target user has access to the shared folder via a group."
    team_folder
        "This action cannot be performed on a team shared folder."
    no_permission
        "The current user does not have permission to perform this action."
    too_many_files
        "This shared folder has too many files for leaving a copy. You can
        still remove this user without leaving a copy."

union_closed RemoveMemberJobStatus extends async.PollResultBase
    complete MemberAccessLevelResult
        "Removing the folder member has finished. The value is information about
        whether the member has another form of access."
    failed RemoveFolderMemberError

    example default
        complete = default

route check_remove_member_job_status(async.PollArg, RemoveMemberJobStatus, async.PollError)
    "Returns the status of an asynchronous job for sharing a folder."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

# --

route update_folder_member(UpdateFolderMemberArg, MemberAccessLevelResult, UpdateFolderMemberError)
    "Allows an owner or editor of a shared folder to update another member's
    permissions."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct UpdateFolderMemberArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."
    member MemberSelector
        "The member of the shared folder to update.  Only the
        :field:`MemberSelector.dropbox_id` may be set at this time."
    access_level AccessLevel
        "The new access level for :field:`member`. :field:`AccessLevel.owner`
        is disallowed."

    example default
        shared_folder_id = "84528192421"
        member = default
        access_level = editor

union UpdateFolderMemberError
    access_error SharedFolderAccessError
    member_error SharedFolderMemberError
    no_explicit_access AddFolderMemberError
        "If updating the access type required the member to be added to the shared folder
        and there was an error when adding the member."
    insufficient_plan
        "The current user's account doesn't support this action. An example of
        this is when downgrading a member from editor to viewer. This action
        can only be performed by users that have upgraded to a Pro or Business
        plan."
    no_permission
        "The current user does not have permission to perform this action."

# --

route mount_folder(MountFolderArg, SharedFolderMetadata, MountFolderError)
    "The current user mounts the designated folder.

    Mount a shared folder for a user after they have been added as a member.
    Once mounted, the shared folder will appear in their Dropbox."

    attrs
        scope = "sharing.write"

# TODO(kelkabany): Consider exposing mount path as an argument. More error
# cases will be possible.
struct MountFolderArg
    shared_folder_id common.SharedFolderId
        "The ID of the shared folder to mount."

    example default
        shared_folder_id = "84528192421"

struct InsufficientQuotaAmounts
    space_needed UInt64
        "The amount of space needed to add the item (the size of the item)."
    space_shortage UInt64
        "The amount of extra space needed to add the item."
    space_left UInt64
        "The amount of space left in the user's Dropbox, less than space_needed."

union MountFolderError
    access_error SharedFolderAccessError
    inside_shared_folder
        "Mounting would cause a shared folder to be inside another, which is
        disallowed."
    insufficient_quota InsufficientQuotaAmounts
        "The current user does not have enough space to mount the shared
        folder."
    already_mounted
        "The shared folder is already mounted."
    no_permission
        "The current user does not have permission to perform this action."
    not_mountable
        "The shared folder is not mountable. One example where this can occur
        is when the shared folder belongs within a team folder in the user's
        Dropbox."

# --

route unmount_folder(UnmountFolderArg, Void, UnmountFolderError)
    "The current user unmounts the designated folder. They can re-mount the
    folder at a later time using :route:`mount_folder`."

    attrs
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct UnmountFolderArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."

    example default
        shared_folder_id = "84528192421"

union UnmountFolderError
    access_error SharedFolderAccessError
    no_permission
        "The current user does not have permission to perform this action."
    not_unmountable
        "The shared folder can't be unmounted. One example where this can occur
        is when the shared folder's parent folder is also a shared folder that
        resides in the current user's Dropbox."

# --

route relinquish_folder_membership(RelinquishFolderMembershipArg, async.LaunchEmptyResult, RelinquishFolderMembershipError)
    "The current user relinquishes their membership in the designated shared
    folder and will no longer have access to the folder.  A folder owner cannot
    relinquish membership in their own folder.

    This will run synchronously if leave_a_copy is false, and asynchronously
    if leave_a_copy is true."

    attrs
        scope = "sharing.write"

struct RelinquishFolderMembershipArg
    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."
    leave_a_copy Boolean = false
        "Keep a copy of the folder's contents upon relinquishing membership.
        This must be set to false when the folder is within a team folder
        or another shared folder."

    example default
        shared_folder_id = "84528192421"
        leave_a_copy = false

union RelinquishFolderMembershipError
    access_error SharedFolderAccessError
    folder_owner
        "The current user is the owner of the shared folder. Owners cannot relinquish membership to
        their own folders. Try unsharing or transferring ownership first."
    mounted
        "The shared folder is currently mounted.  Unmount the shared folder before relinquishing
        membership."
    group_access
        "The current user has access to the shared folder via a group.  You can't relinquish
        membership to folders shared via groups."
    team_folder
        "This action cannot be performed on a team shared folder."
    no_permission
        "The current user does not have permission to perform this action."
    no_explicit_access
        "The current user only has inherited access to the shared folder.  You can't relinquish
        inherited membership to folders."

# --

route set_access_inheritance (SetAccessInheritanceArg, ShareFolderLaunch, SetAccessInheritanceError)
    "Change the inheritance policy of an existing Shared Folder. Only permitted for shared folders in a shared team root.

    If a :field:`ShareFolderLaunch.async_job_id` is returned, you'll need to
    call :route:`check_share_job_status` until the action completes to get the
    metadata for the folder."

    attrs
        scope = "sharing.write"

struct SetAccessInheritanceArg
    access_inheritance AccessInheritance = inherit
        "The access inheritance settings for the folder."

    shared_folder_id common.SharedFolderId
        "The ID for the shared folder."

    example default
        access_inheritance = inherit
        shared_folder_id = "84528192421"

union SetAccessInheritanceError
    access_error SharedFolderAccessError
        "Unable to access shared folder."
    no_permission
        "The current user does not have permission to perform this action."

    example default
        no_permission = null