gitlab-customer-support-operations_zendesk 1.0.0

data/lib/support_ops_zendesk/zendesk/organization_memberships.rb

@@ -0,0 +1,336 @@
+# 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 When this record was created
+    # @attr [Boolean] default Denotes whether this is the default organization membership for the user. If false, returns null
+    # @attr [Integer] id Automatically assigned when the membership is created
+    # @attr [Integer] organization_id The ID of the organization associated with this user, in this membership
+    # @attr [String] organization_name The name of the organization associated with this user, in this membership
+    # @attr [String] updated_at When this record last got updated
+    # @attr [Integer] user_id The ID of the user for whom this memberships belongs
+    # @attr [Boolean] view_tickets Denotes whether the user can or cannot have access to all organization's tickets.
+    class OrganizationMemberships < SupportOps::Zendesk::Base
+      # @!parse
+      #   # Creates an organization 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/organizations/organization_memberships/#create-membership
+      #   #   Zendesk API > Organization 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::OrganizationMemberships.new
+      #   #   new_membership.organization_id = 88
+      #   #   new_membership.user_id = 72
+      #   #
+      #   #   new_membership.save!
+      #   #
+      #   #   pp new_membership.id
+      #   #   # => 461
+      #   def save!; end
+      # @!parse
+      #   # Deletes an organization 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/organizations/organization_memberships/#delete-membership
+      #   #   Zendesk API > Organization 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::OrganizationMemberships.get!(461)
+      #   #   existing_membership.delete!
+      #   def delete!; end
+      # @!parse
+      #   # Lists organization membership's organization
+      #   #
+      #   # @author Jason Colyer
+      #   # @since 1.0.0
+      #   # @return [Object]
+      #   # @note This is inherited from {SupportOps::Zendesk::Base#organizations}
+      #   # @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::OrganizationMemberships.get!(461)
+      #   #   org = existing_membership.organizations
+      #   #   pp org.name
+      #   #   # => "Bob's Burgers"
+      #   def organizations; end
+      # @!parse
+      #   # Lists organization 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::OrganizationMemberships.get!(461)
+      #   #   user = existing_membership.users
+      #   #   pp user.name
+      #   #   # => "Bob"
+      #   def users; end
+      define_attributes :created_at, :default, :id, :organization_id,
+                        :organization_name, :updated_at, :user_id, :view_tickets
+      readonly_attributes :created_at, :id, :updated_at
+
+      ##
+      # Lists organization 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
+      #     organization memberships returned. Default to 0 (i.e. no limit)
+      # @return [Array]
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/#list-memberships
+      #   Zendesk API > Organization 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::OrganizationMemberships.list(limit: 250)
+      #   pp memberships.count
+      #   # => 250
+      #   pp memberships.last.organization_name
+      #   # => "I'm the 250th organization"
+      def self.list(**args)
+        args[:limit] = 0 unless args[:limit]
+        items = []
+        opts = "page[size]=100&sort=#{args[:sort]}"
+        loop do
+          response = client.connection.get("organization_memberships?#{opts}")
+          body = Oj.load(response.body)
+          items += body['organization_memberships'].map { |o| OrganizationMemberships.new(o) }
+          break if args[:limit].to_i.positive? && items.count >= args[:limit].to_i
+          break unless body['meta']['has_more']
+
+          opts = body['links']['next'].split('?').last
+        end
+        return items if args[:limit].to_i.zero?
+        
+        items.first(args[:limit].to_i)
+      end
+
+      ##
+      # Locates a specific organization membership in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/#show-membership
+      #   Zendesk API > Organization 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::OrganizationMemberships.get(250)
+      #   pp membership.organization_name
+      #   # => "I'm the 25th organization"
+      def self.get(object)
+        if object.is_a? OrganizationMemberships
+          OrganizationMemberships.new(id: id).find
+        else
+          OrganizationMemberships.new(id: object).find
+        end
+      end
+
+      ##
+      # Locates a specific organization membership in the Zendesk system
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/#show-membership
+      #   Zendesk API > Organization 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::OrganizationMemberships.get!(250)
+      #   pp membership.organization_name
+      #   # => "I'm the 25th organization"
+      def self.get!(object)
+        if object.is_a? OrganizationMemberships
+          OrganizationMemberships.new(id: id).find!
+        else
+          OrganizationMemberships.new(id: object).find!
+        end
+      end
+
+      ##
+      # Deletes multiple organization memberships via a batch job
+      #
+      # @author Jason Colyer
+      # @since 1.0.0
+      # @param membership_ids [Array] An array of organization membership IDs
+      # @return [object] A {SupportOps::Zendesk::JobStatuses} instance
+      # @see
+      #   https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/#bulk-delete-memberships
+      #   Zendesk API > Organization 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::OrganizationMemberships.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 organization memberships at a time' if membership_ids.count > 100
+
+        response = client.connection.delete("organization_memberships/destroy_many?ids=#{membership_ids.join(',')}")
+        raise "Failed to delete organization memberships => #{body['details']}" if response.status != 200
+        JobStatuses.new(Oj.load(response.body)['job_status'])
+      end
+
+      ##
+      # Creates multiple organization 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/organizations/organization_memberships/#create-many-memberships
+      #   Zendesk API > Organization 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
+      #
+      #   org = SupportOps::Zendesk::Organizations.get!(250)
+      #   user1 = SupportOps::Zendesk::Users.get!(2)
+      #   user2 = SupportOps::Zendesk::Users.get!(4)
+      #   membership1 = SupportOps::Zendesk::OrganizationMemberships.new
+      #   membership1.default = true
+      #   membership1.organization_id = org.id
+      #   membership1.user_id = user1.id
+      #   membership2 = SupportOps::Zendesk::OrganizationMemberships.new
+      #   membership1.default = false
+      #   membership1.organization_id = org.id
+      #   membership1.user_id = user2.id
+      #
+      #   creates = SupportOps::Zendesk::OrganizationMemberships.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 organization memberships at a time' if memberships.count > 100
+        raise 'You can only use SupportOps::Zendesk::OrganizationMemberships instances in the Array' unless memberships.reject { |o| o.is_a? SupportOps::Zendesk::OrganizationMemberships }.count.zero?
+
+        data = { organization_memberships: memberships.map { |o| to_hash(o).compact } }.to_json
+        response = client.connection.post('organization_memberships/create_many', data)
+        raise "Failed to create organization 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("organization_memberships/#{self.id}")
+        return nil if response.status != 200
+
+        Oj.load(response.body)['organization_membership']
+      end
+
+      ##
+      # @private
+      def create_record
+        response = self.client.connection.post("organization_memberships", { organization_membership: attributes_for_save }.to_json)
+        body = Oj.load(response.body)
+        raise "Failed to create organization membership => #{body['details']}" if response.status != 201
+        body['organization_membership']
+      end
+
+      ##
+      # @private
+      def delete_record
+        response = self.client.connection.delete("organization_memberships/#{self.id}")
+        raise "Failed to delete organization membership => #{body['details']}" if response.status != 204
+        true
+      end
+
+      ##
+      # @private
+      def users_record
+        Users.get!(self.user_id)
+      end
+
+      ##
+      # @private
+      def organizations_record
+        Organizations.get!(self.organization_id)
+      end
+    end
+  end
+end