sentdm 0.31.0 → 0.33.0

data/rbi/sentdm/models/contact_event_payload.rbi

@@ -0,0 +1,254 @@
+# typed: strong
+
+module Sentdm
+  module Models
+    class ContactEventPayload < Sentdm::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Sentdm::ContactEventPayload, Sentdm::Internal::AnyHash)
+        end
+
+      # Whether the contact is opted out after this signal — the state to write to your
+      # own record. Same meaning as opt_out on the contact resource. On contact.help and
+      # contact.custom_keyword this reports the contact's existing state, which neither
+      # changes.
+      #
+      # Two signals from the same contact can arrive out of order, because each one is
+      # queued on its own rather than against the contact. Compare the envelope's
+      # timestamp before you overwrite a newer state with an older one. That timestamp
+      # is second-precision, so treat two signals stamped in the same second as
+      # unordered and read the contact resource to settle them.
+      sig { returns(T::Boolean) }
+      attr_accessor :opt_out
+
+      # How the signal reached us. INBOUND_KEYWORD means the contact sent a message
+      # whose text matched one of the keywords; PROVIDER_SIGNAL means the network
+      # reported it. A provider signal usually carries no message_id or text, so read
+      # both for null rather than inferring them from this field.
+      sig { returns(String) }
+      attr_accessor :source
+
+      # The account the contact belongs to. Present so one endpoint can serve several
+      # accounts.
+      sig { returns(T.nilable(String)) }
+      attr_reader :account_id
+
+      sig { params(account_id: String).void }
+      attr_writer :account_id
+
+      # The RCS agent the signal reached, when it reached one.
+      #
+      # Omitted entirely on channels that have no agent, rather than sent as null — an
+      # SMS or WhatsApp payload does not carry this key at all. On RCS it is the
+      # counterpart to To: a contact reaches an agent rather than a number, so exactly
+      # one of the two is populated and never both. If you run more than one agent, this
+      # is what tells you which of them the contact acted on.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :agent_id
+
+      # The channel the signal arrived on, for example sms or whatsapp.
+      sig { returns(T.nilable(String)) }
+      attr_reader :channel
+
+      sig { params(channel: String).void }
+      attr_writer :channel
+
+      # The contact who raised the signal. Always populated, including for contact.help
+      # or contact.custom_keyword from a number you have not messaged before — the
+      # contact is created if it does not exist yet, so this identifier is always
+      # resolvable against the contacts API.
+      sig { returns(T.nilable(String)) }
+      attr_reader :contact_id
+
+      sig { params(contact_id: String).void }
+      attr_writer :contact_id
+
+      # The contact's number, in E.164 format with the leading + — who raised the
+      # signal. The same party message.received publishes as inbound_number.
+      sig { returns(T.nilable(String)) }
+      attr_reader :from
+
+      sig { params(from: String).void }
+      attr_writer :from
+
+      # The inbound message that carried the signal, matching message_id on the
+      # corresponding message.received event so the two can be joined.
+      #
+      # Sent as null when the signal did not arrive as a message — for example when a
+      # network processed an opt-out on your behalf — and also when the message belongs
+      # to a different account than this event, which can happen on a shared WhatsApp
+      # number. The field is always present, so read it and check for null rather than
+      # checking whether the key exists.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :message_id
+
+      # The auto-reply template whose keyword the contact matched, joinable against the
+      # templates API.
+      #
+      # This is what identifies which signal arrived on contact.custom_keyword: every
+      # custom template reports the same event name, so the event alone cannot tell your
+      # booking keyword from your opening-hours one. One template holds as many keywords
+      # as you configured, so this is steadier to switch on than text.
+      #
+      # Populated on the compliance sub-types too, where it names the template that
+      # replied. Sent as null when no template was involved — a network-reported opt-out
+      # matches no keyword. The field is always present, so read it and check for null.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :template_id
+
+      # The text the contact sent, for example STOP or UNSUBSCRIBE. Sent as null when
+      # the signal did not arrive as text. The field is always present, so read it and
+      # check for null rather than checking whether the key exists.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :text
+
+      # The number of yours that received the signal, in E.164 format with the leading
+      # +. Tells a multi-number account which of its senders the contact acted on, which
+      # nothing else on this payload answers.
+      #
+      # This is your number, not the contact's. That is the opposite of what to means on
+      # POST /v3/messages, where it is the list of recipients you are sending to. Reply
+      # to From, not to this field, or the message goes back to yourself.
+      #
+      # Sent as null when the signal did not arrive at a number of yours — an RCS signal
+      # terminates at an agent rather than a number, and a provider-reported opt-out may
+      # name no receiving number at all. The field is always present, so read it and
+      # check for null rather than checking whether the key exists.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :to
+
+      # Body of a contact.opt_in, contact.opt_out, contact.help or
+      # contact.custom_keyword event. Delivered when a contact signals a consent change,
+      # asks for help, or sends one of your own auto-reply keywords.
+      #
+      # These events state the signal outright, so you do not have to recognise keywords
+      # in the text of a message.received event. They also cover cases that produce no
+      # inbound message at all, such as a network handling an opt-out on your behalf.
+      #
+      # Two of the four change consent and two do not: contact.help and
+      # contact.custom_keyword report the state the contact already had. Read opt_out
+      # for the state and the envelope's event for what happened, rather than inferring
+      # one from the other.
+      #
+      # Fields are ordered identity → resulting state → provenance → join keys. The two
+      # parties are from and to. Note that the message family has not moved to those
+      # names yet — message.received still calls the same two parties inbound_number and
+      # outbound_number. Nothing here restates the envelope: which signal occurred is
+      # the envelope's event, and when it was emitted is its timestamp. Retries carry
+      # the same X-Webhook-Event-ID header, which is what to deduplicate on.
+      sig do
+        params(
+          opt_out: T::Boolean,
+          source: String,
+          account_id: String,
+          agent_id: T.nilable(String),
+          channel: String,
+          contact_id: String,
+          from: String,
+          message_id: T.nilable(String),
+          template_id: T.nilable(String),
+          text: T.nilable(String),
+          to: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Whether the contact is opted out after this signal — the state to write to your
+        # own record. Same meaning as opt_out on the contact resource. On contact.help and
+        # contact.custom_keyword this reports the contact's existing state, which neither
+        # changes.
+        #
+        # Two signals from the same contact can arrive out of order, because each one is
+        # queued on its own rather than against the contact. Compare the envelope's
+        # timestamp before you overwrite a newer state with an older one. That timestamp
+        # is second-precision, so treat two signals stamped in the same second as
+        # unordered and read the contact resource to settle them.
+        opt_out:,
+        # How the signal reached us. INBOUND_KEYWORD means the contact sent a message
+        # whose text matched one of the keywords; PROVIDER_SIGNAL means the network
+        # reported it. A provider signal usually carries no message_id or text, so read
+        # both for null rather than inferring them from this field.
+        source:,
+        # The account the contact belongs to. Present so one endpoint can serve several
+        # accounts.
+        account_id: nil,
+        # The RCS agent the signal reached, when it reached one.
+        #
+        # Omitted entirely on channels that have no agent, rather than sent as null — an
+        # SMS or WhatsApp payload does not carry this key at all. On RCS it is the
+        # counterpart to To: a contact reaches an agent rather than a number, so exactly
+        # one of the two is populated and never both. If you run more than one agent, this
+        # is what tells you which of them the contact acted on.
+        agent_id: nil,
+        # The channel the signal arrived on, for example sms or whatsapp.
+        channel: nil,
+        # The contact who raised the signal. Always populated, including for contact.help
+        # or contact.custom_keyword from a number you have not messaged before — the
+        # contact is created if it does not exist yet, so this identifier is always
+        # resolvable against the contacts API.
+        contact_id: nil,
+        # The contact's number, in E.164 format with the leading + — who raised the
+        # signal. The same party message.received publishes as inbound_number.
+        from: nil,
+        # The inbound message that carried the signal, matching message_id on the
+        # corresponding message.received event so the two can be joined.
+        #
+        # Sent as null when the signal did not arrive as a message — for example when a
+        # network processed an opt-out on your behalf — and also when the message belongs
+        # to a different account than this event, which can happen on a shared WhatsApp
+        # number. The field is always present, so read it and check for null rather than
+        # checking whether the key exists.
+        message_id: nil,
+        # The auto-reply template whose keyword the contact matched, joinable against the
+        # templates API.
+        #
+        # This is what identifies which signal arrived on contact.custom_keyword: every
+        # custom template reports the same event name, so the event alone cannot tell your
+        # booking keyword from your opening-hours one. One template holds as many keywords
+        # as you configured, so this is steadier to switch on than text.
+        #
+        # Populated on the compliance sub-types too, where it names the template that
+        # replied. Sent as null when no template was involved — a network-reported opt-out
+        # matches no keyword. The field is always present, so read it and check for null.
+        template_id: nil,
+        # The text the contact sent, for example STOP or UNSUBSCRIBE. Sent as null when
+        # the signal did not arrive as text. The field is always present, so read it and
+        # check for null rather than checking whether the key exists.
+        text: nil,
+        # The number of yours that received the signal, in E.164 format with the leading
+        # +. Tells a multi-number account which of its senders the contact acted on, which
+        # nothing else on this payload answers.
+        #
+        # This is your number, not the contact's. That is the opposite of what to means on
+        # POST /v3/messages, where it is the list of recipients you are sending to. Reply
+        # to From, not to this field, or the message goes back to yourself.
+        #
+        # Sent as null when the signal did not arrive at a number of yours — an RCS signal
+        # terminates at an agent rather than a number, and a provider-reported opt-out may
+        # name no receiving number at all. The field is always present, so read it and
+        # check for null rather than checking whether the key exists.
+        to: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            opt_out: T::Boolean,
+            source: String,
+            account_id: String,
+            agent_id: T.nilable(String),
+            channel: String,
+            contact_id: String,
+            from: String,
+            message_id: T.nilable(String),
+            template_id: T.nilable(String),
+            text: T.nilable(String),
+            to: T.nilable(String)
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/sentdm/models/conversation_messages_list.rbi

@@ -112,7 +112,14 @@ module Sentdm
         attr_accessor :events
 
         # Structured message body format for database storage. Preserves channel-specific
-        # components (header, body, footer, buttons).
+        # components (header, header media, body, footer, buttons, MMS subject and media).
+        #
+        # Persisted as the messageBody jsonb column on Messages. Every write path goes
+        # through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+        # shape is stable regardless of channel or status. Anything that rebuilds this
+        # object field by field — the four IMessageBodyStrategy implementations and
+        # MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+        # silently dropped on whichever path forgot it.
         sig do
           returns(
             T.nilable(Sentdm::ConversationMessagesList::Message::MessageBody)
@@ -166,7 +173,12 @@ module Sentdm
         sig { returns(T.nilable(String)) }
         attr_accessor :template_name
 
-        # Message response for v3 API — same shape as v2 with snake_case JSON conventions
+        # Message response for v3 API — same shape as v2 with snake_case JSON conventions.
+        #
+        # The shape of a message that was sent immediately: it never has a scheduled_at
+        # key. A message that is or was held for a later instant is a
+        # ScheduledMessageResponse, and the endpoint decides which of the two to answer
+        # with. From always returns this type.
         sig do
           params(
             id: String,
@@ -206,7 +218,14 @@ module Sentdm
           direction: nil,
           events: nil,
           # Structured message body format for database storage. Preserves channel-specific
-          # components (header, body, footer, buttons).
+          # components (header, header media, body, footer, buttons, MMS subject and media).
+          #
+          # Persisted as the messageBody jsonb column on Messages. Every write path goes
+          # through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+          # shape is stable regardless of channel or status. Anything that rebuilds this
+          # object field by field — the four IMessageBodyStrategy implementations and
+          # MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+          # silently dropped on whichever path forgot it.
           message_body: nil,
           phone: nil,
           phone_international: nil,
@@ -325,8 +344,57 @@ module Sentdm
           sig { returns(T.nilable(String)) }
           attr_accessor :header
 
+          # The media asset that rode a message's header, recorded as sent.
+          sig do
+            returns(
+              T.nilable(
+                Sentdm::ConversationMessagesList::Message::MessageBody::HeaderMedia
+              )
+            )
+          end
+          attr_reader :header_media
+
+          sig do
+            params(
+              header_media:
+                T.nilable(
+                  Sentdm::ConversationMessagesList::Message::MessageBody::HeaderMedia::OrHash
+                )
+            ).void
+          end
+          attr_writer :header_media
+
+          # MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on
+          # every other channel.
+          #
+          # Persisted rather than derived because a resend and a curfew release rebuild the
+          # send from the stored row — MessageReplayCommandBuilder reads templateId and
+          # templateVariables and nothing else — so media that lives only on the original
+          # request would silently turn a replayed MMS into a text message.
+          sig do
+            returns(
+              T.nilable(
+                T::Array[
+                  Sentdm::ConversationMessagesList::Message::MessageBody::Media
+                ]
+              )
+            )
+          end
+          attr_accessor :media
+
+          # MMS subject line. Null on every other channel.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :subject
+
           # Structured message body format for database storage. Preserves channel-specific
-          # components (header, body, footer, buttons).
+          # components (header, header media, body, footer, buttons, MMS subject and media).
+          #
+          # Persisted as the messageBody jsonb column on Messages. Every write path goes
+          # through MessageUtils.MessageBodyJsonOptions, which writes nulls, so the envelope
+          # shape is stable regardless of channel or status. Anything that rebuilds this
+          # object field by field — the four IMessageBodyStrategy implementations and
+          # MessageUtils.BuildSegmentBody — has to carry every member, or that member is
+          # silently dropped on whichever path forgot it.
           sig do
             params(
               buttons:
@@ -337,10 +405,38 @@ module Sentdm
                 ),
               content: String,
               footer: T.nilable(String),
-              header: T.nilable(String)
+              header: T.nilable(String),
+              header_media:
+                T.nilable(
+                  Sentdm::ConversationMessagesList::Message::MessageBody::HeaderMedia::OrHash
+                ),
+              media:
+                T.nilable(
+                  T::Array[
+                    Sentdm::ConversationMessagesList::Message::MessageBody::Media::OrHash
+                  ]
+                ),
+              subject: T.nilable(String)
             ).returns(T.attached_class)
           end
-          def self.new(buttons: nil, content: nil, footer: nil, header: nil)
+          def self.new(
+            buttons: nil,
+            content: nil,
+            footer: nil,
+            header: nil,
+            # The media asset that rode a message's header, recorded as sent.
+            header_media: nil,
+            # MMS attachments, as the publicly fetchable URLs handed to the carrier. Null on
+            # every other channel.
+            #
+            # Persisted rather than derived because a resend and a curfew release rebuild the
+            # send from the stored row — MessageReplayCommandBuilder reads templateId and
+            # templateVariables and nothing else — so media that lives only on the original
+            # request would silently turn a replayed MMS into a text message.
+            media: nil,
+            # MMS subject line. Null on every other channel.
+            subject: nil
+          )
           end
 
           sig do
@@ -354,7 +450,18 @@ module Sentdm
                   ),
                 content: String,
                 footer: T.nilable(String),
-                header: T.nilable(String)
+                header: T.nilable(String),
+                header_media:
+                  T.nilable(
+                    Sentdm::ConversationMessagesList::Message::MessageBody::HeaderMedia
+                  ),
+                media:
+                  T.nilable(
+                    T::Array[
+                      Sentdm::ConversationMessagesList::Message::MessageBody::Media
+                    ]
+                  ),
+                subject: T.nilable(String)
               }
             )
           end
@@ -412,6 +519,94 @@ module Sentdm
             def to_hash
             end
           end
+
+          class HeaderMedia < Sentdm::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Sentdm::ConversationMessagesList::Message::MessageBody::HeaderMedia,
+                  Sentdm::Internal::AnyHash
+                )
+              end
+
+            # "image", "video" or "document" — taken from the header's media variable.
+            sig { returns(T.nilable(String)) }
+            attr_reader :type
+
+            sig { params(type: String).void }
+            attr_writer :type
+
+            # The https URL the caller supplied for this send. Never the template's stored
+            # props.sample, which is Meta's expiring header_handle rather than what was
+            # delivered.
+            sig { returns(T.nilable(String)) }
+            attr_reader :url
+
+            sig { params(url: String).void }
+            attr_writer :url
+
+            # The media asset that rode a message's header, recorded as sent.
+            sig { params(type: String, url: String).returns(T.attached_class) }
+            def self.new(
+              # "image", "video" or "document" — taken from the header's media variable.
+              type: nil,
+              # The https URL the caller supplied for this send. Never the template's stored
+              # props.sample, which is Meta's expiring header_handle rather than what was
+              # delivered.
+              url: nil
+            )
+            end
+
+            sig { override.returns({ type: String, url: String }) }
+            def to_hash
+            end
+          end
+
+          class Media < Sentdm::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  Sentdm::ConversationMessagesList::Message::MessageBody::Media,
+                  Sentdm::Internal::AnyHash
+                )
+              end
+
+            # One of Constants.MmsMediaTypes when known. Advisory — the carrier reads the
+            # fetched object's Content-Type, not this.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :media_type
+
+            sig { returns(T.nilable(String)) }
+            attr_reader :url
+
+            sig { params(url: String).void }
+            attr_writer :url
+
+            # One attachment on a message: a customer-supplied public URL handed to the
+            # carrier as-is.
+            #
+            #              A URL and nothing else. sent.dm never takes custody of MMS media — the customer hosts it and we
+            #              pass the link through at send time — so there is no storage key, size or expiry to record. If we ever
+            #              do host attachments, that belongs with the change that introduces the hosting, not here.
+            sig do
+              params(media_type: T.nilable(String), url: String).returns(
+                T.attached_class
+              )
+            end
+            def self.new(
+              # One of Constants.MmsMediaTypes when known. Advisory — the carrier reads the
+              # fetched object's Content-Type, not this.
+              media_type: nil,
+              url: nil
+            )
+            end
+
+            sig do
+              override.returns({ media_type: T.nilable(String), url: String })
+            end
+            def to_hash
+            end
+          end
         end
       end
     end

data/rbi/sentdm/models/inbound_message_event.rbi

@@ -8,14 +8,14 @@ module Sentdm
           T.any(Sentdm::InboundMessageEvent, Sentdm::Internal::AnyHash)
         end
 
-      # The specific event within the family, for example message.delivered or
-      # message.received. Absent on events that have no subtype, so treat it as
-      # optional.
+      # 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.
       sig { returns(T.nilable(String)) }
       attr_accessor :event
 
-      # The event family, for example message or templates. Route on this first, then on
-      # event for the specific change.
+      # The event family, for example message, templates or contact. Route on this
+      # first, then on event for the specific change.
       sig { returns(T.nilable(String)) }
       attr_reader :field
 
@@ -34,6 +34,10 @@ module Sentdm
       end
       attr_writer :payload
 
+      # The event-specific body.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :request_id
+
       # 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.
@@ -50,20 +54,23 @@ module Sentdm
           event: T.nilable(String),
           field: String,
           payload: T.nilable(Sentdm::InboundMessageEventPayload::OrHash),
+          request_id: T.nilable(String),
           timestamp: String
         ).returns(T.attached_class)
       end
       def self.new(
-        # The specific event within the family, for example message.delivered or
-        # message.received. Absent on events that have no subtype, so treat it as
-        # optional.
+        # 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.
         event: nil,
-        # The event family, for example message or templates. Route on this first, then on
-        # event for the specific change.
+        # The event family, for example message, templates or contact. Route on this
+        # first, then on event for the specific change.
         field: nil,
         # Body of a message.received event. Delivered when a contact messages one of your
         # numbers.
         payload: nil,
+        # The event-specific body.
+        request_id: nil,
         # 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.
@@ -77,6 +84,7 @@ module Sentdm
             event: T.nilable(String),
             field: String,
             payload: T.nilable(Sentdm::InboundMessageEventPayload),
+            request_id: T.nilable(String),
             timestamp: String
           }
         )

data/rbi/sentdm/models/message_event.rbi

@@ -6,14 +6,14 @@ module Sentdm
       OrHash =
         T.type_alias { T.any(Sentdm::MessageEvent, Sentdm::Internal::AnyHash) }
 
-      # The specific event within the family, for example message.delivered or
-      # message.received. Absent on events that have no subtype, so treat it as
-      # optional.
+      # 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.
       sig { returns(T.nilable(String)) }
       attr_accessor :event
 
-      # The event family, for example message or templates. Route on this first, then on
-      # event for the specific change.
+      # The event family, for example message, templates or contact. Route on this
+      # first, then on event for the specific change.
       sig { returns(T.nilable(String)) }
       attr_reader :field
 
@@ -31,6 +31,10 @@ module Sentdm
       end
       attr_writer :payload
 
+      # The event-specific body.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :request_id
+
       # 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.
@@ -47,21 +51,24 @@ module Sentdm
           event: T.nilable(String),
           field: String,
           payload: T.nilable(Sentdm::MessageEventPayload::OrHash),
+          request_id: T.nilable(String),
           timestamp: String
         ).returns(T.attached_class)
       end
       def self.new(
-        # The specific event within the family, for example message.delivered or
-        # message.received. Absent on events that have no subtype, so treat it as
-        # optional.
+        # 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.
         event: nil,
-        # The event family, for example message or templates. Route on this first, then on
-        # event for the specific change.
+        # The event family, for example message, templates or contact. Route on this
+        # first, then on event for the specific change.
         field: nil,
         # Body of an outbound message lifecycle event. Delivered once per status change,
         # so a single message produces several of these as it moves toward a terminal
         # status.
         payload: nil,
+        # The event-specific body.
+        request_id: nil,
         # 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.
@@ -75,6 +82,7 @@ module Sentdm
             event: T.nilable(String),
             field: String,
             payload: T.nilable(Sentdm::MessageEventPayload),
+            request_id: T.nilable(String),
             timestamp: String
           }
         )