trycourier 4.18.2 → 4.19.0

data/rbi/courier/models/users/preference_bulk_update_params.rbi

@@ -0,0 +1,186 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Users
+      class PreferenceBulkUpdateParams < Courier::Internal::Type::BaseModel
+        extend Courier::Internal::Type::RequestParameters::Converter
+        include Courier::Internal::Type::RequestParameters
+
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::Users::PreferenceBulkUpdateParams,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        sig { returns(String) }
+        attr_accessor :user_id
+
+        # The topics to create or update. Between 1 and 50 topics may be provided in a
+        # single request.
+        sig do
+          returns(T::Array[Courier::Users::PreferenceBulkUpdateParams::Topic])
+        end
+        attr_accessor :topics
+
+        # Update the preferences of a user for this specific tenant context.
+        sig { returns(T.nilable(String)) }
+        attr_accessor :tenant_id
+
+        sig do
+          params(
+            user_id: String,
+            topics:
+              T::Array[
+                Courier::Users::PreferenceBulkUpdateParams::Topic::OrHash
+              ],
+            tenant_id: T.nilable(String),
+            request_options: Courier::RequestOptions::OrHash
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          user_id:,
+          # The topics to create or update. Between 1 and 50 topics may be provided in a
+          # single request.
+          topics:,
+          # Update the preferences of a user for this specific tenant context.
+          tenant_id: nil,
+          request_options: {}
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              user_id: String,
+              topics:
+                T::Array[Courier::Users::PreferenceBulkUpdateParams::Topic],
+              tenant_id: T.nilable(String),
+              request_options: Courier::RequestOptions
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Topic < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::Users::PreferenceBulkUpdateParams::Topic,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          # The subscription status to apply for this topic.
+          sig do
+            returns(
+              Courier::Users::PreferenceBulkUpdateParams::Topic::Status::OrSymbol
+            )
+          end
+          attr_accessor :status
+
+          # A unique identifier associated with a subscription topic.
+          sig { returns(String) }
+          attr_accessor :topic_id
+
+          # The channels a user has chosen to receive notifications through for this topic.
+          sig do
+            returns(
+              T.nilable(T::Array[Courier::ChannelClassification::OrSymbol])
+            )
+          end
+          attr_reader :custom_routing
+
+          sig do
+            params(
+              custom_routing: T::Array[Courier::ChannelClassification::OrSymbol]
+            ).void
+          end
+          attr_writer :custom_routing
+
+          # Whether the recipient has chosen specific delivery channels for this topic.
+          sig { returns(T.nilable(T::Boolean)) }
+          attr_reader :has_custom_routing
+
+          sig { params(has_custom_routing: T::Boolean).void }
+          attr_writer :has_custom_routing
+
+          sig do
+            params(
+              status:
+                Courier::Users::PreferenceBulkUpdateParams::Topic::Status::OrSymbol,
+              topic_id: String,
+              custom_routing:
+                T::Array[Courier::ChannelClassification::OrSymbol],
+              has_custom_routing: T::Boolean
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # The subscription status to apply for this topic.
+            status:,
+            # A unique identifier associated with a subscription topic.
+            topic_id:,
+            # The channels a user has chosen to receive notifications through for this topic.
+            custom_routing: nil,
+            # Whether the recipient has chosen specific delivery channels for this topic.
+            has_custom_routing: nil
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                status:
+                  Courier::Users::PreferenceBulkUpdateParams::Topic::Status::OrSymbol,
+                topic_id: String,
+                custom_routing:
+                  T::Array[Courier::ChannelClassification::OrSymbol],
+                has_custom_routing: T::Boolean
+              }
+            )
+          end
+          def to_hash
+          end
+
+          # The subscription status to apply for this topic.
+          module Status
+            extend Courier::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  Courier::Users::PreferenceBulkUpdateParams::Topic::Status
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            OPTED_IN =
+              T.let(
+                :OPTED_IN,
+                Courier::Users::PreferenceBulkUpdateParams::Topic::Status::TaggedSymbol
+              )
+            OPTED_OUT =
+              T.let(
+                :OPTED_OUT,
+                Courier::Users::PreferenceBulkUpdateParams::Topic::Status::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  Courier::Users::PreferenceBulkUpdateParams::Topic::Status::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/users/preference_bulk_update_response.rbi

@@ -0,0 +1,94 @@
+# typed: strong
+
+module Courier
+  module Models
+    module Users
+      class PreferenceBulkUpdateResponse < Courier::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Courier::Models::Users::PreferenceBulkUpdateResponse,
+              Courier::Internal::AnyHash
+            )
+          end
+
+        # The topics that could not be applied, each with a reason.
+        sig do
+          returns(
+            T::Array[
+              Courier::Models::Users::PreferenceBulkUpdateResponse::Error
+            ]
+          )
+        end
+        attr_accessor :errors
+
+        # The topics that were successfully created or updated.
+        sig { returns(T::Array[Courier::Users::BulkPreferenceTopic]) }
+        attr_accessor :items
+
+        sig do
+          params(
+            errors:
+              T::Array[
+                Courier::Models::Users::PreferenceBulkUpdateResponse::Error::OrHash
+              ],
+            items: T::Array[Courier::Users::BulkPreferenceTopic::OrHash]
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The topics that could not be applied, each with a reason.
+          errors:,
+          # The topics that were successfully created or updated.
+          items:
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              errors:
+                T::Array[
+                  Courier::Models::Users::PreferenceBulkUpdateResponse::Error
+                ],
+              items: T::Array[Courier::Users::BulkPreferenceTopic]
+            }
+          )
+        end
+        def to_hash
+        end
+
+        class Error < Courier::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                Courier::Models::Users::PreferenceBulkUpdateResponse::Error,
+                Courier::Internal::AnyHash
+              )
+            end
+
+          # A human-readable explanation of why the topic could not be applied.
+          sig { returns(String) }
+          attr_accessor :reason
+
+          sig { returns(String) }
+          attr_accessor :topic_id
+
+          # A single topic that could not be applied in a bulk preference request.
+          sig do
+            params(reason: String, topic_id: String).returns(T.attached_class)
+          end
+          def self.new(
+            # A human-readable explanation of why the topic could not be applied.
+            reason:,
+            topic_id:
+          )
+          end
+
+          sig { override.returns({ reason: String, topic_id: String }) }
+          def to_hash
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/courier/models/workspace_preference_create_request.rbi

@@ -15,6 +15,10 @@ module Courier
       sig { returns(String) }
       attr_accessor :name
 
+      # Optional description shown under the section on the hosted preferences page.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
       # Whether the workspace preference defines custom routing for its topics.
       sig { returns(T.nilable(T::Boolean)) }
       attr_accessor :has_custom_routing
@@ -29,6 +33,7 @@ module Courier
       sig do
         params(
           name: String,
+          description: T.nilable(String),
           has_custom_routing: T.nilable(T::Boolean),
           routing_options:
             T.nilable(T::Array[Courier::ChannelClassification::OrSymbol])
@@ -37,6 +42,8 @@ module Courier
       def self.new(
         # Human-readable name for the workspace preference.
         name:,
+        # Optional description shown under the section on the hosted preferences page.
+        description: nil,
         # Whether the workspace preference defines custom routing for its topics.
         has_custom_routing: nil,
         # Default channels for the workspace preference. Defaults to empty if omitted.
@@ -48,6 +55,7 @@ module Courier
         override.returns(
           {
             name: String,
+            description: T.nilable(String),
             has_custom_routing: T.nilable(T::Boolean),
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol])

data/rbi/courier/models/workspace_preference_get_response.rbi

@@ -39,6 +39,10 @@ module Courier
       sig { returns(T.nilable(String)) }
       attr_accessor :creator
 
+      # Optional description shown under the section on the hosted preferences page.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
       # ISO-8601 timestamp of the last update.
       sig { returns(T.nilable(String)) }
       attr_accessor :updated
@@ -58,6 +62,7 @@ module Courier
           topics:
             T::Array[Courier::WorkspacePreferenceTopicGetResponse::OrHash],
           creator: T.nilable(String),
+          description: T.nilable(String),
           updated: T.nilable(String),
           updater: T.nilable(String)
         ).returns(T.attached_class)
@@ -77,6 +82,8 @@ module Courier
         topics:,
         # Id of the creator.
         creator: nil,
+        # Optional description shown under the section on the hosted preferences page.
+        description: nil,
         # ISO-8601 timestamp of the last update.
         updated: nil,
         # Id of the last updater.
@@ -95,6 +102,7 @@ module Courier
               T::Array[Courier::ChannelClassification::TaggedSymbol],
             topics: T::Array[Courier::WorkspacePreferenceTopicGetResponse],
             creator: T.nilable(String),
+            description: T.nilable(String),
             updated: T.nilable(String),
             updater: T.nilable(String)
           }

data/rbi/courier/models/workspace_preference_publish_params.rbi

@@ -2,7 +2,7 @@
 
 module Courier
   module Models
-    class WorkspacePreferencePublishParams < Courier::Internal::Type::BaseModel
+    class WorkspacePreferencePublishParams < Courier::Models::PublishPreferencesRequest
       extend Courier::Internal::Type::RequestParameters::Converter
       include Courier::Internal::Type::RequestParameters
 

data/rbi/courier/models/workspace_preference_replace_request.rbi

@@ -15,6 +15,11 @@ module Courier
       sig { returns(String) }
       attr_accessor :name
 
+      # Optional description shown under the section on the hosted preferences page.
+      # Omit to clear.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
       # Whether the workspace preference defines custom routing for its topics.
       sig { returns(T.nilable(T::Boolean)) }
       attr_accessor :has_custom_routing
@@ -30,6 +35,7 @@ module Courier
       sig do
         params(
           name: String,
+          description: T.nilable(String),
           has_custom_routing: T.nilable(T::Boolean),
           routing_options:
             T.nilable(T::Array[Courier::ChannelClassification::OrSymbol])
@@ -38,6 +44,9 @@ module Courier
       def self.new(
         # Human-readable name for the workspace preference.
         name:,
+        # Optional description shown under the section on the hosted preferences page.
+        # Omit to clear.
+        description: nil,
         # Whether the workspace preference defines custom routing for its topics.
         has_custom_routing: nil,
         # Default channels for the workspace preference. Omit to clear.
@@ -49,6 +58,7 @@ module Courier
         override.returns(
           {
             name: String,
+            description: T.nilable(String),
             has_custom_routing: T.nilable(T::Boolean),
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol])

data/rbi/courier/models/workspace_preference_topic_create_request.rbi

@@ -36,6 +36,10 @@ module Courier
       end
       attr_accessor :allowed_preferences
 
+      # Optional description shown under the topic on the hosted preferences page.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
       # Whether to include a list-unsubscribe header on emails for this topic.
       sig { returns(T.nilable(T::Boolean)) }
       attr_accessor :include_unsubscribe_header
@@ -62,6 +66,7 @@ module Courier
                 Courier::WorkspacePreferenceTopicCreateRequest::AllowedPreference::OrSymbol
               ]
             ),
+          description: T.nilable(String),
           include_unsubscribe_header: T.nilable(T::Boolean),
           routing_options:
             T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
@@ -76,6 +81,8 @@ module Courier
         # Preference controls a recipient may customize for this topic. Defaults to empty
         # if omitted.
         allowed_preferences: nil,
+        # Optional description shown under the topic on the hosted preferences page.
+        description: nil,
         # Whether to include a list-unsubscribe header on emails for this topic.
         include_unsubscribe_header: nil,
         # Default channels delivered for this topic. Defaults to empty if omitted.
@@ -97,6 +104,7 @@ module Courier
                   Courier::WorkspacePreferenceTopicCreateRequest::AllowedPreference::OrSymbol
                 ]
               ),
+            description: T.nilable(String),
             include_unsubscribe_header: T.nilable(T::Boolean),
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),

data/rbi/courier/models/workspace_preference_topic_get_response.rbi

@@ -61,6 +61,10 @@ module Courier
       sig { returns(T.nilable(String)) }
       attr_accessor :creator
 
+      # Optional description shown under the topic on the hosted preferences page.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
       # Id of the last updater.
       sig { returns(T.nilable(String)) }
       attr_accessor :updater
@@ -82,6 +86,7 @@ module Courier
           topic_data: T::Hash[Symbol, T.anything],
           updated: String,
           creator: T.nilable(String),
+          description: T.nilable(String),
           updater: T.nilable(String)
         ).returns(T.attached_class)
       end
@@ -106,6 +111,8 @@ module Courier
         updated:,
         # Id of the creator.
         creator: nil,
+        # Optional description shown under the topic on the hosted preferences page.
+        description: nil,
         # Id of the last updater.
         updater: nil
       )
@@ -129,6 +136,7 @@ module Courier
             topic_data: T::Hash[Symbol, T.anything],
             updated: String,
             creator: T.nilable(String),
+            description: T.nilable(String),
             updater: T.nilable(String)
           }
         )

data/rbi/courier/models/workspace_preference_topic_replace_request.rbi

@@ -35,6 +35,11 @@ module Courier
       end
       attr_accessor :allowed_preferences
 
+      # Optional description shown under the topic on the hosted preferences page. Omit
+      # to clear.
+      sig { returns(T.nilable(String)) }
+      attr_accessor :description
+
       # Whether to include a list-unsubscribe header on emails for this topic.
       sig { returns(T.nilable(T::Boolean)) }
       attr_accessor :include_unsubscribe_header
@@ -62,6 +67,7 @@ module Courier
                 Courier::WorkspacePreferenceTopicReplaceRequest::AllowedPreference::OrSymbol
               ]
             ),
+          description: T.nilable(String),
           include_unsubscribe_header: T.nilable(T::Boolean),
           routing_options:
             T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
@@ -75,6 +81,9 @@ module Courier
         name:,
         # Preference controls a recipient may customize. Omit to clear.
         allowed_preferences: nil,
+        # Optional description shown under the topic on the hosted preferences page. Omit
+        # to clear.
+        description: nil,
         # Whether to include a list-unsubscribe header on emails for this topic.
         include_unsubscribe_header: nil,
         # Default channels delivered for this topic. Omit to clear.
@@ -96,6 +105,7 @@ module Courier
                   Courier::WorkspacePreferenceTopicReplaceRequest::AllowedPreference::OrSymbol
                 ]
               ),
+            description: T.nilable(String),
             include_unsubscribe_header: T.nilable(T::Boolean),
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),

data/rbi/courier/models.rbi

@@ -423,6 +423,8 @@ module Courier
 
   ProviderUpdateParams = Courier::Models::ProviderUpdateParams
 
+  PublishPreferencesRequest = Courier::Models::PublishPreferencesRequest
+
   PublishPreferencesResponse = Courier::Models::PublishPreferencesResponse
 
   PutSubscriptionsRecipient = Courier::Models::PutSubscriptionsRecipient

data/rbi/courier/resources/users/preferences.rbi

@@ -22,6 +22,89 @@ module Courier
         )
         end
 
+        # Replace a user's complete set of preference overrides in a single request. The
+        # topics in the request body become the recipient's entire set of overrides:
+        # listed topics are created or updated, and every existing override that is not
+        # included in the body is reset to its topic default. Submitting an empty `topics`
+        # array is a valid clear-all that resets every existing override.
+        #
+        # This operation is validation-atomic (all-or-nothing): structural validation
+        # fails fast with a single `400`, and if any topic is semantically invalid (an
+        # unknown topic, a `REQUIRED` topic that cannot be opted out, or a custom routing
+        # request that is not available on the workspace's plan) the request returns a
+        # single `400` aggregating every failure in `errors` and writes nothing. On
+        # success it returns `200` with `items` (the complete resulting override set) and
+        # `deleted` (the ids of the overrides that were reset to default).
+        #
+        # Every `topic_id` in the response — in `items`, `deleted`, and any `errors` — is
+        # returned in Courier's canonical topic id form, regardless of the form supplied
+        # in the request.
+        sig do
+          params(
+            user_id: String,
+            topics:
+              T::Array[
+                Courier::Users::PreferenceBulkReplaceParams::Topic::OrHash
+              ],
+            tenant_id: T.nilable(String),
+            request_options: Courier::RequestOptions::OrHash
+          ).returns(Courier::Models::Users::PreferenceBulkReplaceResponse)
+        end
+        def bulk_replace(
+          # Path param: A unique identifier associated with the user whose preferences you
+          # wish to update.
+          user_id,
+          # Body param: The complete set of topic overrides for the user. Up to 50 topics
+          # may be provided. Any existing override not listed here is reset to its topic
+          # default; an empty array resets every existing override.
+          topics:,
+          # Query param: Update the preferences of a user for this specific tenant context.
+          tenant_id: nil,
+          request_options: {}
+        )
+        end
+
+        # Additively create or update a user's preferences for one or more subscription
+        # topics in a single request. Only the topics included in the request body are
+        # created or updated; any existing overrides for topics not listed are left
+        # untouched.
+        #
+        # Structural validation of the request body fails fast with a single `400`. Beyond
+        # that, each topic is processed independently (partial-success, not
+        # all-or-nothing): valid topics are written and returned in `items`, while topics
+        # that cannot be applied are collected in `errors` with a per-topic `reason` (for
+        # example an unknown topic, a `REQUIRED` topic that cannot be opted out, a custom
+        # routing request that is not available on the workspace's plan, or a write
+        # failure). The request therefore returns `200` with both lists whenever the body
+        # is structurally valid.
+        #
+        # Every `topic_id` in the response — in both `items` and `errors` — is returned in
+        # Courier's canonical topic id form, regardless of the form supplied in the
+        # request.
+        sig do
+          params(
+            user_id: String,
+            topics:
+              T::Array[
+                Courier::Users::PreferenceBulkUpdateParams::Topic::OrHash
+              ],
+            tenant_id: T.nilable(String),
+            request_options: Courier::RequestOptions::OrHash
+          ).returns(Courier::Models::Users::PreferenceBulkUpdateResponse)
+        end
+        def bulk_update(
+          # Path param: A unique identifier associated with the user whose preferences you
+          # wish to update.
+          user_id,
+          # Body param: The topics to create or update. Between 1 and 50 topics may be
+          # provided in a single request.
+          topics:,
+          # Query param: Update the preferences of a user for this specific tenant context.
+          tenant_id: nil,
+          request_options: {}
+        )
+        end
+
         # Remove a user's preferences for a specific subscription topic, resetting the
         # topic to its effective default. This operation is idempotent: deleting a
         # preference that does not exist succeeds with no error.

data/rbi/courier/resources/workspace_preferences/topics.rbi

@@ -19,6 +19,7 @@ module Courier
                   Courier::WorkspacePreferenceTopicCreateRequest::AllowedPreference::OrSymbol
                 ]
               ),
+            description: T.nilable(String),
             include_unsubscribe_header: T.nilable(T::Boolean),
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
@@ -36,6 +37,8 @@ module Courier
           # Preference controls a recipient may customize for this topic. Defaults to empty
           # if omitted.
           allowed_preferences: nil,
+          # Optional description shown under the topic on the hosted preferences page.
+          description: nil,
           # Whether to include a list-unsubscribe header on emails for this topic.
           include_unsubscribe_header: nil,
           # Default channels delivered for this topic. Defaults to empty if omitted.
@@ -112,6 +115,7 @@ module Courier
                   Courier::WorkspacePreferenceTopicReplaceRequest::AllowedPreference::OrSymbol
                 ]
               ),
+            description: T.nilable(String),
             include_unsubscribe_header: T.nilable(T::Boolean),
             routing_options:
               T.nilable(T::Array[Courier::ChannelClassification::OrSymbol]),
@@ -131,6 +135,9 @@ module Courier
           name:,
           # Body param: Preference controls a recipient may customize. Omit to clear.
           allowed_preferences: nil,
+          # Body param: Optional description shown under the topic on the hosted preferences
+          # page. Omit to clear.
+          description: nil,
           # Body param: Whether to include a list-unsubscribe header on emails for this
           # topic.
           include_unsubscribe_header: nil,