nexmo 5.8.0 → 5.9.0

data/lib/nexmo/conversation_events.rb

@@ -6,18 +6,65 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Create an event.
+    #
+    # @option params [required, String] :type
+    #   Event type.
+    #
+    # @option params [String] :to
+    #   Member ID.
+    #
+    # @option params [required, String] :from
+    #   Member ID.
+    #
+    # @option params [Hash] :body
+    #   Event Body.
+    #
+    # @param [String] conversation_id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#createEvent
+    #
     def create(conversation_id, params)
       request('/beta/conversations/' + conversation_id + '/events', params: params, type: Post)
     end
 
+    # List events.
+    #
+    # @param [String] conversation_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#getEvents
+    #
     def list(conversation_id)
       request('/beta/conversations/' + conversation_id + '/events')
     end
 
+    # Retrieve an event.
+    #
+    # @param [String] conversation_id
+    # @param [String] event_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#getEvent
+    #
     def get(conversation_id, event_id)
       request('/beta/conversations/' + conversation_id + '/events/' + event_id.to_s)
     end
 
+    # Delete an event.
+    #
+    # @param [String] conversation_id
+    # @param [String] event_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#deleteEvent
+    #
     def delete(conversation_id, event_id)
       request('/beta/conversations/' + conversation_id + '/events/' + event_id.to_s, type: Delete)
     end

data/lib/nexmo/conversation_legs.rb

@@ -4,10 +4,24 @@ module Nexmo
   class ConversationLegs < Namespace
     self.authentication = BearerToken
 
+    # List legs.
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#listLegs
+    #
     def list
       request('/beta/legs')
     end
 
+    # Delete a leg.
+    #
+    # @param [String] leg_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#deleteLeg
+    #
     def delete(leg_id)
       request('/beta/legs/' + leg_id, type: Delete)
     end

data/lib/nexmo/conversation_members.rb

@@ -6,22 +6,96 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Create a member.
+    #
+    # @option params [String] :action
+    #   Invite or join a member to a conversation.
+    #   Must be one of: `invite` or `join`.
+    #
+    # @option params [required, String] :user_id
+    #   User ID.
+    #
+    # @option params [String] :member_id
+    #   Member ID.
+    #
+    # @option params [required, Hash] :channel
+    #   A user who joins a conversation as a member can have one channel per membership type.
+    #
+    # @option params [Hash] :media
+    #   Media Object.
+    #
+    # @option params [String] :knocking_id
+    #   Knocker ID.
+    #   A knocker is a pre-member of a conversation who does not exist yet.
+    #
+    # @option params [String] :member_id_inviting
+    #   Member ID of the member that sends the invitation.
+    #
+    # @param [String] conversation_id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#createMember
+    #
     def create(conversation_id, params)
       request('/beta/conversations/' + conversation_id + '/members', params: params, type: Post)
     end
 
+    # List members.
+    #
+    # @param [String] conversation_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#getMembers
+    #
     def list(conversation_id)
       request('/beta/conversations/' + conversation_id + '/members')
     end
 
+    # Retrieve a member.
+    #
+    # @param [String] conversation_id
+    # @param [String] member_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#getMember
+    #
     def get(conversation_id, member_id)
       request('/beta/conversations/' + conversation_id + '/members/' + member_id)
     end
 
+    # Update a member.
+    #
+    # @option params [String] :action
+    #   Invite or join a member to a conversation.
+    #
+    # @option params [Hash] :channel
+    #   A user who joins a conversation as a member can have one channel per membership type.
+    #
+    # @param [String] conversation_id
+    # @param [String] member_id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#updateMember
+    #
     def update(conversation_id, member_id, params)
       request('/beta/conversations/' + conversation_id + '/members/' + member_id, params: params, type: Put)
     end
 
+    # Delete a member.
+    #
+    # @param [String] conversation_id
+    # @param [String] member_id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#deleteMember
+    #
     def delete(conversation_id, member_id)
       request('/beta/conversations/' + conversation_id + '/members/' + member_id, type: Delete)
     end

data/lib/nexmo/conversation_users.rb

@@ -6,22 +6,85 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Create a user.
+    #
+    # @option params [String] :name
+    #   Unique name for a user.
+    #
+    # @option params [String] :display_name
+    #   A string to be displayed as user name.
+    #   It does not need to be unique.
+    #
+    # @option params [String] :image_url
+    #   A link to an image for conversations' and users' avatars.
+    #
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#createUser
+    #
     def create(params)
       request('/beta/users', params: params, type: Post)
     end
 
+    # List users.
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#getUsers
+    #
     def list
       request('/beta/users')
     end
 
+    # Retrieve a user.
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#getUser
+    #
     def get(id)
       request('/beta/users/' + id)
     end
 
+    # Update a user.
+    #
+    # @option params [String] :name
+    #   Unique name for a user.
+    #
+    # @option params [String] :display_name
+    #   A string to be displayed as user name.
+    #   It does not need to be unique.
+    #
+    # @option params [String] :image_url
+    #   A link to an image for conversations' and users' avatars.
+    #
+    # @option params [Hash] :channels
+    #   A user who joins a conversation as a member can have one channel per membership type.
+    #   Channels can be `app`, `phone`, `sip`, `websocket`, or `vbc`.
+    #
+    # @param [String] id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#updateUser
+    #
     def update(id, params)
       request('/beta/users/' + id, params: params, type: Put)
     end
 
+    # Delete a user.
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#deleteUser
+    #
     def delete(id)
       request('/beta/users/' + id, type: Delete)
     end

data/lib/nexmo/conversations.rb

@@ -6,38 +6,148 @@ module Nexmo
 
     self.request_body = JSON
 
+    # Create a conversation.
+    #
+    # @example
+    #   response = client.conversations.create(name: 'Example Conversation', display_name: 'Example Display Name')
+    #
+    # @option params [String] :name
+    #   Unique name for a conversation.
+    #
+    # @option params [String] :display_name
+    #   The display name for the conversation.
+    #   It does not have to be unique.
+    #
+    # @option params [String] :image_url
+    #   A link to an image for conversations' and users' avatars.
+    #
+    # @option params [Hash] :numbers
+    #   - **:sms** (String) phone number used for sms channel
+    #   - **:pstn** (String) phone number used for pstn channel
+    #
+    # @option params [Hash] :properties
+    #   - **:ttl** (Integer) After how many seconds an empty conversation is deleted
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#createConversation
+    #
     def create(params)
       request('/beta/conversations', params: params, type: Post)
     end
 
+    # List all conversations associated with your application.
+    #
+    # @example
+    #   response = client.conversations.list
+    #
+    # @option params [String] :date_start
+    #   Return the records that occurred after this point in time.
+    #
+    # @option params [String] :date_end
+    #   Return the records that occurred before this point in time.
+    #
+    # @option params [Integer] :page_size
+    #   Return this amount of records in the response.
+    #
+    # @option params [Integer] :record_index
+    #   Return calls from this index in the response.
+    #
+    # @option params ['asc', 'desc'] :order
+    #   Return the records in ascending or descending order.
+    #
+    # @param [Hash, nil] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#replaceConversation
+    #
     def list(params = nil)
       request('/beta/conversations', params: params)
     end
 
+    # Retrieve a conversation.
+    #
+    # @example
+    #   response = client.conversations.get(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#retrieveConversation
+    #
     def get(id)
       request('/beta/conversations/' + id)
     end
   
+    # Update a conversation.
+    #
+    # @example
+    #   response = client.conversations.update(id, display_name: 'Updated conversation')
+    #
+    # @option params [String] :name
+    #   Unique name for a conversation
+    #
+    # @option params [String] :display_name
+    #   The display name for the conversation.
+    #
+    # @option params [String] :image_url
+    #   A link to an image for conversations' and users' avatars.
+    #
+    # @option params [Hash] :numbers
+    #   - **:sms** (String) phone number used for sms channel
+    #   - **:pstn** (String) phone number used for pstn channel
+    #
+    # @option params [Hash] :properties
+    #   - **:ttl** (Integer) After how many seconds an empty conversation is deleted
+    #
+    # @param [String] id
+    # @param [Hash] params
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#replaceConversation
+    #
     def update(id, params)
       request('/beta/conversations/' + id, params: params, type: Put)
     end
 
+    # Delete a conversation.
+    #
+    # @example
+    #   response = client.conversations.delete(id)
+    #
+    # @param [String] id
+    #
+    # @return [Entity]
+    #
+    # @see https://developer.nexmo.com/api/conversation#deleteConversation
+    #
     def delete(id)
       request('/beta/conversations/' + id, type: Delete)
     end
 
+    # @return [ConversationEvents]
+    #
     def events
       @events ||= ConversationEvents.new(@client)
     end
 
+    # @return [ConversationLegs]
+    #
     def legs
       @legs ||= ConversationLegs.new(@client)
     end
 
+    # @return [ConversationMembers]
+    #
     def members
       @members ||= ConversationMembers.new(@client)
     end
 
+    # @return [ConversationUsers]
+    #
     def users
       @users ||= ConversationUsers.new(@client)
     end

data/lib/nexmo/errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+require 'json'
+
+module Nexmo
+  module Errors
+    def self.parse(response)
+      exception_class = case response
+        when Net::HTTPUnauthorized
+          AuthenticationError
+        when Net::HTTPClientError
+          ClientError
+        when Net::HTTPServerError
+          ServerError
+        else
+          Error
+        end
+
+      message = if response.content_type == 'application/json'
+        hash = ::JSON.parse(response.body)
+
+        if hash.key?('error_title')
+          hash['error_title']
+        elsif problem_details?(hash)
+          problem_details_message(hash)
+        end
+      end
+
+      exception_class.new(message)
+    end
+
+    def self.problem_details?(hash)
+      hash.key?('title') && hash.key?('detail') && hash.key?('type')
+    end
+
+    def self.problem_details_message(hash)
+      "#{hash['title']}. #{hash['detail']} See #{hash['type']} for more info, or email support@nexmo.com if you have any questions."
+    end
+  end
+
+  private_constant :Errors
+end