sharing_files.stone

namespace sharing

import common
import files
import users
import seen_state

alias PathOrId = String(pattern="((\/|id:).*|nspath:[0-9]+:.*)|ns:[0-9]+(/.*)?", min_length=1)

###########################################
# Generic route error related definitions #
###########################################

union SharingUserError
    "User account had a problem preventing this action."
    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`."

union SharingFileAccessError
    "User could not access this file."

    no_permission
        "Current user does not have sufficient privileges to perform the desired action."
    invalid_file
        "File specified was not found."
    is_folder
        "A folder can't be shared this way. Use folder sharing or a shared link instead."
    inside_public_folder
        "A file inside a public folder can't be shared this way. Use a public link instead."
    inside_osx_package
        "A Mac OS X package can't be shared this way. Use a shared link instead."


union FileErrorResult
    file_not_found_error files.Id
        "File specified by id was not found."
    invalid_file_action_error files.Id
        "User does not have permission to take the specified action on the file."
    permission_denied_error files.Id
        "User does not have permission to access file specified by file.Id."

#############################################
# File metadata and permissions definitions #
#############################################

union FileAction
    "Sharing actions that may be taken on files."

    disable_viewer_info
        "Disable viewer information on the file."

    edit_contents
        "Change or edit contents of the file."

    enable_viewer_info
        "Enable viewer information on the file."

    invite_viewer
        "Add a member with view permissions."

    invite_viewer_no_comment
        "Add a member with view permissions but no comment permissions."

    invite_editor
        "Add a member with edit permissions."

    unshare
        "Stop sharing this file."

    relinquish_membership
        "Relinquish one's own membership to the file."

    share_link
        "Use create_view_link and create_edit_link instead."

    create_link
        "Use create_view_link and create_edit_link instead."

    create_view_link
        "Create a shared link to a file that only allows users to view the content."

    create_edit_link
        "Create a shared link to a file that allows users to edit the content."

    example default
        edit_contents = null

struct FilePermission
    "Whether the user is allowed to take the sharing action on the file."

    action FileAction
        "The action that the user may wish to take on the file."
    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 = edit_contents
        allow = false
        reason = user_not_same_team_as_owner

struct SharedFileMetadata
    "Properties of the shared file."

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

    id files.FileId
        "The ID of the file."

    expected_link_metadata ExpectedSharedContentLinkMetadata?
        "The expected metadata of the link associated for the file when it is first shared.
        Absent if the link already exists. This is for an unreleased feature so it may not be
        returned yet."

    link_metadata SharedContentLinkMetadata?
        "The metadata of the link associated for the file. This is for an unreleased feature so
        it may not be returned yet."

    name String
        "The name of this file."

    owner_display_names List(String)?
        "The display names of the users that own the file. If the file 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 file. This field is not present if the file
        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
        file is contained within a shared folder."

    path_display String?
        "The cased path to be used for display purposes only. In rare instances
        the casing will not correctly match the user's filesystem, but this
        behavior will match the path provided in the Core API v1.
        Absent for unmounted files."

    path_lower String?
        "The lower-case full path of this file. Absent for unmounted files."

    permissions List(FilePermission)?
        "The sharing permissions that requesting user has on this file. This
        corresponds to the entries given in :field:`GetFileMetadataBatchArg.actions`
        or :field:`GetFileMetadataArg.actions`."

    policy FolderPolicy
        "Policies governing this shared file."

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

    time_invited common.DropboxTimestamp?
        "Timestamp indicating when the current user was invited to this shared file. If the user was
        not invited to the shared file, the timestamp will indicate when the user was invited to the
        parent shared folder. This value may be absent."


    example default
        policy = default
        permissions = []
        owner_display_names = ["Jane Doe"]
        owner_team = default
        preview_url = "https://www.dropbox.com/scl/fi/fir9vjelf"
        path_lower = "/dir/file.txt"
        path_display = "/dir/file.txt"
        name = "file.txt"
        id = "id:3kmLmQFnf1AAAAAAAAAAAw"
        time_invited = "2016-01-20T00:00:00Z"
        access_type = viewer

union ViewerInfoPolicy
    enabled
        "Viewer information is available on this file."
    disabled
        "Viewer information is disabled on this file."

##################################
# File membership mutation types #
##################################

struct FileMemberActionResult
    "Per-member result for :route:`add_file_member`."

    member MemberSelector
        "One of specified input members."
    result FileMemberActionIndividualResult
        "The outcome of the action on this member."
    sckey_sha1 String?
        "The SHA-1 encrypted shared content key."
    invitation_signature List(String)?
        "The sharing sender-recipient invitation signatures for the input member_id.
        A member_id can be a group and thus have multiple users and multiple invitation signatures."

    example default
        member = default
        result = default
        sckey_sha1 = "32gggb672f987b2d94ef1741616bdf37d565e8c1"
        invitation_signature = ["32gggb672f987b2d94ef1741616bdf37d565e8c1:c1ce0a9ef6ggg65e6e2f43514082ea5ffefd9cf5"]

union_closed FileMemberActionIndividualResult
    success AccessLevel?
        "Part of the response for both add_file_member and remove_file_member_v1 (deprecated).
        For add_file_member, indicates giving access was successful and at what AccessLevel.
        For remove_file_member_v1, indicates member was successfully removed from the file. If AccessLevel is given,
        the member still has access via a parent shared folder."
    member_error FileMemberActionError
        "User was not able to perform this action."

    example default
        success = null

union FileMemberRemoveActionResult
    success MemberAccessLevelResult
        "Member was successfully removed from this file."
    member_error FileMemberActionError
        "User was not able to remove this member."

union AddFileMemberError
    "Errors for :route:`add_file_member`."
    user_error SharingUserError
    access_error SharingFileAccessError
    rate_limit
        "The user has reached the rate limit for invitations."
    invalid_comment
        "The custom message did not pass comment permissions checks."

union RemoveFileMemberError
    "Errors for :route:`remove_file_member_2`."
    user_error SharingUserError
    access_error SharingFileAccessError
    no_explicit_access MemberAccessLevelResult
        "This member does not have explicit access to the file and therefore cannot be removed.
        The return value is the access that a user might have to the file from a parent folder."

union FileMemberActionError
    invalid_member
        "Specified member was not found."
    no_permission
        "User does not have permission to perform this action on this member."
    access_error SharingFileAccessError
        "Specified file was invalid or user does not have access."
    no_explicit_access MemberAccessLevelResult
        "The action cannot be completed because the target member does not have explicit access
        to the file. The return value is the access that the member has to the file from a parent folder."

#####################
# Route Definitions #
#####################

route add_file_member(AddFileMemberArgs, List(FileMemberActionResult), AddFileMemberError)
    "Adds specified members to a file."

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

struct AddFileMemberArgs
    "Arguments for :route:`add_file_member`."

    file PathOrId
        "File to which to add members."

    members List(MemberSelector)
        "Members to add. Note that even an email address is given, this
        may result in a user being directly added to the membership if that
        email is the user's main account email."

    custom_message String?
        "Message to send to added members in their invitation."

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

    access_level AccessLevel = viewer
        "AccessLevel union object, describing what access level we want to give new members."

    add_message_as_comment Boolean = false
        "If the custom message should be added as a comment on the file."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        members = [default]
        custom_message = "This is a custom message about ACME.doc"
        quiet = false
        access_level = viewer

# --

struct UpdateFileMemberArgs
    "Arguments for :route:`update_file_member`."

    file PathOrId
        "File for which we are changing a member's access."
    member MemberSelector
        "The member whose access we are changing."
    access_level AccessLevel
        "The new access level for the member."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        member = default
        access_level = viewer

route update_file_member(UpdateFileMemberArgs, MemberAccessLevelResult, FileMemberActionError)
    "Changes a member's access on a shared file."

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

# --

route get_file_metadata(GetFileMetadataArg, SharedFileMetadata, GetFileMetadataError)
    "Returns shared file metadata."

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

struct GetFileMetadataArg
    "Arguments of :route:`get_file_metadata`."

    file PathOrId
        "The file to query."
    actions List(FileAction)?
        "A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
         response's :field:`SharedFileMetadata.permissions` field describing the actions the
         authenticated user can perform on the file."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        actions = []

union GetFileMetadataError
    "Error result for :route:`get_file_metadata`."

    user_error SharingUserError
    access_error SharingFileAccessError

# --

route get_file_metadata/batch(GetFileMetadataBatchArg, List(GetFileMetadataBatchResult), SharingUserError)
    "Returns shared file metadata."

    attrs
        scope = "sharing.read"

struct GetFileMetadataBatchArg
    "Arguments of :route:`get_file_metadata/batch`."

    files List(PathOrId, max_items=100)
        "The files to query."
    actions List(FileAction)?
        "A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
         response's :field:`SharedFileMetadata.permissions` field describing the actions the
         authenticated user can perform on the file."

    example default
        files = ["id:3kmLmQFnf1AAAAAAAAAAAw","id:VvTaJu2VZzAAAAAAAAAADQ"]
        actions = []

struct GetFileMetadataBatchResult
    "Per file results of :route:`get_file_metadata/batch`."

    file PathOrId
        "This is the input file identifier corresponding to one of
        :field:`GetFileMetadataBatchArg.files`."
    result GetFileMetadataIndividualResult
        "The result for this particular file."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        result = default

    example file_error
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        result = file_error

union GetFileMetadataIndividualResult
    metadata SharedFileMetadata
        "The result for this file if it was successful."
    access_error SharingFileAccessError
        "The result for this file if it was an error."

    example default
        metadata = default

    example file_error
        access_error = invalid_file

# --

route list_file_members(ListFileMembersArg, SharedFileMembers, ListFileMembersError)
    "Use to obtain the members who have been invited to a file, both inherited
    and uninherited members."

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

struct ListFileMembersArg
    "Arguments for :route:`list_file_members`."

    file PathOrId
        "The file for which you want to see members."
    actions List(MemberAction)?
        "The actions for which to return permissions on a member."
    include_inherited Boolean = true
        "Whether to include members who only have access from a parent shared folder."
    limit UInt32(min_value=1, max_value=300) = 100
        "Number of members to return max per query. Defaults to 100 if no limit is specified."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"

struct SharedFileMembers
    "Shared file user, group, and invitee membership.

    Used for the results of :route:`list_file_members` and
    :route:`list_file_members/continue`, and used as part of the results
    for :route:`list_file_members/batch`."

    users List(UserFileMembershipInfo)
        "The list of user members of the shared file."
    groups List(GroupMembershipInfo)
        "The list of group members of the shared file."
    invitees List(InviteeMembershipInfo)
        "The list of invited members of a file, but have not logged in and
        claimed this."
    cursor String?
        "Present if there are additional shared file members that have not been returned yet. Pass
        the cursor into :route:`list_file_members/continue` to list additional members."

    example default
        users = [default]
        groups = [default]
        invitees = [default]

union ListFileMembersError
    "Error for :route:`list_file_members`."

    user_error SharingUserError
    access_error SharingFileAccessError

struct UserFileMembershipInfo extends UserMembershipInfo
    "The information about a user member of the shared content with an appended last seen timestamp."

    time_last_seen common.DropboxTimestamp?
        "The UTC timestamp of when the user has last seen the content. Only populated if the
        user has seen the content and the caller has a plan that includes viewer history."
    platform_type seen_state.PlatformType?
        "The platform on which the user has last seen the content, or unknown."

    example default
        user = default
        access_type = owner
        permissions = []
        time_last_seen = "2016-01-20T00:00:00Z"
        platform_type = unknown

# --

route list_file_members/batch(ListFileMembersBatchArg, List(ListFileMembersBatchResult), SharingUserError)
    "Get members of multiple files at once. The arguments
    to this route are more limited, and the limit on query result size per file
    is more strict. To customize the results more, use the individual file
    endpoint.

    Inherited users and groups are not included in the result, and permissions are not
    returned for this endpoint."

    attrs
        scope = "sharing.read"

struct ListFileMembersBatchArg
    "Arguments for :route:`list_file_members/batch`."

    files List(PathOrId, max_items=100)
        "Files for which to return members."
    limit UInt32(max_value=20) = 10
        "Number of members to return max per query. Defaults to 10 if no limit is specified."

    example default
        files = ["id:3kmLmQFnf1AAAAAAAAAAAw","id:VvTaJu2VZzAAAAAAAAAADQ"]
        limit = 10

struct ListFileMembersBatchResult
    "Per-file result for :route:`list_file_members/batch`."

    file PathOrId
        "This is the input file identifier, whether an ID or a path."
    result ListFileMembersIndividualResult
        "The result for this particular file."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        result = default

    example member_error
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        result = file_error


struct ListFileMembersCountResult
    members SharedFileMembers
        "A list of members on this file."
    member_count UInt32
        "The number of members on this file. This does not include inherited members."

    example default
        members = default
        member_count = 3

union ListFileMembersIndividualResult
    result ListFileMembersCountResult
        "The results of the query for this file if it was successful."
    access_error SharingFileAccessError
        "The result of the query for this file if it was an error."

    example default
        result = default

    example file_error
        access_error = invalid_file

# --

route list_file_members/continue(ListFileMembersContinueArg, SharedFileMembers, ListFileMembersContinueError)
    "Once a cursor has been retrieved from :route:`list_file_members` or
    :route:`list_file_members/batch`, use this to paginate through all shared
    file members."

    attrs
        scope = "sharing.read"

struct ListFileMembersContinueArg
    "Arguments for :route:`list_file_members/continue`."

    cursor String
        "The cursor returned by your last call to :route:`list_file_members`,
        :route:`list_file_members/continue`, or :route:`list_file_members/batch`."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

union ListFileMembersContinueError
    "Error for :route:`list_file_members/continue`."

    user_error SharingUserError
    access_error SharingFileAccessError
    invalid_cursor
        ":field:`ListFileMembersContinueArg.cursor` is invalid."

# --

route list_received_files(ListFilesArg, ListFilesResult, SharingUserError)
    "Returns a list of all files shared with current user.

     Does not include files the user has received via shared folders, and does
     not include unclaimed invitations."

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

struct ListFilesArg
    "Arguments for :route:`list_received_files`."

    limit UInt32(min_value=1, max_value=300) = 100
        "Number of files to return max per query. Defaults to 100 if no limit
        is specified."
    actions List(FileAction)?
        "A list of `FileAction`s corresponding to `FilePermission`s that should appear in the
         response's :field:`SharedFileMetadata.permissions` field describing the actions the
         authenticated user can perform on the file."

    example default
        limit = 100
        actions = []

struct ListFilesResult
    "Success results for :route:`list_received_files`."

    entries List(SharedFileMetadata)
        "Information about the files shared with current user."
    cursor String?
        "Cursor used to obtain additional shared files."

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

# --

route list_received_files/continue (ListFilesContinueArg, ListFilesResult, ListFilesContinueError)
    "Get more results with a cursor from :route:`list_received_files`."

    attrs
        scope = "sharing.read"

struct ListFilesContinueArg
    "Arguments for :route:`list_received_files/continue`."

    cursor String
        "Cursor in :field:`ListFilesResult.cursor`."

    example default
        cursor = "AzJJbGlzdF90eXBdofe9c3RPbGlzdGFyZ3NfYnlfZ2lkMRhcbric7Rdog9emfGRlc2MCRWxpbWl0BGRId"

union ListFilesContinueError
    "Error results for :route:`list_received_files/continue`."

    user_error SharingUserError
        "User account had a problem."
    invalid_cursor
        ":field:`ListFilesContinueArg.cursor` is invalid."

# --

route remove_file_member(RemoveFileMemberArg, FileMemberActionIndividualResult, RemoveFileMemberError) deprecated by remove_file_member_2
    "Identical to remove_file_member_2 but with less information returned."

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

route remove_file_member_2(RemoveFileMemberArg, FileMemberRemoveActionResult, RemoveFileMemberError)
    "Removes a specified member from the file."

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

struct RemoveFileMemberArg
    "Arguments for :route:`remove_file_member_2`."

    file PathOrId
        "File from which to remove members."
    member MemberSelector
        "Member to remove from this file. Note that even if an email is
        specified, it may result in the removal of a user (not an invitee) if
        the user's main account corresponds to that email address."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"
        member = default

# --

route relinquish_file_membership(RelinquishFileMembershipArg, Void, RelinquishFileMembershipError)
    "The current user relinquishes their membership in the designated file.
    Note that the current user may still have inherited access to this file
    through the parent folder."

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

struct RelinquishFileMembershipArg
    file PathOrId
        "The path or id for the file."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"

union RelinquishFileMembershipError
    access_error SharingFileAccessError
    group_access
        "The current user has access to the shared file via a group.  You can't relinquish
        membership to a file shared via groups."
    no_permission
        "The current user does not have permission to perform this action."

# --

route unshare_file(UnshareFileArg, Void, UnshareFileError)
    "Remove all members from this file. Does not remove inherited members."

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

struct UnshareFileArg
    "Arguments for :route:`unshare_file`."

    file PathOrId
        "The file to unshare."

    example default
        file = "id:3kmLmQFnf1AAAAAAAAAAAw"

union UnshareFileError
    "Error result for :route:`unshare_file`."
    user_error SharingUserError
    access_error SharingFileAccessError

    example default
        user_error = email_unverified