gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/themes.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Themes within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] author The author of the theme. Specified in the theme manifest
+    # @attr [Integer] brand_id The brand id of the theme
+    # @attr [String] created_at The time at which the theme was created
+    # @attr [String] id Automatically assigned when the theme is created
+    # @attr [Boolean] live Whether or not the theme is currently published in Help Center
+    # @attr [String] name The name of the theme
+    # @attr [String] updated_at The time at which the theme was last updated
+    # @attr [String] version The version number of the theme. Specified in the theme manifest
+    # @attr [String] zipfile The zipfile to use for creates and updates
+    # @todo Publish Theme > https://developer.zendesk.com/api-reference/help_center/help-center-api/theming/#publish-theme
+    class Themes < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a theme
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @see SupportOps::Zendesk::Configuration Setting up a client
+      #   # @return [Object] Instance of {SupportOps::Zendesk::Themes}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @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'
+      #   #     config.connection_type = 'upload'
+      #   #   end
+      #   #
+      #   #   new_theme = SupportOps::Zendesk::Themes.new
+      #   #   new_theme.brand_id = 123
+      #   #   new_theme.name = 'New theme'
+      #   #   new_theme.zipfile = SupportOps::Zendesk::Themes.package!('data/new_theme')
+      #   #
+      #   #   new_theme.save!
+      #   #
+      #   #   pp new_theme.id
+      #   #   # => "28a0b408-626a-4bea-88ab-2d48a8078870"
+      #   # @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'
+      #   #     config.connection_type = 'upload'
+      #   #   end
+      #   #
+      #   #   existing_theme = SupportOps::Zendesk::Themes.get!('28a0b408-626a-4bea-88ab-2d48a8078870')
+      #   #   existing_theme.zipfile = SupportOps::Zendesk::Themes.package!('data/modified_theme')
+      #   #
+      #   #   new_theme.save!
+      #   #
+      #   #   pp new_theme.id
+      #   #   # => "28a0b408-626a-4bea-88ab-2d48a8078870"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a theme
+      #   # 
+      #   # @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/theming/#delete-theme
+      #   #   Zendesk API > Themes > Delete Theme
+      #   # @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_theme = SupportOps::Zendesk::Themes.get!('9f3c1c11-32bf-480b-9358-13bbc55d1bfe')
+      #   #   existing_theme.delete!
+      #   def delete!; end
+      define_attributes :author, :brand_id, :created_at, :id, :live, :name,
+                        :updated_at, :version, :zipfile
+      readonly_attributes :author, :brand_id, :created_at, :id, :live, :name,
+                          :updated_at, :version, :zipfile
+
+      ##
+      # Lists themes in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/theming/#list-themes
+      #   Zendesk API > Themes > List Themes
+      # @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
+      #
+      #   targets = SupportOps::Zendesk::Targets.list
+      #   pp targets.count
+      #   # => 3
+      def self.list
+        response = client.connection.get('guide/theming/themes')
+        body = Oj.load(response.body)
+        body['themes'].map { |t| Themes.new(t) }
+      end
+
+      ##
+      # Locates a theme 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::Themes to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::Themes}
+      # @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
+      #
+      #   themes = SupportOps::Zendesk::Themes.list
+      #   theme = SupportOps::Zendesk::Themes.find_by_name(name: 'Backup', cache: themes)
+      #   pp theme.name
+      #   # => "Backup"
+      #   pp theme.id
+      #   # => "9f3c1c11-32bf-480b-9358-13bbc55d1bfe"
+      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
+          themes = args[:cache]
+        else
+          themes = list
+        end
+        themes.detect { |c| c.name.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Locates the live theme within Zendesk
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Object] An instance of {SupportOps::Zendesk::Themes}
+      # @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
+      #
+      #   themes = SupportOps::Zendesk::Themes.list
+      #   theme = SupportOps::Zendesk::Themes.find_by_name(name: 'Backup', cache: themes)
+      #   pp theme.name
+      #   # => "Backup"
+      #   pp theme.id
+      #   # => "9f3c1c11-32bf-480b-9358-13bbc55d1bfe"
+      def self.live
+        themes = list
+        themes.detect { |t| t.live }
+      end
+
+      ##
+      # Locates a specific theme in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/theming/#show-theme
+      #   Zendesk API > Themes > Show Theme
+      # @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
+      #
+      #   theme = SupportOps::Zendesk::Themes.get('9f3c1c11-32bf-480b-9358-13bbc55d1bfe')
+      #   pp theme.live
+      #   # => false
+      def self.get(object)
+        if object.is_a? Themes
+          Themes.new(id: id).find
+        else
+          Themes.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific theme in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/theming/#show-theme
+      #   Zendesk API > Themes > Show Theme
+      # @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
+      #
+      #   theme = SupportOps::Zendesk::Themes.get!('9f3c1c11-32bf-480b-9358-13bbc55d1bfe')
+      #   pp theme.live
+      #   # => false
+      def self.get!(object)
+        if object.is_a? Themes
+          Themes.new(id: id).find!
+        else
+          Themes.new(id: object).find!
+        end
+      end
+
+      ##
+      # Creates a zipfile for the theme
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see SupportOps::Zendesk::Configuration Setting up a client
+      # @param base_folder [String optional] The path to the folder the theme
+      #   files are located in; defaults to './'
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   file = SupportOps::Zendesk::Themes.package!('data/new_app')
+      #   pp file
+      #   # => "data/20250409124436282.zip"
+      def self.package!(base_folder = '')
+        list = %w[ assets manifest.json script.js settings style.css templates thumbnail.png translations ]
+        SupportOps::Packages.create_zipfile!(item_list: list, input_dir: base_folder)
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("guide/theming/themes/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['theme']
+      end
+
+      ##
+      # @private
+      def create_record
+        data = {
+          'attributes' => {
+            'brand_id' => self.brand_id,
+            'format' => 'zip'
+          }
+        }
+        response = self.client.connection.post('guide/theming/jobs/themes/imports', { 'job' => data }.to_json)
+        raise "Failed to create theme (generate job) => #{body}" if response.status != 202
+        job = ThemeJobStatuses.new(body['job'])
+        upload_url = job.data['upload']['url']
+        upload_params = job.data['upload']['parameters']
+        data = upload_params.merge(file: ::Faraday::UploadIO.new(file, 'application/zip'))
+        response = self.client.connection.post(url, data)
+        job.wait_for_completetion
+        response = client.connection.get('guide/theming/themes')
+        body = Oj.load(response.body)
+        body['themes'].detect { |t| t.name == self.name }
+      end
+
+      ##
+      # @private
+      def update_record
+        data = {
+          'attributes' => {
+            'theme_id' => self.id,
+            'replace_settings' => true,
+            'format' => 'zip'
+          }
+        }
+        response = self.client.connection.post('guide/theming/jobs/themes/updates', { 'job' => data }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update theme (generate job) => #{body}" if response.status != 202
+        job = ThemeJobStatuses.new(body['job'])
+        upload_url = job.data['upload']['url']
+        upload_params = job.data['upload']['parameters']
+        data = upload_params.merge(file: ::Faraday::UploadIO.new(file, 'application/zip'))
+        response = self.client.connection.post(url, data)
+        job.wait_for_completetion
+        response = client.connection.get('guide/theming/themes')
+        body = Oj.load(response.body)
+        response = self.client.connection.get("guide/theming/themes/#{self.id}")
+        Oj.load(response.body)['theme']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("guide/theming/themes/#{self.id}")
+        raise "Failed to delete theme => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/ticket_field_options.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class TicketFieldOptions within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Integer] id Automatically assigned upon creation
+    # @attr [String] name The name of the custom field option
+    # @attr [Integer] position Ordering of the field relative to other field options
+    # @attr [String] raw_name The dynamic content placeholder, if present, or the name value, if not
+    # @attr [String] value The corresponding tag and backend value for the field option
+    # @todo Show a Ticket Field Option => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#show-ticket-field-option
+    class TicketFieldOptions < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates or updates a ticket field option
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#create_or_update!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#create-or-update-ticket-field-option
+      #   #   Zendesk API > Ticket Fields > Create Or Update Ticket Field Option
+      #   # @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_option = SupportOps::Zendesk::TicketFieldOptions.new
+      #   #   new_option.name = 'Linux'
+      #   #   new_option.value = 'system_linux'
+      #   #   new_option.ticket_field_id = 123456
+      #   #
+      #   #   new_option.create_or_update!
+      #   #
+      #   #   pp new_option.name
+      #   #   # => "Linux"
+      #   def create_or_update!; end
+      # @!parse
+      #   # Deletes a ticket field option
+      #   # 
+      #   # @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/tickets/ticket_fields/#delete-ticket-field-option
+      #   #   Zendesk API > Ticket Fields > Delete Ticket Field Option
+      #   # @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_field = SupportOps::Zendesk::TicketFieldOptions.get!(23409462)
+      #   #   existing_option = existing_field.field_options.last
+      #   #   existing_option.delete!
+      #   def delete!; end
+      define_attributes :id, :name, :position, :raw_name, :value,
+                        :ticket_field_id
+      readonly_attributes :id, :ticket_field_id
+
+      ##
+      # Lists ticket field options in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param ticket_field_id [Integer required] The ticket field to find the options for
+      #   @param limit [Integer optional] The limit to the number of ticket
+      #     field options returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#list-ticket-field-options
+      #   Zendesk API > Ticket Fields > List Ticket Field Options
+      # @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
+      #
+      #   field = SupportOps::Zendesk::TicketFields.get!(50)
+      #   options = SupportOps::Zendesk::TicketFields.list(ticket_field_id: field.id)
+      #   pp options.count
+      #   # => 5
+      #   pp options.last.value
+      #   # => "other_or_misc"
+      def self.list(**args)
+        raise 'You must provide a ticket value' unless args[:ticket_field_id]
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("ticket_fields/#{args[:ticket_field_id]}/options?#{opts}")
+          body = Oj.load(response.body)
+          body['custom_field_options'].each do |c|
+            c['ticket_field_id'] = args[:ticket_field_id]
+          end
+          array += body['custom_field_options'].map { |c| TicketFieldOptions.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
+
+      private
+
+      ##
+      # @private
+      def create_or_update_record
+        data = {
+          'id' => self.id,
+          'name' => self.name,
+          'value' => self.value,
+          'position' => self.position,
+          'raw_name' => self.raw_name
+        }.compact
+        response = self.client.connection.post("ticket_fields/#{self.ticket_field_id}/options", { custom_field_option: data }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create or update ticket field option => #{body}" unless [200, 201].include?(response.status)
+        body['custom_field_option']['ticket_field_id'] = self.ticket_field_id
+        body['custom_field_option']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = client.connection.delete("ticket_fields/#{self.ticket_field_id}/options/#{self.id}")
+        raise "Failed to delete ticket field option #{self.id} => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end