tms_client 0.0.3 → 0.1.0

data/Gemfile

@@ -1,2 +1,11 @@
 source "https://rubygems.org"
-gemspec
+gemspec
+
+group :development do
+  gem 'rspec'
+  gem 'rake'
+  gem 'redcarpet'
+  gem 'yard'
+  gem 'guard-rspec'
+  gem 'rubygems-tasks', :git => 'https://github.com/postmodern/rubygems-tasks.git'
+end

data/README.md

@@ -1,94 +1,135 @@
 TMS Client 
 ===========
-This is a ruby client to interact with the GovDelivery TMS REST API.
+This is a reference Ruby client to interact with the GovDelivery TMS REST API.
 
 Installation
 ------------
 ### Using Bundler
-``` ruby
+
+```ruby
 gem 'tms_client'
 ```
 
 ### Standalone
+
 ```
 $ gem install tms_client
 ```
 
 
-Usage 
------
-### Connecting
-
-``` ruby
-client = TMS::Client.new('username', 'password', :api_root => 'https://tms.govdelivery.com')
+Connecting
+----------
+Loading an instance of `TMS::Client` will automatically connect to the API to query the available resources for your account.
 
+```ruby
+client = TMS::Client.new('username', 'password', :api_root => 'https://stage-tms.govdelivery.com')
 ```
 
-### Getting messages
+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...
+### Loading messages
+Sms, Email, and voice messages can be retrieved with the `get` collection method.  Messages are paged in groups of 50.  To retrieve another page, used the `next` method.  This method will not be defined if another page is not available.
+
+```ruby
+client.sms_messages.get        # get the first page of sms messages
+client.sms_messages.next.get   # get the next page of sms messages
 ```
 
 
 ### Sending an SMS Message
 
-``` ruby
-message = client.sms_messages.build(:short_body=>'Test Message!')
+```ruby
+message = client.sms_messages.build(: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"]}
+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={...}>
+message.href             # "/messages/sms/87"
+message.get              # <TMS::SmsMessage href=/messages/sms/87 attributes={...}>
 ```
 
-### Sending an Voice Message
+### Sending Email
 
-``` ruby
-message = client.voice_messages.build(:url=>'www.testmessage.com')
+```ruby
+message = client.email_messages.build(:body=>'<p><a href="http://example.com">Visit here</a>', :subject => 'Hey')
+message.recipients.build(:email=>'example1@example.com')
+message.recipients.build(:email=>'example2@example.com')
+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/email/87"
+message.get              # <TMS::EmailMessage href=/messages/email/88 attributes={...}>
+```
+
+### Sending a Voice Message
+
+```ruby
+message = client.voice_messages.build(:play_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"]}
+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={...}>
+message.href             # "/messages/voice/87"
+message.get              # <TMS::VoiceMessage href=/messages/voice/87 attributes={...}>
+```
+
+Metrics
+-------
+### Viewing recipients that clicked on a link in an email
+
+```ruby
+email_message.get
+email_message.clicked.get
+email_message.clicked.collection # => [<#EmailRecipient>,...]
 ```
 
+### Viewing recipients that opened an email
+
+```ruby
+email_message.get
+email_message.opened.get
+email_message.opened.collection # => [<#EmailRecipient>,...]
+```
+
+### Viewing a list of statistics for a recipient
+
+```ruby
+email_recipient.clicks.get.collection #=> [<#EmailRecipientClick>,...]
+
+email_recipient.opens.get.collection #=> [<#EmailRecipientOpen>,...]
+```
+
+Configuring 2-way SMS
+---------------------
+
 ### Listing Command Types
+Command Types are the available commands that can be used to respond to an incoming SMS message.  
 
-``` ruby 
+```ruby 
 command_types = client.command_types.get
 command_types.collection.each do |at|
-  puts at.name   #=> "forward"
-  puts at.fields #=> ["url", "http_method", ...]
+  puts at.name   # "forward"
+  puts at.fields # ["url", "http_method", ...]
 end
-````
+```
 
 ### Managing Keywords
+Keywords are chunks of text that are used to match an incoming SMS message. 
 
-``` ruby 
+```ruby 
 # CRUD
 keyword = client.keywords.build(:name => "BUSRIDE")
-keyword.post                #=> true
-keyword.name                #=> 'busride'
+keyword.post                # true
+keyword.name                # 'busride'
 keyword.name = "TRAINRIDE"
-keyword.put                 #=> true
-keyword.name                #=> 'trainride'
-keyword.delete              #=> true
+keyword.put                 # true
+keyword.name                # 'trainride'
+keyword.delete              # true
 
 # list
 keywords = client.keywords.get
@@ -98,11 +139,12 @@ end
 ```
 
 ### Managing Commands
+Commands have a command type and one or more keywords.  The example below configures the system to respond to an incoming SMS message containing the string "RIDE" (or "ride") by forwarding an http POST to `http://example.com/new_url`.  The POST body variables are documented in GovDelivery's [TMS REST API documentation](https://govdelivery.atlassian.net/wiki/display/PM/TMS+Customer+API+Documentation#TMSCustomerAPIDocumentation-Configuring2-waySMS "GovDelivery TMS REST API").
 
 ```ruby
 # CRUD
-keywords = client.keywords.get
-keyword = keywords.collection.first.get
+keyword = client.keywords.build(:name => "RIDE")
+keyword.post
 command = keyword.commands.build(
             :name => "Forward to somewhere else", 
             :params => {:url => "http://example.com", :http_method => "get"}, 
@@ -120,21 +162,33 @@ 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. 
+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:
+The example below configures `TMS::Client` to log to `STDOUT`:
 
-``` ruby
+```ruby
 logger = Logger.new(STDOUT)
 client = TMS::Client.new('username', 'password', :logger => logger)
+```
 
+Generating Documentation
+------------------------
+This project uses [yard](https://github.com/lsegal/yard) to generate documentation.  To generate API documentation yourself, use the following series of commands from the project root: 
+
+```ruby
+# install development gems
+bundle install
+# generate documentation
+rake yard
 ```
+The generated documentation will be placed in the `doc` folder.
 
 Compatibility
 -------------
-This project is tested and compatible with REE 1.8.7 and MRI 1.9.3.  
+This project is tested and compatible with REE 1.8.7, MRI 1.9.3, and MRI 2.0.0.
 
 License
 -------

data/Rakefile

@@ -1,6 +1,11 @@
 require 'rspec/core/rake_task'
 require 'rubygems/tasks'
 require 'rubygems/tasks/scm'
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end
 
 RSpec::Core::RakeTask.new(:spec)
 Gem::Tasks.new

data/lib/tms_client/base.rb

@@ -8,7 +8,7 @@ module TMS #:nodoc:
       base.send(:extend, TMS::CoreExt)
     end
 
-    attr_accessor :client, :href, :errors
+    attr_accessor :client, :href, :errors, :new_record
 
     module ClassMethods
       def to_param
@@ -21,6 +21,15 @@ module TMS #:nodoc:
         self.client = client
         self.href = href
       end
+
+      def new_record?
+        !!self.new_record
+      end
+
+      def href=(href)
+        self.new_record=false
+        @href=href
+      end
     end
 
   end

data/lib/tms_client/client.rb

@@ -1,11 +1,11 @@
-# The client class to connect and talk to the TMS REST API. 
+# 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. 
+  # 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
@@ -13,9 +13,9 @@ class TMS::Client
   #
   # === Examples
   #   client = TMS::Client.new("foo@example.com", "onetwothree", {
-  #                               :api_root => "https://tms.govdelivery.com", 
+  #                               :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])
@@ -34,12 +34,12 @@ class TMS::Client
   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
+    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
 
@@ -62,10 +62,10 @@ class TMS::Client
   def delete(href)
     response = raw_connection.delete(href)
     case response.status
-      when 200
-        return response
-      else
-        raise TMS::Request::Error.new(response.status)
+    when 200
+      return response
+    else
+      raise TMS::Request::Error.new(response.status)
     end
   end
 
@@ -77,4 +77,4 @@ class TMS::Client
     self
   end
 
-end
+end

data/lib/tms_client/collection_resource.rb

@@ -30,6 +30,7 @@ module TMS::CollectionResource
 
     def build(attributes=nil)
       thing = instance_class(self.class).new(client, self.href, attributes || {})
+      thing.new_record = true
       self.collection << thing
       thing
     end
@@ -50,4 +51,4 @@ module TMS::CollectionResource
       end
     end
   end
-end
+end

data/lib/tms_client/errors.rb

@@ -0,0 +1,9 @@
+module TMS
+  module Errors
+    class InvalidGet < StandardError
+      def initialize(message=nil)
+        super(message || "Can't GET a resource after an invalid POST; either create a new object or fix errors")
+      end
+    end
+  end
+end

data/lib/tms_client/instance_resource.rb

@@ -88,15 +88,18 @@ module TMS::InstanceResource
     end
 
     def get
+      raise TMS::Errors::InvalidGet if self.new_record?
       set_attributes_from_hash(self.client.get(href).body)
       self
     end
 
     def post
       response = client.post(self)
+
       case response.status
-        when 201
+        when 200..299
           set_attributes_from_hash(response.body)
+          self.new_record=false
           return true
         when 401
           raise Exception.new("401 Not Authorized")
@@ -114,6 +117,7 @@ module TMS::InstanceResource
       response = client.put(self)
       case response.status
         when 200
+          self.new_record=false
           set_attributes_from_hash(response.body)
           return true
         when 401
@@ -156,6 +160,12 @@ module TMS::InstanceResource
       json_hash
     end
 
+    protected
+
+    def relation_class(rel)
+      self.class.custom_class_names[rel.to_sym] || super
+    end
+
     private
 
     def set_attributes_from_hash(hash)

data/lib/tms_client/link_header.rb

@@ -0,0 +1,223 @@
+# link_header, Copyright (c) 2009 Mike Burrows
+ 
+# Permission is hereby granted, free of charge, to any person obtaining
+# a copy of this software and associated documentation files (the
+# "Software"), to deal in the Software without restriction, including
+# without limitation the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the Software, and to
+# permit persons to whom the Software is furnished to do so, subject to
+# the following conditions:
+ 
+# The above copyright notice and this permission notice shall be
+# included in all copies or substantial portions of the Software.
+ 
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+# EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+# MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+require "strscan"
+
+#
+# Represents an HTTP link header of the form described in the draft spec http://tools.ietf.org/id/draft-nottingham-http-link-header-06.txt.
+# It is simply a list of LinkHeader::Link objects and some conversion functions.
+#
+class LinkHeader
+ 
+  # An array of Link objects
+  attr_reader :links
+  
+  #
+  # Initialize from a collection of either LinkHeader::Link objects or data from which Link objects can be created.
+  #
+  # From a list of LinkHeader::Link objects:
+  #
+  #   LinkHeader.new([
+  #     LinkHeader::Link.new("http://example.com/foo", [["rel", "self"]]),
+  #     LinkHeader::Link.new("http://example.com/",    [["rel", "up"]])])
+  #
+  # From the equivalent JSON-friendly raw data:
+  #
+  #   LinkHeader.new([
+  #     ["http://example.com/foo", [["rel", "self"]]],
+  #     ["http://example.com/",    [["rel", "up"]]]]).to_s
+  #
+  # See also LinkHeader.parse
+  #
+  def initialize(links=[])
+    if links
+      @links = links.map{|l| l.kind_of?(Link) ? l : Link.new(*l)}
+    else
+      @links = []
+    end
+  end
+  
+  #
+  # Convert to a JSON-friendly array
+  #
+  #   LinkHeader.parse('<http://example.com/foo>; rel="self", <http://example.com/>; rel = "up"').to_a
+  #   #=> [["http://example.com/foo", [["rel", "self"]]],
+  #        ["http://example.com/", [["rel", "up"]]]]
+  #
+  def to_a
+    links.map{|l| l.to_a}
+  end
+  
+  #
+  # Convert to string representation as per the link header spec
+  #
+  #   LinkHeader.new([
+  #     ["http://example.com/foo", [["rel", "self"]]],
+  #     ["http://example.com/",    [["rel", "up"]]]]).to_s
+  #   #=> '<http://example.com/foo>; rel="self", <http://example.com/>; rel = "up"'
+  #
+  def to_s
+    links.join(', ')
+  end
+  
+  #
+  # Regexes for link header parsing.  TOKEN and QUOTED in particular should conform to RFC2616.
+  #
+  # Acknowledgement: The QUOTED regexp is based on
+  # http://stackoverflow.com/questions/249791/regexp-for-quoted-string-with-escaping-quotes/249937#249937
+  #
+  HREF   = / *< *([^>]*) *> *;? */                  #:nodoc: note: no attempt to check URI validity
+  TOKEN  = /([^()<>@,;:\"\[\]?={}\s]+)/             #:nodoc: non-empty sequence of non-separator characters
+  QUOTED = /"((?:[^"\\]|\\.)*)"/                    #:nodoc: double-quoted strings with backslash-escaped double quotes
+  ATTR   = /#{TOKEN} *= *(#{TOKEN}|#{QUOTED}) */    #:nodoc:
+  SEMI   = /; */                                    #:nodoc:
+  COMMA  = /, */                                    #:nodoc:
+
+  #
+  # Parse a link header, returning a new LinkHeader object
+  #
+  #   LinkHeader.parse('<http://example.com/foo>; rel="self", <http://example.com/>; rel = "up"').to_a
+  #   #=> [["http://example.com/foo", [["rel", "self"]]],
+  #        ["http://example.com/", [["rel", "up"]]]]
+  #
+  def self.parse(link_header)
+    return new unless link_header
+    
+    scanner = StringScanner.new(link_header)
+    links = []
+    while scanner.scan(HREF)
+      href = scanner[1]
+      attrs = []
+      while scanner.scan(ATTR)
+        attr_name, token, quoted = scanner[1], scanner[3], scanner[4].gsub(/\\"/, '"')
+        attrs.push([attr_name, token || quoted])
+        break unless scanner.scan(SEMI)
+      end
+      links.push(Link.new(href, attrs))
+      break unless scanner.scan(COMMA)
+    end
+
+    new(links)
+  end
+  
+  #
+  # Find a member link that has the given attributes
+  #
+  def find_link(*attr_pairs)
+    links.detect do |link|
+      !attr_pairs.detect do |pair|
+        !link.attr_pairs.include?(pair)
+      end
+    end 
+  end
+  
+  #
+  # Render as a list of HTML link elements
+  #
+  def to_html(separator="\n")
+    links.map{|link| link.to_html}.join(separator)
+  end
+
+  #
+  # Represents a link - an href and a list of attributes (key value pairs)
+  #
+  #   LinkHeader::Link.new("http://example.com/foo", [["rel", "self"]]).to_s
+  #   => '<http://example.com/foo>; rel="self"'
+  #
+  class Link
+    #
+    # The link's URI string
+    #
+    #   LinkHeader::Link.new("http://example.com/foo", [["rel", "self"]]).href
+    #   => 'http://example.com/foo>'
+    #
+    attr_reader :href
+    
+    #
+    # The link's attributes, an array of key-value pairs
+    #
+    #   LinkHeader::Link.new("http://example.com/foo", [["rel", "self"], ["rel", "canonical"]]).attr_pairs
+    #   => [["rel", "self"], ["rel", "canonical"]]
+    #
+    attr_reader :attr_pairs
+    
+    #
+    # Initialize a Link from an href and attribute list
+    #
+    #   LinkHeader::Link.new("http://example.com/foo", [["rel", "self"]]).to_s
+    #   => '<http://example.com/foo>; rel="self"'
+    #
+    def initialize(href, attr_pairs)
+      @href, @attr_pairs = href, attr_pairs
+    end
+    
+    #
+    # Lazily convert the attribute list to a Hash
+    #
+    # Beware repeated attribute names (it's safer to use #attr_pairs if this is risk):
+    #
+    #   LinkHeader::Link.new("http://example.com/foo", [["rel", "self"], ["rel", "canonical"]]).attrs
+    #   => {"rel" =>"canonical"}
+    #
+    def attrs
+      @attrs ||= Hash[*attr_pairs.flatten]
+    end
+    
+    #
+    # Access #attrs by key
+    #
+    def [](key)
+      attrs[key]
+    end
+    
+    #
+    # Convert to a JSON-friendly Array
+    #
+    #   LinkHeader::Link.new("http://example.com/foo", [["rel", "self"], ["rel", "canonical"]]).to_a
+    #   => ["http://example.com/foo", [["rel", "self"], ["rel", "canonical"]]]
+    #
+    def to_a
+      [href, attr_pairs]
+    end
+    
+    #
+    # Convert to string representation as per the link header spec.  This includes backspace-escaping doublequote characters in
+    # quoted attribute values.
+    #
+    # Convert to string representation as per the link header spec
+    #
+    #   LinkHeader::Link.new(["http://example.com/foo", [["rel", "self"]]]).to_s
+    #   #=> '<http://example.com/foo>; rel="self"'
+    #
+    def to_s
+      (["<#{href}>"] + attr_pairs.map{|k, v| "#{k}=\"#{v.gsub(/"/, '\"')}\""}).join('; ')
+    end
+    
+    #
+    # Bonus!  Render as an HTML link element
+    #
+    #   LinkHeader::Link.new(["http://example.com/foo", [["rel", "self"]]]).to_html
+    #   #=> '<link href="http://example.com/foo" rel="self">'
+    def to_html
+      ([%Q(<link href="#{href}")] + attr_pairs.map{|k, v| "#{k}=\"#{v.gsub(/"/, '\"')}\""}).join(' ')
+    end
+  end
+end

data/lib/tms_client/resource/collections.rb

@@ -10,7 +10,7 @@ class TMS::SmsMessages
   include TMS::CollectionResource
 end
 
-class TMS::Emails
+class TMS::EmailMessages
   include TMS::CollectionResource
 end
 
@@ -22,6 +22,14 @@ class TMS::EmailRecipients
   include TMS::CollectionResource
 end
 
+class TMS::EmailRecipientOpens
+  include TMS::CollectionResource
+end
+
+class TMS::EmailRecipientClicks
+  include TMS::CollectionResource
+end
+
 # A collection of Keyword objects.
 #
 # === Example
@@ -47,3 +55,7 @@ end
 class TMS::CommandTypes
   include TMS::CollectionResource
 end
+
+class TMS::Commands
+  include TMS::CollectionResource
+end

data/lib/tms_client/resource/command.rb

@@ -17,7 +17,10 @@ module TMS #:nodoc:
   class Command
     include InstanceResource
 
+    # @!parse attr_accessor :name, :command_type, :params
     writeable_attributes :name, :command_type, :params
+    
+    # @!parse attr_reader :created_at, :updated_at
     readonly_attributes :created_at, :updated_at
 
   end

data/lib/tms_client/resource/command_type.rb

@@ -14,6 +14,7 @@ module TMS #:nodoc:
 
     include InstanceResource
     
+    # @!parse attr_reader :fields, :name
     readonly_attributes :name, :fields
   end
 end

data/lib/tms_client/resource/email_message.rb

@@ -0,0 +1,52 @@
+module TMS #:nodoc:
+  # An EmailMessage is used to create and send a email to a collection of EmailRecipient
+  # objects.  Certain metrics are available after the email is sent, including
+  # the collection of recipients who clicked or opened the email. 
+  # 
+  #
+  # ==== Attributes  
+  # 
+  # * +from_name+ - The name of the person or entity sending the email.  
+  # * +subject+   - The subject of the email
+  # * +body+      - The body of the email
+  #
+  # 
+  # === Example
+  # Sending a message
+  #    email_message = client.email_messages.build(:subject => "Great news!", :body => "You win! <a href='http://example.com/'>click here</a>.")
+  #    email_message.recipients.build(:email => "john@example.com")
+  #    email_message.recipients.build(:email => "jeff@example.com")
+  #    email_message.post
+  #    email_message.get
+  #
+  # Viewing recipients that clicked on a link in the email
+  #    email_message.get
+  #    email_message.clicked.get
+  #    email_message.clicked.collection # => [<#EmailRecipient>,...]
+  #
+  # Viewing recipients that opened the email
+  #    email_message.get
+  #    email_message.opened.get
+  #    email_message.opened.collection # => [<#EmailRecipient>,...]
+  class EmailMessage
+    include InstanceResource
+
+    # @!parse attr_accessor :body, :from_name, :subject
+    writeable_attributes :body, :from_name, :subject
+
+    # @!parse attr_reader :created_at, :status
+    readonly_attributes :created_at, :status
+
+    ##
+    # A CollectionResource of EmailRecipients on this email
+    collection_attribute :recipients, 'EmailRecipients'
+
+    ##
+    # A CollectionResource of EmailRecipients that opened this email
+    collection_attribute :opened, 'EmailRecipients'
+
+    ##
+    # A CollectionResource of EmailRecipients that clicked on at least one link in this email
+    collection_attribute :clicked, 'EmailRecipients'
+  end
+end

data/lib/tms_client/resource/email_recipient.rb

@@ -2,6 +2,18 @@ module TMS #:nodoc:
   class EmailRecipient
     include InstanceResource
 
+    # @!parse attr_accessor :email
     writeable_attributes :email
+
+    # @!parse attr_reader :completed_at
+    readonly_attributes :completed_at
+
+    ##
+    # A CollectionResource of EmailRecipientOpens for this EmailRecipient
+    collection_attribute :opens, 'EmailRecipientOpens'
+
+    ##
+    # A CollectionResource of EmailRecipientClicks for this EmailRecipient
+    collection_attribute :clicks, 'EmailRecipientClicks'
   end
-end
+end

data/lib/tms_client/resource/email_recipient_click.rb

@@ -0,0 +1,8 @@
+module TMS #:nodoc:
+  class EmailRecipientClick
+    include InstanceResource
+
+    # @!parse attr_reader :event_at, :url
+    readonly_attributes :event_at, :url
+  end
+end

data/lib/tms_client/resource/email_recipient_open.rb

@@ -0,0 +1,8 @@
+module TMS #:nodoc:
+  class EmailRecipientOpen
+    include InstanceResource
+
+    # @!parse attr_reader :event_at
+    readonly_attributes :event_at
+  end
+end

data/lib/tms_client/resource/inbound_sms_message.rb

@@ -1,7 +1,8 @@
 module TMS #:nodoc:
   class InboundSmsMessage
     include InstanceResource
-
+    
+    # @!parse attr_reader :created_at, :completed_at, :from, :body, :to
     readonly_attributes :created_at, :completed_at, :from, :body, :to
   end
 end

data/lib/tms_client/resource/keyword.rb

@@ -15,7 +15,11 @@ module TMS #:nodoc:
   class Keyword
     include InstanceResource
 
+    # @!parse attr_accessor :name
     writeable_attributes :name
+
+    ##
+    # A CollectionResource of Command objects
     collection_attributes :commands
 
   end

data/lib/tms_client/resource/recipient.rb

@@ -1,8 +1,10 @@
 module TMS #:nodoc:
   class Recipient
     include InstanceResource
-
+    # @!parse attr_accessor :phone
     writeable_attributes :phone
-    readonly_attributes :formatted_phone, :error_message, :status
+
+    # @!parse attr_reader :formatted_phone, :error_message, :status, :completed_at
+    readonly_attributes :formatted_phone, :error_message, :status, :completed_at
   end
 end

data/lib/tms_client/resource/sms_message.rb

@@ -1,9 +1,28 @@
 module TMS #:nodoc:
+  # An SMSMessage is used to create and send a text message to a collection of Recipient
+  # objects.
+  # 
+  #
+  # ==== Attributes  
+  # 
+  # * +body+ - The content of the SMS.  This field will be truncated to 160 characters. 
+  # 
+  # === Example
+  #    sms = client.sms_messages.build(:body => "Hello")
+  #    sms.recipients.build(:phone => "+18001002000")
+  #    sms.post
+  #    sms.get
   class SmsMessage
     include InstanceResource
+    
+    # @!parse attr_accessor :body
+    writeable_attributes :body
 
-    writeable_attributes :from, :body, :subject
-    readonly_attributes :created_at, :completed_at
+    # @!parse attr_reader :created_at, :completed_at, :status
+    readonly_attributes :created_at, :completed_at, :status
+
+    ##
+    # A CollectionResource of Recipient objects
     collection_attributes :recipients
   end
 end

data/lib/tms_client/resource/voice_message.rb

@@ -1,9 +1,29 @@
 module TMS #:nodoc:
+  # A VoiceMessage is used to create and send a voice message to a collection of Recipient
+  # objects.  The recipients are called and the provided +play_url+ is 
+  # played to them.  Accepted sound formats include +wav+, +mp3+, and +aiff+. 
+  # 
+  #
+  # ==== Attributes  
+  # 
+  # * +play_url+ - The url to the sound file to be played back to the call recipients
+  # 
+  # === Example
+  #    voice_message = client.voice_messages.build(:play_url => "http://example.com/emergency_weather.mp3")
+  #    voice_message.recipients.build(:phone => "+18001002000")
+  #    voice_message.post
+  #    voice_message.get
   class VoiceMessage
     include InstanceResource
 
+    # @!parse attr_accessor :play_url
     writeable_attributes :play_url
-    readonly_attributes :created_at, :completed_at
+
+    # @!parse attr_reader :created_at, :completed_at, :status
+    readonly_attributes :created_at, :completed_at, :status
+
+    ##
+    # A CollectionResource of Recipient objects
     collection_attributes :recipients
 
     def self.to_s

data/lib/tms_client/util/hal_link_parser.rb

@@ -29,7 +29,7 @@ module TMS::Util
         if rel == 'self'
           self.href = href
         else
-          klass = ::TMS.const_get(classify(rel)) rescue nil
+          klass = relation_class(rel)
           klass = self.class if ['first', 'prev', 'next', 'last'].include?(rel)
           if klass
             subresources[rel] = klass.new(self.client, href)
@@ -42,6 +42,10 @@ module TMS::Util
       end
     end
 
+    def relation_class(rel)
+      ::TMS.const_get(classify(rel)) rescue nil
+    end
+
     def setup_subresource(link)
       return unless link
       link.each { |rel, href| self.metaclass.send(:define_method, rel.to_sym, &lambda { subresources[rel] }) unless rel == 'self' }

data/lib/tms_client/version.rb

@@ -1,3 +1,3 @@
 module TMS #:nodoc:
-  VERSION = "0.0.3"
+  VERSION = "0.1.0"
 end

data/lib/tms_client.rb

@@ -4,9 +4,9 @@ end
 require 'active_support'
 require 'tms_client/version'
 require 'faraday'
-require 'link_header'
 require 'faraday_middleware'
 
+require 'tms_client/link_header'
 require 'tms_client/util/hal_link_parser'
 require 'tms_client/util/core_ext'
 require 'tms_client/connection'
@@ -16,15 +16,18 @@ require 'tms_client/base'
 require 'tms_client/instance_resource'
 require 'tms_client/collection_resource'
 require 'tms_client/request'
+require 'tms_client/errors'
 
 require 'tms_client/resource/collections'
 require 'tms_client/resource/recipient'
 require 'tms_client/resource/email_recipient'
+require 'tms_client/resource/email_recipient_open'
+require 'tms_client/resource/email_recipient_click'
 require 'tms_client/resource/sms_message'
 require 'tms_client/resource/voice_message'
+require 'tms_client/resource/email_message'
 require 'tms_client/resource/inbound_sms_message'
 require 'tms_client/resource/command_type'
 require 'tms_client/resource/command'
-require 'tms_client/resource/commands'
 require 'tms_client/resource/keyword'
-require 'tms_client/resource/email'
+

data/spec/inbound_sms_messages_spec.rb

@@ -6,7 +6,7 @@ describe TMS::InboundSmsMessages do
       double('client')
     end
     before do
-      @messages = TMS::InboundSmsMessages.new(client, '/inbound_sms_messages')
+      @messages = TMS::InboundSmsMessages.new(client, '/inbound_messages')
     end
     it 'should GET itself' do
       body = [{:body=>"HELP", :from=>"+16125551212", :created_at=>"a while ago", :to=>"(651) 433-6258"}, {:body=>"STOP", :from=>"+16125551212", :created_at=>"a while ago", :to=>"(651) 433-6258"}]

data/spec/instance_resource_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+class Foo
+  include TMS::InstanceResource
+  writeable_attributes :bar
+  collection_attribute :blah, 'EmailMessage'
+end
+
+describe TMS::InstanceResource do
+  context "creating a new inbound messages list" do
+    let(:happy_response) do
+      double(:status => 201,  :body => {})
+    end
+
+    let(:client) do
+      double('client', :post => happy_response)
+    end
+
+
+    before do
+      @instance_resource = Foo.new(client)
+    end
+
+    it 'should POST' do
+      @instance_resource.bar = "OMG"
+      @instance_resource.post.should be_true
+    end
+
+    it 'should correctly reflect on collection resources' do
+      @instance_resource.blah.class.should == TMS::EmailMessage
+    end
+  end
+end

data/tms_client.gemspec

@@ -19,10 +19,6 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency "faraday"
   s.add_runtime_dependency "faraday_middleware"
   s.add_runtime_dependency "activesupport"
-  s.add_runtime_dependency "link_header"
-  s.add_development_dependency "rspec"
-  s.add_development_dependency "rake"
-  s.add_development_dependency "rubygems-tasks"
 
   s.files       = %w{
     Gemfile

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tms_client
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-23 00:00:00.000000000 Z
+date: 2013-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -59,70 +59,6 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: link_header
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rspec
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: rubygems-tasks
-  requirement: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: '0'
 description: ! 'A reference implementation, written in Ruby, to interact with GovDelivery''s
   TMS API. The client is compatible with Ruby versions 1.8.7 and 1.9.3. '
 email:
@@ -139,15 +75,18 @@ files:
 - lib/tms_client/client.rb
 - lib/tms_client/collection_resource.rb
 - lib/tms_client/connection.rb
+- lib/tms_client/errors.rb
 - lib/tms_client/instance_resource.rb
+- lib/tms_client/link_header.rb
 - lib/tms_client/logger.rb
 - lib/tms_client/request.rb
 - lib/tms_client/resource/collections.rb
 - lib/tms_client/resource/command.rb
 - lib/tms_client/resource/command_type.rb
-- lib/tms_client/resource/commands.rb
-- lib/tms_client/resource/email.rb
+- lib/tms_client/resource/email_message.rb
 - lib/tms_client/resource/email_recipient.rb
+- lib/tms_client/resource/email_recipient_click.rb
+- lib/tms_client/resource/email_recipient_open.rb
 - lib/tms_client/resource/inbound_sms_message.rb
 - lib/tms_client/resource/keyword.rb
 - lib/tms_client/resource/recipient.rb
@@ -160,6 +99,7 @@ files:
 - spec/client_spec.rb
 - spec/command_types_spec.rb
 - spec/inbound_sms_messages_spec.rb
+- spec/instance_resource_spec.rb
 - spec/keyword_spec.rb
 - spec/keywords_spec.rb
 - spec/message_spec.rb
@@ -186,7 +126,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 1.8.25
 signing_key: 
 specification_version: 3
 summary: A ruby client to interact with the GovDelivery TMS REST API.
@@ -194,6 +134,7 @@ test_files:
 - spec/client_spec.rb
 - spec/command_types_spec.rb
 - spec/inbound_sms_messages_spec.rb
+- spec/instance_resource_spec.rb
 - spec/keyword_spec.rb
 - spec/keywords_spec.rb
 - spec/message_spec.rb

data/lib/tms_client/resource/commands.rb

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

data/lib/tms_client/resource/email.rb

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