sentdm 0.44.0 → 0.46.0

data/rbi/sentdm/resources/channels/sms.rbi

@@ -0,0 +1,437 @@
+# typed: strong
+
+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
+        # 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.
+        sig do
+          params(
+            number_type:
+              Sentdm::Channels::SMSCreateParams::NumberType::OrSymbol,
+            area_codes: T.nilable(T::Array[String]),
+            compliance: Sentdm::Channels::MarketCompliance::OrHash,
+            country: String,
+            numbers:
+              T.nilable(T::Array[Sentdm::Channels::SMSNumberRequest::OrHash]),
+            sandbox: T::Boolean,
+            sender_value: T.nilable(String),
+            idempotency_key: String,
+            x_profile_id: String,
+            request_options: Sentdm::RequestOptions::OrHash
+          ).returns(Sentdm::Channels::APIResponseOfSMSMarket)
+        end
+        def create(
+          # Body param: Sender type. Decides the provisioning flow and what compliance is
+          # asked for.
+          #
+          # [Required] so the published document says so. The validator has always demanded
+          # it, but requiredness reached the schema by matching a rule to a property name —
+          # which works for country, whose wire name is its camel-cased C# name, and
+          # silently does not for number_type. A client generating a request from our
+          # OpenAPI therefore sent what the document called sufficient and was answered 400.
+          number_type:,
+          # Body param: The area codes to put this sender in, in your own order of
+          # preference, e.g. ["415", "628"] for the US or ["20"] for London. Omit it and a
+          # number is claimed anywhere in the country.
+          #
+          # Ordered, and the order is the request. The claim tries each code in turn and
+          # stops at the first that yields a number. Nothing sorts the list and a code
+          # listed twice is refused.
+          #
+          # One to fifty entries, each the area code as digits: 415, with the trunk prefix
+          # as 020, or with the country's dialing prefix as +1415 (all are stored as the
+          # bare code). A dialing prefix from a different country than country is refused.
+          # Each code is checked against the country's numbering plan: it must start real
+          # local or mobile numbers there, so toll-free and premium ranges, service codes
+          # and another country's codes are refused with a reason.
+          #
+          # LOCAL senders in any country, and US TEN_DLC senders. No other sender type has a
+          # geographic area code, and the list is refused with one rather than accepted and
+          # dropped.
+          #
+          # Honoured exactly or not at all. Ask for 415 and you get a 415 number or you get
+          # none, never a neighbouring code you did not name. A miss leaves the market with
+          # no sender yet and the codes recorded on it, so it is filled when stock appears
+          # rather than filled now from somewhere else. Many countries outside North America
+          # require address or business documents before a local number can be bought, which
+          # can delay or prevent the fill.
+          area_codes: nil,
+          # Body param: The compliance values a market registers with. `brand` and
+          # `campaign` apply to US `TEN_DLC`; other markets fill this map with the document
+          # keys their own requirements name.
+          compliance: nil,
+          # Body param: ISO 3166-1 alpha-2 country the sender operates in.
+          country: nil,
+          # Body param: The numbers to assign, one entry per area code, e.g. [{"area_code":
+          # "212", "quantity": 2}, {"area_code": "415"}, {"quantity": 1}]: two numbers in
+          # 212, one in 415 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.
+          #
+          # Only with LOCAL or TEN_DLC, and not together with area_codes. Each area code is
+          # validated against country the same way area_codes is and may appear once, and at
+          # most one entry may leave area_code out. On a LOCAL market you already hold, this
+          # adds the numbers to it. US TEN_DLC numbers are assigned when the campaign is
+          # approved, not at request time. Not available when the profile inherits the
+          # organization's campaign.
+          numbers: nil,
+          # Body param: Sandbox flag - when true, the operation is simulated without side
+          # effects Useful for testing integrations without actual execution
+          sandbox: nil,
+          # Body param: The sender's identity where the caller chooses it. Required when
+          # number_type is ALPHANUMERIC; optional for carrier-assigned types, which are
+          # procured afterwards.
+          sender_value: 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
+
+        # 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.
+        sig do
+          params(
+            type: String,
+            country: String,
+            x_profile_id: String,
+            request_options: Sentdm::RequestOptions::OrHash
+          ).returns(Sentdm::Channels::APIResponseOfSMSMarket)
+        end
+        def retrieve(
+          # Path param: Sender type: local, mobile, 10dlc (or ten_dlc), toll_free,
+          # short_code, alphanumeric. Matched ignoring case.
+          type,
+          # Path param: ISO 3166-1 alpha-2 country code, e.g. us
+          country:,
+          # 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
+
+        # 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.
+        sig do
+          params(
+            type: String,
+            country: String,
+            compliance: Sentdm::Channels::MarketCompliance::OrHash,
+            sandbox: T::Boolean,
+            idempotency_key: String,
+            x_profile_id: String,
+            request_options: Sentdm::RequestOptions::OrHash
+          ).returns(Sentdm::Channels::APIResponseOfSMSMarket)
+        end
+        def update(
+          # Path param: Sender type, e.g. 10dlc (or ten_dlc), local or alphanumeric. Only
+          # 10dlc in us declares compliance values.
+          type,
+          # Path param: ISO 3166-1 alpha-2 country code, e.g. us
+          country:,
+          # Body param: The compliance values a market registers with. `brand` and
+          # `campaign` apply to US `TEN_DLC`; other markets fill this map with the document
+          # keys their own requirements name.
+          compliance: nil,
+          # Body param
+          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
+
+        # 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.
+        sig do
+          params(
+            x_profile_id: String,
+            request_options: Sentdm::RequestOptions::OrHash
+          ).returns(Sentdm::Channels::APIResponseOfListOfSMSMarket)
+        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:)
+        end
+      end
+    end
+  end
+end

data/rbi/sentdm/resources/channels/whatsapp.rbi

@@ -0,0 +1,108 @@
+# typed: strong
+
+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
+        # 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.
+        sig do
+          params(
+            phone_number_id: T.nilable(String),
+            sandbox: T::Boolean,
+            waba_id: String,
+            idempotency_key: String,
+            x_profile_id: String,
+            request_options: Sentdm::RequestOptions::OrHash
+          ).returns(Sentdm::Channels::APIResponseOfWhatsappChannel)
+        end
+        def create(
+          # Body param: The Meta phone-number id of the number on WabaId, which assigns it
+          # to this profile as the number it sends from. It is not checked against the
+          # account here, so name the account's number; it is refused if another profile
+          # already uses it.
+          #
+          # Optional: omit it to connect the account and settle the number later. Nothing
+          # picks one on your behalf.
+          phone_number_id: nil,
+          # Body param: Sandbox flag - when true, the operation is simulated without side
+          # effects Useful for testing integrations without actual execution
+          sandbox: nil,
+          # Body param: WhatsApp Business Account id — one of the accounts shared into your
+          # organization. Required: the organization holds one per client, and nothing but
+          # the caller says which is meant here.
+          waba_id: 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
+
+        # @api private
+        sig { params(client: Sentdm::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end