gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/translations.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Translations within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] body HTML body of the translation. Empty by default
+    # @attr [String] created_at The time at which the translation was created
+    # @attr [Integer] created_by_id The id of the user who created the translation
+    # @attr [Boolean] draft True if the translation is a draft; false otherwise; false by default
+    # @attr [String] html_url The url of the translation in Help Center
+    # @attr [Integer] id Automatically assigned when a translation is created
+    # @attr [String] locale The locale of the translation
+    # @attr [Boolean] outdated True if the translation is outdated; false otherwise; false by default
+    # @attr [Integer] source_id The id of the item that has this translation
+    # @attr [String] source_type The type of the item that has this translation; can be "article", "section", or "category".
+    # @attr [String] title The title of the translation
+    # @attr [String] updated_at The time at which the translation was last updated
+    # @attr [Integer] updated_by_id The id of the user who last updated the translation
+    class Translations < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a translation
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::Articles},
+      #   #   {SupportOps::Zendesk::HelpCenterCategories}, or
+      #   #   {SupportOps::Zendesk::HelpCenterSections}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#create-translation
+      #   #   Zendesk API > Translations > Create Translation
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#update-translation
+      #   #   Zendesk API > Translations > Update Translation
+      #   # @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
+      #   #
+      #   #   object = SupportOps::Zendesk::Articles.list.last
+      #   #   new_translation = SupportOps::Zendesk::Translations.new
+      #   #   new_translation.locale = 'en-us'
+      #   #   new_translation.title = 'Super Hero Tricks'
+      #   #   new_translation.body = 'This article contains a collection of Super Hero tricks'
+      #   #   new_translation.source_id = object.id
+      #   #   new_translation.source_type = 'article'
+      #   #
+      #   #   new_translation.save!
+      #   #
+      #   #   pp new_translation.id
+      #   #   # => 23409462
+      #   # @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
+      #   #
+      #   #   object = SupportOps::Zendesk::Articles.list.last
+      #   #   existing_translation = SupportOps::Zendesk::Translations.get!(object, 'en-us')
+      #   #   existing_translation.title = 'Super Hero Tricks (be like All Might)'
+      #   #
+      #   #   existing_translation.save!
+      #   #
+      #   #   pp existing_trigger.title
+      #   #   # => "Super Hero Tricks (be like All Might)"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a translation
+      #   # 
+      #   # @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/translations/#delete-translation
+      #   #   Zendesk API > Translations > Delete Translation
+      #   # @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
+      #   #
+      #   #   object = SupportOps::Zendesk::Articles.list.last
+      #   #   existing_translation = SupportOps::Zendesk::Translations.get!(object, 'en-us')
+      #   #   existing_translation.delete!
+      #   def delete!; end
+      define_attributes :body, :created_at, :created_by_id, :draft, :html_url,
+                        :id, :locale, :outdated, :source_id, :source_type,
+                        :title, :updated_at, :updated_by_id
+      readonly_attributes :created_at, :created_by_id, :html_url, :id,
+                          :source_id, :source_type, :updated_at, :updated_by_id
+
+      ##
+      # Lists translations in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param object [Object] An existing {SupportOps::Zendesk::Articles},
+      #   {SupportOps::Zendesk::HelpCenterCategories}, or
+      #   {SupportOps::Zendesk::HelpCenterSections}
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#list-translations
+      #   Zendesk API > Translations > List Translations
+      # @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
+      #
+      #   object = SupportOps::Zendesk::HelpCenterSections.list.first
+      #   translations = SupportOps::Zendesk::Translations.list(object)
+      #   pp translations.count
+      #   # => 2
+      def self.list(object)
+        if object.is_a? HelpCenterCategories
+          response = client.connection.get("help_center/categories/#{object.id}/translations")
+        elsif object.is_a? HelpCenterSections
+          response = client.connection.get("help_center/sections/#{object.id}/translations")
+        elsif object.is_a? Articles
+          response = client.connection.get("help_center/articles/#{object.id}/translations")
+        else
+          raise "Unknown object for a translation: #{object.class}"
+        end
+        body = Oj.load(response.body)
+        body['translations'].map { |t| Translations.new(t) }
+      end
+
+      ##
+      # Lists missing translation locales in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param object [Object] An existing {SupportOps::Zendesk::Articles},
+      #   {SupportOps::Zendesk::HelpCenterCategories}, or
+      #   {SupportOps::Zendesk::HelpCenterSections}
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#list-missing-translations
+      #   Zendesk API > Translations > List Missing Translations
+      # @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
+      #
+      #   object = SupportOps::Zendesk::Articles.list.last
+      #   locales = SupportOps::Zendesk::Translations.list_missing(object)
+      #   pp locales
+      #   # => ["da-dk"]
+      def self.list_missing(object)
+        if object.is_a? HelpCenterCategories
+          response = client.connection.get("help_center/categories/#{object.id}/translations/missing")
+        elsif object.is_a? HelpCenterSections
+          response = client.connection.get("help_center/sections/#{object.id}/translations/missing")
+        elsif object.is_a? Articles
+          response = client.connection.get("help_center/articles/#{object.id}/translations/missing")
+        else
+          raise "Unknown object for a translation: #{object.class}"
+        end
+        body = Oj.load(response.body)
+        body['locales']
+      end
+
+      ##
+      # Locates a specific translation in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#show-translation
+      #   Zendesk API > Translations > Show Translation
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @param object [Object] An existing {SupportOps::Zendesk::Articles},
+      #   {SupportOps::Zendesk::HelpCenterCategories}, or
+      #   {SupportOps::Zendesk::HelpCenterSections}
+      # @param locale [String] The locale to fetch the translation for
+      # @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
+      #
+      #   object = SupportOps::Zendesk::Articles.list.last
+      #   translation = SupportOps::Zendesk::Translations.get(object, 'en-us')
+      #   pp translation.title
+      #   # => "Support Pages"
+      def self.get(object, locale)
+        type = if object.is_a? HelpCenterCategories
+                 'category'
+               elsif object.is_a? HelpCenterSections
+                 'section'
+               elsif object.is_a? Articles
+                 'article'
+               end
+        Translations.new(
+          locale: locale,
+          source_type: type,
+          source_id: object.id
+        ).find
+      end
+
+      ##
+      # Locates a specific translation in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/translations/#show-translation
+      #   Zendesk API > Translations > Show Translation
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @param object [Object] An existing {SupportOps::Zendesk::Articles},
+      #   {SupportOps::Zendesk::HelpCenterCategories}, or
+      #   {SupportOps::Zendesk::HelpCenterSections}
+      # @param locale [String] The locale to fetch the translation for
+      # @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
+      #
+      #   object = SupportOps::Zendesk::Articles.list.last
+      #   translation = SupportOps::Zendesk::Translations.get!(object, 'en-us')
+      #   pp translation.title
+      #   # => "Support Pages"
+      def self.get!(object, locale)
+        type = if object.is_a? HelpCenterCategories
+                 'category'
+               elsif object.is_a? HelpCenterSections
+                 'section'
+               elsif object.is_a? Articles
+                 'article'
+               end
+        Translations.new(
+          locale: locale,
+          source_type: type,
+          source_id: object.id
+        ).find!
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("help_center/#{self.source_type.pluralize}/#{self.source_id}/translations/#{self.locale}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['translation']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("help_center/#{self.source_type.pluralize.downcase}/#{self.source_id}/translations", { translation: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create translation => #{body}" if response.status != 201
+        body['translation']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update trigger => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("help_center/#{self.source_type.pluralize.downcase}/#{self.source_id}/translations/#{self.locale}", { translation: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update translation #{self.source_type.pluralize}/#{self.source_id} #{self.id} => #{body}" if response.status != 200
+        body['translation']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("help_center/translations/#{self.id}")
+        raise "Failed to delete translation => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/trigger_categories.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class TriggerCategories within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at When this record was created
+    # @attr [Integer] id Automatically assigned when the trigger category is created
+    # @attr [String] name Trigger cagegory name
+    # @attr [Integer] position The position of the trigger category
+    # @attr [String] updated_at When this record was updated
+    # @todo Create Batch Job for Ticket Trigger Categories => https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#create-batch-job-for-ticket-trigger-categories
+    class TriggerCategories < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a trigger category
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::Users}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#create-ticket-trigger-category
+      #   #   Zendesk API > Ticket Trigger Categories > Create Ticket Trigger Category
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#update-ticket-trigger-category
+      #   #   Zendesk API > Ticket Trigger Categories > Update Ticket Trigger 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::TriggerCategories.new
+      #   #   new_category.name = 'Misc'
+      #   #   new_category.position = 19
+      #   #
+      #   #   new_category.save!
+      #   #
+      #   #   pp new_category.id
+      #   #   # => 10001
+      #   # @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::TriggerCategories.get!(10001)
+      #   #   existing_category.name = 'Misc/Etc.'
+      #   #
+      #   #   existing_category.save!
+      #   #
+      #   #   pp existing_category.name
+      #   #   # => "Misc/Etc."
+      #   def save!; end
+      # @!parse
+      #   # Deletes a trigger 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/ticketing/business-rules/trigger_categories/#delete-ticket-trigger-category
+      #   #   Zendesk API > Ticket Trigger Categories > Delete Ticket Trigger 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::TriggerCategories.get!(10001)
+      #   #   existing_category.delete!
+      #   def delete!; end
+      define_attributes :created_at, :id, :name, :position, :updated_at
+      readonly_attributes :created_at, :id, :updated_at
+
+      ##
+      # Lists trigger categories in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param sort [String optional] Sort parameters. Allowed values are
+      #     "position", "-position", "name", "-name", "created_at",
+      #     "-created_at", "updated_at", or "-updated_at".
+      #   @param limit [Integer optional] The limit to the number of trigger
+      #     categories returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#list-ticket-trigger-categories
+      #   Zendesk API > Ticket Trigger Categories > List Ticket Trigger 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::TriggerCategories.list(limit: 25)
+      #   pp categories.count
+      #   # => 18
+      #   pp categories.last.name
+      #   # => "2FA"
+      def self.list(**args)
+        args[:sort] = nil unless args[:sort]
+        args[:limit] = 0 unless args[:limit]
+        params = ''
+        params += "sort=#{args[:sort]}&" unless args[:sort].nil?
+        categories = []
+        opts = "#{params}page[size]=100"
+        loop do
+          response = client.connection.get("trigger_categories?#{opts}")
+          body = Oj.load(response.body)
+          categories += body['trigger_categories'].map { |t| TriggerCategories.new(t) }
+          break if args[:limit].to_i.positive? && categories.count >= args[:limit].to_i
+          break unless body['meta']['has_more']
+
+          opts = body['links']['next'].split('?').last
+        end
+        return categories if args[:limit].to_i.zero?
+        
+        categories.first(args[:limit].to_i)
+      end
+
+      ##
+      # Locates a trigger categories 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::TriggerCategories to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::TriggerCategories}
+      # @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::TriggerCategories.list
+      #   category = SupportOps::Zendesk::TriggerCategories.find_by_name(name: '2FA', cache: categories)
+      #   pp category.name
+      #   # => "2FA"
+      #   pp category.id
+      #   # => 18451777063964
+      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 { |c| c.name.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Locates a specific trigger category in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#show-ticket-trigger-category
+      #   Zendesk API > Ticket Trigger Categories > Show Ticket Trigger 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::TriggerCategories.get(18451777063964)
+      #   pp category.name
+      #   # => "2FA"
+      def self.get(object)
+        if object.is_a? TriggerCategories
+          TriggerCategories.new(id: id).find
+        else
+          TriggerCategories.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific trigger category in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/business-rules/trigger_categories/#show-ticket-trigger-category
+      #   Zendesk API > Ticket Trigger Categories > Show Ticket Trigger 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::TriggerCategories.get!(18451777063964)
+      #   pp category.name
+      #   # => "2FA"
+      def self.get!(object)
+        if object.is_a? TriggerCategories
+          TriggerCategories.new(id: id).find!
+        else
+          TriggerCategories.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("trigger_categories/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['trigger_category']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("trigger_categories", { trigger_category: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create trigger category => #{body['errors']}" if response.status != 201
+        body['trigger_category']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update user => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("trigger_categories/#{self.id}", { trigger_category: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update trigger category #{self.id} => #{body['errors']}" if response.status != 200
+        body['trigger_category']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("trigger_categories/#{self.id}")
+        body = Oj.load(response.body)
+        raise "Failed to delete trigger category => #{body['errors']}" if response.status != 204
+        true
+      end
+    end
+  end
+end