gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/client.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Client within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    class Client
+      class Error < StandardError; end
+      class RequestError < Error; end
+      class ResourceNotFound < Error; end
+
+      attr_reader :connection
+
+      def initialize(config = SupportOps::Zendesk::Configuration.new)
+        @connection = determine_connnection(config)
+      end
+
+      def retry_options(config)
+        {
+          max: config[:retry_max],
+          interval: config[:retry_interval],
+          interval_randomness: config[:retry_randomness],
+          backoff_factor: config[:retry_backoff],
+          exceptions: config[:retry_exceptions]
+        }
+      end
+
+      def determine_connnection(config)
+        case config[:connection_type]
+        when 'standard'
+          generate_connection(config)
+        when 'upload'
+          generate_upload_connection(config)
+        when 'impersonation'
+          generate_impersonation_connection(config)
+        else
+          raise "Unknown connection type => #{config[:connection_type]}"
+        end
+      end
+
+      def generate_connection(config)
+        Faraday.new(config[:url]) do |c|
+          c.request :retry, retry_options(config)
+          c.adapter Faraday.default_adapter
+          c.headers['Content-Type'] = 'application/json'
+          c.headers['Authorization'] = authentication_string(config)
+        end
+      end
+
+      def generate_upload_connection(config)
+        Faraday.new(config[:url]) do |c|
+          c.request :retry, retry_options(config)
+          c.request :multipart
+          c.request :url_encoded
+          c.adapter Faraday.default_adapter
+          c.headers['Authorization'] = authentication_string(config)
+        end
+      end
+
+      def generate_impersonation_connection(config)
+        if config[:auth_type] != 'OAuth'
+          puts 'This type of connection only supports OAuth'
+          exit 1
+        end
+        Faraday.new(config[:url]) do |c|
+          c.request :retry, retry_options(config)
+          c.adapter Faraday.default_adapter
+          c.headers['Content-Type'] = 'application/json'
+          c.headers['Authorization'] = authentication_string(config)
+          c.headers['X-On-Behalf-Of'] = config[:on_behalf_of]
+        end
+      end
+
+      def authentication_string(config)
+        case config[:auth_type]
+        when 'API token'
+          "Basic " + Base64.encode64("#{config[:username]}/token:#{config[:token]}").gsub("\n", '')
+        when 'Oauth'
+          "Bearer #{config[:token]}"
+        else
+          raise "Unknown authentication type => #{config[:auth_type]}"
+        end
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/comments.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Comments within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Array] attachments Attachments, if any
+    # @attr [Integer] audit_id The id of the ticket audit record
+    # @attr [Integer] author_id The id of the comment author
+    # @attr [String] body The comment string
+    # @attr [String] created_at The time the comment was created
+    # @attr [String] html_body The comment formatted as HTML
+    # @attr [Integer] id Automatically assigned when the comment is created
+    # @attr [Hash] metadata System information (web client, IP address, etc.) and comment flags, if any
+    # @attr [String] plain_body The comment presented as plain text
+    # @attr [Boolean] public true if a public comment; false if an internal note
+    # @attr [String] type Comment or VoiceComment
+    # @attr [Array] uploads List of tokens received from uploading files for comment attachments
+    # @attr [Hash] via Describes how the object was created
+    # @todo List Comments => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/#list-comments
+    # @todo Count Ticket Comments => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/#count-ticket-comments
+    # @todo Make Comment Private => https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/#make-comment-private
+    class Comments < SupportOps::Zendesk::Base
+      define_attributes :attachments, :audit_id, :author_id, :body, :created_at,
+                        :html_body, :id, :metadata, :plain_body, :public, :type,
+                        :uploads, :via
+      readonly_attributes :id, :created_at
+      
+      private
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/configuration.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the module Configuration within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    module Configuration
+      ##
+      # Setup a Zendesk client configuration
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload configure(key: value)
+      #   @param auth_type [String] See {Config#auth_type}
+      #   @param connection_type [String] See {Config#connection_type}
+      #   @param on_behalf_of [String] See {Config#on_behalf_of}
+      #   @param password [String] See {Config#password}
+      #   @param retry_backoff [Integer] See {Config#retry_backoff}
+      #   @param retry_exceptions [Array] See {Config#retry_exceptions}
+      #   @param retry_interval [Integer] See {Config#retry_interval}
+      #   @param retry_max [Integer] See {Config#retry_max}
+      #   @param retry_randomness [Integer] See {Config#retry_randomness}
+      #   @param token [String] See {Config#token}
+      #   @param url [String] See {Config#url}
+      #   @param username [String] See {Config#username}
+      # @example Standard usage using an API token
+      #   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
+      # @example Standard usage using an OAuth token
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.auth_type = 'OAuth'
+      #     config.token = 'abc123'
+      #   end
+      # @example Using impersonation
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.auth_type = 'OAuth'
+      #     config.connection_type = 'impersonation'
+      #     config.token = 'abc123'
+      #     config.on_behalf_of = 'test_user@example.com'
+      #   end
+      # @example A connection for uploads using an API token
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.connection_type = 'upload'
+      #     config.username = 'jason@example.com'
+      #     config.token = 'abc123'
+      #   end
+      # @example A connection for uploads using an OAuth token
+      #   require 'support_ops_zendesk'
+      #
+      #   SupportOps::Zendesk::Configuration.configure do |config|
+      #     config.url = 'https://gitlab.zendesk.com/api/v2'
+      #     config.auth_type = 'OAuth'
+      #     config.connection_type = 'upload'
+      #     config.token = 'abc123'
+      #   end
+      def self.configure
+        yield config
+      end
+
+      def self.config
+        @config ||= Config.new
+      end
+
+      def self.reset!
+        @config = Config.new
+      end
+
+      ##
+      # Defined the class Config within the module {SupportOps::Zendesk::Configuration}
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @attr [String] auth_type The type of authentication being used, available options are 'API token' and 'OAuth'
+      # @attr [String] connection_type The type of connection being made, available options are 'standard', 'upload', and 'impersonation'
+      # @attr [String] on_behalf_of The email of the user the connection is impersonating. Only used in 'OAuth' connections
+      # @attr [String] password The password to use for authenitcation (deprecated)
+      # @attr [Integer] retry_backoff  multiplier applied to the retry_interval after each retry attempt, causing exponential backoff. Defaults to 2
+      # @attr [Array] retry_exceptions Specifies which types of exceptions or errors should trigger the retry mechanism.
+      # @attr [Integer] retry_interval The base time interval (typically in seconds or milliseconds) between retry attempts. Defaults to 1
+      # @attr [Integer] retry_max The maximum number of retry attempts that will be made when an operation fails. Defaults to 5
+      # @attr [Float] retry_randomness Adds a random element to the retry interval to prevent "thundering herd" problems where many systems retry simultaneously. Defaults to 0.5
+      # @attr [String] token The token to use for authentication
+      # @attr [String] url The API url to connect to, it should alwaus be in the format of 'https:\/\/YOUR_SUBDOMAIN.zendesk.com/api/v2' (note the lack of a trailing /)
+      # @attr [String] username The username (email) you are connecting via, it should only ever be an email address (there is no need to add '/token' or the like to the end of it). Only used in 'API token' connections
+      class Config
+        attr_accessor :url, :username, :token, :retry_max, :retry_interval,
+                      :retry_randomness, :retry_backoff, :retry_exceptions,
+                      :connection_type, :auth_type, :password, :on_behalf_of
+
+        def initialize
+          @auth_type = 'API token'
+          @connection_type = 'standard'
+          @retry_backoff = 2
+          @retry_exceptions = Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ConnectionFailed]
+          @retry_interval = 1
+          @retry_max = 5
+          @retry_randomness = 0.5
+        end
+
+        def client
+          @client ||= Client.new(
+            auth_type: auth_type,
+            connection_type: connection_type,
+            on_behalf_of: on_behalf_of,
+            password: password,
+            retry_max: retry_max,
+            retry_interval: retry_interval,
+            retry_randomness: retry_randomness,
+            retry_backoff: retry_backoff,
+            retry_exceptions: retry_exceptions,
+            url: url,
+            username: username,
+            token: token,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/support_ops_zendesk/zendesk/custom_roles.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class CustomRoles within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Hash] configuration Configuration settings for the role
+    # @attr [String] created_at The time the record was created
+    # @attr [String] description A description of the role
+    # @attr [Integer] id Automatically assigned on creation
+    # @attr [String] name Name of the custom role
+    # @attr [Integer] role_type The user's role; 0 stands for a custom agent, 1 for a light agent, 2 for a chat agent, 3 for a contributor, 4 for an admin and 5 for a billing admin
+    # @attr [Integer] team_member_count The number of team members assigned to this role
+    # @attr [String] updated_at The time the record was last updated
+    class CustomRoles < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates a custom role
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::CustomRoles}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#create-custom-role
+      #   #   Zendesk API > Custom Roles > Create Custom Roles
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#update-custom-role
+      #   #   Zendesk API > Custom Roles > Update Custom Roles
+      #   # @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
+      #   #
+      #   #   orig_role = SupportOps::Zendesk::CustomRoles.get!(10127)
+      #   #   new_role = SupportOps::Zendesk::CustomRoles.new
+      #   #   new_role.name = 'Sample role'
+      #   #   new_role.configuration = orig_role.configuration
+      #   #   new_role.configuration['explore_access'] = 'edit'
+      #   #
+      #   #   new_role.save!
+      #   #
+      #   #   pp new_role.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
+      #   #
+      #   #   existing_role = SupportOps::Zendesk::CustomRoles.get!(23409462)
+      #   #   existing_role.name = 'Sample role cloned from 10127'
+      #   #
+      #   #   existing_role.save!
+      #   #
+      #   #   pp existing_role.name
+      #   #   # => "Sample role cloned from 10127"
+      #   def save!; end
+      # @!parse
+      #   # Deletes a custom role
+      #   # 
+      #   # @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/account-configuration/custom_roles/#delete-custom-role
+      #   #   Zendesk API > Custom Roles > Delete Custom Role
+      #   # @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_role = SupportOps::Zendesk::CustomRoles.get!(23409462)
+      #   #   existing_role.delete!
+      #   def delete!; end
+      define_attributes :configuration, :created_at, :description, :id, :name,
+                        :role_type, :team_member_count, :updated_at
+      readonly_attributes :created_at, :id, :role_type, :team_member_count,
+                          :updated_at
+
+      ##
+      # Lists custom roles in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#list-custom-roles
+      #   Zendesk API > Custom Roles > ist Custom Roles
+      # @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
+      #
+      #   roles = SupportOps::Zendesk::CustomRoles.list
+      #   pp roles.count
+      #   # => 12
+      #   pp roles.last.name
+      #   # => "I'm the 12th custom role"
+      def self.list
+        response = client.connection.get('custom_roles')
+        body = Oj.load(response.body)
+        body['custom_roles'].map { |c| CustomRoles.new(c) }
+      end
+
+      ##
+      # Locates a specific custom role in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#show-custom-role
+      #   Zendesk API > Custom Roles > Show Custom Role
+      # @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
+      #
+      #   role = SupportOps::Zendesk::CustomRoles.get(25)
+      #   pp role.title
+      #   # => "I'm the 25th custom role"
+      def self.get(object)
+        if object.is_a? CustomRoles
+          CustomRoles.new(id: id).find
+        else
+          CustomRoles.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific custom role in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/account-configuration/custom_roles/#show-custom-role
+      #   Zendesk API > Custom Roles > Show Custom Role
+      # @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
+      #
+      #   role = SupportOps::Zendesk::CustomRoles.get!(25)
+      #   pp role.title
+      #   # => "I'm the 25th custom role"
+      def self.get!(object)
+        if object.is_a? CustomRoles
+          CustomRoles.new(id: id).find!
+        else
+          CustomRoles.new(id: object).find!
+        end
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("custom_roles/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['custom_role']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("custom_roles", { custom_role: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create custom role => #{body}" if response.status != 200
+        body['custom_role']
+      end
+
+      ##
+      # @private
+      def update_record
+        raise "Failed to update automation => You didn't change anything in the object" if attributes_for_save.keys == [:id]
+        response = self.client.connection.put("custom_roles/#{self.id}", { custom_role: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to update custom role #{self.id} => #{body['details']}" if response.status != 200
+        body['custom_role']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("custom_roles/#{self.id}")
+        raise "Failed to delete custom role => #{body['details']}" if response.status != 204
+        true
+      end
+    end
+  end
+end