client_success 0.1.2

data/client_success.gemspec

@@ -0,0 +1,44 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "client_success/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "client_success"
+  spec.version       = ClientSuccess::VERSION
+  spec.authors       = ["Practice Ignition"]
+  spec.email         = ["dev@practiceignition.com"]
+
+  spec.summary       = "An unofficial Ruby wrapper for Client Success's REST API"
+  spec.homepage      = "https://github.com/ignitionapp/"
+
+  # 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 { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency("bundler", "~> 2.0")
+  spec.add_development_dependency("rake", ">= 12.3.3")
+  spec.add_development_dependency("rspec", "~> 3.0")
+
+  spec.add_development_dependency("vcr")
+  spec.add_development_dependency("faker")
+
+  spec.add_development_dependency("rubocop", "0.77.0")
+  spec.add_development_dependency("rubocop-rspec")
+
+  spec.add_runtime_dependency("faraday")
+  spec.add_runtime_dependency("faraday_middleware")
+
+  # TODO: don't force the use of typhoeus
+  spec.add_runtime_dependency("typhoeus")
+
+  spec.add_runtime_dependency("dry-types", "0.11.0")
+  spec.add_runtime_dependency("hashie")
+
+  # TODO: remove activesupport as a dependency
+  spec.add_runtime_dependency("activesupport", "~> 5.2")
+end

data/lib/client_success/access_token.rb

@@ -0,0 +1,25 @@
+require_relative "connection"
+require_relative "domain_model/access_token"
+
+module ClientSuccess
+  module AccessToken
+    extend self
+
+    class Error < StandardError; end
+    class InvalidCredentials < Error; end
+
+    def create(username:, password:,
+               connection: ClientSuccess::Connection.new)
+      response = connection.post("/v1/auth",
+        username: username,
+        password: password)
+
+      payload = response.body
+
+      DomainModel::AccessToken.new(
+        payload.deep_transform_keys(&:underscore))
+    rescue Connection::Unauthorised
+      raise InvalidCredentials, "invalid username or password"
+    end
+  end
+end

data/lib/client_success/client.rb

@@ -0,0 +1,115 @@
+require_relative "connection"
+require_relative "domain_model/client"
+require_relative "schema/client/create"
+require_relative "schema/client/update"
+
+module ClientSuccess
+  module Client
+    extend self
+
+    class Error < StandardError; end
+    class NotFound < Error; end
+
+    def list_all(assigned_csm_id: nil, active_only: true,
+             connection:)
+      params = {
+        "assignedCsmId" => assigned_csm_id,
+        "activeOnly" => active_only
+      }
+
+      response = connection.get(
+        "/v1/clients?#{params.compact.to_query}")
+
+      response.body.map do |payload|
+        DomainModel::Client.new(
+          payload.deep_transform_keys(&:underscore))
+      end
+    end
+
+    def get_details(client_id:, connection:)
+      response = connection.get(
+        "/v1/clients/#{client_id}")
+
+      payload = response.body
+
+      DomainModel::Client.new(
+        payload.deep_transform_keys(&:underscore))
+    rescue Connection::NotFound
+      raise NotFound, "client with id '#{client_id}' not found"
+    end
+
+    def get_details_by_external_id(external_id:, connection:)
+      params = {
+        "externalId" => external_id
+      }
+
+      response = connection.get(
+        "/v1/clients?#{params.compact.to_query}")
+
+      payload = response.body
+
+      DomainModel::Client.new(
+        payload.deep_transform_keys(&:underscore))
+    rescue Connection::NotFound
+      raise NotFound, "client with external id '#{external_id}' not found"
+    end
+
+    def create(attributes:, connection:)
+      body = Schema::Client::Create[attributes]
+        .transform_keys { |k| k.to_s.camelize(:lower) }
+        .to_json
+
+      response = connection.post(
+        "/v1/clients", body)
+
+      payload = response.body
+
+      # TODO: find a better way to deal with api weirdness here
+      payload["customFieldValues"].compact!
+
+      DomainModel::Client.new(
+        payload.deep_transform_keys(&:underscore))
+    end
+
+    # NOTE: according to the api documentation, this is _not_ a PATCH operation,
+    #       i.e. any fields not supplied will be set to null - so make sure you
+    #       supply everything :)
+    def update(client_id:, attributes:, connection:)
+      body = attributes
+        .deep_transform_keys { |k| k.to_s.camelize(:lower) }
+        .to_json
+
+      response = connection.put(
+        "/v1/clients/#{client_id}", body)
+
+      payload = response.body
+
+      # TODO: find a better way to deal with api weirdness here
+      payload["customFieldValues"].compact!
+
+      DomainModel::Client.new(
+        payload.deep_transform_keys(&:underscore))
+    end
+
+    def update_custom_field(client_id:, custom_field_name:, value:, connection:)
+      body = {
+        custom_field_name => value.to_s
+      }
+
+      begin
+        connection.patch(
+          "/v1/customfield/value/client/#{client_id}", body)
+      rescue Connection::ParsingError => error
+        # NOTE: request submitted to resolve invalid JSON response from client
+        #       success for this endpoint
+        raise error unless error.message =~ /Update successful/
+      end
+    end
+
+    def delete(client_id:, connection:)
+      # TODO: handle response
+      connection.delete(
+        "/v1/clients/#{client_id}")
+    end
+  end
+end

data/lib/client_success/client_type.rb

@@ -0,0 +1,18 @@
+require_relative "connection"
+require_relative "domain_model/client_type"
+
+module ClientSuccess
+  module ClientType
+    extend self
+
+    def list_all(connection:)
+      response = connection.get(
+        "/v1/client-segments")
+
+      response.body.map do |payload|
+        DomainModel::ClientType.new(
+          payload.deep_transform_keys(&:underscore))
+      end
+    end
+  end
+end

data/lib/client_success/connection.rb

@@ -0,0 +1,99 @@
+require "faraday"
+require "faraday_middleware"
+
+module ClientSuccess
+  class Connection
+    class Error < StandardError; end
+
+    class BadRequest < Error; end
+    class Unauthorised < Error; end
+    class NotFound < Error; end
+
+    class ParsingError < Error; end
+
+    class << self
+      def authorised(access_token)
+        new.tap { |conn| conn.access_token = access_token }
+      end
+    end
+
+    def logger
+      # TODO: something better than this
+      Logger.new(STDOUT).tap do |l|
+        l.level = Logger::WARN
+      end
+    end
+
+    def access_token
+      headers["Authorization"]
+    end
+
+    def access_token=(access_token)
+      headers["Authorization"] = access_token
+    end
+
+    def get(path, headers = {}, &block)
+      request { adapter.get(path, headers, &block) }
+    end
+
+    def head(path, headers = {}, &block)
+      raise NotImplementedError
+    end
+
+    def post(path, body = nil, headers = {}, &block)
+      request { adapter.post(path, body, headers, &block) }
+    end
+
+    def put(path, body = nil, headers = {}, &block)
+      request { adapter.put(path, body, headers, &block) }
+    end
+
+    def patch(path, body = nil, headers = {}, &block)
+      request { adapter.patch(path, body, headers, &block) }
+    end
+
+    def delete(path, headers = {}, &block)
+      request { adapter.delete(path, headers, &block) }
+    end
+
+    def options(path, headers = {}, &block)
+      raise NotImplementedError
+    end
+
+    private
+
+    def headers
+      adapter.headers
+    end
+
+    def adapter
+      @adapter ||= Faraday.new(url: "https://api.clientsuccess.com") do |faraday|
+        faraday.request(:json)
+        faraday.response(:json, content_type: /\bjson$/)
+        faraday.response(:logger, logger)
+        faraday.use(Faraday::Response::RaiseError)
+        faraday.adapter(Faraday.default_adapter)
+      end
+    end
+
+    def request
+      yield
+    rescue Faraday::ParsingError => error
+      raise ParsingError, error
+    rescue Faraday::ClientError => error
+      case error.response[:status]
+      when 400
+        # TODO: parse out userMessage from the response here
+        raise BadRequest, error
+      when 401
+        raise Unauthorised, error
+      when 404
+        raise NotFound, error
+      else
+        raise Error, error
+      end
+    rescue SignalException => error
+      raise Error, error
+    end
+  end
+end

data/lib/client_success/contact.rb

@@ -0,0 +1,104 @@
+require_relative "domain_model/contact"
+require_relative "schema/contact/create"
+require_relative "schema/contact/update"
+
+module ClientSuccess
+  module Contact
+    extend self
+
+    class Error < StandardError; end
+    class NotFound < Error; end
+
+    def list_all(client_id:, connection:)
+      response = connection.get(
+        "/v1/clients/#{client_id}/contacts")
+
+      response.body.map do |payload|
+        DomainModel::Contact.new(
+          payload.deep_transform_keys(&:underscore))
+      end
+    end
+
+    def get_summary(client_id:, contact_id:, connection:)
+      response = connection.get(
+        "/v1/clients/#{client_id}/contacts/#{contact_id}")
+
+      payload = response.body
+
+      DomainModel::Contact.new(
+        payload.deep_transform_keys(&:underscore))
+    end
+
+    def get_details(client_id:, contact_id:, connection:)
+      response = connection.get(
+        "/v1/clients/#{client_id}/contacts/#{contact_id}/details")
+
+      payload = response.body
+
+      DomainModel::Contact.new(
+        payload.deep_transform_keys(&:underscore))
+    end
+
+    def create(client_id:, attributes:, connection:)
+      body = Schema::Contact::Create[attributes]
+        .transform_keys { |k| k.to_s.camelize(:lower) }
+        .to_json
+
+      response = connection.post(
+        "/v1/clients/#{client_id}/contacts", body)
+
+      payload = response.body
+
+      DomainModel::Contact.new(
+        payload.deep_transform_keys(&:underscore))
+    end
+
+    def update(id:, client_id:, attributes:, connection:)
+      body = Schema::Contact::Update[attributes]
+        .transform_keys { |k| k.to_s.camelize(:lower) }
+        .to_json
+
+      response = connection.put("/v1/clients/#{client_id}/contacts/#{id}/details", body)
+
+      payload = response.body
+
+      DomainModel::Contact.new(
+        payload.deep_transform_keys(&:underscore))
+    end
+
+    def delete(id:, client_id:, connection:)
+      connection.delete("/v1/clients/#{client_id}/contacts/#{id}")
+    end
+
+    def search_by_email(email:, connection:)
+      search(term: email, connection: connection)
+        .reject { |contact| contact["email"].nil? }
+        .select { |contact| contact["email"].downcase == email.downcase }
+    end
+
+    def get_details_by_client_external_id_and_email(client_external_id:, email:, connection:)
+      params = {
+        "clientExternalId" => client_external_id,
+        "email" => email
+      }
+
+      response = connection.get(
+        "/v1/contacts?#{params.compact.to_query}")
+
+      # for some reason the ClientSuccess API does not return a 404
+      # but instead a body containing the string "null" if the contact is not found
+      # this is probably a security restriction on their end, but we will instead raise an error
+
+      if response.body.blank?
+        raise NotFound, "contact with email '#{email}' not found on client '#{client_external_id}'"
+      else
+        payload = response.body
+        DomainModel::Contact.new(payload.deep_transform_keys(&:underscore))
+      end
+    end
+
+    def search(term:, connection:)
+      connection.get("/v1/contacts/search?term='#{term}'").body
+    end
+  end
+end

data/lib/client_success/domain_model/access_token.rb

@@ -0,0 +1,11 @@
+module ClientSuccess
+  module DomainModel
+    class AccessToken < Hashie::Dash
+      include Hashie::Extensions::IndifferentAccess
+
+      property :access_token
+      property :token_type
+      property :expires_in
+    end
+  end
+end

data/lib/client_success/domain_model/client.rb

@@ -0,0 +1,14 @@
+require_relative "custom_field_value"
+
+module ClientSuccess
+  module DomainModel
+    class Client < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+      include Hashie::Extensions::Coercion
+
+      coerce_key :custom_field_values, Array[CustomFieldValue]
+    end
+  end
+end

data/lib/client_success/domain_model/client_type.rb

@@ -0,0 +1,14 @@
+require_relative "success_cycle"
+
+module ClientSuccess
+  module DomainModel
+    class ClientType < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+      include Hashie::Extensions::Coercion
+
+      coerce_key :success_cycles, Array[SuccessCycle]
+    end
+  end
+end

data/lib/client_success/domain_model/contact.rb

@@ -0,0 +1,14 @@
+# require_relative "custom_field_value"
+
+module ClientSuccess
+  module DomainModel
+    class Contact < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+      # include Hashie::Extensions::Coercion
+
+      # coerce_key :custom_field_values, Array[CustomFieldValue]
+    end
+  end
+end

data/lib/client_success/domain_model/custom_field_value.rb

@@ -0,0 +1,9 @@
+module ClientSuccess
+  module DomainModel
+    class CustomFieldValue < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+    end
+  end
+end

data/lib/client_success/domain_model/employee.rb

@@ -0,0 +1,14 @@
+require_relative "security_role"
+
+module ClientSuccess
+  module DomainModel
+    class Employee < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+      include Hashie::Extensions::Coercion
+
+      coerce_key :security_roles, Array[SecurityRole]
+    end
+  end
+end

data/lib/client_success/domain_model/product.rb

@@ -0,0 +1,10 @@
+module ClientSuccess
+  module DomainModel
+    class Product < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+      include Hashie::Extensions::Coercion
+    end
+  end
+end

data/lib/client_success/domain_model/security_role.rb

@@ -0,0 +1,9 @@
+module ClientSuccess
+  module DomainModel
+    class SecurityRole < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+    end
+  end
+end

data/lib/client_success/domain_model/status.rb

@@ -0,0 +1,9 @@
+module ClientSuccess
+  module DomainModel
+    class Status < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+    end
+  end
+end

data/lib/client_success/domain_model/subscription.rb

@@ -0,0 +1,12 @@
+require_relative "custom_field_value"
+
+module ClientSuccess
+  module DomainModel
+    class Subscription < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+      include Hashie::Extensions::Coercion
+    end
+  end
+end

data/lib/client_success/domain_model/success_cycle.rb

@@ -0,0 +1,9 @@
+module ClientSuccess
+  module DomainModel
+    class SuccessCycle < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+    end
+  end
+end

data/lib/client_success/domain_model/to_do.rb

@@ -0,0 +1,9 @@
+module ClientSuccess
+  module DomainModel
+    class ToDo < Hash
+      include Hashie::Extensions::MergeInitializer
+      include Hashie::Extensions::IndifferentAccess
+      include Hashie::Extensions::MethodAccess
+    end
+  end
+end

data/lib/client_success/employee.rb

@@ -0,0 +1,18 @@
+require_relative "connection"
+require_relative "domain_model/employee"
+
+module ClientSuccess
+  module Employee
+    extend self
+
+    def list_all(connection:)
+      response = connection.get(
+        "/v1/employees")
+
+      response.body.map do |payload|
+        DomainModel::Employee.new(
+          payload.deep_transform_keys(&:underscore))
+      end
+    end
+  end
+end

data/lib/client_success/product.rb

@@ -0,0 +1,16 @@
+require_relative "domain_model/product"
+
+module ClientSuccess
+  module Product
+    extend self
+
+    def list_all(connection:)
+      response = connection.get("/v1/products")
+
+      response.body.map do |payload|
+        DomainModel::Product.new(
+          payload.deep_transform_keys(&:underscore))
+      end
+    end
+  end
+end

data/lib/client_success/schema/client/create.rb

@@ -0,0 +1,34 @@
+require_relative "../../types"
+
+module ClientSuccess
+  module Schema
+    module Client
+      # TODO: upgrade dry types to use latest schema functions
+      Create = Types::Hash.schema(
+        name:                           Types::Strict::String,
+        site_url:                       Types::Strict::String,
+        zip:                            Types::Strict::String,
+        status_id:                      Types::Coercible::Int,
+        inception_date:                 Types::Strict::String, # TODO
+        created_by_employee_id:         Types::Coercible::Int,
+        linkedin_url:                   Types::Strict::String,
+        managed_by_employee_id:         Types::Coercible::Int,
+        active:                         Types::Strict::Bool,
+        active_client_success_cycle_id: Types::Coercible::Int,
+        zendesk_id:                     Types::Coercible::String,
+        desk_id:                        Types::Coercible::String,
+        freshdesk_id:                   Types::Coercible::String,
+        jira_id:                        Types::Coercible::String,
+        terminated_date:                Types::Strict::String, # TODO
+        assigned_sales_rep:             Types::Coercible::Int,
+        salesforce_account_id:          Types::Coercible::String,
+        usage_id:                       Types::Coercible::String,
+        street:                         Types::Strict::String,
+        state:                          Types::Strict::String,
+        country:                        Types::Strict::String,
+        city:                           Types::Strict::String,
+        external_id:                    Types::Coercible::String
+      )
+    end
+  end
+end

data/lib/client_success/schema/client/update.rb

@@ -0,0 +1,37 @@
+require_relative "../../types"
+
+module ClientSuccess
+  module Schema
+    module Client
+      # TODO: upgrade dry types to use latest schema functions
+      Update = Types::Hash.schema(
+        external_id:                    Types::Coercible::String,
+        name:                           Types::Strict::String,
+        site_url:                       Types::Strict::String,
+        client_segment_id:              Types::Coercible::Int,
+        zip:                            Types::Strict::String,
+        modified_by_employee_id:        Types::Coercible::Int,
+        status_id:                      Types::Coercible::Int,
+        inception_date:                 Types::Strict::String, # TODO
+        created_by_employee:            Types::Coercible::Int,
+        linkedin_url:                   Types::Strict::String,
+        managed_by_employee_id:         Types::Coercible::Int,
+        active:                         Types::Strict::Bool,
+        success_score:                  Types::Strict::Int,
+        active_client_success_cycle_id: Types::Coercible::Int,
+        crm_customer_id:                Types::Coercible::String,
+        crm_customer_url:               Types::Strict::String,
+        zendesk_id:                     Types::Coercible::String,
+        desk_id:                        Types::Coercible::String,
+        freshdesk_id:                   Types::Coercible::String,
+        uservoice_id:                   Types::Coercible::String,
+        assigned_sales_rep:             Types::Strict::String,
+        custom_field_values:            Types::Strict::Array.default([]), # TODO
+        success_cycle_id:               Types::Coercible::Int,
+        salesforce_account_id:          Types::Coercible::String,
+        jira_id:                        Types::Coercible::String,
+        nps_score:                      Types::Strict::Int
+      )
+    end
+  end
+end