Merge pull request #479 from zendesk/issue468-search-articles

Issue468 search articles

Author: ecoologic

README.md

@@ -6,30 +6,22 @@
 
 ## Documentation
 
-This Ruby gem is a wrapper around Zendesk's REST API. Please see our [API documentation](https://developer.zendesk.com) for more information.
+This Ruby gem is a generic wrapper around Zendesk's REST API. Follow this README and the [wiki](https://github.com/zendesk/zendesk_api_client_rb/wiki) for how to use it.
 
-Please check out the [wiki](https://github.com/zendesk/zendesk_api_client_rb/wiki), [class documentation](https://www.rubydoc.info/gems/zendesk_api/), and [issues](https://github.com/zendesk/zendesk_api_client_rb/issues) before reporting a bug or asking for help.
+You can interact with all the resources defined in [`resources.rb`](lib/zendesk_api/resources.rb). Basically we have some cleaver code to convert Ruby objects into HTTP requests.
+
+Please refer to our [API documentation](https://developer.zendesk.com) for the specific endpoints and once you understand the mapping between Ruby and the HTTP endpoints you should be able to call any endpoint.
+
+The Yard generated documentation is available in at [RubyDoc](https://www.rubydoc.info/gems/zendesk_api).
+
+Please report any bug in the [Github issues page](https://github.com/zendesk/zendesk_api_client_rb/issues).
 
 ## Product Support
 
 This Ruby gem supports the REST API's for Zendesk Support, Zendesk Guide,
 and Zendesk Talk. It does not yet support other Zendesk products such as
 Zendesk Chat, Zendesk Explore, and Zendesk Sell.
 
-## Important Notices
-
-* Version 0.0.5 brings with it a change to the top-level namespace. All references to `Zendesk` should now use `ZendeskAPI`.
-* Version 0.3.0 changed the license from MIT to Apache Version 2.
-* Version 0.3.2 introduced a regression when side-loading roles on users. This was fixed in 0.3.4.
-* Version 1.0.0 changes the way errors are handled. Please see the [wiki page](https://github.com/zendesk/zendesk_api_client_rb/wiki/Errors) for more info.
-* Version 1.3.0 updates the Faraday dependency to 0.9. Since Faraday did not bump a major version we have not either, but there is no guarantee >= 1.3.0 works with Faraday < 0.9
-* Version 1.3.8 had a bug where attachments were created, but the response was not handled properly
-* Version >= 1.0 and < 1.4.2 had a bug where non application/json response bodies were discarded
-* Version 1.5.0 removed support for Ruby 1.8
-* Version 1.6.0 ZendeskAPI::Voice::CertificationAddress is now ZendeskAPI::Voice::Address
-* Version 1.8.0 no longer considers 1XX and 3XX (except 304) response status codes valid and will raise a NetworkError
-* Version 1.x.x requires you to install `scrub_rb` or `string-scrub` or similar implementation of `String#scrub!` if you're using Ruby 1.9 or 2.0.
-
 ## Installation
 
 The Zendesk API client can be installed using Rubygems or Bundler.
@@ -44,14 +36,15 @@ gem install zendesk_api
 
 Add it to your Gemfile
 
-    gem "zendesk_api"
+```
+gem "zendesk_api"
+```
 
-and follow normal [Bundler](https://bundler.io/) installation and execution procedures.
+Then `bundle` as usual.
 
 ## 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.
 
 ```ruby
 require 'zendesk_api'
@@ -449,9 +442,4 @@ bundle exec rubocop # Runs the lint (use `--fix` for autocorrect)
 
 Copyright 2015-2022 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
-
-https://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.
+See [LICENSE](./LICENSE).

lib/zendesk_api/association.rb

@@ -19,13 +19,8 @@ def class_from_namespace(klass_as_string)
         nil
       end
 
-      # 1.9+ changed default to search ancestors, added flag to disable behavior.
       def module_defines_class?(mod, klass_as_string)
-        if RUBY_VERSION < '1.9'
-          mod.const_defined?(klass_as_string)
-        else
-          mod.const_defined?(klass_as_string, false)
-        end
+        mod.const_defined?(klass_as_string, false)
       end
     end
 
@@ -58,7 +53,6 @@ def generate_path(*args)
 
       namespace = @options[:class].to_s.split("::")
       namespace[-1] = @options[:class].resource_path
-
       # Remove components without path information
       ignorable_namespace_strings.each { |ns| namespace.delete(ns) }
       has_parent = namespace.size > 1 || (options[:with_parent] && @options.parent)

lib/zendesk_api/collection.rb

@@ -1,5 +1,6 @@
 require 'zendesk_api/resource'
 require 'zendesk_api/resources'
+require 'zendesk_api/search'
 
 module ZendeskAPI
   # Represents a collection of resources. Lazily loaded, resources aren't
@@ -28,7 +29,7 @@ class Collection
     # @param [String] resource The resource being collected.
     # @param [Hash] options Any additional options to be passed in.
     def initialize(client, resource, options = {})
-      @client, @resource_class, @resource = client, resource, resource.resource_name
+      @client, @resource_class, @resource = client, resource, resource.resource_path
       @options = SilentMash.new(options)
 
       set_association_from_options
@@ -186,6 +187,7 @@ def fetch!(reload = false)
         return (@resources = [])
       end
       path_query_link = (@query || path)
+
       @response = get_response(path_query_link)
 
       if path_query_link == "search/export"
@@ -253,7 +255,7 @@ def next
       if @options["page"]
         clear_cache
         @options["page"] += 1
-      elsif @query = @next_page
+      elsif (@query = @next_page)
         fetch(true)
       else
         clear_cache
@@ -269,7 +271,7 @@ def prev
       if @options["page"] && @options["page"] > 1
         clear_cache
         @options["page"] -= 1
-      elsif @query = @prev_page
+      elsif (@query = @prev_page)
         fetch(true)
       else
         clear_cache
@@ -398,8 +400,6 @@ def _save(method = :save)
       result
     end
 
-    ## Initialize
-
     def join_special_params
       # some params use comma-joined strings instead of query-based arrays for multiple values
       @options.each do |k, v|
@@ -415,7 +415,6 @@ def set_association_from_options
       association_options = { :path => @options.delete(:path) }
       association_options[:path] ||= @collection_path.join("/") if @collection_path
       @association = @options.delete(:association) || Association.new(association_options.merge(:class => @resource_class))
-
       @collection_path ||= [@resource]
     end
 

lib/zendesk_api/helpers.rb

@@ -2,6 +2,19 @@ module ZendeskAPI
   # @private
   module Helpers
     # From https://github.com/rubyworks/facets/blob/master/lib/core/facets/string/modulize.rb
+    # Converts a string to module name representation.
+    #
+    # This is essentially #camelcase, but it also converts
+    # '/' to '::' which is useful for converting paths to
+    # namespaces.
+    #
+    # Examples
+    #
+    #   "method_name".modulize    #=> "MethodName"
+    #   "method/name".modulize    #=> "Method::Name"
+    #
+    # @param string [string] input, `module/class_name`
+    # @return [string] a string that can become a class, `Module::ClassName`
     def self.modulize_string(string)
       # gsub('__','/').  # why was this ever here?
       string.gsub(/__(.?)/) { "::#{$1.upcase}" }.
@@ -11,6 +24,14 @@ def self.modulize_string(string)
     end
 
     # From https://github.com/rubyworks/facets/blob/master/lib/core/facets/string/snakecase.rb
+    # Underscore a string such that camelcase, dashes and spaces are
+    # replaced by underscores. This is the reverse of {#camelcase},
+    # albeit not an exact inverse.
+    #
+    #   "SnakeCase".snakecase         #=> "snake_case"
+    #   "Snake-Case".snakecase        #=> "snake_case"
+    #   "Snake Case".snakecase        #=> "snake_case"
+    #   "Snake  -  Case".snakecase    #=> "snake_case"
     def self.snakecase_string(string)
       # gsub(/::/, '/').
       string.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').

lib/zendesk_api/resource.rb

@@ -6,7 +6,7 @@
 require 'zendesk_api/verbs'
 
 module ZendeskAPI
-  # Represents a resource that only holds data.
+  # Represents an abstract resource that only holds data.
   class Data
     include Associations
 
@@ -54,6 +54,7 @@ def namespace(namespace)
     # @param [Hash] attributes The optional attributes that describe the resource
     def initialize(client, attributes = {})
       raise "Expected a Hash for attributes, got #{attributes.inspect}" unless attributes.is_a?(Hash)
+
       @association = attributes.delete(:association) || Association.new(:class => self.class)
       @global_params = attributes.delete(:global) || {}
       @client = client
@@ -177,7 +178,7 @@ class DeleteResource < DataResource
     include Destroy
   end
 
-  # Represents a resource that can CRUD (create, read, update, delete).
+  # Represents an abstract resource that can CRUD (create, read, update, delete).
   class Resource < DataResource
     include Read
     include Create

lib/zendesk_api/resources.rb

@@ -277,83 +277,6 @@ class SatisfactionRating < ReadResource
     has Group
   end
 
-  class Search
-    class Result < Data; end
-
-    # Creates a search collection
-    def self.search(client, options = {})
-      unless (%w{query external_id} & options.keys.map(&:to_s)).any?
-        warn "you have not specified a query for this search"
-      end
-
-      ZendeskAPI::Collection.new(client, self, options)
-    end
-
-    # Quack like a Resource
-    # Creates the correct resource class from the result_type passed in
-    def self.new(client, attributes)
-      result_type = attributes["result_type"]
-
-      if result_type
-        result_type = ZendeskAPI::Helpers.modulize_string(result_type)
-        klass = ZendeskAPI.const_get(result_type) rescue nil
-      end
-
-      (klass || Result).new(client, attributes)
-    end
-
-    class << self
-      def resource_name
-        "search"
-      end
-
-      alias :resource_path :resource_name
-
-      def model_key
-        "results"
-      end
-    end
-  end
-
-  # This will use cursor pagination by default
-  class SearchExport
-    class Result < Data; end
-
-    # Creates a search export collection
-    def self.search_export(client, options = {})
-      unless (%w{query external_id} & options.keys.map(&:to_s)).any?
-        warn "you have not specified a query for this search"
-      end
-
-      ZendeskAPI::Collection.new(client, self, options)
-    end
-
-    # Quack like a Resource
-    # Creates the correct resource class from the result_type passed in
-    def self.new(client, attributes)
-      result_type = attributes["result_type"]
-
-      if result_type
-        result_type = ZendeskAPI::Helpers.modulize_string(result_type)
-        klass = ZendeskAPI.const_get(result_type) rescue nil
-      end
-
-      (klass || Result).new(client, attributes)
-    end
-
-    class << self
-      def resource_name
-        "search/export"
-      end
-
-      alias :resource_path :resource_name
-
-      def model_key
-        "results"
-      end
-    end
-  end
-
   class Request < Resource
     class Comment < DataResource
       include Save

lib/zendesk_api/search.rb

@@ -0,0 +1,51 @@
+# `zendesk_api` gem root
+module ZendeskAPI
+  # A rich factory that returns a class for your searches
+  class Search
+    # Creates a search collection
+    def self.search(client, options = {})
+      if (options.keys.map(&:to_s) & %w[query external_id]).empty?
+        warn "you have not specified a query for this search"
+      end
+
+      ZendeskAPI::Collection.new(client, self, options)
+    end
+
+    # Quack like a Resource
+    # Creates the correct resource class from `attributes[:result_type]`
+    def self.new(client, attributes)
+      present_result_type = (attributes[:result_type] || attributes["result_type"]).to_s
+      result_type = ZendeskAPI::Helpers.modulize_string(present_result_type)
+      klass = begin
+                ZendeskAPI.const_get(result_type)
+              rescue NameError
+                Result
+              end
+
+      (klass || Result).new(client, attributes)
+    end
+
+    class Result < Data; end
+
+    class << self
+      def resource_name
+        "search"
+      end
+      alias resource_path resource_name
+
+      def model_key
+        "results"
+      end
+    end
+  end
+
+  # This will use cursor pagination by default
+  class SearchExport < Search
+    class << self
+      def resource_name
+        "search/export"
+      end
+      alias resource_path resource_name
+    end
+  end
+end

spec/live/article_spec.rb

@@ -5,7 +5,7 @@
     expect(article).not_to be_nil
   end
 
-  describe "creating articles withing sections" do
+  describe "creating articles within a section" do
     def valid_attributes
       { :name => "My Article", user_segment_id: nil, permission_group_id: 2801272, title: "My super article" }
     end
@@ -25,5 +25,16 @@ def valid_attributes
     it "can be created" do
       expect(section_article).not_to be_nil
     end
+
+    describe "#search" do
+      before { section_article }
+
+      it "finds the article", :vcr do
+        actual = client.articles.search(query: "What")
+
+        expect(actual.count).to be > 0
+        expect(actual.last.title).to eq("What are these sections and articles doing here?")
+      end
+    end
   end
 end