help_spot 0.0.2

data/.gitignore

@@ -0,0 +1,4 @@
+pkg
+doc
+*.gem
+config/help_spot.yml

data/History.txt

@@ -0,0 +1,14 @@
+== 0.0.2 2009-10-11
+
+* Add to SSL
+* Release to Gemcutter
+
+== 0.0.1.4 2009-02-09
+
+* Pushed to github
+
+== 0.0.1   2009-01-05
+
+* 1 major enhancement:
+  * Initial release
+

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2009 Jamie Wilson
+
+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.rdoc

@@ -0,0 +1,25 @@
+= HelpSpot
+
+Ruby gem to talk to the API of a HelpSpot instance.
+
+For information on HelpSpot: http://www.userscape.com/products/helpspot/
+
+Details of HelpSpot's API are at: http://www.userscape.com/helpdesk/index.php?pg=kb.book&id=6
+
+== License
+
+Licensed under the MIT License. See the included LICENSE file.
+
+= Usage
+
+== Installation
+
+Copy the <tt>config/help_spot.yml.sample</tt> file to <tt>THE_ROOT_DIR_OF_YOUR_APP/config/help_spot.yml</tt>. Edit the file to have some sensible values.
+
+Somewhere in your application, you'll want to do this once:
+
+<tt>HelpSpot.configure</tt>
+
+In my app, it also turns out it's useful to do this once:
+
+<tt>HELPSPOT_CATEGORIES = HelpSpot.category_key_value_pairs</tt>

data/Rakefile

@@ -0,0 +1,49 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "help_spot"
+    gem.summary = %Q{A package for interacting with UserScape's HelpSpot product.}
+    gem.description = %Q{A package for interacting with UserScape's HelpSpot product.}
+    gem.email = "jnewland@gmail.com"
+    gem.homepage = "http://github.com/jnewland/help_spot"
+    gem.authors = ["Jamie Wilson","Jesse Newland"]
+    gem.add_development_dependency "rspec"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  if File.exist?('VERSION')
+    version = File.read('VERSION')
+  else
+    version = ""
+  end
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "help_spot #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.2

data/config/help_spot.yml.sample

@@ -0,0 +1,6 @@
+root_url: http://www.example.com/helpspot/api/index.php?format=json
+username: helpspot_user@example.com
+password: my_p@ssw0rd
+hidden_categories: 
+  - Deactivations
+  - 'Contact Us'

data/help_spot.gemspec

@@ -0,0 +1,54 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE
+# Instead, edit Jeweler::Tasks in Rakefile, and run `rake gemspec`
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{help_spot}
+  s.version = "0.0.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Jamie Wilson", "Jesse Newland"]
+  s.date = %q{2009-10-11}
+  s.description = %q{A package for interacting with UserScape's HelpSpot product.}
+  s.email = %q{jnewland@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.rdoc"
+  ]
+  s.files = [
+    ".gitignore",
+     "History.txt",
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "config/help_spot.yml.sample",
+     "help_spot.gemspec",
+     "lib/help_spot.rb",
+     "spec/help_spot_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/jnewland/help_spot}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.3}
+  s.summary = %q{A package for interacting with UserScape's HelpSpot product.}
+  s.test_files = [
+    "spec/help_spot_spec.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<rspec>, [">= 0"])
+    else
+      s.add_dependency(%q<rspec>, [">= 0"])
+    end
+  else
+    s.add_dependency(%q<rspec>, [">= 0"])
+  end
+end

data/lib/help_spot.rb

@@ -0,0 +1,200 @@
+require 'uri'
+require 'net/http'
+require 'net/https'
+require 'json'
+
+##
+# help_spot
+#
+# A partial basic implementation of a HelpSpot API interface
+#
+# == Using help_spot
+#
+# === Basics
+#
+# Copy and edit the included config file. Include the gem in your app. Call the configure method. Hit the API.
+#
+#   require 'help_spot'
+#   HelpSpot.configure(:config_file => '/path/to/help_spot.yml')
+#   HelpSpot.forums_list
+#
+#   => [{"xForumId"=>"1", "fClosed"=>"0", "sForumName"=>"The First Forum", "iOrder"=>"0", "sDescription"=>"A test forum"}, {"xForumId"=>"2", "fClosed"=>"0", "sForumName"=>"Secondary Forum", "iOrder"=>"0", "sDescription"=>"Forum #2"}]
+#
+
+module HelpSpot
+  class << self
+
+    # Loads the config file.
+    #
+    # == Options
+    # * config_file (optional)
+    #     Defaults to '/config/help_spot.yml'
+    #     Shouldn't be required when using merb or Rails.
+    #
+    def configure(args={})
+      # work out the default app_root
+      if defined?(Merb)
+        app_root = Merb.root
+      elsif defined?(Rails)
+        app_root = RAILS_ROOT
+      else
+        app_root = '.'
+      end
+
+      config_file = args[:config_file] || '/config/help_spot.yml'
+      yml_file    = app_root+config_file
+
+      raise yml_file+" not found" unless File.exist? yml_file
+      @config = YAML.load_file(yml_file)
+    end
+
+    # sends a feedback request to HelpSpot and returns the request ID number and access key
+    #
+    # == Options
+    # In addition to note you must also have at least one of the following set: first_name, last_name, user_id, email or phone
+    # * note
+    #     The body of the ticket
+    # * category
+    # * first_name
+    # * last_name
+    # * user_id
+    # * email
+    # * phone
+    # * urgent
+    #     A boolean flag. Defaults to false.
+    #
+    def create(args)
+      help_form = {:tNote       => args[:note],
+                   :xCategory   => args[:category],
+                   :sFirstName  => args[:first_name],
+                   :sLastName   => args[:last_name],
+                   :sUserId     => args[:user_id],
+                   :sEmail      => args[:email],
+                   :sPhone      => args[:phone],
+                   :fUrgent     => args[:urgent]}.reject!{|k,v| v == nil}
+
+      JSON.parse(api_request('request.create', 'POST', help_form))['xRequest'] rescue []
+    end
+
+    # Returns an array of tickets belonging to a given user id.
+    #
+    # == Authentication
+    # This method does require authentication.
+    #
+    # == Options
+    # * user_id
+    #     The user who's tickets you wish to view.
+    #
+    def get_by_user_id(args)
+      JSON.parse(api_request('private.request.search', 'GET', {:sUserId => args[:user_id]}))['request'] rescue nil
+    end
+
+    # Returns ticket categories.
+    #
+    # == Authentication
+    # This method does require authentication.
+    #
+    # == Options
+    # * include_deleted
+    #     true if you want to include deleted categories.
+    #
+    def categories(args={})
+      res = api_request('private.request.getCategories', 'GET')
+      res = JSON.parse(res)['category'] rescue []
+
+      unless args[:include_deleted] and args[:include_deleted] == true
+        res.reject!{|k, v| v['fDeleted'] == '1'} rescue []
+      end
+
+      return res
+    end
+
+    # Returns an array of non-deleted categories, as key value pairs. Useful for select lists.
+    #
+    # == Authentication
+    # This method does require authentication.
+    #
+    def category_key_value_pairs
+      categories.collect{|k,v| [k,v['sCategory']]} rescue []
+    end
+
+    # Returns non-deleted categories, with a list of predefined categories removed
+    #
+    def category_key_value_pairs_without(categories=nil)
+      categories ||= @config['hidden_categories'] rescue nil
+
+      orig_categories = category_key_value_pairs
+      if categories
+        categories.each do |category|
+          orig_categories.reject!{|i| i[1] == category}
+        end
+      end
+      orig_categories
+    end
+
+    # Returns an array of forums
+    #
+    def forums_list
+      JSON.parse(HelpSpot.api_request('forums.list'))['forum'] rescue []
+    end
+
+    # Returns an array of forums
+    #
+    # == Options
+    # * forum_id
+    #     The numeric id of the forum you want.
+    def forum_get(args)
+      JSON.parse(HelpSpot.api_request('forums.get', 'GET', :xForumId => args[:forum_id])) rescue []
+    end
+
+    # Returns an array of topics from a given forum
+    #
+    # == Options
+    # * forum_id
+    #     The numeric id of the forum you want.
+    # * start
+    #     record set position to start at
+    # * length
+    #     how many records to return
+    #
+    def forum_get_topics(args={})
+      JSON.parse(HelpSpot.api_request('forums.getTopics', 'GET', {:xForumId => args[:forum_id]}.merge(args)))['topic'] rescue []
+    end
+
+    # Returns an array of posts from a given topic
+    #
+    # == Options
+    # * topic_id
+    #     The numeric id of the topic
+    #
+    def forum_get_topic_posts(args={})
+      JSON.parse(HelpSpot.api_request('forums.getPosts', 'GET', :xTopicId => args[:topic_id]))['post'] rescue []
+    end
+
+    def api_request(api_method, http_method='POST', args={})
+      api_params =  {:method => api_method, :output => 'json'}.merge(args)
+      query_params = api_params.collect{|k,v| [k.to_s, v.to_s]} # [URI.encode(k.to_s),URI.encode(v.to_s.gsub(/\ /, '+'))]
+      built_query  = query_params.collect{|i| i.join('=')}.join('&') # make a query string
+
+      ru = URI::parse(@config['root_url']) # where ru = ROOT_URL
+      merged_query = [built_query, (ru.query == '' ? nil : ru.query)].compact.join('&') # merge our generated query string with the ROOT_URL's query string
+
+      url = URI::HTTP.new(ru.scheme, ru.userinfo, ru.host, ru.port, ru.registry, ru.path, ru.opaque, merged_query, ru.fragment)
+
+      request = nil
+      if http_method == 'POST'
+        request = Net::HTTP::Post.new(url.path)
+        request.set_form_data(query_params)
+      else
+        request = Net::HTTP::Get.new(url.path+'?'+url.query)
+      end
+      request.basic_auth @config['username'], @config['password']
+      http = Net::HTTP.new(url.host, url.port)
+      http.use_ssl = (url.scheme == 'https')
+      response = http.start { |h| h.request(request) }
+
+      response.body
+    end
+
+  end # class
+end # module

data/spec/help_spot_spec.rb

@@ -0,0 +1,7 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe "HelpSpot" do
+  it "fails" do
+    fail "hey buddy, you should probably rename this file and start specing for real"
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+require 'help_spot'
+require 'spec'
+require 'spec/autorun'
+
+Spec::Runner.configure do |config|
+  
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification 
+name: help_spot
+version: !ruby/object:Gem::Version 
+  version: 0.0.2
+platform: ruby
+authors: 
+- Jamie Wilson
+- Jesse Newland
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-11 00:00:00 -04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: A package for interacting with UserScape's HelpSpot product.
+email: jnewland@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- .gitignore
+- History.txt
+- LICENSE
+- README.rdoc
+- Rakefile
+- VERSION
+- config/help_spot.yml.sample
+- help_spot.gemspec
+- lib/help_spot.rb
+- spec/help_spot_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/jnewland/help_spot
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.3
+signing_key: 
+specification_version: 3
+summary: A package for interacting with UserScape's HelpSpot product.
+test_files: 
+- spec/help_spot_spec.rb
+- spec/spec_helper.rb