sentdm 0.32.0 → 0.33.0

data/rbi/sentdm/models/channel_event_payload.rbi

@@ -18,7 +18,9 @@ module Sentdm
       # The account whose market this is, named as on every other family. When an
       # organization receives an event for one of its sender profiles this is the
       # profile, so a reseller compares it with its own id and anything different is one
-      # of its profiles.
+      # of its profiles. Matches customer_id on GET /v3/channels and the sender
+      # profile's id. Together with channel, country, and number_type, it identifies the
+      # market.
       sig { returns(T.nilable(String)) }
       attr_reader :account_id
 
@@ -34,6 +36,33 @@ module Sentdm
       sig { params(channel: String).void }
       attr_writer :channel
 
+      # What a market has been given: the identity it registers under, its programme,
+      # and any documents attached.
+      #
+      # What it does not carry is what the market asks for. That is the subject of GET
+      # /v3/compliance/requirements, and it is the same answer for every caller — a
+      # description of what a compliance regime wants, not a record of one customer's
+      # progress through it. It was reported here as well for a while, which put the
+      # same array in six response shapes and left a caller deciding which of two
+      # sources to believe.
+      #
+      # Present on a list read for markets that register (carrying brand and campaign),
+      # but with documents absent — documents are not fetched for a list, because a
+      # catalog lookup and a document read per market would multiply across a page.
+      # Absent documents is distinct from an empty list: absent says they were not
+      # fetched; empty says the market has been given none. The parent object is null
+      # only when the market registers with nobody and compliance was not computed —
+      # nothing to show at all.
+      sig { returns(T.nilable(Sentdm::ChannelEventPayload::Compliance)) }
+      attr_reader :compliance
+
+      sig do
+        params(
+          compliance: T.nilable(Sentdm::ChannelEventPayload::Compliance::OrHash)
+        ).void
+      end
+      attr_writer :compliance
+
       # The kind of sender the market uses, for example TEN_DLC, LOCAL, or ALPHANUMERIC.
       # Omitted when the subject has no sender type of its own.
       sig { returns(T.nilable(String)) }
@@ -109,6 +138,8 @@ module Sentdm
           country: String,
           account_id: String,
           channel: String,
+          compliance:
+            T.nilable(Sentdm::ChannelEventPayload::Compliance::OrHash),
           number_type: T.nilable(String),
           reason: T.nilable(String),
           sender_value: T.nilable(String),
@@ -125,12 +156,32 @@ module Sentdm
         # The account whose market this is, named as on every other family. When an
         # organization receives an event for one of its sender profiles this is the
         # profile, so a reseller compares it with its own id and anything different is one
-        # of its profiles.
+        # of its profiles. Matches customer_id on GET /v3/channels and the sender
+        # profile's id. Together with channel, country, and number_type, it identifies the
+        # market.
         account_id: nil,
         # The channel this market belongs to: sms, whatsapp, or rcs. Never sent — that
         # value belongs to message events, where it names the smart-routing brand rather
         # than a channel that can be provisioned.
         channel: nil,
+        # What a market has been given: the identity it registers under, its programme,
+        # and any documents attached.
+        #
+        # What it does not carry is what the market asks for. That is the subject of GET
+        # /v3/compliance/requirements, and it is the same answer for every caller — a
+        # description of what a compliance regime wants, not a record of one customer's
+        # progress through it. It was reported here as well for a while, which put the
+        # same array in six response shapes and left a caller deciding which of two
+        # sources to believe.
+        #
+        # Present on a list read for markets that register (carrying brand and campaign),
+        # but with documents absent — documents are not fetched for a list, because a
+        # catalog lookup and a document read per market would multiply across a page.
+        # Absent documents is distinct from an empty list: absent says they were not
+        # fetched; empty says the market has been given none. The parent object is null
+        # only when the market registers with nobody and compliance was not computed —
+        # nothing to show at all.
+        compliance: nil,
         # The kind of sender the market uses, for example TEN_DLC, LOCAL, or ALPHANUMERIC.
         # Omitted when the subject has no sender type of its own.
         number_type: nil,
@@ -174,6 +225,7 @@ module Sentdm
             country: String,
             account_id: String,
             channel: String,
+            compliance: T.nilable(Sentdm::ChannelEventPayload::Compliance),
             number_type: T.nilable(String),
             reason: T.nilable(String),
             sender_value: T.nilable(String),
@@ -184,6 +236,205 @@ module Sentdm
       end
       def to_hash
       end
+
+      class Compliance < Sentdm::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Sentdm::ChannelEventPayload::Compliance,
+              Sentdm::Internal::AnyHash
+            )
+          end
+
+        # The identity this market registers under, with inherit saying whose it is.
+        #
+        # Reported here rather than on the profile because it belongs to the registration
+        # this market files, and only one market files one. It was a top-level block for a
+        # while, which put a per-registration value beside a list of markets and left a
+        # caller to work out which market it belonged to.
+        #
+        # Absent for a market that registers with nobody — such a market asks for no
+        # identity, so there is none to report. Absent and null mean different things:
+        # absent says this market does not ask, null would say it asks and nothing was
+        # supplied.
+        #
+        # Untyped, like the request side, because its members are declared by the market's
+        # own schema rather than by a C# class. A typed pair here would be a second
+        # definition of what a market wants, free to drift from the one that validates.
+        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+        attr_accessor :brand
+
+        # The programme this market registers, with inherit saying whose it is.
+        #
+        # One, not a list. TcrCampaigns permits several and an account built on the admin
+        # side may hold them, but this surface offers one — which is what lets the
+        # market's PATCH be an upsert rather than a collection with an addressable create
+        # behind it. An account holding several is reported as its first and refused on
+        # write, rather than half-edited.
+        #
+        # Carries no id. Nothing addresses a campaign, and an undeclared key would be
+        # refused if the caller sent this object back — which it is meant to be able to
+        # do.
+        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+        attr_accessor :campaign
+
+        # What has been supplied for this market.
+        #
+        # Files, not values — the declared halves above carry the values. A document
+        # cannot be a JSON value, so it is sent as multipart on the channel call and
+        # reported here as a reference.
+        #
+        # Absent on a list read, which fetches identity but does not compute compliance
+        # documents per market. Absent and empty mean different things: absent says the
+        # documents were not fetched; empty says the market has been given none.
+        sig do
+          returns(
+            T.nilable(
+              T::Array[Sentdm::ChannelEventPayload::Compliance::Document]
+            )
+          )
+        end
+        attr_accessor :documents
+
+        # What a market has been given: the identity it registers under, its programme,
+        # and any documents attached.
+        #
+        # What it does not carry is what the market asks for. That is the subject of GET
+        # /v3/compliance/requirements, and it is the same answer for every caller — a
+        # description of what a compliance regime wants, not a record of one customer's
+        # progress through it. It was reported here as well for a while, which put the
+        # same array in six response shapes and left a caller deciding which of two
+        # sources to believe.
+        #
+        # Present on a list read for markets that register (carrying brand and campaign),
+        # but with documents absent — documents are not fetched for a list, because a
+        # catalog lookup and a document read per market would multiply across a page.
+        # Absent documents is distinct from an empty list: absent says they were not
+        # fetched; empty says the market has been given none. The parent object is null
+        # only when the market registers with nobody and compliance was not computed —
+        # nothing to show at all.
+        sig do
+          params(
+            brand: T.nilable(T::Hash[Symbol, T.anything]),
+            campaign: T.nilable(T::Hash[Symbol, T.anything]),
+            documents:
+              T.nilable(
+                T::Array[
+                  Sentdm::ChannelEventPayload::Compliance::Document::OrHash
+                ]
+              )
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The identity this market registers under, with inherit saying whose it is.
+          #
+          # Reported here rather than on the profile because it belongs to the registration
+          # this market files, and only one market files one. It was a top-level block for a
+          # while, which put a per-registration value beside a list of markets and left a
+          # caller to work out which market it belonged to.
+          #
+          # Absent for a market that registers with nobody — such a market asks for no
+          # identity, so there is none to report. Absent and null mean different things:
+          # absent says this market does not ask, null would say it asks and nothing was
+          # supplied.
+          #
+          # Untyped, like the request side, because its members are declared by the market's
+          # own schema rather than by a C# class. A typed pair here would be a second
+          # definition of what a market wants, free to drift from the one that validates.
+          brand: nil,
+          # The programme this market registers, with inherit saying whose it is.
+          #
+          # One, not a list. TcrCampaigns permits several and an account built on the admin
+          # side may hold them, but this surface offers one — which is what lets the
+          # market's PATCH be an upsert rather than a collection with an addressable create
+          # behind it. An account holding several is reported as its first and refused on
+          # write, rather than half-edited.
+          #
+          # Carries no id. Nothing addresses a campaign, and an undeclared key would be
+          # refused if the caller sent this object back — which it is meant to be able to
+          # do.
+          campaign: nil,
+          # What has been supplied for this market.
+          #
+          # Files, not values — the declared halves above carry the values. A document
+          # cannot be a JSON value, so it is sent as multipart on the channel call and
+          # reported here as a reference.
+          #
+          # Absent on a list read, which fetches identity but does not compute compliance
+          # documents per market. Absent and empty mean different things: absent says the
+          # documents were not fetched; empty says the market has been given none.
+          documents: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              brand: T.nilable(T::Hash[Symbol, T.anything]),
+              campaign: T.nilable(T::Hash[Symbol, T.anything]),
+              documents:
+                T.nilable(
+                  T::Array[Sentdm::ChannelEventPayload::Compliance::Document]
+                )
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Document < Sentdm::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Sentdm::ChannelEventPayload::Compliance::Document,
+                Sentdm::Internal::AnyHash
+              )
+            end
+
+          # Identifier of the upload, for fetching it back through the documents endpoints.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :document_id
+
+          sig { returns(T.nilable(String)) }
+          attr_accessor :file_name
+
+          # The catalog's name for this document, matching the requirement it satisfies.
+          sig { returns(T.nilable(String)) }
+          attr_reader :key
+
+          sig { params(key: String).void }
+          attr_writer :key
+
+          # A document a market asked for and has been given.
+          sig do
+            params(
+              document_id: T.nilable(String),
+              file_name: T.nilable(String),
+              key: String
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Identifier of the upload, for fetching it back through the documents endpoints.
+            document_id: nil,
+            file_name: nil,
+            # The catalog's name for this document, matching the requirement it satisfies.
+            key: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                document_id: T.nilable(String),
+                file_name: T.nilable(String),
+                key: String
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+      end
     end
   end
 end

data/rbi/sentdm/models/contact_event.rbi

@@ -20,17 +20,25 @@ module Sentdm
       sig { params(field: String).void }
       attr_writer :field
 
-      # 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.
+      # 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 { returns(T.nilable(Sentdm::ContactEventPayload)) }
       attr_reader :payload
 
@@ -71,17 +79,25 @@ module Sentdm
         # 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 contact.opt_in, contact.opt_out or contact.help event. Delivered when
-        # a contact signals a consent change or asks for help.
+        # 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.
         payload: nil,
         # The event-specific body.
         request_id: nil,

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