cloudmount/vendor/github.com/dropbox/dropbox-sdk-go-unofficial/generator/dropbox-api-spec/paper.stone

namespace paper
    "This namespace contains endpoints and data types for managing docs and folders in Dropbox Paper."

import common
import sharing

alias PaperDocId = String
    "Paper doc ID."

struct RefPaperDoc
    doc_id PaperDocId
        "The Paper doc ID."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"

union ListPaperDocsFilterBy
    docs_accessed
        "Fetches all Paper doc IDs that the user has ever accessed."
    docs_created
        "Fetches only the Paper doc IDs that the user has created."

union ListPaperDocsSortBy
    accessed
        "Sorts the Paper docs by the time they were last accessed."
    modified
        "Sorts the Paper docs by the time they were last modified."
    created
        "Sorts the Paper docs by the creation time."

union ListPaperDocsSortOrder
    ascending
        "Sorts the search result in ascending order."
    descending
        "Sorts the search result in descending order."

struct ListPaperDocsArgs
    filter_by ListPaperDocsFilterBy = docs_accessed
        "Allows user to specify how the Paper docs should be filtered."
    sort_by ListPaperDocsSortBy = accessed
        "Allows user to specify how the Paper docs should be sorted."
    sort_order ListPaperDocsSortOrder = ascending
        "Allows user to specify the sort order of the result."
    limit Int32(min_value=1, max_value=1000) = 1000
        "Size limit per batch. The maximum number of docs that
        can be retrieved per batch is 1000. Higher value results in invalid arguments error."
    example default
        filter_by = docs_created
        sort_by = modified
        sort_order = descending
        limit = 100

struct ListPaperDocsContinueArgs
    cursor String
        "The cursor obtained from :route:`docs/list` or :route:`docs/list/continue`.
        Allows for pagination."
    example default
        cursor = "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd"

struct Cursor
    value String
        "The actual cursor value."
    expiration common.DropboxTimestamp?
        "Expiration time of :field:`value`.

        Some cursors might have expiration time assigned. This is a UTC value after which
        the cursor is no longer valid and the API starts returning an error.
        If cursor expires a new one needs to be obtained and pagination needs to be restarted.
        Some cursors might be short-lived some cursors might be long-lived.

        This really depends on the sorting type and order, e.g.:

        1. on one hand, listing docs created by the user, sorted by the created time
        ascending will have undefinite expiration because the results cannot change while
        the iteration is happening. This cursor would be suitable for long term polling.

        2. on the other hand, listing docs sorted by the last modified time will have
        a very short expiration as docs do get modified very often and the modified time
        can be changed while the iteration is happening thus altering the results.
        "
    example default
        value = "zHZvTPBnXilGgm1AmDgVyZ10zf7qb0qznd5sAVQbbIvoteSnWLjUdLU7aR25hb"
        expiration = "2016-08-07T14:56:15Z"

struct ListPaperDocsResponse
    doc_ids List(String)
        "The list of Paper doc IDs that can be used to access the given Paper docs or
        supplied to other API methods.
        The list is sorted in the order specified by the initial call to :route:`docs/list`."
    cursor Cursor
        "Pass the cursor into :route:`docs/list/continue` to paginate through all files.
        The cursor preserves all properties as specified in the original call
        to :route:`docs/list`.
        "
    has_more Boolean
        "Will be set to True if a subsequent call with the provided cursor
        to :route:`docs/list/continue` returns immediately with some results. If set to False
        please allow some delay before making another call to :route:`docs/list/continue`."

    example default
        doc_ids = ["zO1E7coc54sE8IuMdUoxz", "mm1AmDgVyZ10zf7qb0qzn", "dByYHZvTPBnXilGgyc5mm"]
        cursor = default
        has_more = true

union ExportFormat
    "The desired export format of the Paper doc."

    html
        "The HTML export format."
    markdown
        "The markdown export format."

struct PaperDocExport extends RefPaperDoc
    export_format ExportFormat

    example default
        export_format = markdown
        doc_id = "uaSvRuxvnkFa12PTkBv5q"

struct PaperDocExportResult
    owner String
        "The Paper doc owner's email address."
    title String
        "The Paper doc title."
    revision Int64
        "The Paper doc revision. Simply an ever increasing number."
    mime_type String
        "MIME type of the export. This corresponds to :type:`ExportFormat` specified
        in the request."

    example default
        owner = "james@example.com"
        title = "Week one retention"
        revision = 456736745
        mime_type = "text/x-markdown"

union_closed DocSubscriptionLevel
    "The subscription level of a Paper doc."

    default
        "No change email messages unless you're the creator."
    ignore
        "Ignored: Not shown in pad lists or activity and no email message is sent."
    every
        "Subscribed: Shown in pad lists and activity and change email messages are sent."
    no_email
        "Unsubscribed: Shown in pad lists, but not in activity and no change email messages are sent."

union_closed FolderSubscriptionLevel
    "The subscription level of a Paper folder."

    none
        "Not shown in activity, no email messages."
    activity_only
        "Shown in activity, no email messages."
    daily_emails
        "Shown in activity, daily email messages."
    weekly_emails
        "Shown in activity, weekly email messages."

union_closed FolderSharingPolicyType
    "The sharing policy of a Paper folder.


    Note: The sharing policy of subfolders is inherited from the root folder."
    team
        "Everyone in your team and anyone directly invited can access this folder."
    invite_only
        "Only people directly invited can access this folder."

union_closed SharingTeamPolicyType
    "The sharing policy type of the Paper doc."

    people_with_link_can_edit
        "Users who have a link to this doc can edit it."
    people_with_link_can_view_and_comment
        "Users who have a link to this doc can view and comment on it."
    invite_only
        "Users must be explicitly invited to this doc."

union_closed SharingPublicPolicyType extends SharingTeamPolicyType
    disabled
        "Value used to indicate that doc sharing is enabled only within team."

struct SharingPolicy
    "Sharing policy of Paper doc."

    public_sharing_policy SharingPublicPolicyType?
        "This value applies to the non-team members."
    team_sharing_policy SharingTeamPolicyType?
        "This value applies to the team members only. The value is null for all personal accounts."

    example default
        public_sharing_policy = people_with_link_can_edit
        team_sharing_policy = people_with_link_can_edit

struct Folder
    "Data structure representing a Paper folder."

    id String
        "Paper folder ID. This ID uniquely identifies the folder."
    name String
        "Paper folder name."

    example default
        name = "Design docs"
        id = "e.gGYT6HSafpMej9bUv306oGm60vrHiCHgEFnzziioPGCvHf"

struct FoldersContainingPaperDoc
    "Metadata about Paper folders containing the specififed Paper doc."

    folder_sharing_policy_type FolderSharingPolicyType?
        "The sharing policy of the folder containing the Paper doc."

    folders List(Folder)?
        "The folder path. If present the first folder is the root folder."

    example default
        folder_sharing_policy_type = team
        folders = [default]

struct PaperDocSharingPolicy extends RefPaperDoc
    sharing_policy SharingPolicy
        "The default sharing policy to be set for the Paper doc."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"
        sharing_policy = default

struct RemovePaperDocUser extends RefPaperDoc
    member sharing.MemberSelector
        "User which should be removed from the Paper doc. Specify only email address or
        Dropbox account ID."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"
        member = default

union PaperDocPermissionLevel
    edit
        "User will be granted edit permissions."
    view_and_comment
        "User will be granted view and comment permissions."

struct AddMember
    permission_level PaperDocPermissionLevel = edit
        "Permission for the user."
    member sharing.MemberSelector
        "User which should be added to the Paper doc. Specify only email address or
        Dropbox account ID."

    example default
        member = default
        permission_level = view_and_comment

union UserOnPaperDocFilter
    visited
        "all users who have visited the Paper doc."
    shared
        "All uses who are shared on the Paper doc. This includes all users who have visited
        the Paper doc as well as those who have not."

struct ListUsersOnPaperDocArgs extends RefPaperDoc
    limit Int32(min_value=1, max_value=1000) = 1000
        "Size limit per batch. The maximum number of users that can be retrieved per batch
        is 1000. Higher value results in invalid arguments error."

    filter_by UserOnPaperDocFilter = shared
        "Specify this attribute if you want to obtain users that have already accessed
        the Paper doc."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"
        limit = 100
        filter_by = shared

struct ListUsersOnPaperDocContinueArgs extends RefPaperDoc
    cursor String
        "The cursor obtained from :route:`docs/users/list` or
        :route:`docs/users/list/continue`. Allows for pagination."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"
        cursor = "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd"

struct InviteeInfoWithPermissionLevel
    invitee sharing.InviteeInfo
        "Email address invited to the Paper doc."

    permission_level PaperDocPermissionLevel
        "Permission level for the invitee."

    example default
        invitee = default
        permission_level = edit


struct UserInfoWithPermissionLevel
    user sharing.UserInfo
        "User shared on the Paper doc."

    permission_level PaperDocPermissionLevel
        "Permission level for the user."

    example default
        user = default
        permission_level = view_and_comment

struct ListUsersOnPaperDocResponse
    invitees List(InviteeInfoWithPermissionLevel)
        "List of email addresses with their respective permission levels
        that are invited on the Paper doc."
    users List(UserInfoWithPermissionLevel)
        "List of users with their respective permission levels
        that are invited on the Paper folder."
    doc_owner sharing.UserInfo
        "The Paper doc owner. This field is populated on every single response."
    cursor Cursor
        "Pass the cursor into :route:`docs/users/list/continue` to paginate
        through all users.
        The cursor preserves all properties as specified in the original call
        to :route:`docs/users/list`.
        "
    has_more Boolean
        "Will be set to True if a subsequent call with the provided cursor
        to :route:`docs/users/list/continue` returns immediately with some results.
        If set to False please allow some delay before making another call to
        :route:`docs/users/list/continue`."

    example default
        users = [default]
        invitees = [default]
        doc_owner = default
        cursor = default
        has_more = false

struct AddPaperDocUser extends RefPaperDoc
    members List(AddMember, max_items = 20)
        "User which should be added to the Paper doc. Specify only email address or
        Dropbox account ID."
    custom_message String?
        "A personal message that will be emailed to each successfully added member."
    quiet Boolean = false
        "Clients should set this to true if no email message shall be sent to added users."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"
        members = [default]
        custom_message = "Welcome to Paper."

union AddPaperDocUserResult
    success
        "User was successfully added to the Paper doc."
    unknown_error
        "Something unexpected happened when trying to add the user to the Paper doc."
    sharing_outside_team_disabled
        "The Paper doc can be shared only with team members."
    daily_limit_reached
        "The daily limit of how many users can be added to the Paper doc was reached."
    user_is_owner
        "Owner's permissions cannot be changed."
    failed_user_data_retrieval
        "User data could not be retrieved. Clients should retry."
    permission_already_granted
        "This user already has the correct permission to the Paper doc."

struct AddPaperDocUserMemberResult
    "Per-member result for :route:`docs/users/add`."
    member sharing.MemberSelector
        "One of specified input members."
    result AddPaperDocUserResult
        "The outcome of the action on this member."

union PaperApiBaseError
    insufficient_permissions
        "Your account does not have permissions to perform this action."

union PaperApiCursorError
    expired_cursor
        "The provided cursor is expired."
    invalid_cursor
        "The provided cursor is invalid."
    wrong_user_in_cursor
        "The provided cursor contains invalid user."
    reset
        "Indicates that the cursor has been invalidated. Call
        the corresponding non-continue endpoint to obtain a new cursor."

union DocLookupError extends PaperApiBaseError
    doc_not_found
        "The required doc was not found."

union ListDocsCursorError
    cursor_error PaperApiCursorError

union ListUsersCursorError extends PaperApiBaseError
    doc_not_found
        "The required doc was not found."
    cursor_error PaperApiCursorError

struct ListUsersOnFolderResponse
    invitees List(sharing.InviteeInfo)
        "List of email addresses that are invited on the Paper folder."
    users List(sharing.UserInfo)
        "List of users that are invited on the Paper folder."
    cursor Cursor
        "Pass the cursor into :route:`docs/folder_users/list/continue` to paginate
        through all users.
        The cursor preserves all properties as specified in the original call
        to :route:`docs/folder_users/list`.
        "
    has_more Boolean
        "Will be set to True if a subsequent call with the provided cursor
        to :route:`docs/folder_users/list/continue` returns immediately with some results.
        If set to False please allow some delay before making another call to
        :route:`docs/folder_users/list/continue`."

    example default
        users = [default]
        invitees = [default]
        cursor = default
        has_more = false

struct ListUsersOnFolderArgs extends RefPaperDoc
    limit Int32(min_value=1, max_value=1000) = 1000
        "Size limit per batch. The maximum number of users that can be retrieved per batch
        is 1000. Higher value results in invalid arguments error."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"
        limit = 100

struct ListUsersOnFolderContinueArgs extends RefPaperDoc
    cursor String
        "The cursor obtained from :route:`docs/folder_users/list` or
        :route:`docs/folder_users/list/continue`. Allows for pagination."

    example default
        doc_id = "uaSvRuxvnkFa12PTkBv5q"
        cursor = "U60b6BxT43ySd5sAVQbbIvoteSnWLjUdLU7aR25hbt3ySd5sAVQbbIvoteSnWLjUd"

route docs/folder_users/list (ListUsersOnFolderArgs, ListUsersOnFolderResponse, DocLookupError)
    "Lists the users who are explicitly invited to the Paper folder in which the Paper doc
    is contained. For private folders all users (including owner) shared on the folder
    are listed and for team folders all non-team users shared on the folder are returned."
    attrs
        owner="paper-eng"

route docs/folder_users/list/continue (ListUsersOnFolderContinueArgs, ListUsersOnFolderResponse, ListUsersCursorError)
    "Once a cursor has been retrieved from :route:`docs/folder_users/list`, use this to
    paginate through all users on the Paper folder."
    attrs
        owner="paper-eng"

route docs/sharing_policy/get (RefPaperDoc, SharingPolicy, DocLookupError)
    "Gets the default sharing policy for the given Paper doc."
    attrs
        owner="paper-eng"

route docs/sharing_policy/set (PaperDocSharingPolicy, Void, DocLookupError)
    "Sets the default sharing policy for the given Paper doc. The default 'team_sharing_policy'
    can be changed only by teams, omit this field for personal accounts.


    Note: 'public_sharing_policy' cannot be set to the value 'disabled' because this setting
    can be changed only via the team admin console."
    attrs
        owner="paper-eng"

route docs/archive (RefPaperDoc, Void, DocLookupError)
    "Marks the given Paper doc as archived.

    Note: This action can be performed or undone by anyone with edit permissions to the doc."
    attrs
        owner="paper-eng"

route docs/permanently_delete (RefPaperDoc, Void, DocLookupError)
    "Permanently deletes the given Paper doc. This operation is final as the doc
    cannot be recovered.


    Note: This action can be performed only by the doc owner."
    attrs
        owner="paper-eng"

route docs/download (PaperDocExport, PaperDocExportResult, DocLookupError)
    "Exports and downloads Paper doc either as HTML or markdown."
    attrs
        style="download"
        owner="paper-eng"

route docs/get_folder_info (RefPaperDoc, FoldersContainingPaperDoc, DocLookupError)
    "Retrieves folder information for the given Paper doc. This includes:

      - folder sharing policy; permissions for subfolders are set by the top-level folder.

      - full 'filepath', i.e. the list of folders (both folderId and folderName) from
        the root folder to the folder directly containing the Paper doc.


    Note: If the Paper doc is not in any folder (aka unfiled) the response will be empty."
    attrs
        owner="paper-eng"

route docs/users/add (AddPaperDocUser, List(AddPaperDocUserMemberResult), DocLookupError)
    "Allows an owner or editor to add users to a Paper doc or change their permissions
    using their email address or Dropbox account ID.


    Note: The Doc owner's permissions cannot be changed."
    attrs
        owner="paper-eng"

route docs/users/remove (RemovePaperDocUser, Void, DocLookupError)
    "Allows an owner or editor to remove users from a Paper doc using their email address or
    Dropbox account ID.


    Note: Doc owner cannot be removed."
    attrs
        owner="paper-eng"

route docs/users/list (ListUsersOnPaperDocArgs, ListUsersOnPaperDocResponse, DocLookupError)
    "Lists all users who visited the Paper doc or users with explicit access. This call
    excludes users who have been removed. The list is sorted by the date of the visit or
    the share date.

    The list will include both users, the explicitly shared ones as well as those
    who came in using the Paper url link."
    attrs
        owner="paper-eng"

route docs/users/list/continue (ListUsersOnPaperDocContinueArgs, ListUsersOnPaperDocResponse, ListUsersCursorError)
    "Once a cursor has been retrieved from :route:`docs/users/list`, use this to
    paginate through all users on the Paper doc."
    attrs
        owner="paper-eng"

route docs/list (ListPaperDocsArgs, ListPaperDocsResponse, Void)
    "Return the list of all Paper docs according to the argument specifications. To iterate
    over through the full pagination, pass the cursor to :route:`docs/list/continue`."
    attrs
        owner="paper-eng"

route docs/list/continue (ListPaperDocsContinueArgs, ListPaperDocsResponse, ListDocsCursorError)
    "Once a cursor has been retrieved from :route:`docs/list`, use this to
    paginate through all Paper doc."
    attrs
        owner="paper-eng"