trycourier 4.21.0 → 4.23.0

data/lib/courier/models/users/topic_preference.rb

@@ -5,27 +5,36 @@ module Courier
     module Users
       class TopicPreference < Courier::Internal::Type::BaseModel
         # @!attribute default_status
+        #   The topic's default status, returned on reads. It applies whenever the user has
+        #   no override of their own (status equals this value).
         #
         #   @return [Symbol, Courier::Models::PreferenceStatus]
         required :default_status, enum: -> { Courier::PreferenceStatus }
 
         # @!attribute status
+        #   The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
+        #   user's own choice; REQUIRED is a topic-level default set in the preferences
+        #   editor, not a user choice.
         #
         #   @return [Symbol, Courier::Models::PreferenceStatus]
         required :status, enum: -> { Courier::PreferenceStatus }
 
         # @!attribute topic_id
+        #   The unique identifier of the subscription topic this preference applies to.
         #
         #   @return [String]
         required :topic_id, String
 
         # @!attribute topic_name
+        #   The display name of the subscription topic, returned on reads.
         #
         #   @return [String]
         required :topic_name, String
 
         # @!attribute custom_routing
-        #   The Channels a user has chosen to receive notifications through for this topic
+        #   The channels the user has chosen to receive this topic on, present only when
+        #   has_custom_routing is true. One or more of: direct_message, email, push, sms,
+        #   webhook, inbox.
         #
         #   @return [Array<Symbol, Courier::Models::ChannelClassification>, nil]
         optional :custom_routing,
@@ -33,22 +42,27 @@ module Courier
                  nil?: true
 
         # @!attribute has_custom_routing
+        #   Whether the user has chosen specific delivery channels for this topic (listed in
+        #   custom_routing) rather than the topic's default routing.
         #
         #   @return [Boolean, nil]
         optional :has_custom_routing, Courier::Internal::Type::Boolean, nil?: true
 
         # @!method initialize(default_status:, status:, topic_id:, topic_name:, custom_routing: nil, has_custom_routing: nil)
-        #   @param default_status [Symbol, Courier::Models::PreferenceStatus]
+        #   Some parameter documentations has been truncated, see
+        #   {Courier::Models::Users::TopicPreference} for more details.
         #
-        #   @param status [Symbol, Courier::Models::PreferenceStatus]
+        #   @param default_status [Symbol, Courier::Models::PreferenceStatus] The topic's default status, returned on reads. It applies whenever the user has
         #
-        #   @param topic_id [String]
+        #   @param status [Symbol, Courier::Models::PreferenceStatus] The user's subscription status for this topic. OPTED_IN or OPTED_OUT reflect the
         #
-        #   @param topic_name [String]
+        #   @param topic_id [String] The unique identifier of the subscription topic this preference applies to.
         #
-        #   @param custom_routing [Array<Symbol, Courier::Models::ChannelClassification>, nil] The Channels a user has chosen to receive notifications through for this topic
+        #   @param topic_name [String] The display name of the subscription topic, returned on reads.
         #
-        #   @param has_custom_routing [Boolean, nil]
+        #   @param custom_routing [Array<Symbol, Courier::Models::ChannelClassification>, nil] The channels the user has chosen to receive this topic on, present only when has
+        #
+        #   @param has_custom_routing [Boolean, nil] Whether the user has chosen specific delivery channels for this topic (listed in
       end
     end
   end

data/lib/courier/models/workspace_preference_create_params.rb

@@ -7,7 +7,19 @@ module Courier
       extend Courier::Internal::Type::RequestParameters::Converter
       include Courier::Internal::Type::RequestParameters
 
-      # @!method initialize(request_options: {})
+      # @!attribute idempotency_key
+      #
+      #   @return [String, nil]
+      optional :idempotency_key, String
+
+      # @!attribute x_idempotency_expiration
+      #
+      #   @return [String, nil]
+      optional :x_idempotency_expiration, String
+
+      # @!method initialize(idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+      #   @param idempotency_key [String]
+      #   @param x_idempotency_expiration [String]
       #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
     end
   end

data/lib/courier/models/workspace_preference_publish_params.rb

@@ -7,7 +7,19 @@ module Courier
       extend Courier::Internal::Type::RequestParameters::Converter
       include Courier::Internal::Type::RequestParameters
 
-      # @!method initialize(request_options: {})
+      # @!attribute idempotency_key
+      #
+      #   @return [String, nil]
+      optional :idempotency_key, String
+
+      # @!attribute x_idempotency_expiration
+      #
+      #   @return [String, nil]
+      optional :x_idempotency_expiration, String
+
+      # @!method initialize(idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+      #   @param idempotency_key [String]
+      #   @param x_idempotency_expiration [String]
       #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
     end
   end

data/lib/courier/models/workspace_preferences/topic_create_params.rb

@@ -13,8 +13,20 @@ module Courier
         #   @return [String]
         required :section_id, String
 
-        # @!method initialize(section_id:, request_options: {})
+        # @!attribute idempotency_key
+        #
+        #   @return [String, nil]
+        optional :idempotency_key, String
+
+        # @!attribute x_idempotency_expiration
+        #
+        #   @return [String, nil]
+        optional :x_idempotency_expiration, String
+
+        # @!method initialize(section_id:, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
         #   @param section_id [String]
+        #   @param idempotency_key [String]
+        #   @param x_idempotency_expiration [String]
         #   @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}]
       end
     end

data/lib/courier/models.rb

@@ -113,6 +113,34 @@ module Courier
 
   BrandUpdateParams = Courier::Models::BrandUpdateParams
 
+  Broadcast = Courier::Models::Broadcast
+
+  BroadcastArchiveParams = Courier::Models::BroadcastArchiveParams
+
+  BroadcastCancelParams = Courier::Models::BroadcastCancelParams
+
+  BroadcastCreateParams = Courier::Models::BroadcastCreateParams
+
+  BroadcastDuplicateParams = Courier::Models::BroadcastDuplicateParams
+
+  BroadcastListParams = Courier::Models::BroadcastListParams
+
+  BroadcastListResponse = Courier::Models::BroadcastListResponse
+
+  BroadcastPutContentParams = Courier::Models::BroadcastPutContentParams
+
+  BroadcastRetrieveContentParams = Courier::Models::BroadcastRetrieveContentParams
+
+  BroadcastRetrieveParams = Courier::Models::BroadcastRetrieveParams
+
+  BroadcastSchedule = Courier::Models::BroadcastSchedule
+
+  BroadcastScheduleParams = Courier::Models::BroadcastScheduleParams
+
+  BroadcastSendParams = Courier::Models::BroadcastSendParams
+
+  BroadcastUpdateParams = Courier::Models::BroadcastUpdateParams
+
   CancelJourneyRequest = Courier::Models::CancelJourneyRequest
 
   CancelJourneyResponse = Courier::Models::CancelJourneyResponse
@@ -127,6 +155,8 @@ module Courier
 
   Check = Courier::Models::Check
 
+  CreateBroadcastRequest = Courier::Models::CreateBroadcastRequest
+
   CreateJourneyRequest = Courier::Models::CreateJourneyRequest
 
   DefaultPreferences = Courier::Models::DefaultPreferences
@@ -185,6 +215,8 @@ module Courier
 
   InboundTrackEventParams = Courier::Models::InboundTrackEventParams
 
+  Inbox = Courier::Models::Inbox
+
   Intercom = Courier::Models::Intercom
 
   IntercomRecipient = Courier::Models::IntercomRecipient
@@ -472,6 +504,10 @@ module Courier
 
   Rule = Courier::Models::Rule
 
+  ScheduleBroadcastRequest = Courier::Models::ScheduleBroadcastRequest
+
+  SendBroadcastRequest = Courier::Models::SendBroadcastRequest
+
   SendDirectMessage = Courier::Models::SendDirectMessage
 
   SendMessageParams = Courier::Models::SendMessageParams
@@ -534,6 +570,8 @@ module Courier
 
   TranslationUpdateParams = Courier::Models::TranslationUpdateParams
 
+  UpdateBroadcastRequest = Courier::Models::UpdateBroadcastRequest
+
   UserProfile = Courier::Models::UserProfile
 
   UserProfileFirebaseToken = Courier::Models::UserProfileFirebaseToken

data/lib/courier/resources/audiences.rb

@@ -2,8 +2,11 @@
 
 module Courier
   module Resources
+    # Define filter-based groups whose membership Courier recalculates as user
+    # profiles change.
     class Audiences
-      # Returns the specified audience by id.
+      # Returns one audience with its name, description, and the filter and AND or OR
+      # operator that decide which users belong to it.
       #
       # @overload retrieve(audience_id, request_options: {})
       #
@@ -26,7 +29,8 @@ module Courier
       # Some parameter documentations has been truncated, see
       # {Courier::Models::AudienceUpdateParams} for more details.
       #
-      # Creates or updates audience.
+      # Creates or replaces an audience from a filter and an AND or OR operator.
+      # Membership recalculates automatically as profiles change.
       #
       # @overload update(audience_id, description: nil, filter: nil, name: nil, operator: nil, request_options: {})
       #
@@ -56,7 +60,8 @@ module Courier
         )
       end
 
-      # Get the audiences associated with the authorization token.
+      # Returns the audiences in the workspace with paging. Audiences are filter-based
+      # groups that recalculate as user profiles change.
       #
       # @overload list(cursor: nil, request_options: {})
       #
@@ -79,7 +84,8 @@ module Courier
         )
       end
 
-      # Deletes the specified audience.
+      # Deletes an audience permanently, so update any caller sending to it by audience
+      # id first. Those sends fail once the audience is gone.
       #
       # @overload delete(audience_id, request_options: {})
       #
@@ -99,7 +105,8 @@ module Courier
         )
       end
 
-      # Get list of members of an audience.
+      # Returns the users currently matching an audience filter, with paging. Membership
+      # is recalculated, so results shift as profiles change.
       #
       # @overload list_members(audience_id, cursor: nil, request_options: {})
       #

data/lib/courier/resources/audit_events.rb

@@ -2,8 +2,10 @@
 
 module Courier
   module Resources
+    # Read the audit trail of configuration and access changes in your workspace.
     class AuditEvents
-      # Fetch a specific audit event by ID.
+      # Returns one audit event by id, including the actor who performed it, the target
+      # they changed, the source, the event type, and a timestamp.
       #
       # @overload retrieve(audit_event_id, request_options: {})
       #
@@ -23,7 +25,8 @@ module Courier
         )
       end
 
-      # Fetch the list of audit events
+      # Returns the workspace's audit event log with cursor paging. Each event records
+      # the actor, target, source, type, and timestamp of a change.
       #
       # @overload list(cursor: nil, request_options: {})
       #

data/lib/courier/resources/auth.rb

@@ -2,11 +2,15 @@
 
 module Courier
   module Resources
+    # Issue scoped, short-lived JWTs so client-side SDKs — Inbox, Preferences, and the
+    # embedded designer — can call Courier as a single user. Server-side requests
+    # authenticate with your workspace API key instead.
     class Auth
       # Some parameter documentations has been truncated, see
       # {Courier::Models::AuthIssueTokenParams} for more details.
       #
-      # Returns a new access token.
+      # Returns a JWT for authenticating client-side SDKs such as the Inbox. You supply
+      # the scope and an expires_in duration, both required.
       #
       # @overload issue_token(expires_in:, scope:, request_options: {})
       #

data/lib/courier/resources/automations/invoke.rb

@@ -3,20 +3,33 @@
 module Courier
   module Resources
     class Automations
+      # Invoke a stored automation template or an ad hoc automation defined in the
+      # request.
       class Invoke
-        # Invoke an ad hoc automation run. This endpoint accepts a JSON payload with a
-        # series of automation steps. For information about what steps are available,
-        # checkout the ad hoc automation guide
-        # [here](https://www.courier.com/docs/automations/steps/).
-        #
-        # @overload invoke_ad_hoc(automation:, brand: nil, data: nil, profile: nil, recipient: nil, template: nil, request_options: {})
-        #
-        # @param automation [Courier::Models::Automations::InvokeInvokeAdHocParams::Automation]
-        # @param brand [String, nil]
-        # @param data [Hash{Symbol=>Object}, nil]
-        # @param profile [Hash{Symbol=>Object}, nil]
-        # @param recipient [String, nil]
-        # @param template [String, nil]
+        # Some parameter documentations has been truncated, see
+        # {Courier::Models::Automations::InvokeInvokeAdHocParams} for more details.
+        #
+        # Runs a series of automation steps supplied inline, without a saved template, and
+        # returns a runId.
+        #
+        # @overload invoke_ad_hoc(automation:, brand: nil, data: nil, profile: nil, recipient: nil, template: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+        #
+        # @param automation [Courier::Models::Automations::InvokeInvokeAdHocParams::Automation] Body param
+        #
+        # @param brand [String, nil] Body param
+        #
+        # @param data [Hash{Symbol=>Object}, nil] Body param
+        #
+        # @param profile [Hash{Symbol=>Object}, nil] Body param
+        #
+        # @param recipient [String, nil] Body param
+        #
+        # @param template [String, nil] Body param
+        #
+        # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+        #
+        # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
+        #
         # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
         #
         # @return [Courier::Models::AutomationInvokeResponse]
@@ -24,10 +37,13 @@ module Courier
         # @see Courier::Models::Automations::InvokeInvokeAdHocParams
         def invoke_ad_hoc(params)
           parsed, options = Courier::Automations::InvokeInvokeAdHocParams.dump_request(params)
+          header_params =
+            {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
           @client.request(
             method: :post,
             path: "automations/invoke",
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Courier::AutomationInvokeResponse,
             options: options
           )
@@ -36,21 +52,26 @@ module Courier
         # Some parameter documentations has been truncated, see
         # {Courier::Models::Automations::InvokeInvokeByTemplateParams} for more details.
         #
-        # Invoke an automation run from an automation template.
+        # Starts an automation run from a saved template for one recipient, with optional
+        # data and profile, and returns a runId.
+        #
+        # @overload invoke_by_template(template_id, recipient:, brand: nil, data: nil, profile: nil, template: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+        #
+        # @param template_id [String] Path param: A unique identifier representing the automation template to be invok
         #
-        # @overload invoke_by_template(template_id, recipient:, brand: nil, data: nil, profile: nil, template: nil, request_options: {})
+        # @param recipient [String, nil] Body param
         #
-        # @param template_id [String] A unique identifier representing the automation template to be invoked. This cou
+        # @param brand [String, nil] Body param
         #
-        # @param recipient [String, nil]
+        # @param data [Hash{Symbol=>Object}, nil] Body param
         #
-        # @param brand [String, nil]
+        # @param profile [Hash{Symbol=>Object}, nil] Body param
         #
-        # @param data [Hash{Symbol=>Object}, nil]
+        # @param template [String, nil] Body param
         #
-        # @param profile [Hash{Symbol=>Object}, nil]
+        # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
         #
-        # @param template [String, nil]
+        # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
         #
         # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
         #
@@ -59,10 +80,13 @@ module Courier
         # @see Courier::Models::Automations::InvokeInvokeByTemplateParams
         def invoke_by_template(template_id, params)
           parsed, options = Courier::Automations::InvokeInvokeByTemplateParams.dump_request(params)
+          header_params =
+            {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
           @client.request(
             method: :post,
             path: ["automations/%1$s/invoke", template_id],
-            body: parsed,
+            headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+            body: parsed.except(*header_params.keys),
             model: Courier::AutomationInvokeResponse,
             options: options
           )

data/lib/courier/resources/automations.rb

@@ -2,14 +2,19 @@
 
 module Courier
   module Resources
+    # Invoke a stored automation template or an ad hoc automation defined in the
+    # request.
     class Automations
+      # Invoke a stored automation template or an ad hoc automation defined in the
+      # request.
       # @return [Courier::Resources::Automations::Invoke]
       attr_reader :invoke
 
       # Some parameter documentations has been truncated, see
       # {Courier::Models::AutomationListParams} for more details.
       #
-      # Get the list of automations.
+      # Lists the workspace's saved automation templates, each with its id and a cursor
+      # for paging to the next page of results.
       #
       # @overload list(cursor: nil, version: nil, request_options: {})
       #

data/lib/courier/resources/brands.rb

@@ -2,16 +2,29 @@
 
 module Courier
   module Resources
+    # Manage the logos, colors, and layout that give the templates you send a
+    # consistent look.
     class Brands
-      # Create a new brand. Requires `name` and `settings` (with at least
-      # `colors.primary` and `colors.secondary`).
+      # Some parameter documentations has been truncated, see
+      # {Courier::Models::BrandCreateParams} for more details.
       #
-      # @overload create(name:, settings:, id: nil, snippets: nil, request_options: {})
+      # Creates a brand from a name and settings, including primary and secondary
+      # colors. Brands supply the logo, colors, and styling that templates render with.
+      #
+      # @overload create(name:, settings:, id: nil, snippets: nil, idempotency_key: nil, x_idempotency_expiration: nil, request_options: {})
+      #
+      # @param name [String] Body param
+      #
+      # @param settings [Courier::Models::BrandSettings] Body param
+      #
+      # @param id [String, nil] Body param
+      #
+      # @param snippets [Courier::Models::BrandSnippets, nil] Body param
+      #
+      # @param idempotency_key [String] Header param: A unique key that makes this request idempotent. If Courier receiv
+      #
+      # @param x_idempotency_expiration [String] Header param: How long the idempotency key remains valid, as a Unix epoch timest
       #
-      # @param name [String]
-      # @param settings [Courier::Models::BrandSettings]
-      # @param id [String, nil]
-      # @param snippets [Courier::Models::BrandSnippets, nil]
       # @param request_options [Courier::RequestOptions, Hash{Symbol=>Object}, nil]
       #
       # @return [Courier::Models::Brand]
@@ -19,10 +32,20 @@ module Courier
       # @see Courier::Models::BrandCreateParams
       def create(params)
         parsed, options = Courier::BrandCreateParams.dump_request(params)
-        @client.request(method: :post, path: "brands", body: parsed, model: Courier::Brand, options: options)
+        header_params =
+          {idempotency_key: "idempotency-key", x_idempotency_expiration: "x-idempotency-expiration"}
+        @client.request(
+          method: :post,
+          path: "brands",
+          headers: parsed.slice(*header_params.keys).transform_keys(header_params),
+          body: parsed.except(*header_params.keys),
+          model: Courier::Brand,
+          options: options
+        )
       end
 
-      # Fetch a specific brand by brand ID.
+      # Returns one brand by id, including its colors, logo and styling settings,
+      # Handlebars snippets, and published version.
       #
       # @overload retrieve(brand_id, request_options: {})
       #
@@ -42,7 +65,8 @@ module Courier
         )
       end
 
-      # Replace an existing brand with the supplied values.
+      # Replaces a brand with the values you supply, so send the complete settings and
+      # snippets rather than only the fields you want changed.
       #
       # @overload update(brand_id, name:, settings: nil, snippets: nil, request_options: {})
       #
@@ -70,7 +94,8 @@ module Courier
         )
       end
 
-      # Get the list of brands.
+      # Lists the workspace's brands. Every entry carries its name, styling settings,
+      # snippets, and published version.
       #
       # @overload list(cursor: nil, request_options: {})
       #
@@ -93,7 +118,8 @@ module Courier
         )
       end
 
-      # Delete a brand by brand ID.
+      # Deletes a brand by id. Reassign any template or tenant that references it before
+      # deleting to keep their styling intact.
       #
       # @overload delete(brand_id, request_options: {})
       #