users.stone

namespace users
    "This namespace contains endpoints and data types for user management."

import common

import team_common

import team_policies

import users_common

#
# Route: get_account
#

route get_account (GetAccountArg, BasicAccount, GetAccountError)
    "Get information about a user's account."

    attrs
        allow_app_folder_app = true
        scope = "sharing.read"

struct GetAccountArg
    account_id users_common.AccountId
        "A user's account identifier."

    example default
        account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"

union GetAccountError
    no_account
        "The specified :field:`GetAccountArg.account_id` does not exist."

struct Account
    "The amount of detail revealed about an account depends on the user
    being queried and the user making the query."

    account_id users_common.AccountId
        "The user's unique Dropbox ID."

    name Name
        "Details of a user's name."

    email String
        "The user's email address. Do not rely on this without checking the
        :field:`email_verified` field. Even then, it's possible that the user
        has since lost access to their email."

    email_verified Boolean
        "Whether the user has verified their email address."

    profile_photo_url String?
        "URL for the photo representing the user, if one is set."

    disabled Boolean
        "Whether the user has been disabled."

    example default
        account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        name = default
        email = "franz@dropbox.com"
        email_verified = true
        profile_photo_url = "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"
        disabled = false

struct BasicAccount extends Account
    "Basic information about any account."

    is_teammate Boolean
        "Whether this user is a teammate of the current user. If this account
        is the current user's account, then this will be :val:`true`."

    team_member_id String?
        "The user's unique team member id. This field will only be present if
        the user is part of a team and :field:`is_teammate` is :val:`true`."

    example default
        account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        name = default
        email = "franz@dropbox.com"
        email_verified = true
        profile_photo_url = "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"
        is_teammate = false
        disabled = false

    example team
        account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        name = default
        email = "franz@dropbox.com"
        email_verified = true
        profile_photo_url = "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"
        is_teammate = true
        team_member_id = "dbmid:AAHhy7WsR0x-u4ZCqiDl5Fz5zvuL3kmspwU"
        disabled = false
#
# Route: get_current_account
#

route get_current_account (Void, FullAccount, Void)
    "Get information about the current user's account."

    attrs
        allow_app_folder_app = true
        select_admin_mode = "whole_team"
        scope = "account_info.read"

struct FullAccount extends Account
    "Detailed information about the current user's account."

    country String(min_length=2, max_length=2)?
        "The user's two-letter country code, if available. Country codes are
        based on :link:`ISO 3166-1 http://en.wikipedia.org/wiki/ISO_3166-1`."
    locale String(min_length=2)
        "The language that the user specified. Locale tags will be
        :link:`IETF language tags http://en.wikipedia.org/wiki/IETF_language_tag`."
    referral_link String
        "The user's :link:`referral link https://www.dropbox.com/referrals`."
    team FullTeam?
        "If this account is a member of a team, information about that team."
    team_member_id String?
        "This account's unique team member id. This field will only be present if
        :field:`team` is present."
    is_paired Boolean
        "Whether the user has a personal and work account. If the current
        account is personal, then :field:`team` will always be :val:`null`,
        but :field:`is_paired` will indicate if a work account is linked."
    account_type users_common.AccountType
        "What type of account this user has."
    root_info common.RootInfo
        "The root info for this account."

    example default
        "Paired account."
        account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        name = default
        email = "franz@dropbox.com"
        email_verified = true
        country = "US"
        locale = "en"
        referral_link = "https://db.tt/ZITNuhtI"
        team = default
        team_member_id = "dbmid:AAHhy7WsR0x-u4ZCqiDl5Fz5zvuL3kmspwU"
        is_paired = true
        account_type = business
        disabled = false
        root_info = default

    example unpaired
        "A personal account that is not paired with a team."
        account_id = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"
        name = default
        email = "franz@gmail.com"
        email_verified = false
        country = "US"
        locale = "en"
        referral_link = "https://db.tt/ZITNuhtI"
        team = null
        is_paired = false
        account_type = default
        profile_photo_url = "https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128"
        disabled = false
        root_info = default

struct Team
    "Information about a team."

    id String
        "The team's unique ID."
    name String
        "The name of the team."

    example default
        id = "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"
        name = "Acme, Inc."

struct FullTeam extends Team
    "Detailed information about a team."

    sharing_policies team_policies.TeamSharingPolicies
        "Team policies governing sharing."

    office_addin_policy team_policies.OfficeAddInPolicy
        "Team policy governing the use of the Office Add-In."

    example default
        id = "dbtid:AAFdgehTzw7WlXhZJsbGCLePe8RvQGYDr-I"
        name = "Acme, Inc."
        sharing_policies = default
        office_addin_policy = disabled

struct Name
    "Representations for a person's name to assist with internationalization."

    given_name String
        "Also known as a first name."

    surname String
        "Also known as a last name or family name."

    familiar_name String
        "Locale-dependent name. In the US, a person's familiar name is their
        :field:`given_name`, but elsewhere, it could be any combination of a
        person's :field:`given_name` and :field:`surname`."

    display_name String
        "A name that can be used directly to represent the name of a user's
        Dropbox account."

    abbreviated_name String
        "An abbreviated form of the person's name. Their initials in most locales."

    example default
        given_name = "Franz"
        surname = "Ferdinand"
        familiar_name = "Franz"
        display_name = "Franz Ferdinand (Personal)"
        abbreviated_name = "FF"

    example second_name
        given_name = "Zexy Desperado"
        surname = "Desperado"
        familiar_name = "Zexy"
        display_name = "Zexy Desperado (Personal)"
        abbreviated_name = "ZD"

#
# Route: get_space_usage
#

route get_space_usage(Void, SpaceUsage, Void)
    "Get the space usage information for the current user's account."

    attrs
        allow_app_folder_app = true
        scope = "account_info.read"

struct SpaceUsage
    "Information about a user's space usage and quota."

    used UInt64
        "The user's total space usage (bytes)."
    allocation SpaceAllocation
        "The user's space allocation."

    example default
        used = 314159265
        allocation = default

union SpaceAllocation
    "Space is allocated differently based on the type of account."

    individual IndividualSpaceAllocation
        "The user's space allocation applies only to their individual account."
    team TeamSpaceAllocation
        "The user shares space with other members of their team."

    example default
        individual = default

struct IndividualSpaceAllocation
    allocated UInt64
        "The total space allocated to the user's account (bytes)."

    example default
        allocated = 10000000000

struct TeamSpaceAllocation
    used UInt64
        "The total space currently used by the user's team (bytes)."
    allocated UInt64
        "The total space allocated to the user's team (bytes)."
    user_within_team_space_allocated UInt64
        "The total space allocated to the user within its team allocated space (0 means that
        no restriction is imposed on the user's quota within its team)."
    user_within_team_space_limit_type team_common.MemberSpaceLimitType
        "The type of the space limit imposed on the team member (off, alert_only, stop_sync)."
    user_within_team_space_used_cached UInt64
        "An accurate cached calculation of a team member's total space usage (bytes)."

    example default
        used = 27182818284
        allocated = 100000000000
        user_within_team_space_allocated = 2000000000
        user_within_team_space_limit_type = stop_sync
        user_within_team_space_used_cached = 314159265

#
# Route: get_account_batch
#

route get_account_batch (GetAccountBatchArg, GetAccountBatchResult, GetAccountBatchError)
    "Get information about multiple user accounts.  At most 300 accounts may be queried
    per request."

    attrs
        allow_app_folder_app = true
        scope = "sharing.read"

struct GetAccountBatchArg
    account_ids List(users_common.AccountId, min_items=1)
        "List of user account identifiers.  Should not contain any duplicate account IDs."

    example default
        account_ids = ["dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc", "dbid:AAH1Vcz-DVoRDeixtr_OA8oUGgiqhs4XPOQ"]

alias GetAccountBatchResult = List(BasicAccount)

union GetAccountBatchError
    no_account users_common.AccountId
        "The value is an account ID specified in :field:`GetAccountBatchArg.account_ids`
        that does not exist."

    example default
        no_account = "dbid:AAH4f99T0taONIb-OurWxbNQ6ywGRopQngc"

#
# User Features
#

union UserFeature
    "A set of features that a Dropbox User account may have configured."

    paper_as_files
        "This feature contains information about how the user's Paper files are stored."

    file_locking
        "This feature allows users to lock files in order to restrict other users from editing them."


union UserFeatureValue
    "Values that correspond to entries in :type:`UserFeature`."

    paper_as_files PaperAsFilesValue
    file_locking FileLockingValue

    example paper_as_files_enabled
        paper_as_files = paper_as_files_enabled

union PaperAsFilesValue
    "The value for :field:`UserFeature.paper_as_files`.  "

    enabled Boolean
        "When this value is true, the user's Paper docs are accessible in Dropbox with the .paper
        extension and must be accessed via the /files endpoints.  When this value is
        false, the user's Paper docs are stored separate from Dropbox files and folders and should
        be accessed via the /paper endpoints."

    example paper_as_files_enabled
        enabled = true

union FileLockingValue
    "The value for :field:`UserFeature.file_locking`.  "

    enabled Boolean
        "When this value is True, the user can lock files in shared directories. When the value is
        False the user can unlock the files they have locked or request to unlock files locked by
        others."

    example file_locking_enabled
        enabled = true
#
# Route: feature/get_value_batch
#

struct UserFeaturesGetValuesBatchArg
    features List(UserFeature)
        "A list of features in :type:`UserFeature`. If the list is empty,
        this route will return :type:`UserFeaturesGetValuesBatchError`."

    example listOfFeatures
        features = [paper_as_files, file_locking]

struct UserFeaturesGetValuesBatchResult
    values List(UserFeatureValue)

    example listOfValues
        values = [paper_as_files_enabled]

union UserFeaturesGetValuesBatchError
    empty_features_list
        "At least one :type:`UserFeature` must be included in the
        :type:`UserFeaturesGetValuesBatchArg`.features list."

route features/get_values(UserFeaturesGetValuesBatchArg, UserFeaturesGetValuesBatchResult, UserFeaturesGetValuesBatchError)
    "Get a list of feature values that may be configured for the current account."

    attrs
        allow_app_folder_app = true
        scope = "account_info.read"