gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/help_center_categories.rb

@@ -0,0 +1,332 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class HelpCenterCategories within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at The time at which the category was created
+    # @attr [String] description The description of the category
+    # @attr [String] html_url The url of this category in Help Center
+    # @attr [Integer] id Automatically assigned when creating categories
+    # @attr [String] locale The locale where the category is displayed
+    # @attr [String] name The name of the category
+    # @attr [Boolean] outdated Whether the category is out of date
+    # @attr [Integer] position The position of this category relative to other categories
+    # @attr [String] source_locale The source (default) locale of the category
+    # @attr [String] updated_at The time at which the category was last updated
+    # @todo Update Category Source Locale > https://developer.zendesk.com/api-reference/help_center/help-center-api/categories/#update-category-source-locale
+    class HelpCenterCategories < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a category
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::HelpCenterSections}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/categories/#create-category
+      #   #   Zendesk API > Categories > Create Category
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/categories/#update-category
+      #   #   Zendesk API > Categories > Update Category
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   new_category = SupportOps::Zendesk::HelpCenterCategories.new
+      #   #   new_category.name = 'Docker'
+      #   #   new_category.locale = 'en-us'
+      #   #   new_category.position = 4
+      #   #   new_category.description = 'This is for Docker articles'
+      #   #
+      #   #   new_category.save!
+      #   #
+      #   #   pp new_category.id
+      #   #   # => 122
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_category = SupportOps::Zendesk::HelpCenterCategories.get!(122)
+      #   #   existing_category.position = existing_category.position + 1
+      #   #
+      #   #   existing_category.save!
+      #   #
+      #   #   pp existing_category.position
+      #   #   # => 5
+      #   def save!; end
+      # @!parse
+      #   # Deletes a category
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#delete!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/categories/#delete-category
+      #   #   Zendesk API > Categories > Delete Category
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_category = SupportOps::Zendesk::HelpCenterCategories.get!(122)
+      #   #   existing_category.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Lists translations
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#translations}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#list-translations
+      #   #   Zendesk API > Translations > Show Translations
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_category = SupportOps::Zendesk::HelpCenterCategories.get!(122)
+      #   #   translations = existing_category.translations
+      #   #   pp translations.count
+      #   #   # => 2
+      #   def parent; end
+      define_attributes :created_at, :description, :html_url, :id, :locale,
+                        :name, :outdated, :position, :source_locale, :updated_at
+      readonly_attributes :created_at, :html_url, :id, :outdated,
+                          :source_locale, :updated_at
+
+      ##
+      # Lists Help Center categories in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param locale [String optional] Filter sections by a specific locale
+      #   @param sort_by [String optional] Possible values are "position",
+      #     "created_at", "updated_at" (defauls to "position")
+      #   @param sort_order [String optional] One of "asc" or "desc"
+      #   @param limit [Integer optional] The limit to the number of sections
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/categories/#list-categories
+      #   Zendesk API > Categories > List Categories
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   categories = SupportOps::Zendesk::HelpCenterCategories.list(limit: 10)
+      #   pp categories.count
+      #   # => 10
+      #   pp categories.last.name
+      #   # => "I'm the 10th category"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        opts += "&sort_by=#{args[:sort_by]}" if args[:sort_by]
+        opts += "&sort_order=#{args[:sort_order]}" if args[:sort_order]
+        locale = if args[:locale].to_s != ''
+                   "#{args[:locale].to_s}/"
+                 else
+                  ''
+                 end
+        url = "help_center/#{locale}categories"
+        loop do
+          response = client.connection.get("#{url}?#{opts}")
+          body = Oj.load(response.body)
+          array += body['categories'].map { |c| HelpCenterCategories.new(c) }
+          break if args[:limit].to_i.positive? && array.count >= args[:limit].to_i
+          break unless body['meta']['has_more']
+
+          opts = body['links']['next'].split('?').last
+        end
+        return array if args[:limit].to_i.zero?
+        
+        array.first(args[:limit].to_i)
+      end
+
+      ##
+      # Locates a category within Zendesk by name. Can utilize a cache for quicker results
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload find_by_name(key: value)
+      #   @param name [String required] The name to search for
+      #   @param cache [Array] An Array of SupportOps::Zendesk::HelpCenterCategories to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::HelpCenterCategories}
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   categories = SupportOps::Zendesk::HelpCenterCategories.list
+      #   category = SupportOps::Zendesk::HelpCenterCategories.find_by_name(name: 'Test category', cache: categories)
+      #   pp category.name
+      #   # => "Test category"
+      #   pp category.id
+      #   # => 123456
+      def self.find_by_name(**args)
+        raise 'You have to provide a name' unless args[:name]
+        if args[:cache]
+          raise 'Provided cache is not an Array' unless args[:cache].is_a? Array
+          categories = args[:cache]
+        else
+          categories = list
+        end
+        categories.detect { |s| s.name.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Locates a specific category in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/categories/#show-category
+      #   Zendesk API > Categories > Show Category
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   category = SupportOps::Zendesk::HelpCenterCategories.get(123456)
+      #   pp category.name
+      #   # => "Test category"
+      def self.get(object)
+        if object.is_a? HelpCenterCategories
+          HelpCenterCategories.new(id: id).find
+        else
+          HelpCenterCategories.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific category in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/categories/#show-category
+      #   Zendesk API > Categories > Show Category
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   category = SupportOps::Zendesk::HelpCenterCategories.get!(123456)
+      #   pp category.name
+      #   # => "Test category"
+      def self.get!(object)
+        if object.is_a? HelpCenterCategories
+          HelpCenterCategories.new(id: id).find!
+        else
+          HelpCenterCategories.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("help_center/categories/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['category']
+      end
+
+      ##
+      # @private
+      def create_record
+        data = {
+          'description' => self.description,
+          'name' => self.name,
+          'position' => self.position,
+          'locale' => self.locale
+        }
+        data.delete('position') if data['position'].nil?
+        response = self.client.connection.post("help_center/categories", { category: data }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create category => #{body}" if response.status != 201
+        body['category']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update category => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        data = {
+          'description' => self.description,
+          'locale' => self.locale,
+          'name' => self.name,
+          'position' => self.position
+        }
+        data.delete('position') if data['position'].nil?
+        response = self.client.connection.put("help_center/categories/#{self.id}", { category: data }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update category #{self.id} => #{body}" if response.status != 200
+        body['category']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("help_center/categories/#{self.id}")
+        raise "Failed to delete category #{self.id} => #{body}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def translations_record
+        Translations.list(self)
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/help_center_content_tags.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class HelpCenterContentTags within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at When the content tag was created
+    # @attr [String] id Automatically assigned when the content tag is created
+    # @attr [String] name The name of the content tag
+    # @attr [String] updated_at When the content tag was last updated
+    # @todo Count Content Tags > https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#count-content-tags
+    # @todo Create Content Tags Job > https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#create-content-tags-job
+    class HelpCenterContentTags < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a content tag
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::HelpCenterUserSegments}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#create-content-tag
+      #   #   Zendesk API > Content Tags > Create Content Tag
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#update-content-tag
+      #   #   Zendesk API > Content Tags > Update Content Tag
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   new_tag = SupportOps::Zendesk::HelpCenterContentTags.new
+      #   #   new_tag.name = 'Runner'
+      #   #
+      #   #   new_tag.save!
+      #   #
+      #   #   pp new_tag.id
+      #   #   # => 122
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_tag = SupportOps::Zendesk::HelpCenterContentTags.get!(122)
+      #   #   existing_tag.name = 'Runners'
+      #   #
+      #   #   existing_tag.save!
+      #   #
+      #   #   pp existing_tag.name
+      #   #   # => "Runners"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a content tag
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#delete!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#delete-content-tag
+      #   #   Zendesk API > Content Tags > Delete Content Tag
+      #   # @example
+      #   #   require 'support_ops_zendesk'
+      #   #
+      #   #   SupportOps::Zendesk::Configuration.configure do |config|
+      #   #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #   #     config.username = 'jason@example.com'
+      #   #     config.token = 'abc123'
+      #   #   end
+      #   #
+      #   #   existing_tag = SupportOps::Zendesk::HelpCenterContentTags.get!(122)
+      #   #   existing_tag.delete!
+      #   def delete!; end
+      define_attributes :created_at, :id, :name, :updated_at
+      readonly_attributes :created_at, :id, :updated_at
+
+      ##
+      # Lists Help Center content tags in the Zendesk system (API docs call it "search")
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param name_prefix [String optional] A filter to use in listing out
+      #     tags; requests using the parameter only show content tags with names
+      #     that start with a specified prefix; if a prefix is not provided or
+      #     is set to an empty string, the endpoint returns all content tags.
+      #   @param limit [Integer optional] The limit to the number of user
+      #     segments returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#search-content-tags
+      #   Zendesk API > Content Tags > Search Content Tags
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   tags = SupportOps::Zendesk::HelpCenterContentTags.list(limit: 10)
+      #   pp tags.count
+      #   # => 10
+      #   pp tags.last.name
+      #   # => "Docker"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=30'
+        opts += "&filter[name_prefix]=#{args[:name_prefix]}" unless args[:name_prefix].to_s == ''
+        loop do
+          response = client.connection.get("guide/content_tags?#{opts}")
+          body = Oj.load(response.body)
+          array += body['records'].map { |r| HelpCenterContentTags.new(r) }
+          break if args[:limit].to_i.positive? && array.count >= args[:limit].to_i
+          break unless body['meta']['has_more']
+
+          opts = body['links']['next'].split('?').last
+        end
+        return array if args[:limit].to_i.zero?
+        
+        array.first(args[:limit].to_i)
+      end
+
+      ##
+      # Locates a specific content tag in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#show-content-tag
+      #   Zendesk API > Content Tags > Show Content Tag
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   tag = SupportOps::Zendesk::HelpCenterContentTags.get(123456)
+      #   pp tag.name
+      #   # => "Geo"
+      def self.get(object)
+        if object.is_a? HelpCenterContentTags
+          HelpCenterContentTags.new(id: id).find
+        else
+          HelpCenterContentTags.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific content tag in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/content_tags/#show-content-tag
+      #   Zendesk API > Content Tags > Show Content Tag
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      #
+      #   tag = SupportOps::Zendesk::HelpCenterContentTags.get!(123456)
+      #   pp tag.name
+      #   # => "Geo"
+      def self.get!(object)
+        if object.is_a? HelpCenterContentTags
+          HelpCenterContentTags.new(id: id).find!
+        else
+          HelpCenterContentTags.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("guide/content_tags/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['content_tag']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("guide/content_tags", { content_tag: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create content tag => #{body}" if response.status != 201
+        body['content_tag']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update user segment => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("guide/content_tags/#{self.id}", { content_tag: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update content tag #{self.id} => #{body}" if response.status != 200
+        body['content_tag']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("guide/content_tags/#{self.id}")
+        raise "Failed to delete content tag #{self.id} => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end