dcm_client 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 13acb0bebdf78585fceca974dd5f59a9ec9248da
+  data.tar.gz: 77c314e7f8e34d8507f67c4c8ec31f39c3b5d64a
+SHA512:
+  metadata.gz: 9a427ccea1e81916c4b524b00c838e7b68be26da0130b6e28ee951767ade8b4e2fde1d820719a77f583647aac395ee6ef94c1880daa00b0664ce1680acd0658d
+  data.tar.gz: 643d5a4d6fffd4e8cf100f4033f6a1fbef3c9e543383bb9858c483a2b5319952b9082a0df95ab375146b9b7f1617b7df7e48a9f9943b5f9dc00e27d6e2527881

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in dcm_client.gemspec
+gemspec

data/README.md

@@ -0,0 +1,27 @@
+# DCMClient
+
+DCMClient is a Ruby library to interact with GovDelivery's Digital Communication Management REST API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'dcm_client'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install dcm_client
+
+## Usage
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/dcm_client.gemspec

@@ -0,0 +1,34 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "dcm_client/version"
+
+Gem::Specification.new do |s|
+  s.name        = "dcm_client"
+  s.version     = DCMClient::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 DCM REST API.}
+  s.description = %q{A reference implementation, written in Ruby, to interact with GovDelivery's DCM API.}
+
+  if RUBY_VERSION < "1.9"
+    s.add_runtime_dependency "json" # this is part of 1.9's stdlib
+  end
+
+  s.add_runtime_dependency "faraday"
+  s.add_runtime_dependency "faraday_middleware"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rake"
+
+  s.files       = %w{
+    Gemfile
+    README.md
+    Rakefile
+    dcm_client.gemspec
+  }.concat(Dir["lib/**/*"])
+
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+end

data/lib/dcm_client.rb

@@ -0,0 +1,16 @@
+# stdlib
+require 'base64'
+require 'json'
+
+# gems
+require 'faraday'
+require 'faraday_middleware'
+
+# project
+require 'dcm_client/version'
+require 'dcm_client/connection'
+require 'dcm_client/client'
+require 'dcm_client/error'
+
+module DCMClient
+end

data/lib/dcm_client/client.rb

@@ -0,0 +1,69 @@
+module DCMClient
+  class Client
+    UNSUBSCRIBE_URI = '/api/account/%s/subscribers/%s'
+    SUBSCRIBE_URI   = '/api/account/%s/subscribers/add_subscriptions'
+
+    attr_reader :connection
+    
+    ##
+    # Create and return a new client with an established connection to DCM.
+    #
+    #   :username
+    #   :password
+    #   :api_root - fully-qualified root URL to DCM, including protocol and (optional) port.
+    #
+    def initialize(opts={})
+      @connection = Connection.new(opts)
+    end
+    
+    ## 
+    # Completely remove a wireless subscriber from an account. 
+    #   number - String - the wireless number (with country code), formatted as CC+NUMBER
+    #            Ex: 1+4444444444
+    #   account - String - the account code
+    #
+    def delete_wireless_subscriber(number, account)
+      number = Base64.encode64(number).strip
+      @connection.delete(UNSUBSCRIBE_URI % [account, number])
+    end
+
+    ## 
+    # Add one or more subscriptions to a wireless subscriber. If the subscriber doesn't exist it will be created.
+    #   number             - String  - the wireless number (with country code), formatted as CC+NUMBER
+    #                                  Ex: 1+4444444444
+    #   account            - String  - the account code
+    #   topics             - Array   - the topics to subscribe
+    #   send_notifications - Boolean - whether DCM should send the subscriber a notification (defaults to true)
+    #
+    def wireless_subscribe(number, account, topics, send_notifications=true)
+      country_code, rest = number.split('+')
+      sub = {
+        :subscriber => {
+          :phone =>  rest,
+          :country_code =>  country_code,
+          :send_notifications => send_notifications,
+          :topics => topics.map{|code| {:code => code} }
+        }
+      }
+      @connection.post(SUBSCRIBE_URI % account, sub)
+    end
+
+    ## 
+    # Add one or more subscriptions to a wireless subscriber. If the subscriber doesn't exist it will be created.
+    #   email              - String  - the email address to subscribe
+    #   account            - String  - the account code
+    #   topics             - Array   - the topics to subscribe
+    #   send_notifications - Boolean - whether DCM should send the subscriber a notification (defaults to true)
+    #
+    def email_subscribe(email, account, topics, send_notifications=true)
+      sub = {
+        :subscriber => {
+          :email => email,
+          :send_notifications => send_notifications,
+          :topics => topics.map{|code| {:code => code} }
+        }
+      }
+      @connection.post(SUBSCRIBE_URI % account, sub)
+    end
+  end
+end

data/lib/dcm_client/connection.rb

@@ -0,0 +1,56 @@
+module DCMClient
+  class Connection
+    attr_accessor :username, :password, :api_root, :connection, :logger
+
+    def post(href, body)
+      wrap do
+        connection.post do |req|
+          req.url href
+          req.body = body.to_json
+        end
+      end
+    end
+
+    def delete(href)
+      wrap do
+        connection.delete("#{href}.json")
+      end
+    end
+
+    def initialize(opts={})
+      self.username = opts[:username]
+      self.password = opts[:password]
+      self.api_root = opts[:api_root]
+      self.logger   = opts[:logger]
+    end
+
+    def connection
+      @connection ||= Faraday.new(:url => self.api_root) do |faraday|
+        faraday.use Faraday::Response::Logger, self.logger if self.logger
+        faraday.use Faraday::Response::RaiseError
+        faraday.headers[:user_agent] = DCMClient::USER_AGENT
+        faraday.request :json
+        faraday.basic_auth(self.username, self.password)
+        faraday.response :json, :content_type => /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    private
+
+    def wrap
+      yield
+    rescue Faraday::Error::ResourceNotFound => e
+      raise DCMClient::Error::NotFound.new(e)
+    rescue Faraday::Error::ClientError => e
+      if e.response.respond_to?(:[]) && e.response[:status] == 422
+        raise DCMClient::Error::UnprocessableEntity.new(e) 
+      else
+        raise DCMClient::Error.new(e)
+      end
+    rescue Exception => e
+      raise DCMClient::Error.new(e)
+    end
+
+  end
+end

data/lib/dcm_client/error.rb

@@ -0,0 +1,36 @@
+require 'ostruct'
+
+module DCMClient
+  # A parent error class makes it easier to trap any error 
+  # from client code. 
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(arg, response=nil)
+      self.response = response
+      if (arg.respond_to?(:backtrace))
+        super(arg.message)
+        self.set_backtrace(arg.backtrace)
+        if (arg.respond_to?(:response))
+          self.response = arg.response
+        end
+      else
+        super(arg.to_s)
+      end
+    end
+
+    # Faraday responses aren't actually of class Faraday::Response, which is annoying.
+    # This makes them respond the the methods we need in XACT!
+    def response=(_response)
+      @response = _response.is_a?(Hash) ? OpenStruct.new(_response) : _response
+    end
+  end
+
+  # Specific error types
+  class Error::NotFound < Error
+  end
+  class Error::TimeoutError < Error
+  end
+  class Error::UnprocessableEntity < Error
+  end
+end

data/lib/dcm_client/version.rb

@@ -0,0 +1,4 @@
+module DCMClient
+  VERSION = "0.2.0"
+  USER_AGENT = "Mozilla/5.0 (compatible; GovDelivery DCM Client v#{VERSION} ; http://govdelivery.com)"
+end

data/spec/client_spec.rb

@@ -0,0 +1,54 @@
+require 'spec_helper'
+
+describe DCMClient::Client do
+  subject {
+    client = DCMClient::Client.new({})
+  }
+
+  it 'should invoke delete correctly' do
+    number = "+15555555555"
+    account = 'ACME'
+
+    connection = double('connection')
+    sub = Base64.encode64(number).strip
+    connection.should_receive(:delete).with("/api/account/#{account}/subscribers/#{sub}")
+    DCMClient::Connection.stub(:new).and_return(connection)
+    subject.delete_wireless_subscriber(number, account)
+  end
+
+  it 'should invoke wireless update correctly' do
+    number = '5555555555'
+    country_code = '1'
+    account = 'ACME'
+
+    connection = double('connection')
+    sub = {
+      :subscriber => {
+        :phone =>  '5' * 10,
+        :country_code =>  '1',
+        :send_notifications => true,
+        :topics => [{:code => 'TOPIC'}]
+      }
+    }
+    connection.should_receive(:post).with("/api/account/#{account}/subscribers/add_subscriptions", sub)
+    DCMClient::Connection.stub(:new).and_return(connection)
+    subject.wireless_subscribe("#{country_code}+#{number}", account, ['TOPIC'])
+  end
+
+  it 'should invoke update correctly' do
+    email = 'joe@example.com'
+    account = 'ACME'
+
+    connection = double('connection')
+    sub = {
+      :subscriber => {
+        :email =>  email,
+        :send_notifications => true,
+        :topics => [{:code => 'TOPIC'}]
+      }
+    }
+    connection.should_receive(:post).with("/api/account/#{account}/subscribers/add_subscriptions", sub)
+    DCMClient::Connection.stub(:new).and_return(connection)
+    subject.email_subscribe(email, account, ['TOPIC'])
+  end
+end

data/spec/connection_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe DCMClient::Connection do
+  it 'intercepts 422 errors and raises DCMClient::UnprocessableEntity' do
+    conn = DCMClient::Connection.new
+    faraday = double('Faraday Connection')
+    error = Faraday::Error::ClientError.new(:status => 422)
+    faraday.stub(:post).and_raise(error)
+    conn.stub(:connection).and_return(faraday)
+    lambda {conn.post('hello', 'body')}.should raise_error(DCMClient::Error::UnprocessableEntity)
+  end
+end
+

data/spec/dcm_client_spec.rb

@@ -0,0 +1,7 @@
+require 'spec_helper'
+
+describe DCMClient, "version" do
+  it "should exist" do
+    DCMClient::VERSION.should be_an_instance_of(String)
+  end
+end

data/spec/error_spec.rb

@@ -0,0 +1,34 @@
+require 'spec_helper'
+
+Struct.new("TestResponseError", :message, :backtrace, :response)
+
+describe DCMClient::Error do
+  let(:exception) { e = Exception.new("foo"); e.set_backtrace(['/Users/jim/workspace/my_project/ruby_file.rb']); e }
+  let(:response_exception) { Struct::TestResponseError.new("Hi", ['1'], {:status => 422}) }
+
+  context 'wrapping an exception' do
+    before { @error = DCMClient::Error.new(exception) }
+    specify { @error.backtrace.should eq(exception.backtrace) }
+    specify { @error.message.should eq(exception.message) }
+    specify { @error.response.should be(nil) }
+  end
+
+  context 'wrapping a client exception' do
+    before { @error = DCMClient::Error.new(response_exception) }
+    specify { @error.backtrace.should eq(response_exception.backtrace) }
+    specify { @error.message.should eq(response_exception.message) }
+    specify { @error.response.should be_a(OpenStruct) }
+    specify { @error.response.status.should eq(422) }
+
+  end
+
+  context "a regular old exception" do
+    before { @error = DCMClient::Error.new("foo") }
+    specify { @error.message.should eq("foo") }
+  end
+
+  context '#response=' do
+    before { @error = DCMClient::Error.new("foo", :bar) }
+    specify { @error.response.should eq(:bar) }
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,20 @@
+$: << File.expand_path("../lib", __FILE__)
+require 'dcm_client'
+
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: dcm_client
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- GovDelivery
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-09-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A reference implementation, written in Ruby, to interact with GovDelivery's
+  DCM API.
+email:
+- support@govdelivery.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- Rakefile
+- dcm_client.gemspec
+- lib/dcm_client.rb
+- lib/dcm_client/client.rb
+- lib/dcm_client/connection.rb
+- lib/dcm_client/error.rb
+- lib/dcm_client/version.rb
+- spec/client_spec.rb
+- spec/connection_spec.rb
+- spec/dcm_client_spec.rb
+- spec/error_spec.rb
+- spec/spec_helper.rb
+homepage: http://govdelivery.com
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: A ruby client to interact with the GovDelivery DCM REST API.
+test_files:
+- spec/client_spec.rb
+- spec/connection_spec.rb
+- spec/dcm_client_spec.rb
+- spec/error_spec.rb
+- spec/spec_helper.rb