tms_client 0.0.2

data/Gemfile

@@ -0,0 +1,2 @@
+source "https://rubygems.org"
+gemspec

data/README.md

@@ -0,0 +1,134 @@
+TMS Client 
+===========
+This is a ruby client to interact with the GovDelivery TMS REST API.
+
+
+Usage 
+-----
+### Connecting
+
+``` ruby
+client = TMS::Client.new('username', 'password', :api_root => 'https://tms.govdelivery.com')
+
+```
+
+### Getting messages
+
+``` ruby
+client.subresources            #=> {"messages"=><TMS::Messages href=/messages collection=[]>}
+client.messages                #=> <TMS::Messages href=/messages collection=[]>
+client.sms_messages.get        #=> #lots of sms stuff
+client.sms_messages.next       #=> <TMS::Messages href=/messages/page/2 collection=[]> 
+                               #   (if there is a second page)
+client.sms_messages.next.get   #=> # more messages...
+client.voice_messages.get      #=> #lots of voice stuff
+client.voice_messages.next     #=> <TMS::Messages href=/messages/page/2 collection=[]> 
+                               #   (if there is a second page)
+client.voice_messages.next.get #=> # more messages...
+```
+
+
+### Sending an SMS Message
+
+``` ruby
+message = client.sms_messages.build(:short_body=>'Test Message!')
+message.recipients.build(:phone=>'5551112222')
+message.recipients.build(:phone=>'5551112223')
+message.recipients.build # invalid - no phone
+message.post             #=> true
+message.recipients.collection.detect{|r| r.errors } #=> {"phone"=>["is not a number"]}
+# save succeeded, but we have one bad recipient
+message.href             #=> "/messages/87"
+message.get              #=> <TMS::Message href=/messages/87 attributes={...}>
+```
+
+### Sending an Voice Message
+
+``` ruby
+message = client.voice_messages.build(:url=>'www.testmessage.com')
+message.recipients.build(:phone=>'5551112222')
+message.recipients.build(:phone=>'5551112223')
+message.recipients.build # invalid - no phone
+message.post             #=> true
+message.recipients.collection.detect{|r| r.errors } #=> {"phone"=>["is not a number"]}
+# save succeeded, but we have one bad recipient
+message.href             #=> "/messages/87"
+message.get              #=> <TMS::Message href=/messages/87 attributes={...}>
+```
+
+### Listing Command Types
+
+``` ruby 
+command_types = client.command_types.get
+command_types.collection.each do |at|
+  puts at.name   #=> "forward"
+  puts at.fields #=> ["url", "http_method", ...]
+end
+````
+
+### Managing Keywords
+
+``` ruby 
+# CRUD
+keyword = client.keywords.build(:name => "BUSRIDE")
+keyword.post                #=> true
+keyword.name                #=> 'busride'
+keyword.name = "TRAINRIDE"
+keyword.put                 #=> true
+keyword.name                #=> 'trainride'
+keyword.delete              #=> true
+
+# list
+keywords = client.keywords.get
+keywords.collection.each do |k|
+  puts k.name
+end
+```
+
+### Managing Commands
+
+```ruby
+# CRUD
+keywords = client.keywords.get
+keyword = keywords.collection.first.get
+command = keyword.commands.build(
+            :name => "Forward to somewhere else", 
+            :params => {:url => "http://example.com", :http_method => "get"}, 
+            :command_type => :forward)
+command.post
+command.params = {:url => "http://example.com/new_url", :http_method => "post"}
+command.put
+command.delete
+
+# list
+commands = keyword.commands.get
+commands.collection.each do |c|
+  puts c.inspect
+end
+```
+
+
+### Logging
+Any instance of a [Logger](http://www.ruby-doc.org/stdlib-1.9.3/libdoc/logger/rdoc/Logger.html "Ruby Logger")-like class can be passed in to the client; incoming and outgoing
+request information will then be logged to that instance. 
+
+The example below configures `TMS::Client` to log to STDOUT:
+
+``` ruby
+logger = Logger.new(STDOUT)
+client = TMS::Client.new('username', 'password', :logger => logger)
+
+```
+
+License
+-------
+Copyright (c) 2013, GovDelivery, Inc.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+* Neither the name of GovDelivery nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'rspec/core/rake_task'
+require 'rubygems/tasks'
+require 'rubygems/tasks/scm'
+
+RSpec::Core::RakeTask.new(:spec)
+Gem::Tasks.new
+
+task :default => :spec

data/lib/tms_client/base.rb

@@ -0,0 +1,28 @@
+module TMS #:nodoc:
+  module Base
+    def self.included(base)
+      base.send(:include, TMS::Util::HalLinkParser)
+      base.extend(ClassMethods)
+      base.send(:include, InstanceMethods)
+      base.send(:include, TMS::CoreExt)
+      base.send(:extend, TMS::CoreExt)
+    end
+
+    attr_accessor :client, :href, :errors
+
+    module ClassMethods
+      def to_param
+        tmsify(self)
+      end
+    end
+
+    module InstanceMethods
+      def initialize(client, href)
+        self.client = client
+        self.href = href
+      end
+    end
+
+  end
+
+end

data/lib/tms_client/client.rb

@@ -0,0 +1,80 @@
+# The client class to connect and talk to the TMS REST API. 
+class TMS::Client
+  include TMS::Util::HalLinkParser
+  include TMS::CoreExt
+
+  attr_accessor :connection, :href
+
+  # Create a new client and issue a request for the available resources for a given account. 
+  #
+  # === Options
+  # * +:api_root+ - The root URL of the TMS api. Defaults to localhost:3000
+  # * +:logger+   - An instance of a Logger class (http transport information will be logged here) - defaults to nil
+  #
+  # === Examples
+  #   client = TMS::Client.new("foo@example.com", "onetwothree", {
+  #                               :api_root => "https://tms.govdelivery.com", 
+  #                               :logger => Logger.new(STDOUT)})
+  # 
+  def initialize(username, password, options = {:api_root => 'http://localhost:3000', :logger => nil})
+    @api_root = options[:api_root]
+    connect!(username, password, options[:logger])
+    discover!
+  end
+
+  def connect!(username, password, logger)
+    self.connection = TMS::Connection.new(:username => username, :password => password, :api_root => @api_root, :logger => logger)
+  end
+
+  def discover!
+    services = get('/').body
+    parse_links(services['_links'])
+  end
+
+  def get(href)
+    response = raw_connection.get(href)
+    case response.status
+      when 401..499
+        raise TMS::Request::Error.new(response.status)
+      when 202
+        raise TMS::Request::InProgress.new(response.body['message'])
+      else
+        return response
+    end
+  end
+
+  def post(obj)
+    raw_connection.post do |req|
+      req.url @api_root + obj.href
+      req.headers['Content-Type'] = 'application/json'
+      req.body = obj.to_json
+    end
+  end
+
+  def put(obj)
+    raw_connection.put do |req|
+      req.url @api_root + obj.href
+      req.headers['Content-Type'] = 'application/json'
+      req.body = obj.to_json
+    end
+  end
+
+  def delete(href)
+    response = raw_connection.delete(href)
+    case response.status
+      when 200
+        return response
+      else
+        raise TMS::Request::Error.new(response.status)
+    end
+  end
+
+  def raw_connection
+    connection.connection
+  end
+
+  def client
+    self
+  end
+
+end

data/lib/tms_client/collection_resource.rb

@@ -0,0 +1,53 @@
+module TMS::CollectionResource
+  def self.included(base)
+    base.send(:include, InstanceMethods)
+  end
+
+  module InstanceMethods
+    include TMS::Base
+    attr_accessor :collection
+
+    def initialize(client, href, items=nil)
+      super(client, href)
+      if items
+        initialize_collection_from_items(items)
+      else
+        self.collection = []
+      end
+
+    end
+
+    def get
+      response = client.get(href)
+      initialize_collection_from_items(response.body)
+      #setup page links from header
+      links = LinkHeader.parse(response.headers['link']).to_a.collect do |a|
+        {a[1][0].last => a[0]}
+      end
+      parse_links(links)
+      self
+    end
+
+    def build(attributes=nil)
+      thing = instance_class(self.class).new(client, self.href, attributes || {})
+      self.collection << thing
+      thing
+    end
+
+    def to_json
+      @collection.map(&:to_json)
+    end
+
+    def to_s
+      "<#{self.class.inspect} href=#{self.href} collection=#{self.collection.inspect}>"
+    end
+
+    private
+
+    def initialize_collection_from_items(items)
+      self.collection = items.map do |attrs|
+        instance_class(self.class).new(client, nil, attrs)
+      end
+    end
+  end
+end

data/lib/tms_client/connection.rb

@@ -0,0 +1,30 @@
+class TMS::Connection
+  attr_accessor :username, :password, :api_root, :connection, :logger
+
+  def get(href)
+    resp = connection.get("#{href}.json")
+    if resp.status != 200
+      raise RecordNotFound.new("Could not find resource at #{href} (status #{resp.status})")
+    else
+      resp.body
+    end
+  end
+
+  def initialize(opts={})
+    self.username = opts[:username]
+    self.password = opts[:password]
+    self.api_root = opts[:api_root]
+    self.logger   = opts[:logger]
+    setup_connection
+  end
+
+  def setup_connection
+    self.connection = Faraday.new(:url => self.api_root) do |faraday|
+      faraday.use TMS::Logger, self.logger if self.logger
+      faraday.request :json
+      faraday.basic_auth(self.username, self.password)
+      faraday.response :json, :content_type => /\bjson$/
+      faraday.adapter :net_http
+    end
+  end
+end

data/lib/tms_client/instance_resource.rb

@@ -0,0 +1,175 @@
+module TMS::InstanceResource
+  def self.included(base)
+    base.send(:include, TMS::Base)
+    base.extend(ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  module ClassMethods
+    #
+    # Writeable attributes are sent on POST/PUT.
+    #
+    def writeable_attributes(*attrs)
+      @writeable_attributes ||= []
+      if attrs.any?
+        @writeable_attributes.map!(&:to_sym).concat(attrs).uniq! if attrs.any?
+        setup_attributes(@writeable_attributes, false)
+      end
+      @writeable_attributes
+    end
+
+    #
+    # Readonly attributes don't get POSTed.
+    # (timestamps are included by default)
+    #
+    def readonly_attributes(*attrs)
+      @readonly_attributes ||= [:created_at, :updated_at, :completed_at]
+      if attrs.any?
+        @readonly_attributes.map!(&:to_sym).concat(attrs).uniq!
+        setup_attributes(@readonly_attributes, true)
+      end
+      @readonly_attributes
+    end
+
+    #
+    # For collections that are represented as attributes (i.e. inline, no href)
+    #
+    # # message.rb
+    # collection_attributes :recipients
+    def collection_attributes(*attrs)
+      @collection_attributes ||= []
+      if attrs.any?
+        @collection_attributes.map!(&:to_sym).concat(attrs).uniq! if attrs.any?
+        @collection_attributes.each { |a| setup_collection(a) }
+      end
+      @collection_attributes
+    end
+
+    def custom_class_names
+      @custom_class_names ||= {}
+    end
+
+    #
+    # For collections that are represented as attributes (i.e. inline, no href)
+    # and that have a class name other than the one we would infer.
+    #
+    # # email.rb
+    # collection_attributes :recipients, 'EmailRecipient'
+    def collection_attribute(attr, tms_class)
+      @collection_attributes ||= []
+      @collection_attributes.push(attr).uniq!
+      setup_collection(attr, TMS.const_get(tms_class))
+    end
+
+    def setup_attributes(attrs, readonly=false)
+      attrs.map(&:to_sym).each do |property|
+        self.send :define_method, :"#{property}=", &lambda { |v| @attributes[property] = v } unless readonly
+        self.send :define_method, property.to_sym, &lambda { @attributes[property] }
+      end
+    end
+
+    def setup_collection(property, klass=nil)
+      if klass
+        custom_class_names[property] = klass
+      else
+        klass ||= TMS.const_get(property.to_s.capitalize)
+      end
+
+      self.send :define_method, property.to_sym, &lambda { @attributes[property] ||= klass.new(self.client, nil, nil) }
+    end
+  end
+
+  module InstanceMethods
+    def initialize(client, href=nil, attrs=nil)
+      super(client, href)
+      @attributes = {}
+      attrs ||= self.client.get(href).body if href
+      set_attributes_from_hash(attrs) if attrs
+    end
+
+    def get
+      set_attributes_from_hash(self.client.get(href).body)
+      self
+    end
+
+    def post
+      response = client.post(self)
+      case response.status
+        when 201
+          set_attributes_from_hash(response.body)
+          return true
+        when 401
+          raise Exception.new("401 Not Authorized")
+        when 404
+          raise(Exception.new("Can't POST to #{self.href}"))
+        else
+          if response.body['errors']
+            self.errors = response.body['errors']
+          end
+      end
+      return false
+    end
+
+    def put
+      response = client.put(self)
+      case response.status
+        when 200
+          set_attributes_from_hash(response.body)
+          return true
+        when 401
+          raise Exception.new("401 Not Authorized")
+        when 404
+          raise(Exception.new("Can't POST to #{self.href}"))
+        else
+          if response.body['errors']
+            self.errors = response.body['errors']
+          end
+      end
+      return false
+    end
+
+    def delete
+      response = self.client.delete(href)
+      case response.status
+        when 200
+          return true
+        else
+          if response.body['errors']
+            self.errors = response.body['errors']
+          end
+      end
+      return false
+    end
+
+    def to_s
+      "<#{self.class.inspect}#{' href=' + self.href if self.href} attributes=#{@attributes.inspect}>"
+    end
+
+    def to_json
+      json_hash = {}
+      self.class.writeable_attributes.each do |attr|
+        json_hash[attr] = self.send(attr)
+      end
+      self.class.collection_attributes.each do |coll|
+        json_hash[coll] = self.send(coll).to_json
+      end
+      json_hash
+    end
+
+    private
+
+    def set_attributes_from_hash(hash)
+      hash.reject { |k, _| k=~/^_/ }.each do |property, value|
+        if self.class.collection_attributes.include?(property.to_sym)
+          klass = self.class.custom_class_names[property] || TMS.const_get(property.to_s.capitalize)
+          @attributes[property.to_sym] = klass.new(client, nil, value)
+        else
+          @attributes[property.to_sym] = value
+        end
+      end
+      self.errors = hash['errors']
+      parse_links(hash['_links'])
+    end
+
+  end
+end

data/lib/tms_client/logger.rb

@@ -0,0 +1,34 @@
+module TMS #:nodoc:
+  class Logger < Faraday::Response::Middleware #:nodoc:
+    extend Forwardable
+
+    def initialize(app, logger = nil)
+      super(app)
+      @logger = logger || begin
+        require 'logger'
+        ::Logger.new(STDOUT)
+      end
+    end
+
+    def_delegators :@logger, :debug, :info, :warn, :error, :fatal
+
+    def call(env)
+      puts env.inspect
+      info "#{env[:method]} #{env[:url].to_s}"
+      debug('request') { dump_headers env[:request_headers] }
+      super
+    end
+
+    def on_complete(env)
+      info('Status') { env[:status].to_s }
+      debug('response headers') { dump_headers env[:response_headers] }
+      debug('response body') { env[:body].inspect }
+    end
+
+    private
+
+    def dump_headers(headers)
+      headers.map { |k, v| "#{k}: #{v.inspect}" }.join("\n")
+    end
+  end
+end

data/lib/tms_client/request.rb

@@ -0,0 +1,17 @@
+module TMS #:nodoc:
+  module Request
+    # The generic TMS error class
+    class Error < StandardError
+      attr_reader :code
+
+      def initialize(code)
+        super("HTTP Error: #{code}")
+        @code=code
+      end
+    end
+
+    # Raised when a recipient list is still being constructed and a request is made to view the 
+    # recipient list for a message.
+    class InProgress < StandardError; end
+  end
+end

data/lib/tms_client/resource/collections.rb

@@ -0,0 +1,49 @@
+class TMS::Emails
+  include TMS::CollectionResource
+end
+
+class TMS::VoiceMessages
+  include TMS::CollectionResource
+end
+
+class TMS::SmsMessages
+  include TMS::CollectionResource
+end
+
+class TMS::Emails
+  include TMS::CollectionResource
+end
+
+class TMS::Recipients
+  include TMS::CollectionResource
+end
+
+class TMS::EmailRecipients
+  include TMS::CollectionResource
+end
+
+# A collection of Keyword objects.
+#
+# === Example
+#    keywords = client.keywords.get
+#
+class TMS::Keywords
+  include TMS::CollectionResource
+end
+
+class TMS::InboundMessages
+  include TMS::CollectionResource
+end
+
+# A collection of CommandType instances.
+# This resource changes infrequently.  It may be used to dynamically construct a
+# user interface for configuring arbitrary SMS keywords for an account.
+#
+# This resource is read-only.
+#
+# === Example
+#    client.command_types.get
+#    client.command_types.collection.each {|at| ... }
+class TMS::CommandTypes
+  include TMS::CollectionResource
+end

data/lib/tms_client/resource/command.rb

@@ -0,0 +1,24 @@
+module TMS #:nodoc:
+  # A command is a combination of behavior and parameters that should be executed 
+  # when an incoming SMS message matches the associated Keyword.
+  #
+  # ==== Attributes  
+  # 
+  # * +name+ - The name of the command.  This will default to the command_type if not supplied. 
+  # * +command_type+ - The type of this command.  A list of valid types can be found by querying the CommandType list. 
+  # * +params+ - A Hash of string/string pairs used as configuration for this command.  
+  # 
+  # === Examples
+  #    command = keyword.commands.build(:name => "subscribe to news", :command_type => "dcm_subscribe", :dcm_account_code => "NEWS", :dcm_topic_codes => "NEWS_1, NEWS_2")
+  #    command.post
+  #    command.dcm_topic_codes += ", NEWS_5"
+  #    command.put
+  #    command.delete
+  class Command
+    include InstanceResource
+
+    writeable_attributes :name, :command_type, :params
+    readonly_attributes :created_at, :updated_at
+
+  end
+end

data/lib/tms_client/resource/command_type.rb

@@ -0,0 +1,19 @@
+module TMS #:nodoc:
+  # CommandType is a pair of values (name, fields) that can be attached
+  # to a Keyword (in a Command object).
+  #
+  # This resource is read-only. 
+  #
+  # ==== Attributes  
+  #  
+  # * +name+ - The name of the CommandType.
+  # * +fields+ - An Array of strings representing the different fields on this 
+  #   CommandType.  Field values will always be strings.  
+  #  
+  class CommandType
+
+    include InstanceResource
+    
+    readonly_attributes :name, :fields
+  end
+end

data/lib/tms_client/resource/commands.rb

@@ -0,0 +1,3 @@
+class TMS::Commands
+  include TMS::CollectionResource
+end

data/lib/tms_client/resource/email.rb

@@ -0,0 +1,9 @@
+module TMS #:nodoc:
+  class Email
+    include InstanceResource
+
+    writeable_attributes :body, :from, :subject
+    readonly_attributes :created_at, :completed_at
+    collection_attribute :recipients, 'EmailRecipients'
+  end
+end

data/lib/tms_client/resource/email_recipient.rb

@@ -0,0 +1,7 @@
+module TMS #:nodoc:
+  class EmailRecipient
+    include InstanceResource
+
+    writeable_attributes :email
+  end
+end

data/lib/tms_client/resource/inbound_message.rb

@@ -0,0 +1,7 @@
+module TMS #:nodoc:
+  class InboundMessage
+    include InstanceResource
+
+    readonly_attributes :created_at, :completed_at, :from, :body, :to
+  end
+end