sentdm 0.26.0 → 0.28.0

data/lib/sentdm/resources/profiles.rb

@@ -2,38 +2,50 @@
 
 module Sentdm
   module Resources
-    # 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 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.
       # @return [Sentdm::Resources::Profiles::Campaigns]
       attr_reader :campaigns
 
+      # @deprecated
+      #
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ProfileCreateParams} 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 sender profile within an organization. Profiles represent
       # different brands, departments, or use cases, each with their own messaging
       # configuration and settings. Requires admin role in the organization.
       #
       # ## WhatsApp Business Account
       #
-      # Every profile must be linked to a WhatsApp Business Account. There are two ways
-      # to do this:
-      #
-      # **1. Inherit from organization (default)** — Omit the
-      # `whatsapp_business_account` field. The profile will share the organization's
-      # WhatsApp Business Account, which must have been set up via WhatsApp Embedded
-      # Signup. This is the recommended path for most use cases.
-      #
-      # **2. Direct credentials** — Provide a `whatsapp_business_account` object with
-      # `waba_id`, `phone_number_id`, and `access_token`. Use this when the profile
-      # needs its own independent WhatsApp Business Account. Obtain these from Meta
-      # Business Manager by creating a System User with `whatsapp_business_messaging`
-      # and `whatsapp_business_management` permissions.
+      # Every profile owns its own WhatsApp Business Account — accounts are never shared
+      # between profiles or inherited from the organization. Provide a
+      # `whatsapp_business_account` object with `waba_id`, `phone_number_id`, and
+      # `access_token`. Obtain these from Meta Business Manager by creating a System
+      # User with `whatsapp_business_messaging` and `whatsapp_business_management`
+      # permissions.
       #
-      # If the `whatsapp_business_account` field is omitted and the organization has no
-      # WhatsApp Business Account configured, the request will be rejected with
-      # HTTP 422.
+      # Omit the field and the profile is created without WhatsApp, staying incomplete
+      # until it has an account of its own.
       #
       # ## Brand
       #
@@ -50,31 +62,31 @@ module Sentdm
       #
       # @overload create(allow_contact_sharing: nil, allow_template_sharing: nil, billing_contact: nil, billing_model: nil, brand: nil, description: nil, icon: nil, inherit_contacts: nil, inherit_tcr_brand: nil, inherit_tcr_campaign: nil, inherit_templates: nil, name: nil, payment_details: nil, sandbox: nil, short_name: nil, whatsapp_business_account: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
-      # @param allow_contact_sharing [Boolean] Body param: Whether contacts are shared across profiles (default: false)
+      # @param allow_contact_sharing [Boolean, nil] Body param: Deprecated. Accepted and ignored. Contact and template sharing betwe
       #
-      # @param allow_template_sharing [Boolean] Body param: Whether templates are shared across profiles (default: false)
+      # @param allow_template_sharing [Boolean, nil] Body param
       #
-      # @param billing_contact [Sentdm::Models::BillingContactInfo, nil] Body param: Billing contact information for a profile.
+      # @param billing_contact [Sentdm::Models::ProfileCreateParams::BillingContact, nil] Body param: Billing contact information for a profile.
       #
       # @param billing_model [String, nil] Body param: Billing model: profile, organization, or profile_and_organization (d
       #
-      # @param brand [Sentdm::Models::BrandsBrandData, nil] Body param: Brand and KYC data grouped into contact, business, and compliance se
+      # @param brand [Sentdm::Models::ProfileCreateParams::Brand, nil] Body param: Brand and KYC data grouped into contact, business, and compliance se
       #
       # @param description [String, nil] Body param: Profile description (optional)
       #
       # @param icon [String, nil] Body param: Profile icon URL (optional)
       #
-      # @param inherit_contacts [Boolean, nil] Body param: Whether this profile inherits contacts from organization (default: t
+      # @param inherit_contacts [Boolean, nil] Body param
       #
       # @param inherit_tcr_brand [Boolean, nil] Body param: Whether this profile inherits TCR brand from organization (default:
       #
       # @param inherit_tcr_campaign [Boolean, nil] Body param: Whether this profile inherits TCR campaign from organization (defaul
       #
-      # @param inherit_templates [Boolean, nil] Body param: Whether this profile inherits templates from organization (default:
+      # @param inherit_templates [Boolean, nil] Body param
       #
       # @param name [String] Body param: Profile name (required)
       #
-      # @param payment_details [Sentdm::Models::PaymentDetails, nil] Body param: Payment card details for a profile.
+      # @param payment_details [Sentdm::Models::ProfileCreateParams::PaymentDetails, nil] Body param: Payment card details for this profile (optional).
       #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
@@ -88,7 +100,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfProfileDetail]
+      # @return [Sentdm::Models::ProfileCreateResponse]
       #
       # @see Sentdm::Models::ProfileCreateParams
       def create(params = {})
@@ -99,27 +111,35 @@ module Sentdm
           path: "v3/profiles",
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseOfProfileDetail,
+          model: Sentdm::Models::ProfileCreateResponse,
           options: options
         )
       end
 
+      # @deprecated
+      #
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ProfileRetrieveParams} 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 detailed information about a specific sender profile within an
       # organization, including brand and KYC information if a brand has been
       # configured.
       #
       # @overload retrieve(profile_id, x_profile_id: nil, request_options: {})
       #
-      # @param profile_id [String]
+      # @param profile_id [String] Profile ID from route parameter
       #
       # @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::APIResponseOfProfileDetail]
+      # @return [Sentdm::Models::ProfileRetrieveResponse]
       #
       # @see Sentdm::Models::ProfileRetrieveParams
       def retrieve(profile_id, params = {})
@@ -128,14 +148,22 @@ module Sentdm
           method: :get,
           path: ["v3/profiles/%1$s", profile_id],
           headers: parsed.transform_keys(x_profile_id: "x-profile-id"),
-          model: Sentdm::APIResponseOfProfileDetail,
+          model: Sentdm::Models::ProfileRetrieveResponse,
           options: options
         )
       end
 
+      # @deprecated
+      #
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ProfileUpdateParams} 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 a profile's configuration and settings. Requires admin role in the
       # organization. Only provided fields will be updated (partial update).
       #
@@ -155,45 +183,59 @@ module Sentdm
       # and are forwarded directly to the payment processor. Providing `payment_details`
       # when `billing_model` is `"organization"` is not allowed.
       #
+      # ## Deprecated fields
+      #
+      # `sending_phone_number_profile_id` and `sending_whatsapp_number_profile_id` are
+      # **accepted and ignored**. Sender borrowing is gone: a profile cannot send from
+      # another profile's number, because two profiles behind one sender makes an
+      # inbound reply and a delivery receipt ambiguous about whose they are.
+      #
+      # Sending either **changes nothing and still returns `200`** — they are kept on
+      # the contract so an existing integration keeps working. Reads carry both keys too
+      # and always answer `null`, which is how you can confirm the value did not take.
+      #
+      # Give the profile a sender of its own instead — `POST /v3/channels/sms` or
+      # `POST /v3/channels/whatsapp`, sent with the `x-profile-id` header naming it.
+      #
       # @overload update(profile_id, allow_contact_sharing: nil, allow_number_change_during_onboarding: nil, allow_template_sharing: nil, billing_contact: nil, billing_model: nil, brand: nil, description: nil, icon: nil, inherit_contacts: nil, inherit_tcr_brand: nil, inherit_tcr_campaign: nil, inherit_templates: nil, name: nil, payment_details: nil, sandbox: nil, sending_phone_number: nil, sending_phone_number_profile_id: nil, sending_whatsapp_number_profile_id: nil, short_name: nil, whatsapp_phone_number: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
-      # @param profile_id [String] Path param
+      # @param profile_id [String] Path param: Profile ID from route parameter
       #
-      # @param allow_contact_sharing [Boolean, nil] Body param: Whether contacts are shared across profiles (optional)
+      # @param allow_contact_sharing [Boolean, nil] Body param: Deprecated. Accepted and ignored. Contact and template sharing betwe
       #
       # @param allow_number_change_during_onboarding [Boolean, nil] Body param: Whether number changes are allowed during onboarding (optional)
       #
-      # @param allow_template_sharing [Boolean, nil] Body param: Whether templates are shared across profiles (optional)
+      # @param allow_template_sharing [Boolean, nil] Body param
       #
-      # @param billing_contact [Sentdm::Models::BillingContactInfo, nil] Body param: Billing contact information for a profile.
+      # @param billing_contact [Sentdm::Models::ProfileUpdateParams::BillingContact, nil] Body param: Billing contact information for a profile.
       #
       # @param billing_model [String, nil] Body param: Billing model: profile, organization, or profile_and_organization (o
       #
-      # @param brand [Sentdm::Models::BrandsBrandData, nil] Body param: Brand and KYC data grouped into contact, business, and compliance se
+      # @param brand [Sentdm::Models::ProfileUpdateParams::Brand, nil] Body param: Brand and KYC data grouped into contact, business, and compliance se
       #
       # @param description [String, nil] Body param: Profile description (optional)
       #
       # @param icon [String, nil] Body param: Profile icon URL (optional)
       #
-      # @param inherit_contacts [Boolean, nil] Body param: Whether this profile inherits contacts from organization (optional)
+      # @param inherit_contacts [Boolean, nil] Body param
       #
       # @param inherit_tcr_brand [Boolean, nil] Body param: Whether this profile inherits TCR brand from organization (optional)
       #
       # @param inherit_tcr_campaign [Boolean, nil] Body param: Whether this profile inherits TCR campaign from organization (option
       #
-      # @param inherit_templates [Boolean, nil] Body param: Whether this profile inherits templates from organization (optional)
+      # @param inherit_templates [Boolean, nil] Body param
       #
       # @param name [String, nil] Body param: Profile name (optional)
       #
-      # @param payment_details [Sentdm::Models::PaymentDetails, nil] Body param: Payment card details for a profile.
+      # @param payment_details [Sentdm::Models::ProfileUpdateParams::PaymentDetails, nil] Body param: Payment card details for this profile (optional).
       #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
       # @param sending_phone_number [String, nil] Body param: Direct phone number for SMS sending (optional)
       #
-      # @param sending_phone_number_profile_id [String, nil] Body param: Reference to another profile to use for SMS configuration (optional)
+      # @param sending_phone_number_profile_id [String, nil] Body param: Deprecated. Accepted and ignored. Sender borrowing is gone: a profil
       #
-      # @param sending_whatsapp_number_profile_id [String, nil] Body param: Reference to another profile to use for WhatsApp configuration (opti
+      # @param sending_whatsapp_number_profile_id [String, nil] Body param
       #
       # @param short_name [String, nil] Body param: Profile short name/abbreviation (optional). Must be 3–11 characters,
       #
@@ -205,7 +247,7 @@ module Sentdm
       #
       # @param request_options [Sentdm::RequestOptions, Hash{Symbol=>Object}, nil]
       #
-      # @return [Sentdm::Models::APIResponseOfProfileDetail]
+      # @return [Sentdm::Models::ProfileUpdateResponse]
       #
       # @see Sentdm::Models::ProfileUpdateParams
       def update(profile_id, params = {})
@@ -216,14 +258,22 @@ module Sentdm
           path: ["v3/profiles/%1$s", profile_id],
           headers: parsed.slice(*header_params.keys).transform_keys(header_params),
           body: parsed.except(*header_params.keys),
-          model: Sentdm::APIResponseOfProfileDetail,
+          model: Sentdm::Models::ProfileUpdateResponse,
           options: options
         )
       end
 
+      # @deprecated
+      #
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ProfileListParams} 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 sender profiles within an organization, including brand
       # information for each profile. Profiles represent different brands, departments,
       # or use cases within an organization, each with their own messaging
@@ -249,15 +299,26 @@ module Sentdm
         )
       end
 
+      # @deprecated
+      #
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ProfileDeleteParams} 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.
+      #
       # Soft deletes a sender profile. The profile will be marked as deleted but data is
-      # retained. Requires admin role in the organization.
+      # retained. Anything it still held is released first: phone numbers return to our
+      # inventory and can go to whoever asks next, its own WhatsApp account is
+      # deregistered, and its routing rules stop being used. Requires admin role in the
+      # organization.
       #
       # @overload delete(profile_id, sandbox: nil, x_profile_id: nil, request_options: {})
       #
-      # @param profile_id [String] Path param
+      # @param profile_id [String] Path param: Profile ID from route parameter
       #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
@@ -281,18 +342,32 @@ module Sentdm
         )
       end
 
+      # @deprecated
+      #
       # Some parameter documentations has been truncated, see
       # {Sentdm::Models::ProfileCompleteParams} 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.
+      #
       # Final step in the profile compliance workflow. Validates all prerequisites (KYC,
       # brand, campaigns, required documents), connects the profile to the SMS and
-      # WhatsApp channels, and sets its status based on configuration. Prerequisites are
-      # always validated first: if any fail the call returns 400. If they pass and the
-      # profile is already completed, the call returns 200 and does nothing. Otherwise
-      # it returns 202 and calls the provided webhook URL when background processing
-      # finishes.
+      # WhatsApp channels, and marks it onboarded. Prerequisites are always validated
+      # first: if any fail the call returns 400 naming every unmet one, and nothing is
+      # started. If they pass and the profile is already onboarded, the call returns 200
+      # and does nothing. Otherwise it returns 202 and calls the provided webhook URL
+      # when background processing finishes.
+      #
+      # Callable with the organization's API key or the profile's own key. The key's
+      # user must be an admin or owner of the profile, or of the organization it belongs
+      # to.
       #
-      # Prerequisites:
+      # Prerequisites (all but the last are checked before the already-onboarded
+      # short-circuit, matching the previous contract; the last is checked after it, so
+      # a profile that is already onboarded is never rejected by it):
       #
       # - Profile must have a name, short name, and description (short name max 50
       #   characters, description max 5000)
@@ -303,17 +378,18 @@ module Sentdm
       # - TCR applications must have at least one campaign, own or inherited
       # - Destination countries marked as main must have their required compliance
       #   documents uploaded
-      #
-      # Resulting status:
-      #
-      # - If either the SMS or WhatsApp channel is unconfigured, the profile is
-      #   SUBMITTED
-      # - For a TCR application that inherits both its brand and its campaigns, the
-      #   profile is COMPLETED
-      # - For a TCR application that owns either its brand or its campaigns, the profile
-      #   is COMPLETED once both have been submitted to TCR, and SUBMITTED until then
-      # - For a non-TCR application, the profile is SUBMITTED when a main destination
-      #   country is set, and COMPLETED otherwise
+      # - TCR applications must state whether they inherit the organization's TCR brand
+      #   and campaign
+      #
+      # Outcome:
+      #
+      # - Once the prerequisites pass and background processing succeeds, the profile's
+      #   conversionFlowStatus becomes ONBOARDED and its public status reads `approved`
+      # - A profile with no WhatsApp channel, or one still awaiting TCR registration or
+      #   country documents, is onboarded like any other. Those are answered by the
+      #   brand and campaign records, not by a status on the profile
+      # - If background processing fails, the profile keeps the status it already had
+      #   and the webhook reports the reason
       #
       # @overload complete(profile_id, web_hook_url:, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #

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.
@@ -12,13 +17,13 @@ module Sentdm
       #
       # @overload retrieve(user_id, x_profile_id: nil, request_options: {})
       #
-      # @param user_id [String]
+      # @param user_id [String] User ID from route parameter
       #
       # @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::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
@@ -106,7 +111,7 @@ module Sentdm
       #
       # @overload remove(user_id, sandbox: nil, x_profile_id: nil, request_options: {})
       #
-      # @param user_id [String] Path param
+      # @param user_id [String] Path param: User ID from route parameter
       #
       # @param sandbox [Boolean] Body param: Sandbox flag - when true, the operation is simulated without side ef
       #
@@ -138,7 +143,7 @@ module Sentdm
       #
       # @overload update_role(user_id, role: nil, sandbox: nil, idempotency_key: nil, x_profile_id: nil, request_options: {})
       #
-      # @param user_id [String] Path param
+      # @param user_id [String] Path param: User ID from route parameter
       #
       # @param role [String] Body param: User role: admin, billing, or developer (required)
       #
@@ -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.26.0"
+  VERSION = "0.28.0"
 end