zendesk_sell 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65770f9447275ebe858b49fc9b0301fe368a81b76b14ae290d869988b717ab92
+  data.tar.gz: 7fc85e55b84bd9424c46244e054ba85441e44988b18cb19ea1e8ab1ce47ddb05
+SHA512:
+  metadata.gz: 5a39575e77f3cd46ba99862a3a4682a50c0b2541dcba3259e5ec8fb413db3afa2ec2ad544e8d84157801229f22207d53f749470cb68766d7ffbcc712cd8939b0
+  data.tar.gz: 3cee89cd91cb326a4a5beb4d2bf6a4295eeb56803be98d508adb64171b19d4b68ee618b4006ddb584234a9b6670dcad6a094247d9545c5d27951809bb0d2dd08

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 2.6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-02-05
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Eugeniu Tambur
+
+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.

data/README.md

@@ -0,0 +1,201 @@
+# Zendesk Sell
+
+**Zendesk Sell** is a Ruby client for the [Zendesk Sell (Sales CRM) API](https://developer.zendesk.com/api-reference/sales-crm/resources/introduction/). This gem provides a robust and modular interface to interact with Zendesk Sell’s resources—such as leads, deals, contacts, companies, tasks, and users—using Faraday for HTTP requests. It supports full CRUD operations and follows best practices for a clean and extensible codebase.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zendesk_sell'
+```
+
+Then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself via:
+
+```bash
+gem install zendesk_sell
+```
+
+## Configuration
+
+The client uses the SELL_ACCESS_TOKEN environment variable by default. You can also pass the token directly when initializing the client.
+
+**Using an Environment Variable**
+
+Set your token in your shell or Rails application configuration:
+
+```bash
+export SELL_ACCESS_TOKEN="your_actual_sell_access_token"
+```
+
+## Direct Initialization
+
+```ruby
+client = ZendeskSell::Client.new(access_token: 'your_actual_sell_access_token')
+```
+
+## Available Endpoints
+
+The `zendesk_sell` gem supports the following API endpoints:
+
+- **Leads:** Manage potential customers and track leads.
+- **Deals:** Create, update, and manage business opportunities.
+- **Contacts:** Access and manage contact information for individuals.
+- **Companies:** Organize and maintain details about companies or organizations.
+- **Tasks:** Manage tasks and activities related to your sales process.
+- **Users:** Retrieve and manage information about users in your Zendesk Sell account.
+
+## Direct Initialization
+
+Below are several examples demonstrating how to use the client with various Zendesk Sell resources.
+
+### 1. Listing Resources
+
+**List All Leads**
+
+```ruby
+client = ZendeskSell::Client.new
+leads = client.leads.list(page: 1, per_page: 20)
+puts leads
+```
+
+***List All Deals***
+
+```ruby
+deals = client.deals.list(page: 1, per_page: 20)
+puts deals
+```
+
+### 2. Retrieving a Single Resource
+
+**Retrieve a Specific Lead**
+
+```ruby
+lead_id = 123
+lead = client.leads.find(lead_id)
+puts "Lead Details: #{lead}"
+```
+
+**Retrieve a Specific Contact**
+
+```ruby
+contact_id = 456
+contact = client.contacts.find(contact_id)
+puts "Contact Details: #{contact}"
+```
+
+### 3. Creating a New Resource
+
+**Create a New Lead**
+
+```ruby
+new_lead_attributes = {
+  name: "John Doe",
+  email: "john.doe@example.com",
+  phone: "+123456789"
+}
+created_lead = client.leads.create(new_lead_attributes)
+puts "Created Lead: #{created_lead}"
+```
+
+**Create a New Deal**
+
+```ruby
+new_deal_attributes = {
+  title: "New Business Opportunity",
+  value: 5000,
+  currency: "USD"
+}
+created_deal = client.deals.create(new_deal_attributes)
+puts "Created Deal: #{created_deal}"
+```
+
+### 4. Updating a Resource
+
+**Update an Existing Lead**
+
+```ruby
+lead_id = 123
+updated_attributes = { name: "Jane Doe", phone: "+1987654321" }
+updated_lead = client.leads.update(lead_id, updated_attributes)
+puts "Updated Lead: #{updated_lead}"
+```
+
+**Update a Company**
+
+```ruby
+company_id = 789
+updated_company_attributes = { name: "Acme Corp", industry: "Technology" }
+updated_company = client.companies.update(company_id, updated_company_attributes)
+puts "Updated Company: #{updated_company}"
+```
+
+### 5. Deleting a Resource
+
+**Delete a Lead**
+
+```ruby
+lead_id = 123
+client.leads.delete(lead_id)
+```
+
+**Delete a Deal**
+
+```ruby
+deal_id = 456
+client.deals.delete(deal_id)
+```
+
+### 6. Error Handling
+
+
+```ruby
+begin
+  lead = client.leads.find(9999)  # Assuming 9999 is an invalid ID
+rescue ZendeskSell::Errors::ApiError => e
+  puts "API Error: #{e.message}"
+rescue ZendeskSell::Errors::ConnectionError => e
+  puts "Connection Error: #{e.message}"
+end
+```
+
+### 7. Search 
+
+```ruby
+results = client.leads.search(
+  {
+    "filter" => {
+      "filter" => {
+        "attribute" => { "name" => "email" },
+        "parameter" => { "eq" => "john.doe@example.com" }
+      }
+    },
+    "projection" => [
+      { "name" => "id" },
+      { "name" => "name" },
+      { "name" => "email" }
+    ]
+  }
+)
+```
+
+### 8. Testing
+
+```ruby
+bundle exec rspec
+```
+
+
+### Contributing
+
+Bug reports and pull requests are welcome on GitHub at <https://github.com/RTJ/zendesk_sell>.
+
+License
+
+This gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/lib/zendesk_sell/client.rb

@@ -0,0 +1,103 @@
+# lib/zendesk_sell/client.rb
+require 'uri'
+require 'net/http'
+require 'json'
+
+module ZendeskSell
+  class Client
+    attr_reader :access_token, :base_url, :base_url_v3
+
+    # Initializes the client.
+    # - access_token: Your Zendesk Sell access token (or use ENV['SELL_ACCESS_TOKEN']).
+    # - base_url: The API base URL (default: 'https://api.getbase.com/v2').
+    # - base_url_v3: The API base URL (default: 'https://api.getbase.com/v3').
+    def initialize(access_token: ENV.fetch('SELL_ACCESS_TOKEN'))
+      @access_token = access_token
+      @base_url = "https://api.getbase.com/v2"
+      @base_url_v3 = "https://api.getbase.com/v3"
+    end
+
+    # Performs an HTTP request using Net::HTTP.
+    # - method: Symbol (:get, :post, :put, :patch, :delete).
+    # - path: API endpoint path (e.g. '/leads').
+    # - params: Query parameters (optional).
+    # - payload: Request body payload (optional).
+    def request(method, path, params: {}, payload: nil)
+      headers = default_headers
+
+      # If the path is already an absolute URL, use it directly.
+      uri = if path =~ /\Ahttps?:\/\//
+              URI(path)
+            elsif path.include?('/v2')
+              URI("#{base_url}#{path}")
+            elsif path.include?('/v3/')
+              URI("#{base_url_v3}#{path}")
+            else
+              URI("#{base_url}#{path}")
+            end
+
+      uri.query = URI.encode_www_form(params) if params.any?
+
+      request_obj = case method.to_s.upcase
+                    when "GET"    then Net::HTTP::Get.new(uri)
+                    when "POST"   then Net::HTTP::Post.new(uri)
+                    when "PATCH"  then Net::HTTP::Patch.new(uri)
+                    when "PUT"    then Net::HTTP::Put.new(uri)
+                    when "DELETE" then Net::HTTP::Delete.new(uri)
+                    else
+                      raise "Unsupported HTTP method: #{method}"
+                    end
+
+      headers.each { |key, value| request_obj[key] = value }
+      request_obj.body = payload.to_json if payload
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      response = http.request(request_obj)
+
+      unless response.is_a?(Net::HTTPSuccess)
+        raise Errors::ApiError.new(response)
+      end
+
+      JSON.parse(response.body)
+    rescue Errors::ApiError => e
+      raise e
+    rescue StandardError => e
+      raise Errors::ConnectionError.new(e.message)
+    end
+
+    # Default headers for requests.
+    def default_headers
+      {
+        'Content-Type'  => 'application/json',
+        'Accept'        => 'application/json',
+        'Authorization' => "Bearer #{access_token}"
+      }
+    end
+
+    # Resource accessors.
+    def leads
+      @leads ||= Resources::Leads.new(self)
+    end
+
+    def deals
+      @deals ||= Resources::Deals.new(self)
+    end
+
+    def contacts
+      @contacts ||= Resources::Contacts.new(self)
+    end
+
+    def companies
+      @companies ||= Resources::Companies.new(self)
+    end
+
+    def tasks
+      @tasks ||= Resources::Tasks.new(self)
+    end
+
+    def users
+      @users ||= Resources::Users.new(self)
+    end
+  end
+end

data/lib/zendesk_sell/errors.rb

@@ -0,0 +1,16 @@
+module ZendeskSell
+  module Errors
+    class ApiError < StandardError
+      attr_reader :code, :body
+
+      def initialize(response)
+        @code = response.code
+        @body = response.body
+
+        super("API Error: #{code} - #{body}")
+      end
+    end
+
+    class ConnectionError < StandardError; end
+  end
+end

data/lib/zendesk_sell/resources/base_resource.rb

@@ -0,0 +1,82 @@
+module ZendeskSell
+  module Resources
+    class BaseResource
+      def initialize(client)
+        @client = client
+      end
+
+      # List all resources (supports optional filtering/pagination).
+      def list(params = {})
+        @client.request(:get, endpoint, params: params)
+      end
+
+      # Retrieve a single resource by its ID.
+      def find(id, params = {})
+        @client.request(:get, "#{endpoint}/#{id}", params: params)
+      end
+
+      # Create a new resource.
+      # The payload structure follows the Zendesk Sell API's expected format.
+      def create(attributes = {})
+        payload = { data: { type: resource_type, attributes: attributes } }
+        @client.request(:post, endpoint, payload: payload)
+      end
+
+      # Update an existing resource by its ID.
+      def update(id, attributes = {})
+        payload = { data: attributes }
+        @client.request(:put, "#{endpoint}/#{id}", payload: payload)
+      end
+
+      # Delete a resource by its ID.
+      def delete(id)
+        @client.request(:delete, "#{endpoint}/#{id}")
+      end
+
+      # Search for resources using the v3 search endpoint.
+      # Accepts a query hash formatted per the v3 Search API.
+      #
+      # Example query for searching a contact by email:
+      #   {
+      #     "filter": {
+      #       "filter": {
+      #         "attribute": { "name": "email" },
+      #         "parameter": { "eq": "sell@zendesk.com" }
+      #       }
+      #     },
+      #     "projection": [
+      #       { "name": "id" },
+      #       { "name": "name" },
+      #       { "name": "email" }
+      #     ]
+      #   }
+      def search(query = {}, per_page = 1)
+        payload = {
+          items: [
+            {
+              data: { query: query },
+              per_page: per_page
+            }
+          ]
+        }
+        search_url = "#{@client.base_url_v3}#{endpoint}/search"
+        # The client.search_url(endpoint) returns an absolute URL (e.g. "https://api.getbase.com/v3/contacts/search")
+        @client.request(:post, search_url, payload: payload)
+      end
+
+
+      private
+
+      # Must be implemented in subclasses (e.g., '/leads', '/deals', etc.).
+      def endpoint
+        raise NotImplementedError, "You must implement the endpoint method in the subclass"
+      end
+
+      # Must be implemented in subclasses (e.g., 'lead', 'deal', etc.).
+      def resource_type
+        raise NotImplementedError, "You must implement the resource_type method in the subclass"
+      end
+
+    end
+  end
+end

data/lib/zendesk_sell/resources/companies.rb

@@ -0,0 +1,15 @@
+module ZendeskSell
+  module Resources
+    class Companies < BaseResource
+      private
+
+      def endpoint
+        '/companies'
+      end
+
+      def resource_type
+        'company'
+      end
+    end
+  end
+end

data/lib/zendesk_sell/resources/contacts.rb

@@ -0,0 +1,15 @@
+module ZendeskSell
+  module Resources
+    class Contacts < BaseResource
+      private
+
+      def endpoint
+        '/contacts'
+      end
+
+      def resource_type
+        'contact'
+      end
+    end
+  end
+end

data/lib/zendesk_sell/resources/deals.rb

@@ -0,0 +1,15 @@
+module ZendeskSell
+  module Resources
+    class Deals < BaseResource
+      private
+
+      def endpoint
+        '/deals'
+      end
+
+      def resource_type
+        'deal'
+      end
+    end
+  end
+end

data/lib/zendesk_sell/resources/leads.rb

@@ -0,0 +1,15 @@
+module ZendeskSell
+  module Resources
+    class Leads < BaseResource
+      private
+
+      def endpoint
+        '/leads'
+      end
+
+      def resource_type
+        'lead'
+      end
+    end
+  end
+end

data/lib/zendesk_sell/resources/tasks.rb

@@ -0,0 +1,15 @@
+module ZendeskSell
+  module Resources
+    class Tasks < BaseResource
+      private
+
+      def endpoint
+        '/tasks'
+      end
+
+      def resource_type
+        'task'
+      end
+    end
+  end
+end

data/lib/zendesk_sell/resources/users.rb

@@ -0,0 +1,15 @@
+module ZendeskSell
+  module Resources
+    class Users < BaseResource
+      private
+
+      def endpoint
+        '/users'
+      end
+
+      def resource_type
+        'user'
+      end
+    end
+  end
+end

data/lib/zendesk_sell/version.rb

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

data/lib/zendesk_sell.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "zendesk_sell/version"
+require 'faraday'
+require 'json'
+
+require 'zendesk_sell/client'
+require 'zendesk_sell/errors'
+require 'zendesk_sell/resources/base_resource'
+require 'zendesk_sell/resources/leads'
+require 'zendesk_sell/resources/deals'
+require 'zendesk_sell/resources/contacts'
+require 'zendesk_sell/resources/companies'
+require 'zendesk_sell/resources/tasks'
+require 'zendesk_sell/resources/users'
+
+module ZendeskSell
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/zendesk_sell.rbs

@@ -0,0 +1,4 @@
+module ZendeskSell
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/zendesk_sell.gemspec

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "lib/zendesk_sell/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "zendesk_sell"
+  spec.version = ZendeskSell::VERSION
+  spec.authors = ["Eugeniu Tambur"]
+  spec.email = ["eugeniu.rtj@gmail.com"]
+
+  spec.summary = "A Ruby client for the Zendesk Sell (Sales CRM) API"
+  spec.description = "The zendesk_sell gem provides a robust and modular Ruby interface for interacting with the Zendesk Sell API. It supports full CRUD operations on resources such as leads, deals, contacts, companies, tasks, and users using the Faraday HTTP client."
+  spec.homepage = "https://github.com/RTJ/zendesk_sell"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/RTJ/zendesk_sell"
+  spec.metadata["changelog_uri"] = "https://github.com/RTJ/zendesk_sell/CHANGELOG.md"
+
+  # 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(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile]) ||
+        f.end_with?('.gem')
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+  
+
+  # Uncomment to register a new dependency of your gem
+  # spec.add_dependency "example-gem", "~> 1.0"
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+  
+end

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: zendesk_sell
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Eugeniu Tambur
+bindir: exe
+cert_chain: []
+date: 2025-02-18 00:00:00.000000000 Z
+dependencies: []
+description: The zendesk_sell gem provides a robust and modular Ruby interface for
+  interacting with the Zendesk Sell API. It supports full CRUD operations on resources
+  such as leads, deals, contacts, companies, tasks, and users using the Faraday HTTP
+  client.
+email:
+- eugeniu.rtj@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/zendesk_sell.rb
+- lib/zendesk_sell/client.rb
+- lib/zendesk_sell/errors.rb
+- lib/zendesk_sell/resources/base_resource.rb
+- lib/zendesk_sell/resources/companies.rb
+- lib/zendesk_sell/resources/contacts.rb
+- lib/zendesk_sell/resources/deals.rb
+- lib/zendesk_sell/resources/leads.rb
+- lib/zendesk_sell/resources/tasks.rb
+- lib/zendesk_sell/resources/users.rb
+- lib/zendesk_sell/version.rb
+- sig/zendesk_sell.rbs
+- zendesk_sell.gemspec
+homepage: https://github.com/RTJ/zendesk_sell
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/RTJ/zendesk_sell
+  source_code_uri: https://github.com/RTJ/zendesk_sell
+  changelog_uri: https://github.com/RTJ/zendesk_sell/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A Ruby client for the Zendesk Sell (Sales CRM) API
+test_files: []