pipekit 1.2.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e34407109d67d8d9635733ffba1eccc11f6c6e32
-  data.tar.gz: 33ddaa1c5efbf60e1814db4c61dfd80cd39f4bbd
+  metadata.gz: c29f137ec674dd92e5458ec82f4a637f4571da25
+  data.tar.gz: 0bca608dc9986d0549efd1a79c0dd7deb3cd8d0c
 SHA512:
-  metadata.gz: d5e5629813863251130adf800fe0502651123b5ca3f387459e603f87612e3e95d79352a9ecf290057378b15a7d12b27b82a8ab2f710eb66caf109cdc57cb57e0
-  data.tar.gz: f0b7531452f1bccbb2c9d3f50862c572451c7a976cee387de3969a7eaeb254a36f53af32eb9d1d251baca151cf4ba918f1309a3569f64e6de7ca102035cc2444
+  metadata.gz: 341d2b409dda391fdd27a25fb2c215d8956910c99f6f2402f72cc1ef9991c47c67899903bd2cb6f7084a7d16ebe416d3b63f54de11e4e8c7afe0292f5076275d
+  data.tar.gz: 5e792c6a7523980c5a3ef917a7bebfe283f2e3ba80313dddc1f43d4f361c6587b2273cb662f792312936885f8341407ba1d0a2cf8399253533484a5ba0d27028

data/README.md

@@ -1,8 +1,6 @@
 # Pipekit
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/pipekit`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Pipekit is a gem to interact with [Pipedrive](https://www.pipedrive.com) API.
 
 ## Installation
 
@@ -20,9 +18,117 @@ Or install it yourself as:
 
     $ gem install pipekit
 
+Pipekit expects a config file containing your api token and key-value mappings for custom pipedrive fields. Look at [example config](./spec/support/config.yml) to see the file structure.
+
+Configure Pipekit with your config file:
+
+    Pipekit.config_file_path = File.join("config", "pipedrive.yml")
+
+You need to do once when Pipekit is loaded, the good place for it in the Rails project is `initializers`.
+
 ## Usage
 
-TODO: Write usage instructions here
+The interface of Pipekit is organised around *repositories*. The available repositories are:
+
+- Deal
+- DealField
+- Note
+- Organization
+- Person
+- PersonField
+
+### Resource repositories
+
+Deal, Note, Organization and Person represent corresponding resources on Pipedrive. Repositories provide several methods for querying and changing these resources.
+
+Methods available for all non-field repositories are:
+
+- `all`
+- `where`
+- `find_by`
+- `create`
+- `update`
+
+#### Examples
+
+Get all deals
+
+```ruby
+deal_repo = Pipekit::Deal.new
+
+deal_repo.all
+```
+
+Get all persons matching an attribute
+
+```ruby
+person_repo = Pipekit::Person.new
+
+person_repo.where(name: "Mike")
+```
+
+Get the first deal matching an attribute
+
+```ruby
+deal_repo = Pipekit::Deal.new
+
+deal_repo.find_by(id: 123)
+```
+
+Create a person
+
+```ruby
+person_repo = Pipekit::Person.new
+
+person_repo.create({name: "John Doe", deal_id: 123})
+```
+
+Update a note
+
+```ruby
+note_repo = Pipekit::Note.new
+
+note_repo.update(123, {content: "Hey"})
+```
+
+### Field repositories
+
+Pipedrive stores custom fields as key-value pairs. E.g. when you add an "Address" field to Persons Pipderive will store it as something like "050280e9bed01e55e25532f0b6e6228c748bf994"
+
+Methods available for field repositories (PersonField, DealField) are:
+
+- `get_by_key`
+- `get_by_name`
+- `find_label`
+- `find_values`
+
+### Response object
+
+`Pipekit::Response` is a hash-like object that performs an automatic conversion if Pipedrive IDs to meaningful field names.
+
+```ruby
+# pipedrive.yml
+#
+# fields:
+#   person:
+#     Emergency Contact: 345abd
+#     T-Shirt Size: 567qwe
+#
+# field_values:
+#   person:
+#     T-Shirt Size:
+#       "1": Small
+#       "2": Medium
+#       "3": Large
+
+data = {"id" => 123, "345abd" => "+44123456789", "567qwe" => "1"}
+
+person = Pipekit::Response.new(data)
+person["Emergency Contact"]
+  #=> +44123456789
+person["T-Shirt Size"]
+  #=> "Small"
+```
 
 ## Development
 

data/lib/pipekit/deal.rb

@@ -10,7 +10,7 @@ module Pipekit
     # Finds a person by their email, then finds the first deal related to that
     # person and updates it with the params provided
     def update_by_person(email, params, person_repo: Person.new)
-      person = person_repo.find_by(email: email)
+      person = person_repo.find_exactly_by_email(email)
       deal = get_by_person_id(person[:id], person_repo: person_repo).first
       update(deal[:id], params)
     end

data/lib/pipekit/person.rb

@@ -10,8 +10,14 @@ module Pipekit
       request.get("find", term: name)
     end
 
+    def find_exactly_by_email(email)
+      get_by_email(email).select do |item|
+        item["email"] == email
+      end.first
+    end
+
     def update_by_email(email, fields)
-      person = find_by(email: email)
+      person = find_exactly_by_email(email)
       update(person["id"], fields)
     end
 

data/lib/pipekit/repository.rb

@@ -39,6 +39,7 @@ module Pipekit
     #
     # Returns a Hash or nil if none found.
     def find_by(options)
+      warn "Using `Repository#find_by` with an email may return inexact matches" if email_key?(options)
       where(options, true).first
     end
 
@@ -95,5 +96,9 @@ module Pipekit
     def resource
       self.class.to_s.split("::").last.tap { |name| name[0] = name[0].downcase }
     end
+
+    def email_key?(options)
+      options.keys.first && options.keys.first.to_s == "email"
+    end
   end
 end

data/lib/pipekit/user.rb

@@ -0,0 +1,13 @@
+module Pipekit
+  class User
+    include Repository
+
+    def get_by_email(email)
+      request.get('find', term: email, search_by_email: 1)
+    end
+
+    def get_by_name(name)
+      request.get('find', term: name)
+    end
+  end
+end

data/lib/pipekit/version.rb

@@ -1,3 +1,3 @@
 module Pipekit
-  VERSION = "1.2.0"
+  VERSION = "2.0.0"
 end

data/lib/pipekit.rb

@@ -12,6 +12,7 @@ require "pipekit/deal"
 require "pipekit/person_field"
 require "pipekit/deal_field"
 require "pipekit/note"
+require "pipekit/user"
 
 module Pipekit
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pipekit
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 2.0.0
 platform: ruby
 authors:
 - jafrog
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-11-10 00:00:00.000000000 Z
+date: 2017-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -144,6 +144,7 @@ files:
 - lib/pipekit/request.rb
 - lib/pipekit/response.rb
 - lib/pipekit/result.rb
+- lib/pipekit/user.rb
 - lib/pipekit/version.rb
 - pipekit.gemspec
 homepage: https://github.com/makersacademy/pipekit
@@ -167,7 +168,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
 summary: Pipedrive API client for Ruby.