add support to ominichannel

Author: fbvilela

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## v3.0.6
+
+Adding support to the agent availabilities API endpoints
+
 ## v3.0.5
 
 Adding CBP support to more endpoints. please see `cbp_support_spec.rb` for the complete list.

README.md

@@ -271,6 +271,37 @@ ticket.requester # => #<ZendeskAPI::User id=...>
 Currently, this feature is limited to only a few resources and their associations.
 They are documented on [developer.zendesk.com](https://developer.zendesk.com/rest_api/docs/support/side_loading#supported-endpoints).
 
+#### Recommended Approach
+
+For better control over your data and to avoid large response sizes, consider fetching related resources explicitly. This approach can help you manage data loading more precisely and can lead to optimized performance for complex applications.
+
+```ruby
+ticket = ZendeskAPI::Ticket.find(id: 1)
+requester = ZendeskAPI::User.find(id: ticket.requester_id)
+```
+
+By explicitly fetching associated resources, you can ensure that your application only processes the data it needs, improving overall efficiency.
+
+### Omnichannel
+
+Support for the [Agent Availability API](https://developer.zendesk.com/api-reference/agent-availability/agent-availability-api/introduction/)
+
+An agent’s availability includes their state (such as online) for each channel (such as messaging), and their unified state across channels. It also includes the work items assigned to them.
+
+```ruby
+# All agent availabilities
+client.agent_availabilities.fetch
+
+# fetch availability for one agent, their channels and work items
+agent_availability = ZendeskAPI::AgentAvailability.find(client, 386390041152)
+agent_availability.channels
+agent_availability.channels.first.work_items
+
+# Using the agent availability filter
+ZendeskAPI::AgentAvailability.search(client, { select_channel: 'support' })
+ZendeskAPI::AgentAvailability.search(client, { channel_status: 'support:online' })
+```
+
 ### Search
 
 Searching is done through the client. Returned is an instance of `ZendeskAPI::Collection`:

lib/zendesk_api/resources.rb

@@ -16,6 +16,16 @@ class Locale < ReadResource; end
 
   class CustomRole < DataResource; end
 
+  class WorkItem < Resource; end
+
+  class Channel < Resource
+    def work_items
+      @work_items ||= attributes.fetch('relationships', {}).fetch('work_items', {}).fetch('data', []).map do |work_item_attributes|
+        WorkItem.new(@client, work_item_attributes)
+      end
+    end
+  end
+
   # client.agent_availabilities.fetch
   # client.agent_availabilities.find 20401208368
   # both return consistently - ZendeskAPI::AgentAvailability
@@ -24,10 +34,38 @@ def self.model_key
       "data"
     end
 
-    def self.find(client, id, *args)
+    def initialize(client, attributes = {})
+      nested_attributes = attributes.delete('attributes')
+      super(client, attributes.merge(nested_attributes))
+    end
+
+    def self.find(client, id)
       attributes = client.connection.get("#{resource_path}/#{id}").body.fetch(model_key, {})
       new(client, attributes)
     end
+
+    #  Examples:
+    #  ZendeskAPI::AgentAvailability.search(client, { channel_status: 'support:online' })
+    #  ZendeskAPI::AgentAvailability.search(client, { agent_status_id: 1 })
+    #  Just pass a hash that includes the key and value you want to search for, it gets turned into a query string
+    #  on the format of filter[key]=value
+    #  Returns a collection of AgentAvailability objects
+    def self.search(client, args_hash)
+      query_string = args_hash.map { |k, v| "filter[#{k}]=#{v}" }.join("&")
+      client.connection.get("#{resource_path}?#{query_string}").body.fetch(model_key, []).map do |attributes|
+        new(client, attributes)
+      end
+    end
+
+    def channels
+      @channels ||= begin
+        channel_attributes_array = @client.connection.get(attributes['links']['self']).body.fetch('included')
+        channel_attributes_array.map do |channel_attributes|
+          nested_attributes = channel_attributes.delete('attributes')
+          Channel.new(@client, channel_attributes.merge(nested_attributes))
+        end
+      end
+    end
   end
 
   class Role < DataResource

spec/live/cbp_support_spec.rb

@@ -222,4 +222,27 @@
       end
     end
   end
+
+  describe ZendeskAPI::AgentAvailability do
+    describe '/agent_availabilities' do
+      let(:collection_fetched) do
+        VCR.use_cassette("cbp_#{described_class}_collection") do
+          client.agent_availabilities.fetch
+          client.agent_availabilities
+        end
+      end
+
+      let(:response_body) { collection_fetched.response.body }
+      let(:collection_fetched_results) { collection_fetched.to_a }
+      it 'returns a CBP response with all the correct keys' do
+        expect(response_body).to have_key('meta')
+        expect(response_body).to have_key('links')
+        expect(response_body['meta'].keys).to include('has_more')
+      end
+
+      it 'returns a list of AgentAvailability objects' do
+        expect(collection_fetched_results).to all(be_a(described_class))
+      end
+    end
+  end
 end