cubscout 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c14b1d696bee8bbb568d385670e7153c000372720d55612c5ea307cb7ea51531
+  data.tar.gz: a4411b99e61b6fee43267bb88c39c3649ce9872813fa09044c4a352216aa9753
+SHA512:
+  metadata.gz: cf9ab8423a1c3505d43cf8e4a6666e76427941c3125dd41db0aeaa83724953260cee8569f4a89ad7d7bab67ec61d87708a52c276611ad936ec093339c5cbeba0
+  data.tar.gz: 6487fcbec28d761890d88366196be75282a5d024bb7f809eafa6bbd7cd60f3a8d97c71ce7e4c10eb8bc6b03f84310f154ced7441345dfd91cdbaaabe3eca6b40

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+### Unreleased
+
+### 0.2.0 - 2020-05-14
+
+**Breaking changes**
+
+- Use named `ThreadItem` and `Error` instead of generic object & error [#25](https://github.com/GetSilverfin/cubscout/pull/25)
+- On association method calls, do not make a request to Helpscout by default [#24](https://github.com/GetSilverfin/cubscout/pull/24)
+- `Cubscout::Scopes.all` method returns a `Cubscout::List` object instead of an array of items [#23](https://github.com/GetSilverfin/cubscout/pull/23)
+
+**Dependencies**
+
+- Bump rack from 2.0.7 to 2.0.8 [#21](https://github.com/GetSilverfin/cubscout/pull/21)
+- Update rake requirement from ~> 10.0 to ~> 13.0 [#22](https://github.com/GetSilverfin/cubscout/pull/22)
+
+### 0.1.1 - 2019-11-14
+
+**Fixes**
+
+- use new Auth endpoint after deprecation of old one by helpscout [#16](https://github.com/GetSilverfin/cubscout/issues/16)
+
+### 0.1.0 - 2019-03-21
+
+BROKEN: DO NOT USE (Auth endpoint deprecated by Helpscout)

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at silverfin.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Silverfin NV
+
+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,202 @@
+[![Build Status](https://travis-ci.org/GetSilverfin/cubscout.svg?branch=master)](https://travis-ci.org/GetSilverfin/cubscout)
+
+# Cubscout
+
+Unofficial Ruby client for the [Helpscout API V2](https://developer.helpscout.com/mailbox-api/). 
+
+Cubscout is heavily inspired by [girlscout](https://github.com/omise/girlscout), another unofficial Ruby Client for Helpscout API V1.
+
+## Installation
+
+Add `gem 'cubscout'` to your application's Gemfile, and then run `bundle` to install.
+
+Or install it yourself as `gem install cubscout`.
+
+## Configuration
+
+To get started, you need to configure the client with your App ID and App secret. If you are using Rails, you should add the following to a new initializer file in `config/initializers/helpscout.rb`.
+
+```ruby
+require 'cubscout'
+
+Cubscout::Config.client_id = 'YOUR_APP_ID'
+Cubscout::Config.client_secret = 'YOUR_APP_SECRET'
+```
+
+Note: Your App ID and App Secret are secret credentials, and you should treat them like passwords. You can create an App in your Helpscout account, under Your Profile > My Apps.
+
+## Usage
+
+Cubscout mimics Active Record's querying pattern.
+
+### Conversations
+
+List of conversations:
+
+```ruby
+# all possible conversations available
+# WARNING: this will create a lot of HTTP requests. You probably want some filtering.
+conversations = Cubscout::Conversation.all
+
+# conversations with filters
+conversations = Cubscout::Conversation.all(tag: 'red,blue', status: 'active')
+
+# Cubscout::Conversation.all returns a Cubscout::List object. You can iterate
+# over it's Cubscout::Conversation items like this:
+conversations.each { |conversation| puts conversation.mailbox_id }
+
+# or you can also get some metadata information. For example if you only care
+# about the number of items, you can query the first page only and find out how
+# many elements exist in total:
+Cubscout::Conversation.all(page: 1, tag: 'red,blue', status: 'active').total_size
+```
+
+Check Helpscout's API documentation for [all supported filters](https://developer.helpscout.com/mailbox-api/endpoints/conversations/list/#url-parameters) and [attributes returned](https://developer.helpscout.com/mailbox-api/endpoints/conversations/list/#response).
+
+All filter keys must be passed in the same format as described in the documentation, and all values must be strings or integers. Attribute keys must be symbols:
+
+```ruby
+conversations = Cubscout::Conversation.all(page: 1,
+                                           assigned_to: 1234,
+                                           sortField: "customerName",
+                                           modifiedSince: (DateTime.now - 4).to_time.utc.iso8601,
+                                           tag: "red,blue")
+```
+
+Get one conversation by id:
+
+```ruby
+# find conversation by id:
+conversation = Cubscout::Conversation.find(12345)
+
+# Cubscout::Conversation.find returns one Cubscout::Conversation object, from
+# which attributes can be read. attributes can be read as snake case or camel case.
+puts conversation.mailbox_id
+puts conversation.mailboxId
+
+# By default, the threads are not embedded in the conversations payload. They can
+# optionally be returned with the `embed` option:
+Cubscout::Conversation.find(12345, embed: "threads")
+```
+
+Check Helpscout's API documentation for all [attributes returned](https://developer.helpscout.com/mailbox-api/endpoints/conversations/get/#response)
+
+Update a conversation:
+
+```ruby
+conversation = Cubscout::Conversation.find(12345)
+conversation.update(op: "replace", path: "/subject", value: "New conversation subject")
+
+# or
+Cubscout::Conversation.update(12345, op: "replace", path: "/subject", value: "New conversation subject")
+```
+
+Multiple combinations of `:op`, `:path` and `:value` are permitted, check Helpscout's API documentation for [all the possibilities](https://developer.helpscout.com/mailbox-api/endpoints/conversations/update/#valid-paths-and-operations).
+
+### Threads
+
+In Helpscout's lingo, threads are all the items following a conversation: notes, replies, assignment to users, etc.
+
+Get the threads for a conversation:
+
+```ruby
+# by conversation id, will make a request to Helpscout:
+threads = Cubscout::Conversation.threads(conversation_id)
+
+# from a conversation object, either by embedding threads on conversation request:
+also_threads = Cubscout::Conversation.find(id, embed: 'threads').threads
+# or making the threads request with explicit `fetch` option, will make a request
+# to Helpscout:
+another_way_to_get_threads = Cubscout::Conversation.find(id).threads(fetch: true)
+```
+
+Threads can also be embedded to the List Conversations response payload:
+
+```ruby
+# By default, the threads are not embedded in the conversations payload. They can
+# optionally be returned with the `embed` option:
+conversations = Cubscout::Conversation.all(page: 1, tag: 'red,blue', embed: 'threads')
+threads = conversations.first.threads
+```
+
+Check Helpscout's API documentation for all [attributes returned](https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/list/#response)
+
+Create a note on a conversation:
+
+```ruby
+# by conversation id:
+Cubscout::Conversation.create_note(conversation_id, attributes)
+
+# from a conversation object:
+Cubscout::Conversation.find(id).create_note(attributes)
+
+# of the attributes hash, :text is the only attribute required
+Cubscout::Conversation.create_note(12345, text: "A new note by me")
+
+# this endpoint doesn't return any body
+```
+
+Check Helpscout's API documentation for [all supported attributes](https://developer.helpscout.com/mailbox-api/endpoints/conversations/threads/note/#request-fields)
+
+## Users
+
+List of users:
+
+```ruby
+# all possible users available
+# WARNING: this will create multiple HTTP requests. You may want some filtering.
+users = Cubscout::User.all
+
+# users with filters
+users = Cubscout::User.all(mailbox: 12345)
+
+# Cubscout::User.all returns a Cubscout::List object. You can iterate over
+# it's Cubscout::User items like this:
+users.each { |user| puts user.first_name }
+
+# or you can also get some metadata information. For example if you only care
+# about the number of items, you can query the first page only and find out how
+# many elements exist in total:
+Cubscout::User.all(page: 1, mailbox: 12345).total_size
+```
+
+Check Helpscout's API documentation for [all supported filters](https://developer.helpscout.com/mailbox-api/endpoints/users/list/#url-parameters) and [attributes returned](https://developer.helpscout.com/mailbox-api/endpoints/users/list/#response).
+
+Get one user by id:
+
+```ruby
+# find user by id:
+user = Cubscout::User.find(12345)
+
+# Cubscout::User.find returns one Cubscout::User object, from
+# which attributes can be read. attributes can be read as snake case or camel case.
+puts user.firstName
+puts user.first_name
+```
+
+Check Helpscout's API documentation for all [attributes returned](https://developer.helpscout.com/mailbox-api/endpoints/users/get/#response)
+
+Get a conversation's assigned user:
+
+```ruby
+# With limited attributes returned in conversation payload. Small gotcha here:
+# - "first" attributes is renamed to "firstName"
+# - "last" attributes is renamed to "lastName"
+# to keep consistency with the attribute names returned from the /users endpoint
+user = Cubscout::Conversation.find(conversation_id).assignee
+
+# All attributes, will make a request to Helpscout:
+user = Cubscout::Conversation.find(conversation_id).assignee(fetch: true)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/GetSilverfin/cubscout. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Cubscout project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/GetSilverfin/cubscout/blob/master/CODE_OF_CONDUCT.md).

data/lib/cubscout.rb

@@ -0,0 +1,28 @@
+require "cubscout/version"
+require "cubscout/config"
+
+require "cubscout/resource"
+require "cubscout/request"
+require "cubscout/response"
+
+require "cubscout/scopes"
+require "cubscout/list"
+require "cubscout/object"
+require "cubscout/conversation"
+require "cubscout/user"
+require "cubscout/thread_item"
+
+module Cubscout
+  class Error < StandardError; end
+
+  class AuthenticationError < Error; end
+  class InternalError < Error; end
+  class InvalidFormatError < Error; end
+  class JsonParseError < Error; end
+  class MalformedRequestError < Error; end
+  class PermissionDeniedError < Error; end
+  class ResourceNotFoundError < Error; end
+  class RateLimitExceeded < Error; end
+
+  class ParameterMissing < Error; end
+end

data/lib/cubscout/config.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "oauth2"
+
+module Cubscout
+  # The Config class allows for API client configuration. Basic setup:
+  #    require 'cubscout'
+  #    Cubscout::Config.client_id = 'YOUR_APP_ID'
+  #    Cubscout::Config.client_secret = 'YOUR_APP_SECRET'
+  class Config
+    DEFAULT_API_PREFIX = 'https://api.helpscout.net/v2'
+
+    class << self
+      attr_writer :api_prefix, :client_id, :client_secret
+
+      # @return [String] Base url of Helpscout's API V2.
+      def api_prefix
+        @api_prefix ||= DEFAULT_API_PREFIX
+      end
+
+      # Resets +client_id+, +client_secret+, and +oauth_client+ to null values,
+      # +api_prefix+ to DEFAULT_API_PREFIX
+      def reset!
+        @client_id = @client_secret = nil
+        @access_token = @oauth_client = nil
+        @api_prefix = DEFAULT_API_PREFIX
+      end
+
+      # @return [String] OAuth token used in every request header:
+      #   +Authorization: Bearer #{Cubscout::Config.oauth_token}+
+      def oauth_token
+        access_token.token
+      end
+
+      private
+
+      def access_token
+        if @access_token && @access_token.expires_at > Time.now.to_i + 30
+          return @access_token
+        end
+
+        @access_token = oauth_client.client_credentials.get_token
+      end
+
+      def oauth_client
+        @oauth_client ||= begin
+          unless @client_id && @client_secret
+            raise ParameterMissing, <<~TEXT
+              You need to provide a client_id and client secret that you can get from helpscout (In Your profile -> my Apps)
+
+              Cubscout::Config.client_id = 'your-app-id-here'
+              Cubscout::Config.client_secret = 'your-app-secret-here'
+
+            TEXT
+          end
+
+          OAuth2::Client.new(@client_id, @client_secret, site: URI.join(api_prefix, '/').to_s, token_url: "#{URI::parse(api_prefix).path}/oauth2/token")
+        end
+      end
+    end
+  end
+end

data/lib/cubscout/conversation.rb

@@ -0,0 +1,114 @@
+module Cubscout
+  # the Conversation class encapsulates a helpscout conversation.
+  class Conversation < Object
+    endpoint "conversations"
+
+    class << self
+      # Get the threads of a conversation. In Helpscout lingo, threads are all
+      # the items following a conversation: notes, replies, assignment to users, etc.
+      # @param id [Integer] the conversation ID
+      # @return [Array<Object>] thread items
+      def threads(id)
+        Cubscout.connection.get("#{path}/#{id}/threads").body.dig("_embedded", "threads").map { |item| ThreadItem.new(item) }
+      end
+
+      # Create a note to a conversation.
+      # @param id [Integer] the conversation ID
+      # @param text [String] the note's text
+      # @option attributes [Integer] :user (Resource Owner) ID of the user creating the note.
+      # @option attributes [Boolean] :imported (false) The imported field enables thread to be
+      #   created for historical purposes (i.e. if moving from a different platform, you can import
+      #   your history).
+      #   When imported is set to true, no outgoing emails or notifications will be generated.
+      # @option attributes [String] :createdAt Optional creation date to be used
+      #   when importing conversations and threads.
+      #   It can only be used with imported field set to true
+      # @option attributes [Array<Hash>] :attachments Optional list of attachments to be attached to this thread
+      #     * :fileName (String) Attachment’s file name
+      #     * :mimeType (String) Attachment’s mime type
+      #     * :data (String) Base64-encoded stream of data.
+      # @return [Boolean] success status
+      # @example
+      #   Cubscout::Conversation.create_note(123, text: "This is a note")
+      #   Cubscout::Conversation.create_note(123, text: "This is a note", attachments: [{fileName: "file.txt", mimeType: "plain/text", data: "ZmlsZQ=="}])
+      def create_note(id, text:, **attributes)
+        Cubscout.connection.post("#{path}/#{id}/notes", attributes.merge(text: text).to_json).body
+      end
+
+      # Update a conversation.
+      # @param id [Integer] the conversation ID
+      # @param op [String] Patch operation to be carried out, one of +move+, +remove+, +replace+
+      # @param path [String] Path of the value to be changed, one of:
+      #   +/assignTo+, +/draft+, +/mailboxId+, +/primaryCustomer.id+, +/status+, +/subject+
+      # @option attributes [Varies] :value Value to be used in operation, refer to this documentation
+      #   for valid types: https://developer.helpscout.com/mailbox-api/endpoints/conversations/update/#valid-paths-and-operations.
+      #   In case of status update +(op: "replace", path: "/status")+, :value must be one of +active+, +closed+, +open+, +pending+, +spam+
+      def update(id, op:, path:, **attributes)
+        Cubscout.connection.patch("#{Conversation.path}/#{id}", attributes.merge(op: op, path: path).to_json).body
+      end
+    end
+
+    # Get the assignee of the conversation
+    # @param fetch [Boolean] Optional query to helpscout to fetch full user data.
+    #   By default, use limited data provided in conversation payload
+    # @return [User, nil] User assigned to the conversation. Can be nil
+    def assignee(fetch: false)
+      return nil unless self.attributes.has_key?("assignee")
+      if fetch
+        User.find(self.attributes.dig("assignee", "id"))
+      else
+        user_attributes = self.attributes.fetch("assignee").merge(
+          "firstName" => self.attributes.dig("assignee", "first"),
+          "lastName" => self.attributes.dig("assignee", "last")
+        )
+        User.new(user_attributes)
+      end
+    end
+
+    # Get the threads of the conversation. In Helpscout lingo, threads are all
+    # the items following a conversation: notes, replies, assignment to users, etc.
+    # @param fetch [Boolean] Optional query to helpscout to fetch threads data.
+    #   By default, use data provided in conversation payload. Note that the
+    #   threads are only embedded to the conversation payload on demand, example:
+    #   +Cubscout::Conversation.all(tag: 'blue,red', embed: 'threads')+
+    #   +Cubscout::Conversation.find(1234567, embed: 'threads')+
+    # @return [Array<Object>] thread items
+    def threads(fetch: false)
+      if fetch
+        Conversation.threads(self.id)
+      else
+        self.attributes.dig("_embedded", "threads").map { |item| ThreadItem.new(item) }
+      end
+    end
+
+    # Create a note to a conversation.
+    # @option attributes [String] :text the note's text. Required.
+    # @option attributes [Integer] :user (Resource Owner) ID of the user creating the note.
+    # @option attributes [Boolean] :imported (false) The imported field enables thread to be
+    #   created for historical purposes (i.e. if moving from a different platform, you can import
+    #   your history).
+    #   When imported is set to true, no outgoing emails or notifications will be generated.
+    # @option attributes [String] :createdAt Optional creation date to be used
+    #   when importing conversations and threads.
+    #   It can only be used with imported field set to true
+    # @option attributes [Array<Hash>] :attachments Optional list of attachments to be attached to this thread
+    #     * :fileName (String) Attachment’s file name
+    #     * :mimeType (String) Attachment’s mime type
+    #     * :data (String) Base64-encoded stream of data.
+    # @return [Boolean] success status
+    def create_note(attributes)
+      Conversation.create_note(self.id, attributes)
+    end
+
+    # Update a conversation.
+    # @option attributes [String] :op Patch operation to be carried out, one of +move+, +remove+, +replace+. Required
+    # @option attributes [String] :path Path of the value to be changed, one of:
+    #   +/assignTo+, +/draft+, +/mailboxId+, +/primaryCustomer.id+, +/status+, +/subject+. Required
+    # @option attributes [Varies] :value Value to be used in operation, refer to this documentation
+    #   for valid types: https://developer.helpscout.com/mailbox-api/endpoints/conversations/update/#valid-paths-and-operations.
+    #   In case of status update +(op: "replace", path: "/status")+, :value must be one of +active+, +closed+, +open+, +pending+, +spam+
+    def update(attributes)
+      Conversation.update(self.id, attributes)
+    end
+  end
+end

data/lib/cubscout/list.rb

@@ -0,0 +1,54 @@
+module Cubscout
+  # the List class is the base class for any collection of objects retrieved from the Helpscout API.
+  # it's an Enumerable that can iterate over each of it's items.
+  #
+  # Helpscout API V2 is paginated and will return at max 50 items for each collection
+  # endpoint. The List class allows to query the page status.
+  class List
+    include Enumerable
+
+    def initialize(raw_payload, collection_name, object_class)
+      @raw_payload = raw_payload
+      @collection_name = collection_name
+      @object_class = object_class
+    end
+
+    # current page number
+    def page
+      raw_payload.dig("page", "number")
+    end
+
+    # number of items in the current page. Should be the same as number of +items+, but sometimes it's not (assumption: it's a bug in helpscout)
+    def page_size
+      raw_payload.dig("page", "size")
+    end
+
+    # total number of pages available
+    def number_of_pages
+      raw_payload.dig("page", "totalPages")
+    end
+
+    # total number of items available
+    def total_size
+      raw_payload.dig("page", "totalElements")
+    end
+
+    # array of objects Object retrieved from the API's collection endpoint.
+    def items
+      Array(raw_payload.dig("_embedded", collection_name)).map { |item| object_class.new(item) }
+    end
+
+    # number of +items+
+    def size
+      items.size
+    end
+
+    def each(&block)
+      items.each(&block)
+    end
+
+    private
+
+    attr_reader :raw_payload, :collection_name, :object_class
+  end
+end

data/lib/cubscout/object.rb

@@ -0,0 +1,33 @@
+module Cubscout
+  # the Object class is the base class for any object retrieved from the Helpscout API.
+  # it's attributes can be read either as they are returned (usually camel case)
+  # but also in snake case.
+  # @example
+  #  obj = Cubscout::Object.new("firstName" => "Joren")
+  #  puts obj.firstName # => "Joren"
+  #  puts obj.first_name # => "Joren"
+  class Object
+    include Scopes
+
+    attr_reader :attributes
+
+    def initialize(attributes)
+      # Dirty deep_transform_keys to strings
+      @attributes = JSON.parse(attributes.to_json)
+    end
+
+    def method_missing(method_name, *args, &block)
+      key = camelize(method_name)
+      return super unless @attributes.key?(key)
+
+      @attributes[key]
+    end
+
+    private
+
+    def camelize(sym)
+      parts = sym.to_s.split('_')
+      parts[0] + parts[1..-1].map(&:capitalize).join
+    end
+  end
+end

data/lib/cubscout/request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Cubscout
+  class Request < Faraday::Middleware
+    def call(env)
+      env.request_headers['Authorization'] = "Bearer #{Config.oauth_token}"
+      env.request_headers['Content-Type'] = 'application/json'
+      env.request_headers['Accept'] = 'application/json'
+
+      @app.call(env)
+    end
+  end
+end

data/lib/cubscout/resource.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Cubscout
+  class << self
+    def connection
+      @connection ||= Faraday.new(url: Cubscout::Config.api_prefix) do |faraday|
+        faraday.use Cubscout::Request
+        faraday.use Cubscout::Response
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+  end
+end

data/lib/cubscout/response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Cubscout
+  class Response < Faraday::Response::Middleware
+    def on_complete(env)
+      handle_response_status(env.status, env)
+      parse_json_reponse(env)
+    end
+
+    private
+
+    def handle_response_status(status, env)
+      case status
+      when 400
+        raise Cubscout::MalformedRequestError, env.body
+      when 401
+        raise Cubscout::AuthenticationError, env.body
+      when 403
+        raise Cubscout::PermissionDeniedError, env.body
+      when 404
+        raise Cubscout::ResourceNotFoundError, env.body
+      when 429
+        limit = env.response_headers["x-ratelimit-limit-minute"]
+        remaining = env.response_headers["x-ratelimit-remaining-minute"]
+        retry_after = env.response_headers["x-ratelimit-retry-after"]
+        raise Cubscout::RateLimitExceeded, {retry_after_minutes: retry_after, limit: limit, remaining: remaining}
+      when 500
+        raise Cubscout::InternalError, env.body
+      end
+    end
+
+    def parse_json_reponse(env)
+      return true if [201, 204].include?(env.status)
+
+      begin
+        parsed_body = JSON.parse(env.body)
+        env[:raw_body] = env.body
+      rescue JSON::ParserError
+        raise Cubscout::JsonParseError, env.body
+      end
+
+      env.body = parsed_body
+    end
+
+  end
+end

data/lib/cubscout/scopes.rb

@@ -0,0 +1,78 @@
+module Cubscout
+  # The Scopes module allows for Active Record kind of queries like .all and .find
+  # this module is included in Object, meaning that every subclass of Object can
+  # call the Scopes ClassMethods.
+  # @example
+  #  class Foo < Object; end
+  #  Foo.find(id)
+  #  Foo.all(page: 1)
+  module Scopes
+    module ClassMethods
+      # DSL: necessary to provide the endpoint of the resources to query.
+      # @param path [String] path to the endpoint, without leading slash
+      # @example
+      #   class Conversation
+      #     include Cubscout::Scopes
+      #     endpoint "conversations"
+      #   end
+      def endpoint(path)
+        @path = path
+      end
+
+      # Read the path entered through the DSL
+      def path
+        @path
+      end
+
+      # used with a collection endpoint, get all objects of a certain kind
+      # @param options [Hash] Optional query params described in Helspcout API documentation
+      # @return [Cubscout::List] Returns a List collection where items are instances of the class where the method is called.
+      # @example
+      #   foos = Foo.all(tag: "bar")
+      #   foos.total_size # 335 with this filter
+      #   foos.each { |foo_element| puts "ID is #{foo_element.id}" }
+      def all(options = {})
+        raise Error, "`#{self}.all` method is not available" unless path
+
+        raw_first_or_requested_page = Cubscout.connection.get(path, page: options[:page] || 1, **options).body
+        first_or_requested_page = List.new(raw_first_or_requested_page, path, self)
+
+        if options[:page]
+          first_or_requested_page
+        else
+          last_page_number = first_or_requested_page.number_of_pages
+
+          raw_other_pages_items = (2..last_page_number).to_a.map do |page|
+            Array(Cubscout.connection.get(path, page: page, **options).body.dig("_embedded", path))
+          end
+
+          raw_all_pages = {
+            "_embedded" => { path => (Array(raw_first_or_requested_page.dig("_embedded", path)) + raw_other_pages_items).flatten },
+            "page" => {
+              "number" => first_or_requested_page.page,
+              "size" => first_or_requested_page.total_size,
+              "totalPages" => first_or_requested_page.number_of_pages,
+              "totalElements" => first_or_requested_page.total_size
+            }
+          }
+          List.new(raw_all_pages, path, self)
+        end
+      end
+
+      # used with an instance endpoint, get one instance of an Object
+      # @param id [Integer] ID of the object to get
+      # @param options [Hash] Optional query params described in Helspcout API documentation
+      # @return [Object] Returns an instance of the class where the method is called.
+      #   Example: +Foo.find(123) # => returns an instance of Foo+
+      def find(id, options = {})
+        raise Error, "`#{self}.find` method is not available" unless path
+
+        self.new(Cubscout.connection.get("#{path}/#{id}", options).body)
+      end
+    end
+
+    def self.included(mod)
+      mod.extend ClassMethods
+    end
+  end
+end

data/lib/cubscout/thread_item.rb

@@ -0,0 +1,4 @@
+module Cubscout
+  class ThreadItem < Object
+  end
+end

data/lib/cubscout/user.rb

@@ -0,0 +1,5 @@
+module Cubscout
+  class User < Object
+    endpoint "users"
+  end
+end

data/lib/cubscout/version.rb

@@ -0,0 +1,3 @@
+module Cubscout
+  VERSION = "0.2.0"
+end

metadata

@@ -0,0 +1,162 @@
+--- !ruby/object:Gem::Specification
+name: cubscout
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Joren De Groof
+- Fabien Loup
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-05-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: oauth2
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+description: Help Scout api v2 wrapper
+email:
+- joren@silverfin.com
+- fabien@silverfin.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- lib/cubscout.rb
+- lib/cubscout/config.rb
+- lib/cubscout/conversation.rb
+- lib/cubscout/list.rb
+- lib/cubscout/object.rb
+- lib/cubscout/request.rb
+- lib/cubscout/resource.rb
+- lib/cubscout/response.rb
+- lib/cubscout/scopes.rb
+- lib/cubscout/thread_item.rb
+- lib/cubscout/user.rb
+- lib/cubscout/version.rb
+homepage: https://developer.helpscout.com/mailbox-api/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://developer.helpscout.com/mailbox-api/
+  source_code_uri: https://github.com/GetSilverfin/cubscout
+  changelog_uri: https://github.com/GetSilverfin/cubscout/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Help Scout api v2 wrapper
+test_files: []