trycourier 4.21.0 → 4.23.0

data/rbi/courier/models/users/preference_update_or_create_topic_params.rbi

@@ -81,10 +81,14 @@ module Courier
               )
             end
 
+          # The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
+          # default, not a user choice; the API rejects opting a user out of a REQUIRED
+          # topic.
           sig { returns(Courier::PreferenceStatus::OrSymbol) }
           attr_accessor :status
 
-          # The Channels a user has chosen to receive notifications through for this topic
+          # The channels to deliver this topic on when has_custom_routing is true. One or
+          # more of: direct_message, email, push, sms, webhook, inbox.
           sig do
             returns(
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol])
@@ -92,6 +96,8 @@ module Courier
           end
           attr_accessor :custom_routing
 
+          # Set to true to route this topic to the channels in custom_routing instead of the
+          # topic's default routing.
           sig { returns(T.nilable(T::Boolean)) }
           attr_accessor :has_custom_routing
 
@@ -104,9 +110,15 @@ module Courier
             ).returns(T.attached_class)
           end
           def self.new(
+            # The subscription status to set: OPTED_IN or OPTED_OUT. REQUIRED is a topic-level
+            # default, not a user choice; the API rejects opting a user out of a REQUIRED
+            # topic.
             status:,
-            # The Channels a user has chosen to receive notifications through for this topic
+            # The channels to deliver this topic on when has_custom_routing is true. One or
+            # more of: direct_message, email, push, sms, webhook, inbox.
             custom_routing: nil,
+            # Set to true to route this topic to the channels in custom_routing instead of the
+            # topic's default routing.
             has_custom_routing: nil
           )
           end

data/rbi/courier/models/users/topic_preference.rbi

@@ -9,19 +9,28 @@ module Courier
             T.any(Courier::Users::TopicPreference, Courier::Internal::AnyHash)
           end
 
+        # The topic's default status, returned on reads. It applies whenever the user has
+        # no override of their own (status equals this value).
         sig { returns(Courier::PreferenceStatus::TaggedSymbol) }
         attr_accessor :default_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.
         sig { returns(Courier::PreferenceStatus::TaggedSymbol) }
         attr_accessor :status
 
+        # The unique identifier of the subscription topic this preference applies to.
         sig { returns(String) }
         attr_accessor :topic_id
 
+        # The display name of the subscription topic, returned on reads.
         sig { returns(String) }
         attr_accessor :topic_name
 
-        # 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.
         sig do
           returns(
             T.nilable(T::Array[Courier::ChannelClassification::TaggedSymbol])
@@ -29,6 +38,8 @@ module Courier
         end
         attr_accessor :custom_routing
 
+        # Whether the user has chosen specific delivery channels for this topic (listed in
+        # custom_routing) rather than the topic's default routing.
         sig { returns(T.nilable(T::Boolean)) }
         attr_accessor :has_custom_routing
 
@@ -44,12 +55,23 @@ module Courier
           ).returns(T.attached_class)
         end
         def self.new(
+          # The topic's default status, returned on reads. It applies whenever the user has
+          # no override of their own (status equals this value).
           default_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.
           status:,
+          # The unique identifier of the subscription topic this preference applies to.
           topic_id:,
+          # The display name of the subscription topic, returned on reads.
           topic_name:,
-          # 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.
           custom_routing: nil,
+          # Whether the user has chosen specific delivery channels for this topic (listed in
+          # custom_routing) rather than the topic's default routing.
           has_custom_routing: nil
         )
         end

data/rbi/courier/models/workspace_preference_create_params.rbi

@@ -14,15 +14,41 @@ module Courier
           )
         end
 
+      sig { returns(T.nilable(String)) }
+      attr_reader :idempotency_key
+
+      sig { params(idempotency_key: String).void }
+      attr_writer :idempotency_key
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :x_idempotency_expiration
+
+      sig { params(x_idempotency_expiration: String).void }
+      attr_writer :x_idempotency_expiration
+
       sig do
-        params(request_options: Courier::RequestOptions::OrHash).returns(
-          T.attached_class
-        )
+        params(
+          idempotency_key: String,
+          x_idempotency_expiration: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(T.attached_class)
       end
-      def self.new(request_options: {})
+      def self.new(
+        idempotency_key: nil,
+        x_idempotency_expiration: nil,
+        request_options: {}
+      )
       end
 
-      sig { override.returns({ request_options: Courier::RequestOptions }) }
+      sig do
+        override.returns(
+          {
+            idempotency_key: String,
+            x_idempotency_expiration: String,
+            request_options: Courier::RequestOptions
+          }
+        )
+      end
       def to_hash
       end
     end

data/rbi/courier/models/workspace_preference_publish_params.rbi

@@ -14,15 +14,41 @@ module Courier
           )
         end
 
+      sig { returns(T.nilable(String)) }
+      attr_reader :idempotency_key
+
+      sig { params(idempotency_key: String).void }
+      attr_writer :idempotency_key
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :x_idempotency_expiration
+
+      sig { params(x_idempotency_expiration: String).void }
+      attr_writer :x_idempotency_expiration
+
       sig do
-        params(request_options: Courier::RequestOptions::OrHash).returns(
-          T.attached_class
-        )
+        params(
+          idempotency_key: String,
+          x_idempotency_expiration: String,
+          request_options: Courier::RequestOptions::OrHash
+        ).returns(T.attached_class)
       end
-      def self.new(request_options: {})
+      def self.new(
+        idempotency_key: nil,
+        x_idempotency_expiration: nil,
+        request_options: {}
+      )
       end
 
-      sig { override.returns({ request_options: Courier::RequestOptions }) }
+      sig do
+        override.returns(
+          {
+            idempotency_key: String,
+            x_idempotency_expiration: String,
+            request_options: Courier::RequestOptions
+          }
+        )
+      end
       def to_hash
       end
     end

data/rbi/courier/models/workspace_preferences/topic_create_params.rbi

@@ -18,18 +18,42 @@ module Courier
         sig { returns(String) }
         attr_accessor :section_id
 
+        sig { returns(T.nilable(String)) }
+        attr_reader :idempotency_key
+
+        sig { params(idempotency_key: String).void }
+        attr_writer :idempotency_key
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :x_idempotency_expiration
+
+        sig { params(x_idempotency_expiration: String).void }
+        attr_writer :x_idempotency_expiration
+
         sig do
           params(
             section_id: String,
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(T.attached_class)
         end
-        def self.new(section_id:, request_options: {})
+        def self.new(
+          section_id:,
+          idempotency_key: nil,
+          x_idempotency_expiration: nil,
+          request_options: {}
+        )
         end
 
         sig do
           override.returns(
-            { section_id: String, request_options: Courier::RequestOptions }
+            {
+              section_id: String,
+              idempotency_key: String,
+              x_idempotency_expiration: String,
+              request_options: Courier::RequestOptions
+            }
           )
         end
         def to_hash

data/rbi/courier/models.rbi

@@ -77,6 +77,35 @@ 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
@@ -91,6 +120,8 @@ module Courier
 
   Check = Courier::Models::Check
 
+  CreateBroadcastRequest = Courier::Models::CreateBroadcastRequest
+
   CreateJourneyRequest = Courier::Models::CreateJourneyRequest
 
   DefaultPreferences = Courier::Models::DefaultPreferences
@@ -149,6 +180,8 @@ module Courier
 
   InboundTrackEventParams = Courier::Models::InboundTrackEventParams
 
+  Inbox = Courier::Models::Inbox
+
   Intercom = Courier::Models::Intercom
 
   IntercomRecipient = Courier::Models::IntercomRecipient
@@ -450,6 +483,10 @@ module Courier
 
   Rule = Courier::Models::Rule
 
+  ScheduleBroadcastRequest = Courier::Models::ScheduleBroadcastRequest
+
+  SendBroadcastRequest = Courier::Models::SendBroadcastRequest
+
   SendDirectMessage = Courier::Models::SendDirectMessage
 
   SendMessageParams = Courier::Models::SendMessageParams
@@ -512,6 +549,8 @@ module Courier
 
   TranslationUpdateParams = Courier::Models::TranslationUpdateParams
 
+  UpdateBroadcastRequest = Courier::Models::UpdateBroadcastRequest
+
   UserProfile = Courier::Models::UserProfile
 
   UserProfileFirebaseToken = Courier::Models::UserProfileFirebaseToken

data/rbi/courier/resources/audiences.rbi

@@ -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.
       sig do
         params(
           audience_id: String,
@@ -17,7 +20,8 @@ module Courier
       )
       end
 
-      # Creates or updates audience.
+      # Creates or replaces an audience from a filter and an AND or OR operator.
+      # Membership recalculates automatically as profiles change.
       sig do
         params(
           audience_id: String,
@@ -46,7 +50,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.
       sig do
         params(
           cursor: T.nilable(String),
@@ -60,7 +65,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.
       sig do
         params(
           audience_id: String,
@@ -74,7 +80,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.
       sig do
         params(
           audience_id: String,

data/rbi/courier/resources/audit_events.rbi

@@ -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.
       sig do
         params(
           audit_event_id: String,
@@ -17,7 +19,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.
       sig do
         params(
           cursor: T.nilable(String),

data/rbi/courier/resources/auth.rbi

@@ -2,8 +2,12 @@
 
 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
-      # 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.
       sig do
         params(
           expires_in: String,

data/rbi/courier/resources/automations/invoke.rbi

@@ -3,11 +3,11 @@
 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/).
+        # Runs a series of automation steps supplied inline, without a saved template, and
+        # returns a runId.
         sig do
           params(
             automation:
@@ -17,21 +17,42 @@ module Courier
             profile: T.nilable(T::Hash[Symbol, T.anything]),
             recipient: T.nilable(String),
             template: T.nilable(String),
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::AutomationInvokeResponse)
         end
         def invoke_ad_hoc(
+          # Body param
           automation:,
+          # Body param
           brand: nil,
+          # Body param
           data: nil,
+          # Body param
           profile: nil,
+          # Body param
           recipient: nil,
+          # Body param
           template: nil,
+          # Header param: A unique key that makes this request idempotent. If Courier
+          # receives another request with the same `Idempotency-Key`, it returns the stored
+          # response from the first request without performing the operation again
+          # (including the original status code and any error). Use it to safely retry
+          # `POST` requests after network failures without risking duplicate sends. The key
+          # is scoped to this endpoint.
+          idempotency_key: nil,
+          # Header param: How long the idempotency key remains valid, as a Unix epoch
+          # timestamp in seconds or an ISO 8601 date string. Only applies when
+          # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+          # maximum is 1 year.
+          x_idempotency_expiration: nil,
           request_options: {}
         )
         end
 
-        # 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.
         sig do
           params(
             template_id: String,
@@ -40,18 +61,38 @@ module Courier
             data: T.nilable(T::Hash[Symbol, T.anything]),
             profile: T.nilable(T::Hash[Symbol, T.anything]),
             template: T.nilable(String),
+            idempotency_key: String,
+            x_idempotency_expiration: String,
             request_options: Courier::RequestOptions::OrHash
           ).returns(Courier::AutomationInvokeResponse)
         end
         def invoke_by_template(
-          # A unique identifier representing the automation template to be invoked. This
-          # could be the Automation Template ID or the Automation Template Alias.
+          # Path param: A unique identifier representing the automation template to be
+          # invoked. This could be the Automation Template ID or the Automation Template
+          # Alias.
           template_id,
+          # Body param
           recipient:,
+          # Body param
           brand: nil,
+          # Body param
           data: nil,
+          # Body param
           profile: nil,
+          # Body param
           template: nil,
+          # Header param: A unique key that makes this request idempotent. If Courier
+          # receives another request with the same `Idempotency-Key`, it returns the stored
+          # response from the first request without performing the operation again
+          # (including the original status code and any error). Use it to safely retry
+          # `POST` requests after network failures without risking duplicate sends. The key
+          # is scoped to this endpoint.
+          idempotency_key: nil,
+          # Header param: How long the idempotency key remains valid, as a Unix epoch
+          # timestamp in seconds or an ISO 8601 date string. Only applies when
+          # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+          # maximum is 1 year.
+          x_idempotency_expiration: nil,
           request_options: {}
         )
         end

data/rbi/courier/resources/automations.rbi

@@ -2,11 +2,16 @@
 
 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.
       sig { returns(Courier::Resources::Automations::Invoke) }
       attr_reader :invoke
 
-      # 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.
       sig do
         params(
           cursor: String,

data/rbi/courier/resources/brands.rbi

@@ -2,22 +2,49 @@
 
 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`).
+      # Creates a brand from a name and settings, including primary and secondary
+      # colors. Brands supply the logo, colors, and styling that templates render with.
       sig do
         params(
           name: String,
           settings: Courier::BrandSettings::OrHash,
           id: T.nilable(String),
           snippets: T.nilable(Courier::BrandSnippets::OrHash),
+          idempotency_key: String,
+          x_idempotency_expiration: String,
           request_options: Courier::RequestOptions::OrHash
         ).returns(Courier::Brand)
       end
-      def create(name:, settings:, id: nil, snippets: nil, request_options: {})
+      def create(
+        # Body param
+        name:,
+        # Body param
+        settings:,
+        # Body param
+        id: nil,
+        # Body param
+        snippets: nil,
+        # Header param: A unique key that makes this request idempotent. If Courier
+        # receives another request with the same `Idempotency-Key`, it returns the stored
+        # response from the first request without performing the operation again
+        # (including the original status code and any error). Use it to safely retry
+        # `POST` requests after network failures without risking duplicate sends. The key
+        # is scoped to this endpoint.
+        idempotency_key: nil,
+        # Header param: How long the idempotency key remains valid, as a Unix epoch
+        # timestamp in seconds or an ISO 8601 date string. Only applies when
+        # `Idempotency-Key` is provided. If omitted, the key is retained for 25 hours; the
+        # maximum is 1 year.
+        x_idempotency_expiration: nil,
+        request_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.
       sig do
         params(
           brand_id: String,
@@ -31,7 +58,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.
       sig do
         params(
           brand_id: String,
@@ -52,7 +80,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.
       sig do
         params(
           cursor: T.nilable(String),
@@ -66,7 +95,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.
       sig do
         params(
           brand_id: String,