gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/apps.rb

@@ -0,0 +1,476 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class Apps within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [Object] app_organization Organization that submitted the app to the Zendesk Marketplace
+    # @attr [String] author_email The app author's email
+    # @attr [String] author_name The app author's name
+    # @attr [String] author_url The app author's URL
+    # @attr [Array] categories Zendesk Marketplace categories to which the app belongs
+    # @attr [Array] collections Zendesk Marketplace collections to which the app belongs
+    # @attr [String] created_at When the app was created
+    # @attr [String] date_published When the app was published on the Zendesk Marketplace
+    # @attr [String] default_locale The default locale for translations for the app
+    # @attr [Boolean] deprecated If true, the app is deprecated
+    # @attr [String] feature_color Hexadecimal color value used to feature the app on the Zendesk Marketplace
+    # @attr [Boolean] featured Whether or not the app is featured in the Zendesk Marketplace
+    # @attr [String] framework_version The app framework version for which the app was written
+    # @attr [String] google_analytics_code Universal Google Analytics ("UA-") tracking id for the app's detail page on the Zendesk Marketplace
+    # @attr [Integer] id The id of the app
+    # @attr [Boolean] installable Whether or not the app can be installed
+    # @attr [Integer] installation_count Current number of installations of the app
+    # @attr [String] installation_instructions Instructions for installing the app
+    # @attr [String] large_icon The large icon url for an app
+    # @attr [Array] locations Location ids for the app
+    # @attr [String] long_description The app's long description in the Zendesk Marketplace
+    # @attr [Boolean] marketing_only If true, the app is an integration app
+    # @attr [String] name The name of the app
+    # @attr [Boolean] obsolete If true, the app is obsolete
+    # @attr [Integer] owner_id The app developer id corresponding to the app
+    # @attr [Boolean] paid If true, the app is a paid app
+    # @attr [Array] parameters The parameters for the app
+    # @attr [Array] plans Payment plans for the app
+    # @attr [Array] products Zendesk products supported by the app
+    # @attr [Boolean] promoted Whether or not the app is a promoted app in the Zendesk Marketplace
+    # @attr [Object] rating The ratings of the app
+    # @attr [String] raw_installation_instructions The raw installation instructions
+    # @attr [String] raw_long_description The raw long description for the app in the Zendesk Marketplace
+    # @attr [String] remote_installation_url URL for the app's installation instructions
+    # @attr [Array] screenshots Screenshots for the app when displayed in the Zendesk Marketplace
+    # @attr [String] short_description The short description of the app in the Zendesk Marketplace
+    # @attr [Boolean] single_install Whether or not this app can only be installed once
+    # @attr [String] small_icon The url for the small logo for the app
+    # @attr [String] state Publication state for the app on the Zendesk Marketplace
+    # @attr [String] stripe_publishable_key Publishable key for the app developer's Stripe account
+    # @attr [String] terms_conditions_url URL for the app's terms and conditions
+    # @attr [Object] third_party_pricing Third-party pricing information for the app
+    # @attr [String] updated_at When the app was last updated
+    # @attr [String] version The version of the app
+    # @attr [String] visibility The app is a private app, which is only visible to your account, or a public app
+    class Apps < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates/updates an app
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @see SupportOps::Zendesk::Configuration Setting up a client
+      #   # @return [Object] Instance of {SupportOps::Zendesk::Apps}
+      #   # @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_app = SupportOps::Zendesk::Apps.new
+      #   #   new_app.name = 'New app'
+      #   #   new_app.zipfile = SupportOps::Zendesk::Apps.package!('data/new_app')
+      #   #
+      #   #   new_app.save!
+      #   #
+      #   #   pp new_app.id
+      #   #   # => 123456
+      #   # @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_app = SupportOps::Zendesk::Apps.get!(123456)
+      #   #   existing_app.zipfile = SupportOps::Zendesk::Apps.package!('data/modified_app')
+      #   #
+      #   #   existing_app.save!
+      #   #
+      #   #   pp existing_app.id
+      #   #   # => 123456
+      #   def save!; end
+      # @!parse
+      #   # Reveals the app's public key in PEM format
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Boolean]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#public_key!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/apps/apps/#get-app-public-key
+      #   #   Zendesk API > Apps > Get App Public Key
+      #   # @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_app = SupportOps::Zendesk::Apps.get!(123456)
+      #   #   key = existing_app.public_key
+      #   #   pp key
+      #   #   # => "-----BEGIN PUBLIC KEY-----\nPEM_formatted_string_goes_here\n-----END PUBLIC KEY-----\n"
+      #   def public_key; end
+      # @!parse
+      #   # Deletes an app
+      #   # 
+      #   # @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/apps/apps/#delete-app
+      #   #   Zendesk API > Apps > Delete App
+      #   # @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_app = SupportOps::Zendesk::Apps.get!(123456)
+      #   #   existing_app.delete!
+      #   def delete!; end
+      define_attributes :app_organization, :author_email, :author_name,
+                        :author_url, :categories, :collections, :created_at,
+                        :date_published, :default_locale, :deprecated,
+                        :feature_color, :featured, :framework_version,
+                        :google_analytics_code, :id, :installable,
+                        :installation_count, :installation_instructions,
+                        :large_icon, :locations, :long_description,
+                        :marketing_only, :name, :obsolete, :owner_id, :paid,
+                        :parameters, :plans, :products, :promoted, :rating,
+                        :raw_installation_instructions, :raw_long_description,
+                        :remote_installation_url, :screenshots,
+                        :short_description, :single_install, :small_icon,
+                        :state, :stripe_publishable_key, :terms_conditions_url,
+                        :third_party_pricing, :updated_at, :version,
+                        :visibility, :zipfile
+      readonly_attributes :app_organization, :author_email, :author_name,
+                          :author_url, :categories, :collections, :created_at,
+                          :date_published, :default_locale, :deprecated,
+                          :feature_color, :featured, :framework_version,
+                          :google_analytics_code, :id, :installable,
+                          :installation_count, :installation_instructions,
+                          :large_icon, :locations, :long_description,
+                          :marketing_only, :name, :obsolete, :owner_id, :paid,
+                          :parameters, :plans, :products, :promoted, :rating,
+                          :raw_installation_instructions, :raw_long_description,
+                          :remote_installation_url, :screenshots,
+                          :short_description, :single_install, :small_icon,
+                          :state, :stripe_publishable_key, :terms_conditions_url,
+                          :third_party_pricing, :updated_at, :version,
+                          :visibility
+
+      ##
+      # Lists apps in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/apps/apps/#list-all-apps
+      #   Zendesk API > Apps > List All Apps
+      # @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'
+      #     config.connection_type = 'upload'
+      #   end
+      #
+      #   apps = SupportOps::Zendesk::Apps.list
+      #   pp apps.count
+      #   # => 12
+      def self.list
+        response = client.connection.get('apps')
+        body = Oj.load(response.body)
+        body['apps'].map { |a| Apps.new(a) }
+      end
+
+      ##
+      # Lists apps owned by the current account in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/apps/apps/#list-owned-apps
+      #   Zendesk API > Apps > List Owned Apps
+      # @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'
+      #     config.connection_type = 'upload'
+      #   end
+      #
+      #   apps = SupportOps::Zendesk::Apps.list_owned
+      #   pp apps.count
+      #   # => 10
+      def self.list_owned
+        response = client.connection.get('apps/owned')
+        body = Oj.load(response.body)
+        body['apps'].map { |a| Apps.new(a) }
+      end
+
+      ##
+      # Locates an app 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::Apps to use as a cache
+      # @return [Object] An instance of {SupportOps::Zendesk::Apps}
+      # @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
+      #
+      #   apps = SupportOps::Zendesk::Apps.list
+      #   app = SupportOps::Zendesk::Apps.find_by_name(name: 'QuickSearch', cache: apps)
+      #   pp app.name
+      #   # => "QuickSearch"
+      #   pp app.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
+          apps = args[:cache]
+        else
+          apps = list
+        end
+        apps.detect { |c| c.name.downcase == args[:name].to_s.downcase }
+      end
+
+      ##
+      # Locates a specific app in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/apps/apps/#get-information-about-app
+      #   Zendesk API > Apps > Show Information About App
+      # @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'
+      #     config.connection_type = 'upload'
+      #   end
+      #
+      #   app = SupportOps::Zendesk::Apps.get(123456)
+      #   pp app.name
+      #   # => "QuickSearch"
+      def self.get(object)
+        if object.is_a? Apps
+          Apps.new(id: id).find
+        else
+          Apps.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific app in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/apps/apps/#get-information-about-app
+      #   Zendesk API > Apps > Show Information About App
+      # @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'
+      #     config.connection_type = 'upload'
+      #   end
+      #
+      #   app = SupportOps::Zendesk::Apps.get!(123456)
+      #   pp app.name
+      #   # => "QuickSearch"
+      def self.get!(object)
+        if object.is_a? Apps
+          Apps.new(id: id).find!
+        else
+          Apps.new(id: object).find!
+        end
+      end
+
+      ##
+      # Sends a notification to a specific app in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @overload notify!(key: value)
+      #   @param app_id [Integer] The id of the app you want to send the message
+      #     to
+      #   @param event [String] The name of the event you want to fire in your
+      #     app
+      #   @param body [String optional] If it's valid JSON, it's passed to your
+      #     app as a JavaScript object.
+      #   @param agent_id [Integer optional] Send the notification to only one
+      #     agent
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/apps/apps/#send-notification-to-app
+      #   Zendesk API > Apps > Send Notification to App
+      # @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
+      #
+      #   result = SupportOps::Zendesk::Apps.notify!(app_id: 123456, event: 'updateUsersPhoneNumber', agent_id: 534, body: '+123456789')
+      #   pp result
+      #   # => true
+      def self.notify!(**args)
+        raise 'You must specify the app via "app_id:xxx" for this to work' unless args[:app_id]
+        raise 'You must specify the event via "event:xxx" for this to work' unless args[:event]
+        data = {
+          'app_id' => args[:app_id],
+          'event' => args[:event],
+        }
+        get!(args[:app_id])
+        data['body'] = args[:body] if args[:body]
+        data['agent_id'] = args[:agent_id] if args[:agent_id]
+        response = client.connection.post('apps/notify', data.to_json)
+        body = Oj.load(response.body)
+        raise "Unable to notify app #{args[:app_id]} => #{body}" unless response.status == 200
+        true
+      end
+
+      ##
+      # Creates a zipfile for the app
+      #
+      # @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 app
+      #   files are located in; defaults to './'
+      # @example
+      #   require 'support_ops_zendesk'
+      #
+      #   file = SupportOps::Zendesk::Apps.package!('data/new_app')
+      #   pp file
+      #   # => "data/20250409124436282.zip"
+      def self.package!(base_folder = '')
+        list = %w[ assets translations manifest.json ]
+        SupportOps::Packages.create_zipfile!(item_list: list, input_dir: base_folder)
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("apps/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)
+      end
+
+      ##
+      # @private
+      def public_key_record
+        response = self.client.connection.get("apps/#{self.id}/public_key")
+        return nil if response.status != 200
+
+        Oj.load(response.body)
+      end
+
+      ##
+      # @private
+      def create_record
+        raise 'No zipfile specified' if self.zipfile.nil?
+        data = {
+          'uploaded_data' => ::Faraday::UploadIO.new(self.zipfile, 'application.zip')
+        }
+        response = self.client.connection.post('apps/uploads', data)
+        body = Oj.load(response.body)
+        raise "Unable to create app (upload) => #{body}" unless response.status == 201
+        data = {
+          'upload_id' => body['id']
+        }
+        response = self.client.connection.post('apps', data)
+        body = Oj.load(response.body)
+        raise "Unable to update app #{self.id} => #{body}" unless response.status == 202
+        job_id = body['job_id']
+        job = AppJobStatuses.get!(job_id)
+        job.wait_for_completetion
+        response = client.connection.get('apps/owned')
+        body = Oj.load(response.body)
+        body['apps'].detect { |t| t['name'] == self.name }
+      end
+
+      ##
+      # @private
+      def update_record
+        raise 'No zipfile specified' if self.zipfile.nil?
+        data = {
+          'uploaded_data' => ::Faraday::UploadIO.new(self.zipfile, 'application.zip')
+        }
+        response = self.client.connection.post('apps/uploads', data)
+        body = Oj.load(response.body)
+        raise "Unable to update app #{self.id} (upload) => #{body}" unless response.status == 201
+        data = {
+          'upload_id' => body['id']
+        }
+        response = self.client.connection.put("apps/#{self.id}", data)
+        body = Oj.load(response.body)
+        raise "Unable to update app #{self.id} => #{body}" unless response.status == 202
+        job_id = body['job_id']
+        job = AppJobStatuses.get!(job_id)
+        job.wait_for_completetion
+        response = client.connection.get('apps/owned')
+        body = Oj.load(response.body)
+        body['apps'].detect { |t| t['name'] == self.name }
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("apps/#{self.id}")
+        raise "Failed to delete app => #{body}" if response.status != 204
+        true
+      end
+    end
+  end
+end
+#save!