govdelivery-tms 0.8.0

data/lib/govdelivery-tms/base.rb

@@ -0,0 +1,37 @@
+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, :new_record
+
+    module ClassMethods
+      def to_param
+        tmsify(self)
+      end
+    end
+
+    module InstanceMethods
+      def initialize(client, href)
+        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
+
+end

data/lib/govdelivery-tms/client.rb

@@ -0,0 +1,97 @@
+require 'logger'
+# 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, :api_root, :logger
+
+  DEFAULTS = {:api_root => 'https://tms.govdelivery.com', :logger => nil}.freeze
+
+  # Create a new client and issue a request for the available resources for a given account.
+  #
+  # @param [String] auth_token The auth_token of your account
+  # @param [Hash] options
+  # @option options [String] :api_root The root URL of the TMS api. Defaults to localhost:3000
+  # @option options [Logger] :logger An instance of a Logger class (http transport information will be logged here) - defaults to nil
+  #
+  # @example
+  #   client = TMS::Client.new("auth_token", {
+  #                               :api_root => "https://tms.govdelivery.com",
+  #                               :logger => Logger.new(STDOUT)})
+  #   client = TMS::Client.new("auth_token", {
+  #                               api_root: "https://tms.govdelivery.com",
+  #                               logger:   false})
+  def initialize(auth_token, options = DEFAULTS)
+    @api_root = options[:api_root]
+    @logger = options.fetch(:logger, setup_logging(options[:debug]))
+    connect!(auth_token, options.except(:api_root, :logger, :debug))
+    discover!
+  end
+
+  def connect!(auth_token, options={})
+    self.connection = TMS::Connection.new({:auth_token => auth_token, :api_root => api_root, :logger => logger}.merge!(options))
+  end
+
+  def discover!
+    services = get('/').body
+    parse_links(services['_links'])
+  end
+
+  def get(href)
+    response = raw_connection.get(href)
+    case response.status
+      when 500..599
+        raise TMS::Request::Error.new(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...299
+        return response
+      else
+        raise TMS::Request::Error.new(response.status)
+    end
+  end
+
+  def raw_connection
+    connection.connection
+  end
+
+  def client
+    self
+  end
+
+  private
+
+  def setup_logging(debug)
+    logger = Logger.new(STDOUT)
+    logger.level = debug ? Logger::DEBUG : Logger::INFO
+    logger
+  end
+
+end

data/lib/govdelivery-tms/collection_resource.rb

@@ -0,0 +1,54 @@
+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 || {})
+      thing.new_record = true
+      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/govdelivery-tms/connection.rb

@@ -0,0 +1,34 @@
+class TMS::Connection
+  attr_accessor :auth_token, :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.auth_token = opts[:auth_token]
+    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.headers['X-AUTH-TOKEN'] = auth_token
+      faraday.headers[:user_agent] = "GovDelivery Ruby TMS::Client #{TMS::VERSION}"
+      faraday.response :json, :content_type => /\bjson$/
+      faraday.adapter :net_http
+    end
+  end
+
+  def dump_headers(headers)
+    headers.map { |k, v| "#{k}: #{v.inspect}" }.join("\n")
+  end
+end

data/lib/govdelivery-tms/errors.rb

@@ -0,0 +1,58 @@
+module TMS
+  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
+
+  module Errors
+    class ServerError < StandardError
+      def initialize(response)
+        super("TMS client encountered a server error: #{response.status} \n#{response.body}")
+      end
+    end
+    class NoRelation < StandardError
+      def initialize(rel=nil, obj=nil)
+        message = "no link relation "
+        message << "'#{rel}' " if rel
+        message << 'is available'
+        message << " for #{obj}" if obj
+        super(message)
+      end
+    end
+    class InvalidVerb < StandardError
+      attr_reader :record
+
+      def initialize(record_or_string)
+        if record_or_string.respond_to?(:href)
+          @record = record_or_string
+          super("Couldn't POST #{record.class} to #{record.href}: #{record.errors.map { |k, v| "#{k} #{v.join(' and ')}" }.join(', ')}")
+        else
+          super(record_or_string)
+        end
+
+      end
+    end
+    class InvalidPost < InvalidVerb
+    end
+    class InvalidPut < InvalidVerb
+    end
+    class InvalidDelete < InvalidVerb
+    end
+    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/govdelivery-tms/instance_resource.rb

@@ -0,0 +1,219 @@
+module TMS::InstanceResource
+  def self.included(base)
+    base.send(:include, TMS::Base)
+    base.extend(ClassMethods)
+    base.send(:include, InstanceMethods)
+  end
+
+  attr_accessor :response
+
+  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
+
+    ##
+    # Linkable attributes are sent on POST/PUT.
+    #
+    def linkable_attributes(*attrs)
+      @linkable_attributes ||= []
+      if attrs.any?
+        @linkable_attributes.map!(&:to_sym).concat(attrs).uniq! if attrs.any?
+      end
+      @linkable_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)
+    #
+    # @example
+    #     collection_attributes :recipients
+    #
+    def collection_attributes(*attrs)
+      @collection_attributes ||= []
+      if attrs.any?
+        @collection_attributes.map!(&:to_sym).concat(attrs).uniq!
+        @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.
+    #
+    # @example
+    #    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
+
+    ##
+    # Read-only collection attributes don't get POSTed. 
+    # Use this for collections that are represented as attributes, but cannot be modified. 
+    #
+    # @example
+    #      readonly_collection_attribute :opens
+    #
+    def readonly_collection_attribute(attr, tms_class)
+      @readonly_collection_attributes ||= []
+      @readonly_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
+    attr_reader :links
+
+    def initialize(client, href=nil, attrs=nil)
+      super(client, href)
+      @attributes = {}
+      @links = {}
+      set_attributes_from_hash(attrs) if attrs
+    end
+
+    def attributes
+      @attributes
+    end
+
+    def get
+      raise TMS::Errors::InvalidGet if self.new_record?
+      process_response(client.get(self.href), :get) && self
+    end
+    alias_method :get!, :get
+
+    def post
+      self.errors = nil
+      process_response(client.post(self), :post)
+    end
+
+    def post!
+      self.post or raise TMS::Errors::InvalidPost.new(self)
+    end
+
+    def put
+      process_response(client.put(self), :put)
+    end
+
+    def put!
+      process_response(client.put(self), :put) or raise TMS::Errors::InvalidPut.new(self)
+    end
+
+    def delete
+      process_response(client.delete(self.href), :delete)
+    end
+
+    def delete!
+      process_response(client.delete(self.href), :delete) or raise TMS::Errors::InvalidDelete.new(self)
+    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
+      self.class.linkable_attributes.each do |attr|
+        json_hash[:_links] ||= {}
+        json_hash[:_links][attr] = @links[attr]
+      end
+      json_hash
+    end
+
+    protected
+
+    def relation_class(rel)
+      self.class.custom_class_names[rel.to_sym] || super
+    end
+
+    def process_response(response, method)
+      self.response = response
+      error_class   = TMS::Errors.const_get("Invalid#{method.to_s.capitalize}")
+      case response.status
+        when 204
+          return true
+        when 200..299
+          set_attributes_from_hash(response.body) if response.body.is_a?(Hash)
+          @links = {}
+          self.new_record=false
+          return true
+        when 401
+          raise error_class.new("401 Not Authorized")
+        when 404
+          raise(error_class.new("Can't POST to #{self.href}"))
+        when 500..599
+          raise(TMS::Errors::ServerError.new(response))
+        else # 422?
+          if response.body['errors']
+            self.errors = response.body['errors']
+          end
+      end
+      return false
+    end
+
+    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