help-scout-docs 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3951d0d359947e296adf2c26f393bfc614b836f8
+  data.tar.gz: f2fe077c8dbc7c6f7cca29ed1cf265de88687723
+SHA512:
+  metadata.gz: 7c5582f84ff736fc114dfef007290c6d42baaa4d422759cb8eecaccb82ccbc1f8514925fae19bc482943e51d8b5983505001ae86fd7ae07a5fc10da9dc1721a1
+  data.tar.gz: d093a2b0ddeb3ec679f3791e988c7e5e40144dc182ffe6842539492480b9339b33e1105d92270e7ad1f870077976c753bf99c360a04afa1eb5489331185f04f2

data/.rspec

@@ -0,0 +1,3 @@
+--drb
+--colour
+-f d

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,56 @@
+PATH
+  remote: .
+  specs:
+    help-scout-docs (0.1)
+      faraday_middleware (~> 0.9)
+      json (~> 1.8)
+      log4r (~> 1.1)
+      net-http-persistent (~> 2.9)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.6)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.2.5)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.9.1)
+      faraday (>= 0.7.4, < 0.10)
+    json (1.8.1)
+    json_spec (1.1.2)
+      multi_json (~> 1.0)
+      rspec (>= 2.0, < 4.0)
+    log4r (1.1.10)
+    multi_json (1.10.1)
+    multipart-post (2.0.0)
+    net-http-persistent (2.9.4)
+    rspec (3.0.0)
+      rspec-core (~> 3.0.0)
+      rspec-expectations (~> 3.0.0)
+      rspec-mocks (~> 3.0.0)
+    rspec-core (3.0.4)
+      rspec-support (~> 3.0.0)
+    rspec-expectations (3.0.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.0.0)
+    rspec-mocks (3.0.4)
+      rspec-support (~> 3.0.0)
+    rspec-support (3.0.4)
+    safe_yaml (1.0.3)
+    vcr (2.9.2)
+    webmock (1.18.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  help-scout-docs!
+  json_spec (~> 1.1)
+  multi_json (~> 1.8)
+  rspec (~> 3.0)
+  vcr (~> 2.9)
+  webmock (~> 1.15)

data/README.rdoc

@@ -0,0 +1,62 @@
+= Help Scout Docs
+
+This limited (read-only) Help Scout Docs API integration provides functionality for extracting existing documentation content
+
+See: http://developer.helpscout.net/docs-api/
+
+== Interfacing with the API directly
+
+=== Configuration
+
+In your initializer:
+
+  HelpScoutDocs.configure do |config|
+    config.api_key  = "api-key"
+  end
+
+Or set ENV['HELP_SCOUT_DOCS_API_KEY']
+
+==== Create client
+
+  client = HelpScoutDocs::Client.new({api_key: "api-key"})
+
+==== Articles
+
+Supported methods: get, list (by_category, by_collection), related, revisions, get_revision
+
+  HelpScoutDocs::Article.new.get(1)
+    => HelpScoutDoc::Result #response=>{article: {id: 1, number: "6239e556e4b0cf4cd3254852"} ...}
+
+==== Categories
+
+Supported methods: list, get
+
+  HelpScoutDocs::Category.new.list(1)
+  HelpScoutDocs::Category.new.get(1)
+
+==== Collections
+
+Supported methods: list, get
+
+  HelpScoutDocs::Collection.new.list
+  HelpScoutDocs::Collection.new.get(1)
+
+==== Sites
+
+Supported methods: list, get
+
+  HelpScoutDocs::Collection.new.list
+  HelpScoutDocs::Collection.new.get(1)
+
+=== Passing parameters
+
+Additional parameters are supported for each request (as well as ids in place of numbers), for example:
+
+  HelpScoutDocs::Collection.new.list("123", { siteId: 1, page: 2 })
+
+
+== TODO
+
+* Add objects for returned types (Asset, Article, Category, Collection, Site) and collections
+* Add write methods (create, update etc.)
+* Handle all error response codes

data/help_scout_docs.gemspec

@@ -0,0 +1,33 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "help_scout_docs/version"
+
+Gem::Specification.new do |s|
+  s.name        = "help-scout-docs"
+  s.version     = HelpScoutDocs::VERSION
+  s.license     = "MIT"
+  s.authors     = ["Mark Edmondson"]
+  s.email       = ["mark@guestfolio.com"]
+  s.homepage    = %q{https://github.com/Guestfolio/help-scout-docs}
+  s.summary     = %q{Integration with Help Scout Docs API}
+  s.description = %q{This limited (read-only) Help Scout Docs API integration provides functionality for extracting existing documentation content}
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+
+  s.has_rdoc = true
+
+  s.add_development_dependency "multi_json", "~> 1.8"
+
+  s.add_development_dependency "rspec", "~> 3.0"
+  s.add_development_dependency "webmock", "~> 1.15"
+  s.add_development_dependency "vcr", "~> 2.9"
+  s.add_development_dependency "json_spec", "~> 1.1"
+
+  s.add_runtime_dependency "log4r", "~> 1.1"
+  s.add_runtime_dependency "faraday_middleware", "~> 0.9"
+  s.add_runtime_dependency "json", "~> 1.8"
+  s.add_runtime_dependency "net-http-persistent",  "~> 2.9"
+end

data/lib/help_scout_docs.rb

@@ -0,0 +1,14 @@
+require 'log4r'
+require 'help_scout_docs/configurable'
+require 'help_scout_docs/error/errors'
+require 'help_scout_docs/client'
+require 'help_scout_docs/methods/methods'
+require 'help_scout_docs/result'
+
+module HelpScoutDocs
+  class << self
+    include HelpScoutDocs::Configurable
+  end
+end
+
+HelpScoutDocs.setup

data/lib/help_scout_docs/client.rb

@@ -0,0 +1,95 @@
+require 'faraday'
+require 'json'
+
+module HelpScoutDocs
+  class Client
+    attr_reader :format, :logger
+
+    # Initializes a new Client object
+    #
+    # @param options [Hash]
+    # @return [HelpScoutDocs::Client]
+    #
+    def initialize(options={})
+      @logger = options.delete(:logger) || self.class.logger
+      HelpScoutDocs::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", options[key] || HelpScoutDocs.instance_variable_get(:"@#{key}"))
+      end
+    end
+
+    # Perform an HTTP GET request
+    #
+    # @param action [Array]
+    #
+    def get(path=nil, params={})
+      @path ||= path
+      request(:get, params)
+    end
+
+    # Perform an HTTP POST request
+    #
+    # @param action [Array]
+    #
+    def post(path=nil, params={})
+      @path ||= path
+      request(:post, params)
+    end
+
+    private
+
+    def self.logger
+      Log4r::Logger.new("help_scout_docs::client")
+    end
+
+    # @return [Boolean]
+    #
+    def path
+      @path || raise(ArgumentError, "Required path missing")
+    end
+
+    # @return [Boolean]
+    #
+    def authentication_params?
+      authentication_params.values.all?
+    end
+
+    # Add hash of authentication params
+    # @return [Hash]
+    #
+    def authentication_params
+      {
+        api_key:      @api_key,
+        api_password: @api_password
+      }
+    end
+
+    # Setup the Faraday::Request headers
+    #
+    def headers
+      {
+        ACCEPT: "application/json",
+        ACCEPT_CHARSET: "utf-8"
+      }
+    end
+
+    def request(method, params={})
+      response = connection.send(method.to_sym, path, params, headers)
+      Result.new(response.body) #.force_encoding('utf-8')
+    rescue JSON::ParserError => e
+      @logger.error "Unable to parse Help Scout Docs API response: #{e.message}"
+      @logger.debug response
+      raise HelpScoutDocs::Error::ParserError.new e.message
+    end
+
+    # Returns a Faraday::Connection object
+    #
+    # @return [Faraday::Connection]
+    #
+    def connection
+      raise ArgumentError, "Required authentication params missing" unless authentication_params?
+      @connection ||= Faraday.new(@endpoint, builder: @middleware).tap do |c|
+        c.basic_auth(authentication_params[:api_key], authentication_params[:api_password])
+      end
+    end
+  end
+end

data/lib/help_scout_docs/configurable.rb

@@ -0,0 +1,78 @@
+require 'forwardable'
+require 'help_scout_docs/default'
+
+module HelpScoutDocs
+  module Configurable
+    extend Forwardable
+    attr_accessor :api_key, :api_password, :endpoint, :middleware
+    def_delegator :options, :hash
+
+    class << self
+
+      def keys
+        @keys ||= [
+          :api_key,
+          :api_password,
+          :endpoint,
+          :middleware
+        ]
+      end
+
+    end
+
+    # Convenience method to allow configuration options to be set in a block
+    #
+    def configure
+      yield self
+      validate_credential_type!
+      self
+    end
+
+    def reset!
+      HelpScoutDocs::Configurable.keys.each do |key|
+        instance_variable_set(:"@#{key}", HelpScoutDocs::Default.options[key])
+      end
+      self
+    end
+    alias setup reset!
+
+    # @return [Boolean]
+    #
+    def credentials?
+      credentials.values.all?
+    end
+
+    private
+
+    # @return [Hash]
+    #
+    def credentials
+      {
+        api_key: @api_key,
+        api_password: @api_password
+      }
+    end
+
+    # @return [Hash]
+    #
+    def options
+      Hash[HelpScoutDocs::Configurable.keys.map{|key| [key, instance_variable_get(:"@#{key}")]}]
+    end
+
+    # Ensures that all credentials set during configuration are of a
+    # valid type. Valid types are String and Symbol.
+    #
+    # @raise [HelpScoutDocs::Error::ConfigurationError] Error is raised when
+    #   supplied twitter credentials are not a String or Symbol.
+    def validate_credential_type!
+      credentials.each do |credential, value|
+        next if value.nil?
+
+        unless value.is_a?(String) || value.is_a?(Symbol)
+          raise(Error::ConfigurationError, "Invalid #{credential} specified: #{value} must be a string or symbol.")
+        end
+      end
+    end
+
+  end
+end

data/lib/help_scout_docs/default.rb

@@ -0,0 +1,55 @@
+require 'faraday'
+require 'faraday/request/multipart'
+require 'help_scout_docs/configurable'
+require 'help_scout_docs/response/parse_json'
+require 'help_scout_docs/version'
+
+module HelpScoutDocs
+  module Default
+#     Faraday.default_adapter = :net_http_persistent
+
+    ENDPOINT = 'https://docsapi.helpscout.net/v1/'
+    MIDDLEWARE = Faraday::Builder.new do |builder|
+      # Encode request params as "www-form-urlencoded"
+      builder.use Faraday::Request::UrlEncoded
+      # Parse JSON response bodies
+      builder.use HelpScoutDocs::Response::ParseJson#, content_type: /\bjson$/
+      # Use Faraday logger
+      builder.use Faraday::Response::Logger if ENV['DEBUG']
+      # Set Faraday's HTTP adapter
+      builder.adapter Faraday.default_adapter
+    end
+
+    class << self
+
+      # @return [Hash]
+      def options
+        Hash[HelpScoutDocs::Configurable.keys.map{|key| [key, send(key)]}]
+      end
+
+      # @return [String]
+      def api_key
+        ENV['HELP_SCOUT_DOCS_API_KEY']
+      end
+
+      # @return [String]
+      def api_password
+        ENV['HELP_SCOUT_DOCS_API_PASSWORD'] || "X"
+      end
+
+      # @return [String]
+      def endpoint
+        ENDPOINT
+      end
+
+      # @note Faraday's middleware stack implementation is comparable to that of Rack middleware.  The order of middleware is important: the first middleware on the list wraps all others, while the last middleware is the innermost one.
+      # @see https://github.com/technoweenie/faraday#advanced-middleware-usage
+      # @see http://mislav.uniqpath.com/2011/07/faraday-advanced-http/
+      # @return [Faraday::Builder]
+      def middleware
+        MIDDLEWARE
+      end
+
+    end
+  end
+end

data/lib/help_scout_docs/error.rb

@@ -0,0 +1,5 @@
+module HelpScoutDocs
+  # Custom error class for rescuing errors
+  class Error < StandardError
+  end
+end

data/lib/help_scout_docs/error/authentication_error.rb

@@ -0,0 +1,6 @@
+module HelpScoutDocs
+  class Error
+    class AuthenticationError < Error
+    end
+  end
+end

data/lib/help_scout_docs/error/configuration_error.rb

@@ -0,0 +1,6 @@
+module HelpScoutDocs
+  class Error
+    class ConfigurationError < Error
+    end
+  end
+end

data/lib/help_scout_docs/error/errors.rb

@@ -0,0 +1,6 @@
+require 'help_scout_docs/error'
+require 'help_scout_docs/error/authentication_error'
+require 'help_scout_docs/error/configuration_error'
+require 'help_scout_docs/error/options_error'
+require 'help_scout_docs/error/parser_error'
+require 'help_scout_docs/error/resource_not_found_error'