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

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(sym, *args, &block) ⇒ Object

Provides an easy way to access this account’s info.

Examples:

. # returns @info['login']


216
217
218
219
220
221
222
223
224
225
 
# File 'lib/box/account.rb', line 216

def method_missing(sym, *args, &block)
  super unless authorized?

  # TODO: Use symbols instead of strings
  str = sym.to_s

  return @info[str] if @info.key?(str)

  super
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(details = nil) {|authorize_url| ... } ⇒ Boolean

Authorize the account using the given auth token/ticket, 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.

A ticket can be used for applications that do not block on the user, such as a website, where specifying a redirection url is not possible.

In order to maintain backwards compatibility, a ticket can only be specified in the hash syntax, while an auth token can be used in either the hash or string syntax.

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 => auth_token)

Combining the above two for the best functionality.

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

Parameters:

  • details (Optional, String, Hash{:ticket,:auth_token => String}) (defaults to: nil) —

    Uses an existing auth token or ticket. If nil, a new ticket will be generated and used. If a String, it is assumed to be an auth_token (depreciated). If a Hash, then any values of the :ticket and :auth_token keys will be used to authenticate.

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.



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
 
# File 'lib/box/account.rb', line 89

def authorize(details = nil)
  # for backwards compatibility
  if details.is_a?(Hash)
    auth_token = details[:auth_token]
    ticket = details[:ticket]
  else
    auth_token = details
    ticket = nil
  end

  # 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(ticket) and block_given?
    # the supplied block should instruct the user to visit this url
    yield authorize_url(ticket)

    # try authorizing once more
    authorize_ticket(ticket)
  end

  # return our authorized status
  authorized?
end

#authorized? ⇒ Boolean

Returns Is the account authorized?.

Returns:

  • (Boolean) —

    Is the account authorized?



202
203
204
 
# File 'lib/box/account.rb', line 202

def authorized?
  @info != nil
end

#file(id) ⇒ Object

Note:

This file will not know its parent because of API short-comings. If you need the tree above this file, use root.find(:type => ‘file’, :id => id).first instead.

Note:

This function will return a file regardless of whether it actually exists. You will get exceptions if you try to access any info.

Gets a file object by id.

Parameters:

  • id (String) —

    The id of the folder to fetch.



197
198
199
 
# File 'lib/box/account.rb', line 197

def file(id)
  Box::File.new(@api, nil, :id => id)
end

#folder(id) ⇒ Object

Note:

This folder will not know its parent because of API short-comings. If you need the tree above this folder, use root.find(:type => ‘folder’, :id => id).first instead.

Note:

This function will return a folder regardless of whether it actually exists. You will get exceptions if you try to access any info.

Gets a folder object by id.

Parameters:

  • id (String) —

    The id of the folder to fetch.



181
182
183
 
# File 'lib/box/account.rb', line 181

def folder(id)
  Box::Folder.new(@api, nil, :id => id)
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.



146
147
148
149
150
151
152
153
154
155
156
 
# File 'lib/box/account.rb', line 146

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.



125
126
127
128
129
130
131
132
133
134
 
# File 'lib/box/account.rb', line 125

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

#respond_to?(sym) ⇒ Boolean

Returns:

  • (Boolean) 


227
228
229
 
# File 'lib/box/account.rb', line 227

def respond_to?(sym)
  @info.key?(sym.to_s) or super
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.



164
165
166
167
 
# File 'lib/box/account.rb', line 164

def root
  return @root if @root
  @root = folder(0)
end

#ticket ⇒ String

Get the cached ticket or request a new one from the Box api.

Returns:

  • (String) —

    The authorization ticket.



208
209
210
 
# File 'lib/box/account.rb', line 208

def ticket
  @ticket ||= @api.get_ticket['ticket']
end