team_folders.stone

namespace team

import async
import common
import files

# Common structs

union TeamFolderStatus
    active
        "The team folder and sub-folders are available to all members."
    archived
        "The team folder is not accessible outside of the team folder manager."
    archive_in_progress
        "The team folder is not accessible outside of the team folder manager."

struct TeamFolderIdArg
    team_folder_id common.SharedFolderId
        "The ID of the team folder."

    example default
        team_folder_id = "123456789"

struct TeamFolderIdListArg
    team_folder_ids List(common.SharedFolderId, min_items=1)
        "The list of team folder IDs."

    example default
        team_folder_ids = ["947182", "5819424", "852307532"]

struct TeamFolderMetadata
    "Properties of a team folder."

    team_folder_id common.SharedFolderId
        "The ID of the team folder."

    name String
        "The name of the team folder."

    status TeamFolderStatus
        "The status of the team folder."

    is_team_shared_dropbox Boolean
        "True if this team folder is a shared team root."

    sync_setting files.SyncSetting
        "The sync setting applied to this team folder."

    content_sync_settings List(files.ContentSyncSetting)
        "Sync settings applied to contents of this team folder."

    example default
        name = "Marketing"
        team_folder_id = "123456789"
        status = active
        is_team_shared_dropbox = false
        sync_setting = default
        content_sync_settings = [default]

union TeamFolderAccessError
    invalid_team_folder_id
        "The team folder ID is invalid."
    no_access
        "The authenticated app does not have permission to manage that team folder."

union TeamFolderInvalidStatusError
    active
        "The folder is active and the operation did not succeed."
    archived
        "The folder is archived and the operation did not succeed."
    archive_in_progress
        "The folder is being archived and the operation did not succeed."

union TeamFolderTeamSharedDropboxError
    disallowed
        "This action is not allowed for a shared team root."

union BaseTeamFolderError
    "Base error that all errors for existing team folders should extend."
    access_error TeamFolderAccessError
    status_error TeamFolderInvalidStatusError
    team_shared_dropbox_error TeamFolderTeamSharedDropboxError

#
# Team folder create
#

route team_folder/create(TeamFolderCreateArg, TeamFolderMetadata, TeamFolderCreateError)
    "Creates a new, active, team folder with no members. This endpoint can only be used for teams
    that do not already have a shared team space.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.write"

struct TeamFolderCreateArg
    name String
        "Name for the new team folder."

    sync_setting files.SyncSettingArg?
        "The sync setting to apply to this team folder. Only permitted if the team has team selective sync enabled."

    example default
        name = "Marketing"
        sync_setting = not_synced

union TeamFolderCreateError
    invalid_folder_name
        "The provided name cannot be used."
    folder_name_already_used
        "There is already a team folder with the provided name."
    folder_name_reserved
        "The provided name cannot be used because it is reserved."
    sync_settings_error files.SyncSettingsError
        "An error occurred setting the sync settings."

#
# Team folder rename
#

route team_folder/rename(TeamFolderRenameArg, TeamFolderMetadata, TeamFolderRenameError)
    "Changes an active team folder's name.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.write"

struct TeamFolderRenameArg extends TeamFolderIdArg
    name String
        "New team folder name."

    example default
        team_folder_id = "123456789"
        name = "Sales"

union TeamFolderRenameError extends BaseTeamFolderError
    invalid_folder_name
        "The provided folder name cannot be used."
    folder_name_already_used
        "There is already a team folder with the same name."
    folder_name_reserved
        "The provided name cannot be used because it is reserved."

#
# Team folder list
#

route team_folder/list(TeamFolderListArg, TeamFolderListResult, TeamFolderListError)
    "Lists all team folders.

    Permission : Team member file access."
    attrs
        auth = "team"
        scope = "team_data.content.read"

struct TeamFolderListArg
    limit UInt32(min_value=1, max_value=1000) = 1000
        "The maximum number of results to return per request."

    example default
        limit = 100

struct TeamFolderListResult
    "Result for :route:`team_folder/list` and :route:`team_folder/list/continue`."

    team_folders List(TeamFolderMetadata)
        "List of all team folders in the authenticated team."
    cursor String
        "Pass the cursor into :route:`team_folder/list/continue` to obtain additional team folders."
    has_more Boolean
        "Is true if there are additional team folders that have not been returned
        yet. An additional call to :route:`team_folder/list/continue` can retrieve them."

    example default
        team_folders = [default]
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"
        has_more = false

struct TeamFolderListError
    access_error TeamFolderAccessError

#
# Team folder list/continue
#

route team_folder/list/continue(TeamFolderListContinueArg, TeamFolderListResult, TeamFolderListContinueError)
    "Once a cursor has been retrieved from :route:`team_folder/list`, use this to paginate
    through all team folders.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.read"

struct TeamFolderListContinueArg
    cursor String
        "Indicates from what point to get the next set of team folders."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

union TeamFolderListContinueError
    invalid_cursor
        "The cursor is invalid."

#
# Team folder get info
#

route team_folder/get_info(TeamFolderIdListArg, List(TeamFolderGetInfoItem), Void)
    "Retrieves metadata for team folders.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.read"

union_closed TeamFolderGetInfoItem
    id_not_found String
        "An ID that was provided as a parameter to :route:`team_folder/get_info` did not
        match any of the team's team folders."
    team_folder_metadata TeamFolderMetadata
        "Properties of a team folder."

#
# Team folder activate
#

route team_folder/activate(TeamFolderIdArg, TeamFolderMetadata, TeamFolderActivateError)
    "Sets an archived team folder's status to active.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.write"

union TeamFolderActivateError extends BaseTeamFolderError
    ""

#
# Team folder archive
#

route team_folder/archive(TeamFolderArchiveArg, TeamFolderArchiveLaunch, TeamFolderArchiveError)
    "Sets an active team folder's status to archived and removes all folder and file members.
    This endpoint cannot be used for teams that have a shared team space.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.write"

struct TeamFolderArchiveArg extends TeamFolderIdArg
    force_async_off Boolean = false
        "Whether to force the archive to happen synchronously."

    example default
        team_folder_id = "123456789"
        force_async_off = false

union_closed TeamFolderArchiveLaunch extends async.LaunchResultBase
    complete TeamFolderMetadata

    example default
        complete = default

    example async_job_id
        async_job_id = "34g93hh34h04y384084"

union TeamFolderArchiveError extends BaseTeamFolderError
    ""

route team_folder/archive/check(async.PollArg, TeamFolderArchiveJobStatus, async.PollError)
    "Returns the status of an asynchronous job for archiving a team folder.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.write"

union_closed TeamFolderArchiveJobStatus extends async.PollResultBase
    complete TeamFolderMetadata
        "The archive job has finished. The value is the metadata for the resulting team folder."
    failed TeamFolderArchiveError
        "Error occurred while performing an asynchronous job from :route:`team_folder/archive`."

    example default
        complete = default

#
# Team folder permanently delete
#

route team_folder/permanently_delete(TeamFolderIdArg, Void, TeamFolderPermanentlyDeleteError)
    "Permanently deletes an archived team folder. This endpoint cannot be used for teams
    that have a shared team space.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "team_data.content.write"

union TeamFolderPermanentlyDeleteError extends BaseTeamFolderError
    ""

#
# Team folder update_sync_settings
#

struct TeamFolderUpdateSyncSettingsArg extends TeamFolderIdArg
    sync_setting files.SyncSettingArg?
        "Sync setting to apply to the team folder itself. Only meaningful if the team folder is not a shared team root."

    content_sync_settings List(files.ContentSyncSettingArg)?
        "Sync settings to apply to contents of this team folder."

    example default
        team_folder_id = "123456789"
        sync_setting = default
        content_sync_settings = [default]

union TeamFolderUpdateSyncSettingsError extends BaseTeamFolderError
    sync_settings_error files.SyncSettingsError
        "An error occurred setting the sync settings."

route team_folder/update_sync_settings(TeamFolderUpdateSyncSettingsArg, TeamFolderMetadata, TeamFolderUpdateSyncSettingsError)
    "Updates the sync settings on a team folder or its contents.  Use of this endpoint requires that the team has team selective sync enabled."

    attrs
        auth = "team"
        scope = "team_data.content.write"