cisco_spark 0.2.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b49c8a731f17def9f8f8bad7e5a14105fc9e5e4
-  data.tar.gz: 84999b34944fc0f22f6e07e8148d011208de6011
+  metadata.gz: 9e7bab6e1d7eb7f898297f5f1c350a800e9bfcb7
+  data.tar.gz: 2fba2068d4a125b24ddca0808a7e49981281083b
 SHA512:
-  metadata.gz: 572138fbffa7e999a58f628ded5555cc6b578a841e5f3153d93a7182622cf8e4d338a0a640f37923af9687b03fb6a76312a38cf0ad4e47cfc9ffefbf1c49e607
-  data.tar.gz: 873fa97d1be88c0343c6a881b8e77a9550b310d037e1d95cdd90e9183a44c6b04f8d723e76880d76a57874a7d8eabc936d66437a5e42cda8d9a8cfed123b2517
+  metadata.gz: 153091bc0d40028cdddcb87c33cc987d28d630bf05ce34ab7e75ab370992cbe448f547650388116fa351ad9d769ba98987b9513ae6d040af61297bd5aa31efa7
+  data.tar.gz: be05e4a6bc6e80d85322993b3c2b9974b3671f7e05a2ca25d4d00af7f9e3486c457e4b74e185c37174e702b07f52763c2012371709dd0f1dea5a2446020c20c5

data/README.md

@@ -2,9 +2,7 @@
 [![Build Status](https://travis-ci.org/NGMarmaduke/cisco_spark-ruby.svg?branch=master)](https://travis-ci.org/NGMarmaduke/cisco_spark-ruby)
 [![Coverage Status](https://coveralls.io/repos/github/NGMarmaduke/cisco_spark-ruby/badge.svg?branch=master)](https://coveralls.io/github/NGMarmaduke/cisco_spark-ruby?branch=master)
 
-Ruby SDK for [Cisco Spark](https://developer.ciscospark.com).
-
-Work in progress currently
+Ruby client for [Cisco Spark](https://developer.ciscospark.com).
 
 ## Installation
 
@@ -24,13 +22,257 @@ Or install it yourself as:
 
 ## Usage
 
-WIP
+### Configuration
+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:
+```ruby
+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:
+```ruby
+CiscoSpark.with_token('OAuth token') do
+  users_rooms = CiscoSpark::Room.fetch_all
+end
+```
+
+### Models
+All models have methods to interact with the API and parse response data
+
+###### `klass.fetch_all`
+Fetches all records for a given model, returns a `CiscoSpark::Collection`
+Accepts any parameters that the API allows.
+
+```ruby
+rooms = CiscoSpark::Room.fetch_all(max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+###### `klass.fetch`
+Fetches a single record for the given resource ID, returns an instance
+Accepts any parameters that the API allows.
+
+```ruby
+room = CiscoSpark::Room.fetch('Y2lzY...', show_sip_address: true)
+=> #<CiscoSpark::Room>
+```
+
+###### `klass.create`
+Creates a resource with given attribues, returns an instance
+Accepts any parameters that the API allows.
+
+```ruby
+room = CiscoSpark::Room.create(title: 'Ruby Room')
+=> #<CiscoSpark::Room>
+```
+
+###### `klass.update`
+Updates a resource with given attribues, returns an instance
+Accepts any parameters that the API allows.
+
+```ruby
+room = CiscoSpark::Room.update('Y2lzY...', title: 'Groovey Ruby Room')
+=> #<CiscoSpark::Room>
+```
+
+###### `klass.detroy`
+Destroys a resource with the given ID, returns an boolean to indicate success
+Accepts any parameters that the API allows.
+
+```ruby
+room = CiscoSpark::Room.destroy('Y2lzY...')
+=> true
+```
+
+###### `klass.parse_collection`
+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.
+
+```ruby
+json_string = '{"items": [{ "id": "Y2lzY...", "key": "value" }]}'
+rooms = CiscoSpark::Room.parse_collection(json_string)
+=> #<CiscoSpark::Collection>
+```
+
+###### `klass.parse`
+Parses a valid JSON string or a ruby hash/array into a model.
+This is useful for processing data recieved from a webhook etc.
+
+```ruby
+json_string = '{ "id": "Y2lzY...", "key": "value" }'
+room = CiscoSpark::Room.parse(json_string)
+=> #<CiscoSpark::Room>
+```
+
+###### `klass.new`
+Creates a new instance of the model with given attributes
+
+```ruby
+room = CiscoSpark::Room.new(title: 'New room')
+=> #<CiscoSpark::Room>
+```
+
+###### `instance.persist`
+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
+
+```ruby
+room = CiscoSpark::Room.new(title: 'New room')
+room.persist
+=> #<CiscoSpark::Room>
+```
+
+###### `instance.fetch`
+You can call fetch on an instance fetch or refresh an instance
+
+```ruby
+room = CiscoSpark::Room.new(id: 'Y2lzY...')
+room.fetch
+=> #<CiscoSpark::Room>
+```
+
+###### `instance.destroy`
+You can call destroy on an instance to destroy it through the API
+
+```ruby
+room = CiscoSpark::Room.new(id: 'Y2lzY...')
+room.destroy
+=> true
+```
+
+###### `instance.to_h`
+Convert a model instance into a hash
+
+```ruby
+room = CiscoSpark::Room.fetch('Y2lzY...')
+room.to_h
+=> Hash
+```
+
+##### `CiscoSpark::Person`
+[API reference](https://developer.ciscospark.com/resource-people.html)
+
+###### `CiscoSpark::Person.all_by_email`
+Search all people by email, 
+
+```ruby
+people = CiscoSpark::Person.all_by_email('nickpmaher@gmail.com', max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+###### `CiscoSpark::Person.all_by_name`
+Search all people by display name
+
+```ruby
+people = CiscoSpark::Person.all_by_name('Nick', max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+###### `#memberships`
+Get all memberships for person
+
+```ruby
+person = CiscoSpark::Person.new(id: 'Y2lz...')
+person.memberships(max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+##### `CiscoSpark::Room`
+[API reference](https://developer.ciscospark.com/resource-rooms.html)
+
+###### `#memberships`
+Get all memberships for room
+
+```ruby
+room = CiscoSpark::Room.new(id: 'Y3de...')
+room.memberships(max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+###### `#messages`
+Get all messages for room
+
+```ruby
+room = CiscoSpark::Room.new(id: 'Y3de...')
+room.messages(max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+###### `#messages_before_message`
+Get all message before a given message, accepts a `CiscoSpark::Message` or a message ID
+
+```ruby
+room.all_before_message('Y3de...', max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+###### `#messages_before`
+Get all message before a given time, accepts a `DateTime` or a string
+
+```ruby
+room.messages_before(DateTime.now, max: 5)
+=> #<CiscoSpark::Collection>
+```
+
+###### `#send_message`
+Send a message to the room
+
+```ruby
+message = CiscoSpark::Message.new(text: 'Hello Spark')
+
+room = CiscoSpark::Room.new(id: 'Y3de...')
+room.send_message(message)
+=> #<CiscoSpark::Message>
+```
+
+###### `#add_person`
+Creates a new membership to the room for a given person 
+
+```ruby
+person = CiscoSpark::Person.fetch('Y2lz')
+
+room = CiscoSpark::Room.new(id: 'Y3de...')
+room.add_person(person)
+=> #<CiscoSpark::Membership>
+```
+
+##### `CiscoSpark::Membership`
+[API reference](https://developer.ciscospark.com/resource-memberships.html)
+
+###### `#person`
+Returns the person for this membership
+
+###### `#room`
+Returns the room this membership belongs to
+
+##### `CiscoSpark::Message`
+[API reference](https://developer.ciscospark.com/resource-messages.html)
+
+###### `#person`
+Returns the person that sent this message
+
+###### `#person_to`
+Returns the person that the message was sent to
+
+##### `CiscoSpark::Webhook`
+[API reference](https://developer.ciscospark.com/resource-webhooks.html)
+
+### `CiscoSpark::Collection`
+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
 
 ## Development
 
 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`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`.
 
 ## Contributing
 

data/lib/cisco_spark/api.rb

@@ -23,8 +23,6 @@ module CiscoSpark
       @resource = resource
       @request_body = request_body
 
-      puts "request_body: #{request_body}"
-
       do_put
     end
 
@@ -49,9 +47,7 @@ module CiscoSpark
       response = http_client.request(get_request)
       debug(response) if CiscoSpark.debug
 
-      if response.is_a?(Net::HTTPSuccess)
-        JSON.parse(response.body)
-      end
+      response
     end
 
     def do_post
@@ -62,9 +58,7 @@ module CiscoSpark
       response = http_client.request(post_request)
       debug(response) if CiscoSpark.debug
 
-      if response.is_a?(Net::HTTPSuccess)
-        JSON.parse(response.body)
-      end
+      response
     end
 
     def do_put
@@ -75,10 +69,7 @@ module CiscoSpark
       response = http_client.request(post_request)
       debug(response) if CiscoSpark.debug
 
-      puts "response.body: #{response.body}"
-      if response.is_a?(Net::HTTPSuccess)
-        JSON.parse(response.body)
-      end
+      response
     end
 
     def http_client

data/lib/cisco_spark/collection.rb

@@ -0,0 +1,48 @@
+module CiscoSpark
+  class Collection
+    attr_accessor :collection, :model_klass
+
+    def initialize(model_klass, collection=[], response=nil)
+      @model_klass = model_klass
+      @collection = collection
+
+      parse_pagination(response)
+    end
+
+
+
+    def method_missing(name, *args, &block)
+      if collection.respond_to?(name)
+        collection.send(name, *args, &block)
+      else
+        super
+      end
+    end
+
+    def next
+      return false unless next_params
+      response = model_klass.fetch_all_raw(next_params)
+      @collection = model_klass.parse_collection(response.body)
+      parse_pagination(response)
+      self
+    end
+
+    private
+
+    attr_accessor :next_params
+
+    def parse_pagination(response)
+      @next_params = nil
+      return unless response && response['Link']
+
+      matches = /<(?<next>.*)>; rel="next"/.match(response['Link'])
+      next_url = matches[:next]
+
+      if next_url
+        next_uri = URI.parse(next_url)
+        @next_params = Hash[URI::decode_www_form(next_uri.query)]
+      end
+    end
+
+  end
+end

data/lib/cisco_spark/model.rb

@@ -1,4 +1,5 @@
 require "cisco_spark/api"
+require "cisco_spark/collection"
 require "cisco_spark/data_caster"
 
 module CiscoSpark
@@ -25,36 +26,44 @@ module CiscoSpark
         @mutable_attributes = attributes
       end
 
+      def fetch_all_raw(options={})
+        Api.new.get(@resource, options)
+      end
+
       def fetch_all(options={})
-        response = Api.new.get(@resource, options)
-        parse_collection(response['items'])
+        response = fetch_all_raw(options)
+        collection = parse_collection(response.body)
+        CiscoSpark::Collection.new(self, collection, response)
       end
 
       def fetch(id, options={})
         response = Api.new.get("#{@resource}/#{id}", options)
-        parse(response)
+        parse(response.body)
       end
 
       def create(attributes)
         response = Api.new.post(@resource, attributes)
-        parse(response)
+        parse(response.body)
       end
 
       def update(id, attributes)
         attributes = attributes.select{ |name, _v| @mutable_attributes.include?(name) }
         response = Api.new.put("#{@resource}/#{id}", attributes)
-        parse(response)
+        parse(response.body)
       end
 
       def destroy(id)
         Api.new.delete("#{@resource}/#{id}")
       end
 
-      def parse_collection(collection)
-        collection.map{ |hash| parse(hash) }
+      def parse_collection(object)
+        object = JSON.parse(object) if object.is_a?(String)
+        object = object.fetch('items', []) if object.is_a?(Hash)
+        object.map{ |hash| parse(hash) }
       end
 
       def parse(hash)
+        hash = JSON.parse(hash) if hash.is_a?(String)
         params = attributes.each_with_object({}) do |(attribute, caster), params|
           params[attribute] = caster.call(hash[Utils.camelize(attribute)])
         end
@@ -68,6 +77,7 @@ module CiscoSpark
 
     def fetch
       merge_attributes(self.class.fetch(id))
+      self
     end
 
     def persist
@@ -88,12 +98,14 @@ module CiscoSpark
 
     def create
       merge_attributes(self.class.create(to_h))
+      self
     end
 
     def update
       attrs = to_h
       id = attrs.delete(:id)
       merge_attributes(self.class.update(id, attrs))
+      self
     end
 
     def merge_attributes(object)

data/lib/cisco_spark/models/room.rb

@@ -20,6 +20,22 @@ module CiscoSpark
       CiscoSpark::Message.fetch_all(options)
     end
 
+    def messages_before_message(message, options={})
+      message_id = message.is_a?(CiscoSpark::Message) ? message.id : message
+      options[:before_message] = message_id
+      options[:room_id] = id
+      CiscoSpark::Message.fetch_all(options)
+    end
+
+    def messages_before(date, options={})
+      if date.is_a?(DateTime)
+        date = date.to_time.iso8601
+      end
+      options[:room_id] = id
+      options[:before] = date
+      CiscoSpark::Message.fetch_all(options)
+    end
+
     def memberships(options={})
       options[:room_id] = id
       CiscoSpark::Membership.fetch_all(options)
@@ -27,7 +43,7 @@ module CiscoSpark
 
     def send_message(message)
       message.room_id = id
-      message.persit
+      message.persist
     end
 
     def add_person(person, options={})

data/lib/cisco_spark/models/webhook.rb

@@ -0,0 +1,20 @@
+require "cisco_spark/model"
+
+module CiscoSpark
+  class Webhook
+    include Model
+    resource 'webhooks'
+
+    attributes(
+      id: DataCaster::String,
+      name: DataCaster::String,
+      target_url: DataCaster::String,
+      resource: DataCaster::String,
+      event: DataCaster::String,
+      filter: DataCaster::String,
+      created: DataCaster::DateTime,
+    )
+    mutable_attributes :name, :target_url
+
+  end
+end

data/lib/cisco_spark/version.rb

@@ -1,3 +1,3 @@
 module CiscoSpark
-  VERSION = "0.2.1"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cisco_spark
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.2.2
 platform: ruby
 authors:
 - Nick Maher
@@ -101,6 +101,7 @@ files:
 - cisco_spark.gemspec
 - lib/cisco_spark.rb
 - lib/cisco_spark/api.rb
+- lib/cisco_spark/collection.rb
 - lib/cisco_spark/configuration.rb
 - lib/cisco_spark/data_caster.rb
 - lib/cisco_spark/errors.rb
@@ -109,6 +110,7 @@ files:
 - lib/cisco_spark/models/message.rb
 - lib/cisco_spark/models/person.rb
 - lib/cisco_spark/models/room.rb
+- lib/cisco_spark/models/webhook.rb
 - lib/cisco_spark/utils.rb
 - lib/cisco_spark/version.rb
 homepage: https://github.com/NGMarmaduke/cisco_spark-ruby