sentdm 0.47.0 → 0.48.0

data/lib/sentdm/resources/channels/sms/ten_dlc.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Resources
+    class Channels
+      class 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.
+        class TenDlc
+          # Some parameter documentations has been truncated, see
+          # {Sentdm::Models::Channels::SMS::TenDlcAddCampaignParams} for more details.
+          #
+          # Registers **a new campaign** on the US `TEN_DLC` market you already hold — the
+          # one market that registers campaigns. Use it when you want numbers for a
+          # different use case than the market's existing campaign covers. The campaign is
+          # filed under the brand the market files under — your organization's when you
+          # inherit its identity.
+          #
+          # ## What to send
+          #
+          # The new campaign's fields, at the top level of the body: use cases, consent
+          # narrative, volume, sample messages and keywords, under the
+          # `compliance.campaign.*` keys
+          # `GET /v3/compliance/requirements?country=US&type=TEN_DLC` lists, without that
+          # prefix. It has to be complete. A rejected field is keyed by its name
+          # (`description`). `id` and `inherit` are ignored, so an entry of
+          # `compliance.campaigns` can be sent as read.
+          #
+          # The identity is the market's and is not sent here. A market whose identity has
+          # no registration yet, or one not yet submitted for review, is `400`.
+          #
+          # ## What happens
+          #
+          # The campaign is recorded and goes for review; it is not filed with The Campaign
+          # Registry by this call. **It comes without numbers**: send its `id` from
+          # `compliance.campaigns` to `POST /v3/channels/sms/numbers/US/TEN_DLC` to give it
+          # some. **The campaign you already have, and its numbers, are not touched** —
+          # including a campaign you run on from your organization.
+          #
+          # **Each call files a new campaign**, which is charged when it is submitted. Send
+          # an `Idempotency-Key` so a retried request does not file a second one.
+          #
+          # To change the campaign a market already has, use
+          # `PATCH /v3/channels/sms/US/TEN_DLC`. Once a market holds more than one campaign,
+          # that `PATCH` refuses a campaign or numbers change (`409`) rather than guess
+          # which campaign is meant; numbers are added to a named campaign with
+          # `POST /v3/channels/sms/numbers/US/TEN_DLC`.
+          #
+          # Returns **the market**, in the shape `GET /v3/channels/sms/US/TEN_DLC` returns,
+          # with `202`.
+          #
+          # @overload add_campaign(idempotency_key:, description: nil, help_keywords: nil, help_message: nil, message_flow: nil, opt_in_keywords: nil, opt_in_message: nil, opt_out_keywords: nil, opt_out_message: nil, privacy_policy_link: nil, sandbox: nil, terms_and_conditions_link: nil, use_cases: nil, volume: nil, x_profile_id: nil, request_options: {})
+          #
+          # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+          #
+          # @param description [String] Body param: What this programme sends. TCR description: what recipients will get
+          #
+          # @param help_keywords [String] Body param: Help keywords. TCR helpKeywords, comma separated, e.g. HELP,INFO. Re
+          #
+          # @param help_message [String] Body param: Help reply. TCR helpMessage. Its presence is what sets subscriberHel
+          #
+          # @param message_flow [String] Body param: Consent narrative. TCR messageFlow: how recipients opt in, in prose.
+          #
+          # @param opt_in_keywords [String] Body param: Opt-in keywords. TCR optinKeywords, comma separated, e.g. START,YES.
+          #
+          # @param opt_in_message [String] Body param: Opt-in confirmation. TCR optinMessage. Should state message frequenc
+          #
+          # @param opt_out_keywords [String] Body param: Opt-out keywords. TCR optoutKeywords, comma separated. STOP, END, CA
+          #
+          # @param opt_out_message [String] Body param: Opt-out confirmation. TCR optoutMessage. Its presence is what sets s
+          #
+          # @param privacy_policy_link [String] Body param: Privacy policy URL. TCR privacyPolicyLink. Required when `compliance
+          #
+          # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+          #
+          # @param terms_and_conditions_link [String] Body param: Terms and conditions URL. TCR termsAndConditionsLink. Required when
+          #
+          # @param use_cases [Array<Sentdm::Models::Channels::SMS::TenDlcCampaignUseCase>] Body param: Use cases. What the campaign sends, and an example of each. One to f
+          #
+          # @param volume [String] Body param: Expected monthly volume. Decides how the campaign registers and whic
+          #
+          # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+          #
+          # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Sentdm::Models::Channels::APIResponseOfSMSMarket]
+          #
+          # @see Sentdm::Models::Channels::SMS::TenDlcAddCampaignParams
+          def add_campaign(params)
+            parsed, options = Sentdm::Channels::SMS::TenDlcAddCampaignParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+            @client.request(
+              method: :post,
+              path: "v3/channels/sms/compliances/US/TEN_DLC/campaigns",
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
+              model: Sentdm::Channels::APIResponseOfSMSMarket,
+              options: options
+            )
+          end
+
+          # Some parameter documentations has been truncated, see
+          # {Sentdm::Models::Channels::SMS::TenDlcAddNumbersParams} for more details.
+          #
+          # Adds numbers to **one campaign of your own** on the US `TEN_DLC` market you
+          # hold, named by `campaign_id` — the `id` of an entry in the market's
+          # `compliance.campaigns`.
+          #
+          # ## What to send
+          #
+          # - `campaign_id` — the campaign. One you inherit from your organization is `400`:
+          #   its numbers are the organization's. One out of service — expired, deactivated
+          #   or released — is `409`.
+          # - `numbers` — the list `POST /v3/channels/sms` takes, one entry per area code.
+          #
+          # ## What happens
+          #
+          # The entries are **added** to what the campaign already asks for. With everything
+          # it asks for, a campaign holds at most 49 numbers, counting one for each sender
+          # profile inheriting it. A campaign the carriers have not approved yet gets its
+          # numbers when they do; an approved one gets them now. Until a number is assigned
+          # it reads as `PROVISIONING` in the market's `numbers`, with the area code it was
+          # asked for.
+          #
+          # Returns **the market**, in the shape `GET /v3/channels/sms/US/TEN_DLC` returns,
+          # with `202`.
+          #
+          # @overload add_numbers(campaign_id:, numbers:, idempotency_key:, sandbox: nil, x_profile_id: nil, request_options: {})
+          #
+          # @param campaign_id [String] Body param: The campaign to add the numbers to, as compliance.campaigns[].id rep
+          #
+          # @param numbers [Array<Sentdm::Models::Channels::SMSNumberRequest, nil>] Body param: The numbers to add, one entry per area code, e.g. [{"area_code": "41
+          #
+          # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+          #
+          # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+          #
+          # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+          #
+          # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Sentdm::Models::Channels::APIResponseOfSMSMarket]
+          #
+          # @see Sentdm::Models::Channels::SMS::TenDlcAddNumbersParams
+          def add_numbers(params)
+            parsed, options = Sentdm::Channels::SMS::TenDlcAddNumbersParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+            @client.request(
+              method: :post,
+              path: "v3/channels/sms/numbers/US/TEN_DLC",
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
+              model: Sentdm::Channels::APIResponseOfSMSMarket,
+              options: options
+            )
+          end
+
+          # Some parameter documentations has been truncated, see
+          # {Sentdm::Models::Channels::SMS::TenDlcRetrieveComplianceParams} for more
+          # details.
+          #
+          # Reads what the US `TEN_DLC` market you hold has registered: the `brand` it files
+          # under, **every campaign** under `campaigns` (each with its `id` and `inherit`),
+          # and its `documents`. It is the `compliance` object
+          # `GET /v3/channels/sms/US/TEN_DLC` returns, without the sender and numbers.
+          #
+          # Use a campaign's `id` to change it with
+          # `PATCH /v3/channels/sms/compliances/US/TEN_DLC/campaigns/{campaignId}`, or to
+          # add numbers to it with `POST /v3/channels/sms/numbers/US/TEN_DLC`.
+          #
+          # Send `x-profile-id` with an organization key to read one of your profiles'
+          # markets.
+          #
+          # @overload retrieve_compliance(x_profile_id: nil, request_options: {})
+          #
+          # @param x_profile_id [String] Profile UUID to scope the request to a child profile. Only organization API keys
+          #
+          # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Sentdm::Models::Channels::SMS::APIResponseOfSuppliedCompliance]
+          #
+          # @see Sentdm::Models::Channels::SMS::TenDlcRetrieveComplianceParams
+          def retrieve_compliance(params = {})
+            parsed, options = Sentdm::Channels::SMS::TenDlcRetrieveComplianceParams.dump_request(params)
+            @client.request(
+              method: :get,
+              path: "v3/channels/sms/compliances/US/TEN_DLC",
+              headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+              model: Sentdm::Channels::SMS::APIResponseOfSuppliedCompliance,
+              options: options
+            )
+          end
+
+          # Some parameter documentations has been truncated, see
+          # {Sentdm::Models::Channels::SMS::TenDlcUpdateCampaignParams} for more details.
+          #
+          # Changes **one campaign of your own** on the US `TEN_DLC` market, named by its
+          # `id` in the market's `compliance.campaigns`.
+          #
+          # ## What to send
+          #
+          # The fields to change, at the top level of the body, under the
+          # `compliance.campaign.*` keys
+          # `GET /v3/compliance/requirements?country=US&type=TEN_DLC` lists, without that
+          # prefix. A field you leave out keeps its value, and a rejected one is keyed by
+          # its name. `id` and `"inherit": false` are ignored, so an entry of
+          # `compliance.campaigns` can be sent as read; `"inherit": true` is `400`, because
+          # this call changes a campaign's fields, not whose campaign you run on. The
+          # campaign only: add numbers with `POST /v3/channels/sms/numbers/US/TEN_DLC`, and
+          # change the brand or documents with `PATCH /v3/channels/sms/US/TEN_DLC`.
+          #
+          # ## When it can be changed
+          #
+          # Until it is filed with The Campaign Registry, and again when we ask you to
+          # correct it. That correction sends it back for review. A filed campaign is
+          # otherwise `409`, and so is a change between low and high volume once it is
+          # registered. A campaign you run on from your organization is `409` too: it is the
+          # organization's to change. So is one out of service: expired, deactivated or
+          # released.
+          #
+          # Returns **the market**, in the shape `GET /v3/channels/sms/US/TEN_DLC` returns.
+          #
+          # @overload update_campaign(campaign_id, description: nil, help_keywords: nil, help_message: nil, message_flow: nil, opt_in_keywords: nil, opt_in_message: nil, opt_out_keywords: nil, opt_out_message: nil, privacy_policy_link: nil, sandbox: nil, terms_and_conditions_link: nil, use_cases: nil, volume: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+          #
+          # @param campaign_id [String] Path param: The campaign: its id in the market's compliance.campaigns.
+          #
+          # @param description [String] Body param: What this programme sends. TCR description: what recipients will get
+          #
+          # @param help_keywords [String] Body param: Help keywords. TCR helpKeywords, comma separated, e.g. HELP,INFO. Re
+          #
+          # @param help_message [String] Body param: Help reply. TCR helpMessage. Its presence is what sets subscriberHel
+          #
+          # @param message_flow [String] Body param: Consent narrative. TCR messageFlow: how recipients opt in, in prose.
+          #
+          # @param opt_in_keywords [String] Body param: Opt-in keywords. TCR optinKeywords, comma separated, e.g. START,YES.
+          #
+          # @param opt_in_message [String] Body param: Opt-in confirmation. TCR optinMessage. Should state message frequenc
+          #
+          # @param opt_out_keywords [String] Body param: Opt-out keywords. TCR optoutKeywords, comma separated. STOP, END, CA
+          #
+          # @param opt_out_message [String] Body param: Opt-out confirmation. TCR optoutMessage. Its presence is what sets s
+          #
+          # @param privacy_policy_link [String] Body param: Privacy policy URL. TCR privacyPolicyLink. Required when `compliance
+          #
+          # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+          #
+          # @param terms_and_conditions_link [String] Body param: Terms and conditions URL. TCR termsAndConditionsLink. Required when
+          #
+          # @param use_cases [Array<Sentdm::Models::Channels::SMS::TenDlcCampaignUseCase>] Body param: Use cases. What the campaign sends, and an example of each. One to f
+          #
+          # @param volume [String] Body param: Expected monthly volume. Decides how the campaign registers and whic
+          #
+          # @param idempotency_key [String] Header param: Unique key to ensure idempotent request processing. Must be 1-255
+          #
+          # @param x_profile_id [String] Header param: Profile UUID to scope the request to a child profile. Only organiz
+          #
+          # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
+          #
+          # @return [Sentdm::Models::Channels::APIResponseOfSMSMarket]
+          #
+          # @see Sentdm::Models::Channels::SMS::TenDlcUpdateCampaignParams
+          def update_campaign(campaign_id, params = {})
+            parsed, options = Sentdm::Channels::SMS::TenDlcUpdateCampaignParams.dump_request(params)
+            header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+            @client.request(
+              method: :patch,
+              path: ["v3/channels/sms/compliances/US/TEN_DLC/campaigns/%1$s", campaign_id],
+              headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+              body: parsed.except(*header_params.keys),
+              model: Sentdm::Channels::APIResponseOfSMSMarket,
+              options: options
+            )
+          end
+
+          # @api private
+          #
+          # @param client [Sentdm::Client]
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sentdm/resources/channels/sms.rb

@@ -31,6 +31,36 @@ module Sentdm
       # 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 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.
+        # @return [Sentdm::Resources::Channels::SMS::TenDlc]
+        attr_reader :ten_dlc
+
         # Some parameter documentations has been truncated, see
         # {Sentdm::Models::Channels::SMSCreateParams} for more details.
         #
@@ -413,6 +443,7 @@ module Sentdm
         # @param client [Sentdm::Client]
         def initialize(client:)
           @client = client
+          @ten_dlc = Sentdm::Resources::Channels::SMS::TenDlc.new(client: client)
         end
       end
     end

data/lib/sentdm/version.rb

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

data/lib/sentdm.rb

@@ -128,6 +128,12 @@ require_relative "sentdm/models/channels/market_compliance"
 require_relative "sentdm/models/channels/rc_create_params"
 require_relative "sentdm/models/channels/rcs_address"
 require_relative "sentdm/models/channels/rcs_agent"
+require_relative "sentdm/models/channels/sms/api_response_of_supplied_compliance"
+require_relative "sentdm/models/channels/sms/ten_dlc_add_campaign_params"
+require_relative "sentdm/models/channels/sms/ten_dlc_add_numbers_params"
+require_relative "sentdm/models/channels/sms/ten_dlc_campaign_use_case"
+require_relative "sentdm/models/channels/sms/ten_dlc_retrieve_compliance_params"
+require_relative "sentdm/models/channels/sms/ten_dlc_update_campaign_params"
 require_relative "sentdm/models/channels/sms_create_params"
 require_relative "sentdm/models/channels/sms_list_params"
 require_relative "sentdm/models/channels/sms_market"
@@ -350,6 +356,7 @@ require_relative "sentdm/models"
 require_relative "sentdm/resources/channels"
 require_relative "sentdm/resources/channels/rcs"
 require_relative "sentdm/resources/channels/sms"
+require_relative "sentdm/resources/channels/sms/ten_dlc"
 require_relative "sentdm/resources/channels/voice"
 require_relative "sentdm/resources/channels/whatsapp"
 require_relative "sentdm/resources/compliance"

data/rbi/sentdm/models/channels/sms/api_response_of_supplied_compliance.rbi

@@ -0,0 +1,117 @@
+# typed: strong
+
+module Sentdm
+  module Models
+    module Channels
+      module SMS
+        class APIResponseOfSuppliedCompliance < Sentdm::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Sentdm::Channels::SMS::APIResponseOfSuppliedCompliance,
+                Sentdm::Internal::AnyHash
+              )
+            end
+
+          # 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::Channels::SuppliedCompliance)) }
+          attr_reader :data
+
+          sig do
+            params(
+              data: T.nilable(Sentdm::Channels::SuppliedCompliance::OrHash)
+            ).void
+          end
+          attr_writer :data
+
+          # Error information
+          sig { returns(T.nilable(Sentdm::ErrorDetail)) }
+          attr_reader :error
+
+          sig { params(error: T.nilable(Sentdm::ErrorDetail::OrHash)).void }
+          attr_writer :error
+
+          # Request and response metadata
+          sig { returns(T.nilable(Sentdm::APIMeta)) }
+          attr_reader :meta
+
+          sig { params(meta: Sentdm::APIMeta::OrHash).void }
+          attr_writer :meta
+
+          # Indicates whether the request was successful
+          sig { returns(T.nilable(T::Boolean)) }
+          attr_reader :success
+
+          sig { params(success: T::Boolean).void }
+          attr_writer :success
+
+          # Standard API response envelope for all v3 endpoints
+          sig do
+            params(
+              data: T.nilable(Sentdm::Channels::SuppliedCompliance::OrHash),
+              error: T.nilable(Sentdm::ErrorDetail::OrHash),
+              meta: Sentdm::APIMeta::OrHash,
+              success: T::Boolean
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # 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.
+            data: nil,
+            # Error information
+            error: nil,
+            # Request and response metadata
+            meta: nil,
+            # Indicates whether the request was successful
+            success: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                data: T.nilable(Sentdm::Channels::SuppliedCompliance),
+                error: T.nilable(Sentdm::ErrorDetail),
+                meta: Sentdm::APIMeta,
+                success: T::Boolean
+              }
+            )
+          end
+          def to_hash
+          end
+        end
+      end
+    end
+  end
+end