CiscoSpark

Ruby client for Cisco Spark.

Add this line to your application's Gemfile:

gem 'cisco_spark'

And then execute:

$ bundle

Or install it yourself as:

$ gem install cisco_spark

Configuration can be done in an initializer on app boot. An API key or users OAuth token is required to make any API requests.

API key example:

CiscoSpark.configure do |config|
  config.api_key = 'YOUR KEY'
end

If you are using OAuth token you can wrap API operaions in a block, all API calls within the block will then use that token.

OAuth token example:

CiscoSpark.with_token('OAuth token') do
  users_rooms = CiscoSpark::Room.fetch_all
end

All models have methods to interact with the API and parse response data.

Inlcuded models:

• CiscoSpark::Person
• CiscoSpark::Room
• CiscoSpark::Membership
• CiscoSpark::Message
• CiscoSpark::Team
• CiscoSpark::TeamMembership
• CiscoSpark::Webhook

You can call all the following methods on any of these models

Fetches all records for a given model, returns a CiscoSpark::Collection Accepts any parameters that the API allows.

rooms = CiscoSpark::Room.fetch_all(max: 5)
=> #<CiscoSpark::Collection>

Fetches a single record for the given resource ID, returns an instance Accepts any parameters that the API allows.

room = CiscoSpark::Room.fetch('Y2lzY...', show_sip_address: true)
=> #<CiscoSpark::Room>

Creates a resource with given attribues, returns an instance Accepts any parameters that the API allows.

room = CiscoSpark::Room.create(title: 'Ruby Room')
=> #<CiscoSpark::Room>

Updates a resource with given attribues, returns an instance Accepts any parameters that the API allows.

room = CiscoSpark::Room.update('Y2lzY...', title: 'Groovey Ruby Room')
=> #<CiscoSpark::Room>

Destroys a resource with the given ID, returns an boolean to indicate success Accepts any parameters that the API allows.

room = CiscoSpark::Room.destroy('Y2lzY...')
=> true

Parses a valid JSON string or a ruby hash/array into a collection of models. This is useful for processing data recieved from a webhook etc.

json_string = '{"items": [{ "id": "Y2lzY...", "key": "value" }]}'
rooms = CiscoSpark::Room.parse_collection(json_string)
=> #<CiscoSpark::Collection>

Parses a valid JSON string or a ruby hash/array into a model. This is useful for processing data recieved from a webhook etc.

json_string = '{ "id": "Y2lzY...", "key": "value" }'
room = CiscoSpark::Room.parse(json_string)
=> #<CiscoSpark::Room>

Creates a new instance of the model with given attributes

room = CiscoSpark::Room.new(title: 'New room')
=> #<CiscoSpark::Room>

You can call persist on an instance to create or update it through the API. If the instance already has an ID a PUT will be made to update the mutable attributes

room = CiscoSpark::Room.new(title: 'New room')
room.persist
=> #<CiscoSpark::Room>

You can call fetch on an instance fetch or refresh an instance

room = CiscoSpark::Room.new(id: 'Y2lzY...')
room.fetch
=> #<CiscoSpark::Room>

You can call destroy on an instance to destroy it through the API

room = CiscoSpark::Room.new(id: 'Y2lzY...')
room.destroy
=> true

Convert a model instance into a hash

room = CiscoSpark::Room.fetch('Y2lzY...')
room.to_h
=> Hash

API reference

Search all people by email,

people = CiscoSpark::Person.all_by_email('nickpmaher@gmail.com', max: 5)
=> #<CiscoSpark::Collection>

Search all people by display name

people = CiscoSpark::Person.all_by_name('Nick', max: 5)
=> #<CiscoSpark::Collection>

Get all memberships for person

person = CiscoSpark::Person.new(id: 'Y2lz...')
person.memberships(max: 5)
=> #<CiscoSpark::Collection>

API reference

Get all memberships for room

room = CiscoSpark::Room.new(id: 'Y3de...')
room.memberships(max: 5)
=> #<CiscoSpark::Collection>

Get all messages for room

room = CiscoSpark::Room.new(id: 'Y3de...')
room.messages(max: 5)
=> #<CiscoSpark::Collection>

Get all message before a given message, accepts a CiscoSpark::Message or a message ID

room.all_before_message('Y3de...', max: 5)
=> #<CiscoSpark::Collection>

Get all message before a given time, accepts a DateTime or a string

room.messages_before(DateTime.now, max: 5)
=> #<CiscoSpark::Collection>

Send a message to the room

message = CiscoSpark::Message.new(text: 'Hello Spark')

room = CiscoSpark::Room.new(id: 'Y3de...')
room.send_message(message)
=> #<CiscoSpark::Message>

Creates a new membership to the room for a given person

person = CiscoSpark::Person.fetch('Y2lz')

room = CiscoSpark::Room.new(id: 'Y3de...')
room.add_person(person)
=> #<CiscoSpark::Membership>

API reference

Returns the person for this membership

Returns the room this membership belongs to

API reference

Returns the person that sent this message

Returns the person that the message was sent to

API reference

Get all memberships for team

team = CiscoSpark::Team.new(id: 'Y3de...')
team.memberships(max: 5)
=> #<CiscoSpark::Collection>

Creates a new membership to the team for a given person

person = CiscoSpark::Person.fetch('Y2lz')

team = CiscoSpark::Team.new(id: 'Y3de...')
team.add_person(person)
=> #<CiscoSpark::TeamMembership>

API reference

Returns the person for this membership

Returns the team this membership belongs to

API reference

Wraps a collection of models. Responds to all enumerable methods e.g. first, map, each etc...

Call next on a collection to load the next page of data

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Bug reports and pull requests are welcome on GitHub at https://github.com/NGMarmaduke/cisco_spark-ruby.

The gem is available as open source under the terms of the MIT License.