sentdm 0.34.0 → 0.36.0

data/lib/sentdm/models/webhook_list_events_response.rb

@@ -48,7 +48,7 @@ module Sentdm
       #   handler that rejects an envelope it does not recognise will break on the next
       #   addition rather than ignore it.
       #
-      #   @return [Sentdm::Models::MessageEvent, Sentdm::Models::InboundMessageEvent, Sentdm::Models::TemplateEvent, Sentdm::Models::ChannelEvent, Sentdm::Models::ContactEvent, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload, nil]
+      #   @return [Sentdm::Models::MessageEvent, Sentdm::Models::InboundMessageEvent, Sentdm::Models::TemplateEvent, Sentdm::Models::ChannelEvent, Sentdm::Models::ContactEvent, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload, Sentdm::Models::CallEvent, nil]
       optional :event_data, union: -> { Sentdm::Models::WebhookListEventsResponse::EventData }
 
       # @!attribute event_type
@@ -90,7 +90,7 @@ module Sentdm
       #
       #   @param error_message [String, nil]
       #
-      #   @param event_data [Sentdm::Models::MessageEvent, Sentdm::Models::InboundMessageEvent, Sentdm::Models::TemplateEvent, Sentdm::Models::ChannelEvent, Sentdm::Models::ContactEvent, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload] The exact event body that was delivered, or attempted, for this record. One of t
+      #   @param event_data [Sentdm::Models::MessageEvent, Sentdm::Models::InboundMessageEvent, Sentdm::Models::TemplateEvent, Sentdm::Models::ChannelEvent, Sentdm::Models::ContactEvent, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload, Sentdm::Models::CallEvent] The exact event body that was delivered, or attempted, for this record. One of t
       #
       #   @param event_type [String]
       #
@@ -150,7 +150,7 @@ module Sentdm
 
         # The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares this shape and
         # varies only in Payload.
-        variant -> { Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload }
+        variant -> { Sentdm::CallEvent }
 
         class SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload < Sentdm::Internal::Type::BaseModel
           # @!attribute event
@@ -437,177 +437,8 @@ module Sentdm
           end
         end
 
-        class SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload < Sentdm::Internal::Type::BaseModel
-          # @!attribute event
-          #   The specific event within the family, for example message.delivered,
-          #   message.received or contact.opt_out. Absent on events that have no subtype, so
-          #   treat it as optional.
-          #
-          #   @return [String, nil]
-          optional :event, String, nil?: true
-
-          # @!attribute field
-          #   The event family, for example message, templates or contact. Route on this
-          #   first, then on event for the specific change.
-          #
-          #   @return [String, nil]
-          optional :field, String
-
-          # @!attribute payload
-          #   Body of a call.initiated, call.answered, call.completed, call.failed or
-          #   call.recording_ready event. Which of them occurred is the envelope's event.
-          #
-          #   Shaped like the message, inbound, template and channel payloads: account_id
-          #   names the account the event is about, channel names the channel, and updated_at
-          #   is when the change happened on the call, in the same yyyy-MM-ddTHH:mm:ssZ form.
-          #   duration_seconds and price are added on call.completed, reason on call.failed
-          #   and recording_id on call.recording_ready; each is omitted rather than sent as
-          #   null when it does not apply.
-          #
-          #   Casing is snake_case because these ride the same webhook stream customers
-          #   already parse message_id from; the question/answer contract is a separate
-          #   surface and stays camelCase. Nothing here is provider-shaped: no provider call
-          #   id, no namespaced identity.
-          #
-          #   @return [Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload::Payload, nil]
-          optional :payload,
-                   -> { Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload::Payload },
-                   nil?: true
-
-          # @!attribute request_id
-          #   The event-specific body.
-          #
-          #   @return [String, nil]
-          optional :request_id, String, nil?: true
-
-          # @!attribute timestamp
-          #   When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
-          #   time, not the time the underlying change happened. Use the timestamp inside the
-          #   payload for the latter.
-          #
-          #   @return [String, nil]
-          optional :timestamp, String
-
-          # @!method initialize(event: nil, field: nil, payload: nil, request_id: nil, timestamp: nil)
-          #   Some parameter documentations has been truncated, see
-          #   {Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload}
-          #   for more details.
-          #
-          #   The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
-          #   this shape and varies only in Payload.
-          #
-          #   @param event [String, nil] The specific event within the family, for example message.delivered,
-          #
-          #   @param field [String] The event family, for example message, templates or contact. Route on
-          #
-          #   @param payload [Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload::Payload, nil] Body of a call.initiated, call.answered, call.completed, call.failed
-          #
-          #   @param request_id [String, nil] The event-specific body.
-          #
-          #   @param timestamp [String] When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
-
-          # @see Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload#payload
-          class Payload < Sentdm::Internal::Type::BaseModel
-            # @!attribute call_id
-            #   Sent's call id, the same one the customer saw on the first question.
-            #
-            #   @return [String]
-            required :call_id, String
-
-            # @!attribute account_id
-            #   The account the call belongs to: the key's own customer, or the sender profile
-            #   it acted as.
-            #
-            #   @return [String, nil]
-            optional :account_id, String
-
-            # @!attribute channel
-            #   Always voice.
-            #
-            #   @return [String, nil]
-            optional :channel, String
-
-            # @!attribute duration_seconds
-            #   How long the call lasted. Only on call.completed.
-            #
-            #   @return [Integer, nil]
-            optional :duration_seconds, Integer, nil?: true
-
-            # @!attribute number
-            #   The customer number that owns the call, in E.164 format.
-            #
-            #   @return [String, nil]
-            optional :number, String
-
-            # @!attribute price
-            #   What the call was charged. Only on call.completed, and omitted there until
-            #   billing has recorded the charge.
-            #
-            #   @return [Float, nil]
-            optional :price, Float, nil?: true
-
-            # @!attribute reason
-            #   The machine-readable reason the call did not complete. Only on call.failed, and
-            #   omitted when no reason was recorded.
-            #
-            #   @return [String, nil]
-            optional :reason, String, nil?: true
-
-            # @!attribute recording_id
-            #   The recording that became available, the same id GET /v3/calls/{id}/recordings
-            #   lists it under. Only on call.recording_ready, which is sent once per recording.
-            #
-            #   @return [String, nil]
-            optional :recording_id, String, nil?: true
-
-            # @!attribute updated_at
-            #   When the change happened on the call, as opposed to when the event was emitted.
-            #
-            #   @return [String, nil]
-            optional :updated_at, String
-
-            # @!method initialize(call_id:, account_id: nil, channel: nil, duration_seconds: nil, number: nil, price: nil, reason: nil, recording_id: nil, updated_at: nil)
-            #   Some parameter documentations has been truncated, see
-            #   {Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload::Payload}
-            #   for more details.
-            #
-            #   Body of a call.initiated, call.answered, call.completed, call.failed or
-            #   call.recording_ready event. Which of them occurred is the envelope's event.
-            #
-            #   Shaped like the message, inbound, template and channel payloads: account_id
-            #   names the account the event is about, channel names the channel, and updated_at
-            #   is when the change happened on the call, in the same yyyy-MM-ddTHH:mm:ssZ form.
-            #   duration_seconds and price are added on call.completed, reason on call.failed
-            #   and recording_id on call.recording_ready; each is omitted rather than sent as
-            #   null when it does not apply.
-            #
-            #   Casing is snake_case because these ride the same webhook stream customers
-            #   already parse message_id from; the question/answer contract is a separate
-            #   surface and stays camelCase. Nothing here is provider-shaped: no provider call
-            #   id, no namespaced identity.
-            #
-            #   @param call_id [String] Sent's call id, the same one the customer saw on the first question.
-            #
-            #   @param account_id [String] The account the call belongs to: the key's own customer, or the sender profile i
-            #
-            #   @param channel [String] Always voice.
-            #
-            #   @param duration_seconds [Integer, nil] How long the call lasted. Only on call.completed.
-            #
-            #   @param number [String] The customer number that owns the call, in E.164 format.
-            #
-            #   @param price [Float, nil] What the call was charged. Only on call.completed, and omitted there until billi
-            #
-            #   @param reason [String, nil] The machine-readable reason the call did not complete. Only on call.failed, and
-            #
-            #   @param recording_id [String, nil] The recording that became available, the same id GET /v3/calls/{id}/recordings l
-            #
-            #   @param updated_at [String] When the change happened on the call, as opposed to when the event was emitted.
-          end
-        end
-
         # @!method self.variants
-        #   @return [Array(Sentdm::Models::MessageEvent, Sentdm::Models::InboundMessageEvent, Sentdm::Models::TemplateEvent, Sentdm::Models::ChannelEvent, Sentdm::Models::ContactEvent, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfCallWebhookPayload)]
+        #   @return [Array(Sentdm::Models::MessageEvent, Sentdm::Models::InboundMessageEvent, Sentdm::Models::TemplateEvent, Sentdm::Models::ChannelEvent, Sentdm::Models::ContactEvent, Sentdm::Models::WebhookListEventsResponse::EventData::SentDmServicesCommonServicesWebhooksContractsWebhookEventOfLinkWebhookPayload, Sentdm::Models::CallEvent)]
       end
     end
   end

data/lib/sentdm/models.rb

@@ -41,6 +41,12 @@ module Sentdm
 
   APIMeta = Sentdm::Models::APIMeta
 
+  APIResponseOfCall = Sentdm::Models::APIResponseOfCall
+
+  APIResponseOfCallRecordings = Sentdm::Models::APIResponseOfCallRecordings
+
+  APIResponseOfCallsList = Sentdm::Models::APIResponseOfCallsList
+
   APIResponseOfContact = Sentdm::Models::APIResponseOfContact
 
   APIResponseOfContactMessageSummary = Sentdm::Models::APIResponseOfContactMessageSummary
@@ -67,10 +73,40 @@ module Sentdm
 
   BrandsBrandData = Sentdm::Models::BrandsBrandData
 
+  Call = Sentdm::Models::Call
+
+  CallEvent = Sentdm::Models::CallEvent
+
+  CallEventPayload = Sentdm::Models::CallEventPayload
+
+  CallHangupParams = Sentdm::Models::CallHangupParams
+
+  CallListParams = Sentdm::Models::CallListParams
+
+  CallListRecordingsParams = Sentdm::Models::CallListRecordingsParams
+
+  CallParty = Sentdm::Models::CallParty
+
+  CallRecording = Sentdm::Models::CallRecording
+
+  CallRecordings = Sentdm::Models::CallRecordings
+
+  CallRecordParams = Sentdm::Models::CallRecordParams
+
+  CallRetrieveParams = Sentdm::Models::CallRetrieveParams
+
+  Calls = Sentdm::Models::Calls
+
+  CallsList = Sentdm::Models::CallsList
+
+  CallTimelineEntry = Sentdm::Models::CallTimelineEntry
+
   ChannelEvent = Sentdm::Models::ChannelEvent
 
   ChannelEventPayload = Sentdm::Models::ChannelEventPayload
 
+  Channels = Sentdm::Models::Channels
+
   ContactCreateParams = Sentdm::Models::ContactCreateParams
 
   ContactDeleteParams = Sentdm::Models::ContactDeleteParams

data/lib/sentdm/resources/calls/participants.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Resources
+    class Calls
+      # Phone calls from the numbers you hold, driven by your own callback URL.
+      #
+      # `POST /v3/channels/voice` enables a number for calls, with the callback URL Sent
+      # asks what to do with each call on it, and `POST /v3/channels/voice/tokens` mints
+      # a short-lived token that lets a user of your app place and receive calls as that
+      # number. When a call arrives or a caller presses a key, a signed question is
+      # POSTed to the callback URL and the answer decides the call;
+      # `POST /v3/channels/voice/{number}/test` checks the URL answers the way we need
+      # before a real call reaches it, and
+      # `POST /v3/channels/voice/{number}/rotate-secret` replaces the signing secret.
+      # The call events themselves (`call.completed` and the rest) arrive through your
+      # webhooks.
+      #
+      # Every call is a record under `/v3/calls`: read it, list its recordings once one
+      # is ready, hang it up, start or stop recording, and add, mute or remove
+      # conference participants while it is live. A leg to a phone number runs for at
+      # most what your balance affords at the destination's rate.
+      class Participants
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Calls::ParticipantUpdateParams} for more details.
+        #
+        # Mutes or unmutes one participant of the conference room a live call is in, named
+        # by the participant's own call id from the participants list: send muted true to
+        # silence them, muted false to let them be heard again. Muting a participant who
+        # is already muted succeeds, as does unmuting one who is not. A participant who is
+        # not in this call's room answers 404. A call that has ended answers 409, as does
+        # a call that is not in a conference.
+        #
+        # @overload update(participant_id, id:, muted: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param participant_id [String] Path param: The participant's own call id from the route, as listed by the parti
+        #
+        # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+        #
+        # @param muted [Boolean] Body param: true to mute the participant, false to unmute them
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Sentdm::Models::Calls::ParticipantUpdateParams
+        def update(participant_id, params)
+          parsed, options = Sentdm::Calls::ParticipantUpdateParams.dump_request(params)
+          id =
+            parsed.delete(:id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :patch,
+            path: ["v3/calls/%1$s/participants/%2$s", id, participant_id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Calls::ParticipantListParams} for more details.
+        #
+        # Lists who is in the conference room one of your live calls is in: each
+        # participant's own call id, who they are, whether the room mutes them, and how
+        # long they have been connected. The call itself is one of the participants. Use a
+        # participant's id to mute or remove them; it is also a call id, so GET
+        # /v3/calls/{id} accepts it. A call that has ended answers 409, as does a call
+        # that is not in a conference.
+        #
+        # @overload list(id, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] The call id from the route, as carried by call webhooks and the calls list, for
+        #
+        # @param x_profile_id [String] Profile UUID to scope the request to a child profile. Only organization API keys
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Sentdm::Models::Calls::APIResponseOfListOfCallParticipant]
+        #
+        # @see Sentdm::Models::Calls::ParticipantListParams
+        def list(id, params = {})
+          parsed, options = Sentdm::Calls::ParticipantListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: ["v3/calls/%1$s/participants", id],
+            headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+            model: Sentdm::Calls::APIResponseOfListOfCallParticipant,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Calls::ParticipantAddParams} for more details.
+        #
+        # Dials one of your app users or a phone number into a call that is in a
+        # conference room, and answers with the participant's own call record. The
+        # participant is a call of their own: it has its own id, can be looked up and hung
+        # up, and is billed and reported through call.completed and call.failed like any
+        # other call. Every participant needs a positive balance. A phone participant is
+        # called from caller_id, which must be one of your numbers, or from the call's
+        # owning number when omitted, and needs a destination you may call. Only a call
+        # your answer connected to a conference can take participants: a call connected to
+        # a user or a number answers 409.
+        #
+        # @overload add(id, caller_id: nil, sandbox: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+        #
+        # @param caller_id [String, nil] Body param: The number shown to a phone participant as the caller, in E.164 form
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param to [Sentdm::Models::Calls::CallParticipantTarget] Body param: A participant to add to a call
+        #
+        # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [Sentdm::Models::APIResponseOfCall]
+        #
+        # @see Sentdm::Models::Calls::ParticipantAddParams
+        def add(id, params = {})
+          parsed, options = Sentdm::Calls::ParticipantAddParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: ["v3/calls/%1$s/participants", id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Sentdm::APIResponseOfCall,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Calls::ParticipantRemoveParams} for more details.
+        #
+        # Removes one participant from the conference room a live call is in, named by the
+        # participant's own call id from the participants list. Their leg ends and is
+        # reported through call.completed like any other call; everyone else stays
+        # connected. A participant who is not in this call's room answers 404. A call that
+        # has ended answers 409, as does a call that is not in a conference.
+        #
+        # @overload remove(participant_id, id:, sandbox: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param participant_id [String] Path param: The participant's own call id from the route, as listed by the parti
+        #
+        # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Sentdm::Models::Calls::ParticipantRemoveParams
+        def remove(participant_id, params)
+          parsed, options = Sentdm::Calls::ParticipantRemoveParams.dump_request(params)
+          id =
+            parsed.delete(:id) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          header_params = {x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :delete,
+            path: ["v3/calls/%1$s/participants/%2$s", id, participant_id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Calls::ParticipantRemoveAllParams} for more details.
+        #
+        # Removes every participant from the conference room a live call is in, the call
+        # itself included. Every leg ends and is reported through call.completed like any
+        # other call. A room that is already empty answers 204 as well. A call that has
+        # ended answers 409, as does a call that is not in a conference.
+        #
+        # @overload remove_all(id, sandbox: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param id [String] Path param: The call id from the route, as carried by call webhooks and the call
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+        #
+        # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+        #
+        # @return [nil]
+        #
+        # @see Sentdm::Models::Calls::ParticipantRemoveAllParams
+        def remove_all(id, params = {})
+          parsed, options = Sentdm::Calls::ParticipantRemoveAllParams.dump_request(params)
+          header_params = {x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :delete,
+            path: ["v3/calls/%1$s/participants", id],
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: NilClass,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Sentdm::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end