shared_links.stone

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."
    no_one
        "The link merely points the user to the content, and does not grant any additional rights.
        Existing members of the content who use this link can only access the content with their
        pre-existing access rights. Either on the file directly, or inherited from a parent folder."
    only_you
        "Only the current user can view this link."


union SharedLinkAccessFailureReason
    login_required
        "User is not logged in."
    email_verify_required
        "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`."
    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). For some links, an
        effective_audience value is returned instead."
    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 and resolved_visibility is returned instead of effective_audience."
    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`."
    effective_audience LinkAudience?
        "The type of audience who can benefit from the access level specified by the
        `link_access_level` field."
    link_access_level LinkAccessLevel?
        "The access level that the link will grant to its users. A link can grant additional rights
        to a user beyond their current access level. For example, if a user was invited as a viewer
        to a file, and then opens a link with `link_access_level` set to `editor`, then they will
        gain editor privileges. The `link_access_level` is a property of the link, and does not
        depend on who is calling this API. In particular, `link_access_level` does not take into
        account the API caller's current permissions to the content."
    visibility_policies List(VisibilityPolicy)
        "A list of policies that the user might be able to set for the visibility."
    can_set_expiry Boolean
        "Whether the user can set the expiry settings of the link. This refers to the ability to
        create a new expiry and modify an existing expiry."
    can_remove_expiry Boolean
        "Whether the user can remove the expiry of the link."
    allow_download Boolean
        "Whether the link can be downloaded or not."
    can_allow_download Boolean
        "Whether the user can allow downloads via the link. This refers to the ability to remove a
        no-download restriction on the link."
    can_disallow_download Boolean
        "Whether the user can disallow downloads via the link. This refers to the ability to impose
        a no-download restriction on the link."
    allow_comments Boolean
        "Whether comments are enabled for the linked file. This takes the team commenting policy into account."
    team_restricts_comments Boolean
        "Whether the team has disabled commenting globally."
    audience_options List(LinkAudienceOption)?
        "A list of link audience options the user might be able to set as the new audience."
    can_set_password Boolean?
        "Whether the user can set a password for the link."
    can_remove_password Boolean?
        "Whether the user can remove the password of the link."
    require_password Boolean?
        "Whether the user is required to provide a password to view the link."
    can_use_extended_sharing_controls Boolean?
        "Whether the user can use extended sharing controls, based on their account type."

    example default
        resolved_visibility = public
        can_revoke = false
        revoke_failure_reason = owner_only
        visibility_policies = [public, password]
        can_set_expiry = false
        can_remove_expiry = false
        allow_download = true
        can_allow_download = true
        can_disallow_download = false
        allow_comments = true
        team_restricts_comments = true
        audience_options = [public, team, no_one]
        can_set_password = true
        can_remove_password = true
        require_password = false
        can_use_extended_sharing_controls = false

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; use :route:`files.export` instead."

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

    attrs
        auth = "app, user"
        allow_app_folder_app = true
        scope = "sharing.read"

#
# 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. For members of
    business teams using team space and member folders, returns all shared links in the team
    member's home folder unless the team space ID is specified in the request header. For more
    information, refer to the :link:`Namespace Guide
    https://www.dropbox.com/developers/reference/namespace-guide`.

    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
        allow_app_folder_app = true
        scope = "sharing.read"

#
# Modify shared link settings definitions and route
#

struct SharedLinkSettings
    require_password Boolean?
        "Boolean flag to enable or disable password protection."
    link_password String?
        "If :field:`require_password` is true, 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."
    audience LinkAudience?
        "The new audience who can benefit from the access level specified by the link's access level
        specified in the `link_access_level` field of `LinkPermissions`. This is used in conjunction
        with team policies and shared folder policies to determine the final effective audience type
        in the `effective_audience` field of `LinkPermissions."
    access RequestedLinkAccessLevel?
        "Requested access level you want the audience to gain from this link. Note, modifying access
        level for an existing link is not supported."
    requested_visibility RequestedVisibility?
        "Use :field:`audience` instead.  The requested access for this shared link."
    allow_download Boolean?
        "Boolean flag to allow or not download capabilities for shared links."

    example default
        requested_visibility = public
        audience = public
        access = viewer
        allow_download = true


union LinkAccessLevel
    viewer
        "Users who use the link can view and comment on the content."
    editor
        "Users who use the link can edit, view and comment on the content."

union RequestedLinkAccessLevel
    viewer
        "Users who use the link can view and comment on the content."
    editor
        "Users who use the link can edit, view and comment on the content.
        Note not all file types support edit links yet."
    max
        "Request for the maximum access level you can set the link to."
    default
        "Request for the default access level the user has set."

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
        "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`."

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
        allow_app_folder_app = true
        scope = "sharing.write"

#
# 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 SharedLinkAlreadyExistsMetadata
    metadata SharedLinkMetadata
        "Metadata of the shared link that already exists."

union_closed CreateSharedLinkWithSettingsError
    path files.LookupError
    email_not_verified
        "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`."
    shared_link_already_exists SharedLinkAlreadyExistsMetadata?
        "The shared link already exists. You can call :route:`list_shared_links` to get the
         existing link, or use the provided metadata if it is returned."
    settings_error SharedLinkSettingsError
        "There is an error with the given settings."
    access_denied
        "The user is not allowed to create a shared link to the specified file. For
         example, this can occur if the file is restricted or if the user's links are
         :link:`banned https://help.dropbox.com/files-folders/share/banned-links`."

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
        allow_app_folder_app = true
        select_admin_mode = "team_admin"
        scope = "sharing.write"


#
# 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
        allow_app_folder_app = true
        select_admin_mode = "team_admin"
        scope = "sharing.write"

#
# 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"
        allow_app_folder_app = true
        scope = "sharing.read"

#
# Deprecated 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."

    example default
        path = default

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."

    example default
        links = [default]

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, up to a maximum of 1000 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."

    attrs
        allow_app_folder_app = true
        scope = "sharing.read"

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

    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.

    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
        allow_app_folder_app = true
        select_admin_mode = "team_admin"
        scope = "sharing.write"

struct LinkAudienceOption
    audience LinkAudience
        "Specifies who can access the link."
    allowed Boolean
        "Whether the user calling this API can select this audience option."
    disallowed_reason LinkAudienceDisallowedReason?
        "If :field:`allowed` is :val:`false`, this will provide the reason that the user is not
        permitted to set the visibility to this policy."

    example public
        audience = public
        allowed = true

    example team
        audience = team
        allowed = false

    example no_one
        audience = no_one
        allowed = true

#
# Alpha version of LinkPermissions with visibility information and controls
#

union VisibilityPolicyDisallowedReason
    delete_and_recreate
        "The user needs to delete and recreate the link to change the visibility policy."
    restricted_by_shared_folder
        "The parent shared folder restricts sharing of links outside the shared folder. To change
        the visibility policy, remove the restriction from the parent shared folder."
    restricted_by_team
        "The team policy prevents links being shared outside the team."
    user_not_on_team
        "The user needs to be on a team to set this policy."
    user_account_type
        "The user is a basic user or is on a limited team."
    permission_denied
        "The user does not have permission."

union LinkAudienceDisallowedReason extends VisibilityPolicyDisallowedReason
    "check documentation for VisibilityPolicyDisallowedReason."

union AlphaResolvedVisibility extends ResolvedVisibility
    "check documentation for ResolvedVisibility."

struct VisibilityPolicy
    policy RequestedVisibility
        "This is the value to submit when saving the visibility setting."
    resolved_policy AlphaResolvedVisibility
        "This is what the effective policy would be, if you selected this option. The resolved
        policy is obtained after considering external effects such as shared folder settings and
        team policy. This value is guaranteed to be provided."
    allowed Boolean
        "Whether the user is permitted to set the visibility to this policy."
    disallowed_reason VisibilityPolicyDisallowedReason?
        "If :field:`allowed` is :val:`false`, this will provide the reason that the user is not
        permitted to set the visibility to this policy."

    example public
        policy = public
        resolved_policy = public
        allowed = true

    example public_team
        policy = public
        resolved_policy = team_only
        allowed = false
        disallowed_reason = restricted_by_team

    example public_shared_folder
        policy = public
        resolved_policy = shared_folder_only
        allowed = false
        disallowed_reason = restricted_by_shared_folder

    example password
        policy = password
        resolved_policy = password
        allowed = true

    example password_team
        policy = password
        resolved_policy = team_and_password
        allowed = true

    example password_shared_folder
        policy = password
        resolved_policy = shared_folder_only
        allowed = false
        disallowed_reason = restricted_by_shared_folder

    example team_only
        policy = team_only
        resolved_policy = team_only
        allowed = true

    example team_shared_folder
        policy = team_only
        resolved_policy = shared_folder_only
        allowed = false
        disallowed_reason = restricted_by_shared_folder