icasework 0.1.0

data/icasework.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'lib/icasework/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'icasework'
+  spec.version       = Icasework::VERSION
+  spec.authors       = ['mySociety']
+  spec.email         = ['hello@mysociety.org']
+
+  spec.summary       = 'Ruby library for the iCasework API.'
+  spec.description   = 'iCasework is a case management software that enables ' \
+    'organisations of all sizes to do a better job of case management'
+  spec.homepage      = 'https://github.com/mysociety/icasework-ruby/'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added
+  # into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activesupport', '>= 4.0.0'
+  spec.add_dependency 'jwt', '~> 2.2.0'
+  spec.add_dependency 'nokogiri', '~> 1.0'
+  spec.add_dependency 'pdf-reader', '~> 2.4.0'
+  spec.add_dependency 'rest-client', '~> 2.1.0'
+end

data/lib/icasework/case.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/deep_merge'
+
+module Icasework
+  ##
+  # A Ruby representation of a case in iCasework
+  #
+  class Case
+    class << self
+      def where(params)
+        cases = Icasework::Resource.get_cases(params).data[:cases]
+        return [] unless cases
+
+        cases[:case].map { |data| new(case_data(data)) }
+      end
+
+      def create(params)
+        data = Icasework::Resource.create_case(params).data[:createcaseresponse]
+        return nil unless data
+
+        new(case_details: { case_id: data[:caseid] })
+      end
+
+      private
+
+      def case_data(data)
+        {
+          case_details: case_details_data(data),
+          case_status: case_status_data(data),
+          case_status_receipt: case_status_receipt_data(data),
+          attributes: data[:attributes],
+          classifications: [data[:classifications][:classification]].flatten,
+          documents: [data[:documents][:document]].flatten
+        }
+      end
+
+      def case_details_data(data)
+        { case_id: data[:case_id], case_type: data[:type],
+          case_label: data[:label] }
+      end
+
+      def case_status_receipt_data(data)
+        { method: data[:request_method], time_created: data[:request_date] }
+      end
+
+      def case_status_data(data)
+        { status: data[:status] }
+      end
+    end
+
+    def initialize(hash)
+      @hash = LazyHash.new(hash) do
+        load_additional_data!
+      end
+    end
+
+    def case_id
+      self[:case_details][:case_id]
+    end
+
+    def [](key)
+      @hash[key]
+    end
+
+    def classifications
+      @hash[:classifications].map { |c| Classification.new(c) }
+    end
+
+    def documents
+      @hash[:documents].map { |d| Document.new(d) }
+    end
+
+    def to_h
+      @hash.to_h
+    end
+
+    private
+
+    def load_additional_data!
+      return @hash if @loaded
+
+      @loaded = true
+      @hash.deep_merge!(fetch_additional_data)
+    end
+
+    def fetch_additional_data
+      @fetch_additional_data ||= begin
+        cases = Icasework::Resource.get_case_details(
+          case_id: case_id
+        ).data[:cases]
+
+        if cases
+          cases[:case]
+        else
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/icasework/classification.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Icasework
+  ##
+  # A Ruby representation of a classification in iCasework
+  #
+  class Classification
+    attr_reader :group, :title
+
+    def initialize(attributes)
+      @group = attributes[:group]
+      @title = attributes[:__content__]
+    end
+  end
+end

data/lib/icasework/document.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require 'pdf/reader'
+
+module Icasework
+  ##
+  # A Ruby representation of a document in iCasework
+  #
+  class Document
+    class << self
+      def where(params)
+        documents = Icasework::Resource.get_case_documents(params).
+                    data[:documents]
+        return [] unless documents
+
+        [documents[:document]].flatten.map do |attributes|
+          new(attributes)
+        end
+      end
+
+      def find(document_id: nil, **params)
+        documents = where(params)
+        return documents unless document_id
+
+        documents.find { |d| d.attributes[:id] == document_id }
+      end
+    end
+
+    attr_reader :attributes, :url
+
+    def initialize(attributes)
+      @attributes = attributes
+      @url = attributes[:__content__]
+    end
+
+    def pdf?
+      attributes[:type] == 'application/pdf'
+    end
+
+    def pdf_contents
+      return unless pdf?
+
+      PDF::Reader.open(pdf_file) do |reader|
+        reader.pages.map(&:text).join
+      end
+    end
+
+    private
+
+    def pdf_file
+      raw = RestClient::Request.execute(
+        method: :get,
+        url: url,
+        raw_response: true
+      )
+      raw.file
+    end
+  end
+end

data/lib/icasework/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Icasework
+  ##
+  # An API authentication error
+  #
+  AuthenticationError = Class.new(RuntimeError)
+
+  ##
+  # A request error
+  #
+  RequestError = Class.new(RuntimeError)
+
+  ##
+  # A response error
+  #
+  ResponseError = Class.new(RuntimeError)
+end

data/lib/icasework/lazy_hash.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module Icasework
+  ##
+  # A hash which will attempt to lazy load a value from given block when the key
+  # is missing.
+  #
+  class LazyHash < SimpleDelegator
+    def initialize(hash, key = nil, &block)
+      @hash = hash
+      @key = key
+      @block = block
+
+      @hash.default_proc = proc do |h, k|
+        new_hash = @block.call
+        new_hash = new_hash[@key] if @key
+        h[k] = new_hash.fetch(k)
+      end
+
+      super(@hash)
+    end
+
+    def [](key)
+      value = @hash[key]
+      case value
+      when Hash
+        LazyHash.new(value, key, &@block)
+      else
+        value
+      end
+    end
+  end
+end

data/lib/icasework/resource/curl.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Icasework
+  class Resource
+    ##
+    # Method to output a Icasework::Resource instance as a curl command:
+    #
+    module Curl
+      def to_curl
+        "curl #{curl_params}#{curl_auth}'#{url}'"
+      end
+
+      private
+
+      def curl_auth
+        auth_header = headers[:authorization]
+        "-H 'Authorization: #{auth_header}' " if auth_header
+      end
+
+      def curl_params
+        case method
+        when :get
+          return '-X GET ' if payload[:params].empty?
+
+          "-G -d '#{URI.encode_www_form(payload[:params])}' "
+        when :post
+          return '-X POST ' if payload.empty?
+
+          "-X POST -d '#{URI.encode_www_form(payload)}' "
+        end
+      end
+    end
+  end
+end

data/lib/icasework/resource/data.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Icasework
+  class Resource
+    ##
+    # Converts data returned from the iCasework API into a more "Ruby like" hash
+    #
+    module Data
+      class << self
+        def process(data)
+          case data
+          when Hash
+            convert_keys(array_keys_to_array(flat_keys_to_nested(data)))
+          when Array
+            data.map { |d| process(d) }
+          else
+            data
+          end
+        end
+
+        private
+
+        # converts: { 'foo.bar': 'baz' }
+        # into { foo: { bar: 'baz' } }
+        def flat_keys_to_nested(hash)
+          hash.each_with_object({}) do |(key, value), all|
+            key_parts = key.to_s.split('.')
+            leaf = key_parts[0...-1].inject(all) { |h, k| h[k] ||= {} }
+            leaf[key_parts.last] = process(value)
+          end
+        end
+
+        # converts: { 'n1': 'foo', 'n2': 'bar' }
+        # into: { n: ['foo', 'bar'] }
+        def array_keys_to_array(hash)
+          hash.each_with_object({}) do |(key, value), all|
+            if key.to_s =~ /^(.*)\d+$/
+              key = Regexp.last_match(1)
+              all[key] ||= []
+              all[key] << process(value)
+            else
+              all[key] = process(value)
+            end
+          end
+        end
+
+        # converts: 'FooBar'
+        # into: :foo_bar
+        def convert_keys(hash)
+          hash.each_with_object({}) do |(key, value), all|
+            converted_key = key.gsub(/([a-z\d])?([A-Z])/) do
+              first = Regexp.last_match(1)
+              second = Regexp.last_match(2)
+              "#{"#{first}_" if first}#{second.downcase}"
+            end
+
+            all[converted_key.to_sym] = process(value)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/icasework/resource/payload.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Icasework
+  class Resource
+    ##
+    # Converts payload for iCasework API endpoints into a flat/titlecase keys
+    #
+    module Payload
+      class << self
+        def process(data)
+          case data
+          when Hash
+            nested_to_flat_keys(convert_keys(data))
+          else
+            data
+          end
+        end
+
+        private
+
+        # converts { 'foo' => { 'bar' => 'baz' } }
+        # into: { 'foo.bar' => 'baz' }
+        def nested_to_flat_keys(hash, key = [])
+          return { key.join('.') => process(hash) } unless hash.is_a?(Hash)
+
+          hash.inject({}) do |h, v|
+            h.merge!(nested_to_flat_keys(v[-1], key + [v[0]]))
+          end
+        end
+
+        # converts: :foo_bar
+        # into: 'FooBar'
+        def convert_keys(hash)
+          hash.each_with_object({}) do |(key, value), all|
+            converted_key = key if valid_keys.include?(key.to_s)
+            converted_key ||= key.to_s.gsub(/(?:^|_)([a-z])/i) do
+              Regexp.last_match(1).upcase
+            end
+
+            all[converted_key.to_s] = process(value)
+          end
+        end
+
+        def valid_keys
+          %w[db fromseq toseq grant_type assertion access_token]
+        end
+      end
+    end
+  end
+end

data/lib/icasework/resource.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require 'rest_client'
+
+module Icasework
+  ##
+  # API Endpoints for configured database
+  #
+  class Resource
+    class << self
+      def token(payload = {})
+        new(:post, 'token', payload, authorised: false, format: nil)
+      end
+
+      def get_cases(payload = {})
+        new(:get, 'getcases', payload, subdomain: 'uatportal')
+      end
+
+      def get_case_attribute(payload = {})
+        new(:get, 'getcaseattribute', payload)
+      end
+
+      def get_case_details(payload = {})
+        new(:get, 'getcasedetails', payload)
+      end
+
+      def get_case_documents(payload = {})
+        new(:get, 'getcasedocuments', payload)
+      end
+
+      def create_case(payload = {})
+        new(:post, 'createcase', payload)
+      end
+    end
+
+    require 'icasework/resource/curl'
+    include Curl
+
+    attr_reader :method
+
+    def initialize(method, path, payload, **options)
+      @method = method
+      @path = path
+      @payload = payload
+      @options = options
+    end
+
+    def url
+      if Icasework.production?
+        "https://#{Icasework.account}.icasework.com/#{@path}"
+      else
+        subdomain = @options.fetch(:subdomain, 'uat')
+        "https://#{subdomain}.icasework.com/#{@path}?db=#{Icasework.account}"
+      end
+    end
+
+    def headers
+      return {} unless authorised?
+
+      headers = {}
+      headers[:authorization] = "Bearer #{Icasework::Token::Bearer.generate}"
+      headers
+    end
+
+    def payload
+      return @payload if @payload_parsed
+
+      @payload[:format] = format if format
+
+      @payload = Payload.process(@payload)
+      @payload = { params: @payload } if method == :get
+
+      @payload_parsed = true
+      @payload
+    end
+
+    def data
+      response
+    end
+
+    private
+
+    def authorised?
+      @options.fetch(:authorised, true)
+    end
+
+    def format
+      @options.fetch(:format, 'xml')
+    end
+
+    def resource
+      RestClient::Resource.new(url, headers: headers)
+    end
+
+    def response
+      resource.public_send(method, payload, &parser)
+    rescue RestClient::Exception => e
+      raise RequestError, e.message
+    end
+
+    def parser
+      lambda do |response, _request, _result|
+        Data.process(parse_format(response))
+      rescue JSON::ParserError
+        raise ResponseError, "JSON invalid (#{response.body[0...100]})"
+      rescue REXML::ParseException
+        raise ResponseError, "XML invalid (#{response.body[0...100]})"
+      end
+    end
+
+    def parse_format(response)
+      case format
+      when 'xml'
+        XMLConverter.new(response.body).to_h
+      else
+        JSON.parse(response.body)
+      end
+    end
+  end
+end

data/lib/icasework/token/bearer.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Icasework
+  module Token
+    ##
+    # Generate access token for Bearer authorisation header
+    #
+    class Bearer
+      class << self
+        def generate
+          new Icasework::Resource.token(payload).data
+        rescue RequestError, ResponseError => e
+          raise AuthenticationError, e.message
+        end
+
+        private
+
+        def payload
+          {
+            grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+            assertion: Icasework::Token::JWT.generate
+          }
+        end
+      end
+
+      def initialize(data)
+        @access_token = data.fetch(:access_token)
+        @token_type = data.fetch(:token_type)
+        @expires_in = data.fetch(:expires_in)
+      end
+
+      def to_s
+        @access_token
+      end
+    end
+  end
+end

data/lib/icasework/token/jwt.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'jwt'
+
+module Icasework
+  module Token
+    ##
+    # Generate JSON web token for OAuth API authentication
+    #
+    class JWT
+      class << self
+        def generate
+          new ::JWT.encode(payload, Icasework.secret_key, 'HS256')
+        end
+
+        private
+
+        def payload
+          {
+            iss: Icasework.api_key,
+            aud: Icasework::Resource.token.url,
+            iat: Time.now.to_i
+          }
+        end
+      end
+
+      def initialize(token)
+        @token = token
+      end
+
+      def to_s
+        @token
+      end
+
+      def ==(other)
+        @token == other
+      end
+    end
+  end
+end

data/lib/icasework/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Icasework
+  VERSION = '0.1.0'
+end

data/lib/icasework/xml_converter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/hash/conversions'
+
+module Icasework
+  ##
+  # A patched version of ActiveSupport's XML converter which includes XML tag
+  # attributes
+  #
+  # Credit: https://stackoverflow.com/a/29431089
+  #
+  class XMLConverter < ActiveSupport::XMLConverter
+    private
+
+    def become_content?(value)
+      value['type'] == 'file' ||
+        (value['__content__'] &&
+         (value.keys.size == 1 && value['__content__'].present?))
+    end
+  end
+end

data/lib/icasework.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'icasework/version'
+
+##
+# This module is the main entry point of the Gem
+#
+module Icasework
+  require 'icasework/case'
+  require 'icasework/classification'
+  require 'icasework/document'
+  require 'icasework/errors'
+  require 'icasework/lazy_hash'
+  require 'icasework/resource'
+  require 'icasework/resource/data'
+  require 'icasework/resource/payload'
+  require 'icasework/token/jwt'
+  require 'icasework/token/bearer'
+  require 'icasework/xml_converter'
+
+  ConfigurationError = Class.new(StandardError)
+
+  class << self
+    attr_writer :account, :api_key, :secret_key
+
+    def account
+      @account || raise(
+        ConfigurationError, 'Icasework.account not configured'
+      )
+    end
+
+    def api_key
+      @api_key || raise(
+        ConfigurationError, 'Icasework.api_key not configured'
+      )
+    end
+
+    def secret_key
+      @secret_key || raise(
+        ConfigurationError, 'Icasework.secret_key not configured'
+      )
+    end
+
+    def env=(env)
+      @production = (env == 'production')
+    end
+
+    def production?
+      @production || false
+    end
+  end
+end