gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/articles.rb

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Articles within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Integer] author_id The id of the user who wrote the article (set to the user who made the request on create by default)
+    # @attr [String] body HTML body of the article. Unsafe tags and attributes may be removed before display
+    # @attr [Boolean] comments_disabled True if comments are disabled; false otherwise
+    # @attr [Array] content_tag_ids The list of content tags attached to the article
+    # @attr [String] created_at The time the article was created
+    # @attr [Boolean] draft True if the translation for the current locale is a draft; false otherwise; false by default
+    # @attr [String] edited_at The time the article was last edited in its displayed locale
+    # @attr [String] html_url The url of the article in Help Center
+    # @attr [Integer] id Automatically assigned when the article is created
+    # @attr [Array] label_names An array of label names associated with this article; by default no label names are used
+    # @attr [String] locale The locale that the article is being displayed in
+    # @attr [Array] outdated_locales Locales in which the article was marked as outdated
+    # @attr [Integer] permission_group_id The id of the permission group which defines who can edit and publish this article
+    # @attr [Integer] position The position of this article in the article list
+    # @attr [Boolean] promoted True if this article is promoted; false otherwise; false by default
+    # @attr [Integer] section_id The id of the section to which this article belongs
+    # @attr [String] source_locale The source (default) locale of the article
+    # @attr [String] title The title of the article
+    # @attr [String] updated_at The time the article was last updated
+    # @attr [Integer] user_segment_id The id of the user segment which defines who can see this article; set to null to make it accessible to everyone; either user_segment_id or user_segment_ids must be specified
+    # @attr [Array] user_segment_ids List of user segment ids which define who can view this article; set to an empty list to make it accessible to everyone
+    # @attr [Integer] vote_count The total number of upvotes and downvotes
+    # @attr [Integer] vote_sum The sum of upvotes (+1) and downvotes (-1), which may be positive or negative
+    # @todo Update Article Source Locale > https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/#update-article-source-locale
+    # @todo Associate Attachments in Bulk to Article > https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/#associate-attachments-in-bulk-to-article
+    class Articles < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates an article
+      #   # 
+      #   # @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/articles/#create-article
+      #   #   Zendesk API > Articles > Create Article
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/#update-article
+      #   #   Zendesk API > Articles > Update Article
+      #   # @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_article = SupportOps::Zendesk::Articles.new
+      #   #   new_article.body = 'Use a tripod'
+      #   #   new_article.locale = 'en-us'
+      #   #   new_article.permission_group_id = 56
+      #   #   new_article.title = 'Taking photos in low light'
+      #   #   new_article.user_segment_id = 123
+      #   #   new_article.section_id = 123456
+      #   #
+      #   #   new_article.save!
+      #   #
+      #   #   pp new_article.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_article = SupportOps::Zendesk::Articles.get!(122)
+      #   #   existing_article.label_names = ['photo', 'tripod']
+      #   #
+      #   #   existing_article.save!
+      #   #
+      #   #   pp existing_article.label_names
+      #   #   # => ["photo", "tripod"]
+      #   def save!; end
+      # @!parse
+      #   # Deletes (archives) an article
+      #   # 
+      #   # @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/articles/#archive-article
+      #   #   Zendesk API > Articles > Archive Article
+      #   # @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_article = SupportOps::Zendesk::Articles.get!(122)
+      #   #   existing_article.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_article = SupportOps::Zendesk::Articles.get!(122)
+      #   #   translations = existing_article.translations
+      #   #   pp translations.count
+      #   #   # => 2
+      #   def parent; end
+      define_attributes :author_id, :body, :comments_disabled, :content_tag_ids,
+                        :created_at, :draft, :edited_at, :html_url, :id,
+                        :label_names, :locale, :outdated_locales,
+                        :permission_group_id, :position, :promoted, :section_id,
+                        :source_locale, :title, :updated_at, :user_segment_id,
+                        :user_segment_ids, :vote_count, :vote_sum
+      readonly_attributes :created_at, :edited_at, :html_url, :id,
+                          :outdated_locales, :source_locale, :updated_at,
+                          :vote_count, :vote_sum
+
+      ##
+      # Lists articles 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 articles
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/#list-articles
+      #   Zendesk API > Articles > List Articles
+      # @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
+      #
+      #   articles = SupportOps::Zendesk::Articles.list(limit: 10)
+      #   pp articles.count
+      #   # => 10
+      #   pp articles.last.title
+      #   # => "I'm the 10th article"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        array = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("help_center/articles?#{opts}")
+          body = Oj.load(response.body)
+          array += body['articles'].map { |a| Articles.new(a) }
+          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 an article within Zendesk by title. Can utilize a cache for quicker results
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload find_by_name(key: value)
+      #   @param title [String required] The title to search for
+      #   @param cache [Array] An Array of SupportOps::Zendesk::Articles to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::Articles}
+      # @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
+      #
+      #   articles = SupportOps::Zendesk::Articles.list
+      #   article = SupportOps::Zendesk::Articles.find_by_title(title: 'Test Article', cache: articles)
+      #   pp article.title
+      #   # => "Test Article"
+      #   pp article.id
+      #   # => 123456
+      def self.find_by_title(**args)
+        raise 'You have to provide a title' unless args[:title]
+        if args[:cache]
+          raise 'Provided cache is not an Array' unless args[:cache].is_a? Array
+          articles = args[:cache]
+        else
+          articles = list
+        end
+        articles.detect { |s| s.title.downcase == args[:title].to_s.downcase }
+      end
+
+      ##
+      # Locates a specific article in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/#show-article
+      #   Zendesk API > Articles > Show Article
+      # @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
+      #
+      #   article = SupportOps::Zendesk::Articles.get(123456)
+      #   pp article.title
+      #   # => "Test article"
+      def self.get(object)
+        if object.is_a? Articles
+          Articles.new(id: id).find
+        else
+          Articles.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific article in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/#show-article
+      #   Zendesk API > Articles > Show Article
+      # @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
+      #
+      #   article = SupportOps::Zendesk::Articles.get!(123456)
+      #   pp article.title
+      #   # => "Test article"
+      def self.get!(object)
+        if object.is_a? Articles
+          Articles.new(id: id).find!
+        else
+          Articles.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("help_center/articles//#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['article']
+      end
+
+      ##
+      # @private
+      def create_record
+        data = {
+          'body' => self.body,
+          'locale' => self.locale,
+          'permission_group_id' => self.permission_group_id,
+          'title' => self.title
+        }
+        data['user_segment_id'] = self.user_segment_id unless self.user_segment_id.nil?
+        data['user_segment_ids'] = self.user_segment_ids unless self.user_segment_ids.nil?
+        data['author_id'] = self.author_id unless self.author_id.nil?
+        data['comments_disabled'] = self.comments_disabled unless self.comments_disabled.nil?
+        data['content_tag_ids'] = self.content_tag_ids unless self.content_tag_ids.nil?
+        data['draft'] = self.draft unless self.draft.nil?
+        data['label_names'] = self.label_names unless self.label_names.nil?
+        data['position'] = self.position unless self.position.nil?
+        data['promoted'] = self.promoted unless self.promoted.nil?
+        data['source_locale'] = self.source_locale unless self.source_locale.nil?
+        unless data.keys.include?('user_segment_id') || data.keys.include?('user_segment_ids')
+          data['user_segment_id'] = nil
+        end
+        response = self.client.connection.post("help_center/sections/#{self.section_id}/articles", { article: data }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create article => #{body}" if response.status != 201
+        body['article']
+      end
+
+      ##
+      # @private
+      def update_record
+        data = {
+          'permission_group_id' => self.permission_group_id
+        }
+        data['user_segment_id'] = self.user_segment_id unless self.user_segment_id.nil?
+        data['user_segment_ids'] = self.user_segment_ids unless self.user_segment_ids.nil?
+        data['author_id'] = self.author_id unless self.author_id.nil?
+        data['comments_disabled'] = self.comments_disabled unless self.comments_disabled.nil?
+        data['content_tag_ids'] = self.content_tag_ids unless self.content_tag_ids.nil?
+        data['draft'] = self.draft unless self.draft.nil?
+        data['label_names'] = self.label_names unless self.label_names.nil?
+        data['position'] = self.position unless self.position.nil?
+        data['promoted'] = self.promoted unless self.promoted.nil?
+        data['source_locale'] = self.source_locale unless self.source_locale.nil?
+        unless data.keys.include?('user_segment_id') || data.keys.include?('user_segment_ids')
+          data['user_segment_id'] = nil
+        end
+        raise "Failed to update article => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("help_center/articles", { article: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update article #{self.id} => #{body}" if response.status != 200
+        body['article']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("help_center/articles/#{self.id}")
+        raise "Failed to delete article #{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/audit_logs.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class AuditLogs within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] action Type of change made, possible values are "create", "destroy", "exported", "login", and "update"
+    # @attr [String] action_label Localized string of action field
+    # @attr [Integer] actor_id id of the user or system that initiated the change
+    # @attr [String] actor_name Name of the user or system that initiated the change
+    # @attr [String] change_description The description of the change that occurred
+    # @attr [String] created_at The time the audit got created
+    # @attr [Integer] id The id automatically assigned upon creation
+    # @attr [String] ip_address The IP address of the user doing the audit
+    # @attr [Integer] source_id The id of the item being audited
+    # @attr [String] source_label The name of the item being audited
+    # @attr [String] source_type Item type being audited; typically describes the system where the change was initiated; possible values vary based on your account's Zendesk products and activity; common values include "apitoken", "rule", "ticket", "user", and "zendesk/app_market/app";  The "rule" value is used for automations, macros, triggers, views, and other automated business rules
+    # @todo Export Aduit Logs => https://developer.zendesk.com/api-reference/ticketing/account-configuration/audit_logs/#export-audit-logs
+    class AuditLogs < SupportOps::Zendesk::Base
+      define_attributes :action, :action_label, :actor_id, :actor_name,
+                        :change_description, :created_at, :id, :ip_address,
+                        :source_id, :source_label, :source_type
+      readonly_attributes :action, :action_label, :actor_id, :actor_name,
+                          :change_description, :created_at, :id, :ip_address,
+                          :source_id, :source_label, :source_type
+
+      ##
+      # Lists asudit logs in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload list(key: value)
+      #   @param action [String optional] Filter audit logs by the action
+      #   @param actor_id [Integer optional] Filter audit logs by the actor id
+      #   @param start_time [String optional] Filter audit logs by the time of
+      #     creation. This specifies the time to look after. Must be paired with
+      #     end_time. If the other is missing this will be ignored.
+      #   @param end_time [String optional] ilter audit logs by the time of
+      #     creation. This specifies the time to look before. Must be paired with
+      #     start_time. If the other is missing this will be ignored.
+      #   @param ip_address [String optional] TBD
+      #   @param source_id [Integer optional] TBD
+      #   @param source_type [TBD optional] TBD
+      #   @param limit [Integer optional] The limit to the number of audit logs
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/audit_logs/#list-audit-logs
+      #   Zendesk API > Audit Logs > List Audit Logs
+      # @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
+      #
+      #   logs = SupportOps::Zendesk::AuditLogs.list(limit: 10)
+      #   pp logs.count
+      #   # => 10
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        sort_order = (args[:sort_order] == 'desc' ? '-' : '')
+        array = []
+        opts = 'page[size]=100'
+        opts += "&filter[action]=#{args[:action]}" if args[:action]
+        opts += "&filter[actor_id]=#{args[:actor_id]}" if args[:actor_id]
+        opts += "&filter[ip_address]=#{args[:ip_address]}" if args[:ip_address]
+        opts += "&filter[source_id]=#{args[:source_id]}" if args[:source_id]
+        opts += "&filter[source_type]=#{args[:source_type]}" if args[:source_type]
+        if args[:start_time] && args[:end_time]
+          opts += "&filter[created_at]=#{args[:start_time]}"
+          opts += "&filter[created_at]=#{args[:end_time]}"
+        end
+        loop do
+          response = client.connection.get("audit_logs?#{opts}")
+          body = Oj.load(response.body)
+          array += body['audit_logs'].map { |a| AuditLogs.new(a) }
+          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 audit log in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/audit_logs/#show-audit-log
+      #   Zendesk API > Audit Logs > Show Audit Log
+      # @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
+      #
+      #   log = SupportOps::Zendesk::AuditLogs.get(25)
+      #   pp log.action
+      #   # => "update"
+      def self.get(object)
+        if object.is_a? AuditLogs
+          AuditLogs.new(id: id).find
+        else
+          AuditLogs.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific audit log in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/audit_logs/#show-audit-log
+      #   Zendesk API > Audit Logs > Show Audit Log
+      # @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
+      #
+      #   log = SupportOps::Zendesk::AuditLogs.get!(25)
+      #   pp log.action
+      #   # => "update"
+      def self.get!(object)
+        if object.is_a? AuditLogs
+          AuditLogs.new(id: id).find!
+        else
+          AuditLogs.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("audit_logs/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['audit_log']
+      end
+    end
+  end
+end