namespace sharing

import common
import files
import users

alias Id = files.Id
alias Path = files.Path
alias Rev = files.Rev
alias TeamInfo = users.Team
alias ReadPath = files.ReadPath

#
# Link Metadata definitions and route
#

struct GetSharedLinkMetadataArg
    url String
        "URL of the shared link."
    path Path?
        "If the shared link is to a folder, this parameter can be used to retrieve the metadata for
        a specific file or sub-folder in this folder. A relative path should be used."
    link_password String?
        "If the shared link has a password, this parameter can be used."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        path = "/Prime_Numbers.txt"

union_closed RequestedVisibility
    "The access permission that can be requested by the caller for the shared link.
    Note that the final resolved visibility of the shared link takes into account other aspects,
    such as team and shared folder settings.
    Check the :type:`ResolvedVisibility` for more info on the possible resolved visibility values
    of shared links. "

    public
        "Anyone who has received the link can access it. No login required."
    team_only
        "Only members of the same team can
        access the link. Login is required."
    password
        "A link-specific password is required to access the
        link. Login is not required."

union ResolvedVisibility extends RequestedVisibility
    "The actual access permissions values of shared links after taking into account user
    preferences and the team and shared folder settings.
    Check the :type:`RequestedVisibility` for more info on the possible visibility values
    that can be set by the shared link's owner. "

    team_and_password
        "Only members of the same team who
        have the link-specific password can access the link. Login is required."
    shared_folder_only
        "Only members of the shared folder containing the linked file
        can access the link. Login is required."

union SharedLinkAccessFailureReason
    login_required
        "User is not logged in."
    email_verify_required
        "User's email is not verified."
    password_required
        "The link is password protected."
    team_only
        "Access is allowed for team members only."
    owner_only
        "Access is allowed for the shared link's owner only."

struct LinkPermissions
    resolved_visibility ResolvedVisibility?
        "The current visibility of the link after considering the shared links policies of the
        the team (in case the link's owner is part of a team) and the shared folder (in case the
        linked file is part of a shared folder). This field is shown only if the caller has access
        to this info (the link's owner always has access to this data)."

    requested_visibility RequestedVisibility?
        "The shared link's requested visibility. This can be overridden by the team and shared
        folder policies. The final visibility, after considering these policies, can be found in
        :field:`resolved_visibility`. This is shown only if the caller is the link's
        owner."

    can_revoke Boolean
        "Whether the caller can revoke the shared link"
    revoke_failure_reason SharedLinkAccessFailureReason?
        "The failure reason for revoking the link. This field will only be present if the
        :field:`can_revoke` is :val:`false`."

    example default
        resolved_visibility = public
        can_revoke = false
        revoke_failure_reason = owner_only

struct TeamMemberInfo
    "Information about a team member."

    team_info TeamInfo
        "Information about the member's team"
    display_name String
        "The display name of the user."
    member_id String?
        "ID of user as a member of a team. This field will only be present if the member is in the
        same team as current user."

    example default
        team_info = default
        display_name = "Roger Rabbit"
        member_id = "dbmid:abcd1234"

struct SharedLinkMetadata
    "The metadata of a shared link "

    union
        file FileLinkMetadata
        folder FolderLinkMetadata

    url String
        "URL of the shared link."
    id Id?
        "A unique identifier for the linked file."
    name String
        "The linked file name (including extension).
        This never contains a slash."
    expires common.DropboxTimestamp?
        "Expiration time, if set. By default the link won't expire."
    path_lower String?
        "The lowercased full path in the user's Dropbox. This always starts with a slash.
        This field will only be present only if the linked file is in the authenticated user's
         dropbox."
    link_permissions LinkPermissions
        "The link's access permissions."
    team_member_info TeamMemberInfo?
        "The team membership information of the link's owner.  This field will only be present
         if the link's owner is a team member."
    content_owner_team_info TeamInfo?
        "The team information of the content's owner. This field will only be present if
        the content's owner is a team member and the content's owner team is different from the
        link's owner team."

    example default
        file = default

    example folder_link_metadata
        folder = default

struct FileLinkMetadata extends SharedLinkMetadata
    "The metadata of a file shared link "

    client_modified common.DropboxTimestamp
        "The modification time set by the desktop client
        when the file was added to Dropbox. Since this time is not verified
        (the Dropbox server stores whatever the desktop client sends up), this
        should only be used for display purposes (such as sorting) and not,
        for example, to determine if a file has changed or not."
    server_modified common.DropboxTimestamp
        "The last time the file was modified on Dropbox."
    rev Rev
        "A unique identifier for the current revision of a file. This field is
        the same rev as elsewhere in the API and can be used to detect changes
        and avoid conflicts."
    size UInt64
        "The file size in bytes."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        id = "id:a4ayc_80_OEAAAAAAAAAXw"
        name = "Prime_Numbers.txt"
        path_lower = "/homework/math/prime_numbers.txt"
        link_permissions = default
        team_member_info = default
        client_modified = "2015-05-12T15:50:38Z"
        server_modified = "2015-05-12T15:50:38Z"
        rev = "a1c10ce0dd78"
        size = 7212

struct FolderLinkMetadata extends SharedLinkMetadata
    "The metadata of a folder shared link "

    example default
        url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
        id = "id:a4ayc_80_OEAAAAAAAAAXw"
        name = "Math"
        path_lower = "/homework/math"
        team_member_info = default
        link_permissions = default

union SharedLinkError
    shared_link_not_found
        "The shared link wasn't found."
    shared_link_access_denied
        "The caller is not allowed to access this shared link."
    unsupported_link_type
        "This type of link is not supported."

route get_shared_link_metadata(GetSharedLinkMetadataArg, SharedLinkMetadata, SharedLinkError)
    "Get the shared link's metadata."

    attrs
        owner = "sharing"
        allow_app_folder_app = true

#
# List Shared links definitions and route
#

struct ListSharedLinksArg
    path ReadPath?
        "See :route:`list_shared_links` description."
    cursor String?
        "The cursor returned by your last call to :route:`list_shared_links`."
    direct_only Boolean?
        "See :route:`list_shared_links` description."

    example default
        "List all links"
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

    example path
        path = "/Homework/Math"

    example id
        path = "id:a4ayc_80_OEAAAAAAAAAYa"

    example rev
        path = "rev:a1c10ce0dd78"

    example id_no_parent_links
        path = "id:a4ayc_80_OEAAAAAAAAAYa"
        direct_only = true

struct ListSharedLinksResult
    links List(SharedLinkMetadata)
        "Shared links applicable to the path argument."
    has_more Boolean
        "Is true if there are additional shared links that have not been returned
        yet. Pass the cursor into :route:`list_shared_links` to retrieve them."
    cursor String?
        "Pass the cursor into :route:`list_shared_links` to obtain the additional links. Cursor is
        returned only if no path is given."

    example default
        links = [default]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
        has_more = true

union ListSharedLinksError
    path files.LookupError
    reset
        "Indicates that the cursor has been invalidated. Call
        :route:`list_shared_links` to obtain a new cursor."

route list_shared_links(ListSharedLinksArg, ListSharedLinksResult, ListSharedLinksError)
    "List shared links of this user.

    If no path is given, returns a list of all shared links for the current user.

    If a non-empty path is given, returns a list of all shared links
    that allow access to the given path - direct links to the given path and links to parent folders
    of the given path. Links to parent folders can be suppressed by setting
    direct_only to true."

    attrs
        owner = "sharing"
        allow_app_folder_app = true

#
# Modify shared link settings definitions and route
#

struct SharedLinkSettings
    requested_visibility RequestedVisibility?
        "The requested access for this shared link."
    link_password String?
        "If :field:`requested_visibility` is :field:`RequestedVisibility.password` this is needed
        to specify the password to access the link. "
    expires common.DropboxTimestamp?
        "Expiration time of the shared link. By default the link won't expire."

    example default
        requested_visibility = public

struct ModifySharedLinkSettingsArgs
    url String
        "URL of the shared link to change its settings"
    settings SharedLinkSettings
        "Set of settings for the shared link."
    remove_expiration Boolean = false
        "If set to true, removes the expiration of the shared link."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        settings = default

union_closed SharedLinkSettingsError
    invalid_settings
        "The given settings are invalid
        (for example, all attributes of the :type:`SharedLinkSettings` are empty,
        the requested visibility is :field:`RequestedVisibility.password` but the
        :field:`SharedLinkSettings.link_password` is missing, :field:`SharedLinkSettings.expires`
        is set to the past, etc.)"

    not_authorized
        "User is not allowed to modify the settings of this link. Note that basic
        users can only set :field:`RequestedVisibility.public`
        as the :field:`SharedLinkSettings.requested_visibility` and cannot
        set :field:`SharedLinkSettings.expires`"


union ModifySharedLinkSettingsError extends SharedLinkError
    settings_error SharedLinkSettingsError
        "There is an error with the given settings"
    email_not_verified
        "The caller's email should be verified"

route modify_shared_link_settings(ModifySharedLinkSettingsArgs, SharedLinkMetadata, ModifySharedLinkSettingsError)
    "Modify the shared link's settings.

    If the requested visibility conflict with the shared links policy of the team or the
    shared folder (in case the linked file is part of a shared folder) then the
    :field:`LinkPermissions.resolved_visibility` of the returned :type:`SharedLinkMetadata` will
    reflect the actual visibility of the shared link and the
    :field:`LinkPermissions.requested_visibility` will reflect the requested visibility."

    attrs
        owner = "adminx"
        allow_app_folder_app = true

#
# Create shared link with settings definitions and route
#

struct CreateSharedLinkWithSettingsArg
    path ReadPath
        "The path to be shared by the shared link"
    settings SharedLinkSettings?
        "The requested settings for the newly created shared link"

    example default
        path = "/Prime_Numbers.txt"
        settings = default

union_closed CreateSharedLinkWithSettingsError
    path files.LookupError
    email_not_verified
        "User's email should be verified"
    shared_link_already_exists
        "The shared link already exists"
    settings_error SharedLinkSettingsError
        "There is an error with the given settings"
    access_denied
        "Access to the requested path is forbidden"

route create_shared_link_with_settings(CreateSharedLinkWithSettingsArg, SharedLinkMetadata, CreateSharedLinkWithSettingsError)
    "Create a shared link with custom settings.
    If no settings are given then the default visibility is :field:`RequestedVisibility.public`
    (The resolved visibility, though, may depend on other aspects such as team and shared folder
    settings). "

    attrs
        owner = "sharing"
        allow_app_folder_app = true


#
# Revoke shared link
#

struct RevokeSharedLinkArg
    url String
        "URL of the shared link."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"

union RevokeSharedLinkError extends SharedLinkError
    shared_link_malformed
        "Shared link is malformed."

route revoke_shared_link(RevokeSharedLinkArg, Void, RevokeSharedLinkError)
    "Revoke a shared link.

    Note that even after revoking a shared link to a file, the file may be accessible if there are
    shared links leading to any of the file parent folders. To list all shared links that enable
    access to a specific file, you can use the :route:`list_shared_links` with the file as the
    :field:`ListSharedLinksArg.path` argument. "

    attrs
        owner = "sharing"
        allow_app_folder_app = true

#
# NSLR endpoints
#

union GetSharedLinkFileError extends SharedLinkError
    shared_link_is_directory
        "Directories cannot be retrieved by this endpoint."

alias GetSharedLinkFileArg = GetSharedLinkMetadataArg

route get_shared_link_file(GetSharedLinkFileArg, SharedLinkMetadata, GetSharedLinkFileError)
    "Download the shared link's file from a user's Dropbox."

    attrs
        host="content"
        style="download"
        owner = "sharing"
        allow_app_folder_app = true

#
# Depracated endpoints
#


union Visibility
    "Who can access a shared link.
    The most open visibility is :field:`public`.
    The default depends on many aspects, such as team and user
    preferences and shared folder settings."

    public
        "Anyone who has received the link can access it. No login required."
    team_only
        "Only members of the same team can
        access the link. Login is required."
    password
        "A link-specific password is required to access the
        link. Login is not required."
    team_and_password
        "Only members of the same team who
        have the link-specific password can access the link."
    shared_folder_only
        "Only members of the shared folder containing the linked file
        can access the link. Login is required."

struct LinkMetadata
    "Metadata for a shared link. This can be either a
    :type:`PathLinkMetadata` or :type:`CollectionLinkMetadata`."

    union
        path PathLinkMetadata
        collection CollectionLinkMetadata

    url String
        "URL of the shared link."
    visibility Visibility
        "Who can access the link."
    expires common.DropboxTimestamp?
        "Expiration time, if set. By default the link won't expire."

struct PathLinkMetadata extends LinkMetadata
    "Metadata for a path-based shared link."

    path String
        "Path in user's Dropbox."

    example default
        url = "https://www.dropbox.com/s/2sn712vy1ovegw8/Prime_Numbers.txt?dl=0"
        path = "/Homework/Math/Prime_Numbers.txt"
        expires = null
        visibility = public

struct CollectionLinkMetadata extends LinkMetadata
    "Metadata for a collection-based shared link."

    example default
        url = "https://www.dropbox.com/sh/s6fvw6ol7rmqo1x/AAAgWRSbjmYDvPpDB30Sykjfa?dl=0"
        expires = null
        visibility = public

struct GetSharedLinksArg
    path String?
        "See :route:`get_shared_links` description."

    example default
        "Get all links, including collection links"
        path = ""

    example math_homework_links
        "Get links giving access to /Homework/Math"
        path = "/Homework/Math"

struct GetSharedLinksResult
    links List(LinkMetadata)
        "Shared links applicable to the path argument."

union GetSharedLinksError
    path files.MalformedPathError

route get_shared_links(GetSharedLinksArg, GetSharedLinksResult, GetSharedLinksError) deprecated by list_shared_links
    "Returns a list of :type:`LinkMetadata` objects for this user,
    including collection links.

    If no path is given, returns a list of all shared links for the current
    user, including collection links.

    If a non-empty path is given, returns a list of all shared links
    that allow access to the given path.  Collection links are never
    returned in this case.

    Note that the url field in the response is never the shortened URL."

    attrs
        owner = "sharing"
        allow_app_folder_app = true

union_closed PendingUploadMode
    "Flag to indicate pending upload default (for linking to not-yet-existing paths)."

    file
        "Assume pending uploads are files."
    folder
        "Assume pending uploads are folders."

struct CreateSharedLinkArg
    path String
        "The path to share."
    short_url Boolean = false
        "Whether to return a shortened URL."
    pending_upload PendingUploadMode?
        "If it's okay to share a path that does not yet exist, set this to
        either :field:`PendingUploadMode.file` or :field:`PendingUploadMode.folder`
        to indicate whether to assume it's a file or folder."

    example default
        path = "/Homework/Math/Prime_Numbers.txt"

union CreateSharedLinkError
    path files.LookupError

route create_shared_link(CreateSharedLinkArg, PathLinkMetadata, CreateSharedLinkError) deprecated by create_shared_link_with_settings
    "Create a shared link.

    If a shared link already exists for the given path, that link is returned.

    Note that in the returned :type:`PathLinkMetadata`, the
    :field:`PathLinkMetadata.url` field is the shortened URL if
    :field:`CreateSharedLinkArg.short_url` argument is set to :val:`true`.

    Previously, it was technically possible to break a shared link by moving or
    renaming the corresponding file or folder. In the future, this will no
    longer be the case, so your app shouldn't rely on this behavior. Instead, if
    your app needs to revoke a shared link, use :route:`revoke_shared_link`."

    attrs
        owner = "sharing"
        allow_app_folder_app = true