sentdm 0.31.0 → 0.33.0

data/rbi/sentdm/models/template_event_payload.rbi

@@ -24,6 +24,23 @@ module Sentdm
       sig { params(account_id: String).void }
       attr_writer :account_id
 
+      # Which consent keyword this template answers, when it is one of Sent's
+      # auto-replies: OPT_IN, OPT_OUT, HELP, or OTHER for a customer-defined keyword.
+      #
+      # Omitted for an ordinary template, so its presence is the answer to "is this an
+      # auto-reply". Sent creates the three compliance auto-replies at signup and they
+      # go through review like any other template, so their events arrive mixed in with
+      # the customer's own with nothing else to tell them apart.
+      #
+      # Named for the reader rather than after Template.OptAction, which it is mapped
+      # from. The MCP tool result deliberately keeps OptAction, OptKeywords and IsOpt:
+      # it mirrors the internal shape on purpose and publishes the keywords too, so
+      # renaming one of the three there would leave a surface half in each vocabulary.
+      # Two names for one concept, each consistent within its own surface, chosen over a
+      # rename that breaks MCP clients silently.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :auto_reply_action
+
       # The template's category, for example UTILITY, MARKETING, or AUTHENTICATION.
       sig { returns(T.nilable(String)) }
       attr_reader :category
@@ -31,12 +48,15 @@ module Sentdm
       sig { params(category: String).void }
       attr_writer :category
 
-      # The channel the template applies to.
+      # The channel leg this decision is about, for example whatsapp, sms, or rcs. A
+      # template is reviewed per channel and the legs come back independently, so each
+      # one reports separately.
+      #
+      # Omitted when the decision applies to the template as a whole rather than to one
+      # leg. That event is the broader news: a template-wide rejection blocks every
+      # channel, whatever the individual legs say.
       sig { returns(T.nilable(String)) }
-      attr_reader :channel
-
-      sig { params(channel: String).void }
-      attr_writer :channel
+      attr_accessor :channel
 
       # The template's language code, for example en_US.
       sig { returns(T.nilable(String)) }
@@ -71,8 +91,9 @@ module Sentdm
           status: String,
           whatsapp_template_id: String,
           account_id: String,
+          auto_reply_action: T.nilable(String),
           category: String,
-          channel: String,
+          channel: T.nilable(String),
           language: String,
           reason: T.nilable(String),
           template_id: String,
@@ -87,9 +108,30 @@ module Sentdm
         whatsapp_template_id:,
         # The account the template belongs to.
         account_id: nil,
+        # Which consent keyword this template answers, when it is one of Sent's
+        # auto-replies: OPT_IN, OPT_OUT, HELP, or OTHER for a customer-defined keyword.
+        #
+        # Omitted for an ordinary template, so its presence is the answer to "is this an
+        # auto-reply". Sent creates the three compliance auto-replies at signup and they
+        # go through review like any other template, so their events arrive mixed in with
+        # the customer's own with nothing else to tell them apart.
+        #
+        # Named for the reader rather than after Template.OptAction, which it is mapped
+        # from. The MCP tool result deliberately keeps OptAction, OptKeywords and IsOpt:
+        # it mirrors the internal shape on purpose and publishes the keywords too, so
+        # renaming one of the three there would leave a surface half in each vocabulary.
+        # Two names for one concept, each consistent within its own surface, chosen over a
+        # rename that breaks MCP clients silently.
+        auto_reply_action: nil,
         # The template's category, for example UTILITY, MARKETING, or AUTHENTICATION.
         category: nil,
-        # The channel the template applies to.
+        # The channel leg this decision is about, for example whatsapp, sms, or rcs. A
+        # template is reviewed per channel and the legs come back independently, so each
+        # one reports separately.
+        #
+        # Omitted when the decision applies to the template as a whole rather than to one
+        # leg. That event is the broader news: a template-wide rejection blocks every
+        # channel, whatever the individual legs say.
         channel: nil,
         # The template's language code, for example en_US.
         language: nil,
@@ -109,8 +151,9 @@ module Sentdm
             status: String,
             whatsapp_template_id: String,
             account_id: String,
+            auto_reply_action: T.nilable(String),
             category: String,
-            channel: String,
+            channel: T.nilable(String),
             language: String,
             reason: T.nilable(String),
             template_id: String,

data/rbi/sentdm/models/template_header.rbi

@@ -13,7 +13,59 @@ module Sentdm
       sig { returns(String) }
       attr_accessor :template
 
-      # The type of header (e.g., "text", "image", "video", "document")
+      # Request-only. The s.dm URL of the asset Meta's reviewers see —
+      # https://s.dm/s/{ID}, eight uppercase characters, uploaded to s.dm out of band.
+      # NormalizeRichHeader folds it into the synthesized media variable's Props.Sample
+      # and clears it, so it never persists and a stored definition is indistinguishable
+      # from an imported one.
+      #
+      # Stricter than the send path on purpose:
+      # TemplateUtils.ValidateMediaVariableValues accepts any absolute https URL for the
+      # per-send asset, because that one is the customer's and may live behind a signed
+      # CDN link. This one is the review sample, has to outlive every resubmission, and
+      # so must be ours. Do not "fix" one to match the other.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :example_url
+
+      # The map pin a location header drops. Meta wants none of this at creation — the
+      # component is just {"type":"header","format":"location"} — so these values exist
+      # for Sent: a preview, and the default a StaticResource header falls back to at
+      # send.
+      sig { returns(T.nilable(Sentdm::TemplateHeader::Location)) }
+      attr_reader :location
+
+      sig do
+        params(
+          location: T.nilable(Sentdm::TemplateHeader::Location::OrHash)
+        ).void
+      end
+      attr_writer :location
+
+      # Whether the asset registered at creation is reused when a caller omits the
+      # header's variable at send time. Default false — the caller must supply it per
+      # message, which is the behaviour every existing template has. Written only when
+      # true, so a default-valued header serializes byte-identically to one imported
+      # from Meta.
+      #
+      # Stored and validated but not yet honoured at send: that lands with the Resumable
+      # Upload work, alongside the code that lets such a template be approved in the
+      # first place.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :static_resource
+
+      sig { params(static_resource: T::Boolean).void }
+      attr_writer :static_resource
+
+      # The kind of header. One of:
+      #
+      # text — up to 60 characters, at most one variable. image — png, jpg or jpeg.
+      # Needs ExampleUrl. video — mp4. Needs ExampleUrl. gif — mp4, max 3.5MB. WhatsApp
+      # renders larger files as an ordinary video. Needs ExampleUrl. document — pdf or
+      # docx; only the first page is shown as a thumbnail, so pdf is the practical
+      # choice. Needs ExampleUrl. location — a map pin, supplied through Location.
+      #
+      # Kept lowercase because MetaToTemplateConverter writes Meta's format through
+      # ToLowerInvariant() into this field on import, and the two are compared directly.
       sig { returns(T.nilable(String)) }
       attr_accessor :type
 
@@ -25,6 +77,9 @@ module Sentdm
       sig do
         params(
           template: String,
+          example_url: T.nilable(String),
+          location: T.nilable(Sentdm::TemplateHeader::Location::OrHash),
+          static_resource: T::Boolean,
           type: T.nilable(String),
           variables: T.nilable(T::Array[Sentdm::TemplateVariable::OrHash])
         ).returns(T.attached_class)
@@ -33,7 +88,43 @@ module Sentdm
         # The header template text with optional variable placeholders (e.g., "Welcome to
         # {{0:variable}}")
         template:,
-        # The type of header (e.g., "text", "image", "video", "document")
+        # Request-only. The s.dm URL of the asset Meta's reviewers see —
+        # https://s.dm/s/{ID}, eight uppercase characters, uploaded to s.dm out of band.
+        # NormalizeRichHeader folds it into the synthesized media variable's Props.Sample
+        # and clears it, so it never persists and a stored definition is indistinguishable
+        # from an imported one.
+        #
+        # Stricter than the send path on purpose:
+        # TemplateUtils.ValidateMediaVariableValues accepts any absolute https URL for the
+        # per-send asset, because that one is the customer's and may live behind a signed
+        # CDN link. This one is the review sample, has to outlive every resubmission, and
+        # so must be ours. Do not "fix" one to match the other.
+        example_url: nil,
+        # The map pin a location header drops. Meta wants none of this at creation — the
+        # component is just {"type":"header","format":"location"} — so these values exist
+        # for Sent: a preview, and the default a StaticResource header falls back to at
+        # send.
+        location: nil,
+        # Whether the asset registered at creation is reused when a caller omits the
+        # header's variable at send time. Default false — the caller must supply it per
+        # message, which is the behaviour every existing template has. Written only when
+        # true, so a default-valued header serializes byte-identically to one imported
+        # from Meta.
+        #
+        # Stored and validated but not yet honoured at send: that lands with the Resumable
+        # Upload work, alongside the code that lets such a template be approved in the
+        # first place.
+        static_resource: nil,
+        # The kind of header. One of:
+        #
+        # text — up to 60 characters, at most one variable. image — png, jpg or jpeg.
+        # Needs ExampleUrl. video — mp4. Needs ExampleUrl. gif — mp4, max 3.5MB. WhatsApp
+        # renders larger files as an ordinary video. Needs ExampleUrl. document — pdf or
+        # docx; only the first page is shown as a thumbnail, so pdf is the practical
+        # choice. Needs ExampleUrl. location — a map pin, supplied through Location.
+        #
+        # Kept lowercase because MetaToTemplateConverter writes Meta's format through
+        # ToLowerInvariant() into this field on import, and the two are compared directly.
         type: nil,
         # List of variables used in the header template
         variables: nil
@@ -44,6 +135,9 @@ module Sentdm
         override.returns(
           {
             template: String,
+            example_url: T.nilable(String),
+            location: T.nilable(Sentdm::TemplateHeader::Location),
+            static_resource: T::Boolean,
             type: T.nilable(String),
             variables: T.nilable(T::Array[Sentdm::TemplateVariable])
           }
@@ -51,6 +145,53 @@ module Sentdm
       end
       def to_hash
       end
+
+      class Location < Sentdm::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(Sentdm::TemplateHeader::Location, Sentdm::Internal::AnyHash)
+          end
+
+        sig { returns(String) }
+        attr_accessor :address
+
+        sig { returns(String) }
+        attr_accessor :latitude
+
+        sig { returns(String) }
+        attr_accessor :longitude
+
+        sig { returns(String) }
+        attr_accessor :name
+
+        # The map pin a location header drops. Meta wants none of this at creation — the
+        # component is just {"type":"header","format":"location"} — so these values exist
+        # for Sent: a preview, and the default a StaticResource header falls back to at
+        # send.
+        sig do
+          params(
+            address: String,
+            latitude: String,
+            longitude: String,
+            name: String
+          ).returns(T.attached_class)
+        end
+        def self.new(address:, latitude:, longitude:, name:)
+        end
+
+        sig do
+          override.returns(
+            {
+              address: String,
+              latitude: String,
+              longitude: String,
+              name: String
+            }
+          )
+        end
+        def to_hash
+        end
+      end
     end
   end
 end

data/rbi/sentdm/models/template_variable.rbi

@@ -8,6 +8,9 @@ module Sentdm
           T.any(Sentdm::TemplateVariable, Sentdm::Internal::AnyHash)
         end
 
+      # The variable's name, and the key callers use for it in a send request's
+      # parameters object. Must start with a letter and hold only letters, digits and
+      # underscores.
       sig { returns(String) }
       attr_accessor :name
 
@@ -17,9 +20,17 @@ module Sentdm
       sig { params(props: Sentdm::TemplateVariable::Props::OrHash).void }
       attr_writer :props
 
+      # One of variable, link or media. Decides which Props fields are required.
       sig { returns(String) }
       attr_accessor :type
 
+      # The variable's index, and the number its {{index:variable}} placeholder refers
+      # to.
+      #
+      # Omitting it is only safe for a section holding a single variable. The field is a
+      # non-nullable int, so every variable that leaves it out defaults to 0, and a
+      # section with two such variables is refused by the unique-id rule ("variables
+      # must have unique IDs"). Number them from 0 in the order they appear.
       sig { returns(T.nilable(Integer)) }
       attr_reader :id
 
@@ -34,7 +45,23 @@ module Sentdm
           id: Integer
         ).returns(T.attached_class)
       end
-      def self.new(name:, props:, type:, id: nil)
+      def self.new(
+        # The variable's name, and the key callers use for it in a send request's
+        # parameters object. Must start with a letter and hold only letters, digits and
+        # underscores.
+        name:,
+        props:,
+        # One of variable, link or media. Decides which Props fields are required.
+        type:,
+        # The variable's index, and the number its {{index:variable}} placeholder refers
+        # to.
+        #
+        # Omitting it is only safe for a section holding a single variable. The field is a
+        # non-nullable int, so every variable that leaves it out defaults to 0, and a
+        # section with two such variables is refused by the unique-id rule ("variables
+        # must have unique IDs"). Number them from 0 in the order they appear.
+        id: nil
+      )
       end
 
       sig do
@@ -59,6 +86,11 @@ module Sentdm
         sig { returns(String) }
         attr_accessor :media_type
 
+        # Example value substituted into the template when previewing it and when
+        # submitting it to Meta for review. Free text by nature, so the converter accepts
+        # a JSON number or boolean here and normalizes it — see
+        # JsonScalarToStringConverter for why — and guarantees it is always serialized
+        # back out as a JSON string.
         sig { returns(String) }
         attr_accessor :sample
 
@@ -90,6 +122,11 @@ module Sentdm
         end
         def self.new(
           media_type:,
+          # Example value substituted into the template when previewing it and when
+          # submitting it to Meta for review. Free text by nature, so the converter accepts
+          # a JSON number or boolean here and normalizes it — see
+          # JsonScalarToStringConverter for why — and guarantees it is always serialized
+          # back out as a JSON string.
           sample:,
           url:,
           variable_type:,