zendesk_support_api 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bcf45ecf6e738bc42b2b2843be87308fd0ac25eec6bdc6f7f05f63dbd2e382a7
+  data.tar.gz: 7649928f9e3b6701d14aa93252dab9c641b71935d7461142f5e1d5130612971d
+SHA512:
+  metadata.gz: 3b6057b660110d703092126a67180c69d989c67078cfc50b0edf6b2543f2efc26b209687fbd162257bc7f9cdd89e2b3174f92d3dadeae1cfc9146704f063ff9d
+  data.tar.gz: 987270880751bad257469be25b4ddf975f622a4a438533d04b89a66bbd093f7db54b291be4b22df02855d39be05b3b47b614622fd11d9ad7c2e23d0c39004d68

data/.gitlab-ci.yml

@@ -0,0 +1,13 @@
+image: ruby:2.6.1-alpine
+
+pages:
+  script:
+  - gem install yard
+  - yard doc
+  - rm -rf public
+  - mv doc public
+  artifacts:
+    paths:
+    - public
+  only:
+  - master

data/.yardoc/checksums

@@ -0,0 +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 a9aedf0641e4160b66414e76854e40dd245df1a7
+lib/zendesk_support_api/groups.rb bcc2a0b1af5bf3552c7838d80f339efbf8636e53
+lib/zendesk_support_api/search.rb e741717c61809c578afbcd44f9b8e8f18a8c0363
+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

@@ -0,0 +1,73 @@
+# ZendeskSupportAPI
+
+
+## Documentation
+
+Documentation (generated via yard) can be found [here](https://reyloc.gitlab.io/zendesk_support_api/)
+
+## Installation
+
+The gem can be installed either via rubygems or bundler:
+
+### Rubygems
+
+```bash
+gem install zendesk_support_api
+```
+
+### Bundler
+
+```ruby
+gem "zendesk_support_api"
+```
+
+The current requirements for the gem are:
+
+* 'faraday', '~>1.0.0'
+* 'oj', '~>3.10.6'
+
+## Configuration
+
+Configuration is done through the creation of a `ZendeskSupportAPI::Client`
+instance:
+
+```ruby
+require 'zendesk_support_api'
+
+client = ZendeskSupportAPI::Client.new('user@example.com', '123abc', 'https://zendesk.com/api/v2')
+```
+
+## Usage
+
+Soon to come
+
+## Changelog
+
+* v0.1.0 - Initial creation of gem
+* 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.6.0 - Satisfaction
+* v0.7.0 - Attachments?
+* v0.8.0 - Requests
+* v0.9.0 - Sessions
+* v0.10.0 - Tags
+* v0.11.0 - Views
+* v0.12.0 - Triggers
+* v0.13.0 - Automations
+* v0.14.0 - SLA
+* v0.15.0 - Targets
+* v0.16.0 - Macros
+* v0.17.0 - Brands
+* v0.18.0 - Locales
+* v0.19.0 - Schedules
+* v0.20.0 - Ticket Forms
+* v0.21.0 - Ticket Fields
+* v0.22.0 - User Fields
+* v0.23.0 - Organization Fields
+* v0.24.0 - Account Settings
+* v1.0.0 - Usage details, any polishing needed

data/lib/zendesk_support_api.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'oj'
+
+# ZendeskSupportAPI - https://developer.zendesk.com/rest_api/docs/support/introduction
+module ZendeskSupportAPI
+  require 'zendesk_support_api/client'
+  require 'zendesk_support_api/version'
+end

data/lib/zendesk_support_api/client.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+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
+    #
+    # @param user [String] - The API username to use
+    # @param token [String] - The API token to use
+    # @param url [String] - The API URL to use
+    #
+    # @example
+    #   ZendeskSupportAPI::Client.new('user', '123', 'zendesk.com/api')
+    #   #=> #<ZendeskSupportAPI::Client:0x00007f88779cb330 @user="user",
+    #   #=>    @token="123", @url="zendesk.com/api">
+    def initialize(user, token, url)
+      @user = user
+      @token = token
+      @url = url
+    end
+
+    # Make a request to the Zendesk Support API
+    #
+    # @param http_method [Symbol] The HTTP method to utilize
+    # @param endpoint [String] The endpoint to hit
+    # @param params [Hash] Parameters for the request
+    # @return [Hash]
+    #
+    # @example
+    #   client = ZendeskSupportAPI::Client.new('user', '123', 'zendesk.com/api')
+    #   client.response(:get, 'users.json')
+    #   #=> {users:[{user1},{user2}...{user100}]}
+
+    def request(http_method, endpoint, params = {})
+      response = client.public_send(http_method, endpoint, params)
+      Oj.load(response.body)
+    end
+
+    # Outputs a spinner symbol
+    #
+    # @param string [String] The string to output at the beginning
+    # @param num [Integer] The index of the iteration
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Client.spinner('users', 1) #=> Grabbing users... \
+    #   ZendeskSupportAPI::Client.spinner('groups', 3) #=> /
+
+    def spinner(string, num)
+      print "Grabbing #{string}... " if num.to_i == 1
+      symbols = ['-', '\\', '|', '/']
+      print symbols[num.to_i % 4]
+      print "\b"
+    end
+
+    # Handles responses that create jobs
+    #
+    # @param job [Hash] - The output from a request that created a job
+    # @return [Hash]
+
+    def handle_job(job)
+      print 'Checking job'
+      while job['job_status']['status'] != 'completed'
+        print '.'
+        job = ZendeskSupportAPI::Jobs.show(self, job['job_status']['id'])
+      end
+      puts 'completed'
+      job['job_status']['results']
+    end
+
+    private
+
+    # Creates a new Faraday instance
+    #
+    # @return [ZendeskSupportAPI::Client]
+
+    def client
+      @client ||= Faraday.new(@url) do |c|
+        c.request :url_encoded
+        c.adapter Faraday.default_adapter
+        c.basic_auth "#{@user}/token", @token
+      end
+    end
+  end
+end

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/groups.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module ZendeskSupportAPI
+  # Groups class - https://developer.zendesk.com/rest_api/docs/support/groups
+  class Groups
+    # Function to return a string that side-loads users
+    #
+    # @return [String]
+
+    def self.user_map(groups, users)
+      groups.map { |g| group_object(g, users) }
+    end
+
+    # Creates a group hash (for mappping the user into the group Hash)
+    #
+    # @param group [Hash] The group details to use
+    # @param users [Array] The Array of users to use
+    # @return [Hash]
+
+    def self.group_object(group, users)
+      group['user'] = users.select { |u| u['id'] == group['user_id'] }
+      group
+    end
+
+    # Returns the string of the next_page for pagination
+    #
+    # @param res [Hash] The Hash containing the response from a request
+    # @return [nil|String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Users.next_page(response) #=> nil
+    #   ZendeskSupportAPI::Users.next_page(response)
+    #   #=> "memberships.json?include=users&page=3
+
+    def self.next_page(res)
+      (res['next_page'].nil? ? nil : res['next_page'].split('/').last)
+    end
+
+    # Lists groups (first 100)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Groups.list(client)
+    #   #=> [
+    #   #=>   {
+    #   #=>     "name":       "DJs",
+    #   #=>     "created_at": "2009-05-13T00:07:08Z",
+    #   #=>     "updated_at": "2011-07-22T00:11:12Z",
+    #   #=>     "id":         211
+    #   #=>   },
+    #   #=>   {
+    #   #=>     "name":       "MCs",
+    #   #=>     "created_at": "2009-08-26T00:07:08Z",
+    #   #=>     "updated_at": "2010-05-13T00:07:08Z",
+    #   #=>     "id":         122
+    #   #=>   }
+    #   #=> ]
+
+    def self.list(client)
+      client.request(:get, 'groups.json')['groups']
+    end
+
+    # Shows assignable groups (first 100)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Groups.assignable(client)
+    #   #=> [
+    #   #=>   {
+    #   #=>     "name":       "DJs",
+    #   #=>     "created_at": "2009-05-13T00:07:08Z",
+    #   #=>     "updated_at": "2011-07-22T00:11:12Z",
+    #   #=>     "id":         211
+    #   #=>   },
+    #   #=>   {
+    #   #=>     "name":       "MCs",
+    #   #=>     "created_at": "2009-08-26T00:07:08Z",
+    #   #=>     "updated_at": "2010-05-13T00:07:08Z",
+    #   #=>     "id":         122
+    #   #=>   }
+    #   #=> ]
+
+    def self.assignable(client)
+      client.request(:get, 'assignable.json')['groups']
+    end
+
+    # Shows info about a specific group
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param gid [Integer] The Group ID
+    # @return [Hash]
+    #
+    # @example
+    #   ZendeskSupportAPI::Groups.show(client, 122)
+    #   #=> {
+    #   #=>   "name":       "MCs",
+    #   #=>   "created_at": "2009-08-26T00:07:08Z",
+    #   #=>   "updated_at": "2010-05-13T00:07:08Z",
+    #   #=>   "id":         122
+    #   #=> }
+
+    def self.show(client, gid)
+      client.request(:get, "groups/#{gid}.json")['group']
+    end
+
+    # Create a group
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param group [Hash] The group details to use
+    # @return [String|Hash]
+    #
+    # @example
+    #   group = {
+    #     name: 'Test Group'
+    #   }
+    #   ZendeskSupportAPI::Groups.create(client, group)
+    #   #=> {
+    #   #=>   "name": "Test Group",
+    #   #=>   "created_at": "2011-04-20T17:49:00Z",
+    #   #=>    "updated_at": "2011-04-20T17:49:00Z",
+    #   #=>    "id":         123
+    #   #=> }
+
+    def self.create(client, group)
+      res = client.request(:post, 'groups.json', group: group)
+      return "Creation failed: #{res['details']}" if res['error']
+
+      res
+    end
+
+    # Updates a group
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param gid [Integer] The group ID to use
+    # @param group [Hash] The group details to use
+    # @return [String|Hash]
+    #
+    # @example
+    #   group = {
+    #     name: 'Test Group - defunct'
+    #   }
+    #   ZendeskSupportAPI::Groups.update(client, 123, group)
+    #   #=> {
+    #   #=>   "name": "Test Group - defunct",
+    #   #=>   "created_at": "2011-04-20T17:49:00Z",
+    #   #=>    "updated_at": "2011-07-20T17:49:00Z",
+    #   #=>    "id":         123
+    #   #=> }
+
+    def self.update(client, gid, group)
+      res = client.request(:post, "groups/#{gid}.json", group: group)
+      return "Update failed: #{res['details']}" if res['error']
+
+      res
+    end
+
+    # Deletes a group
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param gid [Integer] The group ID to use
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Groups.delete(client, 123)
+    #   #=> Group 123 has been deleted
+
+    def self.delete(client, gid)
+      res = client.request(:delete, "groups/#{gid}.json")
+      return "Deletion of #{gid} failed: #{res['error']}" if res['error']
+
+      "Group #{gid} has been deleted"
+    end
+  end
+end