zenpush 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+pkg
+*.gem
+.bundle

data/Gemfile

@@ -0,0 +1,4 @@
+# A sample Gemfile
+source "http://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: .
+  specs:
+    zenpush (0.1.0)
+      awesome_print (~> 1.0.0)
+      boson (~> 1.0)
+      httparty (~> 0.8.0)
+      json_pure (~> 1.5.1)
+      redcarpet (~> 2.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    awesome_print (1.0.2)
+    boson (1.1.0)
+    httparty (0.8.1)
+      multi_json
+      multi_xml
+    json_pure (1.5.4)
+      spruz (~> 0.2.8)
+    multi_json (1.1.0)
+    multi_xml (0.4.1)
+    rake (0.9.2.2)
+    redcarpet (2.1.0)
+    spruz (0.2.13)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  zenpush!

data/History.txt

@@ -0,0 +1,5 @@
+== 0.1.0
+
+* Original version
+* List categories, forums, entries
+* Convert entries from Markdown to HTML push them to Zendesk

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2012 CleverScale
+
+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.markdown

@@ -0,0 +1,73 @@
+# ZenPush
+
+This gem allows editing your Zendesk knowledge base in Markdown. It's a command-line tool.
+
+## Getting Started
+
+    $ gem install zenpush
+
+Run it:
+
+    $ zenpush <command> <args>
+    $ zp <command> <args>
+
+## Requirements:
+
+Only installs pure JSON gem json_pure by default. If you are able to install the C-extension json gem, it will use that instead.
+
+Try:
+
+    $ gem install json zenpush
+
+## Configuration
+
+Create a `zenpush.yml` file in your home directory. Here is an example:
+
+    ---
+    uri: https://myproduct.zendesk.com
+    user: email@address.com/token
+    password: LoDsQlEtBXSd8clW87DgWi0VNFod3U9xQggzwJEH
+
+You can find your API token at https://myproduct.zendesk.com/settings/api.
+
+## Usage
+
+### Listing categories
+
+    $ zp categories
+
+### Listing forums
+
+    $ zp forums
+
+### Listing entries in a forum
+
+    $ zp entries -f <forum_id>
+    $ zp entries -F <forum_name>
+
+### Creating/updating an entry
+
+Keep an organized folder of your categories, forums, and entries. Let's say I have the category "Documentation", containing a forum "REST API", and the entries "Introduction" and "Authentication"; you'll want to keep this file structure:
+
+    Documentation/REST API/Introduction.md
+    Documentation/REST API/Authentication.md
+
+Creating or updating an entry:
+
+    $ zp push -f <path_to_markdown_file>
+
+Following the previous example, you would type:
+
+    [~/KB/Documentation/REST API]$ zp push -f Authentication.md
+    [~/KB/Documentation]$ zp push -f REST API/Authentication.md
+    [~/KB]$ zp push -f REST Documentation/API/Authentication.md
+
+The gem will automatically discover the category and forum name of a given entry file. It will also convert your Markdown syntax in HTML before sending it to Zendesk.
+
+### Check if an entry exists
+
+    $ zp exists? -f <path_to_markdown_file>
+
+## Contributors
+
+* @nfo

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/setup"
+Bundler::GemHelper.install_tasks

data/bin/zenpush

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'zenpush'
+ZenPush::Runner.start

data/bin/zp

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'zenpush'
+ZenPush::Runner.start

data/lib/zenpush/markdown.rb

@@ -0,0 +1,13 @@
+# encoding: UTF-8
+require 'redcarpet/compat'
+
+module ZenPush
+  class Markdown
+
+    # Convert a markdown file to HTML, removing all <code> tags,
+    # which make Zendesk remove carriage returns.
+    def self.to_zendesk_html(file)
+      ::Markdown.new(File.read(file)).to_html.gsub(/<\/?code>/, '')
+    end
+  end
+end

data/lib/zenpush/runner.rb

@@ -0,0 +1,55 @@
+# encoding: UTF-8
+require 'boson/runner'
+require 'ap'
+
+module ZenPush
+  class Runner < Boson::Runner
+
+    desc 'List categories'
+    def categories(options = {})
+      ap ZenPush.z.categories
+    end
+
+    desc 'List forums'
+    def forums(options = {})
+      ap ZenPush.z.forums
+    end
+
+    option :forum_id, :type => :numeric
+    desc 'List entries'
+    def entries(options = {})
+      ap ZenPush.z.entries(options[:forum_id])
+    end
+
+    desc 'Does the entry matching the given file exist ?'
+    option :file, :type => :string
+    def exists?(options = {})
+      category_name, forum_name, entry_title = ZenPush.file_to_category_forum_entry(options[:file])
+      entry = ZenPush.z.find_entry(category_name, forum_name, entry_title)
+      ap !!entry
+    end
+
+    desc 'Create or update an entry from the given file'
+    option :file, :type => :string
+    def push(options = {})
+      category_name, forum_name, entry_title = ZenPush.file_to_category_forum_entry(options[:file])
+
+      entry_body = ZenPush::Markdown.to_zendesk_html(options[:file])
+
+      entry = ZenPush.z.find_entry(category_name, forum_name, entry_title)
+      if entry
+        # UPDATE THE ENTRY
+        ap ZenPush.z.put_entry(entry['id'], entry_body)
+      else
+        forum = ZenPush.z.find_forum(category_name, forum_name)
+        if forum
+          # CREATE THE ENTRY
+          ap ZenPush.z.post_entry(forum['id'], entry_title, entry_body)
+        else
+          ap "Could not find a forum named '#{forum_name}' in the category '#{category_name}'"
+          exit(-1)
+        end
+      end
+    end
+  end
+end

data/lib/zenpush/version.rb

@@ -0,0 +1,4 @@
+# encoding: UTF-8
+module ZenPush
+  VERSION = "0.1.0"
+end

data/lib/zenpush/zendesk.rb

@@ -0,0 +1,111 @@
+# encoding: UTF-8
+require 'json'
+require 'yaml'
+require 'httparty'
+
+module ZenPush
+  class Zendesk
+    include HTTParty
+
+    headers 'Content-Type' => 'application/json'
+    # debug_output
+
+    def initialize(b = nil, u = nil, p = nil)
+      if b.nil? || u.nil? || p.nil?
+        creds = YAML.load_file(File.join(ENV['HOME'], '.zenpush.yml'))
+        b ||= creds['uri']
+        u ||= creds['user']
+        p ||= creds['password']
+      end
+
+      self.class.base_uri b + '/api/v1'
+      self.class.basic_auth u, p
+    end
+
+    def get(uri, options = {})
+      self.class.get(uri, options)
+    end
+
+    def post(uri, options = {})
+      self.class.post(uri, options)
+    end
+
+    def put(uri, options = {})
+      self.class.put(uri, options)
+    end
+
+    def delete(uri, options = {})
+      self.class.delete(uri, options)
+    end
+
+    def categories(options = {})
+      self.get('/categories.json', options).parsed_response
+    end
+
+    def category(category_id, options = {})
+      self.get("/categories/#{category_id}.json", options).parsed_response
+    end
+
+    def forums(options = {})
+      self.get('/forums.json', options).parsed_response
+    end
+
+    def forum(forum_id, options = {})
+      self.get("/forums/#{forum_id}.json", options).parsed_response
+    end
+
+    def users(options = {})
+      self.get('/users.json', options).parsed_response
+    end
+
+    def entries(forum_id, options = {})
+      self.get("/forums/#{forum_id}/entries.json", options).parsed_response
+    end
+
+    def entry(entry_id, options = {})
+      self.get("/entries/#{entry_id}.json", options).parsed_response
+    end
+
+    # Find category by name
+    def find_category(category_name, options = {})
+      self.categories.detect {|c| c['name'] == category_name}
+    end
+
+    # Find forum by name, knowing the category name
+    def find_forum(category_name, forum_name, options = {})
+      category = self.find_category(category_name, options)
+      if category
+        self.forums.detect {|f| f['name'] == forum_name}
+      end
+    end
+
+    # Find entry by name, knowing the forum name and category name
+    def find_entry(category_name, forum_name, entry_title, options = {})
+      forum = self.find_forum(category_name, forum_name, options)
+      if forum
+        self.entries(forum['id'], options).detect {|e| e['title'] == entry_title}
+      end
+    end
+
+    # Create an entry in the given forum id
+    def post_entry(forum_id, entry_title, entry_body, options = {})
+      self.post("/entries.json",
+        options.merge(
+          :body => { :entry => {
+            :forum_id => forum_id, :title => entry_title, :body => entry_body
+          } }.to_json
+        )
+      )
+    end
+
+    # Update an entry in the given forum id
+    def put_entry(entry_id, entry_body, options = {})
+      self.put("/entries/#{entry_id}.json",
+        options.merge(
+          :body => { :entry => { :body => entry_body } }.to_json
+        )
+      )
+    end
+
+  end
+end

data/lib/zenpush.rb

@@ -0,0 +1,23 @@
+# encoding: UTF-8
+require 'zenpush/runner'
+require 'zenpush/zendesk'
+require 'zenpush/markdown'
+
+module ZenPush
+  extend self
+
+  # Zendesk API
+  def z
+    @z ||= ZenPush::Zendesk.new
+  end
+
+  # 
+  def file_to_category_forum_entry(file)
+    absolute_path = File.realpath(file)
+    parts = absolute_path.split('/')
+    entry_name = File.basename(absolute_path, '.md') # TODO support .markdown and make it case insensitive
+    forum_name = parts[-2]
+    category_name = parts[-3]
+    return category_name, forum_name, entry_name
+  end
+end

data/zenpush.gemspec

@@ -0,0 +1,28 @@
+# encoding: UTF-8
+$:.push File.expand_path("../lib", __FILE__)
+require "zenpush/version"
+
+Gem::Specification.new do |s|
+  s.name        = "zenpush"
+  s.version     = ZenPush::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Nicolas Fouché"]
+  s.email       = ["nicolas.fouche@cleverscale.com"]
+  s.homepage    = "https://github.com/cleverscale/zenpush"
+  s.summary     = "Push your markdown files to your Zendesk knowledge base"
+  s.description = "Push your markdown files to your Zendesk knowledge base"
+
+  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.rdoc_options  = ["--charset=UTF-8"]
+  
+  s.add_dependency "boson", "~> 1.0" # Command line
+  s.add_dependency "httparty", "~> 0.8.0" # Zendesk API calls
+  s.add_dependency "redcarpet", "~> 2.1.0" # Markdown to HTML
+  s.add_dependency "awesome_print", "~> 1.0.0" # Colorized output of Zendesk responses
+  s.add_dependency "json_pure", "~> 1.5.1" # The C-gem "json" will still be used instead if it's installed
+
+  s.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,135 @@
+--- !ruby/object:Gem::Specification
+name: zenpush
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Nicolas Fouché
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-03-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: boson
+  requirement: &70100188010080 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70100188010080
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: &70100188008860 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70100188008860
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: &70100187769000 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70100187769000
+- !ruby/object:Gem::Dependency
+  name: awesome_print
+  requirement: &70100187768300 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: *70100187768300
+- !ruby/object:Gem::Dependency
+  name: json_pure
+  requirement: &70100187767540 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.5.1
+  type: :runtime
+  prerelease: false
+  version_requirements: *70100187767540
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &70100187766900 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70100187766900
+description: Push your markdown files to your Zendesk knowledge base
+email:
+- nicolas.fouche@cleverscale.com
+executables:
+- zenpush
+- zp
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- History.txt
+- LICENSE
+- README.markdown
+- Rakefile
+- bin/zenpush
+- bin/zp
+- lib/zenpush.rb
+- lib/zenpush/markdown.rb
+- lib/zenpush/runner.rb
+- lib/zenpush/version.rb
+- lib/zenpush/zendesk.rb
+- zenpush.gemspec
+homepage: https://github.com/cleverscale/zenpush
+licenses: []
+post_install_message: 
+rdoc_options:
+- --charset=UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3134286403274189971
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -3134286403274189971
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.17
+signing_key: 
+specification_version: 3
+summary: Push your markdown files to your Zendesk knowledge base
+test_files: []