Class: Box::Account

Inherits:
Object
  • Object
show all
Defined in:
lib/box/account.rb

Overview

Represents an account on Box. In order to use the Box api, the user must first grant the application permission to use their account. This is done in the #authorize function. Once an account has been authorized, it can access all of the details and information stored on that account.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api) ⇒ Account

Creates an account object using the given Box api key. You can then #register a new account or #authorize an existing account.

Parameters:

  • api (String, Api) —

    the api key to use for the Box api.



20
21
22
23
24
25
 
# File 'lib/box/account.rb', line 20

def initialize(api)
  @api = case
    when api.class == Box::Api; api # use the api object as passed in
    else; Box::Api.new(api) # allows user to pass in a string
  end
end

Instance Attribute Details

#auth_token ⇒ String (readonly)

Returns The auth token if authorization was successful.

Returns:

  • (String) —

    The auth token if authorization was successful.



13
14
15
 
# File 'lib/box/account.rb', line 13

def auth_token
  @auth_token
end

Instance Method Details

#authorize(auth_token = nil) {|authorize_url| ... } ⇒ Boolean

Authorize the account using the given auth token, or request permission from the user to let this application use their account.

An auth token can be reused from previous authorizations provided the user doesn’t log out, and significantly speeds up the process. If the auth token if invalid or not provided, the account tries to log in normally and requires the user to log in and provide access for their account.

Examples:

Authorize an account without a saved auth token.

.authorize do |auth_url|
  puts "Please visit #{ auth_url } and enter your account infomation"
  puts "Press the enter key once you have done this."
  gets # wait for the enter key to be pressed
end

Authorize an account using an existing auth token.

auth_token = "saved auth token" # load from file ideally
.authorize(auth_token)

Combining the above two for the best functionality.

auth_token = "saved auth token" # load from file if possible
.authorize(auth_token) do |auth_url|
  # auth token was invalid or nil, have the user visit auth_url
end

Parameters:

  • auth_token (Optional, String) (defaults to: nil) —

    Uses an existing token or requests a new one if nil.

Yields:

  • (authorize_url) —

    This block called when the user has not yet granted this application permission to use their account. You must have the user navigate to the passed url and authorize this app before continuing.

Returns:

  • (Boolean) —

    Whether the user is authorized.



79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
 
# File 'lib/box/account.rb', line 79

def authorize(auth_token = nil)
  # use a saved auth token if it is given
  if auth_token
    return true if authorize_token(auth_token)
  end

  # the auth token either failed or was not provided
  # we must try to authorize a ticket, and call the block if that fails
  if not authorize_ticket and block_given?
    # the supplied block should instruct the user to visit this url
    yield authorize_url

    # try authorizing once more
    authorize_ticket
  end

  # return our authorized status
  authorized?
end

#authorized? ⇒ Boolean

Returns Is the account authorized?.

Returns:

  • (Boolean) —

    Is the account authorized?



151
152
153
 
# File 'lib/box/account.rb', line 151

def authorized?
  @info != nil
end

#info(refresh = false) ⇒ Hash

Return the account details. A cached copy will be used if avaliable, and requested if it is not.

TODO: Add url to Box api documentation, and provide the current fields.

Parameters:

  • refresh (Boolean) (defaults to: false) —

    Will not use the cached version if true.

Returns:

  • (Hash) —

    A hash containing all of the user’s account details, or nil if they are not authorized. Please see the Box api documentation for information about each field.



127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/box/account.rb', line 127

def info(refresh = false)
  return @info if @info and not refresh

  begin
    cache_info(nil) # reset existing info
    info = @api.['user']
    cache_info(info)
  rescue Api::NotAuthorized, Api::InvalidInput
    nil
  end
end

#logout ⇒ Boolean

Note:

The user will have to re-authorize if they wish to use this application, and the auth token will no longer work.

Log out of the account and invalidate the auth token.

Returns:

  • (Boolean) —

    Whether logout was successful.



106
107
108
109
110
111
112
113
114
115
 
# File 'lib/box/account.rb', line 106

def logout
  begin
    @api.logout
    cache_token(nil)
  rescue Api::NotAuthorized
    # already logged out, or never logged in
  end

  true
end

#register(email, password) ⇒ Boolean

Register a new account on the Box website with the given details.

Parameters:

  • email (String) —

    The email address to create the account with

  • password (String) —

    The password to create the account with

Returns:

  • (Boolean) —

    Whether registration was successful.

Raises:



36
37
38
39
40
41
42
43
 
# File 'lib/box/account.rb', line 36

def register(email, password)
  response = @api.register_new_user(email, password)

  cache_info(response['user']) # cache account_info, saving an extra API call
  authorize_token(response['token'])

  true
end

#root ⇒ Folder

Get the root folder of the account. You can use this Folder object to access all sub items within the account. This folder is lazy loaded, and a network request will be made if/when the data is requested.

Returns:

  • (Folder) —

    A folder object representing the root folder.



145
146
147
148
 
# File 'lib/box/account.rb', line 145

def root
  return @root if @root
  @root = Box::Folder.new(@api, nil, :id => 0)
end