zendesk_support_api 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c78cf01ac68e20c32f2e1d3ac3d47a9b4574012200718e33d06f3f92d75d9a68
-  data.tar.gz: f066e3f7c5fbfd5008a8a2d8b3fff4ba416c8d9e5a3373a7f8b8d586126c5fb9
+  metadata.gz: bcf45ecf6e738bc42b2b2843be87308fd0ac25eec6bdc6f7f05f63dbd2e382a7
+  data.tar.gz: 7649928f9e3b6701d14aa93252dab9c641b71935d7461142f5e1d5130612971d
 SHA512:
-  metadata.gz: f55d3a02c043022f70047bfe080d1227a9f1ea4dd9355f6e670ddb33187fd7bd6b79fbf207a99c671616ab0f370e56d4f9b8a510b966d50947a7c6e9ccf5c46e
-  data.tar.gz: 4eeb5abd58621fc511552e686859e68e95cbec5b8cca8363b93c1b9a57cdb2e1f01860b21158351a5290e44b3c929307b231bfd3f65917d7e8fc3a6451211492
+  metadata.gz: 3b6057b660110d703092126a67180c69d989c67078cfc50b0edf6b2543f2efc26b209687fbd162257bc7f9cdd89e2b3174f92d3dadeae1cfc9146704f063ff9d
+  data.tar.gz: 987270880751bad257469be25b4ddf975f622a4a438533d04b89a66bbd093f7db54b291be4b22df02855d39be05b3b47b614622fd11d9ad7c2e23d0c39004d68

data/.yardoc/checksums

@@ -1,8 +1,10 @@
 lib/zendesk_support_api.rb fee89f019b11ec8feb844644e000cec6cad6a695
 lib/zendesk_support_api/jobs.rb 15e3db660bb16f1a2bc580ce17a9368f81fc9d0e
 lib/zendesk_support_api/users.rb eb4f8d81f6f9ccf779679f7bfe354c0cc6be8d0c
-lib/zendesk_support_api/client.rb 19147ca149a521a068e8a8818ad9b26091df0542
+lib/zendesk_support_api/client.rb a9aedf0641e4160b66414e76854e40dd245df1a7
 lib/zendesk_support_api/groups.rb bcc2a0b1af5bf3552c7838d80f339efbf8636e53
 lib/zendesk_support_api/search.rb e741717c61809c578afbcd44f9b8e8f18a8c0363
-lib/zendesk_support_api/version.rb b95930e804ad2f9d4718efe8b3c740f79304913f
-lib/zendesk_support_api/organizations.rb 684c74525f26697a7a6e5fca921a1a937b0d20c8
+lib/zendesk_support_api/tickets.rb 938c32872eeb5459d8d8dae5bb5a9361cb5968d8
+lib/zendesk_support_api/version.rb 4a0944e207874b5ca81f14ae285d645d6d562928
+lib/zendesk_support_api/organizations.rb 9e677997416275c0bbccd5aafc1e1f0b7f0bb4c3
+lib/zendesk_support_api/deleted_tickets.rb 1c58c500e8adf19a910cc02bc7e18650e9751080

data/README.md

@@ -47,13 +47,13 @@ Soon to come
 * v0.2.0 - Added Search functions, Fixed some yard syntax/formatting, Changed version number
 * v0.3.0 - Changed version number, Added Group functions, Added User.groups function
 * v0.4.0 - Added Organization functions, Changed version number
+* v0.5.0 - Added DeletedTickets functions, Added Tickets functions, Yard synx fixes, updated version number
 
 ## Upcoming changes
 
-* v0.5.0 - Requests
-* v0.6.0 - Tickets
+* v0.6.0 - Satisfaction
 * v0.7.0 - Attachments?
-* v0.8.0 - Satisfaction
+* v0.8.0 - Requests
 * v0.9.0 - Sessions
 * v0.10.0 - Tags
 * v0.11.0 - Views

data/lib/zendesk_support_api/client.rb

@@ -3,10 +3,12 @@
 module ZendeskSupportAPI
   # Client class - https://developer.zendesk.com/rest_api/docs/support/introduction#security-and-authentication
   class Client
+    require 'zendesk_support_api/deleted_tickets'
     require 'zendesk_support_api/groups'
     require 'zendesk_support_api/jobs'
     require 'zendesk_support_api/organizations'
     require 'zendesk_support_api/search'
+    require 'zendesk_support_api/tickets'
     require 'zendesk_support_api/users'
 
     # Create a new instance of Client

data/lib/zendesk_support_api/deleted_tickets.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module ZendeskSupportAPI
+  # Tickets class - https://developer.zendesk.com/rest_api/docs/support/tickets
+  class DeletedTickets
+    # Determines if given string is a valid order function
+    #
+    # @param order [String] The order string to use
+    # @return [Boolean]
+    #
+    # @example
+    #   ZendeskSupportAPI::DeletedTickets.order_valid? 'desc' #=> true
+    #   ZendeskSupportAPI::DeletedTickets.order_valid? 'random' #=> false
+
+    def self.order_valid?(order)
+      %w[desc asc].include? order
+    end
+
+    # Prints out the sort_by and order_by string for the url
+    #
+    # @param sort [String] The sort string to use
+    # @param order [String] The order string to use
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::DeletedTickets.sort_order('id', 'desc')
+    #   #=> '&sort_by=id&order_by=desc'
+
+    def self.sort_order(sort, order)
+      "&sort_by=#{sort}&order_by=#{order}"
+    end
+
+    # Returns the string of the next_page for pagination
+    #
+    # @param res [Hash] The Hash containing the response from a request
+    # @return [nil|String]
+
+    def self.next_page(res)
+      (res['next_page'].nil? ? nil : res['next_page'].split('/').last)
+    end
+
+    # Prints out organization_id
+    #
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::DeletedTickets.org_id #=> 'organization_id'
+
+    def self.org_id
+      'organization_id'
+    end
+
+    # Selects an object from an array based on a user ID
+    #
+    # @param array [Array] An array of to look in
+    # @param id [Integer] The ID to use
+    # @return [Hash]
+
+    def self.select_obj(array, id)
+      array.select { |a| a['id'] == id }.first
+    end
+
+    # Determines if sort value is valid for delete requests
+    #
+    # @param sort [String] The string to check
+    # @return [Boolean]
+
+    def self.deleted_sort_valid?(sort)
+      %w[id subject deleted_at].includes?(sort)
+    end
+
+    # Lists deleted tickets (first 100)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param sort [String] The sort string to use
+    # @param order [String] The order string to use
+    # @return [Array]
+
+    def self.list_deleted(client, sort = 'id', order = 'asc')
+      return "Invalid sort '#{sort}'" unless delete_sort_valid?(sort)
+      return "Invalid order '#{order}'" unless order_valid?(order)
+
+      url = "deleted_tickets.json?#{sort_order(sort, order)}"
+      client.request(:get, url)['deleted_tickets']
+    end
+
+    # Lists all deleted tickets
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @return [Array]
+
+    def self.list_all_deleted(client)
+      tickets = []
+      page = 'deleted_tickets.json?page=1'
+      until page.nil?
+        res = client.request(:get, page)
+        client.spinner("tickets (total: #{res['count']})", page.split('=').last)
+        tickets += res['tickets']
+        page = next_page(res)
+      end
+      puts ' ...done'
+      tickets
+    end
+
+    # Restores a deleted ticket
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tid [Integer] The ticket ID to use
+    # @return [nil|String]
+
+    def self.restore(client, tid)
+      res = client.request(:put, "deleted_tickets/#{tid}/restore.json")
+      return "Restore of #{tid} failed: #{res['error']}" if res['error']
+
+      res
+    end
+
+    # Restores several deleted tickets
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tids [Array] Array of ticket IDs to use
+    # @return [ZendeskSupportAPI::Client.handle_job]
+
+    def self.restore_many(client, tids)
+      url = "deleted_tickets/restore_many?ids=#{tids.join(',')}"
+      res = client.request(:put, url)
+      client.handle_job(res)
+    end
+  end
+end

data/lib/zendesk_support_api/organizations.rb

@@ -113,7 +113,7 @@ module ZendeskSupportAPI
     # Creates many organizations
     #
     # @param client [ZendeskSupportAPI::Client] The client instance to use
-    # @param users [Array] The organizations to create
+    # @param orgs [Array] The organizations to create
     # @return [ZendeskSupportAPI::Client.handle_job]
 
     def self.create_many(client, orgs)

data/lib/zendesk_support_api/tickets.rb

@@ -0,0 +1,335 @@
+# frozen_string_literal: true
+
+module ZendeskSupportAPI
+  # Tickets class - https://developer.zendesk.com/rest_api/docs/support/tickets
+  class Tickets
+    # Determines if given string is a valid sort function
+    #
+    # @param sort [String] The sort string to use
+    # @return [Boolean]
+    #
+    # @example
+    #   ZendeskSupportAPI::Tickets.sort_valid? 'assignee' #=> true
+    #   ZendeskSupportAPI::Tickets.sort_valid? 'blah' #=> false
+
+    def self.sort_valid?(sort)
+      valid = %w[assignee assignee_name created_at group id locale requester
+                 requester.name status subject updated_at]
+      valid.include?(sort)
+    end
+
+    # Prints out the include string
+    #
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Tickets.includes
+    #   #=> '?include=users,organizations,ticket_forms,comment_count'
+
+    def self.includes
+      '?include=users,organizations,ticket_forms,comment_count'
+    end
+
+    # Prints out the sort_by and order_by string for the url
+    #
+    # @param sort [String] The sort string to use
+    # @param order [String] The order string to use
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Tickets.sort_order('id', 'desc')
+    #   #=> '&sort_by=id&order_by=desc'
+
+    def self.sort_order(sort, order)
+      "&sort_by=#{sort}&order_by=#{order}"
+    end
+
+    # Maps users into user_objects
+    #
+    # @param tickets [Array] The Array of tickets to map
+    # @param res [Hash] The has containing the response from a request
+    # @return [Hash]
+
+    def self.ticket_map(tickets, res)
+      tickets.map { |t| ticket_object(t, res) }
+    end
+
+    # Returns the string of the next_page for pagination
+    #
+    # @param res [Hash] The Hash containing the response from a request
+    # @return [nil|String]
+
+    def self.next_page(res)
+      (res['next_page'].nil? ? nil : res['next_page'].split('/').last)
+    end
+
+    # Prints out organization_id
+    #
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Tickets.org_id #=> 'organization_id'
+
+    def self.org_id
+      'organization_id'
+    end
+
+    # Creates a ticket object
+    #
+    # @param ticket [Hash] The ticket Hash to use
+    # @param res [Array] The response to use for mapping
+    # @return [Hash]
+
+    def self.ticket_object(ticket, res)
+      ticket.merge(
+        organization: select_obj(res['organizations'], ticket[org_id]),
+        form: select_obj(res['ticket_forms'], ticket['form_id']),
+        requester: select_obj(res['users'], ticket['requester_id']),
+        assignee: select_obj(res['users'], ticket['assignee_id'])
+      )
+    end
+
+    # Selects an object from an array based on a user ID
+    #
+    # @param array [Array] An array of to look in
+    # @param id [Integer] The ID to use
+    # @return [Hash]
+
+    def self.select_obj(array, id)
+      array.select { |a| a['id'] == id }.first
+    end
+
+    # List out tickets (first 100)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param sort [String] The sort method to use
+    # @param order [String] The order method to use
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Tickets.list(client)
+    #   #=> [
+    #   #=>   {
+    #   #=>     "id":      35436,
+    #   #=>     "subject": "Help I need somebody!",
+    #   #=>     ...
+    #   #=>   },
+    #   #=>   {
+    #   #=>     "id":      20057623,
+    #   #=>     "subject": "Not just anybody!",
+    #   #=>     ...
+    #   #=>   },
+    #   #=>   ...
+    #   #=> ]
+
+    def self.list(client, sort = 'id', order = 'asc')
+      return "Invalid sort '#{sort}'" unless sort_valid?(sort)
+      return "Invalid order '#{order}'" unless %w[asc desc].include?(order)
+
+      url = "tickets.json#{includes}#{sort_order(sort, order)}"
+      res = client.request(:get, url)
+      res['tickets'].map { |t| ticket_object(t, res) }
+    end
+
+    # Lists out all tickets (paginates over every page)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Tickets.all(client)
+    #   #=> Grabbing tickets (total: 215336)... / ...done
+    #   #=> [{ticket1},{ticket2}...{ticket215336}]
+
+    def self.all(client)
+      tickets = []
+      page = "tickets.json#{includes}&page=1"
+      until page.nil?
+        res = client.request(:get, page)
+        client.spinner("tickets (total: #{res['count']})", page.split('=').last)
+        tickets += ticket_map(res['tickets'], res)
+        page = next_page(res)
+      end
+      puts ' ...done'
+      tickets
+    end
+
+    # Shows details about a specific ticket
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tid [Integer] The Ticket ID to use
+    # @return [Hash]
+    #
+    # @example
+    #   ZendeskSupportAPI::Tickets.show(client, 35436)
+    #   #=> {
+    #   #=>   "id":      35436,
+    #   #=>   "subject": "My printer is on fire!",
+    #   #=>   ...
+    #   #=> }
+
+    def self.show(client, tid)
+      url = "tickets/#{tid}.json#{includes}"
+      res = client.request(:get, url)
+      res['ticket'].map { |t| ticket_object(t, res) }
+    end
+
+    # Show details about many tickets
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tids [Array] An array of ticket IDs
+    # @return [Array]
+
+    def self.show_many(client, tids)
+      url = "tickets/show_many.json#{includes}&ids=#{tids.join(',')}"
+      res = client.request(:get, url)
+      res['tickets'].map { |t| ticket_object(t, res) }
+    end
+
+    # Create a ticket
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param ticket [Hash] The ticket hash to use for creation
+    # @return [Hash|String]
+    #
+    # @example
+    #   ticket = {
+    #     subject: "This is a test ticket",
+    #     followers: [
+    #       { user_email: 'albert@example.com', action: 'put' },
+    #       { user_id: 123, action: 'put' }
+    #     ],
+    #     comment: {
+    #       body: "This goes into the test ticket body!"
+    #     },
+    #     tags: ["free_user", "ignore"]
+    #   }
+    #   ZendeskSupportAPI::Tickets.create(client, ticket)
+    #   #=> {
+    #   #=>   "id": 1,
+    #   #=>   "subject": "This is a test ticket",
+    #   #=>   ...
+    #   #=> }
+
+    def self.create(client, ticket)
+      res = client.request(:post, 'tickets.json', ticket: ticket)
+      return "Creation failed: #{res['details']}" if res['error']
+
+      res
+    end
+
+    # Creates many tickets
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tickets [Array] The array of ticket hashes to use for creation
+    # @return [ZendeskSupportAPI::Client.handle_job]
+
+    def self.create_many(client, tickets)
+      res = client.request(:post, 'tickets/create_many.json', tickets: tickets)
+      client.handle_job(res)
+    end
+
+    # Updates a ticket
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tid [Integer] The ticket ID to update
+    # @param ticket [Hash] The ticket hash to use
+    # @return [Hash|String]
+
+    def self.update(client, tid, ticket)
+      res = client.request(:put, "tickets/#{tid}.json", ticket: ticket)
+      return "Update of #{tid} failed: #{res['error']}" if res['error']
+
+      res
+    end
+
+    # Updates many tickets
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tickets [Array] The array of ticket hashes to use for updates
+    # @return [ZendeskSupportAPI::Client.handle_job]
+    #
+    # @example
+    #   tickets = [
+    #     {
+    #       id: 123,
+    #       tags: ['ultimate', 'urgent']
+    #     },
+    #     {
+    #       id: 124,
+    #       followers: [
+    #         { user_id: 123, action: 'delete' }
+    #       ]
+    #     },
+    #     {
+    #       id: 125,
+    #       subject: 'Staging Instance having issues'
+    #     }
+    #   ]
+    #   ZendeskSupportAPI::Tickets.update_many(client, tickets)
+
+    def self.update_many(client, tickets)
+      res = client.request(:put, 'tickets/update_many.json', tickets: tickets)
+      client.handle_job(res)
+    end
+
+    # Mark a ticket as spam and suspend the user
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tid [Integer] The ticket ID to use
+    # @return [String]
+
+    def self.mark_as_spam(client, tid)
+      res = client.request(:put, "tickets/#{tid}/mark_as_spam.json")
+      return "Unable to mark ticket as spam: #{res['error']}" if res['error']
+
+      "Ticket #{tid} marked as spam"
+    end
+
+    # Mark many tickets as spam and suspend their users
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tids [Array] The ticket IDs to use
+    # @return [ZendeskSupportAPI::Client.handle_job]
+
+    def self.mark_many_as_spam(client, tids)
+      url = "tickets/mark_many_as_spam.json?ids=#{tids.join(',')}"
+      res = client.request(:put, url)
+      client.handle_job(res)
+    end
+
+    # Merge Tickets into Target Ticket
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tid [Integer] The Ticket ID to merge into
+    # @param hash [Hash] The Hash to use for the merge (see example)
+    # @return [ZendeskSupportAPI::Client.handle_job]
+    #
+    # @example
+    #   merge_hash = {
+    #     ids: [112, 113, 114],
+    #     source_comment: "Closing in favor of #111",
+    #     target_comment: "Merging #112, #113, and #114 into this ticket"
+    #   }
+    #   ZendeskSupportAPI::Tickets.merge(client, 111, merge_hash)
+
+    def self.merge(client, tid, hash)
+      res = client.request(:post, "tickets/#{tid}/merge.json", hash)
+      client.handle_job(res)
+    end
+
+    # List followers of a ticket
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param tid [Integer] The Ticket ID to use
+    # @return [Array]
+
+    def self.list_followers(client, tid)
+      res = client.request(:get, "tickets/#{tid}/followers")['users']
+      res['users'].each do |user|
+        user['organization'] = select_obj(res['organizations'], user[org_id])
+      end
+      res['users']
+    end
+  end
+end

data/lib/zendesk_support_api/version.rb

@@ -3,5 +3,5 @@
 module ZendeskSupportAPI
   # Outputs the gem version
 
-  VERSION = '0.4.0'
+  VERSION = '0.5.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zendesk_support_api
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Jason Colyer
@@ -53,10 +53,12 @@ files:
 - README.md
 - lib/zendesk_support_api.rb
 - lib/zendesk_support_api/client.rb
+- lib/zendesk_support_api/deleted_tickets.rb
 - lib/zendesk_support_api/groups.rb
 - lib/zendesk_support_api/jobs.rb
 - lib/zendesk_support_api/organizations.rb
 - lib/zendesk_support_api/search.rb
+- lib/zendesk_support_api/tickets.rb
 - lib/zendesk_support_api/users.rb
 - lib/zendesk_support_api/version.rb
 - zendesk_support_api.gemspec