hashblue-api 0.0.8

data/lib/hashblue/api/contact.rb

@@ -0,0 +1,26 @@
+# A Contact represents another number with which the Subscriber
+# has sent or received Messages. It should not be instantiated
+# directly; instead, use Subscriber#contacts to retrieve the
+# set for a Subscriber.
+class Hashblue::API::Contact < Hashblue::API::Model
+  #:nodoc:
+  def initialize(attributes)
+    super
+    @attributes["latest_message"] = Hashblue::API::Message.new(@attributes["latest_message"]) if @attributes["latest_message"]
+  end
+
+  # Returns an Array of Message objects corresponding to the conversation
+  # between the Subscriber and this Contact.
+  #
+  # The options available to this message correspond to those available for
+  # the collections on Subscriber.
+  def messages(options={})
+    Hashblue::API::Message.from_json(get("#{_path}/messages.json", options))
+  end
+
+  private
+
+  def _path
+    "/subscribers/#{subscriber_id}/contacts/#{id}"
+  end
+end

data/lib/hashblue/api/error.rb

@@ -0,0 +1,39 @@
+# The base Hashblue Error class, which will be sent serialized
+# as JSON from the API itself.
+class Hashblue::API::Error < StandardError
+  def self.from_response(response)
+    if response.json? && response.keys == ["error"]
+      response["error"].keys.first.constantize.new(response["error"].values.first)
+    elsif response.code == 401
+      Hashblue::API::AccessDeniedError.new(response)
+    else
+      Hashblue::API::BadResponseError.new(response)
+    end
+  end
+
+  def initialize(response)
+    if response.respond_to?(:body)
+      @body = response.body
+      @headers = response.headers
+    else
+      @response = response
+    end
+  end
+
+  def status
+    :not_found
+  end
+
+  def to_s
+    str = "<##{self.class.name}:#{self.object_id}"
+    if @body && @headers
+      str + "@headers=#{@headers.inspect} @body=#{@body.inspect}>"
+    else
+      str + "@resposne=#{@response.inspect}>"
+    end
+  end
+
+  def to_json
+    {self.class.name => self.message}
+  end
+end

data/lib/hashblue/api/message.rb

@@ -0,0 +1,37 @@
+require 'hashblue/api'
+
+# A Message represents an SMS either sent or received by this Subscriber.
+# It should not be instantiated directly; Messages can be loaded either 
+# using Subscriber#messages, or Contact#messages.
+class Hashblue::API::Message < Hashblue::API::Model
+  # Deletes a specific message. Note that you must be authenticated as the
+  # Subscriber in order to delete a message; otherwise an AccessDeniedError
+  # will be raised.
+  def self.delete(subscriber_id, id)
+    Hashblue::API.delete("/subscribers/#{subscriber_id}/messages/#{id}.json")
+  end
+
+  #:nodoc:
+  def initialize(attributes = {})
+    super
+    @attributes["timestamp"] = Time.parse(@attributes["timestamp"]) if @attributes["timestamp"]
+  end
+
+  # Returns true if the message was sent by the Subscriber
+  # See also +received?+, which is the inverse of this.
+  def sent?
+    sent
+  end
+
+  # Returns true if the message was received by the Subscriber
+  # See also +sent?+, which is the inverse of this.
+  def received?
+    !sent
+  end
+
+  # Deletes this message. Note that deletion is not permanent; the Subscriber
+  # provides a collection of deleted messages.
+  def delete
+    self.class.delete(self.subscriber_id, self.id)
+  end
+end

data/lib/hashblue/api/model.rb

@@ -0,0 +1,55 @@
+require 'active_support/inflector'
+
+class Hashblue::API::Model #:nodoc:all
+
+  # Stolen from ActiveModel to get around incompatabilities between ActiveSupport 2.3.5 and ActiveModel 3.0
+  class Name < String
+    attr_reader :human, :singular, :plural, :element, :collection, :partial_path
+    alias_method :cache_key, :collection
+
+    def initialize(name)
+      super(name)
+      @klass = name
+      @singular = ActiveSupport::Inflector.underscore(self).tr('/', '_').freeze
+      @plural = ActiveSupport::Inflector.pluralize(@singular).freeze
+      @element = ActiveSupport::Inflector.underscore(ActiveSupport::Inflector.demodulize(self)).freeze
+      @human = ActiveSupport::Inflector.humanize(@element).freeze
+      @collection = ActiveSupport::Inflector.tableize(self).freeze
+      @partial_path = "#{@collection}/#{@element}".freeze
+    end
+  end
+  
+  def self.model_name
+    @_model_name ||= Name.new(self.name.from(15))
+  end
+  
+  def self.from_json(models)
+    models.map do |attributes|
+      new(attributes)
+    end
+  end
+
+  def initialize(attributes = {})
+    @attributes = attributes.stringify_keys
+  end
+
+  def method_missing(method, *args, &block)
+    if @attributes.keys.include?(method.to_s)
+      @attributes[method.to_s]
+    else
+      super
+    end
+  end
+
+  def id
+    @attributes["id"]
+  end
+
+  def to_param
+    id
+  end
+
+  def get(path, query_options={})
+    Hashblue::API.get(path, :query => query_options)
+  end
+end

data/lib/hashblue/api/request.rb

@@ -0,0 +1,36 @@
+module Hashblue::API::Request #:nodoc:all
+  def get(path, options={})
+    _request { super }
+  end
+
+  def delete(path)
+    _request { super }
+  end
+
+  def _request
+    _with_timeout do
+      response = Response.new(yield)
+      if response.success? && response.json?
+        return response
+      else
+        raise Hashblue::API::Error.from_response(response)
+      end
+    end
+  end
+
+  def _with_timeout(seconds = default_options[:timeout], &block)
+    Timeout::timeout(seconds, &block)
+  rescue Timeout::Error
+    raise Hashblue::API::NotRespondingError
+  end
+
+  class Response < DelegateClass(HTTParty::Response)
+    def success?
+      code == 200
+    end
+
+    def json?
+      Mime::JSON === headers["content-type"].first.split(";").first.strip
+    end
+  end
+end

data/lib/hashblue/api/subscriber.rb

@@ -0,0 +1,65 @@
+# A Subscriber represents an individual phone number (MSISDN)
+# within the Hashblue API, and is the object from which all
+# other API information is made available.
+#
+# Create a Subscriber using the 'find' method, and supplying
+# your API subscriber ID:
+#
+#    subscriber = Hashblue::API::Subscriber.find("yourid")
+#    subscriber.messages
+#    subscriber.contacts.first.messages
+#    # etc..
+#
+# == Collection Options
+#
+# You can pass an options Hash to the collection methods. These can
+# include:
+#
+# [:page]     the page of messages to return
+# [:per_page] the number of messages to return in a page. If the
+#             the page option is provided, but this is omitted, a
+#             default of 20 will be used by the API.
+#
+
+class Hashblue::API::Subscriber < Hashblue::API::Model
+  # Instantiate a Subscriber
+  def self.find(id)
+    new("id" => id)
+  end
+
+  # Returns an Array of Contact objects for the Subscriber.
+  #
+  # Contacts are derived from the messages sent and received by a subscriber,
+  # and cannot be created or manipulated directly.
+  #
+  # See above for possible options this method takes.
+  def contacts(options = {})
+    Hashblue::API::Contact.from_json(get("#{_path}/contacts.json", options))
+  end
+
+  # Returns an Array of Message objects for the Subscriber.
+  #
+  # All sent and received messages for all contacts are included in the
+  # returned Array.
+  #
+  # See above for possible options this method takes.
+  def messages(options={})
+    Hashblue::API::Message.from_json(get("#{_path}/messages.json", options))
+  end
+
+  # Returns an Array of Message objects for the Subscriber.
+  #
+  # All messages that have been deleted for all contacts are included in
+  # the returned Array.
+  #
+  # See above for possible options this method takes.
+  def deleted_messages(options={})
+    Hashblue::API::Message.from_json(get("#{_path}/messages/deleted.json", options))
+  end
+
+  private
+
+  def _path
+    "/subscribers/#{id}"
+  end
+end

data/lib/hashblue/api/test_helper.rb

@@ -0,0 +1,87 @@
+require 'hashblue/api'
+require 'json'
+
+# = Test helper for applications using the Hashblue API gem.
+#
+# Use this helper to stub out calls to the Hashblue API with assurance
+# that stubbing will not allow your application to drift from the current
+# API specification.
+#
+# == Usage
+#
+#   class MyTest < Test::Unit::TestCase
+#     include Hashblue::API::TestHelper
+#
+#     def test_should_work_with_the_api
+#       stub_hashblue_api('123', :messages => [{:content => "blah"}])
+#
+#       subscriber = Hashblue::API::Subscriber.new('123')
+#
+#       assert_equal 1, messages.length
+#       assert_equal "blah", messages[0].content
+#       # etc
+#
+# The test helper will ensure that the data you are passing to +stub_hashblue_api+
+# matches the data that will be returned to your application by the API.
+module Hashblue::API::TestHelper
+  API_KEYS = %w(contact_msisdn content timestamp id sent).map(&:to_sym)
+
+  def stub_hashblue_api(subscriber_id, options={})
+    options.reverse_merge!(:contacts => [], :messages => [])
+
+    messages = options[:messages].map do |attributes|
+      {:id => __next_firehose_id, :content => "Hello", :contact_msisdn => "123",
+       :subscriber_id => subscriber_id, :sent => false,
+       :timestamp => Time.zone.now.to_json}.merge(prepare_and_check_attributes(attributes))
+    end
+
+    messages.each do |message|
+      Hashblue::API.stubs(:delete).with("/subscribers/#{subscriber_id}/messages/#{message[:id]}.json")
+    end
+
+    if options[:q]
+      search_results = messages.select { |message| message[:content][/#{options[:q]}/] }
+      Hashblue::API.stubs(:get).with("/subscribers/#{subscriber_id}/messages.json",
+        {:query => {:q => options[:q]}}).returns(search_results)
+      Hashblue::API.stubs(:get).with("/subscribers/#{subscriber_id}/messages.json", {:query => {}}).returns(messages)
+    else
+      Hashblue::API.stubs(:get).with("/subscribers/#{subscriber_id}/messages.json", anything).returns(messages)
+    end
+
+    contacts = messages.group_by { |m| m[:contact_msisdn] }.map do |msisdn, contact_messages|
+      explicit_contact = options[:contacts].find { |c| c[:msisdn] == msisdn }
+      id = explicit_contact ? explicit_contact[:id] : __next_firehose_id
+
+      url = "/subscribers/#{subscriber_id}/contacts/#{id}/messages.json"
+      Hashblue::API.stubs(:get).with(url, anything).returns(contact_messages)
+
+     {:id => id, :msisdn => msisdn, :latest_message => contact_messages.first, :subscriber_id => subscriber_id}
+    end
+
+    contacts_with_no_messages = options[:contacts].reject do |contact|
+      messages.find { |m| m[:contact_msisdn] == contact[:msisdn] }
+    end.map do |contact|
+      {:latest_message => nil, :id => __next_firehose_id}.merge(contact)
+    end
+
+    contacts += contacts_with_no_messages
+
+    Hashblue::API.stubs(:get).with("/subscribers/#{subscriber_id}/contacts.json", anything).returns(contacts)
+  end
+
+  private
+
+  def prepare_and_check_attributes(message)
+    unless (message.keys - API_KEYS).empty?
+      raise "#{message.keys.inspect} doesn't match the current API (#{API_KEYS.inspect})"
+    end
+    message[:timestamp] = message[:timestamp].to_s if message[:timestamp] # in case it was a DateTime
+    message
+  end
+
+  def __next_firehose_id
+    @@__firehose_id ||= 1
+    "firehose0helper0id#{@@__firehose_id += 1}"
+  end
+
+end

data/test/helpers/test_helper_test.rb

@@ -0,0 +1,115 @@
+require 'test_helper'
+require 'hashblue/api/test_helper'
+
+# Time.zone only appears when loaded within Rails
+unless Time.respond_to?(:zone) && Time.zone
+  def Time.zone
+    Time
+  end
+end
+
+class TestHelperTest < Test::Unit::TestCase
+  include Hashblue::API::TestHelper
+
+  context "When stubbing a message with correct attributes for a subscriber" do
+    setup do
+      @subscriber = Hashblue::API::Subscriber.new(:id => "123")
+    end
+
+    should "no errors raised" do
+      assert_nothing_raised do
+        stub_hashblue_api(@subscriber_id)
+      end
+    end
+
+    should "stub messages for subscriber" do
+      messages = [{:content => "Blah", :contact_msisdn => "123", :timestamp => 1.day.ago}]
+      stub_hashblue_api(@subscriber.id, :messages => messages)
+
+      messages = @subscriber.messages
+      assert_equal 1, messages.length
+      assert_equal "Blah", messages.first.content
+    end
+
+    should "stub deleting a message" do
+      messages = [{:id => "123"}]
+      stub_hashblue_api(@subscriber.id, :messages => messages)
+
+      assert_nothing_raised do
+        Hashblue::API::Message.delete(@subscriber.id, "123")
+      end
+    end
+
+    should "stub querying messages by keyword" do
+      stub_hashblue_api(@subscriber.id, :messages => [{:id => "123", :content => "I'll meet you at the office"},
+        {:id => "456", :content => "sure thing we'll do that"}], :q => "office")
+      messages = @subscriber.messages(:q => "office")
+      assert_equal 1, messages.length
+      assert_equal "I'll meet you at the office", messages.first.content
+    end
+
+    should "return no messages or contacts if none are provided" do
+      stub_hashblue_api(@subscriber.id)
+      assert_equal [], @subscriber.messages
+      assert_equal [], @subscriber.contacts
+    end
+
+    should "provide default content for stubbed messages if it is not provided" do
+      stub_hashblue_api(@subscriber.id, :messages => [{:contact_msisdn => "123"}])
+
+      assert_kind_of String, @subscriber.messages.first.content
+      assert @subscriber.messages.first.content.length > 0
+    end
+
+    should "stub contacts for the subscriber based on the messages" do
+      stub_hashblue_api(@subscriber.id, :messages => [{:contact_msisdn => "123"}])
+
+      contacts = @subscriber.contacts
+      assert_equal 1, contacts.length
+      assert_equal "123", contacts.first.msisdn
+    end
+
+    should "stub messages per contact" do
+      stub_hashblue_api(@subscriber.id, :messages => [{:content => "Hello", :contact_msisdn => "123"},
+                                                             {:content => "Wotcha", :contact_msisdn => "456"}])
+
+      contacts = @subscriber.contacts
+      assert_equal "Hello", contacts.find { |c| c.msisdn == "123" }.messages.first.content
+      assert_equal "Wotcha", contacts.find { |c| c.msisdn == "456" }.messages.first.content
+    end
+
+    should "stub contacts even when they have no messages" do
+      stub_hashblue_api(@subscriber.id, :messages => [{:content => "Hello", :contact_msisdn => "123"},
+                                                  {:content => "Goodbye", :contact_msisdn => "456"}],
+                                    :contacts => [{:id => "abc", :msisdn => "123"}])
+
+      contacts = @subscriber.contacts
+      assert_equal 2, contacts.length
+      assert_equal ["123", "456"], contacts.map(&:msisdn)
+    end
+
+    should "stub contacts even when there are no messages" do
+      stub_hashblue_api(@subscriber.id, :contacts => [{:id => "abc", :msisdn => "123"}])
+
+      contacts = @subscriber.contacts
+      assert_equal 1, contacts.length
+      assert_nil contacts.first.latest_message
+    end
+
+    should "allow control over contact ids" do
+      stub_hashblue_api(@subscriber.id, :messages => [{:contact_msisdn => "123"}],
+                               :contacts => [{:id => "abc", :msisdn => "123"}])
+
+      contact = @subscriber.contacts.first
+      assert_equal "123", contact.msisdn
+      assert_equal "abc", contact.id
+    end
+
+    should "allow control over message ids" do
+      stub_hashblue_api(@subscriber.id, :messages => [{:id => "abc"}])
+
+      message = @subscriber.messages.first
+      assert_equal "abc", message.id
+    end
+  end
+end