Class: Camdram::Client

Inherits:
Object
  • Object
show all
Includes:
API, Utils
Defined in:
lib/camdram/client.rb

Instance Method Summary collapse

Constructor Details

#initialize {|_self| ... } ⇒ Camdram::Client

Initializes a new Client object using a block

Yields:

  • (_self)

Yield Parameters:

Raises:


29
30
31
32
33
34
# File 'lib/camdram/client.rb', line 29

def initialize
  @client_instance = self.object_id
  raise Camdram::Error::Misconfigured.new('Camdram::Client instantiated without config block') unless block_given?
  yield(self)
  raise Camdram::Error::Misconfigured.new('Camdram::Client instantiated with an invalid config block') unless http.mode
end

Instance Method Details

#access_tokenHash

Returns the current Camdram OAuth2 access token

Returns:

  • (Hash)

    A hash representing the current access token.


70
71
72
# File 'lib/camdram/client.rb', line 70

def access_token
  http.access_token.to_hash
end

#access_token_expiring_soon?Boolean

Returns true if the Camdram OAuth2 access token is about to expire

Returns:

  • (Boolean)

    True if the access token expires within the next thirty second.


85
86
87
# File 'lib/camdram/client.rb', line 85

def access_token_expiring_soon?
  http.access_token_expiring_soon?
end

#applicationsArray

Gets an array of producer/director roles and show applications advertised on Camdram

Returns:

  • (Array)

    An array of Application objects.


291
292
293
294
295
# File 'lib/camdram/client.rb', line 291

def applications
  url = '/vacancies/applications.json'
  response = get(url)
  split_object( response, Application )
end

#auditionsArray

Gets an array of actor auditions listed on Camdram

Returns:

  • (Array)

    An array of Audition objects.


273
274
275
276
277
# File 'lib/camdram/client.rb', line 273

def auditions
  url = '/vacancies/auditions.json'
  response = get(url)
  split_object( response, Audition )
end

#auth_code(token_hash, app_id, app_secret, &block) ⇒ Object

Setup the API backend to use the authorisation code OAuth2 strategy

Parameters:

  • token_hash (Hash)

    A hash of the access token, refresh token and expiry Unix time

  • app_id (String)

    The API client application identifier.

  • app_secret (String)

    The API client application secret.

  • block (Proc)

    The Faraday connection builder.


56
57
58
# File 'lib/camdram/client.rb', line 56

def auth_code(token_hash, app_id, app_secret, &block)
  http.auth_code(token_hash, app_id, app_secret, &block)
end

#base_urlString

Returns the root URL that each API request is sent to

Returns:

  • (String)

    The hostname & protocol to send API requests to.


115
116
117
# File 'lib/camdram/client.rb', line 115

def base_url
  http.base_url
end

#base_url=(url) ⇒ String

Sets the API URL that each HTTP request is sent to

Parameters:

  • url (String)

    The API hostname to send requests to.

Returns:

  • (String)

    The url itself.


108
109
110
# File 'lib/camdram/client.rb', line 108

def base_url=(url)
  http.base_url = url
end

#client_credentials(app_id, app_secret, &block) ⇒ Object

Setup the API backend to use the client credentials OAuth2 strategy

Parameters:

  • app_id (String)

    The API client application identifier.

  • app_secret (String)

    The API client application secret.

  • block (Proc)

    The Faraday connection builder.


46
47
48
# File 'lib/camdram/client.rb', line 46

def client_credentials(app_id, app_secret, &block)
  http.client_credentials(app_id, app_secret, &block)
end

#diary(start_date = nil, end_date = nil) ⇒ Camdram::Diary

Gets a diary object which contains an array of upcoming calendar events

Returns:


250
251
252
253
254
255
256
257
# File 'lib/camdram/client.rb', line 250

def diary(start_date=nil, end_date=nil)
  url = "/diary.json"
  if start_date && end_date
    url = "/diary/#{start_date}.json?end=#{end_date}"
  end
  response = get(url)
  Diary.new(response, @client_instance)
end

#disable_auto_token_renewalObject

Disables automatic renewal of expired API access tokens


120
121
122
# File 'lib/camdram/client.rb', line 120

def disable_auto_token_renewal
  http.disable_auto_token_renewal
end

#get_peopleArray

Returns an array containing a sample of people taking part in shows this week

Returns:

  • (Array)

    An array of Role objects.


231
232
233
234
235
# File 'lib/camdram/client.rb', line 231

def get_people
  url = "#{Person.url}.json"
  response = get(url)
  split_object( response, Person )
end

#get_person(id) ⇒ Camdram::Person

Lookup a person by their ID or slug

Parameters:

  • id (Integer)

    The numeric ID of the person.

  • id (String)

    The person's slug.

Returns:

Raises:

  • (ArgumentError)

    Error raised when an integer or string is not provided.


197
198
199
200
201
202
203
204
205
206
207
208
# File 'lib/camdram/client.rb', line 197

def get_person(id)
  url = nil
  if id.is_a? Integer
    url = "#{Person.url}/by-id/#{id}.json"
  elsif id.is_a? String
    url = "#{Person.url}/#{id}.json"
  else
    raise ArgumentError.new 'id must be an integer, or slug must be a string'
  end
  response = get(url)
  Person.new(response, @client_instance)
end

#get_show(id) ⇒ Camdram::Show

Lookup a show by its ID or slug

Parameters:

  • id (Integer)

    The numeric ID of the show.

  • id (String)

    The slug of the show.

Returns:

Raises:

  • (ArgumentError)

    Error raised when an integer or string is not provided.


140
141
142
143
144
145
146
147
148
149
150
151
# File 'lib/camdram/client.rb', line 140

def get_show(id)
  url = nil
  if id.is_a? Integer
    url = "#{Show.url}/by-id/#{id}.json"
  elsif id.is_a? String
    url = "#{Show.url}/#{id}.json"
  else
    raise ArgumentError.new 'id must be an integer, or slug must be a string'
  end
  response = get(url)
  return Show.new(response, @client_instance)
end

#get_societiesArray

Returns an array of all registered societies

Returns:

  • (Array)

    An array of Society objects.


213
214
215
216
217
# File 'lib/camdram/client.rb', line 213

def get_societies
  url = "#{Society.url}.json"
  response = get(url)
  split_object( response, Society )
end

#get_society(id) ⇒ Camdram::Society

Lookup a society by its ID or slug

Parameters:

  • id (Integer)

    The numeric ID of the society.

  • id (String)

    The slug of the society.

Returns:

Raises:

  • (ArgumentError)

    Error raised when an integer or string is not provided.


159
160
161
162
163
164
165
166
167
168
169
170
# File 'lib/camdram/client.rb', line 159

def get_society(id)
  url = nil
  if id.is_a? Integer
    url = "#{Society.url}/by-id/#{id}.json"
  elsif id.is_a? String
    url = "#{Society.url}/#{id}.json"
  else
    raise ArgumentError.new 'id must be an integer, or slug must be a string'
  end
  response = get(url)
  Society.new(response, @client_instance)
end

#get_venue(id) ⇒ Camdram::Venue

Lookup a venue by its ID or slug

Parameters:

  • id (Integer)

    The numeric ID of the venue.

  • id (String)

    The slug of the venue.

Returns:

Raises:

  • (ArgumentError)

    Error raised when an integer or string is not provided.


178
179
180
181
182
183
184
185
186
187
188
189
# File 'lib/camdram/client.rb', line 178

def get_venue(id)
  url = nil
  if id.is_a? Integer
    url = "#{Venue.url}/by-id/#{id}.json"
  elsif id.is_a? String
    url = "#{Venue.url}/#{id}.json"
  else
    raise ArgumentError.new 'id must be an integer, or slug must be a string'
  end
  response = get(url)
  Venue.new(response, @client_instance)
end

#get_venuesArray

Returns an array of all registered venues

Returns:

  • (Array)

    An array of Venue objects.


222
223
224
225
226
# File 'lib/camdram/client.rb', line 222

def get_venues
  url = "#{Venue.url}.json"
  response = get(url)
  split_object( response, Venue )
end

#read_only(&block) ⇒ Object

Note:

It is highly recommended that applications authenticate when making Camdram API calls.

Setup the API backend in read-only mode

Parameters:

  • block (Proc)

    The Faraday connection builder.


63
64
65
# File 'lib/camdram/client.rb', line 63

def read_only(&block)
  http.auth_code({access_token: nil}, nil, nil, &block)
end

#refresh_access_token!Hash

Attempts to refreshes the current Camdram OAuth2 access token

Returns:

  • (Hash)

    A hash representing the new access token.

Raises:

  • (RuntimeError)

    Raised if a refresh token is not available.


78
79
80
# File 'lib/camdram/client.rb', line 78

def refresh_access_token!
  http.refresh!.to_hash
end

#search(query, limit = 10, page = 1) ⇒ Array

Return an array of search entity results based on a search string

Parameters:

  • query (String)

    The query string to search with.

Returns:

  • (Array)

    An array of Search objects.


241
242
243
244
245
# File 'lib/camdram/client.rb', line 241

def search(query, limit=10, page=1)
  url = "/search.json?q=#{query}&limit=#{limit}&page=#{page}"
  response = get(url)
  split_object( response, Search )
end

#techie_advertsArray

Gets an array of technical & designer roles advertised on Camdram

Returns:

  • (Array)

    An array of TechieAdvert objects.


282
283
284
285
286
# File 'lib/camdram/client.rb', line 282

def techie_adverts
  url = '/vacancies/techies.json'
  response = get(url)
  split_object( response, TechieAdvert )
end

#termly_diary(year, term = nil) ⇒ Camdram::Diary

Gets a diary object which contains an array of events occuring in the given year/term

Returns:


262
263
264
265
266
267
268
# File 'lib/camdram/client.rb', line 262

def termly_diary(year, term=nil)
  url = "/diary/#{year}"
  url += "/#{term}" if term
  url += ".json"
  response = get(url)
  Diary.new(response, @client_instance)
end

#time_periods(year = Date.today.year.to_s) ⇒ Array

Gets an array of time periods as defined on Camdram

Returns:

  • (Array)

    An array of TimePeriod objects.


300
301
302
303
304
# File 'lib/camdram/client.rb', line 300

def time_periods(year = Date.today.year.to_s)
  url = "/time-periods/#{year}.json"
  response = get(url)
  split_object( response, TimePeriod )
end

#userCamdram::User

Returns the user associated with the API token if set, otherwise raises an exception

Returns:

Raises:

  • (StandardError)

    Error raised when the API token is not set.


128
129
130
131
132
# File 'lib/camdram/client.rb', line 128

def user
  slug = "/auth/account.json"
  response = get(slug)
  User.new(response, @client_instance)
end

#user_agentString

Returns the user agent HTTP header sent with each API request

Returns:

  • (String)

    The user agent header to send with API requests.


100
101
102
# File 'lib/camdram/client.rb', line 100

def user_agent
  http.user_agent
end

#user_agent=(agent) ⇒ String

Sets the user agent header sent in each HTTP request

Parameters:

  • agent (String)

    The user agent header to send with HTTP requests.

Returns:

  • (String)

    The agent string itself.


93
94
95
# File 'lib/camdram/client.rb', line 93

def user_agent=(agent)
  http.user_agent = agent
end