govdelivery-tms 0.8.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    ZWUwNjNlYmFmOTc5Y2I4ODIwYmZhNTVkOWU0MGUzMzJjOTZiYzA1ZA==
+  data.tar.gz: !binary |-
+    NWNmYzNlYjRlOWI4NjVmYmUzOTQzNzBkMDViNTExNTIwZWNhNDRiMw==
+SHA512:
+  metadata.gz: !binary |-
+    NjJiNTAxMGVhZGY4ZTY0M2JmNGIwNzkwZDY1NWMxYzA2NDBiYzI4ZGE4MjBh
+    Njg5OTUyODgzNDJmMzE2MTUxNWNmNjM5Y2M3MjBmYTQ0MmJhMzA1M2Q2MmQ5
+    MzNhZmY5MTU5YTRhM2MwM2FkYzVlYTVlYmMzZjVlNmM5ZmE2MWY=
+  data.tar.gz: !binary |-
+    OTAzZDMxMDdkMjI2NDBjNDQxYzk1NzA2YzA5ZmJiYjI3YTQ1YWJmMzJjMGVj
+    NjI4ZjExMmQzYzg5MTNiODE2YTVmMGNhYTZkYmU2NzE4ZWQ1NWFjMDU0YjRi
+    NzkxZDMyMzM4ZDI2YmU4NzE2OTE5YzY4NmFlN2VjOTA5ZmM1Yjc=

data/Gemfile

@@ -0,0 +1,14 @@
+source "https://rubygems.org"
+gemspec
+
+group :development, :test do
+  gem "appraisal"
+  gem 'rspec', '~> 2.99'
+  gem 'rspec-its'
+  gem 'rake'
+  gem 'redcarpet', :platform => :ruby
+  gem 'yard'
+  gem 'mail'
+  gem 'rubygems-tasks', :git => 'https://github.com/postmodern/rubygems-tasks.git', :platform => :ruby
+end
+

data/README.md

@@ -0,0 +1,324 @@
+[![Build Status](https://travis-ci.org/govdelivery/govdelivery-tms-ruby.svg?branch=master)](https://travis-ci.org/govdelivery/govdelivery-tms-ruby)
+
+TMS Client
+===========
+This is a reference Ruby client to interact with the GovDelivery TMS REST API.
+
+Installation
+------------
+### Using Bundler
+
+```ruby
+gem 'govdelivery-tms'
+```
+
+### Standalone
+
+```
+$ gem install govdelivery-tms
+```
+
+
+Connecting
+----------
+Loading an instance of `TMS::Client` will automatically connect to the API to query the available resources for your account.
+
+```ruby
+# default api root endpoint is https://tms.govdelivery.com
+client = TMS::Client.new('auth_token', :api_root => 'https://stage-tms.govdelivery.com')
+```
+
+Messages
+--------
+
+### Loading messages
+Sms and Email 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(: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/sms/87"
+message.get              # <TMS::SmsMessage href=/messages/sms/87 attributes={...}>
+```
+
+### Retrieving Inbound SMS Messages
+```ruby
+client.inbound_sms_messages.get                             # <TMS::InboundSmsMessages href=/inbound/sms attributes={...}>
+inbound_sms = client.inbound_sms_messages.collection.first  # <TMS::InboundSmsMessage href=/inbound/sms/10041 attributes={...}>
+inbound_sms.to                                              # "+15559999999"
+inbound_sms.from                                            # "+15005550006"
+inbound_sms.attributes                                      # {:from=>"+15005550006", :to=>"+15559999999", :body=>"test", :command_status=>"success", :keyword_response=>"kwidjebo", :created_at=>"2014-11-05T17:15:01Z"}
+
+```
+
+### Sending an Email Message
+
+```ruby
+message = client.email_messages.build(:body=>'<p><a href="http://example.com">Visit here</a>',
+                                      :subject => 'Hey',
+                                      :from_email => 'foo@example.com')
+message.recipients.build(:email=>'example1@example.com')
+message.recipients.build(:email=>'')
+message.post             # true
+message.recipients.collection.detect{|r| r.errors } # {"email"=>["can't be blank"]}
+# save succeeded, but we have one bad recipient
+message.href             # "/messages/email/87"
+message.get              # <TMS::EmailMessage href=/messages/email/88 attributes={...}>
+```
+
+#### Sending an Email with Macros
+
+```ruby
+message = client.email_messages.build(:subject=>'Hello!',
+                                      :body=>'<p>Hi <span style="color:red;">[[name]]</span>!</p>',
+                                      :macros=>{"name"=>"there"})
+message.recipients.build(:email=>'jim@example.com', :macros=>{"name"=>"Jim"})
+message.recipients.build(:email=>'amy@example.com', :macros=>{"name"=>"Amy"})
+message.recipients.build(:email=>'bill@example.com')
+message.post
+```
+
+### Obtaining IPAWS Ack ###
+```ruby
+client.ipaws_acknowledgement.get
+client.ipaws_acknowledgement.ACK # "PONG"
+```
+
+### Obtaining IPAWS COG Profile
+```ruby
+client.ipaws_cog_profile.get
+client.ipaws_cog_profile.attributes # {:cogid=>"120082", :name=>"GovDelivery" ... }
+```
+
+### Determining NWEM COG Authorization ###
+```ruby
+client.ipaws_nwem_authorization.get
+client.ipaws_nwem_authorization.cogid # true
+```
+
+### Obtaining NWEM Auxilary Data (Authorized areas) ###
+```ruby
+client.ipaws_nwem_areas.get
+client.ipaws_nwem_areas.collection.first.countyFipsCd # "51013"
+```
+
+### Sending an IPAWS Alert ###
+```ruby
+alert = client.ipaws_alerts.build({ identifier: "CAP12-TEST-12345", sender: 'test@open.com' ...})
+alert.post # true
+alert.ipaws_response # { "identifier"=>"CAP12-TEST-1397743203", "statuses"=> [{"CHANNELNAME"=>"CAPEXCH" ... }]}
+```
+
+
+Webhooks
+-------
+### POST to a URL when a recipient is blacklisted (i.e. to remove from your list)  
+
+
+```ruby
+webhook = client.webhooks.build(:url=>'http://your.url', :event_type=>'blacklisted')
+webhook.post # true
+```
+
+POSTs will include in the body the following attributes:
+
+  attribute   |  description
+------------- | -------------
+message_type  | 'sms' or 'email'
+status:       |  message state
+recipient_url |  recipient URL
+messsage_url  |  message URL
+error_message |  (failures only)
+completed_at  |  (sent or failed recipients only)
+
+
+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
+command_types = client.command_types.get
+command_types.collection.each do |at|
+  puts at.name          # "forward"
+  puts at.string_fields # ["url", ...]
+  puts at.array_fields  # ["foo", ...]
+end
+```
+
+### Managing Keywords
+Keywords are chunks of text that are used to match an incoming SMS message.
+
+```ruby
+# CRUD
+keyword = client.keywords.build(:name => "BUSRIDE", :response_text => "Visit example.com/rides for more info")
+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, k.response_text
+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
+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"},
+            :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
+```
+
+### Viewing Command Actions
+Each time a given command is executed, a command action is created.
+
+**Note** The actions relationship does not exist on commands that have 0 command actions. Because of this, an attempt to access the command_actions attribute of a
+command that has 0 command actions will result in a NoMethodError.
+
+```ruby
+# Using the command from above
+begin
+  command.get
+  command_actions = command.command_actions
+  command_actions.get
+  command_action = command_actions.collection.first
+  command_action.inbound_sms_message		# InboundSmsMessage object that initiated this command execution
+  command_action.response_body			# String returned by the forwarded to URL
+  command_action.status				# HTTP Status returned by the forwarded to URL
+  command_action.content_type			# Content-Type header returned by the forwarded to URL
+rescue NoMethodError => e
+  # No command actions to view
+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('auth_token', :logger => logger)
+```
+
+ActionMailer integration
+------------------------
+
+You can use TMS from the mail gem or ActionMailer as a delivery method.
+
+Gemfile
+```ruby
+gem 'govdelivery-tms', :require=>'govdelivery-tms/mail/delivery_method'
+```
+
+config/environment.rb
+```ruby
+config.action_mailer.delivery_method = :govdelivery_tms
+config.action_mailer.govdelivery_tms_settings = {
+    :auth_token=>'auth_token',
+    :api_root=>'https://stage-tms.govdelivery.com'
+    }
+```
+
+
+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.
+
+
+Running Tests
+-------------
+```ruby
+appraisal install
+# optionally specify an activesupport version to test against (2/3/4), e.g.
+# appraisal 4 rake          ## for ruby 2.1.2
+appraisal rake
+```
+
+
+Compatibility
+-------------
+This project is tested and compatible with MRI 1.9.3, JRuby 1.7.12, and MRI 2.1.2.
+
+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,20 @@
+require "rubygems"
+require "bundler/setup"
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+unless defined?(JRUBY_VERSION)
+  require 'rubygems/tasks'
+  require 'rubygems/tasks/scm'
+  Gem::Tasks.new
+end
+require 'yard'
+
+YARD::Rake::YardocTask.new do |t|
+  t.files = ['lib/**/*.rb']
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+
+task :default => :spec
+

data/govdelivery-tms.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "govdelivery-tms/version"
+
+Gem::Specification.new do |s|
+  s.name        = "govdelivery-tms"
+  s.version     = TMS::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["GovDelivery"]
+  s.email       = ["support@govdelivery.com"]
+  s.homepage    = "http://govdelivery.com"
+  s.summary     = %q{A ruby client to interact with the GovDelivery TMS REST API.}
+  s.description = %q{A reference implementation, written in Ruby,
+                     to interact with GovDelivery's TMS API. The client is
+                     compatible with Ruby 1.9 and 2.0. }
+
+  s.add_runtime_dependency "activesupport"
+  s.add_runtime_dependency "faraday"
+  s.add_runtime_dependency "faraday_middleware"
+
+  s.files       = %w{
+    Gemfile
+    README.md
+    Rakefile
+    govdelivery-tms.gemspec
+  } + Dir["lib/**/*"]
+
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.require_paths = ["lib"]
+end

data/lib/govdelivery-tms.rb

@@ -0,0 +1,43 @@
+module TMS #:nodoc:
+end
+
+require 'active_support/core_ext/hash'
+require 'govdelivery-tms/version'
+require 'faraday'
+require 'faraday_middleware'
+
+require 'govdelivery-tms/link_header'
+require 'govdelivery-tms/util/hal_link_parser'
+require 'govdelivery-tms/util/core_ext'
+require 'govdelivery-tms/connection'
+require 'govdelivery-tms/client'
+require 'govdelivery-tms/logger'
+require 'govdelivery-tms/base'
+require 'govdelivery-tms/instance_resource'
+require 'govdelivery-tms/collection_resource'
+require 'govdelivery-tms/errors'
+
+require 'govdelivery-tms/resource/collections'
+require 'govdelivery-tms/resource/recipient'
+require 'govdelivery-tms/resource/email_recipient'
+require 'govdelivery-tms/resource/email_recipient_open'
+require 'govdelivery-tms/resource/email_recipient_click'
+require 'govdelivery-tms/resource/from_address'
+require 'govdelivery-tms/resource/email_template'
+require 'govdelivery-tms/resource/sms_message'
+require 'govdelivery-tms/resource/email_message'
+require 'govdelivery-tms/resource/inbound_sms_message'
+require 'govdelivery-tms/resource/command_type'
+require 'govdelivery-tms/resource/command_action'
+require 'govdelivery-tms/resource/command'
+require 'govdelivery-tms/resource/keyword'
+require 'govdelivery-tms/resource/ipaws_static_resource'
+require 'govdelivery-tms/resource/ipaws_category'
+require 'govdelivery-tms/resource/ipaws_event_code'
+require 'govdelivery-tms/resource/ipaws_response_type'
+require 'govdelivery-tms/resource/ipaws_acknowledgement'
+require 'govdelivery-tms/resource/ipaws_cog_profile'
+require 'govdelivery-tms/resource/ipaws_nwem_authorization'
+require 'govdelivery-tms/resource/ipaws_nwem_area'
+require 'govdelivery-tms/resource/ipaws_alert'
+require 'govdelivery-tms/resource/webhook'