zendesk_api 0.0.9

data/.gitignore

@@ -0,0 +1,7 @@
+pkg
+doc
+*swp
+spec/fixtures/cassettes
+spec/fixtures/credentials.yml
+coverage
+.yardoc

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format nested

data/.travis.yml

@@ -0,0 +1,5 @@
+rvm:
+  - ree
+  - 1.9.2
+  - 1.9.3
+  - jruby

data/.yardopts

@@ -0,0 +1 @@
+--no-private --protected lib/**/*.rb - Readme.md

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem "simplecov", :platforms => :ruby_19, :group => :development
+gem "jruby-openssl", :platforms => :jruby
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,59 @@
+PATH
+  remote: .
+  specs:
+    zendesk_api (0.0.9)
+      faraday (>= 0.8.0)
+      faraday_middleware (>= 0.8.7)
+      hashie
+      inflection
+      json
+      mime-types
+      multipart-post
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.2.8)
+    crack (0.3.1)
+    diff-lcs (1.1.3)
+    faraday (0.8.1)
+      multipart-post (~> 1.1)
+    faraday_middleware (0.8.7)
+      faraday (>= 0.7.4, < 0.9)
+    hashie (1.2.0)
+    inflection (1.0.0)
+    json (1.7.3)
+    mime-types (1.19)
+    multi_json (1.3.6)
+    multipart-post (1.1.5)
+    rake (0.9.2.2)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    vcr (2.2.2)
+    webmock (1.8.7)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+    yard (0.8.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  jruby-openssl
+  rake
+  rspec (>= 2.0.0)
+  simplecov
+  vcr
+  webmock
+  yard
+  zendesk_api!

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2012 Zendesk
+
+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/Rakefile

@@ -0,0 +1,49 @@
+require 'rake/testtask'
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+rescue LoadError
+end
+
+if defined?(RSpec)
+  desc "Run specs"
+  RSpec::Core::RakeTask.new(:spec)
+
+  desc "Run live specs"
+  RSpec::Core::RakeTask.new("spec:live") do |t|
+    t.pattern = "live/*_spec.rb"
+  end
+
+  task :clean_live do
+    sh "rm -rf spec/fixtures/cassettes"
+  end
+
+  if RUBY_VERSION =~ /1.9/
+    desc "Find coverage"
+    task "spec:coverage" do
+      ENV["COVERAGE"] = "yes"
+      Rake::Task["spec"].invoke
+    end
+  end
+
+  desc 'Default: run specs.'
+  task :default => :spec
+end
+
+# extracted from https://github.com/grosser/project_template
+rule /^version:bump:.*/ do |t|
+  sh "git status | grep 'nothing to commit'" # ensure we are not dirty
+  index = ['major', 'minor','patch'].index(t.name.split(':').last)
+  file = 'lib/zendesk_api/version.rb'
+
+  version_file = File.read(file)
+  old_version, *version_parts = version_file.match(/(\d+)\.(\d+)\.(\d+)/).to_a
+  version_parts[index] = version_parts[index].to_i + 1
+  version_parts[2] = 0 if index < 2 # remove patch for minor
+  version_parts[1] = 0 if index < 1 # remove minor for major
+  new_version = version_parts * '.'
+  File.open(file,'w'){|f| f.write(version_file.sub(old_version, new_version)) }
+
+  sh "bundle && git add #{file} Gemfile.lock && git commit -m 'bump version to #{new_version}'"
+end

data/Readme.md

@@ -0,0 +1,178 @@
+# Zendesk API Client
+
+## API version support
+
+This client **only** supports Zendesk's v2 API.  Please see our [API documentation](http://developer.zendesk.com) for more information.
+
+## Important Notice
+
+Version 0.0.5 brings with it a change to the top-level namespace. All references to Zendesk should now use ZendeskAPI.
+
+## Installation
+
+Currently
+
+    gem install zendesk_api
+
+will not install this version of the API client. To install this client, either clone this repository and run
+
+    rake install
+
+or add it to a Gemfile like so:
+
+    gem "zendesk_api", :git => "git://github.com/zendesk/zendesk_api_client_rb.git" #, :tag => "vX.X.X"
+
+## Configuration
+
+Configuration is done through a block returning an instance of ZendeskAPI::Client.
+The block is mandatory and if not passed, an ArgumentError will be thrown.
+
+```
+ZendeskAPI::Client.new do |config|
+  # Mandatory:
+
+  config.url = "https://mydesk.zendesk.com/api/v2"
+
+  config.username = "test.user"
+  config.password = "test.password"
+
+  # Optional:
+
+  # Retry uses middleware to notify the user
+  # when hitting the rate limit, sleep automatically,
+  # then retry the request.
+  config.retry = true
+
+  # Logger prints to STDERR by default, to e.g. print to stdout:
+  require 'logger'
+  config.logger = Logger.new(STDOUT)
+
+  # Changes Faraday adapter
+  config.adapter = :patron
+
+  # Merged with the default client options hash
+  config.client_options = { :ssl => false }
+
+  # When getting the error 'hostname does not match the server certificate' 
+  # use the API at https://yoursubdomain.zendesk.com/api/v2
+end
+```
+
+Note: This ZendeskAPI API client only supports basic authentication at the moment.
+
+## Usage
+
+The result of configuration is an instance of ZendeskAPI::Client which can then be used in two different methods.
+
+One way to use the client is to pass it in as an argument to individual classes.
+
+```
+ZendeskAPI::Ticket.new(client, :id => 1, :priority => "urgent") # doesn't actually send a request, must explicitly call #save
+ZendeskAPI::Ticket.create(client, :subject => "Test Ticket", :description => "This is a test", :submitter_id => client.current_user.id, :priority => "urgent")
+ZendeskAPI::Ticket.find(client, :id => 1)
+ZendeskAPI::Ticket.delete(client, :id => 1)
+```
+
+Another way is to use the instance methods under client.
+
+```
+client.tickets.first
+client.tickets.find(:id => 1)
+client.tickets.create(:subject => "Test Ticket", :description => "This is a test", :submitter_id => client.current_user.id, :priority => "urgent")
+client.tickets.delete(:id => 1)
+```
+
+The methods under ZendeskAPI::Client (such as .tickets) return an instance of ZendeskAPI::Collection a lazy-loaded list of that resource.
+Actual requests may not be sent until an explicit ZendeskAPI::Collection#fetch, ZendeskAPI::Collection#to_a, or an applicable methods such
+as #each.
+
+### Pagination
+
+ZendeskAPI::Collections can be paginated:
+
+```
+tickets = client.tickets.page(2).per_page(3)
+next_page = tickets.next
+previous_page = tickets.prev
+```
+
+### Callbacks
+
+Callbacks can be added to the ZendeskAPI::Client instance and will be called (with the response env) after all response middleware on a successful request.
+
+```
+client.insert_callback do |env|
+  puts env[:response_headers]
+end
+```
+
+### Resource management
+
+Individual resources can be created, modified, saved, and destroyed.
+
+```
+ticket = client.tickets[0] # ZendeskAPI::Ticket.find(client, :id => 1)
+ticket.priority = "urgent"
+ticket.attributes # => { "priority" => "urgent" }
+ticket.save # Will PUT => true
+ticket.destroy # => true
+
+ZendeskAPI::Ticket.new(client, { :priority => "urgent" })
+ticket.new_record? # => true
+ticket.save # Will POST
+```
+
+### Special case: Custom resources paths
+
+API endpoints such as tickets/recent or topics/show_many can be accessed through chaining.
+They will too return an instance of ZendeskAPI::Collection.
+
+```
+client.tickets.recent
+client.topics.show_many(:verb => :post, :ids => [1, 2, 3])
+```
+
+### Special Case: Current user
+
+Use either of the following to obtain the current user instance:
+
+```
+client.users.find(:id => 'me')
+client.current_user
+```
+
+### Attaching files
+
+Files can be attached to tickets using either a path or the File class and will
+be automatically uploaded and attached.
+
+```
+ticket = Ticket.new(...)
+ticket.uploads << "img.jpg"
+ticket.uploads << File.new("img.jpg")
+ticket.save
+```
+
+## TODO
+
+* Search class detection
+* Live Testing
+
+## Note on Patches/Pull Requests
+1. Fork the project.
+2. Make your feature addition or bug fix.
+3. Add tests for it. This is important so I don't break it in a future version
+   unintentionally.
+4. Commit, do not mess with rakefile, version, or history. (if you want to have
+   your own version, that is fine but bump version in a commit by itself I can
+   ignore when I pull)
+5. Send me a pull request. Bonus points for topic branches.
+
+## Supported Ruby Versions
+
+Tested with Ruby 1.8.7 and 1.9.3
+[![Build Status](https://secure.travis-ci.org/zendesk/zendesk_api_client_rb.png)](http://travis-ci.org/zendesk/zendesk_api_client_rb)
+
+## Copyright
+
+See [LICENSE](https://github.com/zendesk/zendesk_api_client_rb/blob/master/LICENSE)

data/lib/zendesk_api.rb

@@ -0,0 +1,10 @@
+require "rubygems"
+require "bundler/setup"
+
+require 'zendesk_api/core_ext/modulize'
+require 'zendesk_api/core_ext/snakecase'
+require 'zendesk_api/core_ext/inflection'
+require 'zendesk_api/client'
+
+module ZendeskAPI
+end

data/lib/zendesk_api/actions.rb

@@ -0,0 +1,176 @@
+module ZendeskAPI
+  module Save
+    # If this resource hasn't been deleted, then create or save it.
+    # Executes a POST if it is a {#new_record?}, otherwise a PUT.
+    # Merges returned attributes on success.
+    # @return [Boolean] Success?
+    def save(options={})
+      return false if respond_to?(:destroyed?) && destroyed?
+
+      if new_record?
+        method = :post
+        req_path = path
+      else
+        method = :put
+        req_path = url || path
+      end
+
+      req_path = options[:path] if options[:path]
+
+      save_associations
+
+      response = @client.connection.send(method, req_path) do |req|
+        req.body = if self.class.unnested_params
+          attributes.changes
+        else
+          {self.class.singular_resource_name.to_sym => attributes.changes}
+        end
+      end
+
+      @attributes.replace @attributes.deep_merge(response.body[self.class.singular_resource_name] || {})
+      @attributes.clear_changes
+      true
+    end
+
+    def save!(options={})
+      save(options) || raise("Save failed")
+    end
+
+    def save_associations
+      self.class.associations.each do |association_data|
+        association_name = association_data[:name]
+        next unless send("#{association_name}_used?") && association = send(association_name)
+
+        if association.respond_to?(:save) && (association.is_a?(Collection) || !association.changes.empty?)
+          association.save
+          self.send("#{association_name}=", association) # set id/ids columns
+        end
+
+        if association_data[:inline]
+          attributes[association_name] = (association.is_a?(Collection) ? association.map(&:to_param) : association.to_param)
+        end
+      end
+    end
+  end
+
+  module Read
+    include Rescue
+
+    # Finds a resource by an id and any options passed in.
+    # A custom path to search at can be passed into opts. It defaults to the {DataResource.resource_name} of the class. 
+    # @param [Client] client The {Client} object to be used
+    # @param [Hash] options Any additional GET parameters to be added
+    def find(client, options = {})
+      @client = client # so we can use client.logger in rescue
+
+      raise "No :id given" unless options[:id] || options["id"]
+      association = options.delete(:association) || Association.new(:class => self)
+
+      response = client.connection.get(association.generate_path(options)) do |req|
+        req.params = options
+      end
+
+      new(client, response.body[singular_resource_name])
+    end
+
+    rescue_client_error :find
+  end
+
+  module Create
+    include Save
+
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      include Rescue
+
+      # Create a resource given the attributes passed in.
+      # @param [Client] client The {Client} object to be used
+      # @param [Hash] attributes The attributes to create.
+      def create(client, attributes = {})
+        ZendeskAPI::Client.check_deprecated_namespace_usage attributes, singular_resource_name
+        resource = new(client, attributes)
+        return unless resource.save
+        resource
+      end
+
+      def create!(client, attributes={})
+        c = create(client, attributes)
+        c || raise("Create failed #{self} #{attributes}")
+      end
+
+      rescue_client_error :create
+    end
+  end
+
+  module Destroy
+    include Rescue
+
+    def self.included(klass)
+      klass.extend(ClassMethod)
+    end
+
+    # Has this object been deleted?
+    def destroyed?
+      @destroyed ||= false
+    end
+
+    # If this resource hasn't already been deleted, then do so.
+    # @return [Boolean] Successful?
+    def destroy
+      return false if destroyed? || new_record?
+      @client.connection.delete(url || path)
+      @destroyed = true
+    end
+
+    rescue_client_error :destroy, :with => false
+
+    module ClassMethod
+      include Rescue
+
+      # Deletes a resource given the id passed in.
+      # @param [Client] client The {Client} object to be used
+      # @param [Hash] opts The optional parameters to pass. Defaults to {}
+      def destroy(client, opts = {})
+        @client = client # so we can use client.logger in rescue
+        association = opts.delete(:association) || Association.new(:class => self)
+
+        client.connection.delete(association.generate_path(opts)) do |req|
+          req.params = opts
+        end
+
+        true
+      end
+
+      rescue_client_error :destroy, :with => false
+    end
+  end
+
+  module Update
+    include Rescue
+    include Save
+
+    def self.included(klass)
+      klass.extend(ClassMethod)
+    end
+
+    rescue_client_error :save, :with => false
+
+    module ClassMethod
+      include Rescue
+
+      # Updates  a resource given the id passed in.
+      # @param [Client] client The {Client} object to be used
+      # @param [Hash] attributes The attributes to update. Default to {} 
+      def update(client, attributes = {})
+        ZendeskAPI::Client.check_deprecated_namespace_usage attributes, singular_resource_name
+        resource = new(client, attributes)
+        resource.save
+      end
+
+      rescue_client_error :update, :with => false
+    end
+  end
+end