sentdm 0.32.0 → 0.34.0

data/rbi/sentdm/models/contact_event_payload.rbi

@@ -9,8 +9,9 @@ module Sentdm
         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
-      # this reports the contact's existing state, which help does not change.
+      # 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
@@ -35,6 +36,16 @@ module Sentdm
       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
@@ -43,14 +54,23 @@ module Sentdm
       attr_writer :channel
 
       # The contact who raised the signal. Always populated, including for contact.help
-      # 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.
+      # 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.
       #
@@ -62,13 +82,19 @@ module Sentdm
       sig { returns(T.nilable(String)) }
       attr_accessor :message_id
 
-      # The contact's number in E.164 format. Same value as phone_number on the contact
-      # resource.
+      # 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_reader :phone_number
-
-      sig { params(phone_number: String).void }
-      attr_writer :phone_number
+      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
@@ -76,33 +102,60 @@ module Sentdm
       sig { returns(T.nilable(String)) }
       attr_accessor :text
 
-      # Body of a contact.opt_in, contact.opt_out or contact.help event. Delivered when
-      # a contact signals a consent change or asks for help.
+      # 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.
       #
-      # Fields are ordered identity → resulting state → provenance → join key. Nothing
-      # here restates the envelope: which of the three signals 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.
+      # 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),
-          phone_number: String,
-          text: 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
-        # this reports the contact's existing state, which help does not change.
+        # 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
@@ -118,12 +171,24 @@ module Sentdm
         # 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
-        # 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.
+        # 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.
         #
@@ -133,13 +198,35 @@ module Sentdm
         # number. The field is always present, so read it and check for null rather than
         # checking whether the key exists.
         message_id: nil,
-        # The contact's number in E.164 format. Same value as phone_number on the contact
-        # resource.
-        phone_number: 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
+        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
 
@@ -149,11 +236,14 @@ module Sentdm
             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),
-            phone_number: String,
-            text: T.nilable(String)
+            template_id: T.nilable(String),
+            text: T.nilable(String),
+            to: T.nilable(String)
           }
         )
       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)
@@ -145,6 +152,20 @@ module Sentdm
         sig { returns(T.nilable(Float)) }
         attr_accessor :price
 
+        # A human-readable sentence for reason_code, for example "Insufficient balance".
+        # Omitted whenever reason_code is.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :reason
+
+        # Why the message is at its current status, as a stable platform code such as
+        # DELIVERY_007, BUSINESS_003 or DELIVERY_003. Present when the current status is
+        # FAILED, FILTERED or BLOCKED and the lifecycle was loaded; omitted otherwise.
+        # Switch on this rather than on reason: the code is stable, the wording may be
+        # improved. It is the platform's classification of the outcome, never a carrier or
+        # vendor code.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :reason_code
+
         sig { returns(T.nilable(String)) }
         attr_reader :region_code
 
@@ -166,7 +187,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,
@@ -189,6 +215,8 @@ module Sentdm
             phone: String,
             phone_international: String,
             price: T.nilable(Float),
+            reason: T.nilable(String),
+            reason_code: T.nilable(String),
             region_code: String,
             status: String,
             template_category: T.nilable(String),
@@ -206,11 +234,28 @@ 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,
           price: nil,
+          # A human-readable sentence for reason_code, for example "Insufficient balance".
+          # Omitted whenever reason_code is.
+          reason: nil,
+          # Why the message is at its current status, as a stable platform code such as
+          # DELIVERY_007, BUSINESS_003 or DELIVERY_003. Present when the current status is
+          # FAILED, FILTERED or BLOCKED and the lifecycle was loaded; omitted otherwise.
+          # Switch on this rather than on reason: the code is stable, the wording may be
+          # improved. It is the platform's classification of the outcome, never a carrier or
+          # vendor code.
+          reason_code: nil,
           region_code: nil,
           status: nil,
           template_category: nil,
@@ -240,6 +285,8 @@ module Sentdm
               phone: String,
               phone_international: String,
               price: T.nilable(Float),
+              reason: T.nilable(String),
+              reason_code: T.nilable(String),
               region_code: String,
               status: String,
               template_category: T.nilable(String),
@@ -269,15 +316,39 @@ module Sentdm
           sig { returns(T.nilable(String)) }
           attr_accessor :description
 
+          # A human-readable sentence for reason_code. Omitted whenever reason_code is.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :reason
+
+          # Why the message reached this status, as a stable platform code such as
+          # DELIVERY_007. Present on FAILED, FILTERED and BLOCKED events; omitted on every
+          # status that needs no explanation. Same wire name and vocabulary as on the
+          # activities list and the webhook.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :reason_code
+
           # Represents a status change event in a message's lifecycle (v3)
           sig do
             params(
               status: String,
               timestamp: Time,
-              description: T.nilable(String)
+              description: T.nilable(String),
+              reason: T.nilable(String),
+              reason_code: T.nilable(String)
             ).returns(T.attached_class)
           end
-          def self.new(status:, timestamp:, description: nil)
+          def self.new(
+            status:,
+            timestamp:,
+            description: nil,
+            # A human-readable sentence for reason_code. Omitted whenever reason_code is.
+            reason: nil,
+            # Why the message reached this status, as a stable platform code such as
+            # DELIVERY_007. Present on FAILED, FILTERED and BLOCKED events; omitted on every
+            # status that needs no explanation. Same wire name and vocabulary as on the
+            # activities list and the webhook.
+            reason_code: nil
+          )
           end
 
           sig do
@@ -285,7 +356,9 @@ module Sentdm
               {
                 status: String,
                 timestamp: Time,
-                description: T.nilable(String)
+                description: T.nilable(String),
+                reason: T.nilable(String),
+                reason_code: T.nilable(String)
               }
             )
           end
@@ -325,8 +398,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 +459,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 +504,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 +573,143 @@ 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 MmsMediaTypes when the content type is known. Advisory — a reader should
+            # trust the fetched object's own Content-Type.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :media_type
+
+            # Content type as the provider declared it. Null when it declared none.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :mime_type
+
+            # Size as the provider declared it. Never measured here — nothing downloads the
+            # file.
+            sig { returns(T.nilable(Integer)) }
+            attr_accessor :size_bytes
+
+            # Inbound only: the SHA-256 the provider declared alongside the attachment, when
+            # it declared one. Relayed to the customer so they can verify what they fetch
+            # matches what the carrier said it sent. It is the only integrity signal available
+            # on an attachment nobody here has read.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :source_hash_sha256
+
+            # Where the file lives. Outbound: the URL the customer gave us and the carrier
+            # fetched. Inbound: the URL the carrier hosts it at, relayed unchanged.
+            sig { returns(T.nilable(String)) }
+            attr_accessor :url
+
+            # One attachment on a message, in either direction — and in both, a URL somebody
+            # else hosts.
+            #
+            # Outbound: the customer supplied a public URL and we handed it to the carrier.
+            # Inbound: the carrier hosts the file and we record where. sent.dm never holds the
+            # bytes, so there is no key, no expiry bookkeeping and nothing minted per read —
+            # what is stored is what is served.
+            #
+            # An inbound link expires on the carrier's own schedule and is unauthenticated.
+            # That is the customer's to manage, and it is documented where they will see it
+            # rather than only here — a recipient who needs an attachment to outlive that
+            # window copies it on receipt.
+            #
+            # Storing a presigned URL is the specific mistake this shape still avoids:
+            # M260826130000 and M260826140000 exist because RCS assets were stored as signed
+            # URLs and went stale. Nothing here is signed.
+            sig do
+              params(
+                media_type: T.nilable(String),
+                mime_type: T.nilable(String),
+                size_bytes: T.nilable(Integer),
+                source_hash_sha256: T.nilable(String),
+                url: T.nilable(String)
+              ).returns(T.attached_class)
+            end
+            def self.new(
+              # One of MmsMediaTypes when the content type is known. Advisory — a reader should
+              # trust the fetched object's own Content-Type.
+              media_type: nil,
+              # Content type as the provider declared it. Null when it declared none.
+              mime_type: nil,
+              # Size as the provider declared it. Never measured here — nothing downloads the
+              # file.
+              size_bytes: nil,
+              # Inbound only: the SHA-256 the provider declared alongside the attachment, when
+              # it declared one. Relayed to the customer so they can verify what they fetch
+              # matches what the carrier said it sent. It is the only integrity signal available
+              # on an attachment nobody here has read.
+              source_hash_sha256: nil,
+              # Where the file lives. Outbound: the URL the customer gave us and the carrier
+              # fetched. Inbound: the URL the carrier hosts it at, relayed unchanged.
+              url: nil
+            )
+            end
+
+            sig do
+              override.returns(
+                {
+                  media_type: T.nilable(String),
+                  mime_type: T.nilable(String),
+                  size_bytes: T.nilable(Integer),
+                  source_hash_sha256: T.nilable(String),
+                  url: T.nilable(String)
+                }
+              )
+            end
+            def to_hash
+            end
+          end
         end
       end
     end