sentdm 0.44.0 → 0.46.0

data/rbi/sentdm/resources/channels.rbi

@@ -2,7 +2,124 @@
 
 module Sentdm
   module Resources
+    # The senders you send from, one per channel.
+    #
+    # **SMS is a list of markets**, each keyed by `(country, number_type)` — a
+    # customer can hold `us/10dlc` and `gb/alphanumeric` at once, so a market is
+    # addressed by the pair rather than by country alone. **WhatsApp and RCS are
+    # single**: a customer has one business account and one agent. **Voice is per
+    # number**: each number you hold can carry phone calls on its own
+    # (`POST /v3/channels/voice`), each with the callback URL Sent asks what to do
+    # with its calls, one of them is the default line for calls placed from your app,
+    # and voice tokens are minted with `POST /v3/voice/tokens`. Read your voice
+    # numbers with `GET /v3/channels/voice` and change one with
+    # `PATCH /v3/channels/voice/{number}`.
+    #
+    # ## Compliance lives on the market
+    #
+    # Adding a market records everything that market registers with, in its
+    # `compliance` object. Only **US `TEN_DLC`** registers with a regime — The
+    # Campaign Registry — and it is the only market whose compliance carries `brand`
+    # and `campaign`. Everywhere else compliance is documents, and many markets ask
+    # for none at all.
+    #
+    # `GET` and `PATCH` on a market return and accept the same shape, so what comes
+    # back can be sent back: an omitted key is left alone, and a key reported in
+    # `requirements` is the path into the body that clears it.
+    #
+    # Call `GET /v3/compliance/requirements` first — it answers what a market demands
+    # before you hold it, with a body you can fill in and post.
     class Channels
+      # The senders you send from, one per channel.
+      #
+      # **SMS is a list of markets**, each keyed by `(country, number_type)` — a
+      # customer can hold `us/10dlc` and `gb/alphanumeric` at once, so a market is
+      # addressed by the pair rather than by country alone. **WhatsApp and RCS are
+      # single**: a customer has one business account and one agent. **Voice is per
+      # number**: each number you hold can carry phone calls on its own
+      # (`POST /v3/channels/voice`), each with the callback URL Sent asks what to do
+      # with its calls, one of them is the default line for calls placed from your app,
+      # and voice tokens are minted with `POST /v3/voice/tokens`. Read your voice
+      # numbers with `GET /v3/channels/voice` and change one with
+      # `PATCH /v3/channels/voice/{number}`.
+      #
+      # ## Compliance lives on the market
+      #
+      # Adding a market records everything that market registers with, in its
+      # `compliance` object. Only **US `TEN_DLC`** registers with a regime — The
+      # Campaign Registry — and it is the only market whose compliance carries `brand`
+      # and `campaign`. Everywhere else compliance is documents, and many markets ask
+      # for none at all.
+      #
+      # `GET` and `PATCH` on a market return and accept the same shape, so what comes
+      # back can be sent back: an omitted key is left alone, and a key reported in
+      # `requirements` is the path into the body that clears it.
+      #
+      # Call `GET /v3/compliance/requirements` first — it answers what a market demands
+      # before you hold it, with a body you can fill in and post.
+      sig { returns(Sentdm::Resources::Channels::SMS) }
+      attr_reader :sms
+
+      # The senders you send from, one per channel.
+      #
+      # **SMS is a list of markets**, each keyed by `(country, number_type)` — a
+      # customer can hold `us/10dlc` and `gb/alphanumeric` at once, so a market is
+      # addressed by the pair rather than by country alone. **WhatsApp and RCS are
+      # single**: a customer has one business account and one agent. **Voice is per
+      # number**: each number you hold can carry phone calls on its own
+      # (`POST /v3/channels/voice`), each with the callback URL Sent asks what to do
+      # with its calls, one of them is the default line for calls placed from your app,
+      # and voice tokens are minted with `POST /v3/voice/tokens`. Read your voice
+      # numbers with `GET /v3/channels/voice` and change one with
+      # `PATCH /v3/channels/voice/{number}`.
+      #
+      # ## Compliance lives on the market
+      #
+      # Adding a market records everything that market registers with, in its
+      # `compliance` object. Only **US `TEN_DLC`** registers with a regime — The
+      # Campaign Registry — and it is the only market whose compliance carries `brand`
+      # and `campaign`. Everywhere else compliance is documents, and many markets ask
+      # for none at all.
+      #
+      # `GET` and `PATCH` on a market return and accept the same shape, so what comes
+      # back can be sent back: an omitted key is left alone, and a key reported in
+      # `requirements` is the path into the body that clears it.
+      #
+      # Call `GET /v3/compliance/requirements` first — it answers what a market demands
+      # before you hold it, with a body you can fill in and post.
+      sig { returns(Sentdm::Resources::Channels::Rcs) }
+      attr_reader :rcs
+
+      # The senders you send from, one per channel.
+      #
+      # **SMS is a list of markets**, each keyed by `(country, number_type)` — a
+      # customer can hold `us/10dlc` and `gb/alphanumeric` at once, so a market is
+      # addressed by the pair rather than by country alone. **WhatsApp and RCS are
+      # single**: a customer has one business account and one agent. **Voice is per
+      # number**: each number you hold can carry phone calls on its own
+      # (`POST /v3/channels/voice`), each with the callback URL Sent asks what to do
+      # with its calls, one of them is the default line for calls placed from your app,
+      # and voice tokens are minted with `POST /v3/voice/tokens`. Read your voice
+      # numbers with `GET /v3/channels/voice` and change one with
+      # `PATCH /v3/channels/voice/{number}`.
+      #
+      # ## Compliance lives on the market
+      #
+      # Adding a market records everything that market registers with, in its
+      # `compliance` object. Only **US `TEN_DLC`** registers with a regime — The
+      # Campaign Registry — and it is the only market whose compliance carries `brand`
+      # and `campaign`. Everywhere else compliance is documents, and many markets ask
+      # for none at all.
+      #
+      # `GET` and `PATCH` on a market return and accept the same shape, so what comes
+      # back can be sent back: an omitted key is left alone, and a key reported in
+      # `requirements` is the path into the body that clears it.
+      #
+      # Call `GET /v3/compliance/requirements` first — it answers what a market demands
+      # before you hold it, with a body you can fill in and post.
+      sig { returns(Sentdm::Resources::Channels::Whatsapp) }
+      attr_reader :whatsapp
+
       # The senders you send from, one per channel.
       #
       # **SMS is a list of markets**, each keyed by `(country, number_type)` — a
@@ -33,6 +150,38 @@ module Sentdm
       sig { returns(Sentdm::Resources::Channels::Voice) }
       attr_reader :voice
 
+      # Every market you send SMS in, your WhatsApp account, your RCS agent and the
+      # numbers you carry phone calls on — with each one's status, and what each market
+      # has supplied.
+      #
+      # **Status lives on the channel, never on you or your brand.** An identity has no
+      # lifecycle; what has one is the registration of a sender in a market and the
+      # approval of a channel. So a customer live in one country and mid-registration in
+      # another reports exactly that, rather than one flattened answer.
+      #
+      # `sms[n].compliance` carries what each market holds: `brand` and `campaign` for
+      # markets that register with a compliance regime such as US TEN_DLC, and
+      # `documents` for markets that pre-register an alphanumeric or similar sender.
+      # Absent means the market registers with nobody and nothing has been supplied.
+      # `GET /v3/compliance/requirements` says what a market demands of any new
+      # customer; this says what you gave it.
+      #
+      # Send `x-profile-id` with an organization key to read one of your profiles'
+      # channels.
+      sig do
+        params(
+          x_profile_id: String,
+          request_options: Sentdm::RequestOptions::OrHash
+        ).returns(Sentdm::APIResponseOfChannelsState)
+      end
+      def list(
+        # Profile UUID to scope the request to a child profile. Only organization API keys
+        # can use this header. The profile must belong to the calling organization.
+        x_profile_id: nil,
+        request_options: {}
+      )
+      end
+
       # @api private
       sig { params(client: Sentdm::Client).returns(T.attached_class) }
       def self.new(client:)

data/rbi/sentdm/resources/compliance.rbi

@@ -0,0 +1,121 @@
+# typed: strong
+
+module Sentdm
+  module Resources
+    # What a market demands, before you have it.
+    #
+    # Requirements vary enormously and change without notice. US `TEN_DLC` registers a
+    # brand and a campaign with The Campaign Registry and asks a substantial set of
+    # questions; an alphanumeric sender pre-registers with documents in one country
+    # and needs nothing in another.
+    #
+    # This is the authoritative answer for whichever market you ask about, and it is
+    # generated from the same declaration that validates the calls themselves — so it
+    # cannot drift from what is actually enforced. The response includes the request
+    # body to send, with every key that market wants already present and blank.
+    #
+    # What you supplied, as opposed to what is asked of you, is reported on the market
+    # under **Channels**.
+    class Compliance
+      # **Call this first.** It returns what a channel, country and sender type demand
+      # before you can send there — and `setup[]`, the calls that satisfy those demands,
+      # in order, each with a body you can copy and send as it stands. You never have to
+      # track forty countries' rules yourself.
+      #
+      # ## Channel
+      #
+      # `channel` is `sms`, `whatsapp` or `rcs`, and **defaults to `sms`** — so a caller
+      # that omits it gets exactly what this endpoint has always returned.
+      #
+      # `sms` is the only one answered today; the other two are `501` until their
+      # requirements are declared. They are refused rather than answered with an empty
+      # requirement set, because empty would say the channel demands nothing, and both
+      # demand plenty — WhatsApp a business verification and a display name review, RCS
+      # a carrier approval. Saying "not yet" is the true answer and the same one
+      # `POST /v3/sender-profiles` gives for `channels.whatsapp`.
+      #
+      # `type` is an SMS sender type, and SMS is the only channel whose senders have
+      # one.
+      #
+      # Requirements vary enormously. US `TEN_DLC` registers a brand and a campaign with
+      # The Campaign Registry and asks for a substantial set of values. An alphanumeric
+      # sender in one country pre-registers with supporting documents; in another it
+      # needs nothing at all. This is the authoritative answer for whichever market you
+      # are asking about, and it is the same declaration used to validate the calls
+      # themselves — so it can never drift from what is actually enforced.
+      #
+      # ## `setup[]` — what to do
+      #
+      # **One step.** `POST /v3/channels/sms` adds the market and records everything it
+      # registers with — the identity in `compliance.brand`, the programme in
+      # `compliance.campaign`. There were three, in a load-bearing order, while the
+      # identity and the campaign were resources of their own; they are members of this
+      # call's body now, so there is nothing to sequence.
+      #
+      # Correct any of it afterwards with `PATCH /v3/channels/sms/{country}/{type}`,
+      # which takes the same `compliance` object one key at a time.
+      #
+      # Each step's `body` has every key that market wants already present, with the
+      # values left **blank**. Blank rather than filled with placeholders, because the
+      # body is meant to be sent: a null value counts as not supplied, so posting a step
+      # verbatim comes back naming every blank you left. `attachments[]` lists files to
+      # send as multipart on the channel call, each under the field name given — a file
+      # cannot be a JSON value, so documents are never listed in `compliance[]`.
+      #
+      # Every step is a call for whoever holds the key. To set a **sender profile** up
+      # instead, send the same requests with the `x-profile-id` header naming it; there
+      # is no separate path.
+      #
+      # ## `requirements[]` — what each value means
+      #
+      # Each entry names a key for the `compliance` array, its value type, and whether
+      # it is required. `required_when` marks values needed only in certain cases —
+      # evaluate it against your own payload, e.g. `brand.entity_type == PUBLIC_PROFIT`.
+      # `options` lists accepted values where the market constrains them, and `label` is
+      # suitable for rendering a form field.
+      #
+      # Values Sent supplies on your behalf are never listed: correlation ids,
+      # environment flags, carrier elections, and booleans derivable from what you
+      # already send.
+      #
+      # ## When nothing is required
+      #
+      # `required` is `false` and `requirements` is empty, and the single `setup` step
+      # carries no `compliance` array at all. A `sender_id_pattern` may still be present
+      # — many markets constrain the sender string without registering anything.
+      sig do
+        params(
+          channel: T.nilable(String),
+          country: T.nilable(String),
+          type: T.nilable(String),
+          x_profile_id: String,
+          request_options: Sentdm::RequestOptions::OrHash
+        ).returns(Sentdm::APIResponseOfComplianceRequirements)
+      end
+      def retrieve_requirements(
+        # Query param: Channel the sender is for: sms, whatsapp or rcs. Defaults to sms,
+        # which is the only one answered today — the other two are 501 until their
+        # requirements are declared.
+        channel: nil,
+        # Query param: ISO 3166-1 alpha-2 country code, e.g. US, XK, IN
+        country: nil,
+        # Query param: Sender type: LOCAL, MOBILE, TEN_DLC, TOLL_FREE, SHORT_CODE,
+        # ALPHANUMERIC. 10DLC is accepted as a synonym of TEN_DLC, the same as on POST
+        # /v3/sender-profiles. Applies to channel=sms, the only channel whose senders have
+        # a type.
+        type: nil,
+        # Header param: Profile UUID to scope the request to a child profile. Only
+        # organization API keys can use this header. The profile must belong to the
+        # calling organization.
+        x_profile_id: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Sentdm::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/sentdm/resources/conversations.rbi

@@ -19,11 +19,7 @@ module Sentdm
           page_size: Integer,
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(
-          Sentdm::Internal::ConversationsPage[
-            Sentdm::ConversationMessagesList::Message
-          ]
-        )
+        ).returns(Sentdm::Internal::ConversationsPage[Sentdm::Message])
       end
       def list(
         # Query param
@@ -47,11 +43,7 @@ module Sentdm
           page_size: Integer,
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(
-          Sentdm::Internal::ConversationsPage[
-            Sentdm::ConversationMessagesList::Message
-          ]
-        )
+        ).returns(Sentdm::Internal::ConversationsPage[Sentdm::Message])
       end
       def list_messages(
         # Path param: Conversation id from the route.

data/rbi/sentdm/resources/me.rbi

@@ -44,7 +44,7 @@ module Sentdm
         params(
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(Sentdm::Models::MeRetrieveResponse)
+        ).returns(Sentdm::APIResponseOfAccount)
       end
       def retrieve(
         # Profile UUID to scope the request to a child profile. Only organization API keys

data/rbi/sentdm/resources/messages.rbi

@@ -25,6 +25,66 @@ module Sentdm
     # released yet. Cancelling is free, fires `message.cancelled`, and is final — a
     # cancelled message cannot be resent.
     class Messages
+      # Calls off a message you scheduled with `scheduled_at`, before it is released for
+      # sending. The message moves to `CANCELLED`, which is terminal, and it is never
+      # sent.
+      #
+      # **Only a SCHEDULED message can be cancelled.** A message that has already been
+      # released — queued, in flight, or finished — returns 409. The release sweeper
+      # runs continuously, so a cancellation sent within about a minute of the scheduled
+      # instant can lose that race and be refused; cancel with time to spare.
+      #
+      # **One message per call.** A send to many recipients, or on several channels,
+      # becomes one message per recipient × channel, each with its own id; cancel the
+      # ones you want stopped. There is no bulk cancellation.
+      #
+      # **Cancelling is free**, and nothing was charged for the hold in the first place
+      # — a scheduled message is only priced and billed at release.
+      #
+      # **A cancellation fires `message.cancelled`** on your webhook, exactly once,
+      # carrying the `scheduled_at` that was called off so a consumer can un-record the
+      # send it was expecting. Cancelling the same message again returns this same
+      # response and fires no second event. `Idempotency-Key` is honoured.
+      #
+      # A cancelled message cannot be resent — send a new one.
+      #
+      # The response is the message itself, in the same shape `GET /v3/messages/{id}`
+      # returns, so the `status` you read back is the one now stored on the row, and
+      # `scheduled_at` is the time it would have gone out. `GET /v3/messages/{id}` keeps
+      # reporting both afterwards.
+      #
+      # `events` is the message lifecycle as it stood immediately before the
+      # cancellation: the CANCELLED entry is written asynchronously and lands a moment
+      # later, so read `status` for the outcome. If you need the entry itself, re-fetch
+      # the message after a few seconds — `GET /v3/messages/{id}` is cached briefly, so
+      # an immediate re-fetch can still show the pre-cancellation state.
+      sig do
+        params(
+          id: String,
+          sandbox: T::Boolean,
+          idempotency_key: String,
+          x_profile_id: String,
+          request_options: Sentdm::RequestOptions::OrHash
+        ).returns(Sentdm::APIResponseOfCancelledMessage)
+      end
+      def cancel(
+        # Path param: Message ID
+        id,
+        # Body param: Sandbox flag - when true, the operation is simulated without side
+        # effects Useful for testing integrations without actual execution
+        sandbox: nil,
+        # Header param: Unique key to ensure idempotent request processing. Must be 1-255
+        # alphanumeric characters, hyphens, or underscores. Responses are cached for 24
+        # hours per key per customer.
+        idempotency_key: nil,
+        # Header param: Profile UUID to scope the request to a child profile. Only
+        # organization API keys can use this header. The profile must belong to the
+        # calling organization.
+        x_profile_id: nil,
+        request_options: {}
+      )
+      end
+
       # Resends a message you already sent, on the same message id, without rebuilding
       # the request. The typical use is recovering a BLOCKED message — for example one
       # refused for insufficient balance — after the account has been topped up.
@@ -90,7 +150,7 @@ module Sentdm
           id: String,
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(Sentdm::Models::MessageRetrieveActivitiesResponse)
+        ).returns(Sentdm::APIResponseOfMessageActivities)
       end
       def retrieve_activities(
         # Message ID from route parameter
@@ -114,7 +174,7 @@ module Sentdm
           id: String,
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(Sentdm::Models::MessageRetrieveStatusResponse)
+        ).returns(Sentdm::APIResponseOfMessage)
       end
       def retrieve_status(
         # Message ID
@@ -159,22 +219,20 @@ module Sentdm
       # 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).
+      # hold at most 1,000,000 scheduled messages at once: a message scheduled past that
+      # is reported as BLOCKED (LIMIT_001) instead of being held.
       sig do
         params(
           channel: T.nilable(T::Array[String]),
           channels:
             T.nilable(
-              T::Hash[
-                Symbol,
-                T::Array[Sentdm::MessageSendParams::Channel::OrHash]
-              ]
+              T::Hash[Symbol, T::Array[Sentdm::MessageChannelOptions::OrHash]]
             ),
           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),
+          template: T.nilable(Sentdm::TemplateRef::OrHash),
           text: T.nilable(String),
           to: T::Array[String],
           idempotency_key: String,

data/rbi/sentdm/resources/numbers.rbi

@@ -17,7 +17,7 @@ module Sentdm
           phone_number: String,
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(Sentdm::Models::NumberLookupResponse)
+        ).returns(Sentdm::APIResponseOfNumberLookupResult)
       end
       def lookup(
         phone_number,

data/rbi/sentdm/resources/profiles.rbi

@@ -364,7 +364,7 @@ module Sentdm
         params(
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(Sentdm::Models::ProfileListResponse)
+        ).returns(Sentdm::APIResponseOfProfilesList)
       end
       def list(
         # Profile UUID to scope the request to a child profile. Only organization API keys
@@ -465,7 +465,7 @@ module Sentdm
           idempotency_key: String,
           x_profile_id: String,
           request_options: Sentdm::RequestOptions::OrHash
-        ).returns(Sentdm::Models::ProfileCompleteResponse)
+        ).returns(Sentdm::APIResponseOfProfileCompletionResult)
       end
       def complete(
         # Path param: Profile ID from route