hashblue 0.0.1 → 0.0.2

data/README.md

@@ -0,0 +1,26 @@
+This gem provides an easy way to access the hashblue API (https://api.hashblue.com) from ruby programs.  Currently the gem is limited to reading data from the API, but it is intended to add all API features shortly.  It also doesn't handle pagination, instead only returning the first 50 results.  This too should be rectified soon.
+
+### Getting started
+
+Using this gem is very straightforward.  First, you need to obtain an OAuth2 access token (see https://api.hashblue.com/doc/Authentication).  Then, create a new client:
+
+    client = Hashblue::Client.new('oauth2-access-token')
+
+Finally, use that client to start to navigate the API:
+
+    contacts = client.account.contacts
+    first_contact_messages = contacts.first.messages
+
+You can also pass in query parameters to restrict the results:
+
+    messages_abouts_pubs = client.messages(:q => 'pub')
+
+And if there are additional pages of results, access them too:
+
+    second_page = client.messages(:q => 'pub').next_page
+
+It's possible to delete messages, and mark them as favourites:
+
+    client.contacts.first.messages.first.delete!
+    client.messages.first.favourite!
+    client.messages.first.unfavourite!

data/lib/hashblue/client.rb

@@ -3,7 +3,7 @@ require 'httparty'
 module Hashblue
   class Client
     class RequestError < StandardError; end
-    
+
     include HTTParty
 
     base_uri "https://api.hashblue.com"
@@ -23,32 +23,44 @@ module Hashblue
       load_messages("/messages", query)
     end
 
+    def favourites(query = {})
+      load_messages("/messages/favourites", query)
+    end
+
     def contacts(query = {})
       load_contacts("/contacts", query)
     end
 
     def load_messages(uri, query = {})
-      get(uri, query)["messages"].collect do |m|
-        Message.new(self, m)
-      end
+      Collection.new(self, Message, get(uri, query), "messages")
     end
 
     def load_contacts(uri, query = {})
-      get(uri, query)["contacts"].collect do |m|
-        Contact.new(self, m)
-      end
+      Collection.new(self, Contact, get(uri, query), "contacts")
     end
 
     def get(path, query = {})
-      response = self.class.get path, :query => query, :headers => request_headers
+      request :get, path, query
+    end
+
+    def delete(path, query = {})
+      request :delete, path, query
+    end
+
+    def put(path, query, body)
+      request :put, path, query, body
+    end
+
+    private
+
+    def request(method, path, query, body = nil)
+      response = self.class.send method, path, :query => query, :headers => request_headers
       case response.headers["status"]
       when "200" then response.to_hash
       else raise RequestError, "request unsuccessful: #{response.to_hash.inspect}"
       end
     end
 
-    private
-
     def request_headers
       {"Authorization" => "OAuth #{access_token}", 'Accept' => 'application/json'}
     end

data/lib/hashblue/collection.rb

@@ -0,0 +1,43 @@
+class Hashblue::Collection
+  def initialize(client, model_class, data, name)
+    @client = client
+    @model_class = model_class
+    @data = data
+    @name = name
+    @items = @data[name].collect do |item|
+      model_class.new(@client, item)
+    end
+  end
+
+  def respond_to?(method)
+    super || @items.respond_to?(method)
+  end
+
+  def method_missing(method, *args, &block)
+    @items.respond_to?(method) ? @items.send(method, *args, &block) : super
+  end
+
+  def next_page?
+    !!@data["next_page_uri"]
+  end
+
+  def next_page
+    if next_page?
+      self.class.new(@client, @model_class, @client.get(@data["next_page_uri"]), @name)
+    else
+      nil
+    end
+  end
+
+  def previous_page?
+    !!@data["previous_page_uri"]
+  end
+
+  def previous_page
+    if previous_page?
+      self.class.new(@client, @model_class, @client.get(@data["previous_page_uri"]), @name)
+    else
+      nil
+    end
+  end
+end

data/lib/hashblue/contact.rb

@@ -1,6 +1,6 @@
 module Hashblue
   class Contact < Model
-    attribute_methods :name, :phone_number, :msisdn, :email
+    attribute_methods :uri, :name, :phone_number, :msisdn, :email
 
     def messages(query = {})
       client.load_messages(messages_uri, query)

data/lib/hashblue/message.rb

@@ -2,6 +2,10 @@ module Hashblue
   class Message < Model
     attribute_methods :uri, :timestamp, :content
 
+    def contact
+      @contact ||= Contact.new(client, @attributes["contact"])
+    end
+
     def sent?
       @attributes["sent"]
     end
@@ -10,8 +14,20 @@ module Hashblue
       @attributes["favourite"]
     end
 
-    def contact
-      @contact ||= Contact.new(client, @attributes["contact"])
+    def delete!
+      client.delete(uri)
+    end
+
+    def favourite!
+      client.put(uri + '/favourite', {}, {})
+      @attributes['favourite'] = true
+      true
+    end
+
+    def unfavourite!
+      client.delete(uri + '/favourite')
+      @attributes['favourite'] = false
+      true
     end
   end
 end

data/lib/hashblue/version.rb

@@ -1,3 +1,3 @@
 module Hashblue
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/hashblue.rb

@@ -3,6 +3,7 @@ require "hashblue/version"
 module Hashblue
   autoload :Account, 'hashblue/account'
   autoload :Client, 'hashblue/client'
+  autoload :Collection, 'hashblue/collection'
   autoload :Contact, 'hashblue/contact'
   autoload :Message, 'hashblue/message'
   autoload :Model, 'hashblue/model'

data/spec/models/client_spec.rb

@@ -64,4 +64,36 @@ describe Hashblue::Client do
       subject.contacts(:anything => :here)
     end
   end
+
+  describe '#favourites(query = {})' do
+    it "loads messages from '/messages/favourites'" do
+      subject.expects(:load_messages).with('/messages/favourites', {}).returns([:favourite_messages])
+      subject.favourites.should eql([:favourite_messages])
+    end
+
+    it "passes query through to load_messages" do
+      subject.expects(:load_messages).with('/messages/favourites', {:anything => :here})
+      subject.favourites(:anything => :here)
+    end
+  end
+
+  describe '#load_messages(uri, query)' do
+    it "builds a Collection of messages with the response from the uri" do
+      response = {"messages" => [{"content" => "hello"}]}
+      subject.stubs(:get).returns(response)
+      collection = mock()
+      Hashblue::Collection.expects(:new).with(subject, Hashblue::Message, response, "messages").returns(collection)
+      subject.load_messages("/messages")
+    end
+  end
+
+  describe '#load_contacts(uri, query)' do
+    it "builds a Collection of contacts with the response from the uri" do
+      response = {"contacts" => [{"msisdn" => "1234"}]}
+      subject.stubs(:get).returns(response)
+      collection = mock()
+      Hashblue::Collection.expects(:new).with(subject, Hashblue::Contact, response, "contacts").returns(collection)
+      subject.load_contacts("/contacts")
+    end
+  end
 end

data/spec/models/collection_spec.rb

@@ -0,0 +1,103 @@
+require 'spec_helper'
+
+describe Hashblue::Collection do
+  let :client do
+    Hashblue::Client.new('hashblue-access-token')
+  end
+
+  describe "in general" do
+    subject do
+      Hashblue::Collection.new(client, Hashblue::Contact, {"contacts" => [
+        {'msisdn' => 1}, {'msisdn' => 2}, {'msisdn' => 3}
+      ]}, "contacts")
+    end
+
+    it "passes array methods to an array of models built from provided data" do
+      subject[0].should eql(Hashblue::Contact.new(client, {'msisdn' => 1}))
+      subject.size.should eql(3)
+      subject.collect {|c| c.msisdn}.should eql([1, 2, 3])
+    end
+  end
+
+  describe "a collection without a next_page_uri" do
+    subject do
+      Hashblue::Collection.new(client, Hashblue::Contact, {"contacts" => []}, "contacts")
+    end
+
+    describe '#next_page?' do
+      it "returns false" do
+        subject.next_page?.should be_false
+      end
+    end
+
+    describe '#next_page' do
+      it "returns nil" do
+        subject.next_page.should be_false
+      end
+    end
+  end
+
+  describe "a collection with a next_page_uri" do
+    subject do
+      Hashblue::Collection.new(client, Hashblue::Contact, {"contacts" => [], "next_page_uri" => "https://api.example.com/contacts/more"}, "contacts")
+    end
+
+    describe '#next_page?' do
+      it "returns true" do
+        subject.next_page?.should be_true
+      end
+    end
+
+    describe '#next_page' do
+      it "returns a new collection built from the response from the next_page_uri" do
+        subject
+        response = {"contacts" => []}
+        client.stubs(:get).with("https://api.example.com/contacts/more").returns(response)
+        collection = mock()
+        Hashblue::Collection.expects(:new).with(client, Hashblue::Contact, response, "contacts").returns(collection)
+        subject.next_page.should eql(collection)
+      end
+    end
+  end
+
+  describe "a collection without a previous_page_uri" do
+    subject do
+      Hashblue::Collection.new(client, Hashblue::Contact, {"contacts" => []}, "contacts")
+    end
+
+    describe '#previous_page?' do
+      it "returns false" do
+        subject.next_page?.should be_false
+      end
+    end
+
+    describe '#previous_page' do
+      it "returns nil" do
+        subject.next_page.should be_false
+      end
+    end
+  end
+
+  describe "a collection with a previous_page_uri" do
+    subject do
+      Hashblue::Collection.new(client, Hashblue::Contact, {"contacts" => [], "previous_page_uri" => "https://api.example.com/contacts/less"}, "contacts")
+    end
+
+    describe '#previous_page?' do
+      it "returns true" do
+        subject.previous_page?.should be_true
+      end
+    end
+
+    describe '#previous_page' do
+      it "returns a new collection built from the response from the next_page_uri" do
+        subject
+        response = {"contacts" => []}
+        client.stubs(:get).with("https://api.example.com/contacts/less").returns(response)
+        collection = mock()
+        Hashblue::Collection.expects(:new).with(client, Hashblue::Contact, response, "contacts").returns(collection)
+        subject.previous_page.should eql(collection)
+      end
+    end
+  end
+end

data/spec/models/contact_spec.rb

@@ -7,6 +7,7 @@ describe Hashblue::Contact do
 
   subject do
     Hashblue::Contact.new(client, {
+      'uri' => 'https://api.example.com/contacts/abcdef123456',
       'messages' => 'https://api.example.com/contact/1/messages',
     })
   end

data/spec/models/message_spec.rb

@@ -7,6 +7,7 @@ describe Hashblue::Message do
 
   subject do
     Hashblue::Message.new(client, {
+      'uri' => 'https://api.example.com/messages/abcdef123456',
       'sent' => true,
       'favourite' => false,
       'contact' => {
@@ -15,6 +16,18 @@ describe Hashblue::Message do
     })
   end
 
+  describe 'favourite?' do
+    it "returns the 'favourite' attribute" do
+      subject.favourite?.should be_false
+    end
+  end
+
+  describe 'sent?' do
+    it "returns the 'sent' attribute" do
+      subject.sent?.should be_true
+    end
+  end
+
   describe '#contact' do
     it "returns Contact built with contact attributes" do
       subject.contact.should eql(Hashblue::Contact.new(client, {
@@ -22,4 +35,47 @@ describe Hashblue::Message do
       }))
     end
   end
+
+  describe '#delete!' do
+    it "sends a delete request to the message uri" do
+      client.expects(:delete).with('https://api.example.com/messages/abcdef123456')
+      subject.delete!
+    end
+  end
+
+  describe '#favourite!' do
+    it "sends a put request to the message favourite uri" do
+      client.expects(:put).with('https://api.example.com/messages/abcdef123456/favourite', {}, {})
+      subject.favourite!
+    end
+
+    it "returns true when request doesn't raise an error" do
+      client.stubs(:put)
+      subject.favourite!.should be_true
+    end
+
+    it "sets favourite attribute to true in local model" do
+      client.stubs(:put)
+      subject.favourite!
+      subject.favourite?.should be_true
+    end
+  end
+
+  describe '#unfavourite!' do
+    it "sends a delete request to the message favourite uri" do
+      client.expects(:delete).with('https://api.example.com/messages/abcdef123456/favourite')
+      subject.unfavourite!
+    end
+
+    it "returns true when request doesn't raise an error" do
+      client.stubs(:delete)
+      subject.unfavourite!.should be_true
+    end
+
+    it "sets favourite attribute to true in local model" do
+      client.stubs(:delete)
+      subject.unfavourite!
+      subject.favourite?.should be_false
+    end
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: hashblue
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - Tom Ward
@@ -93,17 +93,20 @@ files:
 - .rspec
 - Gemfile
 - MIT-LICENCE
+- README.md
 - Rakefile
 - hashblue.gemspec
 - lib/hashblue.rb
 - lib/hashblue/account.rb
 - lib/hashblue/client.rb
+- lib/hashblue/collection.rb
 - lib/hashblue/contact.rb
 - lib/hashblue/message.rb
 - lib/hashblue/model.rb
 - lib/hashblue/version.rb
 - spec/models/account_spec.rb
 - spec/models/client_spec.rb
+- spec/models/collection_spec.rb
 - spec/models/contact_spec.rb
 - spec/models/message_spec.rb
 - spec/spec_helper.rb
@@ -143,6 +146,7 @@ summary: A simple client for the hashblue api
 test_files: 
 - spec/models/account_spec.rb
 - spec/models/client_spec.rb
+- spec/models/collection_spec.rb
 - spec/models/contact_spec.rb
 - spec/models/message_spec.rb
 - spec/spec_helper.rb