gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/group_memberships.rb

@@ -0,0 +1,337 @@
+# frozen_string_literal: true
+
+# Defines the module SupportOps.
+module SupportOps
+  # Defines the module Zendesk
+  module Zendesk
+    ##
+    # Defines the class GroupMemberships within the module {SupportOps::Zendesk}.
+    #
+    # @author Jason Colyer
+    # @since 1.0.0
+    # @attr [String] created_at The time the group was created
+    # @attr [Boolean] default If true, tickets assigned directly to the agent will assume this membership's group
+    # @attr [Integer] group_id The id of a group
+    # @attr [Integer] id Automatically assigned upon creation
+    # @attr [String] updated_at The time of the last update of the group
+    # @attr [Integer] user_id The id of an agent
+    # @todo List Assignable Memberships => https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#list-assignable-memberships
+    # @todo users
+    # @todo groups
+    class GroupMemberships < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates a group membership
+      #   # 
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object] Instance of {SupportOps::Zendesk::OrganizationMemberships}
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#save!}
+      #   # @see
+      #   #   https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#create-membership
+      #   #   Zendesk API > Group Memberships > Create Membership
+      #   # @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_membership = SupportOps::Zendesk::GroupMemberships.new
+      #   #   new_membership.group_id = 88
+      #   #   new_membership.user_id = 72
+      #   #   new_membership.default = false
+      #   #
+      #   #   new_membership.save!
+      #   #
+      #   #   pp new_membership.id
+      #   #   # => 461
+      #   def save!; end
+      # @!parse
+      #   # Deletes a group membership
+      #   # 
+      #   # @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/groups/group_memberships/#delete-membership
+      #   #   Zendesk API > Group Memberships > Delete Membership
+      #   # @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_membership = SupportOps::Zendesk::GroupMemberships.get!(461)
+      #   #   existing_membership.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Lists group membership's group
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#groups}
+      #   # @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_membership = SupportOps::Zendesk::GroupMemberships.get!(461)
+      #   #   group = existing_membership.groups
+      #   #   pp group.name
+      #   #   # => "My Group"
+      #   def groups; end
+      # @!parse
+      #   # Lists group membership's user
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#users}
+      #   #   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_membership = SupportOps::Zendesk::GroupMemberships.get!(461)
+      #   #   user = existing_membership.users
+      #   #   pp user.name
+      #   #   # => "Bob"
+      #   def users; end
+      define_attributes :created_at, :default, :group_id, :id, :updated_at,
+                        :user_id
+      readonly_attributes :created_at, :id, :updated_at
+
+      ##
+      # Lists group memberships 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 tickets
+      #     returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#list-memberships
+      #   Zendesk API > Group Memberships > List Memberships
+      # @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
+      #
+      #   memberships = SupportOps::Zendesk::GroupMemberships.list(limit: 25)
+      #   pp memberships.count
+      #   # => 25
+      #   pp memberships.last.user_id
+      #   # => 1234
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        list = []
+        opts = 'page[size]=100'
+        loop do
+          response = client.connection.get("group_memberships?#{opts}")
+          body = Oj.load(response.body)
+          list += body['group_memberships'].map { |g| GroupMemberships.new(g) }
+          break if args[:limit].to_i.positive? && list.count >= args[:limit].to_i
+          break unless body['meta']['has_more']
+
+          opts = body['links']['next'].split('?').last
+        end
+        return list if args[:limit].to_i.zero?
+        
+        list.first(args[:limit].to_i)
+      end
+
+      ##
+      # Locates a specific group membership in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#show-membership
+      #   Zendesk API > Group Memberships > Show Membership
+      # @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
+      #
+      #   membership = SupportOps::Zendesk::GroupMemberships.get(13983927615772)
+      #   pp membership.user_id
+      #   # => 1234
+      def self.get(object)
+        if object.is_a? GroupMemberships
+          GroupMemberships.new(id: id).find
+        else
+          GroupMemberships.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific group membership in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#show-membership
+      #   Zendesk API > Group Memberships > Show Membership
+      # @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
+      #
+      #   membership = SupportOps::Zendesk::GroupMemberships.get!(13983927615772)
+      #   pp membership.user_id
+      #   # => 1234
+      def self.get!(object)
+        if object.is_a? GroupMemberships
+          GroupMemberships.new(id: id).find!
+        else
+          GroupMemberships.new(id: object).find!
+        end
+      end
+
+      ##
+      # Creates multiple group memberships via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param memberships [Array] An array of {SupportOps::Zendesk::OrganizationMemberships} instances
+      # @return [object] A {SupportOps::Zendesk::JobStatuses} instance
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#bulk-create-memberships
+      #   Zendesk API > Group Memberships > Create Many Memberships
+      # @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
+      #
+      #   group = SupportOps::Zendesk::Groups.get!(25)
+      #   user1 = SupportOps::Zendesk::Users.get!(2)
+      #   user2 = SupportOps::Zendesk::Users.get!(4)
+      #   membership1 = SupportOps::Zendesk::GroupMemberships.new
+      #   membership1.group_id = org.id
+      #   membership1.user_id = user1.id
+      #   membership2 = SupportOps::Zendesk::GroupMemberships.new
+      #   membership1.group_id = org.id
+      #   membership1.user_id = user2.id
+      #
+      #   creates = SupportOps::Zendesk::GroupMemberships.create_many!([membership1, membership2])
+      #   pp creates.id
+      #   # => "82de0b044094f0c67893ac9fe64f1a99"
+      def self.create_many!(memberships)
+        raise 'The parameter must be an Array' unless memberships.is_a? Array
+        raise 'You can only create a maximum of 100 group memberships at a time' if memberships.count > 100
+        raise 'You can only use SupportOps::Zendesk::GroupMemberships instances in the Array' unless memberships.reject { |o| o.is_a? SupportOps::Zendesk::GroupMemberships }.count.zero?
+
+        data = { group_memberships: memberships.map { |o| to_hash(o).compact } }.to_json
+        response = client.connection.post('group_memberships/create_many', data)
+        raise "Failed to create group memberships => #{body['details']}" if response.status != 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      ##
+      # Deletes multiple group memberships via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param membership_ids [Array] An array of group membership IDs
+      # @return [object] A {SupportOps::Zendesk::JobStatuses} instance
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/groups/group_memberships/#bulk-delete-memberships
+      #   Zendesk API > Group Memberships > Bulk Delete Memberships
+      # @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
+      #
+      #   delete = SupportOps::Zendesk::GroupMemberships.delete_many!([123, 456])
+      #   pp delete.id
+      #   # => "82de0b044094f0c67893ac9fe64f1a99"
+      def self.delete_many!(membership_ids)
+        raise 'The parameter must be an Array' unless membership_ids.is_a? Array
+        raise 'You can only delete a maximum of 100 group memberships at a time' if membership_ids.count > 100
+
+        response = client.connection.delete("group_memberships/destroy_many?ids=#{membership_ids.join(',')}")
+        raise "Failed to delete group memberships => #{body['details']}" if response.status != 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      private
+
+      ##
+      # @private
+      def get_record
+        response = self.client.connection.get("group_memberships/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['group_membership']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("group_memberships", { group_membership: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create group membership => #{body}" if response.status != 201
+        body['group_membership']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("group_memberships/#{self.id}")
+        body = Oj.load(response.body)
+        raise "Failed to delete group membership => #{body}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def users_record
+        Users.get!(self.user_id)
+      end
+
+      ##
+      # @private
+      def groups_record
+        Groups.get!(self.group_id)
+      end
+    end
+  end
+end