sentdm 0.27.0 → 0.28.0

data/lib/sentdm/resources/templates.rb

@@ -2,7 +2,13 @@
 
 module Sentdm
   module Resources
-    # Manage message templates with variable substitution
+    # Reusable message bodies with named variables.
+    #
+    # A template is substituted at send time from the values you pass, so the copy
+    # lives here rather than in your application. WhatsApp templates additionally need
+    # Meta's approval before they can be sent, and a template's channel status reports
+    # where that stands — an approved SMS template and an unapproved WhatsApp one are
+    # the same template in two states.
     class Templates
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::TemplateCreateParams} for more details.
@@ -31,7 +37,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseTemplate]
+      # @return [Sentdm::Models::TemplateCreateResponse]
       #
       # @see Sentdm::Models::TemplateCreateParams
       def create(params = {})
@@ -42,7 +48,7 @@ module Sentdm
           path: "v3/templates",
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseTemplate,
+          model: Sentdm::Models::TemplateCreateResponse,
           options: options
         )
       end
@@ -61,7 +67,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseTemplate]
+      # @return [Sentdm::Models::TemplateRetrieveResponse]
       #
       # @see Sentdm::Models::TemplateRetrieveParams
       def retrieve(id, params = {})
@@ -70,7 +76,7 @@ module Sentdm
           method: :get,
           path: ["v3/templates/%1$s", id],
           headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseTemplate,
+          model: Sentdm::Models::TemplateRetrieveResponse,
           options: options
         )
       end
@@ -103,7 +109,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseTemplate]
+      # @return [Sentdm::Models::TemplateUpdateResponse]
       #
       # @see Sentdm::Models::TemplateUpdateParams
       def update(id, params = {})
@@ -114,7 +120,7 @@ module Sentdm
           path: ["v3/templates/%1$s", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseTemplate,
+          model: Sentdm::Models::TemplateUpdateResponse,
           options: options
         )
       end
@@ -133,7 +139,7 @@ module Sentdm
       #
       # @param category [String, nil] Query param: Optional category filter: MARKETING, UTILITY, AUTHENTICATION
       #
-      # @param is_welcome_playground [Boolean, nil] Query param: Optional filter by welcome playground flag
+      # @param is_welcome_playground [Boolean, nil] Query param: Accepted and ignored. It used to filter on the welcome-playground m
       #
       # @param search [String, nil] Query param: Optional search term for filtering templates
       #

data/lib/sentdm/resources/users.rb

@@ -2,7 +2,12 @@
 
 module Sentdm
   module Resources
-    # Invite, update, and manage organization users and roles
+    # The people who can sign in to your organization, and what each may do.
+    #
+    # Users are dashboard access and nothing else — they do not send, and removing one
+    # does not affect traffic. An API key is not a user: it belongs to the
+    # organization or to a sender profile, so revoking a person's access leaves your
+    # integration running.
     class Users
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::UserRetrieveParams} for more details.
@@ -18,7 +23,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfUser]
+      # @return [Sentdm::Models::UserRetrieveResponse]
       #
       # @see Sentdm::Models::UserRetrieveParams
       def retrieve(user_id, params = {})
@@ -27,7 +32,7 @@ module Sentdm
           method: :get,
           path: ["v3/users/%1$s", user_id],
           headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseOfUser,
+          model: Sentdm::Models::UserRetrieveResponse,
           options: options
         )
       end
@@ -82,7 +87,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfUser]
+      # @return [Sentdm::Models::UserInviteResponse]
       #
       # @see Sentdm::Models::UserInviteParams
       def invite(params = {})
@@ -93,7 +98,7 @@ module Sentdm
           path: "v3/users",
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseOfUser,
+          model: Sentdm::Models::UserInviteResponse,
           options: options
         )
       end
@@ -150,7 +155,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfUser]
+      # @return [Sentdm::Models::UserUpdateRoleResponse]
       #
       # @see Sentdm::Models::UserUpdateRoleParams
       def update_role(user_id, params = {})
@@ -161,7 +166,7 @@ module Sentdm
           path: ["v3/users/%1$s", user_id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseOfUser,
+          model: Sentdm::Models::UserUpdateRoleResponse,
           options: options
         )
       end

data/lib/sentdm/resources/webhooks.rb

@@ -2,7 +2,17 @@
 
 module Sentdm
   module Resources
-    # Configure webhook endpoints for real-time event delivery
+    # Delivery reports and inbound messages, pushed to you.
+    #
+    # Subscribe an endpoint to the event types you care about —
+    # `GET /v3/webhooks/event-types` lists them — and we POST each one as it happens,
+    # retrying on failure. Polling `GET /v3/messages/{id}` works and does not scale.
+    #
+    # **Verify the signature.** Every delivery is signed with your endpoint's secret;
+    # an unverified endpoint is one anybody can post to. `rotate-secret` replaces it,
+    # `test` sends a specimen event, and `GET /v3/webhooks/{id}/events` shows what we
+    # tried to deliver and what your endpoint answered — which is the first place to
+    # look when something appears to be missing.
     class Webhooks
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::WebhookCreateParams} for more details.
@@ -31,7 +41,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseWebhook]
+      # @return [Sentdm::Models::WebhookCreateResponse]
       #
       # @see Sentdm::Models::WebhookCreateParams
       def create(params = {})
@@ -42,7 +52,7 @@ module Sentdm
           path: "v3/webhooks",
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseWebhook,
+          model: Sentdm::Models::WebhookCreateResponse,
           options: options
         )
       end
@@ -60,7 +70,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseWebhook]
+      # @return [Sentdm::Models::WebhookRetrieveResponse]
       #
       # @see Sentdm::Models::WebhookRetrieveParams
       def retrieve(id, params = {})
@@ -69,7 +79,7 @@ module Sentdm
           method: :get,
           path: ["v3/webhooks/%1$s", id],
           headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseWebhook,
+          model: Sentdm::Models::WebhookRetrieveResponse,
           options: options
         )
       end
@@ -103,7 +113,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseWebhook]
+      # @return [Sentdm::Models::WebhookUpdateResponse]
       #
       # @see Sentdm::Models::WebhookUpdateParams
       def update(id, params = {})
@@ -114,7 +124,7 @@ module Sentdm
           path: ["v3/webhooks/%1$s", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseWebhook,
+          model: Sentdm::Models::WebhookUpdateResponse,
           options: options
         )
       end
@@ -331,7 +341,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseWebhook]
+      # @return [Sentdm::Models::WebhookToggleStatusResponse]
       #
       # @see Sentdm::Models::WebhookToggleStatusParams
       def toggle_status(id, params = {})
@@ -342,7 +352,7 @@ module Sentdm
           path: ["v3/webhooks/%1$s/toggle-status", id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseWebhook,
+          model: Sentdm::Models::WebhookToggleStatusResponse,
           options: options
         )
       end

data/lib/sentdm/version.rb

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

data/lib/sentdm.rb

@@ -52,35 +52,23 @@ require_relative "sentdm/errors"
 require_relative "sentdm/internal/transport/base_client"
 require_relative "sentdm/internal/transport/pooled_net_requester"
 require_relative "sentdm/client"
-require_relative "sentdm/models/mutation_request"
-require_relative "sentdm/models/api_meta"
-require_relative "sentdm/models/api_response_of_contact"
-require_relative "sentdm/models/api_response_of_contact_message_summary"
-require_relative "sentdm/models/api_response_of_conversation_messages_list"
-require_relative "sentdm/models/api_response_of_profile_detail"
-require_relative "sentdm/models/api_response_of_user"
-require_relative "sentdm/models/api_response_template"
-require_relative "sentdm/models/api_response_webhook"
 require_relative "sentdm/models/authentication_config"
-require_relative "sentdm/models/billing_contact_info"
-require_relative "sentdm/models/brand_business_info"
-require_relative "sentdm/models/brand_compliance_info"
-require_relative "sentdm/models/brand_contact_info"
-require_relative "sentdm/models/brands_brand_data"
 require_relative "sentdm/models/contact_create_params"
+require_relative "sentdm/models/contact_create_response"
 require_relative "sentdm/models/contact_delete_params"
 require_relative "sentdm/models/contact_list_params"
 require_relative "sentdm/models/contact_list_response"
-require_relative "sentdm/models/contact_message_summary"
-require_relative "sentdm/models/contact_response"
 require_relative "sentdm/models/contact_retrieve_message_summary_params"
+require_relative "sentdm/models/contact_retrieve_message_summary_response"
 require_relative "sentdm/models/contact_retrieve_params"
+require_relative "sentdm/models/contact_retrieve_response"
 require_relative "sentdm/models/contact_update_params"
+require_relative "sentdm/models/contact_update_response"
 require_relative "sentdm/models/conversation_list_messages_params"
+require_relative "sentdm/models/conversation_list_messages_response"
 require_relative "sentdm/models/conversation_list_params"
-require_relative "sentdm/models/conversation_messages_list"
+require_relative "sentdm/models/conversation_list_response"
 require_relative "sentdm/models/destination_country"
-require_relative "sentdm/models/error_detail"
 require_relative "sentdm/models/inbound_message_event"
 require_relative "sentdm/models/inbound_message_event_payload"
 require_relative "sentdm/models/me_retrieve_params"
@@ -95,37 +83,33 @@ require_relative "sentdm/models/message_send_params"
 require_relative "sentdm/models/message_send_response"
 require_relative "sentdm/models/number_lookup_params"
 require_relative "sentdm/models/number_lookup_response"
-require_relative "sentdm/models/pagination_meta"
-require_relative "sentdm/models/payment_details"
 require_relative "sentdm/models/profile_complete_params"
 require_relative "sentdm/models/profile_complete_response"
 require_relative "sentdm/models/profile_create_params"
+require_relative "sentdm/models/profile_create_response"
 require_relative "sentdm/models/profile_delete_params"
-require_relative "sentdm/models/profile_detail"
 require_relative "sentdm/models/profile_list_params"
 require_relative "sentdm/models/profile_list_response"
 require_relative "sentdm/models/profile_retrieve_params"
-require_relative "sentdm/models/profiles/api_response_of_brand_campaign"
-require_relative "sentdm/models/profiles/api_response_of_list_of_brand_campaign"
-require_relative "sentdm/models/profiles/brand_campaign"
+require_relative "sentdm/models/profile_retrieve_response"
 require_relative "sentdm/models/profiles/campaign_create_params"
-require_relative "sentdm/models/profiles/campaign_data"
+require_relative "sentdm/models/profiles/campaign_create_response"
 require_relative "sentdm/models/profiles/campaign_delete_params"
 require_relative "sentdm/models/profiles/campaign_list_params"
+require_relative "sentdm/models/profiles/campaign_list_response"
 require_relative "sentdm/models/profiles/campaign_update_params"
-require_relative "sentdm/models/profiles/campaign_use_case"
-require_relative "sentdm/models/profiles/campaign_use_case_data"
+require_relative "sentdm/models/profiles/campaign_update_response"
 require_relative "sentdm/models/profiles/messaging_use_case_us"
-require_relative "sentdm/models/profile_settings"
 require_relative "sentdm/models/profile_update_params"
+require_relative "sentdm/models/profile_update_response"
 require_relative "sentdm/models/tcr_brand_relationship"
 require_relative "sentdm/models/tcr_vertical"
-require_relative "sentdm/models/template"
 require_relative "sentdm/models/template_body"
 require_relative "sentdm/models/template_body_content"
 require_relative "sentdm/models/template_button"
 require_relative "sentdm/models/template_button_props"
 require_relative "sentdm/models/template_create_params"
+require_relative "sentdm/models/template_create_response"
 require_relative "sentdm/models/template_definition"
 require_relative "sentdm/models/template_delete_params"
 require_relative "sentdm/models/template_event"
@@ -135,32 +119,38 @@ require_relative "sentdm/models/template_header"
 require_relative "sentdm/models/template_list_params"
 require_relative "sentdm/models/template_list_response"
 require_relative "sentdm/models/template_retrieve_params"
+require_relative "sentdm/models/template_retrieve_response"
 require_relative "sentdm/models/template_update_params"
+require_relative "sentdm/models/template_update_response"
 require_relative "sentdm/models/template_variable"
 require_relative "sentdm/models/user_invite_params"
+require_relative "sentdm/models/user_invite_response"
 require_relative "sentdm/models/user_list_params"
 require_relative "sentdm/models/user_list_response"
 require_relative "sentdm/models/user_remove_params"
-require_relative "sentdm/models/user_response"
 require_relative "sentdm/models/user_retrieve_params"
+require_relative "sentdm/models/user_retrieve_response"
 require_relative "sentdm/models/user_update_role_params"
+require_relative "sentdm/models/user_update_role_response"
 require_relative "sentdm/models/webhook_create_params"
+require_relative "sentdm/models/webhook_create_response"
 require_relative "sentdm/models/webhook_delete_params"
-require_relative "sentdm/models/webhook_event_type"
 require_relative "sentdm/models/webhook_list_events_params"
 require_relative "sentdm/models/webhook_list_events_response"
 require_relative "sentdm/models/webhook_list_event_types_params"
 require_relative "sentdm/models/webhook_list_event_types_response"
 require_relative "sentdm/models/webhook_list_params"
 require_relative "sentdm/models/webhook_list_response"
-require_relative "sentdm/models/webhook_response"
 require_relative "sentdm/models/webhook_retrieve_params"
+require_relative "sentdm/models/webhook_retrieve_response"
 require_relative "sentdm/models/webhook_rotate_secret_params"
 require_relative "sentdm/models/webhook_rotate_secret_response"
 require_relative "sentdm/models/webhook_test_params"
 require_relative "sentdm/models/webhook_test_response"
 require_relative "sentdm/models/webhook_toggle_status_params"
+require_relative "sentdm/models/webhook_toggle_status_response"
 require_relative "sentdm/models/webhook_update_params"
+require_relative "sentdm/models/webhook_update_response"
 require_relative "sentdm/models"
 require_relative "sentdm/resources/contacts"
 require_relative "sentdm/resources/conversations"

data/rbi/sentdm/client.rbi

@@ -15,38 +15,101 @@ module Sentdm
     sig { returns(String) }
     attr_reader :api_key
 
-    # Configure webhook endpoints for real-time event delivery
+    # Delivery reports and inbound messages, pushed to you.
+    #
+    # Subscribe an endpoint to the event types you care about —
+    # `GET /v3/webhooks/event-types` lists them — and we POST each one as it happens,
+    # retrying on failure. Polling `GET /v3/messages/{id}` works and does not scale.
+    #
+    # **Verify the signature.** Every delivery is signed with your endpoint's secret;
+    # an unverified endpoint is one anybody can post to. `rotate-secret` replaces it,
+    # `test` sends a specimen event, and `GET /v3/webhooks/{id}/events` shows what we
+    # tried to deliver and what your endpoint answered — which is the first place to
+    # look when something appears to be missing.
     sig { returns(Sentdm::Resources::Webhooks) }
     attr_reader :webhooks
 
-    # Invite, update, and manage organization users and roles
+    # The people who can sign in to your organization, and what each may do.
+    #
+    # Users are dashboard access and nothing else — they do not send, and removing one
+    # does not affect traffic. An API key is not a user: it belongs to the
+    # organization or to a sender profile, so revoking a person's access leaves your
+    # integration running.
     sig { returns(Sentdm::Resources::Users) }
     attr_reader :users
 
-    # Manage message templates with variable substitution
+    # Reusable message bodies with named variables.
+    #
+    # A template is substituted at send time from the values you pass, so the copy
+    # lives here rather than in your application. WhatsApp templates additionally need
+    # Meta's approval before they can be sent, and a template's channel status reports
+    # where that stands — an approved SMS template and an unapproved WhatsApp one are
+    # the same template in two states.
     sig { returns(Sentdm::Resources::Templates) }
     attr_reader :templates
 
-    # 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.
     sig { returns(Sentdm::Resources::Profiles) }
     attr_reader :profiles
 
-    # 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.
     sig { returns(Sentdm::Resources::Numbers) }
     attr_reader :numbers
 
-    # 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.
     sig { returns(Sentdm::Resources::Messages) }
     attr_reader :messages
 
-    # 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.
     sig { returns(Sentdm::Resources::Contacts) }
     attr_reader :contacts
 
+    # 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.
     sig { returns(Sentdm::Resources::Conversations) }
     attr_reader :conversations
 
-    # 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.
     sig { returns(Sentdm::Resources::Me) }
     attr_reader :me