gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/help_center_topics.rb

@@ -0,0 +1,274 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class HelpCenterTopics within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at When the topic was created
+    # @attr [String] description The description of the topic. By default an empty string
+    # @attr [Integer] follower_count The number of users following the topic
+    # @attr [String] html_url The community url of the topic
+    # @attr [Integer] id Automatically assigned when the topic is created
+    # @attr [String] manageable_by The set of users who can manage this topic; allowed values are "staff", or "managers".
+    # @attr [String] name The name of the topic
+    # @attr [Integer] position The position of the topic relative to other topics in the community
+    # @attr [String] updated_at When the topic was last updated
+    # @attr [Integer] user_segment_id The id of the user segment to which this topic belongs
+    class HelpCenterTopics < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a topic
+      #   # 
+      #   # @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/topics/#create-topic
+      #   #   Zendesk API > Topics > Create Topic
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/topics/#update-topic
+      #   #   Zendesk API > Topics > Update Topic
+      #   # @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_topic = SupportOps::Zendesk::HelpCenterTopics.new
+      #   #   new_topic.name = 'Backups'
+      #   #
+      #   #   new_topic.save!
+      #   #
+      #   #   pp new_topic.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_topic = SupportOps::Zendesk::HelpCenterTopics.get!(122)
+      #   #   existing_topic.name = 'Backups and Restores'
+      #   #
+      #   #   existing_topic.save!
+      #   #
+      #   #   pp existing_topic.name
+      #   #   # => "Backups and Restores"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a topic
+      #   # 
+      #   # @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/topics/#delete-topic
+      #   #   Zendesk API > Topics > Delete Topic
+      #   # @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_topic = SupportOps::Zendesk::HelpCenterTopics.get!(122)
+      #   #   existing_topic.delete!
+      #   def delete!; end
+      define_attributes :created_at, :description, :follower_count, :html_url,
+                        :id, :manageable_by, :name, :position, :updated_at,
+                        :user_segment_id
+      readonly_attributes :created_at, :follower_count, :html_url, :id,
+                          :updated_at
+
+      ##
+      # Lists Help Center topics in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @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/topics/#list-topics
+      #   Zendesk API > Topics > List Topics
+      # @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
+      #
+      #   topcis = SupportOps::Zendesk::HelpCenterTopics.list(limit: 10)
+      #   pp topcis.count
+      #   # => 10
+      #   pp topcis.last.name
+      #   # => "I'm the 10th topic"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("community/topics?#{opts}")
+          body = Oj.load(response.body)
+          array += body['topics'].map { |t| HelpCenterTopics.new(t) }
+          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 topic 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::HelpCenterTopics to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::HelpCenterTopics}
+      # @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
+      #
+      #   topics = SupportOps::Zendesk::HelpCenterTopics.list
+      #   topic = SupportOps::Zendesk::HelpCenterTopics.find_by_name(name: 'Test topic', cache: topics)
+      #   pp topic.name
+      #   # => "Test topic"
+      #   pp topic.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
+          topics = args[:cache]
+        else
+          topics = list
+        end
+        topics.detect { |s| s.name.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Locates a specific topic in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/topics/#show-topic
+      #   Zendesk API > Topics > Show Topic
+      # @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
+      #
+      #   topic = SupportOps::Zendesk::HelpCenterTopics.get(123456)
+      #   pp topic.name
+      #   # => "Test topic"
+      def self.get(object)
+        if object.is_a? HelpCenterTopics
+          HelpCenterTopics.new(id: id).find
+        else
+          HelpCenterTopics.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific topic in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/topics/#show-topic
+      #   Zendesk API > Topics > Show Topic
+      # @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
+      #
+      #   topic = SupportOps::Zendesk::HelpCenterTopics.get!(123456)
+      #   pp topic.name
+      #   # => "Test topic"
+      def self.get!(object)
+        if object.is_a? HelpCenterTopics
+          HelpCenterTopics.new(id: id).find!
+        else
+          HelpCenterTopics.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("community/topics/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['topic']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post('community/topics', { topic: attributes_for_save.compact }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create topic => #{body}" if response.status != 201
+        body['topic']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update topic => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("community/topics/#{self.id}", { topic: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update topic #{self.id} => #{body}" if response.status != 200
+        body['topic']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("community/topics/#{self.id}")
+        raise "Failed to delete topic => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/help_center_user_segments.rb

@@ -0,0 +1,279 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class HelpCenterUserSegments within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Array] added_user_ids The ids of users added specifically to this user segment, regardless of matching tags or other criteria
+    # @attr [Boolean] built_in Whether the user segment is built-in. Built-in user segments cannot be modified
+    # @attr [String] created_at When the user segment was created
+    # @attr [Array] group_ids The ids of the groups that have access
+    # @attr [Integer] id Automatically assigned when the user segment is created
+    # @attr [String] name User segment name (localized to the locale of the current user for built-in user segments)
+    # @attr [Array] or_tags A user must have at least one tag in the list to have access
+    # @attr [Array] organization_ids The ids of the organizations that have access
+    # @attr [Array] tags All the tags a user must have to have access
+    # @attr [String] updated_at When the user segment was last updated
+    # @attr [String] user_type The set of users who can view content
+    # @todo List Sections with User Segment > https://developer.zendesk.com/api-reference/help_center/help-center-api/user_segments/#list-sections-with-user-segment
+    # @todo List Topics with User Segment > https://developer.zendesk.com/api-reference/help_center/help-center-api/user_segments/#list-topics-with-user-segment
+    class HelpCenterUserSegments < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a user segment
+      #   # 
+      #   # @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/user_segments/#create-user-segment
+      #   #   Zendesk API > User Segments > Create User Segment
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/user_segments/#update-user-segment
+      #   #   Zendesk API > User Segments > Update User Segment
+      #   # @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_segment = SupportOps::Zendesk::HelpCenterUserSegments.new
+      #   #   new_segment.name = 'VIP agent'
+      #   #   new_segment.user_type = 'staff'
+      #   #   new_segment.group_ids = [12, 58]
+      #   #   new_segment.tags = ['vip']
+      #   #
+      #   #   new_segment.save!
+      #   #
+      #   #   pp new_segment.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_segment = SupportOps::Zendesk::HelpCenterUserSegments.get!(122)
+      #   #   existing_segment.name = 'VIP agents'
+      #   #
+      #   #   existing_segment.save!
+      #   #
+      #   #   pp existing_segment.name
+      #   #   # => "VIP agents"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a user segment
+      #   # 
+      #   # @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/user_segments/#delete-user-segment
+      #   #   Zendesk API > User Segments > Delete User Segment
+      #   # @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_segment = SupportOps::Zendesk::HelpCenterUserSegments.get!(122)
+      #   #   existing_segment.delete!
+      #   def delete!; end
+      define_attributes :added_user_ids, :built_in, :created_at, :group_ids,
+                        :id, :name, :or_tags, :organization_ids, :tags,
+                        :updated_at, :user_type
+      readonly_attributes :built_in, :created_at, :id, :updated_at
+
+      ##
+      # Lists Help Center user segments in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @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/user_segments/#list-user-segments
+      #   Zendesk API > User Segments > List User Segments
+      # @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
+      #
+      #   segments = SupportOps::Zendesk::HelpCenterUserSegments.list(limit: 10)
+      #   pp segments.count
+      #   # => 3
+      #   pp segments.last.name
+      #   # => "Publishers"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("help_center/user_segments?#{opts}")
+          body = Oj.load(response.body)
+          array += body['user_segments'].map { |u| HelpCenterUserSegments.new(u) }
+          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 user segment 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::HelpCenterUserSegments to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::HelpCenterUserSegments}
+      # @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
+      #
+      #   segments = SupportOps::Zendesk::HelpCenterUserSegments.list
+      #   segment = SupportOps::Zendesk::HelpCenterUserSegments.find_by_name(name: 'Publishers', cache: segments)
+      #   pp segment.name
+      #   # => "Publishers"
+      #   pp segment.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
+          segments = args[:cache]
+        else
+          segments = list
+        end
+        segments.detect { |s| s.name.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Locates a specific user segment in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/user_segments/#show-user-segment
+      #   Zendesk API > User Segments > Show User Segment
+      # @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
+      #
+      #   segment = SupportOps::Zendesk::HelpCenterUserSegments.get(123456)
+      #   pp section.name
+      #   # => "Publishers"
+      def self.get(object)
+        if object.is_a? HelpCenterUserSegments
+          HelpCenterUserSegments.new(id: id).find
+        else
+          HelpCenterUserSegments.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific user segment in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/user_segments/#show-user-segment
+      #   Zendesk API > User Segments > Show User Segment
+      # @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
+      #
+      #   segment = SupportOps::Zendesk::HelpCenterUserSegments.get!(123456)
+      #   pp section.name
+      #   # => "Publishers"
+      def self.get!(object)
+        if object.is_a? HelpCenterUserSegments
+          HelpCenterUserSegments.new(id: id).find!
+        else
+          HelpCenterUserSegments.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("help_center/user_segments/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['user_segment']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("help_center/user_segments", { user_segment: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create user segment => #{body}" if response.status != 201
+        body['user_segment']
+      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("help_center/user_segments/#{self.id}", { user_segment: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update user segment #{self.id} => #{body}" if response.status != 200
+        body['user_segment']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("help_center/user_segments/#{self.id}")
+        raise "Failed to delete user segment #{self.id} => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end