users.stone

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

import common

import team_policies

import users_common

#
# Route: get_account
#

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

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

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 e-mail 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 e-mail."
    email_verified Boolean
        "Whether the user has verified their e-mail 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/dbid%3AAAH4f99T0taONIb-OurWxbNQ6ywGRopQngc?vers=1453416582218&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/dbid%3AAAH4f99T0taONIb-OurWxbNQ6ywGRopQngc?vers=1453416696524&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/dbid%3AAAH4f99T0taONIb-OurWxbNQ6ywGRopQngc?vers=1453416696524&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
        owner = "dev-plat"
        allow_app_folder_app = true

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."

    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

    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/dbid%3AAAH4f99T0taONIb-OurWxbNQ6ywGRopQngc?vers=1453416673259&size=128x128"
        disabled = false

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."

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

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"

#
# Route: get_space_usage
#

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

    attrs
        owner = "dev-plat"
        allow_app_folder_app = true

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)."

    example default
        used = 27182818284
        allocated = 100000000000

#
# 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
        owner = "dev-plat"
        allow_app_folder_app = true

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"