zendesk_apps_tools 0.0.1

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2013 Zendesk
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,117 @@
+# Zendesk Apps Tools
+
+These tools make it easy to develop [Zendesk Apps](http://developer.zendesk.com/documentation/apps/).
+
+# How to use
+
+**STEP 1**: Install 'zat' using [RubyGems](http://rubygems.org/gems/zendesk_apps_tools).
+
+    $ gem install zendesk_apps_tools
+
+**STEP 2**: Create a new app using 'zat'. Here's an example:
+
+    $ zat new
+    Enter this app author's name:
+    John Smith
+    Enter this app author's email:
+    john@example.com
+    Enter a name for this new app:
+    Test App
+    Enter a directory name to save the new app (will create the dir if it dose not exist, default to current dir):
+    /tmp/test-app
+          create  /tmp/test-app
+          create  /tmp/test-app/app.css
+          create  /tmp/test-app/app.js
+          create  /tmp/test-app/assets/logo-small.png
+          create  /tmp/test-app/assets/logo.png
+          create  /tmp/test-app/manifest.json
+          create  /tmp/test-app/templates/layout.hdbs
+          create  /tmp/test-app/translations/en.json
+
+**STEP 3**: Work on the new app by editing/adding the files in /tmp/test-app folder.
+
+**STEP 4**: Validate the app.
+
+    $ zat validate --path /tmp/test-app
+
+**STEP 5**: Preview the app.
+
+To preview a local app, follow these steps:
+
+1) Start zat server
+
+    $ zat server --path /tmp/test-app
+
+    [2013-01-10 16:54:48] INFO  WEBrick 1.3.1
+    [2013-01-10 16:54:48] INFO  ruby 1.9.3 (2012-04-20) [x86_64-darwin12.0.0]
+    == Sinatra/1.3.3 has taken the stage on 4567 for development with backup from WEBrick
+    [2013-01-10 16:54:48] INFO  WEBrick::HTTPServer#start: pid=76568 port=4567
+
+2) In your favorite browser, navigate to a ticket in New Zendesk. The URL should be something like https://subdomain.zendesk.com/agent/#/tickets/1
+
+3) Edit the URL in the address bar to include a 'zat' parameter `?zat=http://localhost:4567/app.js`, then reload the page.
+
+The full url should look something like this: https://subdomain.zendesk.com/agent/?zat=http://localhost:4567/app.js#/tickets/1
+
+The value of 'zat' is the web address to serve the app locally. The port number should match the 'zat server' port number from previous step.
+
+4) Reload the apps by clicking the 'Reload Apps' link. The local app will appear in the app panel.
+(Note: if you are using Chrome, and you see a 'Shield' icon in the address bar, click that icon, and it says 'This page has insecure content', then click 'Load Anyway'. This is because the page is using https, but we are loading the local app using http.)
+
+**STEP 6**: Package the app.
+
+    $ zat package --path /tmp/test-app
+    Enter a zendesk URL that you'd like to install the app (for example: 'http://abc.zendesk.com', default to 'http://support.zendesk.com'):
+
+        validate  OK
+         package  adding app.css
+         package  adding app.js
+         package  adding assets/logo-small.png
+         package  adding assets/logo.png
+         package  adding manifest.json
+         package  adding templates/layout.hdbs
+         package  adding translations/en.json
+         package  created at /tmp/test-app/tmp/app-20130110164906.zip
+
+Now you can [upload the created zip](http://developer.zendesk.com/documentation/apps/uploading.html).
+
+# Features
+
+### Create a Zendesk App
+Create a template for a Zendesk App.
+
+    $ zat new
+
+### Validate an App
+Run a suite of validations against your App:
+
+    $ zat validate
+
+This will run the same validations that run when an App is uploaded to the Zendesk App Market.
+
+### Preview the App
+Run a http server to serve the App locally.
+
+    $ zat server
+
+### Package the app
+Create a zip file that you can [upload](http://developer.zendesk.com/documentation/apps/uploading.html).
+
+    $ zat package
+
+### Clean tmp folder inside an App
+Remove zip files in the tmp folder.
+
+    $ zat clean
+
+# Supported Ruby Versions
+
+Tested with Ruby 1.8.7 and 1.9.3
+
+# Contribution
+
+Improvements are always welcome. To contribute, please submit detailed Pull Requests.
+
+# Issues
+
+Please submit bug reports to <a href="https://support.zendesk.com/requests/new">Zendesk</a>.

data/bin/zat

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+lib_dir = File.expand_path('../../lib', __FILE__)
+$LOAD_PATH << lib_dir unless $LOAD_PATH.include?(lib_dir)
+require 'zendesk_apps_tools'
+ZendeskAppsTools::Command.start

data/features/clean.feature

@@ -0,0 +1,9 @@
+Feature: clean tmp folder inside the zendesk app
+
+  Background: create a new zendesk app package
+    Given an app is created in directory "tmp/aruba"
+    And I run the command "zat package --path tmp/aruba" to package the app
+
+  Scenario: clean tmp folder
+    When I run the command "zat clean --path tmp/aruba" to clean the app
+    Then the zip file in "tmp/aruba/tmp" folder should not exist

data/features/new.feature

@@ -0,0 +1,61 @@
+Feature: create a template for a new zendesk app
+
+  Scenario: create a template for a new zendesk app by running 'zat new' command
+    Given an app directory "tmp/aruba" exists
+    When I run "zat new" command with the following details:
+      | author name  | John Citizen      |
+      | author email | john@example.com  |
+      | app name     | John Test App     |
+
+    Then the app file "tmp/aruba/manifest.json" is created with:
+    """
+{
+  "name": "John Test App",
+  "author": {
+    "name": "John Citizen",
+    "email": "john@example.com"
+  },
+  "defaultLocale": "en",
+  "private": true,
+  "location": "ticket_sidebar",
+  "frameworkVersion": "0.5"
+}
+"""
+    And the app file "tmp/aruba/app.js" is created with:
+    """
+(function() {
+
+  return {
+    events: {
+      'app.activated':'doSomething'
+    },
+
+    doSomething: function() {
+    }
+  };
+
+}());
+"""
+    And the app file "tmp/aruba/templates/layout.hdbs" is created with:
+    """
+<header>
+  <span class="logo"/>
+  <h3>{{setting "name"}}</h3>
+</header>
+<section data-main/>
+<footer>
+  <a href="mailto:{{author.email}}">
+    {{author.name}}
+  </a>
+</footer>
+</div>
+"""
+    And the app file "tmp/aruba/translations/en.json" is created with:
+    """
+{
+  "app": {
+    "description":  "Play the famous zen tunes in your help desk.",
+    "name":         "Buddha Machine"
+  }
+}
+"""

data/features/package.feature

@@ -0,0 +1,15 @@
+Feature: package a zendesk app into a zip file
+
+  Background: create a new zendesk app
+    Given an app is created in directory "tmp/aruba"
+
+  Scenario: package a zendesk app by running 'zat package' command
+    When I run the command "zat package --path tmp/aruba" to package the app
+    And the command output should contain "adding app.js"
+    And the command output should contain "adding assets/logo-small.png"
+    And the command output should contain "adding assets/logo.png"
+    And the command output should contain "adding manifest.json"
+    And the command output should contain "adding templates/layout.hdbs"
+    And the command output should contain "adding translations/en.json"
+    And the command output should contain "created"
+    And the zip file should exist in directory "tmp/aruba/tmp"

data/features/step_definitions/app_steps.rb

@@ -0,0 +1,63 @@
+Given /^an app directory "(.*?)" exists$/ do |app_dir|
+  @app_dir = app_dir
+  FileUtils.rm_rf(@app_dir)
+  FileUtils.mkdir_p(@app_dir)
+end
+
+Given /^an app is created in directory "(.*?)"$/ do |app_dir|
+  steps %Q{
+    Given an app directory "#{app_dir}" exists
+    And I run "zat new" command with the following details:
+      | author name  | John Citizen      |
+      | author email | john@example.com  |
+      | app name     | John Test App     |
+  }
+end
+
+When /^I run "(.*?)" command with the following details:$/ do |cmd, table|
+  IO.popen(cmd, "w+") do |pipe|
+    key = table.rows_hash
+    pipe.puts key["author name"]
+    pipe.puts key["author email"]
+    pipe.puts key["app name"]
+    pipe.puts @app_dir
+    pipe.close_write
+    @output = pipe.readlines
+    @output.each {|line| puts line}
+  end
+end
+
+When /^I run the command "(.*?)" to (validate|package|clean) the app$/ do |cmd, action|
+  IO.popen(cmd, "w+") do |pipe|
+    pipe.puts "\n"
+    pipe.close_write
+    @output = pipe.readlines
+    @output.each {|line| puts line}
+  end
+end
+
+Then /^the app file "(.*?)" is created with:$/ do |file, content|
+  File.read(file).chomp.gsub(' ', '').should == content.gsub(' ', '')
+end
+
+
+Then /^the zip file should exist in directory "(.*?)"$/ do |path|
+  Dir[path + '/app-*.zip'].size.should == 1
+end
+
+Given /^I remove file "(.*?)"$/ do |file|
+  File.delete(file)
+end
+
+Then /^the zip file in "(.*?)" folder should not exist$/ do |path|
+  Dir[path + '/app-*.zip'].size.should == 0
+end
+
+Then /^it should pass the validation$/ do
+  @output.last.should =~ /OK/
+  $?.should == 0
+end
+
+Then /^the command output should contain "(.*?)"$/ do |output|
+  @output.join.should =~ /#{output}/
+end

data/features/support/env.rb

@@ -0,0 +1,5 @@
+require 'aruba/cucumber'
+
+Before do
+  @aruba_timeout_seconds = 15
+end

data/features/validate.feature

@@ -0,0 +1,15 @@
+Feature: validate a zendesk app
+
+  Validate a zendesk app by running 'zat package' command
+
+  Background: create a new zendesk app
+    Given an app is created in directory "tmp/aruba"
+
+  Scenario: valid app
+    When I run the command "zat validate --path tmp/aruba" to validate the app
+    Then it should pass the validation
+
+  Scenario: invalid app (missing manifest.json
+    Given I remove file "tmp/aruba/manifest.json"
+    When I run the command "zat validate --path tmp/aruba" to validate the app
+    Then the command output should contain "Could not find manifest.json"

data/lib/zendesk_apps_tools.rb

@@ -0,0 +1,4 @@
+module ZendeskAppsTools
+  autoload :Command,      'zendesk_apps_tools/command'
+end
+

data/lib/zendesk_apps_tools/command.rb

@@ -0,0 +1,182 @@
+require "thor"
+require 'zip/zip'
+require 'pathname'
+require 'net/http'
+require 'json'
+
+module ZendeskAppsTools
+  require 'zendesk_apps_support'
+
+  class Command < Thor
+
+    DEFAULT_ZENDESK_URL = "http://support.zendesk.com"
+
+    include Thor::Actions
+    include ZendeskAppsSupport
+
+    source_root File.expand_path(File.join(File.dirname(__FILE__), "../.."))
+
+    desc "new", "Generate a new app"
+    def new
+      puts "Enter this app author's name:"
+      @author_name = get_value_from_stdin(/^\w.*$/, "Invalid name, try again:")
+
+      puts "Enter this app author's email:"
+      @author_email = get_value_from_stdin(/^.+@.+\..+$/, "Invalid email, try again:")
+
+      puts "Enter a name for this new app:"
+      @app_name = get_value_from_stdin(/^\w.*$/, "Invalid app name, try again:")
+
+      puts "Enter a directory name to save the new app (will create the dir if it dose not exist, default to current dir):"
+      while @app_dir = $stdin.readline.chomp.strip do
+        @app_dir = './' and break if @app_dir.empty?
+        if !File.exists?(@app_dir)
+          break
+        elsif !File.directory?(@app_dir)
+          puts "Invalid dir, try again:"
+        else
+          break
+        end
+      end
+
+      directory('template', @app_dir)
+    end
+
+    desc "validate", "Validate your app"
+    method_option :path, :default => './', :required => false
+    def validate
+      puts "Enter a zendesk URL that you'd like to install the app (for example: 'http://abc.zendesk.com', default to '#{DEFAULT_ZENDESK_URL}'):"
+      zendesk = get_value_from_stdin(/^http:\/\/\w+\.\w+|^$/, 'Invalid url, try again:')
+      zendesk = DEFAULT_ZENDESK_URL if zendesk.empty?
+      url = URI.parse(zendesk)
+      response = Net::HTTP.start(url.host, url.port) { |http| http.get('/api/v2/apps/framework_versions.json') }
+      version = JSON.parse(response.body, :symbolize_names => true)
+      if ZendeskAppsSupport::AppVersion::CURRENT != version[:current]
+        puts 'This tool is using an out of date Zendesk App Framework. Please upgrade!'
+        exit 1
+      end
+
+      setup_path(options[:path])
+      errors = app_package.validate
+      valid = errors.none?
+
+      if valid
+        say_status 'validate', 'OK'
+      else
+        errors.each do |e|
+          say_status 'validate', e.to_s
+        end
+      end
+
+      @destination_stack.pop if options[:path]
+      exit 1 unless valid
+      true
+    end
+
+    desc "package", "Package your app"
+    method_option :path, :default => './', :required => false
+    def package
+      setup_path(options[:path])
+      archive_path = File.join(tmp_dir, "app-#{Time.now.strftime('%Y%m%d%H%M%S')}.zip")
+
+      return false unless invoke(:validate, [])
+
+      archive_rel_path = relative_to_original_destination_root(archive_path)
+
+      Zip::ZipFile.open(archive_path, 'w') do |zipfile|
+        app_package.files.each do |file|
+          say_status "package", "adding #{file.relative_path}"
+          zipfile.add(file.relative_path, app_dir.join(file.relative_path).to_s)
+        end
+      end
+
+      say_status "package", "created at #{archive_rel_path}"
+      true
+    end
+
+    desc "clean", "Remove app packages in temp folder"
+    method_option :path, :default => './', :required => false
+    def clean
+      setup_path(options[:path])
+
+      return unless File.exists?(Pathname.new(File.join(app_dir, "tmp")).to_s)
+
+      FileUtils.rm(Dir["#{tmp_dir}/app-*.zip"])
+    end
+
+    DEFAULT_SERVER_PATH = "./"
+    DEFAULT_SERVER_PORT = 4567
+
+    desc "server", "Run a http server to serve the local app"
+    method_option :path, :default => DEFAULT_SERVER_PATH, :required => false
+    method_option :port, :default => DEFAULT_SERVER_PORT, :required => false
+    def server
+      setup_path(options[:path])
+      manifest = app_package.manifest_json
+
+      settings = settings_for_parameters(manifest[:parameters])
+
+      require 'zendesk_apps_tools/server'
+      ZendeskAppsTools::Server.tap do |server|
+        server.set :port, options[:port]
+        server.set :root, options[:path]
+        server.set :parameters, settings
+        server.run!
+      end
+    end
+
+    protected
+
+    def get_value_from_stdin(valid_regex, error_msg)
+      while input = $stdin.readline.chomp.strip do
+        unless input =~ valid_regex
+          puts error_msg
+        else
+          break
+        end
+      end
+
+      return input
+    end
+
+    def setup_path(path)
+      @destination_stack << relative_to_original_destination_root(path) unless @destination_stack.last == path
+    end
+
+    def app_dir
+      @app_dir ||= Pathname.new(destination_root)
+    end
+
+    def tmp_dir
+      @tmp_dir ||= Pathname.new(File.join(app_dir, "tmp")).tap do |dir|
+        FileUtils.mkdir_p(dir)
+      end
+    end
+
+    def app_package
+      @app_package ||= Package.new(self.app_dir.to_s)
+    end
+
+    def settings_for_parameters(parameters)
+      return {} if parameters.nil?
+
+      parameters.inject({}) do |settings, param|
+        if param[:required]
+          puts "Enter a value for required parameter '#{param[:name]}':"
+          input = get_value_from_stdin(/\S+/, 'Invalid, try again:')
+        else
+          puts "Enter a value for optional parameter '#{param[:name]}': (press 'Return' to skip)"
+          input = $stdin.readline.chomp.strip
+        end
+
+        unless input.empty?
+          input = (input =~ /^(true|t|yes|y|1)$/i) if param[:type] == 'checkbox'
+          settings[param[:name]] = input
+        end
+
+        settings
+      end
+    end
+  end
+end
+

data/lib/zendesk_apps_tools/server.rb

@@ -0,0 +1,14 @@
+require 'sinatra/base'
+require 'zendesk_apps_support/package'
+
+module ZendeskAppsTools
+  class Server < Sinatra::Base
+    set :public_folder, Proc.new {"#{settings.root}/assets"}
+
+    get '/app.js' do
+      content_type 'text/javascript'
+      ZendeskAppsSupport::Package.new(settings.root).readified_js(nil, 0, "http://localhost:#{settings.port}", settings.parameters)
+    end
+
+  end
+end

data/template/app.js

@@ -0,0 +1,12 @@
+(function() {
+
+  return {
+    events: {
+      'app.activated':'doSomething'
+    },
+
+    doSomething: function() {
+    }
+  };
+
+}());

data/template/manifest.json.tt

@@ -0,0 +1,11 @@
+{
+  "name": "<%= @app_name %>",
+  "author": {
+    "name": "<%= @author_name %>",
+    "email": "<%= @author_email %>"
+  },
+  "defaultLocale": "en",
+  "private": true,
+  "location": "ticket_sidebar",
+  "frameworkVersion": "0.5"
+}

data/template/templates/layout.hdbs

@@ -0,0 +1,11 @@
+<header>
+  <span class="logo"/>
+  <h3>{{setting "name"}}</h3>
+</header>
+<section data-main/>
+<footer>
+  <a href="mailto:{{author.email}}">
+    {{author.name}}
+  </a>
+</footer>
+</div>

data/template/translations/en.json

@@ -0,0 +1,6 @@
+{
+  "app": {
+    "description":  "Play the famous zen tunes in your help desk.",
+    "name":         "Buddha Machine"
+  }
+}

metadata

@@ -0,0 +1,170 @@
+--- !ruby/object:Gem::Specification
+name: zendesk_apps_tools
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- James A. Rosen
+- Kenshiro Nakagawa
+- Shajith Chacko
+- Likun Liu
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.15.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.15.2
+- !ruby/object:Gem::Dependency
+  name: rubyzip
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.1
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: zendesk_apps_support
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.3.2
+- !ruby/object:Gem::Dependency
+  name: cucumber
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: aruba
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Tools to help you develop Zendesk Apps.
+email:
+- dev@zendesk.com
+executables:
+- zat
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/zat
+- lib/zendesk_apps_tools/command.rb
+- lib/zendesk_apps_tools/server.rb
+- lib/zendesk_apps_tools.rb
+- template/app.css
+- template/app.js
+- template/assets/logo-small.png
+- template/assets/logo.png
+- template/manifest.json.tt
+- template/templates/layout.hdbs
+- template/translations/en.json
+- README.md
+- LICENSE
+- features/clean.feature
+- features/new.feature
+- features/package.feature
+- features/step_definitions/app_steps.rb
+- features/support/env.rb
+- features/validate.feature
+homepage: http://github.com/zendesk/zendesk_apps_tools
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Tools to help you develop Zendesk Apps.
+test_files:
+- features/clean.feature
+- features/new.feature
+- features/package.feature
+- features/step_definitions/app_steps.rb
+- features/support/env.rb
+- features/validate.feature