shared_content_links.stone

namespace sharing

import common


union LinkExpiry
    remove_expiry
        "Remove the currently set expiry for the link."
    set_expiry common.DropboxTimestamp
        "Set a new expiry or change an existing expiry."

union LinkPassword

    remove_password
        "Remove the currently set password for the link."

    set_password String
        "Set a new password or change an existing password."

struct LinkSettings
    "Settings that apply to a link."
    access_level AccessLevel?
        "The access level on the link for this file. Currently,
        it only accepts 'viewer' and 'viewer_no_comment'."
    audience LinkAudience?
        "The type of audience on the link for this file."
    expiry LinkExpiry?
        "An expiry timestamp to set on a link."
    password LinkPassword?
        "The password for the link."

union LinkAudience
    public
        "Link is accessible by anyone."
    team
        "Link is accessible only by team members."
    no_one
        "The link can be used by no one. The link merely points the user to the content, and does
        not grant additional rights to the user. Members of the content who use this link can only
        access the content with their pre-existing access rights."
    password
        "Use `require_password` instead. A link-specific password is required to access the
        link. Login is not required."
    members
        "Link is accessible only by members of the content."

struct LinkPermission
    "Permissions for actions that can be performed on a link."
    action LinkAction
    allow Boolean
    reason PermissionDeniedReason?

    example default
        action = change_audience
        allow = true

union LinkAction
    "Actions that can be performed on a link."
    change_access_level
        "Change the access level of the link."
    change_audience
        "Change the audience of the link."
    remove_expiry
        "Remove the expiry date of the link."
    remove_password
        "Remove the password of the link."
    set_expiry
        "Create or modify the expiry date of the link."
    set_password
        "Create or modify the password of the link."

struct SharedContentLinkMetadataBase
    access_level AccessLevel?
        "The access level on the link for this file."
    audience_options List(LinkAudience)
        "The audience options that are available for the content. Some audience options may be
        unavailable. For example, team_only may be unavailable if the content is not owned by a
        user on a team. The 'default' audience option is always available if the user can modify
        link settings."
    audience_restricting_shared_folder AudienceRestrictingSharedFolder?
        "The shared folder that prevents the link audience for this link from being more
        restrictive."
    current_audience LinkAudience
        "The current audience of the link."
    expiry common.DropboxTimestamp?
        "Whether the link has an expiry set on it. A link with an expiry will have its
         audience changed to members when the expiry is reached."
    link_permissions List(LinkPermission)
        "A list of permissions for actions you can perform on the link."
    password_protected Boolean
        "Whether the link is protected by a password."

struct SharedContentLinkMetadata extends SharedContentLinkMetadataBase
    "Metadata of a shared link for a file or folder."

    audience_exceptions AudienceExceptions?
        "The content inside this folder with link audience different than this folder's. This is
        only returned when an endpoint that returns metadata for a single shared folder is called,
        e.g. /get_folder_metadata."

    url String
        "The URL of the link."

    example default
        audience_options = [public, team, members]
        current_audience = public
        link_permissions = [default]
        password_protected = false
        url = ""

struct ExpectedSharedContentLinkMetadata extends SharedContentLinkMetadataBase
    "The expected metadata of a shared link for a file or folder when a link is first created for
    the content. Absent if the link already exists."

    example default
        audience_options = [public, team, members]
        current_audience = public
        link_permissions = [default]
        password_protected = false

struct AudienceRestrictingSharedFolder
    "Information about the shared folder that prevents the link audience for this link from being
    more restrictive."
    shared_folder_id common.SharedFolderId
        "The ID of the shared folder."
    name String
        "The name of the shared folder."
    audience LinkAudience
        "The link audience of the shared folder."

struct AudienceExceptions
    "The total count and truncated list of information of content inside this folder that has a
    different audience than the link on this folder. This is only returned for folders."
    count UInt32
    exceptions List(AudienceExceptionContentInfo)
        "A truncated list of some of the content that is an exception. The length of this list could
        be smaller than the count since it is only a sample but will not be empty as long as
        count is not 0."

    example default
        count = 0
        exceptions = []

struct AudienceExceptionContentInfo
    "Information about the content that has a link audience different than that of this folder."
    name String
        "The name of the content, which is either a file or a folder."

    example default
        name = "sample file name"