namespace team

import common

#
# Structs for devices/list_member_devices
#

struct ListMemberDevicesArg
    team_member_id String
        "The team's member id."
    include_web_sessions Boolean = true
        "Whether to list web sessions of the team's member."
    include_desktop_clients Boolean = true
        "Whether to list linked desktop devices of the team's member."
    include_mobile_clients Boolean = true
        "Whether to list linked mobile devices of the team's member."

    example default
        team_member_id="dbmid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"

struct DeviceSession
    session_id String
        "The session id."

    ip_address String?
        "The IP address of the last activity from this session."

    country String?
        "The country from which the last activity from this session was made."

    created common.DropboxTimestamp?
        "The time this session was created."

    updated common.DropboxTimestamp?
        "The time of the last activity from this session."

# TODO(gal) - for mobile, camera uploads don't count for updated activity (See T25556
# for more context). This needs to be documented somewhere.

struct ActiveWebSession extends DeviceSession
    "Information on active web sessions."

    user_agent String
        "Information on the hosting device."

    os String
        "Information on the hosting operating system."

    browser String
        "Information on the browser used for this web session."

    expires common.DropboxTimestamp?
        "The time this session expires."

    example default
        session_id = "dbwsid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"
        ip_address = "3.3.3.3"
        country = "United States"
        created = "2015-05-12T15:50:38Z"
        updated = "2015-05-12T15:51:22Z"
        user_agent = "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/535.1 (KHTML, like Gecko) Chrome/14.0.815.0 Safari/535.1"
        os = "Windows"
        browser = "Chrome"
        expires = "2015-05-13T15:51:22Z"

union DesktopPlatform
    windows
        "Official Windows Dropbox desktop client."
    mac
        "Official Mac Dropbox desktop client."
    linux
        "Official Linux Dropbox desktop client."

struct DesktopClientSession extends DeviceSession
    "Information about linked Dropbox desktop client sessions."

    host_name String
        "Name of the hosting desktop."

    client_type DesktopPlatform
        "The Dropbox desktop client type."

    client_version String
        "The Dropbox client version."

    platform String
        "Information on the hosting platform."

    is_delete_on_unlink_supported Boolean
        "Whether it's possible to delete all of the account files upon unlinking."

    example default
        session_id= "dbdsid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"
        ip_address = "3.3.3.3"
        country = "United States"
        created = "2015-05-12T15:50:38Z"
        updated = "2015-05-12T15:51:22Z"
        host_name = "Home_desktop"
        client_type = mac
        client_version = "3.9.19"
        platform = "Mac OS X 10.10.3"
        is_delete_on_unlink_supported = true

union MobileClientPlatform
    iphone
        "Official Dropbox iPhone client."
    ipad
        "Official Dropbox iPad client."
    android
        "Official Dropbox Android client."
    windows_phone
        "Official Dropbox Windows phone client."
    blackberry
        "Official Dropbox Blackberry client."

struct MobileClientSession extends DeviceSession
    "Information about linked Dropbox mobile client sessions."

    device_name String
        "The device name."

    client_type MobileClientPlatform
        "The mobile application type."

    client_version String?
        "The dropbox client version."

    os_version String?
        "The hosting OS version."

    last_carrier String?
        "last carrier used by the device."

    example default
        session_id = "dbmsid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"
        ip_address = "3.3.3.3"
        country = "United States"
        created = "2015-05-12T15:50:38Z"
        updated = "2015-05-12T15:51:22Z"
        device_name = "Iphone 6"
        client_type = iphone
        client_version = "3.9.5"
        os_version = "8.4"
        last_carrier = "Verizon"

struct ListMemberDevicesResult
    active_web_sessions List(ActiveWebSession)?
        "List of web sessions made by this team member."
    desktop_client_sessions List(DesktopClientSession)?
        "List of desktop clients used by this team member."
    mobile_client_sessions List(MobileClientSession)?
        "List of mobile client used by this team member."

union ListMemberDevicesError
    member_not_found
        "Member not found."

#
# Route: devices/list_member_devices
#

route devices/list_member_devices(ListMemberDevicesArg, ListMemberDevicesResult, ListMemberDevicesError)
    "List all device sessions of a team's member."

    attrs
        auth = "team"
        scope = "sessions.list"

#
# Structs for devices/list_members_devices
#

struct ListMembersDevicesArg
    cursor String?
        "At the first call to the :route:`devices/list_members_devices` the cursor shouldn't be passed.
        Then, if the result of the call includes a cursor, the following requests should include the
        received cursors in order to receive the next sub list of team devices."
    include_web_sessions Boolean = true
        "Whether to list web sessions of the team members."
    include_desktop_clients Boolean = true
        "Whether to list desktop clients of the team members."
    include_mobile_clients Boolean = true
        "Whether to list mobile clients of the team members."

struct MemberDevices
    "Information on devices of a team's member."

    team_member_id String
        "The member unique Id."
    web_sessions List(ActiveWebSession)?
        "List of web sessions made by this team member."
    desktop_clients List(DesktopClientSession)?
        "List of desktop clients by this team member."
    mobile_clients List(MobileClientSession)?
        "List of mobile clients by this team member."

    example default
        team_member_id = "dbmid:AAHhy7WsR0x-u4ZCqiDl5Fz5zvuL3kmspwU"

struct ListMembersDevicesResult
    devices List(MemberDevices)
        "The devices of each member of the team."
    has_more Boolean
        "If true, then there are more devices available. Pass the
        cursor to :route:`devices/list_members_devices` to retrieve the rest."
    cursor String?
        "Pass the cursor into :route:`devices/list_members_devices` to receive the next
        sub list of team's devices."

union ListMembersDevicesError
    reset
        "Indicates that the cursor has been invalidated. Call
        :route:`devices/list_members_devices` again with an empty cursor to obtain a new cursor."

#
# Route: devices/list_members_devices
#
route devices/list_members_devices(ListMembersDevicesArg, ListMembersDevicesResult, ListMembersDevicesError)
    "List all device sessions of a team.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "sessions.list"

#
# Structs for devices/revoke_device_session
#

struct DeviceSessionArg
    session_id String
        "The session id."
    team_member_id String
        "The unique id of the member owning the device."

    example default
        session_id = "1234faaf0678bcde"
        team_member_id = "dbmid:AAHhy7WsR0x-u4ZCqiDl5Fz5zvuL3kmspwU"

struct RevokeDesktopClientArg extends DeviceSessionArg
    delete_on_unlink Boolean = false
        "Whether to delete all files of the account (this is possible only if supported by
        the desktop client and  will be made the next time the client access the account)."

    example default
        session_id = "1234faaf0678bcde"
        team_member_id = "dbmid:AAHhy7WsR0x-u4ZCqiDl5Fz5zvuL3kmspwU"

union_closed RevokeDeviceSessionArg
    web_session DeviceSessionArg
        "End an active session."
    desktop_client RevokeDesktopClientArg
        "Unlink a linked desktop device."
    mobile_client DeviceSessionArg
        "Unlink a linked mobile device."

    example default
        web_session = default

union RevokeDeviceSessionError
    device_session_not_found
        "Device session not found."
    member_not_found
        "Member not found."

#
# Route: devices/revoke_device_session
#

route devices/revoke_device_session(RevokeDeviceSessionArg, Void, RevokeDeviceSessionError)
    "Revoke a device session of a team's member."

    attrs
        auth = "team"
        scope = "sessions.modify"

#
# structs for devices/revoke_device_session_batch
#

struct RevokeDeviceSessionBatchArg
    revoke_devices List(RevokeDeviceSessionArg)

    example default
        revoke_devices = [default]

struct RevokeDeviceSessionStatus

    success Boolean
        "Result of the revoking request."
    error_type RevokeDeviceSessionError?
        "The error cause in case of a failure."

struct RevokeDeviceSessionBatchResult
    revoke_devices_status List(RevokeDeviceSessionStatus)

union RevokeDeviceSessionBatchError
    ""

#
# Route: devices/revoke_device_session_batch
#

route devices/revoke_device_session_batch(RevokeDeviceSessionBatchArg, RevokeDeviceSessionBatchResult, RevokeDeviceSessionBatchError)
    "Revoke a list of device sessions of team members."

    attrs
        auth = "team"
        scope = "sessions.modify"


#
# Deprecated endpoints
#

struct ListTeamDevicesArg
    cursor String?
        "At the first call to the :route:`devices/list_team_devices` the cursor shouldn't be passed.
        Then, if the result of the call includes a cursor, the following requests should include the
        received cursors in order to receive the next sub list of team devices."
    include_web_sessions Boolean = true
        "Whether to list web sessions of the team members."
    include_desktop_clients Boolean = true
        "Whether to list desktop clients of the team members."
    include_mobile_clients Boolean = true
        "Whether to list mobile clients of the team members."

    example default
        cursor = "ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu"

struct ListTeamDevicesResult
    devices List(MemberDevices)
        "The devices of each member of the team."
    has_more Boolean
        "If true, then there are more devices available. Pass the
        cursor to :route:`devices/list_team_devices` to retrieve the rest."
    cursor String?
        "Pass the cursor into :route:`devices/list_team_devices` to receive the next
        sub list of team's devices."

    example default
        devices = [default]
        has_more = false

union ListTeamDevicesError
    reset
        "Indicates that the cursor has been invalidated. Call
        :route:`devices/list_team_devices` again with an empty cursor to obtain a new cursor."

route devices/list_team_devices(ListTeamDevicesArg, ListTeamDevicesResult, ListTeamDevicesError) deprecated by devices/list_members_devices
    "List all device sessions of a team.

    Permission : Team member file access."

    attrs
        auth = "team"
        scope = "sessions.list"