sentdm 0.26.0 → 0.28.0

data/lib/sentdm/resources/contacts.rb

@@ -2,7 +2,15 @@
 
 module Sentdm
   module Resources
-    # Create, update, and manage customer contact lists
+    # The people you message, and their channel identities.
+    #
+    # A contact holds one identity per channel — a phone number, a WhatsApp number —
+    # so routing can choose between them for the same person. Opt-out is recorded
+    # against the contact and honoured on every send, whichever channel it came
+    # through.
+    #
+    # `GET /v3/contacts/{id}/message-summary` is the per-contact view of what you have
+    # sent and what happened to it.
     class Contacts
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ContactCreateParams} for more details.
@@ -22,7 +30,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfContact]
+      # @return [Sentdm::Models::ContactCreateResponse]
       #
       # @see Sentdm::Models::ContactCreateParams
       def create(params)
@@ -33,7 +41,7 @@ module Sentdm
           path: "v3/contacts",
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseOfContact,
+          model: Sentdm::Models::ContactCreateResponse,
           options: options
         )
       end
@@ -53,7 +61,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfContact]
+      # @return [Sentdm::Models::ContactRetrieveResponse]
       #
       # @see Sentdm::Models::ContactRetrieveParams
       def retrieve(id, params = {})
@@ -62,7 +70,7 @@ module Sentdm
           method: :get,
           path: ["v3/contacts/%1$s", id],
           headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseOfContact,
+          model: Sentdm::Models::ContactRetrieveResponse,
           options: options
         )
       end
@@ -70,8 +78,7 @@ module Sentdm
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ContactUpdateParams} for more details.
       #
-      # Updates a contact's default channel and/or opt-out status. Inherited contacts
-      # cannot be updated.
+      # Updates a contact's default channel and/or opt-out status.
       #
       # @overload update(id, default_channel: nil, opt_out: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
@@ -89,7 +96,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfContact]
+      # @return [Sentdm::Models::ContactUpdateResponse]
       #
       # @see Sentdm::Models::ContactUpdateParams
       def update(id, params = {})
@@ -100,7 +107,7 @@ module Sentdm
           path: ["v3/contacts/%1$s", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseOfContact,
+          model: Sentdm::Models::ContactUpdateResponse,
           options: options
         )
       end
@@ -144,11 +151,21 @@ module Sentdm
         )
       end
 
+      # @deprecated
+      #
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ContactDeleteParams} for more details.
       #
-      # Dissociates a contact from the authenticated customer. Inherited contacts cannot
-      # be deleted.
+      # **Deprecated.** Use `PATCH /v3/contacts/{id}` with `{"opt_out": true}` instead,
+      # and expect this to be removed in a future release. It still behaves exactly as
+      # before, so nothing needs to change today.
+      #
+      # Opting a contact out stops every send to them, which is what deleting one was
+      # mostly used for — and it keeps the record of who they were and that they asked.
+      # A delete discards the consent history along with the contact, which is the part
+      # you need if anyone ever asks why you stopped, or why you started again.
+      #
+      # Dissociates a contact from the authenticated customer.
       #
       # @overload delete(id, sandbox: nil, x_profile_id: nil, request_options: {})
       #
@@ -192,7 +209,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfContactMessageSummary]
+      # @return [Sentdm::Models::ContactRetrieveMessageSummaryResponse]
       #
       # @see Sentdm::Models::ContactRetrieveMessageSummaryParams
       def retrieve_message_summary(contact_id, params = {})
@@ -201,7 +218,7 @@ module Sentdm
           method: :get,
           path: ["v3/contacts/%1$s/message-summary", contact_id],
           headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseOfContactMessageSummary,
+          model: Sentdm::Models::ContactRetrieveMessageSummaryResponse,
           options: options
         )
       end

data/lib/sentdm/resources/conversations.rb

@@ -2,6 +2,14 @@
 
 module Sentdm
   module Resources
+    # Inbound and outbound messages, grouped by the person they are with.
+    #
+    # A conversation is the thread for one contact across every channel — a reply by
+    # SMS and one by WhatsApp belong to the same conversation, because they are the
+    # same person talking to you.
+    #
+    # Read-only. Sending is **Messages**; a reply arrives here and through your
+    # webhooks.
     class Conversations
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ConversationListParams} for more details.
@@ -19,7 +27,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfConversationMessagesList]
+      # @return [Sentdm::Models::ConversationListResponse]
       #
       # @see Sentdm::Models::ConversationListParams
       def list(params)
@@ -31,7 +39,7 @@ module Sentdm
           path: "v3/conversations",
           query: query,
           headers: parsed.except(*query_params).transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseOfConversationMessagesList,
+          model: Sentdm::Models::ConversationListResponse,
           options: options
         )
       end
@@ -54,7 +62,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfConversationMessagesList]
+      # @return [Sentdm::Models::ConversationListMessagesResponse]
       #
       # @see Sentdm::Models::ConversationListMessagesParams
       def list_messages(id, params)
@@ -66,7 +74,7 @@ module Sentdm
           path: ["v3/conversations/%1$s", id],
           query: query,
           headers: parsed.except(*query_params).transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseOfConversationMessagesList,
+          model: Sentdm::Models::ConversationListMessagesResponse,
           options: options
         )
       end

data/lib/sentdm/resources/me.rb

@@ -2,7 +2,12 @@
 
 module Sentdm
   module Resources
-    # Retrieve account details
+    # Who the current key is.
+    #
+    # `GET /v3/me` answers with the account the key authenticates as, which is the
+    # quickest way to tell a live key from a test one, an organization key from a
+    # sender profile's, and to confirm `x-profile-id` resolved to the profile you
+    # meant.
     class Me
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::MeRetrieveParams} for more details.

data/lib/sentdm/resources/messages.rb

@@ -2,7 +2,17 @@
 
 module Sentdm
   module Resources
-    # Send and track SMS and WhatsApp messages
+    # Send a message and follow what happened to it.
+    #
+    # One endpoint sends on any channel: pass `channel: "sent"` and we pick between
+    # SMS, WhatsApp and RCS per recipient using your routing rules, or name a channel
+    # to pin it. A send is accepted asynchronously — `POST /v3/messages` returns an
+    # id, and delivery is reported through `GET /v3/messages/{id}`, its activities, or
+    # a webhook.
+    #
+    # **A message needs a sender.** What you can send, where, and at what cost is
+    # decided by the markets under **Channels** — so a recipient in a country you hold
+    # no sender for is refused here rather than queued.
     class Messages
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::MessageRetrieveActivitiesParams} for more details.
@@ -67,10 +77,12 @@ module Sentdm
       # multi-channel broadcast — when multiple channels are specified (e.g. ["sms",
       # "whatsapp"]), a separate message is created for each (recipient, channel) pair.
       # Returns immediately with per-recipient message IDs for async tracking via
-      # webhooks or the GET /messages/{id} endpoint. Account-level preconditions such as
-      # insufficient balance do not reject the request: the send is accepted with 202
-      # and the affected messages are reported as BLOCKED on GET /messages/{id} and the
-      # message status webhook.
+      # webhooks or the GET /messages/{id} endpoint. Sends gated before any delivery
+      # attempt do not reject the request — an account-level precondition such as
+      # insufficient balance, a template not approved for sending, or free-form content
+      # with no open conversation with the contact. The send is accepted with 202 and
+      # the affected messages are reported as BLOCKED on GET /messages/{id} and the
+      # message.blocked webhook.
       #
       # @overload send_(channel: nil, sandbox: nil, template: nil, text: nil, to: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #

data/lib/sentdm/resources/numbers.rb

@@ -2,7 +2,12 @@
 
 module Sentdm
   module Resources
-    # Manage and lookup phone numbers
+    # What a phone number actually is, before you send to it.
+    #
+    # A lookup returns the number's country, line type and carrier, which is what
+    # decides whether it is reachable on a channel and what it costs. Worth doing on
+    # import rather than on send: a landline in a contact list is a message that can
+    # never be delivered.
     class Numbers
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::NumberLookupParams} for more details.

data/lib/sentdm/resources/profiles/campaigns.rb

@@ -3,11 +3,25 @@
 module Sentdm
   module Resources
     class Profiles
-      # Manage organization profiles
+      # **Deprecated — use Sender Profiles.**
+      #
+      # The original profile resource, kept because it has live callers. It still works,
+      # and its replacement is `/v3/sender-profiles`, which takes the identity and the
+      # campaign in one call instead of across three.
+      #
+      # New integrations should not start here.
       class Campaigns
+        # @deprecated
+        #
         # Some parameter documentations has been truncated, see
         # {Sentdm::Models::Profiles::CampaignCreateParams} for more details.
         #
+        # **Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be
+        # removed in a future release. It still behaves exactly as before, so nothing
+        # needs to change today — but new integrations should use `/v3/sender-profiles`,
+        # which models a profile's markets, compliance, brand, campaigns and billing
+        # explicitly.
+        #
         # Creates a new campaign scoped under the brand of the specified profile. Each
         # campaign must include at least one use case with sample messages.
         #
@@ -15,7 +29,7 @@ module Sentdm
         #
         # @param profile_id [String] Path param: Profile ID from route
         #
-        # @param campaign [Sentdm::Models::Profiles::CampaignData] Body param: Campaign data for create or update operation
+        # @param campaign [Sentdm::Models::Profiles::CampaignCreateParams::Campaign] Body param: Campaign data for create or update operation
         #
         # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
         #
@@ -25,7 +39,7 @@ module Sentdm
         #
         # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
         #
-        # @return [Sentdm::Models::Profiles::APIResponseOfBrandCampaign]
+        # @return [Sentdm::Models::Profiles::CampaignCreateResponse]
         #
         # @see Sentdm::Models::Profiles::CampaignCreateParams
         def create(profile_id, params)
@@ -36,14 +50,22 @@ module Sentdm
             path: ["v3/profiles/%1$s/campaigns", profile_id],
             headers: parsed.slice(*header_params.keys).transform_keys(header_params),
             body: parsed.except(*header_params.keys),
-            model: Sentdm::Profiles::APIResponseOfBrandCampaign,
+            model: Sentdm::Models::Profiles::CampaignCreateResponse,
             options: options
           )
         end
 
+        # @deprecated
+        #
         # Some parameter documentations has been truncated, see
         # {Sentdm::Models::Profiles::CampaignUpdateParams} for more details.
         #
+        # **Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be
+        # removed in a future release. It still behaves exactly as before, so nothing
+        # needs to change today — but new integrations should use `/v3/sender-profiles`,
+        # which models a profile's markets, compliance, brand, campaigns and billing
+        # explicitly.
+        #
         # Updates an existing campaign under the brand of the specified profile. Cannot
         # update campaigns that have already been submitted to TCR.
         #
@@ -53,7 +75,7 @@ module Sentdm
         #
         # @param profile_id [String] Path param: Profile ID from route
         #
-        # @param campaign [Sentdm::Models::Profiles::CampaignData] Body param: Campaign data for create or update operation
+        # @param campaign [Sentdm::Models::Profiles::CampaignUpdateParams::Campaign] Body param: Campaign data for create or update operation
         #
         # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
         #
@@ -63,7 +85,7 @@ module Sentdm
         #
         # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
         #
-        # @return [Sentdm::Models::Profiles::APIResponseOfBrandCampaign]
+        # @return [Sentdm::Models::Profiles::CampaignUpdateResponse]
         #
         # @see Sentdm::Models::Profiles::CampaignUpdateParams
         def update(campaign_id, params)
@@ -78,14 +100,22 @@ module Sentdm
             path: ["v3/profiles/%1$s/campaigns/%2$s", profile_id, campaign_id],
             headers: parsed.slice(*header_params.keys).transform_keys(header_params),
             body: parsed.except(*header_params.keys),
-            model: Sentdm::Profiles::APIResponseOfBrandCampaign,
+            model: Sentdm::Models::Profiles::CampaignUpdateResponse,
             options: options
           )
         end
 
+        # @deprecated
+        #
         # Some parameter documentations has been truncated, see
         # {Sentdm::Models::Profiles::CampaignListParams} for more details.
         #
+        # **Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be
+        # removed in a future release. It still behaves exactly as before, so nothing
+        # needs to change today — but new integrations should use `/v3/sender-profiles`,
+        # which models a profile's markets, compliance, brand, campaigns and billing
+        # explicitly.
+        #
         # Retrieves all campaigns linked to the profile's brand, including use cases and
         # sample messages. Returns inherited campaigns if inherit_tcr_campaign=true.
         #
@@ -97,7 +127,7 @@ module Sentdm
         #
         # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
         #
-        # @return [Sentdm::Models::Profiles::APIResponseOfListOfBrandCampaign]
+        # @return [Sentdm::Models::Profiles::CampaignListResponse]
         #
         # @see Sentdm::Models::Profiles::CampaignListParams
         def list(profile_id, params = {})
@@ -106,14 +136,22 @@ module Sentdm
             method: :get,
             path: ["v3/profiles/%1$s/campaigns", profile_id],
             headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
-            model: Sentdm::Profiles::APIResponseOfListOfBrandCampaign,
+            model: Sentdm::Models::Profiles::CampaignListResponse,
             options: options
           )
         end
 
+        # @deprecated
+        #
         # Some parameter documentations has been truncated, see
         # {Sentdm::Models::Profiles::CampaignDeleteParams} for more details.
         #
+        # **Deprecated.** This endpoint is replaced by `/v3/sender-profiles` and will be
+        # removed in a future release. It still behaves exactly as before, so nothing
+        # needs to change today — but new integrations should use `/v3/sender-profiles`,
+        # which models a profile's markets, compliance, brand, campaigns and billing
+        # explicitly.
+        #
         # Deletes a campaign by ID from the brand of the specified profile. The profile
         # must belong to the authenticated organization.
         #