help_scout 0.12.1 → 1.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 975c65e3a727e0ff9dde7a883b6128dc48e3c0b1367a2318c05f89cb6c941741
-  data.tar.gz: a8374deb4ffd828d2c5c025844d663684953e581e7a1c31081b7b4eb6a11e4d7
+SHA1:
+  metadata.gz: ab8a0fda60b049cfcabe64b115dd2d35df71184e
+  data.tar.gz: 1f42dc562130e722dbf52588f4b0ffe46e732b1c
 SHA512:
-  metadata.gz: 6d1a5764d2b872592ca7e81e83e6de8f73b0048e0f58c3464e8077da9a03675550ad4ce679933239ea19dc615cd7d9735949bb2ca797a191063b940150e5b5db
-  data.tar.gz: af8f594af7cbdd12bc99081141651610131a917415b5a6324a929e67299eb5982c93146082ab3c2379f48c0a4fd34aae1cb1f08010eb49799857325570abc602
+  metadata.gz: f5c6c5ab4751da5bfb99b11e788f008d43e64092a5e1a2f3221512ab657cd4fed2bcd70521c1f6357a95c047f93ef87a742f3700f7ff207a9675c6c39ed2f236
+  data.tar.gz: 593e12e794ea41ab29075c3be541f5fb5ffa9e65eb293ce37833cf6d0870c57918458a654ee88b97fd5f0417bf25411cbff9b69cd60a11815bfd5951023a8f08

data/Gemfile

@@ -2,3 +2,5 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in help_scout.gemspec
 gemspec
+
+gem 'redis'

data/help_scout.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.add_runtime_dependency "httparty", "~> 0.14"
 
-  spec.add_development_dependency "bundler", "~> 1.12"
+  spec.add_development_dependency "bundler"
   spec.add_development_dependency "rake", "~> 10.5"
   spec.add_development_dependency "rspec", "~> 3.5"
   spec.add_development_dependency "webmock", "~> 2.1"

data/lib/help_scout.rb

@@ -1,4 +1,7 @@
 require "help_scout/version"
+require "help_scout/token_storage/memory"
+require "help_scout/token_storage/redis"
+
 require "httparty"
 
 class HelpScout
@@ -10,188 +13,284 @@ class HelpScout
   class ForbiddenError < StandardError; end
   class ServiceUnavailable < StandardError; end
 
+  class InvalidDataError < StandardError; end
+
   # Status codes used by Help Scout, not all are implemented in this gem yet.
-  # http://developer.helpscout.net/help-desk-api/status-codes/
+  # https://developer.helpscout.com/mailbox-api/overview/status_codes/
   HTTP_OK = 200
   HTTP_CREATED = 201
   HTTP_NO_CONTENT = 204
   HTTP_BAD_REQUEST = 400
+  HTTP_UNAUTHORIZED = 401
   HTTP_FORBIDDEN = 403
   HTTP_NOT_FOUND = 404
   HTTP_TOO_MANY_REQUESTS = 429
   HTTP_INTERNAL_SERVER_ERROR = 500
   HTTP_SERVICE_UNAVAILABLE = 503
 
+  # https://developer.helpscout.com/mailbox-api/endpoints/conversations/list/
+  CONVERSATION_STATUSES = ["active", "closed", "open", "pending", "spam"]
+
+  # https://developer.helpscout.com/mailbox-api/overview/authentication/#client-credentials-flow
+  def generate_oauth_token
+    options = {
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: {
+        grant_type: "client_credentials",
+        client_id: @api_key,
+        client_secret: @api_secret,
+      }
+    }
+    options[:body] = options[:body].to_json
+    response = HTTParty.post("https://api.helpscout.net/v2/oauth2/token", options)
+    JSON.parse(response.body)["access_token"]
+  end
+
   attr_accessor :last_response
 
-  def initialize(api_key)
+  def initialize(api_key, api_secret, token_storage = TokenStorage::Memory.new)
     @api_key = api_key
+    @api_secret = api_secret
+    @token_storage = token_storage
   end
 
   # Public: Create conversation
   #
   # data - hash with data
+  # note: since v2 the status is now required, which had a default of "active" in v1.
   #
-  # More info: http://developer.helpscout.net/help-desk-api/conversations/create/
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/create/
   #
   # Returns conversation ID
   def create_conversation(data)
+    # required_fields = ["subject", "type", "mailboxId", "status", "customer", "threads"]
+
     post("conversations", { body: data })
 
-    # Extract ID of created conversation from the Location header
-    conversation_uri = last_response.headers["location"]
-    conversation_uri.match(/(\d+)\.json$/)[1]
+    last_response.headers["Resource-ID"]
   end
 
   # Public: Get conversation
   #
   # id - conversation ID
+  # embed_threads - boolean - This will load in subentities, currently only
+  # Threads are supported by HS
   #
-  # More info: http://developer.helpscout.net/help-desk-api/objects/conversation/
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/get/
   #
   # Returns hash from HS with conversation data
-  def get_conversation(id)
-    get("conversations/#{id}")
+  def get_conversation(id, embed_threads: false)
+    if embed_threads
+      get("conversations/#{id}?embed=threads")
+    else
+      get("conversations/#{id}")
+    end
   end
 
-  # Public: Get conversations
-  #
-  # mailbox_id - ID of mailbox (find these with get_mailboxes)
-  # page - integer of page to fetch (default: 1)
-  # modified_since - Only return conversations that have been modified since
-  #                  this UTC datetime (default: nil)
+  # Public: Update conversation
   #
-  # More info: http://developer.helpscout.net/help-desk-api/conversations/list/
+  # id - conversation id
+  # data - hash with data
   #
-  # Returns hash from HS with conversation data
-  def get_conversations(mailbox_id, page = 1, modified_since = nil)
-    options = {
-      query: {
-        page: page,
-        modifiedSince: modified_since,
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/update/
+  def update_conversation(id, data)
+    instructions = []
+
+    if data[:subject]
+      instructions << {
+        op: "replace",
+        path: "/subject",
+        value: data[:subject],
       }
-    }
+    end
+    if data[:mailboxId]
+      instructions << {
+        op: "move",
+        path: "/mailboxId",
+        value: data[:mailboxId],
+      }
+    end
+    if data[:status]
+      status = data[:status]
+      if !CONVERSATION_STATUSES.include?(status)
+        raise InvalidDataError.new("status \"#{status}\" not supported, must be one of #{CONVERSATION_STATUSES}")
+      end
 
-    get("mailboxes/#{mailbox_id}/conversations", options)
+      instructions << {
+        op: "replace",
+        path: "/status",
+        value: data[:status],
+      }
+    end
+    if data.key?(:assignTo)
+      # change owner
+      if data[:assignTo]
+        instructions << {
+          op: "replace",
+          path: "/assignTo",
+          value: data[:assignTo],
+        }
+      else
+        # un assign
+        instructions << {
+          op: "remove",
+          path: "/assignTo",
+        }
+      end
+    end
+
+    # Note: HelpScout currently does not support multiple
+    # instructions in the same request, well have to do them
+    # individually :-)
+    instructions.each do |instruction|
+      patch("conversations/#{id}", { body: instruction })
+    end
   end
 
-  # Public: Update conversation
+  # Public: Update conversation tags
   #
-  # id - conversation id
-  # data - hash with data
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/tags/update/
+  def update_conversation_tags(id, tags)
+    data = { tags: tags }
+    put("conversations/#{id}/tags", { body: data })
+  end
+
+  # Public: Update conversation custom fields
   #
-  # More info: http://developer.helpscout.net/help-desk-api/conversations/update/
-  def update_conversation(id, data)
-    put("conversations/#{id}", { body: data })
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/custom_fields/update/
+  def update_conversation_custom_fields(id, fields)
+    data = { fields: fields }
+    put("conversations/#{id}/fields", { body: data })
   end
 
   # Public: Search for conversations
   #
   # query - term to search for
   #
-  # More info: http://developer.helpscout.net/help-desk-api/search/conversations/
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/list/
   def search_conversations(query)
-    search("search/conversations", query)
+    search("conversations", query)
   end
 
   # Public: Delete conversation
   #
   # id - conversation id
   #
-  # More info: https://developer.helpscout.com/help-desk-api/conversations/delete/
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/delete/
   def delete_conversation(id)
     delete("conversations/#{id}")
   end
 
-  # Public: Get customer
-  #
-  # id - customer id
+  # Public: List all mailboxes
   #
-  # More info: http://developer.helpscout.net/help-desk-api/customers/get/
-  def get_customer(id)
-    get("customers/#{id}")
-  end
-
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/mailboxes/list/
   def get_mailboxes
     get("mailboxes")
   end
 
-  # Public: Get ratings
+  # Public: Create note thread
   #
-  # More info: http://developer.helpscout.net/help-desk-api/reports/user/ratings/
-  # 'rating' parameter required: 0 (for all ratings), 1 (Great), 2 (Okay), 3 (Not Good)
-  def reports_user_ratings(user_id, rating, start_date, end_date, options)
-    options = {
-      user: user_id,
-      rating: rating,
-      start: start_date,
-      end: end_date,
+  # imported: no outgoing e-mails or notifications will be generated
+  #
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/note/
+  def create_note(conversation_id:, text:, user: nil, imported: false)
+    data = {
+      text: text,
+      user: user,
+      imported: imported,
     }
+    post("conversations/#{conversation_id}/notes", body: data)
 
-    get("reports/user/ratings", options)
+    last_response.code == HTTP_CREATED
   end
 
-  # Public: Creates conversation thread
+  # Public: Create phone thread
   #
-  # conversion_id - conversation id
-  # thread - thread content to be created
-  # imported - When set to true no outgoing emails or notifications will be
-  #            generated
-  # reload - Set to true to get the entire conversation in the result
-  #
-  # More info: http://developer.helpscout.net/help-desk-api/conversations/create-thread/
-  #
-  # Returns true if created, false otherwise. When used with reload: true it
-  # will return the entire conversation
-  def create_thread(conversation_id:, thread:, imported: nil, reload: nil)
-    query = {}
-    { reload: reload, imported: imported }.each do |key, value|
-      query[key] = value unless value.nil?
-    end
-
-    post("conversations/#{conversation_id}", body: thread, query: query)
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/phone/
+  def create_phone(conversation_id:, text:, customer:, imported: false)
+    # Note, hs does not list user as an accepted type
+    # https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/phone/
+    data = {
+      text: text,
+      customer: {
+        id: customer
+      },
+      imported: imported,
+    }
+    post("conversations/#{conversation_id}/phones", body: data)
 
-    if reload
-      last_response.parsed_response
-    else
-      last_response.code == HTTP_CREATED
-    end
+    last_response.code == HTTP_CREATED
   end
 
-  # Public: Updates conversation thread
-  #
-  # conversion_id - conversation id
-  # thread - thread content to be updated (only the body can be updated)
-  # reload - Set to true to get the entire conversation in the result
+  # Public: Create reply thread
   #
-  # More info: http://developer.helpscout.net/help-desk-api/conversations/update-thread/
-  #
-  # Returns true if updated, false otherwise. When used with reload: true it
-  # will return the entire conversation
-  def update_thread(conversation_id:, thread:, reload: nil)
-    query = {}
-    query[:reload] = reload if reload
-    body = { body: thread[:body] }
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/reply/
+  def create_reply(conversation_id:, text:, customer:, user: nil, imported: false)
+    data = {
+      text: text,
+      user: user,
+      customer: {
+        id: customer
+      },
+      imported: imported,
+    }
+    post("conversations/#{conversation_id}/reply", body: data)
 
-    put("conversations/#{conversation_id}/threads/#{thread[:id]}", body: body, query: query)
+    last_response.code == HTTP_CREATED
+  end
 
-    if reload
-      last_response.parsed_response
-    else
-      last_response.code == HTTP_OK
-    end
+  # Public: Get customer
+  #
+  # id - customer id
+  #
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/customers/get/
+  def get_customer(id)
+    get("customers/#{id}")
   end
 
-  # Public: Update Customer
+  # Public: Update customer
+  #
+  # Note: to update address, chat handles, emails, phones, social profiles or
+  # websites, separate endpoints have to be used.
   #
   # id - customer id
   # data - hash with data
   #
-  # More info: http://developer.helpscout.net/help-desk-api/customers/update/
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/customers/update/
   def update_customer(id, data)
     put("customers/#{id}", { body: data })
   end
 
+  # Public: Create phone number
+  #
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/customers/phones/create/
+  def create_customer_phone(customer_id, data)
+    post("customers/#{customer_id}/phones", { body: data })
+  end
+
+  # Public: Delete phone number
+  #
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/customers/phones/delete/
+  def delete_customer_phone(customer_id, phone_id)
+    delete("customers/#{customer_id}/phones/#{phone_id}")
+  end
+
+  # Public: Create email
+  #
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/customers/emails/create/
+  def create_customer_email(customer_id, data)
+    post("customers/#{customer_id}/emails", { body: data })
+  end
+
+  # Public: Delete email
+  #
+  # More info: https://developer.helpscout.com/mailbox-api/endpoints/customers/emails/delete/
+  def delete_customer_email(customer_id, email_id)
+    delete("customers/#{customer_id}/emails/#{email_id}")
+  end
+
   protected
 
   def post(path, options = {})
@@ -214,43 +313,59 @@ class HelpScout
     request(:delete, path, options)
   end
 
+  def patch(path, options = {})
+    options[:body] = options[:body].to_json if options[:body]
+
+    request(:patch, path, options)
+  end
+
   def search(path, query, page_id = 1, items = [])
     options = { query: { page: page_id, query: "(#{query})" } }
 
     result = get(path, options)
-    if !result.empty?
-      next_page_id = page_id + 1
-      result["items"] += items
-      if next_page_id > result["pages"]
-        return result["items"]
-      else
-        search(path, query, next_page_id, result["items"])
-      end
+    next_page_id = page_id + 1
+
+    if result.key?("_embedded")
+      items += result["_embedded"]["conversations"]
+    end
+
+    if next_page_id > result["page"]["totalPages"]
+      return items
+    else
+      search(path, query, next_page_id, items)
     end
   end
 
   def request(method, path, options)
-    uri = URI("https://api.helpscout.net/v1/#{path}.json")
+    uri = URI("https://api.helpscout.net/v2/#{path}")
+
+    token = @token_storage.token
+    if token.nil?
+      token = generate_oauth_token
+      @token_storage.store_token(token)
+    end
 
-    # The password can be anything, it's not used, see:
-    # http://developer.helpscout.net/help-desk-api/
     options = {
-      basic_auth: {
-        username: @api_key, password: 'X'
-      },
-      headers: {}
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": "Bearer #{token}",
+      }
     }.merge(options)
 
-    if options.key?(:body)
-      options[:headers]['Content-Type'] ||= 'application/json'
-    end
-
     @last_response = HTTParty.send(method, uri, options)
+
     case last_response.code
+    when HTTP_UNAUTHORIZED
+      # Unauthorized means our token is expired. We will fetch a new one, and
+      # retry the original request
+      new_token = generate_oauth_token
+      @token_storage.store_token(new_token)
+      options.delete(:headers)
+      request(method, path, options)
     when HTTP_OK, HTTP_CREATED, HTTP_NO_CONTENT
       last_response.parsed_response
     when HTTP_BAD_REQUEST
-      raise ValidationError, last_response.parsed_response["validationErrors"]
+      raise ValidationError, JSON.parse(last_response.body)["_embedded"]["errors"]
     when HTTP_FORBIDDEN
       raise ForbiddenError
     when HTTP_NOT_FOUND
@@ -261,7 +376,7 @@ class HelpScout
     when HTTP_SERVICE_UNAVAILABLE
       raise ServiceUnavailable
     when HTTP_TOO_MANY_REQUESTS
-      retry_after = last_response.headers["Retry-After"]
+      retry_after = last_response.headers["X-RateLimit-Retry-After"]
       message = "Rate limit of 200 RPM or 12 POST/PUT/DELETE requests per 5 " +
         "seconds reached. Next request possible in #{retry_after} seconds."
       raise TooManyRequestsError, message

data/lib/help_scout/token_storage.rb

@@ -0,0 +1,4 @@
+class HelpScout
+  module TokenStorage
+  end
+end

data/lib/help_scout/token_storage/memory.rb

@@ -0,0 +1,13 @@
+class HelpScout
+  module TokenStorage
+    class Memory
+      def token
+        @token
+      end
+
+      def store_token(token)
+        @token = token
+      end
+    end
+  end
+end

data/lib/help_scout/token_storage/redis.rb

@@ -0,0 +1,19 @@
+class HelpScout
+  module TokenStorage
+    class Redis
+      IDENTIFIER = "helpscout-client-token"
+
+      def initialize(db)
+        @db = db
+      end
+
+      def token
+        @db.get(IDENTIFIER)
+      end
+
+      def store_token(new_token)
+        @db.set(IDENTIFIER, new_token)
+      end
+    end
+  end
+end

data/lib/help_scout/version.rb

@@ -1,3 +1,3 @@
 class HelpScout
-  VERSION = "0.12.1"
+  VERSION = "1.0.0.beta1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: help_scout
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 1.0.0.beta1
 platform: ruby
 authors:
 - Dennis Paagman
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-06-21 00:00:00.000000000 Z
+date: 2019-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -31,16 +31,16 @@ dependencies:
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.12'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -118,6 +118,9 @@ files:
 - bin/setup
 - help_scout.gemspec
 - lib/help_scout.rb
+- lib/help_scout/token_storage.rb
+- lib/help_scout/token_storage/memory.rb
+- lib/help_scout/token_storage/redis.rb
 - lib/help_scout/version.rb
 homepage: https://github.com/Springest/help_scout
 licenses:
@@ -134,12 +137,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.4
+rubygems_version: 2.6.14.3
 signing_key: 
 specification_version: 4
 summary: HelpScout is an API client for Help Scout