file_requests.stone

namespace file_requests
    "This namespace contains endpoints and data types for file request operations."


alias FileRequestId = String(pattern="[-_0-9a-zA-Z]+", min_length=1)

import common
import files

#
# Common file requests objects
#

union GracePeriod
    one_day
    two_days
    seven_days
    thirty_days
    always

    example default
        seven_days = null

struct FileRequestDeadline

    deadline common.DropboxTimestamp
        "The deadline for this file request."
    allow_late_uploads GracePeriod?
        "If set, allow uploads after the deadline has passed. These
            uploads will be marked overdue."

    example deadline
        deadline = "2020-10-12T17:00:00Z"

    example deadline_with_grace_period
        deadline = "2020-10-12T17:00:00Z"
        allow_late_uploads = seven_days

struct FileRequest
    "A :link:`file request https://www.dropbox.com/help/9090` for receiving
    files into the user's Dropbox account."

    id FileRequestId
        "The ID of the file request."
    url String(min_length=1)
        "The URL of the file request."
    title String(min_length=1)
        "The title of the file request."
    destination files.Path?
        "The path of the folder in the Dropbox where uploaded files will be
        sent. This can be :val:`null` if the destination was removed. For apps
        with the app folder permission, this will be relative to the app
        folder."
    created common.DropboxTimestamp
        "When this file request was created."
    deadline FileRequestDeadline?
        "The deadline for this file request. Only set if the request has a
        deadline."
    is_open Boolean
        "Whether or not the file request is open. If the file request is
        closed, it will not accept any more file submissions."
    file_count Int64
        "The number of files this file request has received."
    description String?
        "A description of the file request."

    example default
        id = "oaCAVmEyrqYnkZX9955Y"
        url = "https://www.dropbox.com/request/oaCAVmEyrqYnkZX9955Y"
        title = "Homework submission"
        destination = "/File Requests/Homework"
        created = "2015-10-05T17:00:00Z"
        deadline = deadline_with_grace_period
        is_open = true
        file_count = 3
        description = "Please submit your homework here."

    example with_deadline
        id = "BAJ7IrRGicQKGToykQdB"
        url = "https://www.dropbox.com/request/BAJ7IrRGjcQKGToykQdB"
        title = "Photo contest submission"
        destination = "/Photo contest entries"
        created = "2015-11-02T04:00:00Z"
        deadline = deadline
        is_open = true
        file_count = 105

    example with_no_deadline
        id = "rxwMPvK3ATTa0VxOJu5T"
        url = "https://www.dropbox.com/request/rxwMPvK3ATTa0VxOJu5T"
        title = "Wedding photo submission"
        destination = "/Wedding photos"
        created = "2015-12-15T13:02:00Z"
        deadline = null
        is_open = true
        file_count = 37

alias FileRequestValidationError = String?

union GeneralFileRequestsError
    "There is an error accessing the file requests functionality."

    disabled_for_team
        "This user's Dropbox Business team doesn't allow file requests."

union FileRequestError extends GeneralFileRequestsError
    "There is an error with the file request."

    not_found
        "This file request ID was not found."
    not_a_folder
        "The specified path is not a folder."
    app_lacks_access
        "This file request is not accessible to this app. Apps with the app
        folder permission can only access file requests in their app folder."
    no_permission
        "This user doesn't have permission to access or modify this file
        request."
    email_unverified
        "This user's email address is not verified. File requests are only
        available on accounts with a verified email address. Users can verify
        their email address :link:`here https://www.dropbox.com/help/317`."
    validation_error
        "There was an error validating the request. For example, the title was
        invalid, or there were disallowed characters in the destination path."

#
# Getting file requests
#

route list:2(ListFileRequestsArg, ListFileRequestsV2Result, ListFileRequestsError)
    "Returns a list of file requests owned by this user. For apps with the app
    folder permission, this will only return file requests with destinations in
    the app folder."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.read"

struct ListFileRequestsArg
    "Arguments for :route:`list:2`."

    limit UInt64 = 1000
        "The maximum number of file requests that should be returned per request."

    example default
        limit = 1000

struct ListFileRequestsV2Result
    "Result for :route:`list:2` and :route:`list/continue`."

    file_requests List(FileRequest)
        "The file requests owned by this user. Apps with the app folder
        permission will only see file requests in their app folder."

    cursor String
        "Pass the cursor into :route:`list/continue` to obtain additional file requests."

    has_more Boolean
        "Is true if there are additional file requests that have not been returned
        yet. An additional call to :route:list/continue` can retrieve them."

    example default
        file_requests = [default, with_deadline, with_no_deadline]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
        has_more = true

route list/continue(ListFileRequestsContinueArg, ListFileRequestsV2Result, ListFileRequestsContinueError)
    "Once a cursor has been retrieved from :route:`list:2`, use this to paginate through all
    file requests. The cursor must come from a previous call to :route:`list:2` or
    :route:`list/continue`."
    attrs
        allow_app_folder_app = true
        scope = "file_requests.read"

struct ListFileRequestsContinueArg
    cursor String
        "The cursor returned by the previous API call specified in the endpoint description."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

union ListFileRequestsContinueError extends GeneralFileRequestsError
    "There was an error retrieving the file requests."

    invalid_cursor
        "The cursor is invalid."


route list(Void, ListFileRequestsResult, ListFileRequestsError)
    "Returns a list of file requests owned by this user. For apps with the app
    folder permission, this will only return file requests with destinations in
    the app folder."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.read"

struct ListFileRequestsResult
    "Result for :route:`list`."

    file_requests List(FileRequest)
        "The file requests owned by this user. Apps with the app folder
        permission will only see file requests in their app folder."

    example default
        file_requests = [default, with_deadline, with_no_deadline]

union ListFileRequestsError extends GeneralFileRequestsError
    "There was an error retrieving the file requests."


#
# Getting individual file requests
#

route get(GetFileRequestArgs, FileRequest, GetFileRequestError)
    "Returns the specified file request."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.read"

struct GetFileRequestArgs
    "Arguments for :route:`get`."

    id FileRequestId
        "The ID of the file request to retrieve."

    example default
        id = "oaCAVmEyrqYnkZX9955Y"

union GetFileRequestError extends FileRequestError
    "There was an error retrieving the specified file request."


#
# Creating new file requests
#

route create(CreateFileRequestArgs, FileRequest, CreateFileRequestError)
    "Creates a file request for this user."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.write"

struct CreateFileRequestArgs
    "Arguments for :route:`create`."

    title String(min_length=1)
        "The title of the file request. Must not be empty."
    destination files.Path
        "The path of the folder in the Dropbox where uploaded files will be
        sent. For apps with the app folder permission, this will be relative to
        the app folder."
    deadline FileRequestDeadline?
        "The deadline for the file request. Deadlines can only be set by
        Professional and Business accounts."
    open Boolean = true
        "Whether or not the file request should be open. If the file request is
        closed, it will not accept any file submissions, but it can be opened
        later."
    description String?
        "A description of the file request."

    example default
        title = "Homework submission"
        destination = "/File Requests/Homework"
        deadline = deadline_with_grace_period

union CreateFileRequestError extends FileRequestError
    "There was an error creating the file request."

    invalid_location
        "File requests are not available on the specified folder."
    rate_limit
        "The user has reached the rate limit for creating file requests. The
        limit is currently 4000 file requests total."

#
# Updating existing file requests
#

route update(UpdateFileRequestArgs, FileRequest, UpdateFileRequestError)
    "Update a file request."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.write"

struct UpdateFileRequestArgs
    "Arguments for :route:`update`."

    id FileRequestId
        "The ID of the file request to update."
    title String(min_length=1)?
        "The new title of the file request. Must not be empty."
    destination files.Path?
        "The new path of the folder in the Dropbox where uploaded files will be
        sent. For apps with the app folder permission, this will be relative to
        the app folder."
    deadline UpdateFileRequestDeadline = no_update
        "The new deadline for the file request. Deadlines can only be set by
        Professional and Business accounts."
        union
            no_update
                "Do not change the file request's deadline."
            update FileRequestDeadline?
                "If :val:`null`, the file request's deadline is cleared."

            example set_deadline
                update = deadline_with_grace_period
    open Boolean?
        "Whether to set this file request as open or closed."
    description String?
        "The description of the file request."

    example default
        id = "oaCAVmEyrqYnkZX9955Y"
        title = "Homework submission"
        destination = "/File Requests/Homework"
        deadline = set_deadline
        open = true

union UpdateFileRequestError extends FileRequestError
    "There is an error updating the file request."

#
# Count file requests
#

route count(Void, CountFileRequestsResult, CountFileRequestsError)
    "Returns the total number of file requests owned by this user. Includes both open and
    closed file requests."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.read"

struct CountFileRequestsResult
    "Result for :route:`count`."

    file_request_count UInt64
        "The number file requests owner by this user."

    example default
        file_request_count = 15

union CountFileRequestsError extends GeneralFileRequestsError
    "There was an error counting the file requests."

#
# Deleting existing file requests
#

route delete(DeleteFileRequestArgs, DeleteFileRequestsResult, DeleteFileRequestError)
    "Delete a batch of closed file requests."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.write"

struct DeleteFileRequestArgs
    "Arguments for :route:`delete`."

    ids List(FileRequestId)
        "List IDs of the file requests to delete."

    example default
        ids = ["oaCAVmEyrqYnkZX9955Y", "BaZmehYoXMPtaRmfTbSG"]

struct DeleteFileRequestsResult
    "Result for :route:`delete`."

    file_requests List(FileRequest)
        "The file requests deleted by the request."

    example default
        file_requests = [default, with_deadline, with_no_deadline]

union DeleteFileRequestError extends FileRequestError
    "There was an error deleting these file requests."

    file_request_open
        "One or more file requests currently open."

#
# Deleting all closed file requests
#

route delete_all_closed(Void, DeleteAllClosedFileRequestsResult, DeleteAllClosedFileRequestsError)
    "Delete all closed file requests owned by this user."

    attrs
        allow_app_folder_app = true
        scope = "file_requests.write"

struct DeleteAllClosedFileRequestsResult
    "Result for :route:`delete_all_closed`."

    file_requests List(FileRequest)
        "The file requests deleted for this user."

    example default
        file_requests = [default, with_deadline, with_no_deadline]

union DeleteAllClosedFileRequestsError extends FileRequestError
    "There was an error deleting all closed file requests."