zendesk_support_api 0.5.0

data/lib/zendesk_support_api/jobs.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module ZendeskSupportAPI
+  # Jobs class - https://developer.zendesk.com/rest_api/docs/support/job_statuses
+  class Jobs
+    # Make a request to show the job status
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param id [String] The id of the job to check
+    # @return [Hash]
+    #
+    # @example
+    #   client = ZendeskSupportAPI::Client.new('user', '123', 'zendesk.com/api')
+    #   ZendeskSupportAPI::Jobs.show(client, 'abc123')
+    #   #=> {
+    #   #=>   "job_status"=> {
+    #   #=>     "id"=>"abc123",
+    #   #=>     "url"=>"abc123.json",
+    #   #=>     "total"=>2,
+    #   #=>     "progress"=>2,
+    #   #=>     "status"=>"completed",
+    #   #=>     "message"=>"Completed at 2020-04-29 13:26:40 +0000",
+    #   #=>     "results"=> [
+    #   #=>       {
+    #   #=>         "id"=>369731992959,
+    #   #=>         "status"=>"Updated",
+    #   #=>         "email"=>"test@example.com"
+    #   #=>       },
+    #   #=>       {
+    #   #=>         "id"=>369728778639,
+    #   #=>         "status"=>"Updated",
+    #   #=>         "email"=>"test2@example.com"
+    #   #=>       }
+    #   #=>     ]
+    #   #=>   }
+    #   #=> }
+
+    def self.show(client, id)
+      client.request(:get, "job_statuses/#{id}.json")
+    end
+
+    # Make a request to show all job statuses
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @return [Hash]
+    #
+    # @example
+    #   ZendeskSupportAPI::Jobs.show_many(client, ['abc123', 'def456'])
+    #   #=> {
+    #   #=>   "job_statuses": [
+    #   #=>     {
+    #   #=>       "id": "abc123",
+    #   #=>       "status": "completed",
+    #   #=>       ...
+    #   #=>     },
+    #   #=>     {
+    #   #=>      "id": "def456",
+    #   #=>      "status": "completed",
+    #   #=>      ...
+    #   #=>     }
+    #   #=>   ]
+    #   #=> }
+
+    def self.list(client)
+      client.request(:get, 'job_statuses.json')['job_statuses']
+    end
+
+    # Show many job statuses
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param ids [Array] An Array of job IDs to show
+    # @return [Hash]
+    #
+    # @example
+    #   ZendeskSupportAPI::Jobs.show_many(client, ['abc123', 'def456'])
+    #   #=> {
+    #   #=>   "job_statuses": [
+    #   #=>     {
+    #   #=>       "id": "abc123",
+    #   #=>       "status": "completed",
+    #   #=>       ...
+    #   #=>     },
+    #   #=>     {
+    #   #=>      "id": "def456",
+    #   #=>      "status": "completed",
+    #   #=>      ...
+    #   #=>     }
+    #   #=>   ]
+    #   #=> }
+
+    def self.show_many(client, ids)
+      client.request(:get, "job_statuses/show_many.json?ids=#{ids.join(',')}")
+    end
+  end
+end

data/lib/zendesk_support_api/organizations.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+module ZendeskSupportAPI
+  # Organizations class - https://developer.zendesk.com/rest_api/docs/support/organizations
+  class Organizations
+    # Prints out organizations
+    #
+    # @return [String]
+
+    def self.orgs
+      'organizations'
+    end
+
+    # Lists Organizations (first 100)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Organizations.list(client)
+    #   #=> [
+    #   #=>   {
+    #   #=>     "url": "https://zendesk.com/api/v2/organizations/1.json",
+    #   #=>     "id": 1,
+    #   #=>     "name": "One Organization",
+    #   #=>     ...
+    #   #=>   },
+    #   #=>   ...
+    #   #=>   {
+    #   #=>     "url": "https://zendesk.com/api/v2/organizations/100.json",
+    #   #=>     "id: 100,
+    #   #=>     "name": "Other Organization",
+    #   #=>     ...
+    #   #=>   }
+    #   #=> ]
+
+    def self.list(client)
+      client.request(:get, "#{orgs}.json")[orgs]
+    end
+
+    # Shows info about an organization
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param oid [Integer] The Organization ID to use
+    # @return [Hash]
+    #
+    # @example
+    #   ZendeskSupportAPI::Organizations.show(client, 123)
+    #   #=> {
+    #   #=>   "url": "https://zendesk.com/api/v2/organizations/1.json",
+    #   #=>   "id": 1,
+    #   #=>   "name": "One Organization",
+    #   #=>   ...
+    #   #=> }
+
+    def self.show(client, oid)
+      client.request(:get, "#{orgs}/#{oid}.json")['organization']
+    end
+
+    # Show several organizations
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param oids [Array] An Array of Organization IDs to show
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Organizations.show(client, [1,2])
+    #   #=> [
+    #   #=>   {
+    #   #=>     "url": "https://zendesk.com/api/v2/organizations/1.json",
+    #   #=>     "id": 1,
+    #   #=>     "name": "One Organization",
+    #   #=>     ...
+    #   #=>   },
+    #   #=>   {
+    #   #=>     "url": "https://zendesk.com/api/v2/organizations/2.json",
+    #   #=>     "id": 2,
+    #   #=>     "name": "Two Organization",
+    #   #=>     ...
+    #   #=>   }
+    #   #=> ]
+
+    def self.show_many(client, oids)
+      ids = "ids=#{oids.join(',')}"
+      client.request(:get, "#{orgs}/show_many.json?#{ids}")[orgs]
+    end
+
+    # Creates an organization
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param org [Hash] The organization info to use
+    # @return [Hash|String]
+    #
+    # @example
+    #   org = {
+    #     name: 'Test Organization',
+    #   }
+    #   ZendeskSupportAPI::Organizations.create(client, org)
+    #   #=> {
+    #   #=>   "url": "",
+    #   #=>   "id": 123,
+    #   #=>   "name": "Test Organization",
+    #   #=>   ...
+    #   #=> }
+
+    def self.create(client, org)
+      res = client.request(:post, "#{orgs}.json", organization: org)
+      return "Creation failed: #{res['details']}" if res['error']
+
+      res['organization']
+    end
+
+    # Creates many organizations
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param orgs [Array] The organizations to create
+    # @return [ZendeskSupportAPI::Client.handle_job]
+
+    def self.create_many(client, orgs)
+      url = "#{orgs}/create_many.json"
+      res = client.request(:post, url, organizations: orgs)
+      client.handle_job(res)
+    end
+
+    # Creates or updates an organization
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param org [Hash] The organization info to use
+    # @return [Hash|String]
+    #
+    # @example
+    #   org = {
+    #     name: 'Test Organization',
+    #   }
+    #   ZendeskSupportAPI::Organizations.create_or_update(client, org)
+    #   #=> {
+    #   #=>   "url": "",
+    #   #=>   "id": 123,
+    #   #=>   "name": "Test Organization",
+    #   #=>   ...
+    #   #=> }
+
+    def self.create_or_update(client, org)
+      url = "#{orgs}/create_or_update.json"
+      res = client.request(:post, url, organization: org)
+      return "Create/Update failed: #{res['description']}" if res['error']
+
+      res['organization']
+    end
+
+    # Updates an organization
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param oid [Integer] The Organization ID to use
+    # @param org [Hash] The organization info to use
+    # @return [Hash|String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Organizations.update(client, 123, org)
+    #   #=> {organization}
+
+    def self.update(client, oid, org)
+      res = client.request(:post, "#{orgs}/#{oid}.json", organization: org)
+      return "Update of #{uid} failed: #{res['error']}" if res['error']
+
+      res['organization']
+    end
+
+    # Updates many organizations
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param orgs [Array] The organizations to update
+    # @return [ZendeskSupportAPI::Client.handle_job]
+
+    def self.update_many(client, orgs)
+      url = "#{orgs}/update_many.json"
+      res = client.request(:put, url, organizations: orgs)
+      client.handle_job(res)
+    end
+
+    # Deletes an organization
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param oid [Integer] The Organization ID to delete
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Organizations.delete(client, 123)
+    #   #=> Organization 123 has been deleted
+    #   ZendeskSupportAPI::Organizations.delete(client, 123)
+    #   #=> "Deletion of 123 failed: RecordNotFound"
+
+    def self.delete(client, oid)
+      res = client.request(:delete, "#{orgs}/#{oid}.json")
+      return "Deletion of #{oid} failed: #{res['error']}" if res['error']
+
+      "Organization #{uid} has been deleted"
+    end
+
+    # Deletes many organizations
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param ids [Array] The array of Organization IDs to delete
+    # @return [ZendeskSupportAPI::Client.handle_job
+
+    def self.bulk_delete(client, ids)
+      url = "#{orgs}/destroy_many.json?ids=#{ids.join(',')}"
+      res = client.request(:delete, url)
+      client.handle_job(res)
+    end
+
+    # Searches for orgs by their external_id (first 100)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param eid [String] The External ID to use
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Organizations.search_by_external_id(client, 'abc123')
+    #   #=> [
+    #   #=>   {
+    #   #=>     "url": "https://zendesk.com/api/v2/organizations/1.json",
+    #   #=>     "id": 1,
+    #   #=>     "name": "One Organization",
+    #   #=>     ...
+    #   #=>   },
+    #   #=>   ...
+    #   #=>   {
+    #   #=>     "url": "https://zendesk.com/api/v2/organizations/100.json",
+    #   #=>     "id: 100,
+    #   #=>     "name": "Other Organization",
+    #   #=>     ...
+    #   #=>   }
+    #   #=> ]
+
+    def self.search_by_external_id(client, eid)
+      client.request(:get, "#{orgs}/search.json?external_id=#{eid}")[orgs]
+    end
+
+    # Get an Organization's members
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param oid [Integer] The Organization ID to use
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Organizations.members(client, 123)
+    #   #=> [
+    #   #=>   {
+    #   #=>     "id": 1,
+    #   #=>     "name": "Albert",
+    #   #=>     "email": "albert@example.com",
+    #   #=>     ...
+    #   #=>   },
+    #   #=>   ...
+    #   #=>   {
+    #   #=>     "id": 22,
+    #   #=>     "name": "Victor",
+    #   #=>     "email": "victor@example.com",
+    #   #=>     ...
+    #   #=>   }
+    #   #=> ]
+
+    def self.members(client, oid)
+      url = "#{orgs}/#{oid}/organization_memberships.json?include=users"
+      client.request(:get, url)['users']
+    end
+  end
+end

data/lib/zendesk_support_api/search.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module ZendeskSupportAPI
+  # Search class - https://developer.zendesk.com/rest_api/docs/support/search
+  class Search
+    # Perform a search and list results (first 100)
+    #
+    # @param client [ZendeskSupportAPI::Client] The client instance to use
+    # @param query [String] The query to use
+    # @param sort [String] The sorting method to use (defaults to revelance)
+    # @param order [String] The order to use (defaults to desc)
+    # @return [Array]
+    #
+    # @example
+    #   ZendeskSupportAPI::Search.list(client, 'bob')
+    #   #=> [
+    #   #=>   {
+    #   #=>     "name":        "Bob McBob",
+    #   #=>     "created_at":  "2009-05-13T00:07:08Z",
+    #   #=>     "updated_at":  "2011-07-22T00:11:12Z",
+    #   #=>     "id":          211,
+    #   #=>     "result_type": "user"
+    #   #=>     "url":         "https://zendesk.com/api/v2/users/211.json"
+    #   #=>   },
+    #   #=>   {
+    #   #=>     "name":        "Bob's Company",
+    #   #=>     "created_at":  "2009-08-26T00:07:08Z",
+    #   #=>     "updated_at":  "2010-05-13T00:07:08Z",
+    #   #=>     "id":          122,
+    #   #=>     "result_type": "group"
+    #   #=>     "url":         "https://zendesk.com/api/v2/groups/122.json"
+    #   #=>   },
+    #   #=>   ...
+    #   #=> ]
+
+    def self.list(client, query, sort = '', order = 'desc')
+      return bad_search("invalid sort - #{sort}") unless sort_valid?(sort)
+      return bad_search("invalid order - #{order}") unless order_valid?(order)
+
+      sort_order = sort_order_string(sort, order)
+      client.request(:get, "search.json?query=#{query}#{sort_order}")['results']
+    end
+
+    # Determines if a given sort string is valid
+    #
+    # @param sort [String] The sort string to check
+    # @return [Boolean]
+    #
+    # @example
+    #   ZendeskSupportAPI::Search.sort_valid? 'updated_at'
+    #   #=> true
+    #   ZendeskSupportAPI::Search.sort_valid? 'ticket_type'
+    #   #=> true
+    #   ZendeskSupportAPI::Search.sort_valid? 'random'
+    #   #=> false
+
+    def self.sort_valid?(sort)
+      return true if sort.empty?
+
+      valid = %w[updated_at created_at priority status ticket_type]
+      valid.include? sort
+    end
+
+    # Determines if a given order string is valid
+    #
+    # @param order [String] The order string to check
+    # @return [Boolean]
+    #
+    # @example
+    #   ZendeskSupportAPI::Search.order_valid? 'asc'
+    #   #=> true
+    #   ZendeskSupportAPI::Search.order_valid? 'desc'
+    #   #=> true
+    #   ZendeskSupportAPI::Search.order_valid? 'random'
+    #   #=> false
+
+    def self.order_valid?(order)
+      valid = %w[asc desc]
+      valid.include? order
+    end
+
+    # Prints out an error message
+    #
+    # @param string [String] The error that occurred
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Search.bad_search('invalid sort - name')
+    #   #=> "Search cannot be completed: invalid sort - name"
+
+    def self.bad_search(string)
+      "Search cannot be completed: #{string}"
+    end
+
+    # Determines the sort and order to use in the query
+    #
+    # @param sort [String] The sort string to use
+    # @param order [String] The order string to use
+    # @return [String]
+    #
+    # @example
+    #   ZendeskSupportAPI::Search.sort_order_string('', 'asc')
+    #   #=> "&order_by=asc"
+    #   ZendeskSupportAPI::Search.sort_order_string('priority', 'desc')
+    #   #=> "&sort_by=priority"
+    #   ZendeskSupportAPI::Search.sort_order_string('updated_at', 'asc')
+    #   #=> "&sort_by=updated_at&order_by=asc"
+
+    def self.sort_order_string(sort, order)
+      sort = (sort.empty? ? '' : "&sort_by=#{sort}")
+      order = (order == 'desc' ? '' : '&order_by=asc')
+      "#{sort}#{order}"
+    end
+  end
+end