sentdm 0.32.0 → 0.33.0

data/rbi/sentdm/models/message_send_params.rbi

@@ -17,6 +17,23 @@ module Sentdm
       sig { returns(T.nilable(T::Array[String])) }
       attr_accessor :channel
 
+      # Attachments for this send, as publicly fetchable https URLs. Used by the MMS
+      # channel and ignored by every other one.
+      #
+      # Supplying these replaces the media on the template's mms body rather than adding
+      # to it, so a template can hold a default creative while a caller still sends
+      # something recipient-specific.
+      #
+      # Their presence is also what makes a message eligible for MMS on an auto-detect
+      # send: a message with nothing attached is delivered as SMS, because an MMS with
+      # no media is a more expensive text message.
+      #
+      # The recipient's carrier fetches each URL after the send is accepted, so it must
+      # stay publicly reachable — a link that expires, or one behind auth, arrives as a
+      # failed message.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_accessor :media_urls
+
       # Sandbox flag - when true, the operation is simulated without side effects Useful
       # for testing integrations without actual execution
       sig { returns(T.nilable(T::Boolean)) }
@@ -25,6 +42,25 @@ module Sentdm
       sig { params(sandbox: T::Boolean).void }
       attr_writer :sandbox
 
+      # Optional future send time as an ISO-8601 timestamp with an explicit UTC offset,
+      # e.g. 2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A value without an
+      # offset is rejected (400) rather than read in the server's zone. The offset only
+      # fixes the instant: it is stored and echoed in UTC as scheduled_at. Omit to send
+      # now. Must be at least one minute ahead and at most 30 days ahead. Accepted
+      # messages report SCHEDULED and are released for delivery at this time. Quiet
+      # hours, balance and template approval are evaluated at release, not at
+      # acceptance: a message whose time falls inside a recipient's protected
+      # quiet-hours window is moved to the next allowed time and a second
+      # message.scheduled webhook reports the new scheduled_at.
+      sig { returns(T.nilable(Time)) }
+      attr_accessor :scheduled_at
+
+      # Subject line for this send, overriding the template's. MMS only; ignored on
+      # every other channel. Most handsets render it above the body, some ignore it
+      # entirely.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :subject
+
       # SDK-style template reference: resolve by ID or by name, with optional
       # parameters.
       sig { returns(T.nilable(Sentdm::MessageSendParams::Template)) }
@@ -63,7 +99,10 @@ module Sentdm
       sig do
         params(
           channel: T.nilable(T::Array[String]),
+          media_urls: T.nilable(T::Array[String]),
           sandbox: T::Boolean,
+          scheduled_at: T.nilable(Time),
+          subject: T.nilable(String),
           template: T.nilable(Sentdm::MessageSendParams::Template::OrHash),
           text: T.nilable(String),
           to: T::Array[String],
@@ -77,9 +116,39 @@ module Sentdm
         # separate message per recipient. "sent" = auto-detect. Defaults to ["sent"]
         # (auto-detect) if omitted.
         channel: nil,
+        # Attachments for this send, as publicly fetchable https URLs. Used by the MMS
+        # channel and ignored by every other one.
+        #
+        # Supplying these replaces the media on the template's mms body rather than adding
+        # to it, so a template can hold a default creative while a caller still sends
+        # something recipient-specific.
+        #
+        # Their presence is also what makes a message eligible for MMS on an auto-detect
+        # send: a message with nothing attached is delivered as SMS, because an MMS with
+        # no media is a more expensive text message.
+        #
+        # The recipient's carrier fetches each URL after the send is accepted, so it must
+        # stay publicly reachable — a link that expires, or one behind auth, arrives as a
+        # failed message.
+        media_urls: nil,
         # Sandbox flag - when true, the operation is simulated without side effects Useful
         # for testing integrations without actual execution
         sandbox: nil,
+        # Optional future send time as an ISO-8601 timestamp with an explicit UTC offset,
+        # e.g. 2026-10-01T09:00:00+02:00 or 2026-10-01T07:00:00Z. A value without an
+        # offset is rejected (400) rather than read in the server's zone. The offset only
+        # fixes the instant: it is stored and echoed in UTC as scheduled_at. Omit to send
+        # now. Must be at least one minute ahead and at most 30 days ahead. Accepted
+        # messages report SCHEDULED and are released for delivery at this time. Quiet
+        # hours, balance and template approval are evaluated at release, not at
+        # acceptance: a message whose time falls inside a recipient's protected
+        # quiet-hours window is moved to the next allowed time and a second
+        # message.scheduled webhook reports the new scheduled_at.
+        scheduled_at: nil,
+        # Subject line for this send, overriding the template's. MMS only; ignored on
+        # every other channel. Most handsets render it above the body, some ignore it
+        # entirely.
+        subject: nil,
         # SDK-style template reference: resolve by ID or by name, with optional
         # parameters.
         template: nil,
@@ -97,7 +166,10 @@ module Sentdm
         override.returns(
           {
             channel: T.nilable(T::Array[String]),
+            media_urls: T.nilable(T::Array[String]),
             sandbox: T::Boolean,
+            scheduled_at: T.nilable(Time),
+            subject: T.nilable(String),
             template: T.nilable(Sentdm::MessageSendParams::Template),
             text: T.nilable(String),
             to: T::Array[String],
@@ -127,7 +199,20 @@ module Sentdm
         sig { returns(T.nilable(String)) }
         attr_accessor :name
 
-        # Template variable parameters for personalization
+        # Template variable parameters for personalization, keyed by variable name.
+        #
+        # Every variable the template declares is required; GET /v3/templates/{id} lists
+        # them. Supplying a key the template does not declare is ignored.
+        #
+        # Media headers. A template whose header is an image (designed in WhatsApp Manager
+        # and imported into Sent) declares a reserved header_image key. Its value is a
+        # publicly reachable https URL that Meta fetches at send time — Sent does not host
+        # the asset, and the sample approved with the template is not reused. The key is
+        # derived from the header's media type, so header_video and header_document follow
+        # the same shape when those formats ship.
+        #
+        # "parameters": { "header_image": "https://cdn.example.com/banner.jpg", "name":
+        # "John Doe" }
         sig { returns(T.nilable(T::Hash[Symbol, String])) }
         attr_accessor :parameters
 
@@ -145,7 +230,20 @@ module Sentdm
           id: nil,
           # Template name (mutually exclusive with id)
           name: nil,
-          # Template variable parameters for personalization
+          # Template variable parameters for personalization, keyed by variable name.
+          #
+          # Every variable the template declares is required; GET /v3/templates/{id} lists
+          # them. Supplying a key the template does not declare is ignored.
+          #
+          # Media headers. A template whose header is an image (designed in WhatsApp Manager
+          # and imported into Sent) declares a reserved header_image key. Its value is a
+          # publicly reachable https URL that Meta fetches at send time — Sent does not host
+          # the asset, and the sample approved with the template is not reused. The key is
+          # derived from the header's media type, so header_video and header_document follow
+          # the same shape when those formats ship.
+          #
+          # "parameters": { "header_image": "https://cdn.example.com/banner.jpg", "name":
+          # "John Doe" }
           parameters: nil
         )
         end

data/rbi/sentdm/models/message_send_response.rbi

@@ -17,7 +17,9 @@ module Sentdm
       # its result; this is what a caller sees, and the mapping between them is a
       # decision the endpoint makes.
       #
-      # The wire is unchanged by the move: same names, same values.
+      # The shape of an immediate send: it never has a scheduled_at key. A send that
+      # carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+      # which of the two to answer with. From always returns this type.
       sig { returns(T.nilable(Sentdm::Models::MessageSendResponse::Data)) }
       attr_reader :data
 
@@ -68,7 +70,9 @@ module Sentdm
         # its result; this is what a caller sees, and the mapping between them is a
         # decision the endpoint makes.
         #
-        # The wire is unchanged by the move: same names, same values.
+        # The shape of an immediate send: it never has a scheduled_at key. A send that
+        # carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+        # which of the two to answer with. From always returns this type.
         data: nil,
         # Error information
         error: nil,
@@ -120,7 +124,9 @@ module Sentdm
         end
         attr_writer :recipients
 
-        # Overall status — QUEUED once the batch is accepted for delivery.
+        # QUEUED: the batch is accepted. A request that carried scheduled_at is QUEUED
+        # here too; each message moves to SCHEDULED once it is held, as GET
+        # /v3/messages/{id} and the message.scheduled webhook report.
         sig { returns(T.nilable(String)) }
         attr_reader :status
 
@@ -148,7 +154,9 @@ module Sentdm
         # its result; this is what a caller sees, and the mapping between them is a
         # decision the endpoint makes.
         #
-        # The wire is unchanged by the move: same names, same values.
+        # The shape of an immediate send: it never has a scheduled_at key. A send that
+        # carried scheduled_at is a ScheduledSendMessageResponse, and the endpoint decides
+        # which of the two to answer with. From always returns this type.
         sig do
           params(
             recipients:
@@ -162,7 +170,9 @@ module Sentdm
         end
         def self.new(
           recipients: nil,
-          # Overall status — QUEUED once the batch is accepted for delivery.
+          # QUEUED: the batch is accepted. A request that carried scheduled_at is QUEUED
+          # here too; each message moves to SCHEDULED once it is held, as GET
+          # /v3/messages/{id} and the message.scheduled webhook report.
           status: nil,
           template_id: nil,
           template_name: nil

data/rbi/sentdm/models/template_body.rbi

@@ -6,6 +6,19 @@ module Sentdm
       OrHash =
         T.type_alias { T.any(Sentdm::TemplateBody, Sentdm::Internal::AnyHash) }
 
+      # MMS-specific content — subject, text and attachments.
+      #
+      # Like Rcs, an override that cannot stand on its own: a template still needs a
+      # MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
+      # Rcs, it has no fallback at send time — MMS with no media is a more expensive
+      # SMS, so a template without this slot is deliberately not MMS-capable and never
+      # produces an MMS route candidate.
+      sig { returns(T.nilable(Sentdm::TemplateBody::Mms)) }
+      attr_reader :mms
+
+      sig { params(mms: T.nilable(Sentdm::TemplateBody::Mms::OrHash)).void }
+      attr_writer :mms
+
       # The shared body, used for every channel. One half of the choice described above.
       sig { returns(T.nilable(Sentdm::TemplateBodyContent)) }
       attr_reader :multi_channel
@@ -54,6 +67,7 @@ module Sentdm
       # the copy, but cannot stand alone.
       sig do
         params(
+          mms: T.nilable(Sentdm::TemplateBody::Mms::OrHash),
           multi_channel: T.nilable(Sentdm::TemplateBodyContent::OrHash),
           rcs: T.nilable(Sentdm::TemplateBodyContent::OrHash),
           sms: T.nilable(Sentdm::TemplateBodyContent::OrHash),
@@ -61,6 +75,14 @@ module Sentdm
         ).returns(T.attached_class)
       end
       def self.new(
+        # MMS-specific content — subject, text and attachments.
+        #
+        # Like Rcs, an override that cannot stand on its own: a template still needs a
+        # MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
+        # Rcs, it has no fallback at send time — MMS with no media is a more expensive
+        # SMS, so a template without this slot is deliberately not MMS-capable and never
+        # produces an MMS route candidate.
+        mms: nil,
         # The shared body, used for every channel. One half of the choice described above.
         multi_channel: nil,
         # RCS-specific copy that overrides the chosen strategy for RCS only. The one true
@@ -77,6 +99,7 @@ module Sentdm
       sig do
         override.returns(
           {
+            mms: T.nilable(Sentdm::TemplateBody::Mms),
             multi_channel: T.nilable(Sentdm::TemplateBodyContent),
             rcs: T.nilable(Sentdm::TemplateBodyContent),
             sms: T.nilable(Sentdm::TemplateBodyContent),
@@ -86,6 +109,116 @@ module Sentdm
       end
       def to_hash
       end
+
+      class Mms < Sentdm::Models::TemplateBodyContent
+        OrHash =
+          T.type_alias do
+            T.any(Sentdm::TemplateBody::Mms, Sentdm::Internal::AnyHash)
+          end
+
+        # Attachments carried by every send on this template, in order. A per-send
+        # media_urls on the request replaces this list rather than adding to it, so a
+        # template can hold a default creative and a caller can still send something
+        # recipient-specific.
+        sig { returns(T.nilable(T::Array[Sentdm::TemplateBody::Mms::Media])) }
+        attr_accessor :media
+
+        # MMS subject line. Optional — most handsets render it above the body, some ignore
+        # it entirely. Deliberately its own field rather than riding TemplateHeader: the
+        # header is authored once and shared across every channel, and carries Meta's
+        # 60-character cap plus its no-newline, no-emoji text rules, none of which
+        # describe an MMS subject.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :subject
+
+        # MMS-specific content — subject, text and attachments.
+        #
+        # Like Rcs, an override that cannot stand on its own: a template still needs a
+        # MultiChannel body or the Sms + Whatsapp pair to be deliverable at all. Unlike
+        # Rcs, it has no fallback at send time — MMS with no media is a more expensive
+        # SMS, so a template without this slot is deliberately not MMS-capable and never
+        # produces an MMS route candidate.
+        sig do
+          params(
+            media:
+              T.nilable(T::Array[Sentdm::TemplateBody::Mms::Media::OrHash]),
+            subject: T.nilable(String)
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # Attachments carried by every send on this template, in order. A per-send
+          # media_urls on the request replaces this list rather than adding to it, so a
+          # template can hold a default creative and a caller can still send something
+          # recipient-specific.
+          media: nil,
+          # MMS subject line. Optional — most handsets render it above the body, some ignore
+          # it entirely. Deliberately its own field rather than riding TemplateHeader: the
+          # header is authored once and shared across every channel, and carries Meta's
+          # 60-character cap plus its no-newline, no-emoji text rules, none of which
+          # describe an MMS subject.
+          subject: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              media: T.nilable(T::Array[Sentdm::TemplateBody::Mms::Media]),
+              subject: T.nilable(String)
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Media < Sentdm::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(Sentdm::TemplateBody::Mms::Media, Sentdm::Internal::AnyHash)
+            end
+
+          # One of MmsMediaTypes. Advisory: the carrier reads the Content-Type off the
+          # fetched object, not this field. It exists so an authoring UI can render the
+          # right preview and so a reviewer can see what was intended.
+          sig { returns(T.nilable(String)) }
+          attr_accessor :media_type
+
+          # Publicly fetchable https URL. The carrier's MMSC fetches this at send time, so
+          # it has to stay reachable and unauthenticated for the life of the send —
+          # including retries and a DLQ replay — which is why a presigned URL is not a valid
+          # value here.
+          sig { returns(T.nilable(String)) }
+          attr_reader :url
+
+          sig { params(url: String).void }
+          attr_writer :url
+
+          # One attachment on an MMS template body.
+          sig do
+            params(media_type: T.nilable(String), url: String).returns(
+              T.attached_class
+            )
+          end
+          def self.new(
+            # One of MmsMediaTypes. Advisory: the carrier reads the Content-Type off the
+            # fetched object, not this field. It exists so an authoring UI can render the
+            # right preview and so a reviewer can see what was intended.
+            media_type: nil,
+            # Publicly fetchable https URL. The carrier's MMSC fetches this at send time, so
+            # it has to stay reachable and unauthenticated for the life of the send —
+            # including retries and a DLQ replay — which is why a presigned URL is not a valid
+            # value here.
+            url: nil
+          )
+          end
+
+          sig do
+            override.returns({ media_type: T.nilable(String), url: String })
+          end
+          def to_hash
+          end
+        end
+      end
     end
   end
 end

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

@@ -86,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
 
@@ -117,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:,