namespace files
    "This namespace contains endpoints and data types for basic file operations."

import async
import auth
import common
import users_common
import properties

alias Id = String(min_length=1)
alias Path = String(pattern="/(.|[\\r\\n])*")
alias PathOrId = String(pattern="/(.|[\\r\\n])*|id:.*|(ns:[0-9]+(/.*)?)")
alias PathR = String(pattern="(/(.|[\\r\\n])*)?|(ns:[0-9]+(/.*)?)")               # A path that can be the root path ("").
alias Rev = String(min_length=9, pattern="[0-9a-f]+") # TODO: Change pattern to "rev:[0-9a-f]{9,}"
alias ListFolderCursor = String(min_length=1)
alias ReadPath = String(pattern="(/(.|[\\r\\n])*|id:.*)|(rev:[0-9a-f]{9,})|(ns:[0-9]+(/.*)?)")
alias WritePath = String(pattern="(/(.|[\\r\\n])*)|(ns:[0-9]+(/.*)?)")
alias Sha256HexHash = String(min_length=64, max_length=64)

#
# Metadata definitions and route
#

struct Metadata
    "Metadata for a file or folder."

    union_closed
        file FileMetadata
        folder FolderMetadata
        deleted DeletedMetadata  # Used by list_folder* and search

    name String
        "The last component of the path (including extension).
        This never contains a slash."
    path_lower String?
        "The lowercased full path in the user's Dropbox. This always starts with a slash.
        This field will be null if the file or folder is not mounted."
    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, and at least the last path component will have the correct casing. Changes
        to only the casing of paths won't be returned by :route:`list_folder/continue`. This field
        will be null if the file or folder is not mounted."
    parent_shared_folder_id common.SharedFolderId?
        "Deprecated. Please use :field:`FileSharingInfo.parent_shared_folder_id`
        or :field:`FolderSharingInfo.parent_shared_folder_id` instead."

    example default
        file = default

    example folder_metadata
        folder = default

struct SharingInfo
    "Sharing info for a file or folder."

    read_only Boolean
        "True if the file or folder is inside a read-only shared folder."

    example default
        read_only = false

struct FileSharingInfo extends SharingInfo
    "Sharing info for a file which is contained by a shared folder."

    parent_shared_folder_id common.SharedFolderId
        "ID of shared folder that holds this file."

    modified_by users_common.AccountId?
        "The last user who modified the file. This field will be null if
        the user's account has been deleted."

    example default
        read_only = true
        parent_shared_folder_id = "84528192421"
        modified_by = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"

struct FolderSharingInfo extends SharingInfo
    "Sharing info for a folder which is contained in a shared folder or is a
    shared folder mount point."

    parent_shared_folder_id common.SharedFolderId?
        "Set if the folder is contained by a shared folder."

    shared_folder_id common.SharedFolderId?
        "If this folder is a shared folder mount point, the ID of the shared
        folder mounted at this location."

    traverse_only Boolean = false
        "Specifies that the folder can only be traversed and the user can only see
        a limited subset of the contents of this folder because they don't have
        read access to this folder. They do, however, have access to some sub folder."

    no_access Boolean = false
        "Specifies that the folder cannot be accessed by the user."

    example default
        "Folder inside a shared folder."
        read_only = false
        parent_shared_folder_id = "84528192421"

    example shared_folder
        "Read-only shared folder mount point."
        read_only = true
        shared_folder_id = "84528192421"

struct Dimensions
    "Dimensions for a photo or video."

    height UInt64
        "Height of the photo/video."
    width UInt64
        "Width of the photo/video."

    example default
        height = 768
        width = 1024

struct GpsCoordinates
    "GPS coordinates for a photo or video."

    latitude Float64
        "Latitude of the GPS coordinates."
    longitude Float64
        "Longitude of the GPS coordinates."

    example default
        latitude = 37.7833
        longitude = 122.4167

struct MediaMetadata
    "Metadata for a photo or video."

    union_closed
        photo PhotoMetadata
        video VideoMetadata

    dimensions Dimensions?
        "Dimension of the photo/video."
    location GpsCoordinates?
        "The GPS coordinate of the photo/video."
    time_taken common.DropboxTimestamp?
        "The timestamp when the photo/video is taken."

struct PhotoMetadata extends MediaMetadata
    "Metadata for a photo."

    example default
        dimensions = default
        location = default
        time_taken = "2015-05-12T15:50:38Z"

struct VideoMetadata extends MediaMetadata
    "Metadata for a video."

    duration UInt64?
        "The duration of the video in milliseconds."

    example default
        dimensions = default
        location = default
        time_taken = "2015-05-12T15:50:38Z"
        duration = 1000

union_closed MediaInfo
    pending
        "Indicate the photo/video is still under processing and metadata is
        not available yet."
    metadata MediaMetadata
        "The metadata for the photo/video."

struct FileMetadata extends Metadata
    id Id
        "A unique identifier for the file."
    client_modified common.DropboxTimestamp
        "For files, this is 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."
    media_info MediaInfo?
        "Additional information if the file is a photo or video."
    sharing_info FileSharingInfo?
        "Set if this file is contained in a shared folder."
    property_groups List(properties.PropertyGroup)?
        "Additional information if the file has custom properties with the
        property template specified."
    has_explicit_shared_members Boolean?
        "This flag will only be present if include_has_explicit_shared_members
         is true in :route:`list_folder` or :route:`get_metadata`. If this
         flag is present, it will be true if this file has any explicit shared
         members. This is different from sharing_info in that this could be true
         in the case where a file has explicit members but is not contained within
         a shared folder."
    content_hash Sha256HexHash?
        "A hash of the file content. This field can be used to verify data integrity. For more
        information see our :link:`Content hash /developers/reference/content-hash` page."

    example default
        id = "id:a4ayc_80_OEAAAAAAAAAXw"
        name = "Prime_Numbers.txt"
        path_lower = "/homework/math/prime_numbers.txt"
        path_display = "/Homework/math/Prime_Numbers.txt"
        sharing_info = default
        client_modified = "2015-05-12T15:50:38Z"
        server_modified = "2015-05-12T15:50:38Z"
        rev = "a1c10ce0dd78"
        size = 7212
        property_groups = [default]
        has_explicit_shared_members = false
        content_hash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"

struct FolderMetadata extends Metadata
    id Id
        "A unique identifier for the folder."
    shared_folder_id common.SharedFolderId?
        "Deprecated. Please use :field:`sharing_info` instead."
    sharing_info FolderSharingInfo?
        "Set if the folder is contained in a shared folder or is a shared folder mount point."
    property_groups List(properties.PropertyGroup)?
        "Additional information if the file has custom properties with the
        property template specified."

    example default
        id = "id:a4ayc_80_OEAAAAAAAAAXz"
        path_lower = "/homework/math"
        path_display = "/Homework/math"
        name = "math"
        sharing_info = default
        property_groups = [default]

struct DeletedMetadata extends Metadata
    "Indicates that there used to be a file or folder at this path, but it no longer exists."
    # TODO: Do we care about whether it's a deleted file or folder?
    # TODO: Add the mtime when it's been deleted?  And the rev???

    example default
        path_lower = "/homework/math/pi.txt"
        path_display = "/Homework/math/pi.txt"
        name = "pi.txt"

union_closed GetMetadataError
    path LookupError

struct GetMetadataArg
    path ReadPath
        "The path of a file or folder on Dropbox."
    include_media_info Boolean = false
        "If true, :field:`FileMetadata.media_info` is set for photo and video."
    include_deleted Boolean = false
        "If true, :type:`DeletedMetadata` will be returned for deleted file or
        folder, otherwise :field:`LookupError.not_found` will be returned."
    include_has_explicit_shared_members Boolean = false
        "If true, the results will include a flag for each file indicating whether or not
         that file has any explicit members."

    example default
        path = "/Homework/math"

    example id
        path = "id:a4ayc_80_OEAAAAAAAAAYa"

    example rev
        path = "rev:a1c10ce0dd78"

route get_metadata (GetMetadataArg, Metadata, GetMetadataError)
    "Returns the metadata for a file or folder.

    Note: Metadata for the root folder is unsupported."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true
        takes_path_root = true

#
# List folder routes
#

struct ListFolderLongpollArg
    cursor ListFolderCursor
        "A cursor as returned by :route:`list_folder` or :route:`list_folder/continue`. Cursors
        retrieved by setting :field:`ListFolderArg.include_media_info` to :val:`true` are not
        supported."

    timeout UInt64(min_value=30, max_value=480) = 30
        "A timeout in seconds. The request will block for at most this length
        of time, plus up to 90 seconds of random jitter added to avoid the
        thundering herd problem. Care should be taken when using this
        parameter, as some network infrastructure does not support long
        timeouts."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

struct ListFolderLongpollResult
    changes Boolean
        "Indicates whether new changes are available. If true, call
        :route:`list_folder/continue` to retrieve the changes."
    backoff UInt64?
        "If present, backoff for at least this many seconds before calling
        :route:`list_folder/longpoll` again."

    example default
        changes = true

union ListFolderLongpollError
    reset
        "Indicates that the cursor has been invalidated. Call
        :route:`list_folder` to obtain a new cursor."

route list_folder/longpoll (ListFolderLongpollArg, ListFolderLongpollResult, ListFolderLongpollError)
    "A longpoll endpoint to wait for changes on an account. In conjunction with
    :route:`list_folder/continue`, this call gives you a low-latency way to
    monitor an account for file changes. The connection will block until there
    are changes available or a timeout occurs. This endpoint is useful mostly
    for client-side apps. If you're looking for server-side notifications,
    check out our
    :link:`webhooks documentation https://www.dropbox.com/developers/reference/webhooks`."

    attrs
        host = "notify"
        auth = "noauth"
        owner = "dev-plat"
        allow_app_folder_app = true

struct ListFolderArg
    path PathR
        "The path to the folder you want to see the contents of."
    recursive Boolean = false
        "If true, the list folder operation will be applied recursively to all subfolders
        and the response will contain contents of all subfolders."
    include_media_info Boolean = false
        "If true, :field:`FileMetadata.media_info` is set for photo and video."
    include_deleted Boolean = false
        "If true, the results will include entries for files and folders that used to exist but were deleted."
    include_has_explicit_shared_members Boolean = false
        "If true, the results will include a flag for each file indicating whether or not
         that file has any explicit members."

    example default
        path = "/Homework/math"
        recursive = false

struct ListFolderResult
    entries List(Metadata)
        "The files and (direct) subfolders in the folder."
    cursor ListFolderCursor
        "Pass the cursor into :route:`list_folder/continue` to see what's
        changed in the folder since your previous query."
    has_more Boolean
        "If true, then there are more entries available. Pass the
        cursor to :route:`list_folder/continue` to retrieve the rest."

    example default
        entries = [default, folder_metadata]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
        has_more = false

union ListFolderError
    path LookupError

route list_folder (ListFolderArg, ListFolderResult, ListFolderError)
    "Starts returning the contents of a folder. If the result's :field:`ListFolderResult.has_more`
    field is :val:`true`, call :route:`list_folder/continue` with the returned
    :field:`ListFolderResult.cursor` to retrieve more entries.

    If you're using :field:`ListFolderArg.recursive` set to :val:`true` to keep a local cache of
    the contents of a Dropbox account, iterate through each entry in order and process them as
    follows to keep your local state in sync:

    For each :type:`FileMetadata`, store the new entry at the given path in your local state. If the
    required parent folders don't exist yet, create them. If there's already something else at the
    given path, replace it and remove all its children.

    For each :type:`FolderMetadata`, store the new entry at the given path in your local state. If
    the required parent folders don't exist yet, create them. If there's already something else at
    the given path, replace it but leave the children as they are. Check the new entry's
    :field:`FolderSharingInfo.read_only` and set all its children's read-only statuses to match.

    For each :type:`DeletedMetadata`, if your local state has something at the given path, remove it
    and all its children. If there's nothing at the given path, ignore this entry.

    Note: :type:`auth.RateLimitError` may be returned if multiple :route:`list_folder` or
    :route:`list_folder/continue` calls with same parameters are made simultaneously by same
    API app for same user. If your app implements retry logic, please hold off the retry until
    the previous request finishes."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

struct ListFolderContinueArg
    cursor ListFolderCursor
        "The cursor returned by your last call to :route:`list_folder` or
        :route:`list_folder/continue`."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

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

route list_folder/continue (ListFolderContinueArg, ListFolderResult, ListFolderContinueError)
    "Once a cursor has been retrieved from :route:`list_folder`, use this to paginate through all
    files and retrieve updates to the folder, following the same rules as documented for
    :route:`list_folder`."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

struct ListFolderGetLatestCursorResult
    cursor ListFolderCursor
        "Pass the cursor into :route:`list_folder/continue` to see what's
        changed in the folder since your previous query."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

route list_folder/get_latest_cursor (ListFolderArg, ListFolderGetLatestCursorResult, ListFolderError)
    "A way to quickly get a cursor for the folder's state. Unlike :route:`list_folder`,
    :route:`list_folder/get_latest_cursor` doesn't return any entries. This endpoint is for app
    which only needs to know about new files and modifications and doesn't need to know about
    files that already exist in Dropbox."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Download
#

union DownloadError
    path LookupError

struct DownloadArg
    path ReadPath
        "The path of the file to download."
    rev Rev?
        "Deprecated. Please specify revision in :field:`path` instead."

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

    example id
        path = "id:a4ayc_80_OEAAAAAAAAAYa"

    example rev
        path = "rev:a1c10ce0dd78"

route download (DownloadArg, FileMetadata, DownloadError)
    "Download a file from a user's Dropbox."

    attrs
        host = "content"
        style = "download"
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Upload Routes
#

# Errors

struct UploadWriteFailed
    reason WriteError
        "The reason why the file couldn't be saved."
    upload_session_id String
        "The upload session ID; this may be used to retry the commit."

union UploadError
    path UploadWriteFailed
        "Unable to save the uploaded contents to a file."

struct UploadSessionOffsetError
    correct_offset UInt64
        "The offset up to which data has been collected."

union UploadSessionLookupError
    not_found
        "The upload session ID was not found or has expired. Upload sessions are
        valid for 48 hours."
    incorrect_offset UploadSessionOffsetError
        "The specified offset was incorrect. See the value for the
        correct offset. This error may occur when a previous request
        was received and processed successfully but the client did not
        receive the response, e.g. due to a network error."
    closed
        "You are attempting to append data to an upload session that
        has alread been closed (i.e. committed)."
    not_closed
        "The session must be closed before calling upload_session/finish_batch."

union UploadSessionFinishError
    lookup_failed UploadSessionLookupError
        "The session arguments are incorrect; the value explains the reason."
    path WriteError
        "Unable to save the uploaded contents to a file."
    too_many_shared_folder_targets
        "The batch request commits files into too many different shared folders.
        Please limit your batch request to files contained in a single shared folder."
    too_many_write_operations
        "There are too many write operations happening in the user's Dropbox. You should
        retry uploading this file."

# Req/Resp

struct UploadSessionStartArg
    close Boolean = false
        "If true, the current session will be closed, at which point you won't
        be able to call :route:`upload_session/append_v2` anymore with the
        current session."

    example with_close
        close = false

struct UploadSessionStartResult
    session_id String
        "A unique identifier for the upload session. Pass this to
        :route:`upload_session/append_v2` and
        :route:`upload_session/finish`."

    example default
        session_id = "1234faaf0678bcde"

route upload_session/start (UploadSessionStartArg, UploadSessionStartResult, Void)
    "Upload sessions allow you to upload a single file in one or more
    requests, for example where the size of the file is greater than 150
    MB.  This call starts a new upload session with the given data. You
    can then use :route:`upload_session/append_v2` to add more data and
    :route:`upload_session/finish` to save all the data to a file in
    Dropbox.

    A single request should not upload more than 150 MB.

    An upload session can be used for a maximum of 48 hours. Attempting
    to use an :field:`UploadSessionStartResult.session_id` with
    :route:`upload_session/append_v2` or :route:`upload_session/finish` more
    than 48 hours after its creation will return a
    :field:`UploadSessionLookupError.not_found`."

    attrs
        host = "content"
        style = "upload"
        owner = "dev-plat"
        feature = "upload_api_rate_limit"
        allow_app_folder_app = true

struct UploadSessionAppendArg
    cursor UploadSessionCursor
        "Contains the upload session ID and the offset."
    close Boolean = false
        "If true, the current session will be closed, at which point
        you won't be able to call :route:`upload_session/append_v2`
        anymore with the current session."

    example default
        cursor = default

route upload_session/append_v2 (UploadSessionAppendArg, Void, UploadSessionLookupError)
    "Append more data to an upload session.

    When the parameter close is set, this call will close the session.

    A single request should not upload more than 150 MB."

    attrs
        host = "content"
        style = "upload"
        owner = "dev-plat"
        feature = "upload_api_rate_limit"
        allow_app_folder_app = true


struct UploadSessionCursor
    session_id String
        "The upload session ID (returned by :route:`upload_session/start`)."
    offset UInt64
        "The amount of data that has been uploaded so far. We use this to make
        sure upload data isn't lost or duplicated in the event of a network
        error."

    example default
        session_id = "1234faaf0678bcde"
        offset = 0

route upload_session/append (UploadSessionCursor, Void, UploadSessionLookupError) deprecated by upload_session/append_v2
    "Append more data to an upload session.

    A single request should not upload more than 150 MB."

    attrs
        host = "content"
        style = "upload"
        owner = "dev-plat"
        feature = "upload_api_rate_limit"
        allow_app_folder_app = true

union_closed WriteMode
    "Your intent when writing a file to some path. This is used to determine
    what constitutes a conflict and what the autorename strategy is.

    In some situations, the conflict behavior is identical:
    (a) If the target path doesn't contain anything, the file is always written;
    no conflict.
    (b) If the target path contains a folder, it's always a conflict.
    (c) If the target path contains a file with identical contents, nothing gets
    written; no conflict.

    The conflict checking differs in the case where there's a file at the target
    path with contents different from the contents you're trying to write."

    add
        "Do not overwrite an existing file if there is a conflict. The
        autorename strategy is to append a number to the file name. For example,
        \"document.txt\" might become \"document (2).txt\"."
    overwrite
        "Always overwrite the existing file. The autorename
        strategy is the same as it is for :field:`add`."
    update Rev
        "Overwrite if the given \"rev\" matches the existing file's \"rev\".
        The autorename strategy is to append the string \"conflicted copy\"
        to the file name. For example, \"document.txt\" might become
        \"document (conflicted copy).txt\" or \"document (Panda's conflicted copy).txt\"."

    example default
        add = null

    example overwriting
        overwrite = null

    example with_revision
        update = "a1c10ce0dd78"

struct CommitInfo
    path WritePath
        "Path in the user's Dropbox to save the file."
    mode WriteMode = add
        "Selects what to do if the file already exists."
    autorename Boolean = false
        "If there's a conflict, as determined by :field:`mode`, have the Dropbox
        server try to autorename the file to avoid conflict."
    client_modified common.DropboxTimestamp?
        "The value to store as the :field:`client_modified` timestamp. Dropbox
        automatically records the time at which the file was written to the
        Dropbox servers. It can also record an additional timestamp, provided
        by Dropbox desktop clients, mobile clients, and API apps of when the
        file was actually created or modified."
    mute Boolean = false
        "Normally, users are made aware of any file modifications in their
        Dropbox account via notifications in the client software. If
        :val:`true`, this tells the clients that this modification shouldn't
        result in a user notification."

    example default
        path = "/Homework/math/Matrices.txt"
        autorename = true

    example update
        path = "/Homework/math/Matrices.txt"
        mode = with_revision
        autorename = false

struct UploadSessionFinishArg
    cursor UploadSessionCursor
        "Contains the upload session ID and the offset."
    commit CommitInfo
        "Contains the path and other optional modifiers for the commit."

    example default
        cursor = default
        commit = default

    example update
        cursor = default
        commit = update

route upload_session/finish (UploadSessionFinishArg, FileMetadata, UploadSessionFinishError)
    "Finish an upload session and save the uploaded data to the given file
    path.

    A single request should not upload more than 150 MB."

    attrs
        host = "content"
        style = "upload"
        owner = "dev-plat"
        feature = "upload_api_rate_limit"
        allow_app_folder_app = true

route upload (CommitInfo, FileMetadata, UploadError)
    "Create a new file with the contents provided in the request.

    Do not use this to upload a file larger than 150 MB. Instead, create an
    upload session with :route:`upload_session/start`."

    attrs
        host = "content"
        style = "upload"
        owner = "dev-plat"
        feature = "upload_api_rate_limit"
        allow_app_folder_app = true
        takes_path_root = true

#
# Batch Upload
#

struct UploadSessionFinishBatchArg
    entries List(UploadSessionFinishArg, max_items=1000)
        "Commit information for each file in the batch."

    example default
        entries = [default]

struct UploadSessionFinishBatchResult
    entries List(UploadSessionFinishBatchResultEntry)
        "Commit result for each file in the batch."

    example default
        entries = [default]

union_closed UploadSessionFinishBatchResultEntry
    success FileMetadata
    failure UploadSessionFinishError

    example default
        success = default

union_closed UploadSessionFinishBatchJobStatus extends async.PollResultBase
    complete UploadSessionFinishBatchResult
        "The :route:`upload_session/finish_batch` has finished."

    example default
        complete = default

union UploadSessionFinishBatchLaunch extends async.LaunchResultBase
    "Result returned by :route:`upload_session/finish_batch` that may either launch an
    asynchronous job or complete synchronously."

    complete UploadSessionFinishBatchResult

    example complete
        complete = default

    example async_job_id
        async_job_id = "34g93hh34h04y384084"

route upload_session/finish_batch (UploadSessionFinishBatchArg, UploadSessionFinishBatchLaunch, Void)
    "This route helps you commit many files at once into a user's Dropbox. Use
    :route:`upload_session/start` and :route:`upload_session/append_v2` to
    upload file contents. We recommend uploading many files in parallel to increase
    throughput. Once the file contents have been uploaded, rather than calling
    :route:`upload_session/finish`, use this route to finish all your upload sessions
    in a single request.

    :field:`UploadSessionStartArg.close` or :field:`UploadSessionAppendArg.close`
    needs to be true for the last
    :route:`upload_session/start` or :route:`upload_session/append_v2` call.

    This route will return a job_id immediately and do the async commit job in background.
    Use :route:`upload_session/finish_batch/check` to check the job status.

    For the same account, this route should be executed serially. That means you should not start
    the next job before current job finishes. We allow up to 1000 entries in a single request."

    attrs
        owner = "dev-plat"
        feature = "upload_api_rate_limit"
        allow_app_folder_app = true

route upload_session/finish_batch/check(async.PollArg, UploadSessionFinishBatchJobStatus, async.PollError)
    "Returns the status of an asynchronous job for :route:`upload_session/finish_batch`. If
    success, it returns list of result for each entry."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Search
#

union_closed SearchMode
    filename
        "Search file and folder names."
    filename_and_content
        "Search file and folder names as well as file contents."
    deleted_filename
        "Search for deleted file and folder names."

    example default
        filename_and_content = null

    example name_only
        filename = null

    example deleted_names
        deleted_filename = null

struct SearchArg
    path PathR
        "The path in the user's Dropbox to search. Should probably be
        a folder."
    query String
        "The string to search for. The search string is split on spaces into
        multiple tokens. For file name searching, the last token is used for
        prefix matching (i.e. \"bat c\" matches \"bat cave\" but not \"batman
        car\")."
    start UInt64 = 0
        "The starting index within the search results (used for paging)."
    max_results UInt64(min_value=1, max_value=1000) = 100
        "The maximum number of search results to return."
    mode SearchMode = filename
        "The search mode (filename, filename_and_content, or deleted_filename).
        Note that searching file content is only available for Dropbox Business
        accounts."

    example default
        path = ""
        query = "prime numbers"

union_closed SearchMatchType
    "Indicates what type of match was found for a given item."

    filename
        "This item was matched on its file or folder name."
    content
        "This item was matched based on its file contents."
    both
        "This item was matched based on both its contents and its file name."

    example default
        content = null

struct SearchMatch
    match_type SearchMatchType
        "The type of the match."
    metadata Metadata
        "The metadata for the matched file or folder."

    example default
        match_type = default
        metadata = default

struct SearchResult
    matches List(SearchMatch)
        "A list (possibly empty) of matches for the query."
    more Boolean
        "Used for paging. If true, indicates there is another page of results
        available that can be fetched by calling :route:`search` again."
    start UInt64
        "Used for paging. Value to set the start argument to when calling
        :route:`search` to fetch the next page of results."

    example default
        matches = [default]
        more = false
        start = 1

union SearchError
    path LookupError

route search (SearchArg, SearchResult, SearchError)
    "Searches for files and folders.

    Note: Recent changes may not immediately be reflected in search results due to a short delay in indexing."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Errors shared by various operations
#

alias MalformedPathError = String?  # TODO: Maybe a user_message-like thing?

union LookupError
    malformed_path MalformedPathError
    not_found
        "There is nothing at the given path."
    not_file
        "We were expecting a file, but the given path refers to something that isn't a file."
    not_folder
        "We were expecting a folder, but the given path refers to something that isn't a folder."
    restricted_content
        "The file cannot be transferred because the content is restricted.  For example,
        sometimes there are legal restrictions due to copyright claims."

union WriteError
    malformed_path MalformedPathError
    conflict WriteConflictError
        "Couldn't write to the target path because there was something in the way."
    no_write_permission
        "The user doesn't have permissions to write to the target location."
    insufficient_space
        "The user doesn't have enough available space (bytes) to write more data."
    disallowed_name
        "Dropbox will not save the file or folder because of its name."
    team_folder
        "This endpoint cannot modify or delete team folders."

union WriteConflictError
    file
        "There's a file in the way."
    folder
        "There's a folder in the way."
    file_ancestor
        "There's a file at an ancestor path, so we couldn't create the required parent folders."

#
# Create folder
#

struct CreateFolderArg
    path WritePath
        "Path in the user's Dropbox to create."
    autorename Boolean = false
        "If there's a conflict, have the Dropbox server try to autorename
        the folder to avoid the conflict."

    example default
        path = "/Homework/math"

union_closed CreateFolderError
    path WriteError

route create_folder (CreateFolderArg, FolderMetadata, CreateFolderError)
    "Create a folder at a given path."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Delete
#

struct DeleteArg
    path WritePath
        "Path in the user's Dropbox to delete."

    example delete
        path = "/Homework/math/Prime_Numbers.txt"

union DeleteError
    path_lookup LookupError
    path_write WriteError

struct DeleteBatchArg
    entries List(DeleteArg)

    example default
        entries = [delete]

union_closed DeleteBatchResultEntry
    success DeleteResult
    failure DeleteError

    example default
        success = default

struct DeleteResult
    metadata Metadata

    example default
        metadata = default

struct DeleteBatchResult
    entries List(DeleteBatchResultEntry)

    example default
        entries = [default]

union DeleteBatchError
    too_many_write_operations
        "There are too many write operations in user's Dropbox. Please retry
        this request."

union DeleteBatchJobStatus extends async.PollResultBase
    complete DeleteBatchResult
        "The batch delete has finished."
    failed DeleteBatchError
        "The batch delete has failed."

    example default
        complete = default

union DeleteBatchLaunch extends async.LaunchResultBase
    "Result returned by :route:`delete_batch` that may either launch an asynchronous job or complete
    synchronously."

    complete DeleteBatchResult

    example complete
        complete = default

    example async_job_id
        async_job_id = "34g93hh34h04y384084"

route delete (DeleteArg, Metadata, DeleteError)
    "Delete the file or folder at a given path.

    If the path is a folder, all its contents will be deleted too.

    A successful response indicates that the file or folder was deleted. The returned metadata will
    be the corresponding :type:`FileMetadata` or :type:`FolderMetadata` for the item at time of
    deletion, and not a :type:`DeletedMetadata` object."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

route delete_batch (DeleteBatchArg, DeleteBatchLaunch, Void)
    "Delete multiple files/folders at once.

    This route is asynchronous, which returns a job ID immediately and runs
    the delete batch asynchronously. Use :route:`delete_batch/check` to check
    the job status."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

route delete_batch/check (async.PollArg, DeleteBatchJobStatus, async.PollError)
    "Returns the status of an asynchronous job for :route:`delete_batch`. If
    success, it returns list of result for each entry."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

route permanently_delete (DeleteArg, Void, DeleteError)
    "Permanently delete the file or folder at a given path
    (see https://www.dropbox.com/en/help/40).

    Note: This endpoint is only available for Dropbox Business apps."

#
# Args and error shared by copy and move
#

struct RelocationPath
    from_path WritePath
        "Path in the user's Dropbox to be copied or moved."
    to_path WritePath
        "Path in the user's Dropbox that is the destination."

    example default
        from_path = "/Homework/math"
        to_path = "/Homework/algebra"

struct RelocationArg extends RelocationPath
    allow_shared_folder Boolean = false
        "If true, :route:`copy` will copy contents in shared folder,
        otherwise :field:`RelocationError.cant_copy_shared_folder` will be
        returned if :field:`from_path` contains shared folder. This field is
        always true for :route:`move`."
    autorename Boolean = false
        "If there's a conflict, have the Dropbox server try to autorename
        the file to avoid the conflict."

    example default
        from_path = "/Homework/math"
        to_path = "/Homework/algebra"

union RelocationError
    from_lookup LookupError
    from_write WriteError
    to WriteError

    cant_copy_shared_folder
        "Shared folders can't be copied."
    cant_nest_shared_folder
        "Your move operation would result in nested shared folders.  This is not allowed."
    cant_move_folder_into_itself
        "You cannot move a folder into itself."
    too_many_files
        "The operation would involve more than 10,000 files and folders."
    duplicated_or_nested_paths
        "There are duplicated/nested paths among :field:`RelocationArg.from_path`
        and :field:`RelocationArg.to_path`."

struct RelocationBatchArg
    entries List(RelocationPath)
        "List of entries to be moved or copied. Each entry is :type:`RelocationPath`."
    allow_shared_folder Boolean = false
        "If true, :route:`copy_batch` will copy contents in shared folder,
        otherwise :field:`RelocationError.cant_copy_shared_folder` will be
        returned if :field:`RelocationPath.from_path` contains shared folder.
         This field is always true for :route:`move_batch`."
    autorename Boolean = false
        "If there's a conflict with any file, have the Dropbox server try to
        autorename that file to avoid the conflict."

    example default
        entries = [default]

struct RelocationBatchResult
    entries List(RelocationResult)

    example default
        entries = [default]

union_closed RelocationBatchJobStatus extends async.PollResultBase
    complete RelocationBatchResult
        "The copy or move batch job has finished."
    failed RelocationBatchError
        "The copy or move batch job has failed with exception."

    example default
        complete = default

union RelocationBatchLaunch extends async.LaunchResultBase

    "Result returned by :route:`copy_batch` or :route:`move_batch` that may either launch an
    asynchronous job or complete synchronously."

    complete RelocationBatchResult

    example complete
        complete = default

    example async_job_id
        async_job_id = "34g93hh34h04y384084"

struct RelocationResult
    metadata Metadata

    example default
        metadata = default

union RelocationBatchError extends RelocationError
    too_many_write_operations
        "There are too many write operations in user's Dropbox. Please retry
        this request."
#
# Copy
#

route copy (RelocationArg, Metadata, RelocationError)
    "Copy a file or folder to a different location in the user's Dropbox.

    If the source path is a folder all its contents will be copied."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true


route copy_batch (RelocationBatchArg, RelocationBatchLaunch, Void)
    "Copy multiple files or folders to different locations at once in the
    user's Dropbox.

    If :field:`RelocationBatchArg.allow_shared_folder` is false, this
    route is atomic. If on entry failes, the whole transaction will abort. If
    :field:`RelocationBatchArg.allow_shared_folder` is true, not
    atomicity is guaranteed, but you will be able to copy the contents of
    shared folders to new locations.

    This route will return job ID immediately and do the async copy job in
    background. Please use :route:`copy_batch/check` to check the job status."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

route copy_batch/check(async.PollArg, RelocationBatchJobStatus, async.PollError)
    "Returns the status of an asynchronous job for :route:`copy_batch`. If
    success, it returns list of results for each entry."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Move
#

route move (RelocationArg, Metadata, RelocationError)
    "Move a file or folder to a different location in the user's Dropbox.

    If the source path is a folder all its contents will be moved."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

route move_batch (RelocationBatchArg, RelocationBatchLaunch, Void)
    "Move multiple files or folders to different locations at once in the
    user's Dropbox.

    This route is 'all or nothing', which means if one entry fails, the
    whole transaction will abort.

    This route will return job ID immediately and do the async moving job in
    background. Please use :route:`move_batch/check` to check the job status."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

route move_batch/check(async.PollArg, RelocationBatchJobStatus, async.PollError)
    "Returns the status of an asynchronous job for :route:`move_batch`. If
    success, it returns list of results for each entry."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Thumbnail
#

union_closed ThumbnailSize
    w32h32
        "32 by 32 px."
    w64h64
        "64 by 64 px."
    w128h128
        "128 by 128 px."
    w640h480
        "640 by 480 px."
    w1024h768
        "1024 by 768."

union_closed ThumbnailFormat
    jpeg
    png

struct ThumbnailArg
    path ReadPath
        "The path to the image file you want to thumbnail."
    format ThumbnailFormat = jpeg
        "The format for the thumbnail image, jpeg (default) or png. For
         images that are photos, jpeg should be preferred, while png is
         better for screenshots and digital arts."
    size ThumbnailSize = w64h64
        "The size for the thumbnail image."

    example default
        path = "/image.jpg"
        format = jpeg

    example id
        path = "id:a4ayc_80_OEAAAAAAAAAYa"
        format = jpeg

    example rev
        path = "rev:a1c10ce0dd78"
        format = jpeg

union_closed ThumbnailError
    path LookupError
        "An error occurs when downloading metadata for the image."
    unsupported_extension
        "The file extension doesn't allow conversion to a thumbnail."
    unsupported_image
        "The image cannot be converted to a thumbnail."
    conversion_error
        "An error occurs during thumbnail conversion."

route get_thumbnail(ThumbnailArg, FileMetadata, ThumbnailError)
    "Get a thumbnail for an image.

    This method currently supports files with the following file extensions:
    jpg, jpeg, png, tiff, tif, gif and bmp. Photos that are larger than 20MB
    in size won't be converted to a thumbnail."

    attrs
        host = "content"
        style = "download"
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Preview
#

struct PreviewArg
    path ReadPath
        "The path of the file to preview."
    rev Rev?
        "Deprecated. Please specify revision in :field:`path` instead."

    example default
        path = "/word.docx"

    example id
        path = "id:a4ayc_80_OEAAAAAAAAAYa"

    example rev
        path = "rev:a1c10ce0dd78"

union_closed PreviewError
    path LookupError
        "An error occurs when downloading metadata for the file."
    in_progress
        "This preview generation is still in progress and the file is not ready
         for preview yet."
    unsupported_extension
        "The file extension is not supported preview generation."
    unsupported_content
        "The file content is not supported for preview generation."

route get_preview(PreviewArg, FileMetadata, PreviewError)
    "Get a preview for a file.

    Currently, PDF previews are generated for files with the following extensions:
    .ai, .doc, .docm, .docx, .eps, .odp, .odt, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .rtf.

    HTML previews are generated for files with the following extensions: .csv, .ods, .xls, .xlsm, .xlsx.

    Other formats will return an unsupported extension error."

    attrs
        host = "content"
        style = "download"
        owner = "dev-plat"
        allow_app_folder_app = true

#
# List revisions
#

struct ListRevisionsArg
    path PathOrId
        "The path to the file you want to see the revisions of."

    limit UInt64(min_value=1, max_value=100) = 10
        "The maximum number of revision entries returned."

    # TODO: Add last_rev when we get pagination support from FJ Service.

    example default
        path = "/root/word.docx"
        limit = 10

union ListRevisionsError
    path LookupError

struct ListRevisionsResult
    is_deleted Boolean
        "If the file is deleted."
    entries List(FileMetadata)
        "The revisions for the file. Only non-delete revisions will show up here."

    example default
        is_deleted = false
        entries = [default]

route list_revisions(ListRevisionsArg, ListRevisionsResult, ListRevisionsError)
    "Return revisions of a file."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Restore
#

struct RestoreArg
    path WritePath
        "The path to the file you want to restore."
    rev Rev
        "The revision to restore for the file."

    example default
        path = "/root/word.docx"
        rev = "a1c10ce0dd78"

union RestoreError
    path_lookup LookupError
        "An error occurs when downloading metadata for the file."
    path_write WriteError
        "An error occurs when trying to restore the file to that path."
    invalid_revision
        "The revision is invalid. It may point to a different file."

route restore(RestoreArg, FileMetadata, RestoreError)
    "Restore a file to a specific revision."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Temporary link
#

struct GetTemporaryLinkArg
    path ReadPath
        "The path to the file you want a temporary link to."

    example default
        path = "/video.mp4"

struct GetTemporaryLinkResult
    metadata FileMetadata
        "Metadata of the file."
    link String
        "The temporary link which can be used to stream content the file."

    example default
        metadata = default
        link = "https://dl.dropboxusercontent.com/apitl/1/YXNkZmFzZGcyMzQyMzI0NjU2NDU2NDU2"

union GetTemporaryLinkError
    path LookupError

route get_temporary_link(GetTemporaryLinkArg, GetTemporaryLinkResult, GetTemporaryLinkError)
    "Get a temporary link to stream content of a file. This link will expire in four hours and
    afterwards you will get 410 Gone. Content-Type of the link is determined automatically by
    the file's mime type."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Copy reference
#

struct GetCopyReferenceArg
    path ReadPath
        "The path to the file or folder you want to get a copy reference to."

    example default
        path = "/video.mp4"

struct GetCopyReferenceResult
    metadata Metadata
        "Metadata of the file or folder."
    copy_reference String
        "A copy reference to the file or folder."
    expires common.DropboxTimestamp
        "The expiration date of the copy reference. This value is currently set to be
        far enough in the future so that expiration is effectively not an issue."

    example default
        metadata = default
        copy_reference = "z1X6ATl6aWtzOGq0c3g5Ng"
        expires = "2045-05-12T15:50:38Z"

union GetCopyReferenceError
    path LookupError

route copy_reference/get(GetCopyReferenceArg, GetCopyReferenceResult, GetCopyReferenceError)
    "Get a copy reference to a file or folder. This reference string can be used to
    save that file or folder to another user's Dropbox by passing it to
    :route:`copy_reference/save`."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

struct SaveCopyReferenceArg
    copy_reference String
        "A copy reference returned by :route:`copy_reference/get`."

    path Path
        "Path in the user's Dropbox that is the destination."

    example default
        copy_reference = "z1X6ATl6aWtzOGq0c3g5Ng"
        path = "/video.mp4"

struct SaveCopyReferenceResult
    metadata Metadata
        "The metadata of the saved file or folder in the user's Dropbox."

    example default
        metadata = default

union SaveCopyReferenceError
    path WriteError
    invalid_copy_reference
        "The copy reference is invalid."
    no_permission
        "You don't have permission to save the given copy reference. Please make sure this app
        is same app which created the copy reference and the source user is still linked to
        the app."
    not_found
        "The file referenced by the copy reference cannot be found."
    too_many_files
        "The operation would involve more than 10,000 files and folders."

route copy_reference/save(SaveCopyReferenceArg, SaveCopyReferenceResult, SaveCopyReferenceError)
    "Save a copy reference returned by :route:`copy_reference/get` to the user's Dropbox."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Save URL
#

struct SaveUrlArg
    path Path
        "The path in Dropbox where the URL will be saved to."
    url String
        "The URL to be saved."

    example default
        path = "/a.txt"
        url = "http://example.com/a.txt"

union_closed SaveUrlResult extends async.LaunchResultBase
    complete FileMetadata
        "Metadata of the file where the URL is saved to."

union SaveUrlError
    path WriteError
    download_failed
        "Failed downloading the given URL."
    invalid_url
        "The given URL is invalid."
    not_found
        "The file where the URL is saved to no longer exists."

route save_url(SaveUrlArg, SaveUrlResult, SaveUrlError)
    "Save a specified URL into a file in user's Dropbox. If the given path already
    exists, the file will be renamed to avoid the conflict (e.g. myfile (1).txt)."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

#
# Save URL Job
#

union_closed SaveUrlJobStatus extends async.PollResultBase
    complete FileMetadata
        "Metadata of the file where the URL is saved to."
    failed SaveUrlError

route save_url/check_job_status(async.PollArg, SaveUrlJobStatus, async.PollError)
    "Check the status of a :route:`save_url` job."

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true