livechat_client 0.0.1

data/lib/livechat.rb

@@ -0,0 +1,23 @@
+
+require 'net/http'
+require 'net/https'
+require 'multi_json'
+require 'cgi'
+require 'openssl'
+
+
+require "livechat/version"
+require 'livechat/util'
+require 'livechat/rest/errors'
+require 'livechat/rest/utils'
+require 'livechat/rest/list_resource'
+require 'livechat/rest/instance_resource'
+require 'livechat/rest/agents'
+require 'livechat/rest/canned_responses'
+require 'livechat/rest/chats'
+require 'livechat/rest/goals'
+require 'livechat/rest/groups'
+require 'livechat/rest/reports'
+require 'livechat/rest/status'
+require 'livechat/rest/visitors'
+require 'livechat/rest/client'

data/lib/livechat/rest/agents.rb

@@ -0,0 +1,19 @@
+module LiveChat
+  module REST
+    class Agents < ListResource
+      def initialize(path, client)
+        super
+        #hard-coded keys since agents are special
+        @instance_id_key = 'login'
+      end
+    end
+
+    class Agent < InstanceResource
+      def reset_api_key
+        raise "Can't execute without a REST Client" unless @client
+        set_up_properties_from(@client.put("#{@path}/reset_api_key", {}))
+        self
+      end
+    end
+  end
+end

data/lib/livechat/rest/canned_responses.rb

@@ -0,0 +1,9 @@
+module LiveChat
+  module REST
+    class CannedResponses < ListResource
+    end
+
+    class CannedResponse < InstanceResource
+    end
+  end
+end

data/lib/livechat/rest/chats.rb

@@ -0,0 +1,18 @@
+module LiveChat
+  module REST
+    class Chats < ListResource
+      def initialize(path, client)
+        super
+        #chats is different than the other resources
+        @list_key = 'chats'
+      end
+    end
+
+    class Chat < InstanceResource
+      def send_transcript(*args)
+        @client.post "#{@path}/send_transcript", Hash[*args]
+        self
+      end
+    end
+  end
+end

data/lib/livechat/rest/client.rb

@@ -0,0 +1,142 @@
+module LiveChat
+  module REST
+    class Client
+      include LiveChat::Util
+      include LiveChat::REST::Utils
+
+      API_VERSION = '2'
+
+      HTTP_HEADERS = {
+        'Accept' => 'application/json',
+        'Accept-Charset' => 'utf-8',
+        'User-Agent' => "livechat-ruby/#{LiveChat::VERSION}",
+        'X-API-Version' => API_VERSION
+      }
+
+      DEFAULTS = {
+        :host => 'api.livechatinc.com',
+        :port => 443,
+        :use_ssl => true,
+        :ssl_verify_peer => true,
+        :ssl_ca_file => File.dirname(__FILE__) + '/../../../conf/cacert.pem',
+        :timeout => 30,
+        :proxy_addr => nil,
+        :proxy_port => nil,
+        :proxy_user => nil,
+        :proxy_pass => nil,
+        :retry_limit => 1,
+      }
+
+      attr_reader :login, :last_request, :last_response
+
+      %w(agents canned_responses chats goals groups reports status visitors).each do |r|
+        define_method(r.to_sym) do |*args|
+          klass = LiveChat::REST.const_get restify(r.capitalize)
+          n = klass.new("/#{r}", self)
+          if args.length > 0
+            n.get(args[0])
+          else 
+            n
+          end
+        end
+      end
+
+      ##
+      # Instantiate a new HTTP client to talk to LiveChat. The parameters
+      # +login+ and +api_key+ are required and used to generate the
+      # HTTP basic auth header in each request.
+      #
+      def initialize(options={})        
+        yield options if block_given?
+        @config = DEFAULTS.merge! options
+        @login = @config[:login].strip
+        @api_key = @config[:api_key].strip
+        raise ArgumentError, "Login and API key are required!" unless @login and @api_key
+        set_up_connection
+      end
+
+      def inspect # :nodoc:
+        "<LiveChat::REST::Client @login=#{@login}>"
+      end
+
+      ##
+      # Define #get, #put, #post and #delete helper methods for sending HTTP
+      # requests to LiveChat. You shouldn't need to use these methods directly,
+      # but they can be useful for debugging. Each method returns a hash
+      # obtained from parsing the JSON object in the response body.
+      [:get, :put, :post, :delete].each do |method|
+        method_class = Net::HTTP.const_get method.to_s.capitalize
+        define_method method do |path, *args|
+          params ||= {}
+          params = args[0] if args[0]
+          unless args[1] # build the full path unless already given
+            path = "#{path}"
+            if method == :get
+              path << "?#{url_encode(params)}" if method == :get && !params.empty?
+            end
+          end
+          request = method_class.new path, HTTP_HEADERS
+          request.basic_auth @login, @api_key
+          request.form_data = params if [:post, :put].include? method
+          connect_and_send request
+        end
+      end
+
+      private
+
+      ##
+      # Set up and cache a Net::HTTP object to use when making requests. This is
+      # a private method documented for completeness.
+      def set_up_connection # :doc:
+        connection_class = Net::HTTP::Proxy @config[:proxy_addr],
+          @config[:proxy_port], @config[:proxy_user], @config[:proxy_pass]
+        @connection = connection_class.new @config[:host], @config[:port]
+        set_up_ssl
+        @connection.open_timeout = @config[:timeout]
+        @connection.read_timeout = @config[:timeout]
+      end
+ 
+      ##
+      # Set up the ssl properties of the <tt>@connection</tt> Net::HTTP object.
+      # This is a private method documented for completeness.
+      def set_up_ssl # :doc:
+        @connection.use_ssl = @config[:use_ssl]
+        if @config[:ssl_verify_peer]
+          @connection.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          @connection.ca_file = @config[:ssl_ca_file]
+        else
+          @connection.verify_mode = OpenSSL::SSL::VERIFY_NONE
+        end
+      end
+
+
+      ##
+      # Send an HTTP request using the cached <tt>@connection</tt> object and
+      # return the JSON response body parsed into a hash. Also save the raw
+      # Net::HTTP::Request and Net::HTTP::Response objects as
+      # <tt>@last_request</tt> and <tt>@last_response</tt> to allow for
+      # inspection later.
+      def connect_and_send(request) # :doc:
+        @last_request = request
+        retries_left = @config[:retry_limit]
+        begin
+          response = @connection.request request
+          @last_response = response
+          if response.kind_of? Net::HTTPServerError
+            raise LiveChat::REST::ServerError
+          end
+        rescue Exception
+          raise if request.class == Net::HTTP::Post
+          if retries_left > 0 then retries_left -= 1; retry else raise end
+        end
+        if response.body and !response.body.empty?
+          object = MultiJson.load response.body
+        end
+        if response.kind_of? Net::HTTPClientError
+          raise LiveChat::REST::RequestError.new "#{object['message']}: #{response.body}", object['code']
+        end
+        object
+      end
+    end
+  end
+end

data/lib/livechat/rest/errors.rb

@@ -0,0 +1,14 @@
+module LiveChat
+  module REST
+    class ServerError < StandardError; end
+
+    class RequestError < StandardError
+      attr_reader :code
+
+      def initialize(message, code=nil)
+        super message
+        @code = code
+      end
+    end
+  end
+end

data/lib/livechat/rest/goals.rb

@@ -0,0 +1,14 @@
+module LiveChat
+  module REST
+    class Goals < ListResource
+    end
+
+    class Goal < InstanceResource
+      def mark_as_successful(*args)
+        raise "Can't execute without a REST Client" unless @client
+        @client.post "#{@path}/mark_as_successful", Hash[*args]
+        self
+      end
+    end
+  end
+end

data/lib/livechat/rest/groups.rb

@@ -0,0 +1,9 @@
+module LiveChat
+  module REST
+    class Groups < ListResource
+    end
+
+    class Group < InstanceResource
+    end
+  end
+end

data/lib/livechat/rest/instance_resource.rb

@@ -0,0 +1,115 @@
+#This file is based on code from https://github.com/twilio/twilio-ruby
+#
+#Copyright (c) 2010 Andrew Benton.
+#
+#  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.
+  
+
+module LiveChat
+  module REST
+    ##
+    # A class to wrap an instance resource (like a call or application) within
+    # the LiveChat API. 
+    class InstanceResource
+      include Utils
+
+      ##
+      # Instantiate a new instance resource object. You must pass the +path+ of
+      # the instance (e.g. /chats/MH022RD0K5) as well as a
+      # +client+ object that responds to #get #post and #delete. This client
+      # is meant to be an instance of LiveChat::REST::Client but could just as
+      # well be a mock object if you want to test the interface. The optional
+      # +params+ hash will be converted into attributes on the instantiated
+      # object.
+      def initialize(path, client, params = {})
+        @path, @client = path, client
+        set_up_properties_from params
+      end
+
+      def inspect # :nodoc:
+        "<#{self.class} @path=#{@path}>"
+      end
+
+      ##
+      # Update the properties of this instance resource using the key/value
+      # pairs in +params+. This makes an HTTP POST request to <tt>@path</tt>
+      # to handle the update. 
+      #
+      # After returning, the object will contain the most recent state of the
+      # instance resource, including the newly updated properties.
+      def update(params = {})
+        raise "Can't update a resource without a REST Client" unless @client
+        yield params if block_given?
+        set_up_properties_from(@client.put(@path, params))
+        self
+      end
+
+      ##
+      # Refresh the attributes of this instance resource object by fetching it
+      # from LiveChat. Calling this makes an HTTP GET request to <tt>@path</tt>.
+      def refresh
+        raise "Can't refresh a resource without a REST Client" unless @client
+        @updated = false
+        set_up_properties_from(@client.get(@path))
+        self
+      end
+
+      ##
+      # Delete an instance resource from LiveChat. This operation isn't always
+      # supported. For instance, you can't delete an SMS. Calling this method
+      # makes an HTTP DELETE request to <tt>@path</tt>.
+      def delete
+        raise "Can't delete a resource without a REST Client" unless @client
+        @client.delete @path
+      end
+
+      ##
+      # Lazily load attributes of the instance resource by waiting to fetch it
+      # until an attempt is made to access an unknown attribute.
+      def method_missing(method, *args)
+        super if @updated
+        set_up_properties_from(@client.get(@path))
+        self.send method, *args
+      end
+
+      protected
+
+      def set_up_properties_from(hash)
+        eigenclass = class << self; self; end
+        hash.each do |p,v|
+          property = unrestify p
+          eigenclass.send :define_method, property.to_sym, &lambda {v}
+        end
+        @updated = !hash.keys.empty?
+      end
+
+      def resource(*resources)
+        resources.each do |r|
+          resource = restify r
+          relative_path = resource
+          path = "#{@path}/#{relative_path}"
+          resource_class = LiveChat::REST.const_get resource
+          instance_variable_set("@#{r}", resource_class.new(path, @client))
+        end
+        self.class.instance_eval {attr_reader *resources}
+      end
+
+    end
+  end
+end

data/lib/livechat/rest/list_resource.rb

@@ -0,0 +1,115 @@
+#This file is based on code from https://github.com/twilio/twilio-ruby
+#
+#Copyright (c) 2010 Andrew Benton.
+#
+#  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.
+
+module LiveChat
+  module REST
+    class ListResource
+      include Utils
+
+      def initialize(path, client)
+        @path, @client = path, client
+        resource_name = self.class.name.split('::')[-1]
+        @instance_class = LiveChat::REST.const_get resource_name.chop
+        @instance_id_key = 'id'
+      end
+
+      def inspect # :nodoc:
+        "<#{self.class} @path=#{@path}>"
+      end
+
+      ##
+      # Grab a list of this kind of resource and return it as an array. The
+      # array includes a special attribute named +total+ which will return the
+      # total number of items in the list on LiveChat's server. This may differ
+      # from the +size+ and +length+ attributes of the returned array since
+      # by default LiveChat will only return 50 resources, and the maximum number
+      # of resources you can request is 1000.
+      #
+      # The optional +params+ hash allows you to filter the list returned. The
+      # filters for each list resource type are defined by LiveChat.
+      def list(params={}, full_path=false)
+        raise "Can't get a resource list without a REST Client" unless @client
+        response = @client.get @path, params, full_path
+        resources = @list_key ? response[@list_key]: response
+        path = full_path ? @path.split('.')[0] : @path
+        resource_list = resources.map do |resource|
+          @instance_class.new "#{path}/#{resource[@instance_id_key]}", @client,
+            resource
+        end
+        # set the +total+ and +next_page+ properties on the array
+        #client, list_class = @client, self.class
+        #resource_list.instance_eval do
+          #eigenclass = class << self; self; end
+          #eigenclass.send :define_method, :total, &lambda {response['total']}
+          #eigenclass.send :define_method, :next_page, &lambda {
+          #  if response['next_page_uri']
+          #    list_class.new(response['next_page_uri'], client).list({}, true)
+          #  else
+          #    []
+          #  end
+          #}
+        #end
+        resource_list
+      end
+
+      ##
+      # Ask LiveChat for the total number of items in the list.
+      # Calling this method makes an HTTP GET request to <tt>@path</tt> with a
+      # page size parameter of 1 to minimize data over the wire while still
+      # obtaining the total. Don't use this if you are planning to
+      # call #list anyway, since the array returned from #list will have a
+      # +total+ attribute as well.
+      #def total
+      #  raise "Can't get a resource total without a REST Client" unless @client
+      #  @client.get(@path, :page_size => 1)['total']
+      #end
+
+      ##
+      # Return an empty instance resource object with the proper path. Note that
+      # this will never raise a LiveChat::REST::RequestError on 404 since no HTTP
+      # request is made. The HTTP request is made when attempting to access an
+      # attribute of the returned instance resource object, such as
+      # its #date_created or #voice_url attributes.
+      def get(id)
+        @instance_class.new "#{@path}/#{id}", @client
+      end
+      alias :find :get # for the ActiveRecord lovers
+
+      ##
+      # Return a newly created resource. Some +params+ may be required. Consult
+      # the LiveChat REST API documentation related to the kind of resource you
+      # are attempting to create for details. Calling this method makes an HTTP
+      # POST request to <tt>@path</tt> with the given params
+      def create(params={})
+        raise "Can't create a resource without a REST Client" unless @client
+        yield params if block_given?
+        response = @client.post @path, params
+        @instance_class.new "#{@path}/#{response[@instance_id_key]}", @client, response
+      end
+
+      def each
+        list.each { |result| yield result }
+      end
+
+    end
+  end
+end