close 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9aa1bc5d8124785414823311b95736c9ddde2ca4c5f2746e6308443f313ace7a
-  data.tar.gz: e3eac1f1c53b1da521845eb66bd3a8ec6cd342c608cf216b2cef62e7b0cea410
+  metadata.gz: 2854258a74b425cbfcde648007a00465eebb1c42b41ea3dcb5dd8b9af558839e
+  data.tar.gz: e1032fe4a32b4927b50d1aedf0bbfb6eb85b8af6e81f20a04fa77141f77f9ace
 SHA512:
-  metadata.gz: 0a5b9a3e0ee10bced5cccad33bc838c8b156fad65c821f332f548a94d0a6eff47847a340b946b5e91b12c0503bc36c0af883347cca12aa95887ad4d62e3d3144
-  data.tar.gz: 991f361451aedaf253e9d602f3f8975deb3495202fb2f294c058b32b4ba83ecd20a9d262e7ab2d23aff1ba0d64dea314cfe9c0c05c8773beac094dfdcc218e64
+  metadata.gz: 5506272793581e06aee3d9ca3f7302f512436978aaab7e9826dc8c68cedd2d91165a24dcff21ce549af48d05151e68b83930aea5e93679c7142ef7d37c788186
+  data.tar.gz: 815914f77867cbe2152eb143ffe4ace620b297ed0a0283512d324c55ae2520564138c26043ccb2e229cae735980801e61864de7664ceccf3d704f34dcad7ff8f

data/Gemfile

@@ -12,3 +12,7 @@ gem "rspec", "~> 3.0"
 gem "rubocop", "~> 1.21"
 
 gem "faraday"
+
+gem "webmock"
+
+gem "sinatra"

data/Gemfile.lock

@@ -8,17 +8,28 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.8.1)
+      public_suffix (>= 2.0.2, < 6.0)
     ast (2.4.2)
+    crack (0.4.5)
+      rexml
     diff-lcs (1.5.0)
     faraday (2.6.0)
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)
     faraday-net_http (3.0.1)
+    hashdiff (1.0.1)
     json (2.6.2)
+    mustermann (3.0.0)
+      ruby2_keywords (~> 0.0.1)
     ostruct (0.5.5)
     parallel (1.22.1)
     parser (3.1.2.1)
       ast (~> 2.4.1)
+    public_suffix (5.0.0)
+    rack (2.2.4)
+    rack-protection (3.0.2)
+      rack
     rainbow (3.1.1)
     rake (13.0.6)
     regexp_parser (2.6.0)
@@ -50,7 +61,17 @@ GEM
       parser (>= 3.1.1.0)
     ruby-progressbar (1.11.0)
     ruby2_keywords (0.0.5)
+    sinatra (3.0.2)
+      mustermann (~> 3.0)
+      rack (~> 2.2, >= 2.2.4)
+      rack-protection (= 3.0.2)
+      tilt (~> 2.0)
+    tilt (2.0.11)
     unicode-display_width (2.3.0)
+    webmock (3.18.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
 
 PLATFORMS
   arm64-darwin-21
@@ -61,6 +82,8 @@ DEPENDENCIES
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop (~> 1.21)
+  sinatra
+  webmock
 
 BUNDLED WITH
    2.3.7

data/README.md

@@ -70,6 +70,23 @@ lead.save
 
 ## Supported Resources
 
+### Advanced Filters
+[Close API Docs](https://developer.close.com/resources/leads/)
+
+Advanced Filters are a clever way to open up search to the API, with the caveat that they are very dense and appear to be written in search DSL (Elastic, Solr, etc).
+
+I have tried to encapsulate the complexity of the DSL into a simple interface that is easy to use. This is mostly by defining queries before
+they are run and then running them with parameters when they are needed.
+
+An example of an advanced filter query:
+
+```ruby
+# Run a prebuilt query
+Close::AdvancedFilter.run('find_leads_by_email', {email: 'buster.bluth@gmail.com'})
+
+
+```
+
 ### Leads
 [Close API Docs](https://developer.close.com/resources/leads/)
 

data/lib/close/data/filters/find_lead_by_contact_email.json

@@ -0,0 +1,60 @@
+{
+  "limit": null,
+  "query": {
+    "negate": false,
+    "queries": [
+      {
+        "negate": false,
+        "object_type": "lead",
+        "type": "object_type"
+      },
+      {
+        "negate": false,
+        "queries": [
+          {
+            "negate": false,
+            "related_object_type": "contact",
+            "related_query": {
+              "negate": false,
+              "queries": [
+                {
+                  "negate": false,
+                  "related_object_type": "contact_email",
+                  "related_query": {
+                    "negate": false,
+                    "queries": [
+                      {
+                        "condition": {
+                          "mode": "full_words",
+                          "type": "text",
+                          "value": "%EMAIL%"
+                        },
+                        "field": {
+                          "field_name": "email",
+                          "object_type": "contact_email",
+                          "type": "regular_field"
+                        },
+                        "negate": false,
+                        "type": "field_condition"
+                      }
+                    ],
+                    "type": "and"
+                  },
+                  "this_object_type": "contact",
+                  "type": "has_related"
+                }
+              ],
+              "type": "and"
+            },
+            "this_object_type": "lead",
+            "type": "has_related"
+          }
+        ],
+        "type": "and"
+      }
+    ],
+    "type": "and"
+  },
+  "results_limit": null,
+  "sort": []
+}

data/lib/close/errors.rb

@@ -3,4 +3,6 @@ module Close
   class InvalidRequestError < StandardError; end
   class AuthenticationError < StandardError; end
   class APIError < StandardError; end
+  class QueryNotFoundError < StandardError; end
+  class MissingParameterError < StandardError; end
 end

data/lib/close/filter.rb

@@ -0,0 +1,99 @@
+# This class attempts to abstract away the Advanced Filter API.
+# It is very powerful and fast, but building the queries is very tedious.
+# It allows to store preset queries as JSON for common queries that
+# can be commited to the repo and validated. It also lets you
+# define queries on the fly which can then be reused across the 
+# codebase without having to copy and paste the query all the time.
+module Close
+  class Filter
+    extend APIOperations
+
+    @@queries = {}
+
+    # Executes a raw query against the Close API.
+    # @param [Hash] query The query to execute.
+    # @return [Array] An array of results.
+    def self.execute(query = {})
+      response = request(:post, 'api/v1/data/search/', query)
+      response['data']
+    end
+
+    # Executes a query by name.
+    # @param [String] name The name of the query to execute.
+    # @param [Hash] params The parameters to pass to the query.
+    # @return [Array] An array of results.
+    def self.run(name, params = {})
+      query_string = load_query_from_file(name)
+      expected_params = find_params(query_string)
+      preflight_params(params, expected_params)
+      parameterized_query = apply_params(query_string, params)
+      execute(parameterized_query)
+    end
+
+    # Loads a query from a file or from memory.
+    # @param [String] name The name of the query.
+    # @return [String] A stringified JSON query.
+    def self.load_query(name)
+      if @@queries[name.to_s]
+        @@queries[name.to_s]
+      else
+        load_query_from_file(name)
+      end
+    end
+
+    # This method is used to defined a query at run time.
+    # If a name collision occurs, the query will be overwritten.
+    # @param [String] name The name of the query.
+    # @param [Hash] query_body A hash with placeholders in keys.
+    # @return [Void]
+    def self.add_query(name, query_body)
+      @@queries[name.to_s] = query_body.to_json
+    end
+
+    # Applies the params to the query string.
+    # @param [String] query_string The stringified JSON query.
+    # @param [Hash] params The parameters to apply.
+    # @return [String] The stringified JSON query with the parameters applied.
+    def self.apply_params(query_string, params)
+      qs = query_string.dup
+      params.each do |key, value|
+        qs.gsub!(/%#{key.upcase}%/, value)
+      end
+      qs
+    end
+
+    # Check that all of the params are present in expected_params.
+    # @param [Hash] params The parameters to check.
+    # @param [Array] expected_params The expected parameters.
+    # @return [Void]
+    # @raise [Close::MissingParameterError] if a parameter is missing.
+    def self.preflight_params(params, expected_params)
+      expected_params.each do |param|
+        if !params.transform_keys(&:to_s).has_key?(param.to_s)
+          raise Close::MissingParameterError, "Missing parameter: #{param}"
+        end
+      end
+    end
+
+    # Loads a predefined query from a file.
+    # @param [String] name The name of the query.
+    # @return [String] A stringified JSON query.
+    # @raise [Close::QueryNotFoundError] if the file does not exist.
+    def self.load_query_from_file(name)
+      begin
+        file = File.read("lib/close/data/filters/#{name}.json")
+      rescue Errno::ENOENT
+        raise Close::QueryNotFoundError.new("Query #{name} not found.")
+      end
+    end
+
+    # Scans a string a returns the parameters it will expect
+    # when executed.
+    # @param [String] str The string to scan.
+    # @return [Array] An array of parameters.
+    def self.find_params(str)
+      str.scan(/%[A-Z]+(?:_[A-Z]+)*%/).map{ |x| x[1..-2].downcase }.uniq
+    end
+
+  end
+end

data/lib/close/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Close
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

data/lib/close.rb

@@ -5,6 +5,7 @@ require "faraday"
 require_relative "close/close_object"
 require_relative "close/api_operations"
 require_relative "close/api_resource"
+require_relative "close/filter"
 require_relative "close/resources"
 require_relative "close/errors"
 require_relative "close/version"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: close
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - JoyNerd LLC
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-18 00:00:00.000000000 Z
+date: 2022-10-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ostruct
@@ -54,11 +54,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- close-0.1.0.gem
 - lib/close.rb
 - lib/close/api_operations.rb
 - lib/close/api_resource.rb
 - lib/close/close_object.rb
+- lib/close/data/filters/find_lead_by_contact_email.json
 - lib/close/errors.rb
+- lib/close/filter.rb
 - lib/close/resource/contact.rb
 - lib/close/resource/custom_activity_type.rb
 - lib/close/resource/lead.rb