sentdm 0.45.0 → 0.46.0

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

@@ -0,0 +1,417 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Resources
+    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.
+      class SMS
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Channels::SMSCreateParams} for more details.
+        #
+        # Gives the customer a sender in one country — the first market it sends in, and
+        # the fifth.
+        #
+        # ## What to have in place first
+        #
+        # **Call `GET /v3/compliance/requirements?country=US&type=TEN_DLC` first.** It
+        # returns this request's body ready to fill in, plus the brand and campaign calls
+        # to make before it, in order. You never have to track forty countries' rules
+        # yourself.
+        #
+        # **A market that registers with a compliance regime needs an identity, and this
+        # call takes one.** US `TEN_DLC` registers with The Campaign Registry and files
+        # that registration against a business identity. Send it in `compliance.brand` and
+        # it is recorded here, before the registration that attaches to it — so a customer
+        # with no identity reaches a first 10DLC market in one call.
+        #
+        # `{ "inherit": true }` runs on your organization's instead. A market with neither
+        # — none stored, none sent — is `400`, because accepting it would write a channel
+        # that could never register and leave it provisioning for ever with nothing saying
+        # why.
+        #
+        # **Everything the regime wants arrives in this request's `compliance`**, as two
+        # declared objects: `brand` — the identity the registration is filed against — and
+        # `campaign`, with the use case, the consent narrative, the volume, the sample
+        # messages and the keywords. There is nothing to set up first. Nothing is
+        # submitted here either: the rows are what a submission is later assembled from,
+        # and filing is externally rejectable so it happens on its own path.
+        #
+        # **A half you run yourself has to be complete here.** Whichever of `brand` and
+        # `campaign` is your own rather than your organization's must carry every field
+        # the regime asks of it, counting what you already hold — send the rest in this
+        # request. A missing one is `400` naming each field, rather than a `202` for a
+        # market that could never be filed. A half you inherit is asked for nothing.
+        #
+        # A market that registers with nobody — an alphanumeric sender in most countries —
+        # needs neither, and may need documents instead.
+        #
+        # ## Sending it
+        #
+        # Takes the same fields `channels.sms` takes on `POST /v3/sender-profiles`,
+        # because it is the same work, and both run one provisioning path. `compliance` is
+        # top-level and answers for the market in this request, carrying `brand` and
+        # `campaign` where the market registers.
+        #
+        # **Accepts multipart as well as JSON**, with each file named after the compliance
+        # key it satisfies — a market that pre-registers its sender needs its documents at
+        # the same moment it needs the sender. Every required document must be attached to
+        # this request; a missing or invalid file is rejected before the market is added.
+        #
+        # **`area_codes` puts the sender somewhere specific**, in your order of
+        # preference, for a `LOCAL` sender in any country or a US `TEN_DLC` sender — a
+        # 10DLC number is an ordinary local long code bound to a registered campaign, so
+        # both take the same codes out of the same inventory. It is honoured exactly: you
+        # get a number in one of the codes you named or you get none, never one in a code
+        # you left out.
+        #
+        # ## Several numbers
+        #
+        # **`numbers` lists the numbers you want, one entry per area code**, e.g.
+        # `[{"area_code": "212", "quantity": 2}, {"quantity": 1}]` for two numbers in 212
+        # and one in any area code. `quantity` defaults to 1, and an entry without
+        # `area_code` means any area code. Omit `numbers` for one number. It is for
+        # `LOCAL` and `TEN_DLC` only and cannot be combined with `area_codes`. A market
+        # holds at most 49 numbers, counting the ones it already has.
+        #
+        # **On a `LOCAL` market you already hold, `numbers` adds those numbers to it**
+        # instead of `409`. US `TEN_DLC` numbers belong to the market's campaign and are
+        # assigned when the campaign is approved, not at request time. Until then they
+        # read as `PROVISIONING` in the response's `numbers`, each with the area code it
+        # was asked for. A profile inheriting your organization's campaign cannot request
+        # `numbers` (`400`). `numbers` on a `TEN_DLC` market you already hold is `409`:
+        # its numbers belong to its one campaign and are set when the market is created.
+        #
+        # **A market you already send in is `409`**: adding what is already there is a
+        # mistake worth reporting rather than a silent no-op. A market is a
+        # `(country, sender_type)` pair, so a **second sender type in a country you
+        # already send in is fine** — `US TOLL_FREE` alongside `US TEN_DLC` is the
+        # ordinary case. Two of the same type is not.
+        #
+        # **A market you hold that has no sender yet is not a duplicate**, and re-sending
+        # it re-asks for a sender rather than being refused. That is the way out of an
+        # area-code request nothing could fill: send the call again to name different
+        # codes, or no codes at all to take a number anywhere in the country. It answers
+        # `201` with the sender when the pool has one, otherwise `202` with the codes
+        # recorded — and changes nothing else; compliance on a market you hold is
+        # `PATCH /v3/channels/sms/{country}/{type}`.
+        #
+        # One exception: while a market's sender type is still unassigned, adding any type
+        # to that country is `409` once it has a sender, because the market you have may
+        # be about to become the one you asked for.
+        #
+        # Returns **the market**, in the shape `GET` and `PATCH` on
+        # `/v3/channels/sms/{country}/{type}` use — so what this answers can be read back
+        # and written back without reshaping. Not every channel you have: adding a market
+        # cannot change an RCS agent or a WhatsApp account, and `GET /v3/channels` is the
+        # whole picture. `201` when the market is ready; `202` while a sender or a
+        # registration is still outstanding.
+        #
+        # Send `x-profile-id` with an organization key to add a market to one of your
+        # profiles.
+        #
+        # @overload create(number_type:, area_codes: nil, compliance: nil, country: nil, numbers: nil, sandbox: nil, sender_value: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param number_type [Symbol, Sentdm::Models::Channels::SMSCreateParams::NumberType] Body param: Sender type. Decides the provisioning flow and what compliance is as
+        #
+        # @param area_codes [Array<String>, nil] Body param: The area codes to put this sender in, in your own order of preferenc
+        #
+        # @param compliance [Sentdm::Models::Channels::MarketCompliance] Body param: The compliance values a market registers with. `brand` and `campaign
+        #
+        # @param country [String] Body param: ISO 3166-1 alpha-2 country the sender operates in.
+        #
+        # @param numbers [Array<Sentdm::Models::Channels::SMSNumberRequest>, nil] Body param: The numbers to assign, one entry per area code, e.g.
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param sender_value [String, nil] Body param: The sender's identity where the caller chooses it. Required when num
+        #
+        # @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::SMSCreateParams
+        def create(params)
+          parsed, options = Sentdm::Channels::SMSCreateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: "v3/channels/sms",
+            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::SMSRetrieveParams} for more details.
+        #
+        # Reads one market you send in — its sender, where that sender stands, and
+        # everything its compliance holds.
+        #
+        # ## What `compliance` carries
+        #
+        # A market that registers with a compliance regime reports `brand` — the identity
+        # the registration is filed against — and `campaign`, the programme filed against
+        # it. Each carries `inherit`, saying whether it is yours or your organization's.
+        #
+        # A market that registers with nobody has neither, so **both keys are absent**
+        # rather than null: absent says this market does not ask, where null would say it
+        # asks and you supplied nothing. It reports `documents` instead.
+        #
+        # `GET /v3/compliance/requirements` says what a market demands of any new
+        # customer; this says what you gave it.
+        #
+        # ## Writing it back
+        #
+        # **`PATCH` this same path**, with the `compliance` object from this response:
+        #
+        # ```json
+        # { "compliance": { "brand": { "tax_id": "12-3456789" } } }
+        # ```
+        #
+        # Nothing else to learn — what comes back can be sent back, an omitted key is left
+        # alone. There is no sub-resource for either half: both are singletons of the
+        # market, so both are written here.
+        #
+        # `GET /v3/compliance/requirements` says what a market demands of anybody; this
+        # says what you gave it.
+        #
+        # Send `x-profile-id` with an organization key to read one of your profiles'
+        # markets.
+        #
+        # @overload retrieve(type, country:, x_profile_id: nil, request_options: {})
+        #
+        # @param type [String] Path param: Sender type: local, mobile, 10dlc (or ten_dlc), toll_free, short_cod
+        #
+        # @param country [String] Path param: ISO 3166-1 alpha-2 country code, e.g. us
+        #
+        # @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::SMSRetrieveParams
+        def retrieve(type, params)
+          parsed, options = Sentdm::Channels::SMSRetrieveParams.dump_request(params)
+          country =
+            parsed.delete(:country) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          @client.request(
+            method: :get,
+            path: ["v3/channels/sms/%1$s/%2$s", country, type],
+            headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+            model: Sentdm::Channels::APIResponseOfSMSMarket,
+            options: options
+          )
+        end
+
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Channels::SMSUpdateParams} for more details.
+        #
+        # Supplies whatever this market is waiting on, and answers with the market as
+        # stored — the same shape `GET` on this path returns, so **what comes back can be
+        # sent back**.
+        #
+        # **A market reporting `ACTION_NEEDED` is fixed here**, whatever it is waiting on:
+        #
+        # | Outstanding                                  | Send                                                                                                                                  |
+        # | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+        # | a `brand` or `campaign` value (US `TEN_DLC`) | `compliance`, as below                                                                                                                |
+        # | a document, in any market                    | a multipart file named after the document's key                                                                                       |
+        # | a registration sent back for correction      | `compliance.brand` and/or `compliance.campaign` — the identity is accepted even once filed, and the registration goes back for review |
+        # | different numbers                            | `numbers`, the list the market asks for from now on                                                                                   |
+        #
+        # ## Partial, at every level
+        #
+        # **An omitted key is left alone. An explicit `null` clears it.** Those are
+        # different requests, so `{}` changes nothing and is refused rather than silently
+        # accepted, and correcting one field does not blank the others.
+        #
+        # ```json
+        # { "compliance": { "brand": { "contact_phone": "+12125550123" } } }
+        # ```
+        #
+        # That leaves the campaign untouched, along with every other field of the
+        # identity.
+        #
+        # ## What a US `TEN_DLC` market holds
+        #
+        # Two halves, both singular: `brand`, the identity the registration is filed
+        # against, and `campaign`, the programme filed against it. Each carries `inherit`.
+        #
+        # | Body                              | Effect                                                        |
+        # | --------------------------------- | ------------------------------------------------------------- |
+        # | `"brand": { … }`                  | supplies or corrects the identity, and takes one of your own  |
+        # | `"brand": { "inherit": true }`    | runs on your organization's, giving up your own               |
+        # | `"brand": null`                   | the same thing, said the short way                            |
+        # | `"campaign": { … }`               | supplies or corrects the programme, and takes one of your own |
+        # | `"campaign": { "inherit": true }` | runs on your organization's                                   |
+        # | key omitted                       | left exactly as it is                                         |
+        #
+        # **Nothing here creates a second anything.** One identity and one campaign per
+        # market, so a write is an upsert and a replayed request lands on the row it
+        # already wrote. Sending the campaign twice does not file two registrations.
+        #
+        # ## Every other market
+        #
+        # Markets that register with no regime have neither half, so `compliance` is `400`
+        # there. Their compliance is documents, sent here as multipart.
+        #
+        # ## Documents
+        #
+        # Send `multipart/form-data` with **each file named after the compliance key it
+        # satisfies** — the key the market's `requirements` names. A file that matches no
+        # document the market asks for is `400` naming the keys that would, and a file the
+        # upload rules refuse (empty, too large, an unsupported type) is `422`.
+        # `compliance` and `numbers` may ride in the same form as text parts holding their
+        # JSON.
+        #
+        # ## Numbers
+        #
+        # `numbers` takes the list `POST /v3/channels/sms` takes, for a `LOCAL` or
+        # `TEN_DLC` market, and **replaces** what the market asks for — send the list you
+        # want, not a difference. Numbers already assigned stay; a list that leaves one of
+        # them out is `400`, because nothing here releases a number.
+        #
+        # ```json
+        # { "numbers": [{ "area_code": "415", "quantity": 2 }, { "quantity": 1 }] }
+        # ```
+        #
+        # A `LOCAL` market is claimed from inventory at once, and whatever inventory
+        # cannot cover stays pending. A `TEN_DLC` market's numbers are recorded on its
+        # campaign and assigned once the carriers elect it — on the next acquisition cycle
+        # when it already has been. They need a campaign of the profile's own: one
+        # inherited from the organization is `400`.
+        #
+        # ## What it will refuse
+        #
+        # **A filed identity is `409`.** Once the registration has gone to The Campaign
+        # Registry they hold a copy, and a local change would diverge from it silently.
+        # The campaign is not frozen — omit `brand` and the same body is accepted. The
+        # exception is a registration sent back for correction: the identity is accepted,
+        # and a correction to either half sends the registration back for review. Refiling
+        # it with The Campaign Registry stays with Sent.
+        #
+        # **More than one campaign is `409`.** The schema permits several and an account
+        # built on the admin side may hold them; this surface writes one, and editing
+        # whichever sorted first would leave the others unmentioned and unedited.
+        #
+        # Nothing is submitted to a regime here. These are the rows a submission is later
+        # assembled from, which is what lets them be corrected without waiting on
+        # something externally rejectable.
+        #
+        # Send `x-profile-id` with an organization key to write one of your profiles'
+        # markets.
+        #
+        # @overload update(type, country:, compliance: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param type [String] Path param: Sender type, e.g. 10dlc (or ten_dlc), local or alphanumeric. Only 10
+        #
+        # @param country [String] Path param: ISO 3166-1 alpha-2 country code, e.g. us
+        #
+        # @param compliance [Sentdm::Models::Channels::MarketCompliance] Body param: The compliance values a market registers with. `brand` and `campaign
+        #
+        # @param sandbox [Boolean] Body param
+        #
+        # @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::SMSUpdateParams
+        def update(type, params)
+          parsed, options = Sentdm::Channels::SMSUpdateParams.dump_request(params)
+          country =
+            parsed.delete(:country) do
+              raise ArgumentError.new("missing required path argument #{_1}")
+            end
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :patch,
+            path: ["v3/channels/sms/%1$s/%2$s", country, type],
+            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::SMSListParams} for more details.
+        #
+        # Every market you send SMS in, each with its sender, where that sender stands,
+        # and what its compliance holds.
+        #
+        # The same entries `GET /v3/channels` reports under `sms`, and the same shape
+        # `GET /v3/channels/sms/{country}/{type}` returns for one of them — so a list, a
+        # member read and the all-channels read cannot describe a market differently.
+        #
+        # Send `x-profile-id` with an organization key to list one of your profiles'
+        # markets.
+        #
+        # @overload list(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::APIResponseOfListOfSMSMarket]
+        #
+        # @see Sentdm::Models::Channels::SMSListParams
+        def list(params = {})
+          parsed, options = Sentdm::Channels::SMSListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "v3/channels/sms",
+            headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
+            model: Sentdm::Channels::APIResponseOfListOfSMSMarket,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Sentdm::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Sentdm
+  module Resources
+    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.
+      class Whatsapp
+        # Some parameter documentations has been truncated, see
+        # {Sentdm::Models::Channels::WhatsappCreateParams} for more details.
+        #
+        # Connects a WhatsApp Business Account shared with us through a Multi-Partner
+        # Solution to the calling sender profile. Send `x-profile-id` for the profile the
+        # account belongs to.
+        #
+        # **Two fields, because everything else is derived.** `waba_id` says which of your
+        # organization's shared accounts this is — you hold one per client, and nothing
+        # else can say which. `phone_number_id` names the account's number, which is what
+        # assigns it to the profile as the number it sends from.
+        #
+        # The solution the account arrived through, the client business portfolio that
+        # owns it, the access token and its expiry are all resolved from your
+        # organization. They are not accepted here: the first two are Meta's answer about
+        # provenance, and the token is minted per client business and rotates roughly
+        # every sixty days, so a value you sent would be stale before it was useful.
+        #
+        # `phone_number_id` is optional. Omit it to connect the account now and settle the
+        # number later — the channel reads as `ACTION_NEEDED` with `reason_code`
+        # `CHANNEL_007`, and the profile's WhatsApp messages fail until a number is named.
+        # They do not fall back to your organization's account. Call this endpoint again
+        # with `phone_number_id` to name one.
+        #
+        # The same resolution runs behind `channels.whatsapp` on
+        # `POST /v3/sender-profiles`, so connecting at create and connecting afterwards
+        # fill the same fields.
+        #
+        # Returns **the account**, not every channel you have — adding one cannot change a
+        # market or an RCS agent, and `GET /v3/channels` is the whole picture. Giving an
+        # account up is not self-service: ask support, because deregistering a number
+        # lands in your own Meta business.
+        #
+        # @overload create(phone_number_id: nil, sandbox: nil, waba_id: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
+        #
+        # @param phone_number_id [String, nil] Body param: The Meta phone-number id of the number on WabaId, which assigns it t
+        #
+        # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
+        #
+        # @param waba_id [String] Body param: WhatsApp Business Account id — one of the accounts shared into your
+        #
+        # @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::APIResponseOfWhatsappChannel]
+        #
+        # @see Sentdm::Models::Channels::WhatsappCreateParams
+        def create(params = {})
+          parsed, options = Sentdm::Channels::WhatsappCreateParams.dump_request(params)
+          header_params = {idempotency_key: "idempotency-key", x_profile_id: "x-profile-id"}
+          @client.request(
+            method: :post,
+            path: "v3/channels/whatsapp",
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
+            model: Sentdm::Channels::APIResponseOfWhatsappChannel,
+            options: options
+          )
+        end
+
+        # @api private
+        #
+        # @param client [Sentdm::Client]
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end