DEVX-7835: Add Conversation API (#305)

* Adding Conversation API v1

CHANGES.md

@@ -1,3 +1,7 @@
+# 7.22.0
+
+* Adds support for v1 the Conversation API. [#305](https://github.com/Vonage/vonage-ruby-sdk/pull/305)
+
 # 7.21.0
 
 * Changes the HTTP adapter from `Net::HTTP` to `Net::HTTP::Persistent` and fixes an issue with a dependency (`ruby-jwt`)

README.md

@@ -525,6 +525,7 @@ The following is a list of Vonage APIs for which the Ruby SDK currently provides
 
 * [Account API](https://developer.vonage.com/en/account/overview)
 * [Application API](https://developer.vonage.com/en/application/overview)
+* [Conversation API](https://developer.vonage.com/en/conversation/overview)
 * [Meetings API](https://developer.vonage.com/en/meetings/overview)
 * [Messages API](https://developer.vonage.com/en/messages/overview)
 * [Number Insight API](https://developer.vonage.com/en/number-insight/overview)

lib/vonage/client.rb

@@ -40,8 +40,17 @@ def applications
       @applications ||= T.let(Applications.new(config), T.nilable(Vonage::Applications))
     end
 
+    # @return [Conversation]
+    #
+    sig { returns(T.nilable(Vonage::Conversation)) }
+    def conversation
+      @conversation ||= T.let(Conversation.new(config), T.nilable(Vonage::Conversation))
+    end
+
     # @return [Conversations]
     #
+    # @deprecated Please use {#conversation} instead
+    #
     sig { returns(T.nilable(Vonage::Conversations)) }
     def conversations
       @conversations ||= T.let(Conversations.new(config), T.nilable(Vonage::Conversations))

lib/vonage/conversation.rb

@@ -0,0 +1,164 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Vonage
+  class Conversation < Namespace
+    extend T::Sig
+
+    self.authentication = BearerToken
+
+    self.request_body = JSON
+
+    # List conversations associated with a Vonage application.
+    #
+    # @example
+    #   response = client.conversation.list
+    #
+    # @param [String] :date_start
+    #   Return the records that occurred after this point in time.
+    #
+    # @param [String] :date_end
+    #   Return the records that occurred before this point in time.
+    #
+    # @param [Integer] :page_size
+    #   Return this amount of records in the response.
+    #
+    # @param ['asc', 'desc'] :order
+    #   Return the records in ascending or descending order.
+    #
+    # @param [String] :cursor
+    #   The cursor to start returning results from.
+    #  
+    # @return [Conversation::ListResponse]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#listConversations
+    #
+    def list(**params)
+      request('/v1/conversations', params: params, response_class: ListResponse)
+    end
+
+    # Create a conversation.
+    #
+    # @example
+    #   response = client.conversation.create(name: 'Example Conversation', display_name: 'Example Display Name')
+    #
+    # @param [String] :name
+    #   Your internal conversation name. Must be unique.
+    #
+    # @param [String] :display_name
+    #   The public facing name of the conversation.
+    #
+    # @param [String] :image_url
+    #   An image URL that you associate with the conversation
+    #
+    # @param [Hash] :properties
+    #   - :ttl (Integer) After how many seconds an empty conversation is deleted
+    #   - :type (String)
+    #   - :custom_sort_key (String)
+    #   - :custom_data (Hash) Custom key/value pairs to be included with conversation data
+    #
+    # @option params [Array] :numbers An array of Hashes containing number information for different channels.
+    #
+    # @option params [Hash] :callback
+    #   - @option callback :url (String)
+    #   - @option callback :event_mask (String)
+    #   - @option callback :params (Hash)
+    #     - @option params :applicationId (String)
+    #     - @option params :ncco_url (String)
+    #   - @option callback :method (String) Must be one of ['POST', 'GET']
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#createConversation
+    #
+    def create(**params)
+      request('/v1/conversations', params: params, type: Post)
+    end
+
+    # Retrieve a conversation.
+    #
+    # @example
+    #   response = client.conversation.find(conversation_id: 'CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a')
+    #
+    # @param [String] :conversation_id
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#retrieveConversation
+    #
+    def find(conversation_id:)
+      request("/v1/conversations/#{conversation_id}")
+    end
+
+    # Update a conversation.
+    #
+    # @example
+    #   response = client.conversation.update(conversation_id: 'CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a', display_name: 'Updated conversation')
+    #
+    # @param [String] :name
+    #   Your internal conversation name. Must be unique.
+    #
+    # @param [String] :display_name
+    #   The public facing name of the conversation.
+    #
+    # @param [String] :image_url
+    #   An image URL that you associate with the conversation
+    #
+    # @param [Hash] :properties
+    #   - @option properties :ttl (Integer) After how many seconds an empty conversation is deleted
+    #   - @option properties :type (String)
+    #   - @option properties :custom_sort_key (String)
+    #   - @option properties :custom_data (Hash) Custom key/value pairs to be included with conversation data
+    #
+    # @param [Array] :numbers An array of Hashes containing number information for different channels.
+    #
+    # @option params [Hash] :callback
+    #   - @option callback :url (String)
+    #   - @option callback :event_mask (String)
+    #   - @option callback :params (Hash)
+    #     - @option params :applicationId (String)
+    #     - @option params :ncco_url (String)
+    #   - @option callback :method (String) Must be one of ['POST', 'GET']
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#replaceConversation
+    #
+    def update(conversation_id:, **params)
+      request("/v1/conversations/#{conversation_id}", params: params, type: Put)
+    end
+
+    # Delete a conversation.
+    #
+    # @example
+    #   response = client.conversation.delete(conversation_id: 'CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a')
+    #
+    # @param [String] :conversation_id
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#deleteConversation
+    #
+    def delete(conversation_id:)
+      request("/v1/conversations/#{conversation_id}", type: Delete)
+    end
+
+    # @return [Conversation::User]
+    sig { returns(T.nilable(Vonage::Conversation::User)) }
+    def user
+      @user ||= User.new(@config)
+    end
+
+    # @return [Conversation::Member]
+    sig { returns(T.nilable(Vonage::Conversation::Member)) }
+    def member
+      @member ||= Member.new(@config)
+    end
+
+    # @return [Conversation::Event]
+    sig { returns(T.nilable(Vonage::Conversation::Event)) }
+    def event
+      @event ||= Event.new(@config)
+    end
+  end
+end

lib/vonage/conversation/event.rb

@@ -0,0 +1,108 @@
+# typed: true
+# frozen_string_literal: true
+
+module Vonage
+  class Conversation::Event < Namespace
+    self.authentication = BearerToken
+
+    self.request_body = JSON
+
+    # List conversation events
+    #
+    # @example
+    #   response = client.conversation.event.list(conversation_id: 'CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a')
+    #
+    # @param [required, String] :conversation_id The conversation_id of the conversation to list events for
+    #
+    # @param [String] :start_id
+    #   The ID to start returning events at
+    #
+    # @param [String] :end_id
+    #   The ID to end returning events at
+    #
+    # @param [String] :event_type
+    #  The type of event to search for. Does not currently support custom events
+    #
+    # @param [Integer] :page_size
+    #   Return this amount of records in the response.
+    #
+    # @param ['asc', 'desc'] :order
+    #   Return the records in ascending or descending order.
+    #
+    # @param [String] :cursor
+    #   The cursor to start returning results from.
+    #
+    # @return [Conversation::Member::ListResponse]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#getEvents
+    #
+    def list(conversation_id:, **params)  
+      request("/v1/conversations/#{conversation_id}/events", params: params, response_class: ListResponse)
+    end
+
+    # Create an event
+    # @example
+    #   response = client.conversation.event.create(
+    #     conversation_id: 'CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a',
+    #     type: 'message',
+    #     body: {
+    #       message_type: 'text',
+    #       text: 'Hello World'
+    #     }
+    #   )  
+    #
+    # @param [required, String] :conversation_id The conversation_id of the conversation to create the event for
+    #
+    # @param [required, String] :type
+    #   Event type.
+    #
+    # @param [String] :from
+    #
+    # @option params [required, String] :from
+    #
+    # @param [Hash] :body
+    #   The body of the event. There are many possible properties depending on the event type and message_type
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#createEvent
+    #
+    def create(conversation_id:, **params)
+      request("/v1/conversations/#{conversation_id}/events", params: params, type: Post)
+    end
+
+    # Get details of a specific event
+    #
+    # @example
+    #   response = client.conversation.event.find(conversation_id: 'CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a', event_id: 1) 
+    #
+    # @param [required, String] :conversation_id
+    #
+    # @param [required, String] :event_id
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#getEvent
+    #
+    def find(conversation_id:, event_id:)
+      request("/v1/conversations/#{conversation_id}/events/#{event_id}")
+    end
+
+    # Delete an event.
+    #
+    # @example
+    #   response = client.conversation.event.delete(conversation_id: 'CON-d66d47de-5bcb-4300-94f0-0c9d4b948e9a', event_id: 1)
+    #
+    # @param [String] :conversation_id
+    #
+    # @param [String] :event_id
+    #
+    # @return [Response]
+    #
+    # @see https://developer.vonage.com/en/api/conversation#deleteEvent
+    #
+    def delete(conversation_id:, event_id:)
+      request("/v1/conversations/#{conversation_id}/events/#{event_id}", type: Delete)
+    end
+  end
+end

lib/vonage/conversation/event/list_response.rb

@@ -0,0 +1,11 @@
+# typed: true
+
+class Vonage::Conversation::Event::ListResponse < Vonage::Response
+  include Enumerable
+
+  def each
+    return enum_for(:each) unless block_given?
+
+    @entity._embedded.each { |item| yield item }
+  end
+end

lib/vonage/conversation/list_response.rb

@@ -0,0 +1,11 @@
+# typed: true
+
+class Vonage::Conversation::ListResponse < Vonage::Response
+  include Enumerable
+
+  def each
+    return enum_for(:each) unless block_given?
+
+    @entity._embedded.conversations.each { |item| yield item }
+  end
+end