sentdm 0.31.0 → 0.33.0

data/lib/sentdm/resources/messages.rb

@@ -13,12 +13,20 @@ module Sentdm
     # **A message needs a sender.** What you can send, where, and at what cost is
     # decided by the markets under **Channels** — so a recipient in a country you hold
     # no sender for is refused here rather than queued.
+    #
+    # **A message can be resent on its id.** `POST /v3/messages/{id}/resend` puts a
+    # finished message — typically one BLOCKED for insufficient balance — back through
+    # the send pipeline. It is a new attempt, not a free retry: every policy runs
+    # again, the message is billed again, and its status webhooks fire again. A
+    # FILTERED message is never resendable.
     class Messages
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::MessageRetrieveActivitiesParams} for more details.
       #
       # Retrieves the activity log for a specific message. Activities track the message
-      # lifecycle including acceptance, processing, sending, delivery, and any errors.
+      # lifecycle including acceptance, processing, sending, delivery, and any errors. A
+      # SCHEDULED entry carries scheduled_at, the release instant in UTC as it stood at
+      # that moment. Other entries have no scheduled_at key.
       #
       # @overload retrieve_activities(id, x_profile_id: nil, request_options: {})
       #
@@ -46,7 +54,11 @@ module Sentdm
       # {Sentdm::Models::MessageRetrieveStatusParams} for more details.
       #
       # Retrieves the current status and details of a message by ID. Includes delivery
-      # status, timestamps, and error information if applicable.
+      # status, timestamps, and error information if applicable. A message that is or
+      # was held for a later time (a send you scheduled with scheduled_at, or a
+      # quiet-hours hold) is returned as a ScheduledMessageResponse: the same fields
+      # plus scheduled_at, the release instant in UTC. A message sent immediately has no
+      # scheduled_at key.
       #
       # @overload retrieve_status(id, x_profile_id: nil, request_options: {})
       #
@@ -82,14 +94,30 @@ module Sentdm
       # insufficient balance, a template not approved for sending, or free-form content
       # with no open conversation with the contact. The send is accepted with 202 and
       # the affected messages are reported as BLOCKED on GET /messages/{id} and the
-      # message.blocked webhook.
-      #
-      # @overload send_(channel: nil, sandbox: nil, template: nil, text: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+      # message.blocked webhook. To send later, set scheduled_at (ISO-8601 with an
+      # explicit UTC offset; a value without one is rejected) between 1 minute and 30
+      # days ahead: the response is a ScheduledSendMessageResponse (the same fields plus
+      # scheduled_at; status is still QUEUED), each message then moves to SCHEDULED, is
+      # held and released at that time (within a few minutes), and a message.scheduled
+      # webhook fires once it is held. Balance and template approval are evaluated at
+      # release, not at acceptance. Quiet hours are not checked when the request is
+      # accepted: if the time falls inside a legally protected quiet-hours window for a
+      # recipient, that message is moved to the next allowed time at release and a
+      # second message.scheduled webhook reports the new scheduled_at. An account may
+      # hold at most 1,000,000 scheduled messages at once (429 LIMIT_001).
+      #
+      # @overload send_(channel: nil, media_urls: nil, sandbox: nil, scheduled_at: nil, subject: nil, template: nil, text: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
       # @param channel [Array<String>, nil] Body param: Channels to broadcast on, e.g. ["whatsapp", "sms"].
       #
+      # @param media_urls [Array<String>, nil] Body param: Attachments for this send, as publicly fetchable https URLs. Used by
+      #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
+      # @param scheduled_at [Time, nil] Body param: Optional future send time as an ISO-8601 timestamp with an explicit
+      #
+      # @param subject [String, nil] Body param: Subject line for this send, overriding the template's. MMS only; ign
+      #
       # @param template [Sentdm::Models::MessageSendParams::Template, nil] Body param: SDK-style template reference: resolve by ID or by name, with optiona
       #
       # @param text [String, nil] Body param: Plain-text (free-form) message body. Provide either Template or this

data/lib/sentdm/resources/templates.rb

@@ -15,7 +15,9 @@ module Sentdm
       #
       # Creates a new message template with header, body, footer, and buttons. The
       # template can be submitted for review immediately or saved as draft for later
-      # submission.
+      # submission. There is no `name` field on create — the display name is derived
+      # from the template's content and can be changed afterwards with
+      # `PUT /v3/templates/{id}`.
       #
       # @overload create(category: nil, creation_source: nil, definition: nil, language: nil, sandbox: nil, submit_for_review: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
@@ -85,7 +87,31 @@ module Sentdm
       # {Sentdm::Models::TemplateUpdateParams} for more details.
       #
       # Updates an existing template's name, category, language, definition, or submits
-      # it for review.
+      # it for review. While the template is in review (status PENDING, or any channel
+      # awaiting a verdict) its definition, category and language are frozen and a
+      # resubmission is refused — those requests answer 409 CONFLICT_006. The display
+      # name stays editable throughout.
+      #
+      # `definition`, `category` and `language` are editable only from status DRAFT,
+      # REJECTED or APPROVED. An edit to any of them on a template in another state
+      # (PAUSED, DISABLED or REVOKED) is refused with 400 VALIDATION_001 and the detail
+      # "Template (except display name) cannot be updated unless it is in draft or
+      # rejected status"; `name` stays editable in every state. `submit_for_review` on a
+      # PAUSED, DISABLED or REVOKED template is accepted and answers 200, but opens no
+      # review and does not move the status — only the reviewer can reinstate it.
+      #
+      # Editing an APPROVED template is a live edit: the new content is stored
+      # immediately, and sending `submit_for_review: true` re-opens review, which
+      # returns the affected channels to PENDING so they stop sending until they are
+      # approved again. The previously approved content is never sent during re-review.
+      # Watch the per-channel `templates` webhook events rather than assuming the
+      # template-level status.
+      #
+      # Templates provisioned by Sent (light-onboarding templates, whose names carry the
+      # reserved `sent_` prefix) are read-only: every field is refused with 400
+      # VALIDATION*001 and the detail "This template is read-only. Only 'submit for
+      # review' is allowed.", and only `submit_for_review` is accepted. A `name`
+      # starting with `sent*` is refused for the same reason — the prefix is reserved.
       #
       # @overload update(id, category: nil, definition: nil, language: nil, name: nil, sandbox: nil, submit_for_review: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #

data/lib/sentdm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sentdm
-  VERSION = "0.31.0"
+  VERSION = "0.33.0"
 end

data/lib/sentdm.rb

@@ -58,6 +58,7 @@ require_relative "sentdm/internal/templates_page"
 require_relative "sentdm/internal/webhook_events_page"
 require_relative "sentdm/internal/webhooks_page"
 require_relative "sentdm/models/mutation_request"
+require_relative "sentdm/models/template_body_content"
 require_relative "sentdm/models/api_meta"
 require_relative "sentdm/models/api_response_of_contact"
 require_relative "sentdm/models/api_response_of_contact_message_summary"
@@ -72,8 +73,12 @@ require_relative "sentdm/models/brand_business_info"
 require_relative "sentdm/models/brand_compliance_info"
 require_relative "sentdm/models/brand_contact_info"
 require_relative "sentdm/models/brands_brand_data"
+require_relative "sentdm/models/channel_event"
+require_relative "sentdm/models/channel_event_payload"
 require_relative "sentdm/models/contact_create_params"
 require_relative "sentdm/models/contact_delete_params"
+require_relative "sentdm/models/contact_event"
+require_relative "sentdm/models/contact_event_payload"
 require_relative "sentdm/models/contact_list_params"
 require_relative "sentdm/models/contact_message_summary"
 require_relative "sentdm/models/contact_response"
@@ -126,7 +131,6 @@ require_relative "sentdm/models/tcr_brand_relationship"
 require_relative "sentdm/models/tcr_vertical"
 require_relative "sentdm/models/template"
 require_relative "sentdm/models/template_body"
-require_relative "sentdm/models/template_body_content"
 require_relative "sentdm/models/template_button"
 require_relative "sentdm/models/template_button_props"
 require_relative "sentdm/models/template_create_params"

data/rbi/sentdm/client.rbi

@@ -78,6 +78,12 @@ module Sentdm
     # **A message needs a sender.** What you can send, where, and at what cost is
     # decided by the markets under **Channels** — so a recipient in a country you hold
     # no sender for is refused here rather than queued.
+    #
+    # **A message can be resent on its id.** `POST /v3/messages/{id}/resend` puts a
+    # finished message — typically one BLOCKED for insufficient balance — back through
+    # the send pipeline. It is a new attempt, not a free retry: every policy runs
+    # again, the message is billed again, and its status webhooks fire again. A
+    # FILTERED message is never resendable.
     sig { returns(Sentdm::Resources::Messages) }
     attr_reader :messages
 

data/rbi/sentdm/models/channel_event.rbi

@@ -0,0 +1,128 @@
+# typed: strong
+
+module Sentdm
+  module Models
+    class ChannelEvent < Sentdm::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias { T.any(Sentdm::ChannelEvent, Sentdm::Internal::AnyHash) }
+
+      # The specific event within the family, for example message.delivered,
+      # message.received or contact.opt_out. Absent on events that have no subtype, so
+      # treat it as optional.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :event
+
+      # The event family, for example message, templates or contact. Route on this
+      # first, then on event for the specific change.
+      sig { returns(T.nilable(String)) }
+      attr_reader :field
+
+      sig { params(field: String).void }
+      attr_writer :field
+
+      # Body of a channel event: where one of the customer's channels stands in
+      # provisioning and compliance. Delivered when a milestone moves — a registration
+      # filed, a verdict returned, a resubmission asked for, a sender gone live — so a
+      # customer's own onboarding UI does not have to poll GET /v3/channels.
+      #
+      # The subject is one item, never the account. A customer's "SMS channel" has no
+      # status; a market does. Country, NumberType and SenderValue name which one, so a
+      # customer terminating only to Kosovo never receives an event about US 10DLC.
+      #
+      # Status is the stable half of the contract. It is the same four-value set GET
+      # /v3/channels publishes, computed through the same code, so an event and a read
+      # of the same market cannot disagree. A subscriber that reads nothing but the
+      # status and the subject fields is a correct subscriber. The sub-type on the
+      # envelope names the specific milestone and is additive — that vocabulary comes
+      # from registries and carriers, which are parties Sent does not control.
+      #
+      # Status means provisioning and compliance are complete, not that a send will
+      # succeed right now. An account can be suspended, or a destination blocked by a
+      # routing rule, without either showing up here. Those are separate surfaces and
+      # deliberately not modelled on this payload.
+      sig { returns(T.nilable(Sentdm::ChannelEventPayload)) }
+      attr_reader :payload
+
+      sig do
+        params(payload: T.nilable(Sentdm::ChannelEventPayload::OrHash)).void
+      end
+      attr_writer :payload
+
+      # The event-specific body.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :request_id
+
+      # When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+      # time, not the time the underlying change happened. Use the timestamp inside the
+      # payload for the latter.
+      sig { returns(T.nilable(String)) }
+      attr_reader :timestamp
+
+      sig { params(timestamp: String).void }
+      attr_writer :timestamp
+
+      # The envelope Sent POSTs to a subscribed webhook endpoint. Every event shares
+      # this shape and varies only in Payload.
+      sig do
+        params(
+          event: T.nilable(String),
+          field: String,
+          payload: T.nilable(Sentdm::ChannelEventPayload::OrHash),
+          request_id: T.nilable(String),
+          timestamp: String
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The specific event within the family, for example message.delivered,
+        # message.received or contact.opt_out. Absent on events that have no subtype, so
+        # treat it as optional.
+        event: nil,
+        # The event family, for example message, templates or contact. Route on this
+        # first, then on event for the specific change.
+        field: nil,
+        # Body of a channel event: where one of the customer's channels stands in
+        # provisioning and compliance. Delivered when a milestone moves — a registration
+        # filed, a verdict returned, a resubmission asked for, a sender gone live — so a
+        # customer's own onboarding UI does not have to poll GET /v3/channels.
+        #
+        # The subject is one item, never the account. A customer's "SMS channel" has no
+        # status; a market does. Country, NumberType and SenderValue name which one, so a
+        # customer terminating only to Kosovo never receives an event about US 10DLC.
+        #
+        # Status is the stable half of the contract. It is the same four-value set GET
+        # /v3/channels publishes, computed through the same code, so an event and a read
+        # of the same market cannot disagree. A subscriber that reads nothing but the
+        # status and the subject fields is a correct subscriber. The sub-type on the
+        # envelope names the specific milestone and is additive — that vocabulary comes
+        # from registries and carriers, which are parties Sent does not control.
+        #
+        # Status means provisioning and compliance are complete, not that a send will
+        # succeed right now. An account can be suspended, or a destination blocked by a
+        # routing rule, without either showing up here. Those are separate surfaces and
+        # deliberately not modelled on this payload.
+        payload: nil,
+        # The event-specific body.
+        request_id: nil,
+        # When Sent emitted the event, in UTC (yyyy-MM-ddTHH:mm:ssZ). This is the emission
+        # time, not the time the underlying change happened. Use the timestamp inside the
+        # payload for the latter.
+        timestamp: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            event: T.nilable(String),
+            field: String,
+            payload: T.nilable(Sentdm::ChannelEventPayload),
+            request_id: T.nilable(String),
+            timestamp: String
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end