Class: FranklyClient

Inherits:
Object
  • Object
show all
Defined in:
lib/frankly-ruby.rb

Overview

Instances of this class can be used to authenticate and query the Frankly REST APIs.

Instance Method Summary collapse

Constructor Details

#initialize(address = 'https://app.franklychat.com/') ⇒ FranklyClient

Returns a new instance of FranklyClient.



266
267
268
269
270
 
# File 'lib/frankly-ruby.rb', line 266

def initialize(address='https://app.franklychat.com/')
  @base_url = address
  @headers = {}
  @session_token = ''
end

Instance Method Details

#close ⇒ Object

Discards all internal state maintained by this client.



300
301
302
303
 
# File 'lib/frankly-ruby.rb', line 300

def close
  @session_token = nil
  @headers = nil
end

#create(path, params = {}, payload = {}) ⇒ Hash/Array

This method exposes a generic interface for creating objects through the Frankly API. Every create_* method is implemented on top of this one.

Parameters:

  • path (Array) —

    An Array of strings representing the collection to create an object in.

  • params (Hash) (defaults to: {}) —

    Parameters passed as part of the request.

  • payload (Hash) (defaults to: {}) —

    Dict-like object representing the object to create.

Returns:

  • (Hash/Array) —

    The method returns either a hash, or an array of hashes representing the object or objects that were created.



384
385
386
 
# File 'lib/frankly-ruby.rb', line 384

def create(path, params = {}, payload = {})
  JSON.parse Generic.create(@base_url, @headers, @session_token, path, params, payload)
end

#create_announcement(payload) ⇒ Hash

Creates a new announcement object in the app. The properties of that new announcement are given as hash to the method.

Parameters:

  • payload (Hash) —

    A hash containing the properties of the new announcement. See the Announcement section above to see how properly format this argument

Returns:

  • (Hash) —

    The method returns a hash that represents the newly created announcement.



480
481
482
 
# File 'lib/frankly-ruby.rb', line 480

def create_announcement(payload)
  JSON.parse Announcement.create_announcement(@base_url, @headers, @session_token, payload.to_json)
end

#create_file(payload) ⇒ Hash

Creates a new file object on Frankly servers and returns that object. The properties of that new file are given as a hash to the method.

Parameters:

  • payload (Hash) —

    A hash containing the properties of the new file. See the Files section above to see how properly format this argument.

Returns:

  • (Hash) —

    The method returns a hash that represents the newly created file.



570
571
572
 
# File 'lib/frankly-ruby.rb', line 570

def create_file(payload)
  JSON.parse Files.create_file(@base_url, @headers, @session_token, payload.to_json)
end

#create_room(payload) ⇒ Hash

Creates a new room object in the app. The properties of that new room are given as hash to the method.

Parameters:

  • payload (Hash) —

    A hash containing the properties of the new room. See the Rooms section above to see how properly format this argument

Returns:

  • (Hash) —

    The method returns a hash that represents the newly created room.



314
315
316
 
# File 'lib/frankly-ruby.rb', line 314

def create_room(payload)
  JSON.parse Rooms.create_room(@base_url, @headers, @session_token, payload.to_json)
end

#create_room_message(room_id, payload) ⇒ Hash

Creates a new message object in the room with id specified as first argument. The properties of that new message are given as hash to the method.

Parameters:

  • room_id (Int) —

    The identifier of the room to create the message in.

  • payload (Hash) —

    A hash containing the properties of the new message. See the Messages section above to see how properly format this argument

Returns:

  • (Hash) —

    The method returns a hash that represents the newly created message.



541
542
543
 
# File 'lib/frankly-ruby.rb', line 541

def create_room_message(room_id, payload)
  JSON.parse Message.create_room_message(@base_url, @headers, @session_token, room_id, payload)
end

#delete(path, params = {}, payload = {}) ⇒ nil

This method exposes a generic interface for deleting objects through the Frankly API. Every delete_* method is implemented on top of this one.

Parameters:

  • path (Array) —

    An Array of strings representing the collection to delete an object in.

  • params (Hash) (defaults to: {}) —

    Parameters passed as part of the request.

  • payload (Hash) (defaults to: {}) —

    A hash representing the body of the request.

Returns:

  • (nil) —

    The method doesn’t return anything on success and throws an exception on failure.



439
440
441
 
# File 'lib/frankly-ruby.rb', line 439

def delete(path, params = {}, payload = {})
  JSON.parse Generic.delete(@base_url, @headers, @session_token, path, params, payload)
end

#delete_announcement(announcement_id) ⇒ nil

Deletes an announcement object with id sepecified as first argument from the app. Note that deleting an announcement doesn’t remove messages from rooms it has already been published to. This operation cannot be undone!

Parameters:

  • announcement_id (Int) —

    The identifier of the announcement to delete.

Returns:

  • (nil) —

    The method doesn’t return anything on success and throws an exception on failure.



504
505
506
 
# File 'lib/frankly-ruby.rb', line 504

def delete_announcement(announcement_id)
  Announcement.delete_announcement(@base_url, @headers, @session_token, announcement_id)
end

#delete_room(room_id) ⇒ nil

Deletes an room object with id sepecified as first argument from the app. Note that this will cause all messages sent to this room to be deleted as well, a safer approach could be to change the room status to ‘unpublished’ to hide it without erasing data. This operation cannot be undone!

Parameters:

  • room_id (Int) —

    The identifier of the room to delete.

Returns:

  • (nil) —

    The method doesn’t return anything on success and throws an exception on failure.



365
366
367
 
# File 'lib/frankly-ruby.rb', line 365

def delete_room(room_id)
  Rooms.delete_room(@base_url, @headers, @session_token, room_id)
end

#open(app_key, app_secret) ⇒ nil

This should be the first method called on an instance of FranklyClient, after succesfully returning the client can be used to interact with the Frankly API.

Parameters:

  • app_key (String) —

    The key that specifies which app this client is authenticating for, this value is provided by the Frankly Console.

  • app_secret (String) —

    The secret value associated the the key allowing the client to securely authenticate against the Frankly API.

Returns:

  • (nil) —

    The method doesn’t return anything, it modified the internal state of the object it is called on.



290
291
292
293
294
295
296
297
 
# File 'lib/frankly-ruby.rb', line 290

def open(app_key, app_secret)
  nonce = Auth.nonce(@base_url)[1..-2]

  identity_token = generate_identity_token(app_key, app_secret, nonce, nil, 'admin')
  session = JSON.parse Auth.open(@base_url, identity_token)
  @session_token = session['token']
  @headers = Util.build_headers
end

#read(path, params = {}, payload = {}) ⇒ Hash/Array

This method exposes a generic interface for reading objects through the Frankly API. Every read_* method is implemented on top of this one.

Parameters:

  • path (Array) —

    An Array of strings representing the collection to read an object in.

  • params (Hash) (defaults to: {}) —

    Parameters passed as part of the request.

  • payload (Hash) (defaults to: {}) —

    Dict-like object representing the object to create.

Returns:

  • (Hash/Array) —

    The method returns the object read from the API at the specified path.



402
403
404
 
# File 'lib/frankly-ruby.rb', line 402

def read(path, params = {}, payload = {})
  JSON.parse Generic.read(@base_url, @headers, @session_token, path, params, payload)
end

#read_announcement(announcement_id) ⇒ Hash

Retrieves an announcement object with id sepecified as first argument from the app.

Parameters:

  • announcement_id (Int) —

    The identifier of the announcement to fetch.

Returns:

  • (Hash) —

    The method returns a hash representing the announcement wit the specified id in the app.



491
492
493
 
# File 'lib/frankly-ruby.rb', line 491

def read_announcement(announcement_id)
  JSON.parse Announcement.read_announcement(@base_url, @headers, @session_token, announcement_id)
end

#read_announcement_list ⇒ Array

Retrieves a list of announcements available in the app.

Returns:

  • (Array) —

    The method returns an array of annoucement hashes ordered by id, which may be empty if there are no announcements in the app.



513
514
515
 
# File 'lib/frankly-ruby.rb', line 513

def read_announcement_list
  JSON.parse Announcement.read_announcement_list(@base_url, @headers, @session_token)
end

#read_announcement_room_list(announcement_id) ⇒ Array

Retrieves the list of rooms that an annoucement has been published to.

Parameters:

  • announcement_id (Int) —

    The identifier of the announcement to get the list of rooms for.

Returns:

  • (Array) —

    The method returns a list of room objects ordered by id, which may be empty if the announcement haven’t been published yet.



525
526
527
 
# File 'lib/frankly-ruby.rb', line 525

def read_announcement_room_list(announcement_id)
  JSON.parse Announcement.read_announcement_room_list(@base_url, @headers, @session_token, announcement_id)
end

#read_room(room_id) ⇒ Hash

Retrieves a room object with id specified as first argument from the app.

Parameters:

  • room_id (Int) —

    The identifier of the room to fetch.

Returns:

  • (Hash) —

    The method returns a hash that represents the fetched room.



334
335
336
 
# File 'lib/frankly-ruby.rb', line 334

def read_room(room_id)
  JSON.parse Rooms.read_room(@base_url, @headers, @session_token, room_id)
end

#read_room_list ⇒ Array

Retrieves the list of all available rooms from the app.

Returns:

  • (Array) —

    The method returns a list of hashes ordered by id, which may be empty if there are no rooms in the app.



323
324
325
 
# File 'lib/frankly-ruby.rb', line 323

def read_room_list
  JSON.parse Rooms.read_room_list(@base_url, @headers, @session_token)
end

#read_room_message_list(room_id, params) ⇒ Array

Creates a new message object in the room with id specified as first argument. The properties of that new message are given as hash to the method.

Parameters:

  • room_id (Int) —

    The identifier of the room to create the message in.

  • params (Hash) —

    A hash that defines the range of the messages that are fetched. See the Messages section above to see how properly format this argument.

Returns:

  • (Array) —

    The method returns an array of room hashes which may be empty if no messages satisfy the query.



557
558
559
 
# File 'lib/frankly-ruby.rb', line 557

def read_room_message_list(room_id, params)
  JSON.parse Message.read_room_message_list(@base_url, @headers, @session_token, room_id, params)
end

#update(path, params = {}, payload = {}) ⇒ Hash/Array

This method exposes a generic interface for updating objects through the Frankly API. Every read_* method is implemented on top of this one.

Parameters:

  • path (Array) —

    An Array of strings representing the collection to read an object in.

  • params (Hash) (defaults to: {}) —

    Parameters passed as part of the request.

  • payload (Hash) (defaults to: {}) —

    Dict-like object representing the object to create.

Returns:

  • (Hash/Array) —

    The method returns the object updated on the API at the specified path.



420
421
422
 
# File 'lib/frankly-ruby.rb', line 420

def update(path, params = {}, payload = {})
  JSON.parse Generic.update(@base_url, @headers, @session_token, path, params, payload)
end

#update_file(destination_url, file_obj, file_size, mime_type, encoding = nil) ⇒ nil

Creates a new file object on Frankly servers and returns that object. The properties of that new file are given as a hash to the method.

Parameters:

  • destination_url (String) —

    The URL at which the file is hosted on Frankly servers. This can be obtained from the url field of an object returned by create_file for example.

  • file_obj (File) —

    A file-like object (as returned by File.open(…, “rb”) for example) providing the new content of the file.

  • file_size (Int) —

    The size of the new file content (in bytes).

  • mime_type (String) —

    The mime type of the new file content.

  • encoding (String) (defaults to: nil) —

    The encoding of the new file content (‘gzip’ for example).

Returns:

  • (nil) —

    The method doesn’t return anything on success and throws an exception on failure.



596
597
598
 
# File 'lib/frankly-ruby.rb', line 596

def update_file(destination_url, file_obj, file_size, mime_type, encoding = nil)
  Files.upload_file(@base_url, @headers, @session_token, destination_url, file_obj, file_size, mime_type, encoding)
end

#update_file_from_path(destination_url, file_path) ⇒ nil

Creates a new file object on Frankly servers and returns that object. The properties of that new file are given as a hash to the method.

Parameters:

  • destination_url (String) —

    The URL at which the file is hosted on Frankly servers. This can be obtained from the url field of an object returned by create_file for example.

  • file_path (String) —

    A path to a local providing the new file content

Returns:

  • (nil) —

    The method doesn’t return anything on success and throws an exception on failure.



612
613
614
 
# File 'lib/frankly-ruby.rb', line 612

def update_file_from_path(destination_url, file_path)
  Files.update_file_from_path(@base_url, @headers, @session_token, destination_url, file_path)
end

#update_room(room_id, payload) ⇒ Hash

Updates an existing room object in the app and return that object. The properties of that new room are given as a hash to the method.

Parameters:

  • room_id (Integer) —

    The identifier of the room to update.

  • payload (Hash) —

    A hash containing the properties of the new room. See the Rooms section above to see how properly format this argument

Returns:

  • (Hash) —

    The method returns a hash that represents the newly updated room.



350
351
352
353
 
# File 'lib/frankly-ruby.rb', line 350

def update_room(room_id, payload)
  JSON.parse Rooms.update_room(@base_url, @headers, @session_token,
                               room_id, payload.to_json)
end

#upload(url, params, payload, content_length, content_type, content_encoding) ⇒ nil

This method exposes a generic interface for uploading file contents through the Frankly API. Every upload_* method is implemented on top of this one.

Parameters:

  • url (String) —

    The URL at which the file is hosted on Frankly servers. This can be obtained from the url field of an object returned by create_file for example.

  • params (Hash) —

    Parameters passed as part of the request.

  • payload (Hash) —

    A hash representing the body of the request.

  • content_length (Int) —

    The size of the new file content (in bytes).

  • content_type (String) —

    The mime type of the new file content.

  • content_encoding (String) —

    The encoding of the new file content (‘gzip’ for example).

Returns:

  • (nil) —

    The method doesn’t return anything on success and throws an exception on failure.



467
468
469
 
# File 'lib/frankly-ruby.rb', line 467

def upload(url, params, payload, content_length, content_type, content_encoding)
  JSON.parse Generic.upload(@base_url, @headers, @session_token, url, params, payload, content_length, content_type, content_encoding)
end

#upload_file(file_obj, file_size, mime_type, encoding = nil, params) ⇒ Hash

This method is convenience wrapper for creating a new file object on the Frankly API and setting its content.

Parameters:

  • file_obj (File) —

    A file-like object (as returned by File.open(…, “rb”) for example) providing the new content of the file.

  • file_size (Int) —

    The size of the new file content (in bytes).

  • mime_type (String) —

    The mime type of the new file content.

  • encoding (String) (defaults to: nil) —

    The encoding of the new file content (‘gzip’ for example).

  • params (Hash) —

    A hash containing the properties of the new file. See the Files section above to see how properly format this argument.

Returns:

  • (Hash) —

    The method returns a hash that represents the newly created file.



637
638
639
 
# File 'lib/frankly-ruby.rb', line 637

def upload_file(file_obj, file_size, mime_type, encoding = nil, params)
  Files.upload_file(@base_url, @headers, @session_token, destination_url, file_obj, file_size, mime_type, encoding, params)
end

#upload_file_from_path(file_path, params) ⇒ Hash

This method is convenience wrapper for creating a new file object on the Frankly API and setting its content.

Parameters:

  • file_path (String) —

    A path to a local providing the new file content

  • params (Hash) —

    A hash containing the properties of the new file. See the Files section above to see how properly format this argument.

Returns:

  • (Hash) —

    The method returns a hash that represents the newly created file.



652
653
654
 
# File 'lib/frankly-ruby.rb', line 652

def upload_file_from_path(file_path, params)
  Files.upload_file_from_path(@base_url, @headers, @session_token, file_path, params)
end